@indigo-gr/claude-code-station 0.3.3 → 0.5.0

package/bin/ccs-scan.ts

@@ -15,7 +15,7 @@
 
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { open, readdir, stat } from "node:fs/promises";
+import { open, readdir, realpath, stat } from "node:fs/promises";
 import {
   closeSync,
   existsSync,
@@ -28,6 +28,7 @@ import { join } from "node:path";
 import type Database from "better-sqlite3";
 
 import { loadConfig, getPaths, type RepoEntry } from "./ccs-config.ts";
+import { groupsToMeta, readLogicalGroups } from "./ccs-groups.ts";
 import {
   openDb,
   upsertRepo,
@@ -40,6 +41,7 @@ import { maskSecrets } from "./ccs-secrets.ts";
 import { stripControlChars } from "./ccs-sanitize.ts";
 import { nowIso, type UiMode } from "./ccs-utils.ts";
 import { scanSessions } from "./ccs-scan-sessions.ts";
+import { pathToFileURL } from "node:url";
 
 const execFileP = promisify(execFile);
 
@@ -52,6 +54,12 @@ export interface ScanOptions {
   ttlSeconds?: number;
   parallelism?: number;
   scanSessions?: boolean;
+  /**
+   * The machine interface's scan (`ccs sessions`): repos.yml is read without
+   * scaffolding (no template, no README; only the cache dir) and its
+   * warnings are not printed.
+   */
+  quietConfig?: boolean;
 }
 
 export interface ScanResult {
@@ -65,6 +73,8 @@ export interface ScanResult {
   lockSkipped?: boolean;
   /** repos.yml `defaults.ui` as loaded by this run (set even when lock-skipped). */
   ui?: UiMode;
+  /** repos.yml `defaults.update_check` (set even when lock-skipped). */
+  updateCheck?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -81,12 +91,25 @@ const PREVIEW_FILE_LIMIT = 10;
 // Utilities
 // ---------------------------------------------------------------------------
 
+const SAFE_GIT_ARGS = [
+  "--no-optional-locks",
+  "-c",
+  "diff.autoRefreshIndex=false",
+  "-c",
+  "core.fsmonitor=false",
+  "-c",
+  "core.hooksPath=/dev/null",
+];
+
 async function runGit(
   cwd: string,
   args: string[],
 ): Promise<{ stdout: string; stderr: string } | null> {
   try {
-    const res = await execFileP("git", args, {
+    // A repo's own .git/config can name programs. These are the ones a scan
+    // would run: an fsmonitor, and the post-index-change hook when status or
+    // diff rewrites the index. A scan only reads, so neither rewrites it.
+    const res = await execFileP("git", [...SAFE_GIT_ARGS, ...args], {
       cwd,
       timeout: GIT_TIMEOUT_MS,
       maxBuffer: 4 * 1024 * 1024,
@@ -216,12 +239,24 @@ async function readFirstLine(filePath: string): Promise<string | null> {
   }
 }
 
+/** A symlink is followed only when it ends up inside the repo. */
+async function realPathInside(path: string, realRoot: string): Promise<string | null> {
+  const real = await realpath(path);
+  return real === realRoot || real.startsWith(`${realRoot}/`) ? real : null;
+}
+
 async function listDirPreview(
   dirPath: string,
+  repoPath: string,
 ): Promise<{ count: number; previews: PreviewFile[] }> {
   if (!existsSync(dirPath)) return { count: 0, previews: [] };
   let entries: string[];
+  let realRoot: string;
   try {
+    realRoot = await realpath(repoPath);
+    if ((await realPathInside(dirPath, realRoot)) === null) {
+      return { count: 0, previews: [] };
+    }
     entries = await readdir(dirPath);
   } catch {
     return { count: 0, previews: [] };
@@ -230,8 +265,9 @@ async function listDirPreview(
 
   const results = await Promise.all(
     visible.map(async (name): Promise<PreviewFile | null> => {
-      const full = join(dirPath, name);
       try {
+        const full = await realPathInside(join(dirPath, name), realRoot);
+        if (full === null) return null;
         const st = await stat(full);
         if (!st.isFile()) return null;
         const line = await readFirstLine(full);
@@ -391,11 +427,11 @@ async function scanOneRepo(
     }
 
     // --- Workspace dirs ---
-    const handoff = await listDirPreview(join(repo.path, "handoff"));
+    const handoff = await listDirPreview(join(repo.path, "handoff"), repo.path);
     stats.handoff_count = handoff.count;
     handoffPreviews = handoff.previews;
 
-    const pending = await listDirPreview(join(repo.path, "pendings"));
+    const pending = await listDirPreview(join(repo.path, "pendings"), repo.path);
     stats.pending_count = pending.count;
     pendingPreviews = pending.previews;
 
@@ -626,8 +662,11 @@ export async function scan(opts: ScanOptions = {}): Promise<ScanResult> {
   const parallelism = opts.parallelism ?? DEFAULT_PARALLELISM;
   const scanSessionsFlag = opts.scanSessions ?? true;
 
-  // loadConfig() runs ensureConfigDir(), so cacheDir exists before the lock.
-  const config = loadConfig();
+  // loadConfig() runs ensureConfigDir() (or, quiet, creates the cache dir),
+  // so cacheDir exists before the lock.
+  const config = opts.quietConfig
+    ? loadConfig({ scaffold: false, sink: () => {} })
+    : loadConfig();
   const paths = getPaths();
 
   const releaseLock = acquireScanLock(paths.cacheDir);
@@ -644,10 +683,19 @@ export async function scan(opts: ScanOptions = {}): Promise<ScanResult> {
       durationMs: Date.now() - started,
       lockSkipped: true,
       ui: config.defaults.ui,
+      updateCheck: config.settings.updateCheck,
     };
   }
 
-  const handle = openDb(paths.stateDb);
+  // A DB that cannot open must not leave the lock behind: every later scan
+  // would say "another scan is in progress" and hide the real error.
+  let handle: ReturnType<typeof openDb>;
+  try {
+    handle = openDb(paths.stateDb);
+  } catch (err) {
+    releaseLock();
+    throw err;
+  }
 
   try {
     syncReposToDb(handle.db, config.repos);
@@ -658,6 +706,16 @@ export async function scan(opts: ScanOptions = {}): Promise<ScanResult> {
     // repos.yml `defaults.ui`, for the `ccs --no-scan` path (bin/ccs reads it
     // back through `ccs-list --print-ui` when no scan ran this launch).
     setMeta(handle.db, "defaults_ui", config.defaults.ui);
+    // repos.yml `defaults.update_check`, read back the same way (`ccs-list
+    // --print-settings`) when no scan ran this launch.
+    setMeta(handle.db, "defaults_update_check", config.settings.updateCheck ? "on" : "off");
+    // defaults.groups_dir: the logical groups, matched to repos.yml by path,
+    // for the list to read (an empty list when the setting is off, so
+    // removing it clears the headers).
+    const groups = config.settings.groupsDir
+      ? readLogicalGroups(config.settings.groupsDir, config.repos).groups
+      : [];
+    setMeta(handle.db, "logical_groups", groupsToMeta(groups));
 
     // Order matters (audit C-1): scanOneRepo aggregates session counts FROM
     // the sessions table, so sessions must be refreshed first — otherwise
@@ -686,6 +744,7 @@ export async function scan(opts: ScanOptions = {}): Promise<ScanResult> {
       sessionsSkipped,
       durationMs: Date.now() - started,
       ui: config.defaults.ui,
+      updateCheck: config.settings.updateCheck,
     };
   } finally {
     handle.close();
@@ -702,12 +761,14 @@ function parseArgs(argv: string[]): {
   noSessions: boolean;
   quiet: boolean;
   printUi: boolean;
+  printSettings: boolean;
 } {
   return {
     force: argv.includes("--force"),
     noSessions: argv.includes("--no-sessions"),
     quiet: argv.includes("--quiet"),
     printUi: argv.includes("--print-ui"),
+    printSettings: argv.includes("--print-settings"),
   };
 }
 
@@ -733,7 +794,15 @@ async function main(): Promise<{ code: number; out: string }> {
           `(${res.sessionsSkipped} cached) in ${secs}s\n`,
       );
     }
-    return { code: 0, out: args.printUi && res.ui ? `ui=${res.ui}\n` : "" };
+    // --print-settings: `ui=` and `update_check=` (bin/ccs's pre-scan);
+    // --print-ui: `ui=` alone, as before.
+    let out = "";
+    if (args.printSettings && res.ui) {
+      out = `ui=${res.ui}\nupdate_check=${res.updateCheck === false ? "off" : "on"}\n`;
+    } else if (args.printUi && res.ui) {
+      out = `ui=${res.ui}\n`;
+    }
+    return { code: 0, out };
   } catch (err) {
     process.stderr.write(
       `[ccs-scan] fatal: ${err instanceof Error ? err.message : String(err)}\n`,
@@ -742,7 +811,9 @@ async function main(): Promise<{ code: number; out: string }> {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// pathToFileURL, not `file://${argv[1]}`: a folder with a space (or any
+// character a URL escapes) in its name would never match.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
   main().then(
     ({ code, out }) => {
       // Exit only after stdout drained: pipe writes are async on macOS, and

package/bin/ccs-sessions.ts

@@ -0,0 +1,174 @@
+/**
+ * ccs-sessions.ts — `ccs sessions --json [--project <name>] [--limit <n>]
+ * [--with-titles] [--no-scan]`.
+ *
+ * Past conversations per project, newest first, at most --limit each. Only
+ * what a screen needs to offer "resume": the project's name, the time, the
+ * UUID to hand to `ccs open --session`, and (only with --with-titles) the
+ * first request's one line. Never the summary, the working folder, the
+ * branch or the conversation itself. Contract:
+ * docs/design/machine-interface.md 2.3.
+ *
+ * Before reading, the same incremental scan the list runs refreshes the cache
+ * (not with --no-scan, not without a repos.yml). Its stderr is held: the
+ * scan's lines can name repos and paths.
+ */
+
+import { existsSync } from "node:fs";
+
+import { getPaths, readConfig } from "./ccs-config.ts";
+import {
+  cliOutcome,
+  configFailure,
+  okOutcome,
+  parseFlags,
+  type Outcome,
+} from "./ccs-machine.ts";
+import { maskSecrets } from "./ccs-secrets.ts";
+import { stripControlChars } from "./ccs-sanitize.ts";
+
+const LIMIT_DEFAULT = 5;
+const LIMIT_MAX = 50;
+const TITLE_MAX = 80;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** One line, no control or reordering characters, at most 80 code points (+ …). */
+export function sessionTitle(topic: string | null): string | null {
+  if (topic === null) return null;
+  const clean = stripControlChars(maskSecrets(stripControlChars(topic)));
+  if (clean === "") return null;
+  const points = [...clean];
+  return points.length > TITLE_MAX ? points.slice(0, TITLE_MAX).join("") + "…" : clean;
+}
+
+function isoOrNull(value: string | null): string | null {
+  if (!value) return null;
+  const t = Date.parse(value);
+  return Number.isNaN(t) ? null : new Date(t).toISOString();
+}
+
+/** Run the list's scan in this process with stderr and console.warn held back. */
+async function quietScan(): Promise<boolean> {
+  const write = process.stderr.write;
+  const warn = console.warn;
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+  console.warn = () => {};
+  try {
+    const { scan } = await import("./ccs-scan.ts");
+    const res = await scan({ quietConfig: true });
+    return !res.lockSkipped;
+  } catch {
+    return false;
+  } finally {
+    process.stderr.write = write;
+    console.warn = warn;
+  }
+}
+
+interface Row {
+  uuid: string;
+  repo_name: string | null;
+  last_activity_at: string | null;
+  topic: string | null;
+  mapped: number;
+  disabled: number | null;
+}
+
+export async function sessionsOutcome(args: readonly string[]): Promise<Outcome> {
+  const flags = parseFlags(args, {
+    booleans: ["--json", "--with-titles", "--no-scan"],
+    values: ["--project", "--limit"],
+  });
+  if (!flags.ok) return cliOutcome(flags.code);
+  if (flags.positionals.length > 0 || flags.rest.length > 0) return cliOutcome("extra_argument");
+  if (!flags.booleans.has("--json")) {
+    return cliOutcome("json_required", {}, "`ccs sessions` needs --json (to pick a conversation by hand, run ccs --resume)");
+  }
+  let limit = LIMIT_DEFAULT;
+  const rawLimit = flags.values.get("--limit");
+  if (rawLimit !== undefined) {
+    if (!/^[0-9]{1,3}$/.test(rawLimit) || Number(rawLimit) < 1 || Number(rawLimit) > LIMIT_MAX) {
+      return cliOutcome("invalid_argument", {}, `--limit takes 1–${LIMIT_MAX}`);
+    }
+    limit = Number(rawLimit);
+  }
+  const project = flags.values.get("--project");
+  const withTitles = flags.booleans.has("--with-titles");
+  const paths = getPaths();
+
+  // --project must name an entry of repos.yml as it is now.
+  if (project !== undefined) {
+    try {
+      const result = readConfig();
+      if (!result.found) {
+        return cliOutcome("config_missing", {}, "no repos.yml yet (config_missing)");
+      }
+      if (!result.config.repos.some((r) => r.name === project)) {
+        return cliOutcome("repo_not_found");
+      }
+    } catch (err) {
+      return configFailure(err);
+    }
+  }
+
+  let fresh = false;
+  if (!flags.booleans.has("--no-scan") && existsSync(paths.reposYml)) {
+    fresh = await quietScan();
+  }
+
+  if (!existsSync(paths.stateDb)) {
+    return cliOutcome("cache_missing", {}, "no cache yet (cache_missing); open the list once, or run ccs --refresh");
+  }
+  let rows: Row[];
+  try {
+    const { openDb } = await import("./ccs-db.ts");
+    const handle = openDb(paths.stateDb, { readonly: true, skipMigrate: true });
+    try {
+      rows = handle.db
+        .prepare(
+          `SELECT s.uuid, s.repo_name, s.last_activity_at, s.topic,
+                  (r.name IS NOT NULL) AS mapped, r.disabled
+             FROM sessions s
+             LEFT JOIN repos r ON r.name = s.repo_name
+            ORDER BY s.last_activity_at DESC`,
+        )
+        .all() as Row[];
+    } finally {
+      handle.db.close();
+    }
+  } catch {
+    return cliOutcome("cache_not_readable", {}, "cannot open the cache (cache_not_readable)");
+  }
+
+  let unmapped = 0;
+  const byProject = new Map<string, Row[]>();
+  for (const row of rows) {
+    if (!UUID_RE.test(row.uuid)) continue;
+    if (!row.mapped || !row.repo_name) {
+      unmapped++;
+      continue;
+    }
+    if (row.disabled) continue;
+    if (project !== undefined && row.repo_name !== project) continue;
+    const list = byProject.get(row.repo_name) ?? [];
+    list.push(row);
+    byProject.set(row.repo_name, list);
+  }
+
+  // Rows come newest first, so the Map's insertion order is already the
+  // projects' order by their newest conversation.
+  const projects = [...byProject.entries()].map(([name, list]) => ({
+    name,
+    sessions: list.slice(0, limit).map((s) => {
+      const item: Record<string, unknown> = {
+        uuid: s.uuid,
+        last_activity_at: isoOrNull(s.last_activity_at),
+      };
+      if (withTitles) item.title = sessionTitle(s.topic);
+      return item;
+    }),
+    more: Math.max(0, list.length - limit),
+  }));
+
+  return okOutcome({ stale: !fresh, limit, projects, unmapped });
+}

package/bin/ccs-tsx.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# ccs-tsx.sh — start a ccs module with tsx from ccs's own folder.
+#
+# Usage (from bin/ccs, the fzf bindings and ccs-delete.sh):
+#   CCS_TSX_REAL=<tsx> bash ccs-tsx.sh <module.ts> [args…]
+#
+# Node resolves tsx's preload (--require) from the CURRENT folder and reads
+# the nearest package.json above it on the way; a package.json there that
+# Node cannot parse stops every module before it starts, even though ccs's
+# own files are fine. So the module runs from the folder holding these
+# scripts, and the folder the user ran ccs in is passed on in CCS_CWD (read
+# where it matters: `ccs .` and `ccs repo add <relative path>`).
+set -euo pipefail
+export CCS_CWD="${CCS_CWD:-$PWD}"
+cd "$(dirname "${BASH_SOURCE[0]}")"
+exec "${CCS_TSX_REAL:-tsx}" "$@"

package/bin/ccs-update-check.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env tsx
+/**
+ * ccs-update-check.ts — ask the npm registry for the package's latest version
+ * and remember the answer for bin/ccs.
+ *
+ * bin/ccs starts this in the background (at most once a day) and never waits
+ * for it: the launcher only reads the cache this file writes, so a slow or
+ * missing network cannot delay or stop the picker. Nothing is printed and the
+ * exit code is always 0.
+ *
+ * Sent: one HTTPS GET for the package's public dist-tags. No ccs version, repo,
+ * session or machine details are in it.
+ *
+ * Cache: <cacheDir>/update-check, two key=value lines:
+ *   latest=<X.Y.Z, or empty when the registry's latest is not a plain release>
+ *   checked=<unix seconds>
+ * The registry's answer is untrusted text that ends up in a terminal and in an
+ * fzf option, so only a plain X.Y.Z is ever stored. bin/ccs validates the file
+ * again when it reads it.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getPaths } from "./ccs-config.ts";
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const REQUEST_TIMEOUT_MS = 3_000;
+const HARD_EXIT_MS = 5_000;
+// bin/ccs asks again once `checked` is a day old (UPDATE_INTERVAL there). A
+// failed attempt is back-dated so the next try comes after an hour, not a day.
+const CHECK_INTERVAL_S = 86_400;
+const RETRY_AFTER_FAILURE_S = 3_600;
+
+const PLAIN_RELEASE = /^[0-9]{1,9}\.[0-9]{1,9}\.[0-9]{1,9}$/;
+
+export function isPlainRelease(version: unknown): version is string {
+  return typeof version === "string" && PLAIN_RELEASE.test(version);
+}
+
+/** Registry base URL: CCS_UPDATE_REGISTRY when it is http(s), else npm's. */
+export function registryBase(value: string | undefined): string {
+  if (value && /^https?:\/\/[^\s]+$/.test(value)) return value.replace(/\/+$/, "");
+  return DEFAULT_REGISTRY;
+}
+
+export function distTagsUrl(base: string, pkg: string): string {
+  return `${base}/-/package/${encodeURIComponent(pkg)}/dist-tags`;
+}
+
+/**
+ * The version the cache should hold after a successful answer: a plain release,
+ * or "" when `latest` is a prerelease. Throws on an answer with no usable
+ * `latest` (treated like a failed request).
+ */
+export function latestFromDistTags(body: unknown): string {
+  if (typeof body !== "object" || body === null) throw new Error("not an object");
+  const latest = (body as { latest?: unknown }).latest;
+  if (typeof latest !== "string") throw new Error("no latest tag");
+  return isPlainRelease(latest) ? latest : "";
+}
+
+export function renderCache(latest: string, checked: number): string {
+  return `latest=${latest}\nchecked=${checked}\n`;
+}
+
+/** The last good version in an existing cache file ("" when there is none). */
+export function cachedLatest(text: string): string {
+  for (const line of text.split("\n")) {
+    if (line.startsWith("latest=")) {
+      const v = line.slice("latest=".length);
+      return isPlainRelease(v) ? v : "";
+    }
+  }
+  return "";
+}
+
+function writeCache(cacheDir: string, latest: string, checked: number): void {
+  mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+  const file = join(cacheDir, "update-check");
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, renderCache(latest, checked), { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+function readCachedLatest(cacheDir: string): string {
+  try {
+    return cachedLatest(readFileSync(join(cacheDir, "update-check"), "utf-8"));
+  } catch {
+    return "";
+  }
+}
+
+async function fetchLatest(url: string): Promise<string> {
+  const res = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return latestFromDistTags(await res.json());
+}
+
+async function main(): Promise<void> {
+  const pkg = process.argv[2];
+  if (!pkg) return;
+  // A stalled DNS lookup or body must not leave a process behind.
+  setTimeout(() => process.exit(0), HARD_EXIT_MS);
+
+  const { cacheDir } = getPaths();
+  const now = Math.floor(Date.now() / 1000);
+  try {
+    const url = distTagsUrl(registryBase(process.env.CCS_UPDATE_REGISTRY), pkg);
+    writeCache(cacheDir, await fetchLatest(url), now);
+  } catch {
+    // Offline, timed out, bad answer: keep what the last good answer said.
+    try {
+      const retryAt = now - CHECK_INTERVAL_S + RETRY_AFTER_FAILURE_S;
+      writeCache(cacheDir, readCachedLatest(cacheDir), retryAt);
+    } catch {
+      // Cache not writable: nothing to remember, nothing to report.
+    }
+  }
+}
+
+// Run only as a script, so the test suite can import the helpers.
+if (process.argv[1]?.endsWith("ccs-update-check.ts")) {
+  main().then(
+    () => process.exit(0),
+    () => process.exit(0),
+  );
+}

package/bin/ccs-utils.ts

@@ -46,6 +46,11 @@ export function truncate(s: string, max: number): string {
   return flat.length <= max ? flat : flat.slice(0, max - 1) + "…";
 }
 
+/** A repos.yml icon as drawn: never a tab or an escape, 📁 when nothing is left. */
+export function displayIcon(icon: string | null | undefined): string {
+  return stripControlChars(icon ?? "") || "📁";
+}
+
 // ---------------------------------------------------------------------------
 // Repo display name & nesting
 // ---------------------------------------------------------------------------

package/bin/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}