claude-code-station 0.2.1

package/bin/ccs-db.ts

@@ -0,0 +1,404 @@
+/**
+ * ccs-db.ts - SQLite initialization & migration module for ccs v0.2.0
+ *
+ * Responsibilities:
+ *   - Open better-sqlite3 connection with secure defaults
+ *   - Apply idempotent schema migrations inside per-migration transactions
+ *   - Provide prepared-statement helpers for repo sync (upsert/list/delete)
+ *
+ * Source of truth: docs/design/sqlite-schema.md
+ */
+
+import Database from "better-sqlite3";
+import { mkdirSync, chmodSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const CURRENT_SCHEMA_VERSION = 2;
+
+export interface DbHandle {
+  db: Database.Database;
+  close(): void;
+}
+
+export interface OpenDbOptions {
+  /** Skip migrate() — useful for hot preview paths on an already-initialized DB. */
+  skipMigrate?: boolean;
+  /** Open the SQLite connection in read-only mode. */
+  readonly?: boolean;
+}
+
+export interface RepoRow {
+  name: string;
+  path: string;
+  description: string;
+  command: string;
+  cwd: string | null;
+  tags_json: string;
+  icon: string;
+  disabled: 0 | 1;
+  scan_enabled: 0 | 1;
+  custom_json: string;
+  config_hash: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface Migration {
+  version: number;
+  up: string;
+}
+
+// ---------------------------------------------------------------------------
+// Migrations
+// ---------------------------------------------------------------------------
+
+const MIGRATION_V1 = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version     INTEGER PRIMARY KEY,
+  applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS repos (
+  name            TEXT PRIMARY KEY,
+  path            TEXT NOT NULL,
+  description     TEXT NOT NULL DEFAULT '',
+  command         TEXT NOT NULL DEFAULT '',
+  cwd             TEXT,
+  tags_json       TEXT NOT NULL DEFAULT '[]',
+  icon            TEXT NOT NULL DEFAULT '📁',
+  disabled        INTEGER NOT NULL DEFAULT 0,
+  scan_enabled    INTEGER NOT NULL DEFAULT 1,
+  custom_json     TEXT NOT NULL DEFAULT '{}',
+  config_hash     TEXT NOT NULL,
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_repos_path ON repos(path);
+CREATE INDEX IF NOT EXISTS idx_repos_disabled ON repos(disabled);
+
+CREATE TABLE IF NOT EXISTS repo_stats (
+  name                   TEXT PRIMARY KEY,
+  is_git                 INTEGER NOT NULL DEFAULT 0,
+  branch                 TEXT,
+  last_commit_hash       TEXT,
+  last_commit_subject    TEXT,
+  last_commit_at         TEXT,
+  uncommitted_files      INTEGER NOT NULL DEFAULT 0,
+  uncommitted_insertions INTEGER NOT NULL DEFAULT 0,
+  uncommitted_deletions  INTEGER NOT NULL DEFAULT 0,
+  handoff_count          INTEGER NOT NULL DEFAULT 0,
+  pending_count          INTEGER NOT NULL DEFAULT 0,
+  claude_room_latest     TEXT,
+  claude_room_latest_at  TEXT,
+  session_count_total    INTEGER NOT NULL DEFAULT 0,
+  session_last_at        TEXT,
+  scanned_at             TEXT NOT NULL DEFAULT (datetime('now')),
+  scan_duration_ms       INTEGER NOT NULL DEFAULT 0,
+  scan_error             TEXT,
+  FOREIGN KEY (name) REFERENCES repos(name) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_repo_stats_scanned_at ON repo_stats(scanned_at);
+CREATE INDEX IF NOT EXISTS idx_repo_stats_session_last_at ON repo_stats(session_last_at DESC);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  uuid             TEXT PRIMARY KEY,
+  repo_name        TEXT,
+  project_dir      TEXT NOT NULL,
+  cwd              TEXT NOT NULL,
+  branch           TEXT,
+  started_at       TEXT NOT NULL,
+  last_activity_at TEXT NOT NULL,
+  message_count    INTEGER NOT NULL DEFAULT 0,
+  topic            TEXT,
+  summary          TEXT,
+  jsonl_size       INTEGER NOT NULL DEFAULT 0,
+  jsonl_mtime      TEXT NOT NULL,
+  indexed_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (repo_name) REFERENCES repos(name) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_repo ON sessions(repo_name, last_activity_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_last_activity ON sessions(last_activity_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
+
+CREATE TABLE IF NOT EXISTS handoff_files (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_name  TEXT NOT NULL,
+  filename   TEXT NOT NULL,
+  size       INTEGER NOT NULL DEFAULT 0,
+  mtime      TEXT NOT NULL,
+  first_line TEXT,
+  FOREIGN KEY (repo_name) REFERENCES repos(name) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_handoff_repo ON handoff_files(repo_name, mtime DESC);
+
+CREATE TABLE IF NOT EXISTS pending_items (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_name  TEXT NOT NULL,
+  filename   TEXT NOT NULL,
+  size       INTEGER NOT NULL DEFAULT 0,
+  mtime      TEXT NOT NULL,
+  first_line TEXT,
+  FOREIGN KEY (repo_name) REFERENCES repos(name) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_pending_repo ON pending_items(repo_name, mtime DESC);
+`;
+
+// v2: key/value store for scan-time resolved settings. First consumer is
+// `defaults_command` — the resolved launch-command fallback (defaults.command
+// > CCS_CMD > "claude") that ccs-list needs for sessions not mapped to any
+// repo (review A-8). ccs-list opens the DB readonly+skipMigrate, so it must
+// tolerate this table being absent on a not-yet-migrated cache (getMeta).
+const MIGRATION_V2 = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+
+const migrations: Migration[] = [
+  { version: 1, up: MIGRATION_V1 },
+  { version: 2, up: MIGRATION_V2 },
+  // future: { version: 3, up: `...` },
+];
+
+// ---------------------------------------------------------------------------
+// Migration runner
+// ---------------------------------------------------------------------------
+
+export function getCurrentSchemaVersion(db: Database.Database): number {
+  const row = db
+    .prepare(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'`,
+    )
+    .get() as { name?: string } | undefined;
+  if (!row) return 0;
+  const v = db
+    .prepare(`SELECT MAX(version) AS v FROM schema_version`)
+    .get() as { v: number | null } | undefined;
+  return v?.v ?? 0;
+}
+
+export function migrate(db: Database.Database): void {
+  const current = getCurrentSchemaVersion(db);
+  const pending = migrations.filter((m) => m.version > current);
+  for (const m of pending) {
+    try {
+      db.transaction(() => {
+        db.exec(m.up);
+        db.prepare(`INSERT INTO schema_version (version) VALUES (?)`).run(
+          m.version,
+        );
+      })();
+      process.stderr.write(`[ccs] applied migration v${m.version}\n`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`[ccs-db] migration v${m.version} failed: ${msg}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Open / close
+// ---------------------------------------------------------------------------
+
+export function openDb(
+  stateDbPath: string,
+  opts: OpenDbOptions = {},
+): DbHandle {
+  const readOnly = opts.readonly === true;
+
+  if (readOnly) {
+    if (!existsSync(stateDbPath)) {
+      throw new Error(
+        `[ccs-db] state.db not found at ${stateDbPath} — run \`ccs --refresh\` first`,
+      );
+    }
+  } else {
+    // Ensure parent directory exists with restrictive permissions.
+    const parent = dirname(stateDbPath);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+  }
+
+  const db = readOnly
+    ? new Database(stateDbPath, { readonly: true })
+    : new Database(stateDbPath);
+
+  // PRAGMAs: foreign keys must be ON before migrations.
+  // journal_mode/synchronous are session-scoped write pragmas — skip on readonly.
+  if (!readOnly) {
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    // Scan-workload throughput pragmas (backlog: PRAGMA tuning). Negative
+    // cache_size is KiB (≈8MB page cache); temp_store=MEMORY keeps sort/temp
+    // b-trees off disk; mmap_size lets reads go through the page cache
+    // mapping (64MB ≫ any ccs-sized DB). All session-scoped, write path only.
+    db.pragma("cache_size = -8000");
+    db.pragma("temp_store = MEMORY");
+    db.pragma("mmap_size = 67108864");
+  }
+  db.pragma("foreign_keys = ON");
+  // WAL allows one writer at a time; concurrent `--force` scans (Ctrl-R right
+  // after `ccs --refresh`, or two terminals) would otherwise fail immediately
+  // with SQLITE_BUSY (audit NEW-4). 3s is ample for ccs-sized transactions.
+  db.pragma("busy_timeout = 3000");
+
+  if (!readOnly) {
+    // Tighten file permissions, including WAL side files which inherit the
+    // main DB's content. Best-effort, but a failure is no longer silent
+    // (audit L-4): on umask-hostile or foreign filesystems the cache may stay
+    // group/world-readable, and the user should know.
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const p = stateDbPath + suffix;
+      if (suffix !== "" && !existsSync(p)) continue;
+      try {
+        chmodSync(p, 0o600);
+      } catch {
+        process.stderr.write(
+          `[ccs-db] warning: could not chmod 0600 ${p} — cache may be readable by other users\n`,
+        );
+      }
+    }
+  }
+
+  if (!opts.skipMigrate && !readOnly) {
+    migrate(db);
+  }
+
+  return {
+    db,
+    close() {
+      try {
+        // Passive checkpoint flushes WAL pages back to the main DB without
+        // blocking other readers. Safe to ignore errors (checkpoint is hygiene,
+        // not correctness). Readonly connections cannot checkpoint — skip.
+        if (!readOnly) {
+          db.pragma("wal_checkpoint(PASSIVE)");
+        }
+      } catch {
+        // ignore
+      }
+      db.close();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Repo helpers (used by ccs-scan.ts to sync repos.yml -> DB)
+// ---------------------------------------------------------------------------
+
+type RepoInsert = Omit<RepoRow, "created_at" | "updated_at">;
+
+export function upsertRepo(db: Database.Database, row: RepoInsert): void {
+  // Update updated_at only when config_hash changes; created_at is preserved
+  // on conflict via excluded.created_at being ignored.
+  const stmt = db.prepare(`
+    INSERT INTO repos (
+      name, path, description, command, cwd, tags_json, icon,
+      disabled, scan_enabled, custom_json, config_hash,
+      created_at, updated_at
+    ) VALUES (
+      @name, @path, @description, @command, @cwd, @tags_json, @icon,
+      @disabled, @scan_enabled, @custom_json, @config_hash,
+      datetime('now'), datetime('now')
+    )
+    ON CONFLICT(name) DO UPDATE SET
+      path         = excluded.path,
+      description  = excluded.description,
+      command      = excluded.command,
+      cwd          = excluded.cwd,
+      tags_json    = excluded.tags_json,
+      icon         = excluded.icon,
+      disabled     = excluded.disabled,
+      scan_enabled = excluded.scan_enabled,
+      custom_json  = excluded.custom_json,
+      config_hash  = excluded.config_hash,
+      updated_at   = CASE
+        WHEN repos.config_hash != excluded.config_hash
+          THEN datetime('now')
+        ELSE repos.updated_at
+      END
+  `);
+  stmt.run(row);
+}
+
+export function getAllRepos(db: Database.Database): RepoRow[] {
+  return db
+    .prepare(
+      `SELECT name, path, description, command, cwd, tags_json, icon,
+              disabled, scan_enabled, custom_json, config_hash,
+              created_at, updated_at
+       FROM repos
+       ORDER BY name`,
+    )
+    .all() as RepoRow[];
+}
+
+/**
+ * Delete a single session row by UUID using a bound parameter.
+ *
+ * Exists so shell callers (ccs-delete.sh via ccs-delete-session.ts) never
+ * have to assemble SQL strings themselves (audit M-3 — the old sqlite3 CLI
+ * one-liner interpolated the UUID into the statement; safe only as long as
+ * the upstream regex gate held).
+ *
+ * Returns the number of rows removed (0 when the UUID was not cached).
+ */
+export function deleteSession(db: Database.Database, uuid: string): number {
+  const res = db.prepare(`DELETE FROM sessions WHERE uuid = ?`).run(uuid);
+  return res.changes;
+}
+
+/** Upsert one key into the meta table (schema v2). */
+export function setMeta(
+  db: Database.Database,
+  key: string,
+  value: string,
+): void {
+  db.prepare(
+    `INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+  ).run(key, value);
+}
+
+/**
+ * Read one key from the meta table. Returns null when the key is absent OR
+ * when the table itself does not exist yet — readonly/skipMigrate consumers
+ * (ccs-list) can hit a schema-v1 cache that predates migration v2, and a
+ * missing setting must degrade to the caller's default, not crash the list.
+ */
+export function getMeta(db: Database.Database, key: string): string | null {
+  try {
+    const row = db
+      .prepare(`SELECT value FROM meta WHERE key = ?`)
+      .get(key) as { value: string } | undefined;
+    return row?.value ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function deleteReposNotIn(
+  db: Database.Database,
+  names: string[],
+): number {
+  if (names.length === 0) {
+    // Preserve existing semantic: empty array deletes all repos.
+    const res = db.prepare(`DELETE FROM repos`).run();
+    return res.changes;
+  }
+  // Use json_each(JSON array) to avoid SQLite's 999-variable bind limit
+  // when syncing large numbers of repos. JSON1 is default-enabled since
+  // SQLite 3.38 (bundled with better-sqlite3).
+  const res = db
+    .prepare(
+      `DELETE FROM repos
+       WHERE name NOT IN (SELECT value FROM json_each(?))`,
+    )
+    .run(JSON.stringify(names));
+  return res.changes;
+}

package/bin/ccs-delete-session.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+/**
+ * ccs-delete-session.ts — Remove one session row from the state cache.
+ *
+ * Invoked by ccs-delete.sh after the JSONL file has been deleted, so the
+ * stale row disappears from the fzf list on the next reload. Uses a bound
+ * parameter via ccs-db.ts (audit M-3) instead of interpolating the UUID into
+ * a sqlite3 CLI string.
+ *
+ * Usage: tsx ccs-delete-session.ts <session-uuid>
+ * Exit codes: 0 = row deleted or not present, 1 = bad args / DB failure.
+ */
+
+import { existsSync } from "node:fs";
+import { getPaths } from "./ccs-config.ts";
+import { openDb, deleteSession } from "./ccs-db.ts";
+import { UUID_RE } from "./ccs-utils.ts";
+
+function main(): number {
+  const uuid = process.argv[2] ?? "";
+  if (!UUID_RE.test(uuid)) {
+    process.stderr.write("[ccs-delete-session] invalid session UUID\n");
+    return 1;
+  }
+
+  const paths = getPaths();
+  if (!existsSync(paths.stateDb)) {
+    // No cache, nothing to clean up.
+    return 0;
+  }
+
+  try {
+    const handle = openDb(paths.stateDb, { skipMigrate: true });
+    try {
+      deleteSession(handle.db, uuid);
+    } finally {
+      handle.close();
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(
+      `[ccs-delete-session] ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+}
+
+process.exit(main());

package/bin/ccs-delete.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# ccs-delete.sh - Delete a Claude Code session file with confirmation
+# Args: sessionId
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Same package-local tsx preference as bin/ccs (npm / copy install layouts);
+# this script is invoked by path (never symlinked), so no $0 resolution here.
+if [[ -x "${SCRIPT_DIR}/../node_modules/.bin/tsx" ]]; then
+  TSX="${SCRIPT_DIR}/../node_modules/.bin/tsx"
+elif [[ -x "${SCRIPT_DIR}/node_modules/.bin/tsx" ]]; then
+  TSX="${SCRIPT_DIR}/node_modules/.bin/tsx"
+else
+  TSX="tsx"
+fi
+
+SESSION_ID="${1:-}"
+UUID_RE='^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+
+# bash renders `read -p` prompts only when stdin is a TTY — with piped stdin
+# (tests, scripted use) the prompt silently vanishes. Print prompts to stderr
+# explicitly so they are always visible; in a TTY this looks identical, since
+# `read -p` writes to stderr too.
+prompt_read() { # prompt_read <prompt> [varname]
+  printf '%s' "$1" >&2
+  IFS= read -r "${2:-REPLY}"
+}
+
+if [[ -z "$SESSION_ID" ]] || [[ ! "$SESSION_ID" =~ $UUID_RE ]]; then
+  echo "❌ Invalid session ID"
+  prompt_read "Press Enter to continue..."
+  exit 1
+fi
+
+PROJECTS_DIR="$HOME/.claude/projects"
+TARGET=""
+
+for dir in "$PROJECTS_DIR"/*/; do
+  FILE="${dir}${SESSION_ID}.jsonl"
+  if [[ -f "$FILE" ]]; then
+    TARGET="$FILE"
+    break
+  fi
+done
+
+if [[ -z "$TARGET" ]]; then
+  echo "❌ Session file not found"
+  prompt_read "Press Enter to continue..."
+  exit 1
+fi
+
+# Show file info. du can fail if the file vanishes between the find loop and
+# here (concurrent cleanup) — under `set -e` that would kill the script with
+# no message, so fall back to "?" instead.
+SIZE=$(du -h "$TARGET" 2>/dev/null | cut -f1 || echo "?")
+echo "━━━ Delete Session ━━━"
+echo "📄 $TARGET"
+echo "📏 $SIZE"
+echo ""
+prompt_read "Delete this session? (y/N): " confirm
+
+if [[ "$confirm" == "y" || "$confirm" == "Y" ]]; then
+  # Wrap rm explicitly: under `set -e` a bare rm failure (permissions, file
+  # gone) would exit the script before the trailing "Press Enter" prompt, so
+  # the fzf execute pane closes with no message and the user has no way to
+  # know the delete failed (review C-2).
+  if ! rm "$TARGET"; then
+    echo "❌ Failed to delete: $TARGET" >&2
+    prompt_read "Press Enter to continue..."
+    exit 1
+  fi
+  # Also remove subagents directory if it exists. The final-form check is a
+  # defensive guard on the rm -rf argument: it must still look like
+  # <projects>/<dir>/<validated-uuid> at deletion time (audit L-2).
+  SUBAGENT_DIR="${PROJECTS_DIR}/$(basename "$(dirname "$TARGET")")/${SESSION_ID}"
+  if [[ -d "$SUBAGENT_DIR" && "$SUBAGENT_DIR" == "$PROJECTS_DIR/"*"/$SESSION_ID" ]]; then
+    if ! rm -rf "$SUBAGENT_DIR"; then
+      # Main JSONL is already gone — report and continue to cache cleanup.
+      echo "[ccs] warning: could not remove subagent dir: $SUBAGENT_DIR" >&2
+    fi
+  fi
+  # Remove the stale row from the SQLite cache so the session disappears
+  # from the fzf list immediately on reload (Ctrl-D → +reload). Uses a bound
+  # parameter via better-sqlite3 (audit M-3) and reports failures instead of
+  # swallowing them (audit L-3).
+  if [[ "$TSX" != "tsx" ]] || command -v tsx &>/dev/null; then
+    if ! "${TSX}" "${SCRIPT_DIR}/ccs-delete-session.ts" "$SESSION_ID"; then
+      echo "[ccs] warning: cache row cleanup failed — a stale row may remain until the next refresh" >&2
+    fi
+  else
+    echo "[ccs] warning: tsx not found — cache row not removed (run ccs --refresh)" >&2
+  fi
+  echo "✅ Deleted"
+else
+  echo "Cancelled"
+fi
+
+prompt_read "Press Enter to continue..."