diff --git a/.gitignore b/.gitignore index 15f47de..abe7a43 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,27 @@ +# dependencies node_modules/ + +# build dist/ + +# env +.env +.env.* +!.env.example + +# logs +*.log + +# testing coverage/ .vault-test/ -.agent-session-pack/ -.worktrees/ -scripts/dev/ -*.log + +# editor and OS .DS_Store -.env +Thumbs.db +.idea/ +.vscode/ +*.swp + +# local +.worktrees/ diff --git a/AGENTS.md b/AGENTS.md index 65ef950..aa7e930 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,8 +54,6 @@ tests/ # shared helpers/fixtures + optional *.integration.test.ts examples/roundtrip/ scripts/ evidenceLocal.ts - dev/ # ignored scratch -docs/adr/current/ .github/workflows/ ``` @@ -66,7 +64,6 @@ Root guidance stays compact. Deeper detail lives in dedicated files: - `PROJECT.md`: purpose, direction, non-goals. - `CONTEXT.md` and `LANGUAGE.md`: domain model and vocabulary. - `CODE-STYLE.md`: full code style, CLI contract, and test policy. -- `docs/adr/current`: architecture decisions. ## Validation diff --git a/README.md b/README.md index 89ebeed..48a533b 100644 --- a/README.md +++ b/README.md @@ -334,6 +334,5 @@ pnpm build Project intent lives in [PROJECT.md](PROJECT.md). Agent editing rules live in [AGENTS.md](AGENTS.md). Code style and command contracts live in -[CODE-STYLE.md](CODE-STYLE.md). Architecture decisions live in -[docs/adr/current](docs/adr/current/). The public AI index lives in +[CODE-STYLE.md](CODE-STYLE.md). The public AI index lives in [llms.txt](llms.txt), following the [llms.txt](https://llmstxt.org/) convention. diff --git a/docs/adr/current/0001-cli-contract.md b/docs/adr/current/0001-cli-contract.md deleted file mode 100644 index 59a4de1..0000000 --- a/docs/adr/current/0001-cli-contract.md +++ /dev/null @@ -1,25 +0,0 @@ -# ADR 0001: CLI Contract - -## Status - -Accepted. - -## Context - -Agent Session Pack must work for humans in a terminal and for agents in scripts. It cannot hang in non-TTY mode. - -## Decision - -Use `citty` for command and argument parsing, `@clack/prompts` for TTY prompts and pickers, and Effect Schema for decoded command contracts. - -Bare TTY invocation opens a menu. Destructive `--apply` commands prompt only in an interactive TTY and can be confirmed with `--yes` for automation. Non-TTY or `--json` apply commands never hang; they require an explicit confirmation path. `--json` never emits ANSI. - -`agent-session-pack guide` is the discoverable command map for coding agents. `agent-session-pack guide --json` returns the same safety contract as stable machine-readable JSON. - -`pack --max --dry-run` is the all-age curiosity preview. `pack --max --apply` is refused so active or very recent sessions are not packed by accident. - -## Consequences - -The CLI boundary stays thin. Human and JSON routes call the same Effect workflows. - -`agent-session-pack check` is the no-install-friendly proof command after npm publish. It aliases the copy-only savings workflow and must stay safe against real provider stores. diff --git a/docs/adr/current/0002-safety-model.md b/docs/adr/current/0002-safety-model.md deleted file mode 100644 index ba10697..0000000 --- a/docs/adr/current/0002-safety-model.md +++ /dev/null @@ -1,17 +0,0 @@ -# ADR 0002: Archive Safety Model - -## Status - -Accepted. - -## Context - -The tool handles local AI session files that developers may rely on to resume work. Data loss is unacceptable. - -## Decision - -Packing is dry-run first. Apply mode must require explicit confirmation, write an archive, verify byte-exact restore by SHA-256, write metadata, and only then remove the original. Unpack apply mode restores from manifests and refuses to overwrite changed live files. Provider modules are read-only. Destructive behavior lives in core archive/restore workflows. Cursor and Devin are backup-only providers until their native stores are safe to mutate. - -## Consequences - -Normal tests use synthetic fixtures. Real local proof is opt-in through `pnpm evidence:local`. Real pack/unpack runs are opt-in through `agent-session-pack pack --all-providers --apply` and `agent-session-pack unpack --all-providers --apply`. diff --git a/docs/adr/current/0003-dependency-choices.md b/docs/adr/current/0003-dependency-choices.md deleted file mode 100644 index 72db397..0000000 --- a/docs/adr/current/0003-dependency-choices.md +++ /dev/null @@ -1,38 +0,0 @@ -# ADR 0003: Dependency Choices - -## Status - -Accepted. - -## Context - -The codebase needs typed workflows, runtime schemas, interactive CLI UX, argument parsing, and a local index. - -## Decision - -Runtime dependencies: - -- `effect` -- `citty` -- `@clack/prompts` - -Dev dependencies: - -- `typescript` -- `tsx` -- `tsup` -- `vitest` -- `@types/node` -- `@biomejs/biome` -- `eslint` -- `typescript-eslint` -- `eslint-plugin-tsdoc` - -External binary: - -- `zstd`, checked by `agent-session-pack doctor`. -- `sqlite3`, checked by `agent-session-pack doctor` for Devin session discovery. - -## Consequences - -Agent Session Pack keeps compression native and transparent while using TypeScript libraries for command and data contracts. diff --git a/docs/adr/current/0004-ci-workflows.md b/docs/adr/current/0004-ci-workflows.md deleted file mode 100644 index 9082732..0000000 --- a/docs/adr/current/0004-ci-workflows.md +++ /dev/null @@ -1,39 +0,0 @@ -# ADR 0004: Lean CI Workflows - -## Status - -Accepted. - -## Context - -Agent Session Pack is a small TypeScript CLI. Multi-OS and multi-Node matrices -add CI cost and noise without proportional value: engines already allow -`node >= 20`, and the product surface is pure Node + system `zstd`/`sqlite3` -binaries rather than native OS-specific builds. - -CI still needs to make push-to-main failures obvious and keep each gate easy -to reason about. - -## Decision - -Pin CI to a single platform and runtime: - -- `runs-on: ubuntu-latest` -- `node-version: 22` (current LTS; engines allow `>=20`) - -Use a lean workflow layout: - -- `ci.yml` — single workflow with parallel jobs: `biome`, `typecheck`, `test`, - `build`, plus a `ciGate` aggregator -- `reportFailure.yml` — reusable workflow called from `ci.yml` on main-branch - gate failure (opens or updates a `ci-failure` issue) -- `publish.yml` — release / manual publish on `ubuntu-latest` + Node 22 - -Do not use OS or Node version matrices. Install system `zstd` and `sqlite3` -only on the test job (archive and Devin provider tests need them). - -## Consequences - -Fewer CI jobs, faster PR feedback, and one place to read the required gates. -Main-branch failures still surface through `reportFailure.yml`. Broader -compatibility is covered by `engines.node` rather than matrix CI. diff --git a/docs/superpowers/plans/2026-07-06-kiro-session-roundtrip.md b/docs/superpowers/plans/2026-07-06-kiro-session-roundtrip.md deleted file mode 100644 index 7847134..0000000 --- a/docs/superpowers/plans/2026-07-06-kiro-session-roundtrip.md +++ /dev/null @@ -1,35 +0,0 @@ -# Kiro Session Round-Trip Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Prove a latest Kiro CLI session can be copied, compressed, restored, and verified without touching the original session file. - -**Architecture:** Build a minimal TypeScript CLI/library that discovers the latest Kiro JSONL session, copies it into a repo-local fixture directory, compresses that copy with `zstd`, restores it to a separate directory, and compares SHA256 hashes. JSONL parsing is used only as validation; exact bytes are the source of truth. - -**Tech Stack:** Node.js 24, TypeScript, Vitest, native `zstd` CLI, Node `crypto`, Node `fs/promises`. - -## Global Constraints - -- No daemon or watcher. -- Never delete, rewrite, or compress the real `~/.kiro/sessions` source file. -- Use exact-byte round-trip verification with SHA256. -- Test first: Vitest must fail before production implementation exists. - ---- - -### Task 1: Kiro Exact-Byte Round Trip - -**Files:** -- Create: `tests/kiroRoundTrip.test.ts` -- Create: `src/kiroRoundTrip.ts` -- Create: `src/cli.ts` - -**Interfaces:** -- Produces: `runKiroRoundTrip(options?: RoundTripOptions): Promise` -- Produces: `formatEvidence(result: RoundTripResult): string` - -- [x] **Step 1: Write the failing test** -- [ ] **Step 2: Run test to verify it fails** -- [ ] **Step 3: Write minimal implementation** -- [ ] **Step 4: Run test to verify it passes** -- [ ] **Step 5: Run CLI evidence command** diff --git a/docs/superpowers/plans/2026-07-07-interactive-cli-flow.md b/docs/superpowers/plans/2026-07-07-interactive-cli-flow.md deleted file mode 100644 index 35fd576..0000000 --- a/docs/superpowers/plans/2026-07-07-interactive-cli-flow.md +++ /dev/null @@ -1,248 +0,0 @@ -# Interactive CLI Flow Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Build the approved guided Clack CLI flow for Agent Session Pack with first setup, provider multi-select, vault path validation, spinner-backed scans, and safe pack/restore entrypoints. - -**Architecture:** Keep command parsing and automation in `citty`, keep prompt orchestration in `src/cli`, and keep filesystem validation plus provider inventory summaries in `src/core`. Interactive flows call the same command/core workflows used by scriptable commands so JSON output and destructive safety stay consistent. - -**Tech Stack:** TypeScript, Effect, Effect Schema, citty, @clack/prompts, Vitest, Biome, ESLint. - -## Global Constraints - -- Agent Session Pack is CLI-only. -- No daemon in v1. -- No local web app in v1. -- No mutation of Cursor's native storage in v1. -- No mutation of Devin's native storage in v1. -- No lossy conversion of session logs. -- No background deletion of real session files. -- Provider modules stay read-only. -- Destructive behavior stays in core archive/restore workflows. -- `--json`, non-TTY calls, and explicit command invocations never prompt or hang. -- Bare `agent-session-pack` in a TTY opens the interactive safety menu. -- Provider setup uses multi-select. -- Vault path setup validates before summary and final confirmation. -- Provider scanning shows animated loading in TTY mode. - ---- - -### Task 1: Setup Config And Vault Path Validation - -**Files:** -- Create: `src/core/setupConfig.ts` -- Modify: `src/core/index.ts` -- Test: `tests/setupConfig.test.ts` - -**Interfaces:** -- Produces: `expandHomePath(path, home)`, `resolveConfigPath(home)`, `validateVaultPath(request)`, `writeSetupConfig(request)`. -- Consumes: `ProviderIdSchema` and `ProviderId` from `src/core/sessionStore.ts`. - -- [ ] **Step 1: Write failing validation tests** - -```ts -import { mkdir, stat } from 'node:fs/promises'; -import { tmpdir } from 'node:os'; -import { join } from 'node:path'; -import { Effect } from 'effect'; -import { describe, expect, it } from 'vitest'; -import { - expandHomePath, - validateVaultPath, - writeSetupConfig, -} from '../src/core/setupConfig.js'; - -describe('setup config vault paths', () => { - it('expands home paths and accepts a new vault below a writable parent', async () => { - const home = await mkdir(join(tmpdir(), 'agent-session-pack-home-'), { recursive: true }); - const resolved = await Effect.runPromise( - validateVaultPath({ - home, - inputPath: '~/.agent-session-pack', - providerRoots: [join(home, '.codex', 'sessions')], - }), - ); - - expect(resolved.path).toBe(join(home, '.agent-session-pack')); - expect(expandHomePath('~/vault', home)).toBe(join(home, 'vault')); - }); - - it('rejects vault paths inside provider stores', async () => { - const home = await mkdir(join(tmpdir(), 'agent-session-pack-provider-'), { recursive: true }); - const providerRoot = join(home, '.codex', 'sessions'); - await mkdir(providerRoot, { recursive: true }); - - await expect( - Effect.runPromise( - validateVaultPath({ - home, - inputPath: join(providerRoot, 'vault'), - providerRoots: [providerRoot], - }), - ), - ).rejects.toMatchObject({ - _tag: 'VaultPathValidationError', - reason: 'inside-provider-store', - }); - }); - - it('writes config and creates the vault only after setup confirmation', async () => { - const home = await mkdir(join(tmpdir(), 'agent-session-pack-write-'), { recursive: true }); - const vaultPath = join(home, '.agent-session-pack'); - - await Effect.runPromise( - writeSetupConfig({ - home, - config: { - version: 1, - providers: ['codex', 'claude'], - vaultPath, - coldAfter: '7d', - createdAt: '2026-07-07T00:00:00.000Z', - updatedAt: '2026-07-07T00:00:00.000Z', - }, - }), - ); - - await expect(stat(vaultPath)).resolves.toMatchObject({ isDirectory: expect.any(Function) }); - }); -}); -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `pnpm vitest run tests/setupConfig.test.ts` - -Expected: fails because `src/core/setupConfig.ts` does not exist. - -- [ ] **Step 3: Implement setup config helpers** - -Create `src/core/setupConfig.ts` with Effect Schema config decoding, path expansion, provider-store rejection, writable parent validation, and config write to `~/.agent-session-pack/config.json`. - -- [ ] **Step 4: Export helpers** - -Add `export * from './setupConfig.js';` to `src/core/index.ts`. - -- [ ] **Step 5: Run test to verify it passes** - -Run: `pnpm vitest run tests/setupConfig.test.ts` - -Expected: all setup config tests pass. - -### Task 2: Provider Inventory Summaries - -**Files:** -- Create: `src/core/providerInventory.ts` -- Modify: `src/core/index.ts` -- Test: `tests/providerInventory.test.ts` - -**Interfaces:** -- Produces: `inspectProviderInventory(request)` returning provider rows with session count, cold count, guarded recent count, bytes, mode, and paths. -- Consumes: provider adapters from `src/providers/index.ts`. - -- [ ] **Step 1: Write failing inventory tests** - -Create tests that build temp Codex JSONL files with old and recent mtimes, call `inspectProviderInventory`, and assert `coldSessions`, `guardedRecentSessions`, `candidateBytes`, and `paths`. - -- [ ] **Step 2: Run test to verify it fails** - -Run: `pnpm vitest run tests/providerInventory.test.ts` - -Expected: fails because `providerInventory.ts` does not exist. - -- [ ] **Step 3: Implement provider inventory** - -Implement read-only provider discovery across existing roots. Classify archive-mode sessions older than the cutoff as cold and newer sessions as guarded recent. Backup-only providers report sessions and paths but zero cold destructive candidates. - -- [ ] **Step 4: Export inventory** - -Add `export * from './providerInventory.js';` to `src/core/index.ts`. - -- [ ] **Step 5: Run test to verify it passes** - -Run: `pnpm vitest run tests/providerInventory.test.ts` - -Expected: inventory test passes. - -### Task 3: Interactive Clack Prompt Flow - -**Files:** -- Create: `src/cli/interactiveCli.ts` -- Modify: `src/cli/main.ts` -- Modify: `src/cli/commands/initCommand.ts` -- Test: `tests/interactiveCli.test.ts` -- Test: `tests/mainEntrypoint.test.ts` - -**Interfaces:** -- Produces: `shouldRunInteractiveCli(argv, stdin, stdout)`, `runInteractiveCli(request)`, `runFirstSetup(request)`. -- Consumes: setup config helpers, provider inventory, pack/unpack command runners, savings command runner, scan command runner, doctor command runner. - -- [ ] **Step 1: Write failing interactive tests** - -Create tests with a fake prompt adapter that assert main-menu option hints exist, setup provider prompt is multi-select, vault path validation is called, and bare TTY detection returns true only when no subcommand or flags are present. - -- [ ] **Step 2: Run test to verify it fails** - -Run: `pnpm vitest run tests/interactiveCli.test.ts tests/mainEntrypoint.test.ts` - -Expected: fails because the interactive module and bare TTY detection do not exist. - -- [ ] **Step 3: Implement interactive orchestration** - -Use `@clack/prompts` `intro`, `note`, `select`, `multiselect`, `text`, `confirm`, `spinner`, `outro`, `cancel`, and `isCancel`. Keep prompt code in `src/cli/interactiveCli.ts` and call existing command runners for check, review, pack, restore, and doctor actions. - -- [ ] **Step 4: Wire bare TTY and init** - -Update `src/cli/main.ts` so bare TTY invocation calls `runInteractiveCli`. Update `initCommand` so TTY non-JSON runs `runFirstSetup`; non-TTY and `--json` remain non-interactive. - -- [ ] **Step 5: Run test to verify it passes** - -Run: `pnpm vitest run tests/interactiveCli.test.ts tests/mainEntrypoint.test.ts` - -Expected: tests pass and existing entrypoint behavior remains stable. - -### Task 4: Output, Docs, And Full Verification - -**Files:** -- Modify: `README.md` -- Modify: `CODE-STYLE.md` -- Modify: `src/output/packOutput.ts` -- Test: `tests/packAllProvidersCommand.test.ts` -- Test: `tests/humanOutput.test.ts` - -**Interfaces:** -- Consumes: `ProviderInventoryReport` for interactive tables. -- Keeps: `formatHumanPackReport`, `formatHumanUnpackReport`, and JSON output stable for automation. - -- [ ] **Step 1: Write or update failing output tests** - -Assert pack dry-run output no longer says apply is blocked, and human-facing tables include the guided setup language where applicable. - -- [ ] **Step 2: Run focused output tests** - -Run: `pnpm vitest run tests/packAllProvidersCommand.test.ts tests/humanOutput.test.ts` - -Expected: tests fail before output copy is corrected. - -- [ ] **Step 3: Update output and docs** - -Remove stale pack text, document bare `agent-session-pack`, `agent-session-pack init`, provider multi-select, path validation, and spinner-backed scans. - -- [ ] **Step 4: Run focused tests** - -Run: `pnpm vitest run tests/packAllProvidersCommand.test.ts tests/humanOutput.test.ts` - -Expected: focused tests pass. - -- [ ] **Step 5: Run full verification** - -Run: - -```bash -pnpm check:ci -pnpm typecheck -pnpm test -pnpm build -``` - -Expected: all commands exit 0. diff --git a/docs/superpowers/specs/2026-07-07-interactive-cli-flow-design.md b/docs/superpowers/specs/2026-07-07-interactive-cli-flow-design.md deleted file mode 100644 index 79adf9c..0000000 --- a/docs/superpowers/specs/2026-07-07-interactive-cli-flow-design.md +++ /dev/null @@ -1,309 +0,0 @@ -# Interactive CLI Flow Design - -## Purpose - -Agent Session Pack is a CLI-only tool for reducing local disk usage from AI coding-agent -session history while preserving byte-exact restore into provider-native formats. The -interactive CLI should feel like a safe storage assistant: it explains what will happen, -shows evidence before mutation, and keeps every destructive action behind an explicit -confirmation. - -## Scope - -This design covers the human TTY flow for first setup, savings checks, session review, -pack, restore, and doctor entrypoints. It does not install lifecycle hooks, run a daemon, -mutate Cursor native storage, mutate Devin native storage, or change the JSON automation -contract. - -## CLI Shape - -Agent Session Pack remains a hybrid CLI: - -- `citty` owns commands, flags, help output, and scriptable behavior. -- `@clack/prompts` owns short interactive flows in TTY mode. -- `--json`, non-TTY calls, and explicit command invocations never prompt or hang. -- Bare `agent-session-pack` in a TTY opens the interactive safety menu. - -## First Screen - -Bare TTY invocation starts with a concise explanation before showing actions: - -```text -Agent Session Pack - -Compress old local AI-agent sessions without breaking resume. - -How it works: - 1. Scans provider stores read-only - 2. Proves savings on copied files first - 3. Packs only cold sessions into ~/.agent-session-pack - 4. Verifies byte-exact restore - 5. Removes originals only after verification - -No daemon. No background deletion. Cursor and Devin stay backup-only for now. -``` - -## Main Menu - -Each option includes a dimmed description with an example-level explanation. - -```text -? What do you want to do? - -> First setup choose providers, vault path, cold threshold, and safety defaults - Check savings copy-only proof; shows what you could save without touching sessions - Review sessions scan all providers; show dates, paths, size, cold/active status - Pack cold sessions dry-run first; apply only after verified archive + confirmation - Restore sessions unpack archived sessions back to native provider paths - Doctor check zstd, sqlite, provider roots, vault health, and config - Exit leave without changing files -``` - -## First Setup Flow - -Setup writes configuration only. It does not pack, delete, restore, or mutate provider -session files. - -The setup flow begins with animated loading while provider discovery runs: - -```text -Scanning provider stores... -``` - -The spinner text names the work being done and stops before rendering the provider table. -Spinner output is TTY-only and is never emitted in `--json` mode. - -After scanning, setup shows discovered providers: - -```text -Detected providers - -Provider Mode Sessions Path -codex archive 558 ~/.codex/sessions -claude archive 176 ~/.claude/projects -kiro archive 227 ~/.kiro/sessions -devin backup-only 8 ~/.local/share/devin/cli/sessions.db -cursor backup-only 0 Cursor profile/session stores -``` - -Provider selection is a multi-select prompt: - -```text -? Which providers should Agent Session Pack manage? - -> codex archive old JSONL sessions; restore byte-exact when needed - claude archive old Claude Code project sessions - kiro archive old Kiro CLI sessions - devin backup-only proof; native mutation disabled for safety - cursor backup-only proof; native mutation disabled for safety -``` - -Rules: - -- Archive-mode providers may be selected for scan, savings, pack, and restore. -- Backup-only providers may be selected for scan and savings, but not destructive pack. -- The prompt must allow selecting multiple providers. -- The prompt must allow canceling without writing config. -- Empty selection returns to the same prompt with a short explanation. - -Cold threshold selection follows: - -```text -? When is a session considered cold? - -> 7 days recommended; protects normal active work - 14 days safer for long-running sessions - 30 days conservative cleanup - Custom enter 12h, 7d, 2w, or 30d -``` - -The vault path prompt validates the path before continuing: - -```text -? Where should archives be stored? - -> ~/.agent-session-pack default local vault; manifests and compressed archives live here - Custom path useful for external drive or synced disk -``` - -Validation rules: - -- Expand `~` against `HOME`. -- Reject an empty path. -- Reject paths inside known provider stores such as `~/.codex`, `~/.claude`, and `~/.kiro`. -- If the path exists, it must be a directory and writable. -- If the path does not exist, the parent directory must exist and be writable. -- The setup summary must show the resolved absolute path. -- Config writes create the vault directory only after final confirmation. - -Setup ends with a full summary: - -```text -Setup summary - -Providers: codex, claude, kiro -Vault: /Users/example/.agent-session-pack -Cold after: 7 days -Safety: - - dry-run before apply - - recent sessions guarded - - restore verified before original removal - - changed live files never overwritten - -? Save this setup? -``` - -## Savings Flow - -The savings flow proves compression on copied data only. - -```text -Checking savings... -``` - -After the copy-only proof, render the existing human evidence table and finish with: - -```text -Original sessions touched: no -Next: run Pack cold sessions when you are ready to archive cold files. -``` - -## Review Sessions Flow - -The review flow scans configured or selected providers and shows a dense table that helps -the user understand what is active, cold, archived, or backup-only. - -```text -Scanning provider stores... - -Provider Sessions Cold Guarded recent Size Path -codex 558 480 78 2.2 GB ~/.codex/sessions -claude 176 120 56 1.4 GB ~/.claude/projects -kiro 227 0 227 0 B ~/.kiro/sessions -``` - -The table must include paths because users need to understand where disk usage lives. - -## Pack Flow - -The pack flow always starts as a dry-run in interactive mode: - -```text -Pack cold sessions - -Scanning provider stores... -``` - -Then render a candidate table: - -```text -Provider Sessions Cold Guarded recent Candidate size Path -codex 558 480 78 2.2 GB ~/.codex/sessions -claude 176 120 56 1.4 GB ~/.claude/projects -kiro 227 0 227 0 B ~/.kiro/sessions -``` - -Rules: - -- Sessions newer than the cold threshold are labeled guarded recent. -- Guarded recent sessions are not candidates. -- Backup-only providers are shown for visibility and skipped for destructive pack. -- The first confirmation starts a dry-run preview only. -- The second confirmation applies the verified archive workflow. -- Apply text must name the provider count, candidate session count, candidate size, and vault path. - -Final confirmation copy: - -```text -Apply pack now? - -This will archive 600 cold sessions from codex and claude into: -/Users/example/.agent-session-pack - -Original files are removed only after archive write, restore verification, and manifest write. -``` - -## Restore Flow - -The restore flow scans the vault first: - -```text -Scanning vault manifests... -``` - -Then it shows archived sessions by provider: - -```text -Provider Archived Restore target Conflicts -codex 480 original provider paths 0 -claude 120 original provider paths 0 -kiro 0 original provider paths 0 -``` - -Rules: - -- Changed live files are never overwritten. -- Conflicts are shown before confirmation. -- Restore apply requires explicit confirmation. -- Restore success prints the next useful command: `agent-session-pack scan`. - -## Doctor Flow - -Doctor stays command-shaped but becomes reachable from the interactive menu. It should -check external binaries, provider roots, vault path, config readability, and backup-only -provider constraints. Failures should include the command needed to fix the issue. - -## Automation Contract - -All existing commands remain stable: - -```bash -agent-session-pack check [--provider codex|claude|kiro|cursor|devin] [--json] -agent-session-pack init [--apply] [--json] -agent-session-pack scan [--provider codex|claude|kiro|cursor|devin] [--json] -agent-session-pack pack [--all-providers|--provider codex|claude|kiro|cursor|devin] [--older-than 7d] [--dry-run|--apply] [--yes] [--json] -agent-session-pack unpack [--all-providers|--provider codex|claude|kiro|cursor|devin] [--apply] [--yes] [--json] -agent-session-pack savings [--provider codex|claude|kiro|cursor|devin] [--json] -``` - -Non-TTY behavior: - -- No prompt. -- No spinner. -- No ANSI-only descriptions. -- `--json` emits stable JSON only. -- Apply mode requires `--yes` or an explicit confirmation path. - -## Error And Empty States - -- Missing `HOME`: print `HOME is not set.` and exit non-zero. -- No providers found: show provider root examples and offer Doctor or Exit. -- No cold candidates: show sessions found and guarded count, then exit with no changes. -- Invalid vault path: keep the user in the path prompt with a clear reason. -- Missing `zstd`: show Doctor result and install guidance. -- User cancel: print `No files changed.`. -- Apply failure: preserve original files unless the verified archive workflow completed. - -## Implementation Notes - -- Keep provider modules read-only. -- Put prompt orchestration in `src/cli`, not in core workflows. -- Keep destructive behavior inside existing core archive/restore workflows. -- Build prompt choices from provider discovery results so option descriptions include real - session counts, modes, and paths. -- Use Clack spinner only for TTY loading states. -- Use shared renderers for tables where possible so command and interactive output stay - consistent. - -## Acceptance Criteria - -- Bare `agent-session-pack` in a TTY opens the guided safety menu. -- Main menu options include dim descriptions with example-level context. -- First setup explains the safety model before asking questions. -- Provider setup uses multi-select. -- Vault path setup validates before summary and final confirmation. -- Provider scanning shows animated loading in TTY mode. -- Pack flow shows cold and guarded-recent counts before apply. -- Backup-only providers are visible but skipped for destructive pack. -- `--json` and non-TTY behavior never prompt or emit spinner output. -- Existing scriptable commands continue to work. diff --git a/llms.txt b/llms.txt index b07f260..af39229 100644 --- a/llms.txt +++ b/llms.txt @@ -9,7 +9,6 @@ - [Project purpose](https://github.com/YosefHayim/agent-session-pack/blob/main/PROJECT.md): Scope, users, non-goals, and success criteria. - [Agent instructions](https://github.com/YosefHayim/agent-session-pack/blob/main/AGENTS.md): Editing rules for coding agents. - [Code style](https://github.com/YosefHayim/agent-session-pack/blob/main/CODE-STYLE.md): TypeScript, Effect, CLI, output, and test conventions. -- [Architecture decisions](https://github.com/YosefHayim/agent-session-pack/tree/main/docs/adr/current): Current ADRs for CLI contract, safety model, dependency choices, and CI workflows. - [Roundtrip examples](https://github.com/YosefHayim/agent-session-pack/tree/main/examples/roundtrip): Tiny before/archive/after fixtures that show byte-exact restore. ## What It Does In v0.2.0 diff --git a/package.json b/package.json index d81f65d..d92c6ae 100644 --- a/package.json +++ b/package.json @@ -57,7 +57,6 @@ "PROJECT.md", "AGENTS.md", "CODE-STYLE.md", - "docs/adr/current", "LICENSE", "examples" ],