feat(cli): import/export verbs + Pathbase round-trip

CHANGELOG.md

@@ -10,6 +10,15 @@ All notable changes to the Toolpath workspace are documented here.
 
 ### Changed
 
+- `toolpath-cli` 0.5.0: CLI restructure — external-boundary verbs collapsed into two symmetric verbs with an on-disk document cache at `~/.toolpath/documents/<cache-id>.json`:
+  - `path import <source>` replaces `path derive <source>`. Writes each derived document into the cache and prints the resulting path to stdout. `--no-cache` sends JSON to stdout instead (preserving old pipe ergonomics: `path import git --no-cache | path render md`). `--force` overwrites an existing cache entry; default is error-on-exists, uniform across every source.
+  - `path export <target>` replaces `path incept` and `path project claude`. `export claude --input <ref> [--project <dir> | --output <file>]` covers both old commands; `<ref>` resolves as a bare cache id first (e.g. `claude-abc123`) or a filesystem path.
+  - `path cache ls | rm` list / remove cached documents.
+  - **New Pathbase round-trip:** `path import pathbase <id-or-url>` downloads a previously uploaded trace into the cache; `path export pathbase --input <ref>` uploads. Reuses the existing `path auth login` session at `~/.toolpath/credentials.json`. Targets `POST/GET /api/v1/traces[/:id]`. `--url` on `export pathbase` warns when its host differs from the session's.
+  - **Cache id** is `<source>-<inner-id>`. Git folds a short hash of the canonical repo path so two repos on the same branch don't collide (`git-a1b2c3d4-path-main` vs `git-e5f6a7b8-path-main`). `make_id` strips any trailing `.json` to avoid round-tripping into a `.json.json` file.
+  - **Atomic cache writes:** `write_cached` uses `O_CREAT | O_EXCL` when not forcing, so concurrent imports can't silently stomp each other.
+  - **Deprecation aliases** (one-release overlap, hidden, stderr warning): `path derive` → `path import` (stdout preserved via implicit `--no-cache`), `path incept` → `path export claude --project <dir>`, `path project claude` → `path export claude`.
+  - Shared HTTP/session plumbing extracted into `cmd_pathbase` (from `cmd_auth`); config-dir resolution lives in a new `config` module so `cmd_cache` builds on wasm/emscripten targets where `cmd_pathbase` is gated out.
 - `toolpath-convo` 0.7.0: **breaking** — `file_write_diff` gains a `before_state: Option<&str>` parameter. For the `Write { content }` shape, callers can now supply the prior file contents (e.g. resolved from `git show HEAD:<path>`) so the resulting diff shows `-` lines for replaced content instead of an addition-only hunk. `None` preserves the old behaviour (diff against `""`). `Edit` / `MultiEdit` shapes are unaffected — they carry their own `old_string`. `toolpath-claude`'s Claude-JSONL deriver wires a best-effort git-HEAD lookup for `Write` tool invocations; falls back silently to additions-only when the project isn't a git repo, the file isn't tracked, or `git` isn't on `PATH`. (#35)
 - `toolpath-convo` 0.6.0: adds `derive_path(view, config) -> Path` and `DeriveConfig` (moved in from the unreleased `toolpath-derive` crate). `toolpath-convo` now depends on `toolpath`.
 - `toolpath-convo` 0.6.0: adds `ConversationProjector` trait, `AnyProjector` type-erasing wrapper, `extract_conversation()` for Path → ConversationView, and conversation sub-protocol (`conversation.init`, `conversation.append`, `tool.invoke`, `agent://` URN scheme).

CLAUDE.md

@@ -65,13 +65,27 @@ Requires Rust 1.85+ (edition 2024). Pinned to 1.94.0 via `rust-toolchain.toml`.
 The binary is called `path` (package: `toolpath-cli`):
 
 ```bash
-cargo run -p toolpath-cli -- derive git --repo . --branch main --pretty
-cargo run -p toolpath-cli -- derive github --repo owner/repo --pr 42 --pretty
-cargo run -p toolpath-cli -- derive claude --project /path/to/project
-cargo run -p toolpath-cli -- derive gemini --project /path/to/project
-cargo run -p toolpath-cli -- derive codex --session <uuid>
-cargo run -p toolpath-cli -- derive opencode --session ses_<id>
-cargo run -p toolpath-cli -- derive pi --project /path/to/project
+# Import from external formats into the local toolpath cache (~/.toolpath/documents/)
+cargo run -p toolpath-cli -- import git --repo . --branch main
+cargo run -p toolpath-cli -- import github https://github.com/owner/repo/pull/42
+cargo run -p toolpath-cli -- import claude --project /path/to/project
+cargo run -p toolpath-cli -- import gemini --project /path/to/project
+cargo run -p toolpath-cli -- import codex --session <uuid>
+cargo run -p toolpath-cli -- import opencode --session ses_<id>
+cargo run -p toolpath-cli -- import pi --project /path/to/project
+cargo run -p toolpath-cli -- import pathbase <trace-id-or-url>
+cargo run -p toolpath-cli -- import claude --project . --no-cache | path render md --input -
+
+# Export toolpath documents into external formats. <ref> is a cache id or a file path.
+cargo run -p toolpath-cli -- export claude --input <ref> --project /tmp/sandbox
+cargo run -p toolpath-cli -- export claude --input <ref> --output conv.jsonl
+cargo run -p toolpath-cli -- export pathbase --input <ref>
+
+# Manage the cache
+cargo run -p toolpath-cli -- cache ls
+cargo run -p toolpath-cli -- cache rm <cache-id>
+
+# Inspect / analyze
 cargo run -p toolpath-cli -- render dot --input doc.json
 cargo run -p toolpath-cli -- render md --input doc.json --detail full
 cargo run -p toolpath-cli -- query dead-ends --input doc.json
@@ -91,6 +105,10 @@ cargo run -p toolpath-cli -- auth whoami
 cargo run -p toolpath-cli -- auth logout
 ```
 
+`path derive`, `path incept`, and `path project` are deprecated aliases for `path import` / `path export claude` and print a deprecation warning to stderr. They will be removed in the release after next.
+
+The **cache** at `~/.toolpath/documents/<cache-id>.json` is the single landing zone for every `import` (and for `import pathbase` downloads). Cache id is `<source>-<inner-id>` — e.g. `claude-abc123`, `git-main`, `pathbase-trc_01H…`. Files are `0600`, parent directory `0700`. `$TOOLPATH_CONFIG_DIR` overrides the root. Default behavior: error on cache hit; pass `--force` to overwrite. `--no-cache` sends the JSON to stdout for shell composition.
+
 `path auth login` prints `<base>/auth/cli`; the user opens it, logs in, and
 pastes the 8-character code back into the CLI. The CLI calls
 `POST /api/v1/auth/cli/redeem` to trade the code for a bearer token, which it
@@ -121,7 +139,7 @@ Tests live alongside the code (`#[cfg(test)] mod tests`), plus `toolpath-cli` ha
 - `toolpath-opencode`: 43 unit + 1 doc test (SQLite reader, JSON payload serde, provider assembly, snapshot-based derive, tool-input fallback for gitignored paths)
 - `toolpath-pi`: ~88 unit tests (types, paths, error, reader, io, provider)
 - `toolpath-dot`: 30 unit + 2 doc tests (render, visual conventions, escaping)
-- `toolpath-cli`: 126 unit + 24 integration tests (all commands, track sessions, merge, validate, roundtrip, render-md snapshots)
+- `toolpath-cli`: 165 unit + 26 integration tests (import/export/cache, track sessions, merge, validate, roundtrip, render-md snapshots, deprecation aliases, pathbase HTTP mock-server tests)
 
 Validate example documents: `for f in examples/*.json; do cargo run -p toolpath-cli -- validate --input "$f"; done`
 

README.md

@@ -62,29 +62,42 @@ See each crate's README for library-level documentation.
 # Build everything
 cargo build --workspace
 
-# Derive a Toolpath document from this repo's git history
-path derive git --repo . --branch main --pretty
+# Import a Toolpath document from this repo's git history (cached under ~/.toolpath/documents/)
+path import git --repo . --branch main
 
 # Visualize it
-path derive git --repo . --branch main | path render dot | dot -Tpng -o graph.png
+path import git --repo . --branch main --no-cache | path render dot | dot -Tpng -o graph.png
 
 # Render as Markdown for an LLM
-path derive git --repo . --branch main | path render md
+path import git --repo . --branch main --no-cache | path render md
 
-# Derive from a GitHub pull request
-path derive github --repo owner/repo --pr 42 --pretty
+# Import from a GitHub pull request
+path import github https://github.com/owner/repo/pull/42
 
-# Derive from Claude conversation logs
-path derive claude --project /path/to/project --pretty
+# Import from Claude conversation logs
+path import claude --project /path/to/project
 
-# Derive from Gemini CLI conversation logs
-path derive gemini --project /path/to/project --pretty
+# Import from Gemini CLI conversation logs
+path import gemini --project /path/to/project
 
-# Derive from Codex CLI rollout files (most recent session by default)
-path derive codex --pretty
+# Import from Codex CLI rollout files (most recent session by default)
+path import codex
 
-# Derive from opencode session database (most recent session by default)
-path derive opencode --pretty
+# Import from opencode session database (most recent session by default)
+path import opencode
+
+# List what's in the cache
+path cache ls
+
+# Export a cached document back into a Claude Code session
+path export claude --input claude-<session-id> --project /path/to/resume
+
+# Push a cached document to Pathbase
+path auth login
+path export pathbase --input claude-<session-id>
+
+# Pull a trace from Pathbase back into the local cache
+path import pathbase <trace-id-or-url>
 
 # Query for dead ends (abandoned approaches)
 path query dead-ends --input doc.json

crates/toolpath-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "toolpath-cli"
-version = "0.4.0"
+version = "0.5.0"
 edition.workspace = true
 license.workspace = true
 repository = "https://github.com/empathic/toolpath"