Add native restore and session cleanup commands

This commit is contained in:
2026-11-20 05:41:16 +00:00
parent 6b7a0847d4
commit 85df36a770
14 changed files with 665 additions and 423 deletions

View File

@@ -568,6 +568,18 @@ bootstrap. File formatting is independent of report formatting.
## Stage 14: Convert restore and local cleanup commands
**Completed.** Native restore and session-clean declarations return separate
public action reports after resource release, including conflicts and completed
work on failure. Restore retains pointer authority, transition locking, recovery
markers, confined replacements, and manifest-last installation; its planner no
longer creates directories or changes their modes during dry runs. Cleanup
retains the exact workspace/spool/cache scopes and cache opt-in, checks --all
selection conflicts before bootstrap, and loads only pipeline context for that
mode. Removed top-level cleanup implementation. Focused restore/recovery/cache,
cleanup confinement/partial-failure, native selection, composition, package,
build, and diff checks pass with Go 1.27.4. Legacy workflow/parser assertions
continue their scheduled conversion before final verification.
Read: `restore.go`, `restore_plan.go`, `restore_execute.go`,
`restore_report.go`, `clean.go`, and their focused safety tests.

View File

@@ -1,177 +1,12 @@
package app
import (
"context"
"flag"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/fileops"
)
// Clean removes local workspace/spool state while preserving durable cache
// state unless cache cleanup is explicitly requested.
func Clean(ctx context.Context, args []string, out io.Writer) error {
return cleanWithDependencies(ctx, args, out, commandDependencies{})
}
func cleanWithDependencies(ctx context.Context, args []string, out io.Writer, deps commandDependencies) error {
deps = normalizeCommandDependencies(deps)
fs := flag.NewFlagSet("clean", flag.ContinueOnError)
fs.SetOutput(io.Discard)
var flags commonConfigFlags
var all bool
var dryRun bool
var clearCache bool
addCommonConfigFlags(fs, &flags)
fs.BoolVar(&all, "all", false, "clean all local session work/spool state")
fs.BoolVar(&dryRun, "dry-run", false, "print cleanup targets without deleting")
fs.BoolVar(&clearCache, "clear-cache", false, "also clear durable S3 audio cache entries")
if err := parseSessionAwareFlags("clean", fs, args, &flags.sessionID); err != nil {
return err
}
if all {
return cleanAllLocalWithDependencies(flags, dryRun, clearCache, out, deps)
}
return cleanSessionWithDependencies(ctx, flags, dryRun, clearCache, out, deps)
}
func cleanSessionWithDependencies(ctx context.Context, flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
if strings.TrimSpace(flags.sessionID) == "" {
return fmt.Errorf("clean: session_id is required unless --all is set")
}
loaded, err := loadCommandConfigWithDependencies(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions(), flags.secretsDir.pointer(), deps)
if err != nil {
return fmt.Errorf("clean: %w", err)
}
defer func() { _ = loaded.Close() }()
cfg := loaded.Config
if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
return fmt.Errorf("clean: resolved pipeline and session config are required")
}
campaign := strings.TrimSpace(cfg.Session.Campaign)
sessionID := strings.TrimSpace(cfg.Session.SessionID)
if campaign == "" || sessionID == "" {
return fmt.Errorf("clean: campaign and session_id are required")
}
if dryRun {
fmt.Fprintf(out, "Clean plan for %s/%s\n", campaign, sessionID)
} else {
fmt.Fprintf(out, "Cleaned %s/%s\n", campaign, sessionID)
}
workDir := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, campaign, sessionID)
spoolDir := artifacts.SessionSpoolDir(cfg.Pipeline.Spool.Root, campaign, sessionID)
if err := reportCleanScopedDir(out, cfg.Pipeline.Workspace.Root, workDir, "clean.workspace.session", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if err := reportCleanScopedDir(out, cfg.Pipeline.Spool.Root, spoolDir, "clean.spool.session", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if clearCache {
if err := cleanSessionAudioCacheWithDependencies(ctx, cfg, dryRun, out, deps); err != nil {
return fmt.Errorf("clean: %w", err)
}
} else {
fmt.Fprintln(out, "Cache: preserved")
}
return nil
}
func cleanAllLocalWithDependencies(flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
if strings.TrimSpace(flags.campaignPath) != "" ||
strings.TrimSpace(flags.campaignFilePath) != "" ||
strings.TrimSpace(flags.sessionPath) != "" ||
strings.TrimSpace(flags.sessionID) != "" ||
strings.TrimSpace(flags.previousSessionID) != "" {
return fmt.Errorf("clean: --all cannot be combined with --campaign, --campaign-file, --session, a session_id, or --previous-session-id")
}
_, pipelineCfg, err := loadPipelineConfigWithDependencies(flags.pipelinePath, config.PipelineLoadOptions{Overlay: flags.overlay.pointer()}, flags.secretsDir.pointer(), deps)
if err != nil {
return fmt.Errorf("clean: %w", err)
}
if dryRun {
fmt.Fprintln(out, "Clean plan for all local sessions")
} else {
fmt.Fprintln(out, "Cleaned all local sessions")
}
workRoot := filepath.Join(pipelineCfg.Workspace.Root, config.PathWorkDirSegment)
if err := reportCleanScopedDir(out, pipelineCfg.Workspace.Root, workRoot, "clean.workspace.all", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if err := reportCleanRootChildren(out, pipelineCfg.Spool.Root, "clean.spool.all", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if clearCache {
if err := cleanAllAudioCache(pipelineCfg, dryRun, out); err != nil {
return fmt.Errorf("clean: %w", err)
}
} else {
fmt.Fprintln(out, "Cache: preserved")
}
return nil
}
func reportCleanScopedDir(out io.Writer, root, target, policy string, dryRun bool) error {
dir, err := validateScopedDir(root, target, policy)
if err != nil {
return err
}
if dryRun {
if dir.Exists {
fmt.Fprintf(out, "Would delete: %s\n", dir.TargetAbs)
} else {
fmt.Fprintf(out, "Would skip missing: %s\n", dir.TargetAbs)
}
return nil
}
if !dir.Exists {
fmt.Fprintf(out, "Missing: %s\n", dir.TargetAbs)
return nil
}
if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
}
fmt.Fprintf(out, "Deleted: %s\n", dir.TargetAbs)
return nil
}
func reportCleanRootChildren(out io.Writer, root, policy string, dryRun bool) error {
rootAbs, entries, err := cleanableRootChildren(root, policy)
if err != nil {
return err
}
if len(entries) == 0 {
if dryRun {
fmt.Fprintf(out, "Would skip empty: %s\n", rootAbs)
} else {
fmt.Fprintf(out, "Empty: %s\n", rootAbs)
}
return nil
}
for _, entry := range entries {
if dryRun {
fmt.Fprintf(out, "Would delete: %s\n", entry)
continue
}
if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
}
fmt.Fprintf(out, "Deleted: %s\n", entry)
}
return nil
}
func cleanableRootChildren(root, policy string) (string, []string, error) {
rootAbs, exists, err := validateCleanRoot(root, policy)
if err != nil {
@@ -199,83 +34,6 @@ func cleanableRootChildren(root, policy string) (string, []string, error) {
return rootAbs, out, nil
}
func cleanSessionAudioCacheWithDependencies(ctx context.Context, cfg *config.Config, dryRun bool, out io.Writer, deps commandDependencies) error {
if cfg.Session.Inputs.AudioS3 == nil {
fmt.Fprintln(out, "Cache: skipped (session does not use audio_s3)")
return nil
}
if cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
return fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
store, err := newCommandObjectStoreWithDependencies(ctx, cfg, nil, deps)
if err != nil {
return fmt.Errorf("initialize object store for cache cleanup: %w", err)
}
sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
objects, err := store.List(ctx, audioPrefix)
if err != nil {
return fmt.Errorf("list s3 audio objects under %q: %w", audioPrefix, err)
}
count := 0
for _, obj := range objects {
key := strings.TrimSpace(obj.Key)
if key == "" || strings.HasSuffix(key, "/") || !cleanIsFlac(key) {
continue
}
cachePath, err := artifacts.S3AudioCachePath(cfg.Pipeline.Cache.Root, cfg.Pipeline.Storage.S3.Bucket, key)
if err != nil {
return err
}
deleted, err := reportCleanScopedFile(out, cfg.Pipeline.Cache.Root, cachePath, "clean.cache.session", dryRun)
if err != nil {
return err
}
if deleted {
count++
}
}
if count == 0 {
fmt.Fprintf(out, "Cache: no cached S3 audio files found for %s\n", audioPrefix)
}
return nil
}
func cleanAllAudioCache(cfg *config.PipelineConfig, dryRun bool, out io.Writer) error {
if cfg.Storage.S3 == nil || strings.TrimSpace(cfg.Storage.S3.Bucket) == "" {
return fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
namespaceDir, err := artifacts.S3AudioCacheNamespaceDir(cfg.Cache.Root, cfg.Storage.S3.Bucket, cfg.Storage.S3.RootPrefix)
if err != nil {
return err
}
return reportCleanScopedDir(out, cfg.Cache.Root, namespaceDir, "clean.cache.all", dryRun)
}
func reportCleanScopedFile(out io.Writer, root, target, policy string, dryRun bool) (bool, error) {
file, err := validateScopedFile(root, target, policy)
if err != nil {
return false, err
}
if dryRun {
if file.Exists {
fmt.Fprintf(out, "Would delete cache file: %s\n", file.TargetAbs)
return true, nil
}
fmt.Fprintf(out, "Would skip missing cache file: %s\n", file.TargetAbs)
return false, nil
}
if !file.Exists {
fmt.Fprintf(out, "Missing cache file: %s\n", file.TargetAbs)
return false, nil
}
if err := fileops.RemoveAllUnderRoot(file.RootAbs, file.TargetAbs); err != nil {
return false, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, file.TargetAbs, err)
}
fmt.Fprintf(out, "Deleted cache file: %s\n", file.TargetAbs)
return true, nil
}
func validateScopedFile(root, target, policy string) (scopedDir, error) {
return validateScopedTarget(root, target, policy, false)
}

View File

@@ -0,0 +1,231 @@
package app
import (
"context"
"errors"
"fmt"
"path/filepath"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/fileops"
"go.maximumdirect.net/commandkit"
)
type cleanCommandInput struct {
Selection configurationSelection
PreviousSession commandkit.Supplied[string]
All, DryRun, ClearCache bool
}
type cleanCommandReport struct {
Campaign string `json:"campaign,omitempty"`
SessionID string `json:"session_id,omitempty"`
All bool `json:"all"`
DryRun bool `json:"dry_run"`
Complete bool `json:"complete"`
Cache string `json:"cache"`
Actions []cleanAction `json:"actions"`
Error string `json:"error,omitempty"`
}
type cleanAction struct {
Path string `json:"path"`
Status string `json:"status"`
Error string `json:"error,omitempty"`
}
func checkCleanInput(input *cleanCommandInput) error {
if err := checkConfigurationSelection(input.Selection); err != nil {
return err
}
if input.All {
if input.Selection.Session.Set || input.Selection.SessionFile.Set || input.Selection.Campaign.Set || input.Selection.CampaignFile.Set || input.Selection.PartyFile.Set || input.PreviousSession.Set {
return fmt.Errorf("--all cannot be combined with session, campaign, party, or previous-session selections")
}
} else if !input.Selection.Session.Set {
return fmt.Errorf("session identity is required unless --all is set")
}
return nil
}
func cleanCommand(deps commandDependencies) commandkit.Command {
common := newConfigurationFlags(func(input **cleanCommandInput) *configurationSelection { return &(*input).Selection })
return commandkit.NewCommand(commandkit.CommandSpec[*cleanCommandInput]{Name: "clean", Summary: "Remove selected local session data, preserving cache unless requested.", NewInput: func() *cleanCommandInput { return &cleanCommandInput{} },
Flags: []commandkit.Flag[*cleanCommandInput]{common.Config, common.Overlay, common.Campaign, common.CampaignFile, common.SessionFile, common.PartyFile, common.SecretsDir,
commandkit.ValueFlag(commandkit.FlagMeta{Name: "previous-session-id", Usage: "Assert the previous session identity."}, nil, stringValue, func(input **cleanCommandInput, value commandkit.Supplied[string]) { (*input).PreviousSession = value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "all", Usage: "Clean all local session workspace and spool entries."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).All = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "dry-run", Usage: "Preview exact paths without deleting them."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).DryRun = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "clear-cache", Usage: "Also remove the selected S3 audio cache entries."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).ClearCache = value.Value }),
},
Arguments: []commandkit.Argument[*cleanCommandInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "SESSION", Usage: "Session identity, omitted with --all."}, false, stringValue, func(input **cleanCommandInput, value commandkit.Supplied[string]) { (*input).Selection.Session = value })},
CheckInput: checkCleanInput,
Run: func(invocation commandkit.Invocation, input *cleanCommandInput) commandkit.Outcome {
report, err := cleanSelectedSession(invocation.Context, input, deps)
if report != nil {
err = errors.Join(err, invocation.Reporter().Report(commandkit.Report{Value: report}))
}
return operationOutcome(err)
},
})
}
func cleanSelectedSession(ctx context.Context, input *cleanCommandInput, deps commandDependencies) (report *cleanCommandReport, err error) {
deps = normalizeCommandDependencies(deps)
deps.secretsBootstrap = &secretsBootstrap{}
acquired := newConfigurationAcquisition(input.Selection, deps)
acquired.previousSessionID = input.PreviousSession.Value
defer func() {
err = errors.Join(err, acquired.Close())
if report != nil {
report.Complete = err == nil && !input.DryRun
if err != nil {
report.Error = err.Error()
}
}
}()
report = &cleanCommandReport{All: input.All, DryRun: input.DryRun, Cache: "preserved", Actions: []cleanAction{}}
if input.ClearCache {
report.Cache = "requested"
}
pipeline, err := acquired.Pipeline(ctx)
if err != nil {
return report, err
}
appendTarget := func(root, target, policy string, directory bool) error {
action, err := cleanScopedTarget(root, target, policy, directory, input.DryRun)
report.Actions = append(report.Actions, action)
return err
}
if input.All {
if err := appendTarget(pipeline.Workspace.Root, filepath.Join(pipeline.Workspace.Root, config.PathWorkDirSegment), "clean.workspace.all", true); err != nil {
return report, err
}
actions, err := cleanRootChildren(pipeline.Spool.Root, "clean.spool.all", input.DryRun)
report.Actions = append(report.Actions, actions...)
if err != nil {
return report, err
}
if input.ClearCache {
if pipeline.Storage.S3 == nil || strings.TrimSpace(pipeline.Storage.S3.Bucket) == "" {
return report, fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
namespace, err := artifacts.S3AudioCacheNamespaceDir(pipeline.Cache.Root, pipeline.Storage.S3.Bucket, pipeline.Storage.S3.RootPrefix)
if err != nil {
return report, err
}
if err := appendTarget(pipeline.Cache.Root, namespace, "clean.cache.all", true); err != nil {
return report, err
}
report.Cache = "processed"
}
return report, nil
}
cfg, err := acquired.Domain(ctx)
if err != nil {
return report, err
}
report.Campaign = cfg.Session.Campaign
report.SessionID = cfg.Session.SessionID
work := artifacts.SessionWorkDirForCampaign(pipeline.Workspace.Root, report.Campaign, report.SessionID)
spool := artifacts.SessionSpoolDir(pipeline.Spool.Root, report.Campaign, report.SessionID)
if err := appendTarget(pipeline.Workspace.Root, work, "clean.workspace.session", true); err != nil {
return report, err
}
if err := appendTarget(pipeline.Spool.Root, spool, "clean.spool.session", true); err != nil {
return report, err
}
if input.ClearCache {
if cfg.Session.Inputs.AudioS3 == nil {
report.Cache = "not_applicable"
return report, nil
}
actions, err := cleanSessionCache(ctx, cfg, input.DryRun, deps)
report.Actions = append(report.Actions, actions...)
if err != nil {
return report, err
}
report.Cache = "processed"
}
return report, nil
}
func cleanScopedTarget(root, target, policy string, directory, dryRun bool) (cleanAction, error) {
action := cleanAction{Path: target, Status: "failed"}
scoped, err := validateScopedTarget(root, target, policy, directory)
if err != nil {
action.Error = err.Error()
return action, err
}
action.Path = scoped.TargetAbs
if !scoped.Exists {
action.Status = "missing"
return action, nil
}
if dryRun {
action.Status = "would_delete"
return action, nil
}
if err := fileops.RemoveAllUnderRoot(scoped.RootAbs, scoped.TargetAbs); err != nil {
action.Error = err.Error()
return action, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, scoped.TargetAbs, err)
}
action.Status = "deleted"
return action, nil
}
func cleanRootChildren(root, policy string, dryRun bool) ([]cleanAction, error) {
rootAbs, entries, err := cleanableRootChildren(root, policy)
if err != nil {
return []cleanAction{{Path: root, Status: "failed", Error: err.Error()}}, err
}
if len(entries) == 0 {
return []cleanAction{{Path: rootAbs, Status: "empty"}}, nil
}
actions := make([]cleanAction, 0, len(entries))
for _, entry := range entries {
action := cleanAction{Path: entry, Status: "would_delete"}
if !dryRun {
if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
action.Status = "failed"
action.Error = err.Error()
return append(actions, action), fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
}
action.Status = "deleted"
}
actions = append(actions, action)
}
return actions, nil
}
func cleanSessionCache(ctx context.Context, cfg *config.Config, dryRun bool, deps commandDependencies) ([]cleanAction, error) {
if cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
return nil, fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
store, err := newCommandObjectStoreWithDependencies(ctx, cfg, nil, deps)
if err != nil {
return nil, fmt.Errorf("initialize object store for cache cleanup: %w", err)
}
prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
audioPrefix := artifacts.S3AudioPrefix(prefix, cfg.Session.Inputs.AudioS3.Prefix)
objects, err := store.List(ctx, audioPrefix)
if err != nil {
return nil, fmt.Errorf("list s3 audio objects under %q: %w", audioPrefix, err)
}
actions := []cleanAction{}
for _, object := range objects {
key := strings.TrimSpace(object.Key)
if key == "" || strings.HasSuffix(key, "/") || !cleanIsFlac(key) {
continue
}
cache, err := artifacts.S3AudioCachePath(cfg.Pipeline.Cache.Root, cfg.Pipeline.Storage.S3.Bucket, key)
if err != nil {
return actions, err
}
action, err := cleanScopedTarget(cfg.Pipeline.Cache.Root, cache, "clean.cache.session", false, dryRun)
actions = append(actions, action)
if err != nil {
return actions, err
}
}
return actions, nil
}

View File

@@ -0,0 +1,98 @@
package app
import (
"bytes"
"context"
"encoding/json"
"os"
"path/filepath"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
configkit "go.maximumdirect.net/configkit"
)
func TestCleanCommandReportsCompletedActionsBeforeLaterFailure(t *testing.T) {
workspace := t.TempDir()
pipeline, campaign, session := writeValidConfigFiles(t, workspace)
work := artifacts.SessionWorkDirForCampaign(workspace, "sample-campaign", "2026-05-03")
mustWriteTestFile(t, filepath.Join(work, "manifest.json"), "{}")
spool := artifacts.SessionSpoolDir(filepath.Join(workspace, "spool"), "sample-campaign", "2026-05-03")
if err := os.MkdirAll(filepath.Dir(spool), 0755); err != nil {
t.Fatal(err)
}
outside := t.TempDir()
sentinel := filepath.Join(outside, "retained")
mustWriteTestFile(t, sentinel, "retained")
if err := os.Symlink(outside, spool); err != nil {
t.Fatal(err)
}
var out, diagnostic bytes.Buffer
outcome := Execute(context.Background(), []string{"session", "clean", "2026-05-03", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 1 {
t.Fatalf("status=%d diagnostics=%s", outcome.Status, diagnostic.String())
}
var report cleanCommandReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
if report.Complete || len(report.Actions) != 2 || report.Actions[0].Status != "deleted" || report.Actions[1].Status != "failed" || report.Error == "" {
t.Fatalf("partial report=%#v", report)
}
cleanAssertMissing(t, work)
cleanAssertExists(t, sentinel)
}
func TestCleanCommandChecksAllSelectionBeforeBootstrap(t *testing.T) {
app, err := newApplication(commandDependencies{
loadSecretsDir: func(string) (*configkit.SecretsReport, error) {
t.Fatal("invalid cleanup bootstrapped secrets")
return nil, nil
},
loadPipelineConfig: func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) {
t.Fatal("invalid cleanup loaded configuration")
return nil, nil
},
}, executePlan)
if err != nil {
t.Fatal(err)
}
for _, args := range [][]string{
{"session", "clean"},
{"session", "clean", "session", "--all"},
{"session", "clean", "--all", "--campaign", "campaign"},
{"session", "clean", "--all", "--campaign-file", "campaign.yml"},
{"session", "clean", "--all", "--session-file", "session.yml"},
{"session", "clean", "--all", "--party-file", "party.yml"},
{"session", "clean", "--all", "--previous-session-id", "previous"},
{"clean"},
} {
var out, diagnostic bytes.Buffer
outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 2 {
t.Fatalf("%v status=%d diagnostics=%s", args, outcome.Status, diagnostic.String())
}
}
}
func TestCleanAllCommandNeedsOnlyPipelineConfiguration(t *testing.T) {
root := t.TempDir()
pipeline := filepath.Join(root, "pipeline.yml")
mustWriteTestFile(t, pipeline, "workspace: {root: ./workspace}\nspool: {root: ./spool}\nwhisperx: {transcribe_url: https://transcription.example.test/transcribe}\n")
var out, diagnostic bytes.Buffer
outcome := Execute(context.Background(), []string{"session", "clean", "--all", "--dry-run", "--config", pipeline, "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 0 {
t.Fatalf("status=%d diagnostics=%s", outcome.Status, diagnostic.String())
}
var report cleanCommandReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
if !report.All || !report.DryRun || report.Complete || report.Campaign != "" || report.Cache != "preserved" {
t.Fatalf("report=%#v", report)
}
cleanAssertMissing(t, filepath.Join(root, "workspace"))
cleanAssertMissing(t, filepath.Join(root, "spool"))
}

View File

@@ -26,14 +26,14 @@ func TestExecuteCleanSessionDeletesWorkAndSpoolButPreservesCache(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
cleanAssertMissing(t, workDir)
cleanAssertMissing(t, spoolDir)
cleanAssertExists(t, cachePath)
if !strings.Contains(stdout.String(), "Cache: preserved") {
if !strings.Contains(stdout.String(), "cache: preserved") {
t.Fatalf("stdout = %q, want cache preserved", stdout.String())
}
}
@@ -48,13 +48,13 @@ func TestExecuteCleanSessionDryRunDeletesNothing(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--dry-run"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--dry-run"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
cleanAssertExists(t, workDir)
cleanAssertExists(t, spoolDir)
if !strings.Contains(stdout.String(), "Would delete:") {
if !strings.Contains(stdout.String(), "status: would_delete") {
t.Fatalf("stdout = %q, want dry-run delete plan", stdout.String())
}
}
@@ -65,11 +65,11 @@ func TestExecuteCleanMissingSessionPathsSucceeds(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
if !strings.Contains(stdout.String(), "Missing:") {
if !strings.Contains(stdout.String(), "status: missing") {
t.Fatalf("stdout = %q, want missing path output", stdout.String())
}
}
@@ -105,7 +105,7 @@ inputs:
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--clear-cache"}, &stdout, &stderr, deps, executePlan)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -122,11 +122,11 @@ func TestExecuteCleanLocalAudioClearCacheIsNoop(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--clear-cache"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
if !strings.Contains(stdout.String(), "Cache: skipped (session does not use audio_s3)") {
if !strings.Contains(stdout.String(), "cache: not_applicable") {
t.Fatalf("stdout = %q, want local audio cache no-op", stdout.String())
}
}
@@ -143,7 +143,7 @@ func TestExecuteCleanAllDeletesWorkAndSpoolContentsButPreservesCache(t *testing.
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "--config", pipelinePath, "--all"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "--config", pipelinePath, "--all"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -170,7 +170,7 @@ func TestExecuteCleanAllClearCacheRemovesS3AudioNamespaceOnly(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "--config", pipelinePath, "--all", "--clear-cache"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "--config", pipelinePath, "--all", "--clear-cache"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -184,7 +184,7 @@ func TestExecuteCleanAllRejectsSessionScopedFlags(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--all"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--all"}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
@@ -196,11 +196,11 @@ func TestExecuteCleanAllRejectsSessionScopedFlags(t *testing.T) {
func TestCleanRequiresSessionID(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean"}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean"}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "session_id is required unless --all is set") {
if !strings.Contains(stderr.String(), "session identity is required unless --all is set") {
t.Fatalf("stderr = %q, want missing session-id", stderr.String())
}
}
@@ -208,22 +208,22 @@ func TestCleanRequiresSessionID(t *testing.T) {
func TestCleanRejectsUnsafeTargets(t *testing.T) {
root := t.TempDir()
outside := t.TempDir()
if err := reportCleanScopedDir(&bytes.Buffer{}, root, filepath.Join(outside, "target"), "test.outside", false); err == nil {
if _, err := cleanScopedTarget(root, filepath.Join(outside, "target"), "test.outside", true, false); err == nil {
t.Fatal("outside target error = nil, want error")
}
if err := reportCleanScopedDir(&bytes.Buffer{}, root, root, "test.root", false); err == nil {
if _, err := cleanScopedTarget(root, root, "test.root", true, false); err == nil {
t.Fatal("root target error = nil, want error")
}
filePath := filepath.Join(root, "file.txt")
mustWriteTestFile(t, filePath, "file")
if err := reportCleanScopedDir(&bytes.Buffer{}, root, filePath, "test.file", false); err == nil {
if _, err := cleanScopedTarget(root, filePath, "test.file", true, false); err == nil {
t.Fatal("file target error = nil, want error")
}
symlinkPath := filepath.Join(root, "link")
if err := os.Symlink(filepath.Join(root, "missing"), symlinkPath); err != nil {
t.Fatalf("Symlink() error = %v", err)
}
if err := reportCleanScopedDir(&bytes.Buffer{}, root, symlinkPath, "test.symlink", false); err == nil {
if _, err := cleanScopedTarget(root, symlinkPath, "test.symlink", true, false); err == nil {
t.Fatal("symlink target error = nil, want error")
}
}
@@ -235,7 +235,7 @@ func TestClearIsNotCommandAlias(t *testing.T) {
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), `unknown command: "clear"`) {
if code != 2 {
t.Fatalf("stderr = %q, want unknown clear command", stderr.String())
}
}

View File

@@ -24,6 +24,8 @@ func newApplication(deps commandDependencies, executor pipelineExecutor) (*comma
),
commandkit.Group("session", "Manage and inspect sessions.",
sessionPlanCommand(deps),
restoreCommand(deps),
cleanCommand(deps),
sessionInitializationCommand(deps),
sessionValidationCommand(deps),
sessionStateCommand("status", true, deps),

View File

@@ -6,16 +6,12 @@ import (
"flag"
"fmt"
"io"
"log/slog"
"os"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/logging"
"go.maximumdirect.net/commandkit"
)
// Restore validates restore CLI/config inputs and storage preflight for future restore phases.
// Restore loads the selected session and restores its committed remote snapshot.
func Restore(ctx context.Context, args []string, out io.Writer) (resultErr error) {
return restoreWithDependencies(ctx, args, out, commandDependencies{})
}
@@ -59,111 +55,9 @@ func restoreWithDependencies(ctx context.Context, args []string, out io.Writer,
}
defer func() { _ = loaded.Close() }()
cfg := loaded.Config
if err := config.Validate(cfg); err != nil {
return fmt.Errorf("restore: %w", err)
report, err := restoreSession(ctx, cfg, RestorePlanOptions{DryRun: dryRun, Force: force, IncludeAudio: includeAudio}, deps)
if report != nil {
err = errors.Join(err, commandkit.RenderReport(out, commandkit.Report{Value: report}, ""))
}
objectStore, err := newCommandObjectStoreWithDependencies(ctx, cfg, logging.NewLogger(os.Stderr, slog.LevelInfo), deps)
if err != nil {
return fmt.Errorf("restore: %w", err)
}
current, err := deps.discoverRemoteCurrentState(ctx, cfg, objectStore)
if err != nil {
return fmt.Errorf("restore: %w", err)
}
if dryRun {
plan, err := deps.buildRestorePlan(ctx, cfg, current, objectStore, RestorePlanOptions{
IncludeAudio: includeAudio,
Force: force,
DryRun: true,
})
if err != nil {
return fmt.Errorf("restore: %w", err)
}
report, err := newRestoreReport(current, plan, RestorePlanOptions{
IncludeAudio: includeAudio,
Force: force,
DryRun: true,
})
if err != nil {
return fmt.Errorf("restore: %w", err)
}
if err := writeRestoreDryRunSummary(out, report); err != nil {
return fmt.Errorf("restore: write plan output: %w", err)
}
return nil
}
artifactStore := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
if _, err := artifactStore.EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID); err != nil {
return fmt.Errorf("restore: prepare workdir: %w", err)
}
lock, err := artifactStore.AcquireSessionLockForContext(ctx, cfg.Session.Campaign, cfg.Session.SessionID)
if err != nil {
return fmt.Errorf("restore: acquire session lock: %w", err)
}
defer func() {
if releaseErr := artifactStore.ReleaseSessionLock(lock); releaseErr != nil {
if resultErr == nil {
resultErr = fmt.Errorf("restore: release session lock: %w", releaseErr)
} else {
resultErr = errors.Join(resultErr, fmt.Errorf("restore: release session lock: %w", releaseErr))
}
}
}()
// Classification and installation share the same transition lock as a
// runner. This prevents a runner from making reuse decisions against state
// that restore is about to replace.
plan, err := deps.buildRestorePlan(ctx, cfg, current, objectStore, RestorePlanOptions{
IncludeAudio: includeAudio,
Force: force,
})
if err != nil {
return fmt.Errorf("restore: %w", err)
}
report, err := newRestoreReport(current, plan, RestorePlanOptions{
IncludeAudio: includeAudio,
Force: force,
})
if err != nil {
return fmt.Errorf("restore: %w", err)
}
if plan.ConflictCount > 0 {
report.setFailed(fmt.Errorf("conflict: %d conflicting path(s)", plan.ConflictCount))
if _, reportErr := persistRestoreReport(artifactStore, cfg, report); reportErr != nil {
return fmt.Errorf("restore: report failure: %w", reportErr)
}
return fmt.Errorf(
"restore conflict: %d conflicting path(s); --force can replace eligible regular files but not unresolved conflicts (download=%d skip_same=%d conflicts=%d)",
plan.ConflictCount,
plan.DownloadCount,
plan.SkipSameCount,
plan.ConflictCount,
)
}
if err := writeRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
return fmt.Errorf("restore: mark incomplete restore: %w", err)
}
result, err := deps.executeRestorePlan(ctx, cfg, current, plan, report, objectStore)
if err != nil {
report.setFailed(err)
if _, reportErr := persistRestoreReport(artifactStore, cfg, report); reportErr != nil {
return fmt.Errorf("restore: execute plan failed (%v) and report write failed (%v)", err, reportErr)
}
return fmt.Errorf("restore: execute plan: %w", err)
}
report.Execution.Downloaded = result.DownloadedCount
report.setSucceeded()
if err := clearRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
return fmt.Errorf("restore: clear incomplete restore marker: %w", err)
}
if _, err := persistRestoreReport(artifactStore, cfg, report); err != nil {
return fmt.Errorf("restore: write report: %w", err)
}
if err := writeRestoreSuccessSummary(out, report); err != nil {
return fmt.Errorf("restore: write summary: %w", err)
}
return nil
return err
}

View File

@@ -0,0 +1,197 @@
package app
import (
"context"
"errors"
"fmt"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
)
type restoreCommandInput struct {
Selection configurationSelection
PreviousSession string
DryRun, Force, IncludeAudio bool
}
type restoreCommandReport struct {
Campaign string `json:"campaign"`
SessionID string `json:"session_id"`
RunID string `json:"run_id"`
DryRun bool `json:"dry_run"`
Complete bool `json:"complete"`
Status string `json:"status"`
Downloaded int `json:"downloaded"`
Conflicts int `json:"conflicts"`
Actions []restoreCommandAction `json:"actions"`
}
type restoreCommandAction struct {
Kind string `json:"kind"`
LocalPath string `json:"local_path"`
RemoteKey string `json:"remote_key"`
Status string `json:"status"`
Reason string `json:"reason,omitempty"`
Error string `json:"error,omitempty"`
}
func restoreSession(ctx context.Context, cfg *config.Config, opts RestorePlanOptions, deps commandDependencies) (public *restoreCommandReport, resultErr error) {
diagnostic, resultErr := restoreSessionState(ctx, cfg, opts, normalizeCommandDependencies(deps))
if diagnostic == nil {
return nil, resultErr
}
public = &restoreCommandReport{Campaign: diagnostic.Campaign, SessionID: diagnostic.SessionID, RunID: diagnostic.RunID, DryRun: opts.DryRun, Complete: !opts.DryRun && resultErr == nil && diagnostic.Status == "succeeded", Status: diagnostic.Status, Downloaded: diagnostic.Execution.Downloaded, Conflicts: diagnostic.Plan.Conflicts, Actions: []restoreCommandAction{}}
for _, action := range diagnostic.Actions {
public.Actions = append(public.Actions, restoreCommandAction{Kind: action.Kind, LocalPath: action.LocalRelativePath, RemoteKey: action.RemoteKey, Status: action.Status, Reason: action.Reason, Error: action.Error})
}
return public, resultErr
}
func restoreSessionState(ctx context.Context, cfg *config.Config, opts RestorePlanOptions, deps commandDependencies) (diagnostic *RestoreReport, resultErr error) {
if err := config.Validate(cfg); err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
objectStore, err := newCommandObjectStoreWithDependencies(ctx, cfg, nil, deps)
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
current, err := deps.discoverRemoteCurrentState(ctx, cfg, objectStore)
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
if opts.DryRun {
plan, err := deps.buildRestorePlan(ctx, cfg, current, objectStore, RestorePlanOptions{
IncludeAudio: opts.IncludeAudio,
Force: opts.Force,
DryRun: true,
})
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
report, err := newRestoreReport(current, plan, RestorePlanOptions{
IncludeAudio: opts.IncludeAudio,
Force: opts.Force,
DryRun: true,
})
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
diagnostic = report
return diagnostic, nil
}
artifactStore := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
if _, err := artifactStore.EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID); err != nil {
return diagnostic, fmt.Errorf("restore: prepare workdir: %w", err)
}
lock, err := artifactStore.AcquireSessionLockForContext(ctx, cfg.Session.Campaign, cfg.Session.SessionID)
if err != nil {
return diagnostic, fmt.Errorf("restore: acquire session lock: %w", err)
}
defer func() {
if releaseErr := artifactStore.ReleaseSessionLock(lock); releaseErr != nil {
if resultErr == nil {
resultErr = fmt.Errorf("restore: release session lock: %w", releaseErr)
} else {
resultErr = errors.Join(resultErr, fmt.Errorf("restore: release session lock: %w", releaseErr))
}
}
}()
// Classification and installation share the same transition lock as a
// runner. This prevents a runner from making reuse decisions against state
// that restore is about to replace.
plan, err := deps.buildRestorePlan(ctx, cfg, current, objectStore, RestorePlanOptions{
IncludeAudio: opts.IncludeAudio,
Force: opts.Force,
})
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
report, err := newRestoreReport(current, plan, RestorePlanOptions{
IncludeAudio: opts.IncludeAudio,
Force: opts.Force,
})
if err != nil {
return diagnostic, fmt.Errorf("restore: %w", err)
}
diagnostic = report
if plan.ConflictCount > 0 {
conflictErr := fmt.Errorf("restore conflict: %d conflicting path(s); --force can replace eligible regular files but not unresolved conflicts (download=%d skip_same=%d conflicts=%d)", plan.ConflictCount, plan.DownloadCount, plan.SkipSameCount, plan.ConflictCount)
report.setFailed(conflictErr)
_, reportErr := persistRestoreReport(artifactStore, cfg, report)
return diagnostic, errors.Join(conflictErr, reportErr)
}
if err := writeRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
return diagnostic, fmt.Errorf("restore: mark incomplete restore: %w", err)
}
result, err := deps.executeRestorePlan(ctx, cfg, current, plan, report, objectStore)
if err != nil {
report.setFailed(err)
if _, reportErr := persistRestoreReport(artifactStore, cfg, report); reportErr != nil {
return diagnostic, fmt.Errorf("restore: execute plan and persist report: %w", errors.Join(err, reportErr))
}
return diagnostic, fmt.Errorf("restore: execute plan: %w", err)
}
if result == nil {
return diagnostic, fmt.Errorf("restore execution returned no result")
}
report.Execution.Downloaded = result.DownloadedCount
report.setSucceeded()
if err := clearRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
return diagnostic, fmt.Errorf("restore: clear incomplete restore marker: %w", err)
}
if _, err := persistRestoreReport(artifactStore, cfg, report); err != nil {
return diagnostic, fmt.Errorf("restore: write report: %w", err)
}
return diagnostic, nil
}
func restoreCommand(deps commandDependencies) commandkit.Command {
common := newConfigurationFlags(func(input **restoreCommandInput) *configurationSelection { return &(*input).Selection })
return commandkit.NewCommand(commandkit.CommandSpec[*restoreCommandInput]{Name: "restore", Summary: "Restore the committed remote session snapshot.", NewInput: func() *restoreCommandInput { return &restoreCommandInput{} },
Flags: []commandkit.Flag[*restoreCommandInput]{common.Config, common.Overlay, common.Campaign, common.CampaignFile, common.SessionFile, common.PartyFile, common.SecretsDir,
commandkit.ValueFlag(commandkit.FlagMeta{Name: "previous-session-id", Usage: "Assert the previous session identity."}, nil, stringValue, func(input **restoreCommandInput, value commandkit.Supplied[string]) {
(*input).PreviousSession = value.Value
}),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "dry-run", Usage: "Preview restore actions without writing local files."}, false, func(input **restoreCommandInput, value commandkit.Supplied[bool]) { (*input).DryRun = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "force", Usage: "Replace eligible conflicting regular files."}, false, func(input **restoreCommandInput, value commandkit.Supplied[bool]) { (*input).Force = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "include-audio", Usage: "Include session audio objects."}, false, func(input **restoreCommandInput, value commandkit.Supplied[bool]) {
(*input).IncludeAudio = value.Value
}),
},
Arguments: []commandkit.Argument[*restoreCommandInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "SESSION", Usage: "Session identity."}, true, stringValue, func(input **restoreCommandInput, value commandkit.Supplied[string]) {
(*input).Selection.Session = value
})},
CheckInput: func(input *restoreCommandInput) error { return checkConfigurationSelection(input.Selection) },
Run: func(invocation commandkit.Invocation, input *restoreCommandInput) commandkit.Outcome {
report, err := restoreSelectedSession(invocation.Context, input, deps)
if report != nil {
err = errors.Join(err, invocation.Reporter().Report(commandkit.Report{Value: report}))
}
return operationOutcome(err)
},
})
}
func restoreSelectedSession(ctx context.Context, input *restoreCommandInput, deps commandDependencies) (report *restoreCommandReport, err error) {
deps = normalizeCommandDependencies(deps)
deps.secretsBootstrap = &secretsBootstrap{}
acquired := newConfigurationAcquisition(input.Selection, deps)
acquired.previousSessionID = input.PreviousSession
defer func() {
err = errors.Join(err, acquired.Close())
if report != nil && err != nil {
report.Complete = false
}
}()
cfg, err := acquired.Domain(ctx)
if err != nil {
return nil, err
}
return restoreSession(ctx, cfg, RestorePlanOptions{DryRun: input.DryRun, Force: input.Force, IncludeAudio: input.IncludeAudio}, deps)
}

View File

@@ -0,0 +1,56 @@
package app
import (
"bytes"
"encoding/json"
"os"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"go.maximumdirect.net/commandkit"
)
func decodeRestoreCommandReport(t *testing.T, data []byte) restoreCommandReport {
t.Helper()
var report restoreCommandReport
// DecodeYAMLReport normalizes YAML through the same JSON representation.
normalized, err := commandkit.DecodeYAMLReport(bytes.NewReader(data))
if err != nil {
t.Fatal(err)
}
encoded, err := json.Marshal(normalized)
if err != nil {
t.Fatal(err)
}
if err := json.Unmarshal(encoded, &report); err != nil {
t.Fatal(err)
}
return report
}
func TestRestoreCommandDryRunLeavesMissingWorkspaceAbsent(t *testing.T) {
pipeline, campaign, session := writeValidConfigFiles(t, t.TempDir())
fake := &storage.FakeBackend{}
cfg, _, _, _ := seedRestoreCommittedState(t, fake, pipeline, campaign, session)
seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{"artifacts/recap.md": []byte("synthetic recap\n")})
paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
if _, err := os.Stat(paths.Root); !os.IsNotExist(err) {
t.Fatalf("fixture session root=%v", err)
}
var out, diagnostic bytes.Buffer
code := restoreCommandExecutor(fake)([]string{"session", "restore", cfg.Session.SessionID, "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--dry-run"}, &out, &diagnostic)
if code != 0 {
t.Fatalf("status=%d diagnostics=%s", code, diagnostic.String())
}
report := decodeRestoreCommandReport(t, out.Bytes())
if !report.DryRun || report.Complete || len(report.Actions) == 0 {
t.Fatalf("report=%#v", report)
}
if _, err := os.Stat(paths.Root); !os.IsNotExist(err) {
t.Fatalf("dry run created workspace: %v", err)
}
if len(fake.Downloads) != 0 {
t.Fatal("dry run installed remote payloads")
}
}

View File

@@ -39,14 +39,14 @@ func TestExecuteRestoreNonDryRunRestoresDurableFiles(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
if !strings.Contains(stdout.String(), "Restored session state for sample-campaign/2026-05-03") {
if !decodeRestoreCommandReport(t, stdout.Bytes()).Complete {
t.Fatalf("stdout = %q, want completion summary", stdout.String())
}
@@ -126,7 +126,7 @@ func TestExecuteRestoreRoundTripsPublishedExtractionAndManifestMetadata(t *testi
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -164,7 +164,7 @@ func TestExecuteRestoreIncludeAudioRestoresAudio(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--include-audio"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -190,7 +190,7 @@ func TestExecuteRestoreIncludeAudioUsesCacheAfterWorkspaceDeletion(t *testing.T)
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--include-audio"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("first restore exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -206,7 +206,7 @@ func TestExecuteRestoreIncludeAudioUsesCacheAfterWorkspaceDeletion(t *testing.T)
}
stdout.Reset()
stderr.Reset()
code = executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--include-audio"}, &stdout, &stderr)
code = executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--include-audio"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("second restore exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -229,7 +229,7 @@ func TestExecuteRestoreRestoresPreviousCacheWhenPresent(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -262,14 +262,14 @@ func TestExecuteRestoreDryRunReportsPreviousCacheWithoutWriting(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--dry-run"}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--dry-run"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
if !strings.Contains(stdout.String(), "previous/artifacts/session_recap.md") {
t.Fatalf("stdout = %q, want planned previous-cache artifact", stdout.String())
}
if !strings.Contains(stdout.String(), "may read remote data; no session files will be written") {
if !decodeRestoreCommandReport(t, stdout.Bytes()).DryRun {
t.Fatalf("stdout = %q, want dry-run remote-read notice", stdout.String())
}
@@ -294,7 +294,7 @@ func TestExecuteRestoreConflictWithoutForceDoesNotOverwrite(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
@@ -326,7 +326,7 @@ func TestExecuteRestoreForceOverwritesDifferingFile(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -356,7 +356,7 @@ func TestExecuteRestoreForceOverwritesDifferingPreviousCacheFile(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
code := executeRestore([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
@@ -516,13 +516,17 @@ func TestExecuteRestoreInvalidManifestReportsFailureAndRetainsRecoveryMarker(t *
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"session", "restore", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "restore", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "validate manifest decode") {
t.Fatalf("stderr = %q, want manifest validation failure", stderr.String())
}
public := decodeRestoreCommandReport(t, stdout.Bytes())
if public.Complete || public.Status != "failed" || public.Downloaded == 0 {
t.Fatalf("partial restore report=%#v", public)
}
mustReadEquals(t, filepath.Join(sessionRoot, "transcripts", "full.json"), "remote-transcript")
report := mustReadRestoreReport(t, filepath.Join(sessionRoot, "reports", "restore-latest.json"))
if report.Status != "failed" {

View File

@@ -16,7 +16,6 @@ import (
"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/fileops"
"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
"gitea.maximumdirect.net/eric/narratio/internal/previouscache"
)
@@ -83,14 +82,13 @@ func buildRestorePlan(ctx context.Context, cfg *config.Config, current *RemoteCu
return nil, fmt.Errorf("remote object store is required")
}
sessionPaths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
if err := fileops.EnsureWorkspaceDirectory(sessionPaths.Root); err != nil {
return nil, fmt.Errorf("create session root for restore planning: %w", err)
}
sessionRoot, err := os.OpenRoot(sessionPaths.Root)
if err != nil {
if err != nil && !errors.Is(err, os.ErrNotExist) {
return nil, fmt.Errorf("open session root for restore planning: %w", err)
}
defer func() { _ = sessionRoot.Close() }()
if sessionRoot != nil {
defer func() { _ = sessionRoot.Close() }()
}
actions, err := buildCurrentRestoreActions(ctx, current, store, sessionPaths, sessionRoot, opts)
if err != nil {
@@ -420,13 +418,13 @@ type restoreTarget struct {
}
func inspectRestoreTarget(root *os.Root, relative string) (restoreTarget, error) {
if root == nil {
return restoreTarget{}, fmt.Errorf("restore session root is required")
}
name := filepath.Clean(filepath.FromSlash(strings.TrimSpace(relative)))
if name == "." || name == ".." || filepath.IsAbs(name) || strings.HasPrefix(name, ".."+string(filepath.Separator)) {
return restoreTarget{}, fmt.Errorf("restore path %q is not a normalized relative path", relative)
}
if root == nil {
return restoreTarget{kind: restoreTargetMissing}, nil
}
parts := strings.Split(name, string(filepath.Separator))
current := root
var opened []*os.Root

View File

@@ -97,7 +97,7 @@ func TestForcedRestoreRetryClearsIncompleteMarker(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
args := []string{"session", "restore", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}
args := []string{"session", "restore", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}
if code := executeRestore(args, &stdout, &stderr); code == 0 {
t.Fatal("forced restore exit code = 0, want partial-install failure")
}

View File

@@ -26,7 +26,7 @@ func TestExecuteRestoreHelp(t *testing.T) {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
out := stdout.String()
if !strings.Contains(out, "Usage: narratio session restore <session_id>") {
if !strings.Contains(out, "narratio session restore SESSION") {
t.Fatalf("stdout = %q, want restore usage", out)
}
if !strings.Contains(out, "--include-audio") {
@@ -70,7 +70,7 @@ func TestExecuteRestoreDryRunPrintsPlanWithoutWriting(t *testing.T) {
"session", "restore", "2026-05-03",
"--config", pipelinePath,
"--campaign-file", campaignPath,
"--session", sessionPath,
"--session-file", sessionPath,
"--dry-run",
"--force",
"--include-audio",
@@ -86,15 +86,9 @@ func TestExecuteRestoreDryRunPrintsPlanWithoutWriting(t *testing.T) {
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
outText := stdout.String()
if !strings.Contains(outText, "Restore plan for sample-campaign/2026-05-03") {
t.Fatalf("stdout = %q, want restore plan summary", outText)
}
if !strings.Contains(outText, "Would download: 1") {
t.Fatalf("stdout = %q, want plan count output", outText)
}
if !strings.Contains(outText, "Would download: manifest.json") {
t.Fatalf("stdout = %q, want action output", outText)
public := decodeRestoreCommandReport(t, stdout.Bytes())
if !public.DryRun || public.Complete || len(public.Actions) != 1 || public.Actions[0].LocalPath != "manifest.json" {
t.Fatalf("dry-run report=%#v", public)
}
manifestPath := artifacts.SessionManifestPathForCampaign(workspaceRoot, "sample-campaign", "2026-05-03")
@@ -113,13 +107,11 @@ func TestExecuteRestoreRejectsUnexpectedPositionalArguments(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "extra"}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "restore: unexpected positional arguments") {
t.Fatalf("stderr = %q, want positional-args failure", stderr.String())
code := executeForTest([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "extra"}, &stdout, &stderr)
if code != 2 {
t.Fatalf("status=%d diagnostics=%s", code, stderr.String())
}
}
func TestExecuteRestoreFailsWhenStorageBackendNotConfigured(t *testing.T) {
@@ -128,7 +120,7 @@ func TestExecuteRestoreFailsWhenStorageBackendNotConfigured(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeForTest([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
@@ -148,7 +140,7 @@ func TestExecuteRestoreDiscoveryErrorSurfaced(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr, deps, executePlan)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
@@ -221,7 +213,7 @@ func TestExecuteRestoreLoadsSecretsBeforeObjectStoreInit(t *testing.T) {
"session", "restore", "2026-05-03",
"--config", pipelinePath,
"--campaign-file", campaignPath,
"--session", sessionPath,
"--session-file", sessionPath,
"--dry-run",
"--secrets-dir", secretsDir,
},
@@ -260,12 +252,12 @@ func TestExecuteRestoreNonDryRunConflictDoesNotexecuteForTest(t *testing.T) {
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr, deps, executePlan)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty on conflict failure", stdout.String())
if report := decodeRestoreCommandReport(t, stdout.Bytes()); report.Conflicts != 1 || report.Complete {
t.Fatalf("conflict report=%#v", report)
}
if !strings.Contains(stderr.String(), "restore conflict: 1 conflicting path(s)") {
t.Fatalf("stderr = %q, want conflict failure", stderr.String())
@@ -290,7 +282,7 @@ func TestExecuteRestoreForceStillBlocksUnresolvedConflict(t *testing.T) {
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
if code == 0 {
t.Fatal("exit code = 0, want conflict failure")
}
@@ -324,11 +316,11 @@ func TestExecuteRestoreNonDryRunForceExecutesPlan(t *testing.T) {
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
code := executeWithDependencies([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr, deps, executePlan)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}
if !strings.Contains(stdout.String(), "Restored session state for sample-campaign/2026-05-03") {
if !decodeRestoreCommandReport(t, stdout.Bytes()).Complete {
t.Fatalf("stdout = %q, want completion summary", stdout.String())
}
if stderr.Len() != 0 {

View File

@@ -360,7 +360,7 @@ func TestExecuteCleanAcceptsPositionalSessionID(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := executeForTest([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
}