claude-code-station 0.2.1

package/bin/ccs-init.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env tsx
+/**
+ * ccs-init.ts — repos.yml bootstrap helpers for `ccs init`.
+ *
+ * Three modes, wired by bin/ccs:
+ *   scaffold            ensure ~/.config/ccs/ exists, print where config lives
+ *   discover [--depth N]  walk $HOME for git repos not yet in repos.yml and
+ *                         emit fzf candidate lines: "<name>\t<~/path>"
+ *   append              read selected candidate lines from stdin and append
+ *                         them to repos.yml (comment/format-preserving), with
+ *                         backup + post-write validation rollback
+ *
+ * Spec: docs/v0.2.1-backlog.md "ccs init --auto-discover".
+ */
+
+import { readdir } from "node:fs/promises";
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, relative } from "node:path";
+import { parseDocument, isSeq } from "yaml";
+
+import { ensureConfigDir, getPaths, loadConfig } from "./ccs-config.ts";
+import { hasShellMetachars } from "./ccs-sanitize.ts";
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_DEPTH = 5;
+
+// Non-hidden directories that never contain the user's own repos. Hidden
+// directories (.venv, .cache, .Trash*, .next, ...) are skipped wholesale by
+// the dot rule below, so only visible noise needs listing here.
+const EXCLUDED_DIR_NAMES = new Set([
+  "node_modules",
+  "Library",
+  "Applications",
+  "__pycache__",
+  "dist",
+  "build",
+  "target",
+]);
+
+export interface DiscoverOptions {
+  /** Levels below `home` to descend (default 5). */
+  maxDepth?: number;
+  /** Walk root — overridable for tests (default homedir()). */
+  home?: string;
+}
+
+/**
+ * Find git checkout roots under $HOME. A directory containing a `.git`
+ * entry (dir for normal clones, file for worktrees/submodules) is emitted
+ * and NOT descended into — nested repos inside a found repo are the found
+ * repo's business. Symlinked directories are skipped (cycle safety).
+ *
+ * Exception: the walk root itself ($HOME-as-dotfiles-repo pattern) is
+ * emitted but still descended, otherwise one `.git` at $HOME would mask
+ * every real project below it.
+ */
+export async function discoverGitRepos(
+  opts: DiscoverOptions = {},
+): Promise<string[]> {
+  const home = opts.home ?? homedir();
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const found: string[] = [];
+
+  async function walk(dir: string, depth: number): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // unreadable dir — not ours to report
+    }
+    if (entries.some((e) => e.name === ".git")) {
+      found.push(dir);
+      if (depth > 0) return; // stop at repo roots (root-dir exception above)
+    }
+    if (depth >= maxDepth) return;
+    const subdirs = entries.filter(
+      (e) =>
+        e.isDirectory() &&
+        !e.name.startsWith(".") &&
+        !EXCLUDED_DIR_NAMES.has(e.name),
+    );
+    await Promise.all(subdirs.map((e) => walk(join(dir, e.name), depth + 1)));
+  }
+
+  await walk(home, 0);
+  return found.sort();
+}
+
+// ---------------------------------------------------------------------------
+// Candidate building
+// ---------------------------------------------------------------------------
+
+export interface Candidate {
+  name: string;
+  /** Stored form: "~" or "~/<relative>" so repos.yml stays portable. */
+  path: string;
+}
+
+export interface ExistingConfig {
+  names: Set<string>;
+  /** Resolved absolute repo paths (RepoEntry.path). */
+  paths: Set<string>;
+}
+
+/**
+ * Turn discovered absolute paths into repos.yml candidates: subtract repos
+ * already registered, skip paths the SHELL_METACHARS policy would reject at
+ * load time anyway, suggest names from the directory basename, and uniquify
+ * against existing + already-suggested names ("foo", "foo-2", ...).
+ */
+export function buildCandidates(
+  foundAbsPaths: string[],
+  existing: ExistingConfig,
+  home: string,
+): Candidate[] {
+  const out: Candidate[] = [];
+  const taken = new Set(existing.names);
+  for (const abs of foundAbsPaths) {
+    if (existing.paths.has(abs)) continue;
+    if (hasShellMetachars(abs)) {
+      process.stderr.write(
+        `[ccs-init] skipped (shell metacharacters in path): ${JSON.stringify(abs)}\n`,
+      );
+      continue;
+    }
+    const base = abs === home ? "home" : basename(abs);
+    let name = base;
+    for (let i = 2; taken.has(name); i++) name = `${base}-${i}`;
+    taken.add(name);
+    out.push({
+      name,
+      path: abs === home ? "~" : `~/${relative(home, abs)}`,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// YAML append (comment/format-preserving)
+// ---------------------------------------------------------------------------
+
+/**
+ * Append candidates to the `repos:` sequence of a repos.yml source string.
+ * parseDocument round-trips comments and the user's existing formatting —
+ * never re-serialize the whole config from plain objects.
+ */
+export function appendReposToYaml(
+  source: string,
+  candidates: Candidate[],
+): string {
+  const doc = parseDocument(source);
+  const repos = doc.get("repos", true);
+  if (!isSeq(repos)) {
+    throw new Error("repos.yml: top-level `repos` sequence not found");
+  }
+  for (const c of candidates) {
+    repos.add(doc.createNode({ name: c.name, path: c.path }));
+  }
+  // lineWidth: 0 — never re-fold long lines the user wrote on one line;
+  // flowCollectionPadding: false — keep `tags: [work]`, not `[ work ]`.
+  // Without these, toString() normalizes UNTOUCHED lines (observed on a real
+  // config: every tags entry repadded + a long description folded in two).
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}
+
+/**
+ * Write candidates into repos.yml with a `.bak` backup, then re-run the full
+ * loadConfig() validation. On any validation failure the original file is
+ * restored — `ccs init` must never leave a config the launcher cannot load.
+ */
+export function appendAndValidate(
+  reposYmlPath: string,
+  candidates: Candidate[],
+): void {
+  const source = readFileSync(reposYmlPath, "utf-8");
+  const updated = appendReposToYaml(source, candidates);
+  writeFileSync(reposYmlPath + ".bak", source, { mode: 0o600 });
+  writeFileSync(reposYmlPath, updated, { mode: 0o600 });
+  try {
+    loadConfig();
+  } catch (err) {
+    writeFileSync(reposYmlPath, source, { mode: 0o600 });
+    throw new Error(
+      `[ccs-init] validation failed after append — repos.yml restored (backup kept at .bak): ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseDepth(argv: string[]): number {
+  const i = argv.indexOf("--depth");
+  if (i < 0) return DEFAULT_MAX_DEPTH;
+  const n = parseInt(argv[i + 1] ?? "", 10);
+  if (!Number.isFinite(n) || n < 1 || n > 12) {
+    throw new Error(`[ccs-init] --depth must be an integer 1-12, got: ${argv[i + 1]}`);
+  }
+  return n;
+}
+
+async function cliDiscover(argv: string[]): Promise<number> {
+  const maxDepth = parseDepth(argv);
+  ensureConfigDir();
+  const config = loadConfig(); // throws ConfigError on a broken repos.yml
+  const existing: ExistingConfig = {
+    names: new Set(config.repos.map((r) => r.name)),
+    paths: new Set(config.repos.map((r) => r.path)),
+  };
+  const home = homedir();
+  const found = await discoverGitRepos({ maxDepth, home });
+  const candidates = buildCandidates(found, existing, home);
+  for (const c of candidates) {
+    process.stdout.write(`${c.name}\t${c.path}\n`);
+  }
+  return 0;
+}
+
+async function cliAppend(): Promise<number> {
+  const stdin = readFileSync(0, "utf-8");
+  const candidates: Candidate[] = [];
+  for (const line of stdin.split("\n")) {
+    if (!line.trim()) continue;
+    const tab = line.indexOf("\t");
+    if (tab <= 0) {
+      process.stderr.write(`[ccs-init] malformed candidate line skipped: ${JSON.stringify(line)}\n`);
+      continue;
+    }
+    candidates.push({ name: line.slice(0, tab), path: line.slice(tab + 1) });
+  }
+  if (candidates.length === 0) {
+    process.stderr.write("[ccs-init] nothing selected — repos.yml unchanged\n");
+    return 0;
+  }
+  const paths = getPaths();
+  appendAndValidate(paths.reposYml, candidates);
+  process.stderr.write(
+    `[ccs-init] added ${candidates.length} repo(s) to ${paths.reposYml}\n`,
+  );
+  return 0;
+}
+
+function cliScaffold(): number {
+  ensureConfigDir();
+  const paths = getPaths();
+  process.stdout.write(
+    `Config ready: ${paths.reposYml}\n` +
+      `Edit it directly, or run \`ccs init --auto-discover\` to scan $HOME for git repos.\n`,
+  );
+  return 0;
+}
+
+async function main(): Promise<number> {
+  const mode = process.argv[2] ?? "";
+  const rest = process.argv.slice(3);
+  try {
+    if (mode === "discover") return await cliDiscover(rest);
+    if (mode === "append") return await cliAppend();
+    if (mode === "scaffold") return cliScaffold();
+    process.stderr.write(
+      "Usage: ccs-init.ts <scaffold | discover [--depth N] | append>\n",
+    );
+    return 1;
+  } catch (err) {
+    process.stderr.write(
+      `[ccs-init] ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(
+        `[ccs-init] fatal: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      process.exit(1);
+    },
+  );
+}

package/bin/ccs-list.ts

@@ -0,0 +1,363 @@
+#!/usr/bin/env tsx
+/**
+ * ccs-list.ts — SQL-driven row builder for the ccs fzf launcher (v0.2.0)
+ *
+ * Outputs tab-separated rows for fzf consumption:
+ *   <LABEL>\t<DESCRIPTION>\t<BADGES>\t<KIND>:<KEY>\t<CWD>\t<COMMAND>
+ *
+ * Modes:
+ *   --current-only    sessions whose cwd matches process.cwd()
+ *   --repos-only      only NEW repo rows
+ *   --sessions-only   only RESUME session rows
+ *   (default)         NEW first (alpha), then RESUME (last_activity_at DESC)
+ */
+
+import { homedir } from "node:os";
+import { openDb, getMeta } from "./ccs-db.ts";
+import { getPaths } from "./ccs-config.ts";
+import { SHELL_METACHARS } from "./ccs-sanitize.ts";
+import { truncate, formatRelativeTime, formatDateTime } from "./ccs-utils.ts";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DESC_MAX = 60;
+const BADGES_MAX = 60;
+const KNOWN_INTEGRATION_KEYS = [
+  "plane_project_id",
+  "attio_workspace",
+  "notion_db",
+  "linear_team",
+  "slack_channel",
+  "github_repo",
+  "figma_file",
+];
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+interface Flags {
+  currentOnly: boolean;
+  reposOnly: boolean;
+  sessionsOnly: boolean;
+}
+
+function parseArgs(argv: string[]): Flags {
+  return {
+    currentOnly: argv.includes("--current-only"),
+    reposOnly: argv.includes("--repos-only"),
+    sessionsOnly: argv.includes("--sessions-only"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// truncate / formatRelativeTime / formatDateTime come from ccs-utils.ts —
+// the single source shared with the preview pane (review A-1/A-3/K-8), so
+// list badges and preview text can no longer drift in thresholds or language.
+
+function clipBadges(badges: string[], max: number): string {
+  const out: string[] = [];
+  let len = 0;
+  for (const b of badges) {
+    const add = (out.length === 0 ? 0 : 1) + b.length;
+    if (len + add > max) break;
+    out.push(b);
+    len += add;
+  }
+  return out.join(" ");
+}
+
+function parseCustom(json: string): Record<string, unknown> {
+  try {
+    const v = JSON.parse(json);
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      return v as Record<string, unknown>;
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+function integrationShortNames(custom: Record<string, unknown>): string[] {
+  const names: string[] = [];
+  for (const key of KNOWN_INTEGRATION_KEYS) {
+    if (custom[key] === undefined || custom[key] === null || custom[key] === "") continue;
+    // map key -> short label
+    const short = key
+      .replace(/_project_id$/, "")
+      .replace(/_workspace$/, "")
+      .replace(/_db$/, "")
+      .replace(/_team$/, "")
+      .replace(/_channel$/, "")
+      .replace(/_repo$/, "")
+      .replace(/_file$/, "");
+    names.push(short);
+  }
+  return names;
+}
+
+// ---------------------------------------------------------------------------
+// Row builders
+// ---------------------------------------------------------------------------
+
+interface RepoRowFull {
+  name: string;
+  path: string;
+  description: string;
+  command: string;
+  cwd: string | null;
+  icon: string;
+  disabled: number;
+  scan_enabled: number;
+  custom_json: string;
+  // stats (LEFT JOINed, may be null)
+  is_git: number | null;
+  branch: string | null;
+  uncommitted_insertions: number | null;
+  uncommitted_deletions: number | null;
+  handoff_count: number | null;
+  pending_count: number | null;
+  session_last_at: string | null;
+}
+
+function buildRepoBadges(r: RepoRowFull): string {
+  const badges: string[] = [];
+
+  // scan: false repos keep their last-scanned stats forever — flag the
+  // staleness so the user doesn't read a frozen badge as current state
+  // (audit logic M-2).
+  if (r.scan_enabled === 0) {
+    badges.push(`[scan off]`);
+  }
+
+  if (r.is_git === 1) {
+    const branch = r.branch ?? "?";
+    const ins = r.uncommitted_insertions ?? 0;
+    const del = r.uncommitted_deletions ?? 0;
+    if (ins === 0 && del === 0) {
+      badges.push(`[${branch} clean]`);
+    } else {
+      badges.push(`[${branch} +${ins}/-${del}]`);
+    }
+  }
+
+  if ((r.handoff_count ?? 0) > 0) {
+    badges.push(`[⚠️ handoff×${r.handoff_count}]`);
+  }
+  if ((r.pending_count ?? 0) > 0) {
+    badges.push(`[📝 pending×${r.pending_count}]`);
+  }
+
+  if (r.session_last_at) {
+    const ht = formatRelativeTime(r.session_last_at, "");
+    if (ht) badges.push(`[🔄 ${ht}]`);
+  } else {
+    badges.push(`[💤 未使用]`);
+  }
+
+  const custom = parseCustom(r.custom_json);
+  const names = integrationShortNames(custom).slice(0, 3);
+  if (names.length > 0) {
+    badges.push(`[🔗 ${names.join(",")}]`);
+  }
+
+  return clipBadges(badges, BADGES_MAX);
+}
+
+// Dim vertical bar separator (ANSI 2 = faint) inserted between the label
+// column and the description column to visually distinguish them. fzf is
+// invoked with --ansi so these codes render as styling.
+const LABEL_SEP = " \x1b[2m│\x1b[0m";
+
+function repoToRow(r: RepoRowFull): string {
+  const label = `${r.icon || "📁"} ${r.name}${LABEL_SEP}`;
+  const desc = truncate(r.description || "", DESC_MAX);
+  const badges = buildRepoBadges(r);
+  const cwd = r.cwd && r.cwd.length > 0 ? r.cwd : r.path;
+  const command = r.command || "claude";
+  return [
+    label,
+    desc,
+    badges,
+    `new:${r.name}`,
+    cwd,
+    command,
+  ].join("\t");
+}
+
+interface SessionRowFull {
+  uuid: string;
+  repo_name: string | null;
+  cwd: string;
+  last_activity_at: string;
+  topic: string | null;
+  // from repos (LEFT JOIN)
+  repo_display: string | null;
+  repo_icon: string | null;
+  repo_command: string | null;
+}
+
+function sessionToRow(s: SessionRowFull, defaultCommand: string): string {
+  // Mapped sessions use the registered repo icon + name.
+  // Unmapped sessions get ❓ as a visible reminder: either a one-off run
+  // or a repo that hasn't been added to repos.yml yet.
+  // Ternary tests s.repo_display directly so TS narrows string|null → string
+  // without a non-null assertion.
+  // Unmapped sessions fall back to showing their cwd. That value is gated at
+  // scan time, but route it through truncate() anyway so the label column
+  // gets the same control-char stripping as every other column (audit NEW-1
+  // defense-in-depth; fzf renders this column with --ansi).
+  const displayName = s.repo_display
+    ? s.repo_display
+    : s.cwd
+      ? truncate(s.cwd.replace(homedir(), "~"), DESC_MAX)
+      : "(unknown)";
+  const mapIcon = s.repo_display ? s.repo_icon || "📁" : "❓";
+  const label = `🔄 ${mapIcon} ${displayName}${LABEL_SEP}`;
+  const desc = truncate(s.topic || "", DESC_MAX);
+  const badges = `[${formatDateTime(s.last_activity_at)}]`;
+  // Unmapped sessions fall back to the scan-time resolved default
+  // (defaults.command > CCS_CMD > "claude"), not a hardcoded "claude" — the
+  // documented priority chain applies to every launchable row (review A-8).
+  const command = s.repo_command || defaultCommand;
+  return [
+    label,
+    desc,
+    badges,
+    `resume:${s.uuid}`,
+    s.cwd,
+    command,
+  ].join("\t");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): number {
+  const flags = parseArgs(process.argv.slice(2));
+  const paths = getPaths();
+  // openDb() is called INSIDE the try so that a cold-start failure (state.db
+  // missing before first scan) is caught and rendered as a friendly hint
+  // instead of leaking a raw stack trace to fzf.
+  let close: (() => void) | undefined;
+  try {
+    const handle = openDb(paths.stateDb, { readonly: true, skipMigrate: true });
+    const db = handle.db;
+    close = handle.close;
+
+    const lines: string[] = [];
+
+    const wantRepos = !flags.sessionsOnly && !flags.currentOnly;
+    const wantSessions = !flags.reposOnly;
+
+    if (wantRepos) {
+      const repos = db
+        .prepare(
+          `SELECT r.name, r.path, r.description, r.command, r.cwd, r.icon,
+                  r.disabled, r.scan_enabled, r.custom_json,
+                  s.is_git, s.branch, s.uncommitted_insertions,
+                  s.uncommitted_deletions, s.handoff_count, s.pending_count,
+                  s.session_last_at
+             FROM repos r
+             LEFT JOIN repo_stats s ON s.name = r.name
+            WHERE r.disabled = 0
+            ORDER BY r.name COLLATE NOCASE ASC`,
+        )
+        .all() as RepoRowFull[];
+      for (const r of repos) {
+        lines.push(repoToRow(r));
+      }
+    }
+
+    if (wantSessions) {
+      // Launch-command fallback for unmapped sessions (review A-8), written
+      // by ccs-scan at sync time. getMeta returns null on a schema-v1 cache
+      // that predates the meta table — degrade to "claude". The metachar
+      // check is display-side defense in depth: the value was validated at
+      // config load, but this row is re-executed unquoted by bin/ccs.
+      const metaCommand = getMeta(db, "defaults_command");
+      const defaultCommand =
+        metaCommand && !SHELL_METACHARS.test(metaCommand)
+          ? metaCommand
+          : "claude";
+
+      const filterCwd = flags.currentOnly ? process.cwd() : null;
+      const baseSelect = `SELECT s.uuid, s.repo_name, s.cwd, s.last_activity_at, s.topic,
+                  r.name AS repo_display, r.icon AS repo_icon, r.command AS repo_command
+             FROM sessions s
+             LEFT JOIN repos r ON r.name = s.repo_name`;
+      // --current-only filters in SQL so idx_sessions_cwd is usable
+      // (review A-10). The prefix match is expressed as a half-open range
+      // [cwd + "/", cwd + "0") — "0" is the code point after "/" — because
+      // LIKE is case-insensitive by default and would bypass the index.
+      const rows = (
+        filterCwd
+          ? db
+              .prepare(
+                `${baseSelect}
+            WHERE s.cwd = ? OR (s.cwd >= ? AND s.cwd < ?)
+            ORDER BY s.last_activity_at DESC`,
+              )
+              .all(filterCwd, filterCwd + "/", filterCwd + "0")
+          : db
+              .prepare(`${baseSelect}
+            ORDER BY s.last_activity_at DESC`)
+              .all()
+      ) as SessionRowFull[];
+      const sessionRows: string[] = [];
+      for (const s of rows) {
+        sessionRows.push(sessionToRow(s, defaultCommand));
+      }
+      // Insert a section separator between NEW repos and RESUME sessions
+      // when both are present. The separator row uses KIND=separator so
+      // bin/ccs recognises it and exits cleanly if the user selects it.
+      // Guard uses the explicit wantRepos flag (not lines.length) so future
+      // additions to `lines` before this block can't spuriously trigger it.
+      if (wantRepos && sessionRows.length > 0) {
+        const bar = "─".repeat(20);
+        const label = `\x1b[2m${bar}\x1b[0m \x1b[1;90m Past Sessions \x1b[0m\x1b[2m${bar}\x1b[0m`;
+        lines.push([label, "", "", "separator:-", "", ""].join("\t"));
+      }
+      lines.push(...sessionRows);
+    }
+
+    process.stdout.write(lines.join("\n") + (lines.length > 0 ? "\n" : ""));
+    return 0;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Cold-start case: state.db not yet built by the scanner.
+    // The readonly path in openDb() raises its own "[ccs-db] state.db not
+    // found" message BEFORE better-sqlite3 ever runs (review C-5) — that
+    // pattern must be matched here or the friendly hint below is dead code.
+    // The better-sqlite3 native patterns stay as a guard for races where the
+    // file disappears between the existsSync check and the open.
+    const isMissing =
+      /state\.db not found/i.test(msg) ||
+      /unable to open database file/i.test(msg) ||
+      /database (file )?does not exist/i.test(msg) ||
+      /ENOENT/.test(msg);
+    if (isMissing) {
+      process.stderr.write(
+        "[ccs-list] state.db not found. Run `ccs --refresh` first to build the cache.\n",
+      );
+    } else {
+      process.stderr.write(`[ccs-list] fatal: ${msg}\n`);
+    }
+    return 1;
+  } finally {
+    // close may be undefined if openDb() itself threw before the destructure
+    // completed, so guard against it.
+    close?.();
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main());
+}