claude-code-station 0.2.1

package/docs/v0.2.1-backlog.md

@@ -0,0 +1,225 @@
+# v0.2.1+ Deferred Backlog
+
+Collected from the second-round code review (CR2, 2026-04-14) across four specialist reviews (TypeScript / Security / Database / General). **None of these are ship blockers for v0.2.0** — all HIGH-severity findings and the critical MEDIUM items were addressed in Phase 6 (see `docs/v0.2.0-review-notes.md` §Phase 6 fixes). The items below are deliberate deferrals, scheduled for v0.2.1 or later as scope permits.
+
+Severity conventions per `~/.claude/rules/common/code-review.md`:
+CRITICAL (block) · HIGH (warn) · MEDIUM (info) · LOW (note) · INFO (optional)
+
+---
+
+## Closed in the 2026-06-12 review cleanup (`fix/v0.2.1-review-cleanup`)
+
+The 4-perspective defensive review (Correctness / Consistency / Design /
+Devil's Advocate, 2026-06-12) confirmed and closed the following entries.
+Details live in `CHANGELOG.md` [Unreleased] and the per-fix regression tests.
+
+- **[MEDIUM] `isUnderHome` lexical resolve()** — already fixed by audit M-4
+  (realpathSync two-layer check); this entry had gone stale (review K-3).
+- **[MEDIUM] Extract shared utils to `bin/ccs-utils.ts`** — done (review
+  A-1/A-2/A-3/K-8): truncate / timeBucket / formatRelativeTime /
+  formatDateTime / extractText / UUID_RE / MAX_JSONL_SIZE unified, with
+  `test/ccs-utils.test.ts` pinning behavior.
+- **[MEDIUM] `git log %x09` tab separator** — switched to `%x00` (NUL) +
+  `split("\0")` with a tab-in-subject regression test (review C-1).
+- **[MEDIUM] `--current-only` filters in JS** — pushed into SQL as
+  `cwd = ? OR (cwd >= ? AND cwd < ?)` so `idx_sessions_cwd` applies
+  (review A-10), with an exact/subdir/sibling-prefix test.
+- **[LOW] Error message style inconsistency** — `command`/`custom` errors now
+  carry the `reposYmlPath: repos[i].field` prefix like every other
+  ConfigError (review K-4).
+- **[LOW] 50MB JSONL cap guard untested** — oversized files now keep their
+  row, stamp size/mtime, and stop re-parsing (review C-4) — covered by an
+  ftruncate-based sparse-file test.
+- **[LOW] `freshImport()` cache-bust comment** — resolved by documenting
+  reality instead: the ESM cache is NOT busted and resets must use exported
+  hooks (review C-6). No query-string hack added.
+- **[LOW] Missing `--current-only` test** — added (see A-10 above).
+- **[LOW] `install.sh` ls | grep** — replaced with `find -maxdepth 1`
+  (review K-10).
+- **[LOW] CR3: `resolvedDefaultsCommand` origin validation** — defaults.command
+  (incl. CCS_CMD/CCR_CMD origin) is now SHELL_METACHARS-validated in
+  loadConfig and persisted to the v2 `meta` table for unmapped-session
+  fallback (reviews A-6 + A-8).
+- **[LOW] CR3: REVIEW.md stale command-trust wording** — updated (review K-5).
+- **[LOW] CR3 / README architecture diagram omissions** — diagram now lists
+  all bin/ modules incl. ccs-preview-session / ccs-scan-sessions / ccs-utils
+  (reviews K-6 / A-11).
+
+Follow-up batch (same branch, second pass on user request):
+
+- **[MEDIUM] `scanOneRepo` COUNT(*) outside transaction** — session
+  aggregation now runs inside the write transaction (better-sqlite3 is
+  synchronous, so read+write are atomic).
+- **[LOW] PRAGMA tuning** — write-path `openDb` sets `cache_size = -8000`,
+  `temp_store = MEMORY`, `mmap_size = 64MB`.
+- **[LOW] Concurrent scan race / advisory lock** — `<cacheDir>/scan.lock`
+  (O_EXCL create, 5-min stale takeover); a second scan skips with a stderr
+  note and `ScanResult.lockSkipped`. Tested incl. stale-lock takeover.
+- **[HIGH] `install.sh` node_modules** — short-term option (a) shipped:
+  install.sh symlinks the repo checkout's `node_modules` into the install
+  dir (warns when absent). Option (b) npm-package distribution remains open
+  below.
+- **Shell-surface tests** — new `test/ccs-shell.test.ts` drives `bin/ccs`
+  (non-interactive paths) and `ccs-delete.sh` (incl. the C-2 rm-failure
+  branch and the L-2 subagent-dir removal) via node:test + spawnSync.
+  No bats dependency needed.
+
+---
+
+## MEDIUM
+
+### [MEDIUM] `ccs-list.ts --current-only` filters in JS after full fetch
+**File**: `bin/ccs-list.ts` (current-only filter path)
+**Issue**: `--current-only` pulls all sessions from SQLite then filters by `cwd === process.cwd()` in JS. At 10x scale (thousands of sessions) the unnecessary deserialization dominates.
+**Fix sketch**: Push the filter into SQL as a `WHERE cwd = ?` predicate on the prepared statement. Parameterize the current cwd.
+**Why deferred**: Current dataset sizes (hundreds of sessions) make the JS filter imperceptible. Revisit once users report lag at scale.
+
+---
+
+## LOW
+
+### [LOW] Error message style inconsistency
+**File**: `bin/ccs-config.ts` (multiple `throw new ConfigError(...)` sites)
+**Issue**: Older errors prefix messages with `${reposYmlPath}:` (file-path context) while the new Phase 6 `command` / `custom` validation errors don't. Inconsistent UX.
+**Fix sketch**: Pick one style (recommend always prefixing with source location) and unify; update tests.
+**Why deferred**: Cosmetic; messages are still intelligible. Batch with the v0.2.1 error-handling pass.
+
+### [LOW] `ccs-db.test.ts` uses `setTimeout(1100)` for TTL check
+**File**: `test/ccs-db.test.ts`
+**Issue**: Real `setTimeout` makes the test take 1.1 s minimum and introduces flake risk on loaded CI.
+**Fix sketch**: Inject a `nowFn` parameter into the TTL-check code path (default `Date.now`); tests pass a deterministic clock.
+**Why deferred**: Test quality improvement, not a shipping issue. Cleaner to do alongside the shared `ccs-utils.ts` extraction.
+
+### [LOW] `ccs-scan.test.ts` coverage gaps
+**File**: `test/ccs-scan.test.ts`
+**Issue**: Missing cases: (a) git-uninitialized repo, (b) missing `~/.claude/projects/` dir, (c) sessions with `cwd` NOT matching any configured repo, (d) 50 MB JSONL cap guard trigger.
+**Fix sketch**: Add four focused test cases; (d) can use a stub file with faked stat size to avoid generating 50 MB on disk.
+**Why deferred**: Existing tests cover the happy path; these are edge cases. Prioritized for v0.2.1 test-coverage uplift.
+
+### [LOW] `freshImport()` doesn't actually bust ESM cache
+**File**: `test/ccs-config.test.ts`
+**Issue**: `import(path)` without a cache-bust query is memoized by the ESM loader; successive `freshImport()` calls return the same module, which defeats the `migrationWarned` isolation intent.
+**Fix sketch**: Append `?v=${Date.now()}` to the import specifier.
+**Why deferred**: Current tests pass (module state happens to not leak between the specific test orderings used). Fix with M2 hook export.
+
+### [LOW] Missing `--current-only` test in ccs-list.test.ts
+**File**: `test/ccs-list.test.ts`
+**Issue**: No test exercises the `ccs .` (current-dir filter) path.
+**Fix sketch**: Add a test that seeds the DB with mixed `cwd` values and asserts only the current-cwd rows appear.
+**Why deferred**: Coverage, not correctness. Bundle with the v0.2.1 test pass.
+
+### [LOW] README architecture diagram filename ambiguity
+**File**: `README.md` (architecture section)
+**Issue**: Diagram labels read `ccs-preview.ts` in some places and `ccs-preview-session.ts` elsewhere; they are two distinct files and the diagram should disambiguate.
+**Fix sketch**: Update the diagram source and regenerate the image/ASCII art to show both nodes with labeled responsibilities.
+**Why deferred**: Docs-only; no functional impact.
+
+### [LOW] `ccs-preview-session.ts` banner comment
+**File**: `bin/ccs-preview-session.ts` (top of file)
+**Issue**: Future readers may mistake the `console.log` calls for debug output and try to remove them; they are actually the fzf preview stdout contract.
+**Fix sketch**: Add a banner comment at the top stating "NOTE: console.log output IS the fzf preview payload — not debug logging."
+**Why deferred**: Pure docs.
+
+### [LOW] `bin/ccs --flag=value` form not supported
+**File**: `bin/ccs` (arg parser loop)
+**Issue**: The loop recognizes `--flag value` but not `--flag=value` (POSIX-long-opt style).
+**Fix sketch**: Either extend the parser to split on `=`, or document the limitation in README and man-page.
+**Why deferred**: Mostly stylistic; current users have not complained.
+
+### [LOW] `install.sh` uses `ls | grep`
+**File**: `install.sh`
+**Issue**: Shellcheck SC2010 — `ls | grep` is fragile with unusual filenames.
+**Fix sketch**: Replace with a `find -printf` pattern or a glob-based `for f in pattern; do [ -e "$f" ]; done` loop.
+**Why deferred**: Current callers use well-formed filenames; cosmetic lint.
+
+### [LOW] `du -h` portability in `ccs-delete.sh`
+**File**: `bin/ccs-delete.sh`
+**Issue**: `du -h` output format differs between GNU coreutils and BSD; the parsing assumes GNU.
+**Fix sketch**: Add a note in the script header or switch to `wc -c` + manual formatting.
+**Why deferred**: macOS (BSD) is the primary dev platform and tests do not assert exact output.
+
+---
+
+## INFO
+
+### [INFO] SQLite `created_at` omission in UPDATE clarified
+**File**: `bin/ccs-db.ts` (session UPSERT)
+**Issue**: `created_at` is deliberately excluded from the `ON CONFLICT ... DO UPDATE SET ...` clause (only set on INSERT). Future readers may mistake this for an oversight.
+**Fix sketch**: Add a `-- created_at intentionally omitted: preserve original creation time` inline comment.
+**Why deferred**: No functional change; documentation only.
+
+### [INFO] `scanSessions` autocommits per row
+**File**: `bin/ccs-scan.ts` (scanSessions loop)
+**Issue**: Each row INSERT/UPDATE runs as its own implicit transaction. For a full rescan this is measurable overhead compared to batching.
+**Fix sketch**: Wrap the iteration in `db.transaction(() => { for (...) stmt.run(...); })`.
+**Why deferred**: Performance optimization. Requires benchmark-backed tuning; not essential for v0.2.0.
+
+---
+
+## CR3 additions (2026-04-14)
+
+### [LOW] `resolvedDefaultsCommand` stored in config object without origin-site validation
+**File**: `bin/ccs-config.ts:459-460`
+**Issue**: env-sourced `CCS_CMD` is stored in `config.defaults.command` before reaching `resolveRepoEntry`. Current execution path always re-validates via `rejectShellMetachars(command)` at line 337, so no bypass exists, but a caller using `config.defaults.command` directly would get an unvalidated string.
+**Fix sketch**: Validate `envCommand()` return at origin; add regression test.
+**Why deferred**: No exploitable path in current code; defensive-only.
+
+### [LOW] Prepared statements in scanOneRepo compiled per repo
+**File**: `bin/ccs-scan.ts:377-435` (repo_stats upsert, handoff/pending deletes, hInsert, pInsert)
+**Issue**: 5 `db.prepare()` calls inside per-repo transaction callback. 50 repos = 250 compile events per scan.
+**Fix sketch**: Hoist to `scanAllRepos` scope and pass as parameter.
+**Why deferred**: Minor perf win, safe to defer until observed as bottleneck.
+
+### [LOW] Repo name length cap not enforced
+**File**: `bin/ccs-config.ts`
+**Issue**: No upper bound on repo `name` length. JSON.stringify in deleteReposNotIn would faithfully serialize a 10MB name.
+**Fix sketch**: Add `name.length > 200 → ConfigError` in validation.
+**Why deferred**: repos.yml is operator-authored; attack surface is self-inflicted.
+
+### [LOW] REVIEW.md stale re: command: field trust
+**File**: `REVIEW.md`
+**Issue**: Bullet says "trust documented in README" — predates Phase 6 hard rejection.
+**Fix sketch**: Update to "actively rejects shell metacharacters at config load".
+**Why deferred**: Doc sync, not a behavioral defect.
+
+### [LOW] README architecture diagram omits ccs-preview-session.ts
+**File**: `README.md:259`
+**Issue**: Diagram lists only `ccs-preview.ts`; the session preview binary is a separate file.
+**Fix sketch**: Add a line for `ccs-preview-session.ts → preview pane (session conversation head)`.
+**Why deferred**: Cosmetic; backlog item M6 in v0.2.1.
+
+### [LOW] Test file runtime-assembly comment not repeated on all token fakes
+**File**: `test/ccs-secrets.test.ts`
+**Issue**: Comment explaining runtime assembly appears only on Stripe test; future maintainers adding e.g. a GitHub PAT test might hardcode.
+**Fix sketch**: Move comment to describe-block docstring or repeat on each assembly site.
+**Why deferred**: Preventive only.
+
+---
+
+## User-requested features (2026-04-14, to address in v0.2.1)
+
+### [LOW] npm registry publish (`npm install -g claude-code-station`)
+**File**: — (release process, not code)
+**Issue**: The account-free distribution path is DONE — `npm install -g github:indigo-gr/claude-code-station` works (bin/ccs resolves $0 through npm's global-bin symlink, tsx ships as a dependency and is preferred from the package-local node_modules, `files` field set; verified end-to-end via `npm pack` + sandbox-prefix global install). What remains is only publishing to the npm REGISTRY for discoverability/version pinning.
+**Fix sketch**: npm account → claim package name → `npm publish` (repo side is ready); optional release automation.
+**Why deferred**: Pure publish decision. Tracked in `~/.claude/pendings/ccs-npm-registry-publish.md` (owner decision).
+
+### [HIGH] `install.sh --auto-install` — auto-install missing dependencies
+**File**: `install.sh`
+**Issue**: Currently prints missing-dependency hints and asks "Continue anyway? y/N". First-time OSS users need to copy-paste each install command manually.
+**Fix sketch**: New `--auto-install` flag. Detect platform (macOS → brew, Debian/Ubuntu → apt, Fedora → dnf, Arch → pacman). For each missing dep:
+- `node`: `brew install node` / `apt install nodejs npm`
+- `fzf`: `brew install fzf` / `apt install fzf`
+- `tsx`: `npm install -g tsx` (once node is available)
+- `claude`: print installer URL; cannot auto-install
+Prompt once with a summary ("Install: fzf, tsx — proceed? [Y/n]") rather than per-tool.
+**Why deferred**: Nice-to-have. The manual path works; auto is for OSS onboarding polish.
+
+### ~~[MEDIUM] `ccs init --auto-discover`~~ — DONE (2026-06-12, feat/ccs-init-auto-discover)
+Shipped as specced: `bin/ccs-init.ts` (discover / append / scaffold modes) wired
+via the new `ccs init` subcommand. $HOME walk with depth 5 default (`--depth N`),
+hidden+noise dir excludes, stop-at-repo-root (with a $HOME-as-dotfiles-repo
+exception), symlink-safe; candidates dedup against repos.yml, name suggestions
+uniquified; append is comment/format-preserving (yaml parseDocument) with a
+`.bak` backup and full loadConfig() validation rollback. Covered by
+`test/ccs-init.test.ts` + shell tests.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-code-station",
+  "version": "0.2.1",
+  "description": "Claude Code Station — fzf-powered launcher and session picker for Claude Code with multi-repo support and SQLite-backed state cache",
+  "type": "module",
+  "bin": {
+    "ccs": "bin/ccs"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "fzf",
+    "cli",
+    "session",
+    "launcher"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/indigo-gr/claude-code-station.git"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.3.0",
+    "tsx": "^4.19.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}