kankaku-pi 1.0.0

package/src/adapters/file-inflight-store.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isWorkRecord } from "../domain/work-record.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+import type { InflightStore } from "../ports/inflight-store.ts";
+
+const INFLIGHT_DIR_NAME = "inflight";
+const JSON_EXT = ".json";
+const TMP_EXT = ".tmp";
+/** Matches `save`'s tmp filename: `<ownerPid>.json.<writerPid>.<timestamp>.tmp`. */
+const TMP_NAME_PATTERN = /\.json\.(\d+)\.\d+\.tmp$/;
+
+function safeUnlink(filePath: string): void {
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Best effort: another process may have already removed it.
+  }
+}
+
+/** The writer pid embedded in a `save` tmp filename, or `undefined` when it cannot be parsed. */
+function parseTmpWriterPid(entry: string): number | undefined {
+  const match = TMP_NAME_PATTERN.exec(entry);
+  if (!match) return undefined;
+  const pid = Number(match[1]);
+  return Number.isFinite(pid) ? pid : undefined;
+}
+
+/**
+ * {@link InflightStore} backed by one checkpoint file per process,
+ * `<dir>/inflight/<pid>.json`. `save` writes to a temp file then renames
+ * it into place so a reader never observes a partially written checkpoint.
+ */
+export class FileInflightStore implements InflightStore {
+  private readonly dir: string;
+  private readonly pid: number;
+
+  constructor(dir: string, pid: number) {
+    this.dir = dir;
+    this.pid = pid;
+  }
+
+  private get inflightDir(): string {
+    return join(this.dir, INFLIGHT_DIR_NAME);
+  }
+
+  private filePathFor(pid: number): string {
+    return join(this.inflightDir, `${pid}${JSON_EXT}`);
+  }
+
+  save(record: WorkRecord): void {
+    mkdirSync(this.inflightDir, { recursive: true });
+    const target = this.filePathFor(this.pid);
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, target);
+  }
+
+  clear(): void {
+    safeUnlink(this.filePathFor(this.pid));
+  }
+
+  recoverStale(isAlive: (pid: number) => boolean): WorkRecord[] {
+    if (!existsSync(this.inflightDir)) return [];
+
+    const recovered: WorkRecord[] = [];
+    const ownFileName = `${this.pid}${JSON_EXT}`;
+
+    for (const entry of readdirSync(this.inflightDir)) {
+      if (entry.endsWith(TMP_EXT)) {
+        this.sweepTmpEntry(entry, isAlive);
+        continue;
+      }
+
+      if (!entry.endsWith(JSON_EXT) || entry === ownFileName) continue;
+
+      const filePath = join(this.inflightDir, entry);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+      } catch {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (!isWorkRecord(parsed)) {
+        safeUnlink(filePath);
+        continue;
+      }
+
+      if (isAlive(parsed.pid)) continue;
+
+      recovered.push({ ...parsed, status: "interrupted" });
+      safeUnlink(filePath);
+    }
+
+    return recovered;
+  }
+
+  /**
+   * Delete a stray `save()` tmp file left behind by a writer that crashed
+   * between the write and the rename. Deleted when the writer pid is not
+   * alive, or when the filename cannot be parsed at all (nothing to check
+   * liveness against). A tmp file written by this very process is always
+   * left alone regardless of what `isAlive` reports, since a concurrent
+   * `save()` in this process may still be renaming it into place.
+   */
+  private sweepTmpEntry(entry: string, isAlive: (pid: number) => boolean): void {
+    const writerPid = parseTmpWriterPid(entry);
+    if (writerPid === process.pid) return;
+    if (writerPid === undefined || !isAlive(writerPid)) {
+      safeUnlink(join(this.inflightDir, entry));
+    }
+  }
+}

package/src/adapters/file-modes.ts

@@ -0,0 +1,35 @@
+import { chmodSync, mkdirSync, statSync } from "node:fs";
+
+/**
+ * Every file kankaku writes under `~/.kankaku` (the machine-wide registry
+ * `run/`, the catalog cache) carries absolute project paths, session ids, or
+ * hub identifiers — restricted to the owner (F4). Not applied to a
+ * project's own `<KANKAKU_DIR>` (`worklog.jsonl`, `inflight/`, …), which is
+ * project-local, frequently committed alongside, and out of scope here.
+ */
+export const OWNER_DIR_MODE = 0o700;
+export const OWNER_FILE_MODE = 0o600;
+
+/**
+ * Create `dir` (recursive) with `mode`, then best-effort tighten it when it
+ * already existed with a looser mode — `mkdirSync`'s own `mode` option only
+ * applies to a directory it actually creates in this call, never to one
+ * that already existed (e.g. left by an older kankaku build, or a
+ * permissive umask). Never throws: a permission-tightening failure must
+ * never block the write this call exists to make.
+ */
+export function ensureDirMode(dir: string, mode: number = OWNER_DIR_MODE): void {
+  mkdirSync(dir, { recursive: true, mode });
+  tightenMode(dir, mode);
+}
+
+/** Best-effort `chmod` down to `mode` when the current mode is looser than it; never throws. */
+export function tightenMode(path: string, mode: number = OWNER_FILE_MODE): void {
+  try {
+    const current = statSync(path).mode & 0o777;
+    if ((current & ~mode) !== 0) chmodSync(path, mode);
+  } catch {
+    // Best effort: another process may have already removed the path, or
+    // this filesystem does not support POSIX modes at all.
+  }
+}

package/src/adapters/hub-actions.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared line-building for the hub-facing `/kankaku` subcommands (`sync`,
+ * `sync all`, `sync status`, `backfill`, `catalog refresh`) and the panel's
+ * `sync`/`export` screens (`adapters/panel/screens/sync.ts`), extracted from
+ * `kankaku-command.ts` so the subcommands and the panel can never drift —
+ * see odd/tasks/kankaku-panel.md P4.
+ */
+import type { CatalogSnapshot } from "../ports/catalog.ts";
+import type { SyncStatusSnapshot, SyncSummary } from "./sync-runner.ts";
+
+/**
+ * `/kankaku sync status`'s report lines: the watermark, the pending count,
+ * how many tasks fell outside this run's revisit window (R3), and the last
+ * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
+ */
+export function buildSyncStatusLines(status: SyncStatusSnapshot): string[] {
+  const { state, pending, staleOutsideWindow } = status;
+  const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
+  if (staleOutsideWindow > 0) {
+    lines.push(`${staleOutsideWindow} task(s) never synced fall outside the sync window — run '/kankaku sync all' to upload them`);
+  }
+  if (state?.lastError) lines.push(`last error: ${state.lastError.message} (at ${state.lastError.at})`);
+  return lines;
+}
+
+/**
+ * Render a {@link SyncSummary} as report lines: counts, any stop reason, the
+ * new watermark, and the unassigned/failed breakdowns. Used by `/kankaku
+ * sync`/`sync all` and the panel's sync screen.
+ */
+export function formatSyncSummaryLines(summary: SyncSummary): string[] {
+  const lines = [`uploaded ${summary.uploaded}, updated ${summary.updated}, skipped ${summary.skipped}, failed ${summary.failed.length}`];
+
+  if (summary.locked) lines.push("another sync is already in progress; nothing was attempted");
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  if (summary.syncedThrough) lines.push(`synced through ${summary.syncedThrough}`);
+
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+  if (unassignedEntries.length > 0) {
+    lines.push("unassigned (Sin determinar):");
+    for (const [label, count] of unassignedEntries) lines.push(`  ${label}: ${count}`);
+  }
+
+  if (summary.failed.length > 0) {
+    lines.push("failed:");
+    for (const entry of summary.failed) lines.push(`  ${entry.id}: ${entry.reason}`);
+  }
+
+  return lines;
+}
+
+/**
+ * `/kankaku backfill`'s report lines: tasks routed to Sin determinar this
+ * run, grouped by their old free-text label, or "no unassigned tasks" when
+ * none were. Exact body of `handleBackfillCommand`.
+ */
+export function formatBackfillLines(summary: SyncSummary): string[] {
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+
+  const lines =
+    unassignedEntries.length > 0
+      ? [
+          ...unassignedEntries.map(([label, count]) => `${label}: ${count} task(s) -> Sin determinar`),
+          "reassign these in the hub web app's unassigned queue",
+        ]
+      : ["no unassigned tasks"];
+
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  return lines;
+}
+
+/**
+ * `/kankaku catalog refresh`'s report lines: client/project counts, or an
+ * unreachable notice when the refresh failed (`snapshot` is `undefined`).
+ * The subcommand still notifies that failure as an error rather than a
+ * report (see `handleCatalogCommand`); the panel's sync screen shows
+ * whatever this returns either way.
+ */
+export function formatCatalogRefreshLines(snapshot: CatalogSnapshot | undefined): string[] {
+  if (!snapshot) return ["hub unreachable; catalog not refreshed"];
+  return [`refreshed: ${snapshot.clients.length} client(s), ${snapshot.projects.length} project(s)`];
+}

package/src/adapters/hub-credentials.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadHubEnvCredentials, validateHubUrl } from "../config.ts";
+
+const CREDENTIALS_FILE = join(".kankaku", "credentials.json");
+
+export interface HubCredentials {
+  url: string;
+  email: string;
+  password: string;
+}
+
+interface HubCredentialsFile {
+  url?: string;
+  email?: string;
+  password?: string;
+}
+
+/**
+ * Read `<homeDir>/.kankaku/credentials.json`. Tolerates a missing file,
+ * malformed JSON, a non-object document, or non-string fields — all
+ * return `{}` rather than throwing, since this file is optional and
+ * hand-edited (mirrors `project-config.ts#readProjectClient`).
+ */
+function readCredentialsFile(filePath: string): HubCredentialsFile {
+  if (!existsSync(filePath)) return {};
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const record = parsed as Record<string, unknown>;
+    return {
+      url: typeof record["url"] === "string" ? record["url"] : undefined,
+      email: typeof record["email"] === "string" ? record["email"] : undefined,
+      password: typeof record["password"] === "string" ? record["password"] : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export interface ResolveHubCredentialsDeps {
+  env: NodeJS.ProcessEnv;
+  /**
+   * Resolves the home directory; called lazily, inside this function, and
+   * defensively. A throwing provider (no `HOME`, a sandboxed environment
+   * without a resolvable home directory) is treated the same as "no home
+   * directory" rather than propagating — env-only credentials must still
+   * resolve, and the hub-unconfigured case must stay a no-op regardless of
+   * the host environment. Injectable for tests; defaults to `os.homedir` at
+   * the call site (extension.ts) — passed as a reference, never invoked
+   * there, so a throw never escapes before this function's own try/catch.
+   */
+  homeDir: () => string;
+}
+
+export interface ResolveHubCredentialsResult {
+  /** `undefined` when unconfigured (no url/email/password from any source) or the URL is refused. */
+  credentials: HubCredentials | undefined;
+  /** Set only when a hub URL was given but rejected by {@link validateHubUrl}; surface it once via `ctx.ui.notify`. */
+  invalidReason?: string;
+}
+
+/**
+ * Resolve hub credentials: `KANKAKU_PB_URL`/`_EMAIL`/`_PASSWORD` take
+ * precedence per field over `~/.kankaku/credentials.json` (so a partially
+ * set environment still combines with the file rather than failing
+ * closed). Never reads the project's own `.kankaku/config.json` — that
+ * file is project-local and frequently committed.
+ */
+/** Resolve `homeDir()` defensively: any failure (no `HOME`, a sandboxed environment) yields `undefined` instead of throwing. Exported so callers with their own homedir-dependent path (e.g. `extension.ts`'s catalog cache) can share the same guard. */
+export function safeHomeDir(homeDir: () => string): string | undefined {
+  try {
+    return homeDir();
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveHubCredentials(deps: ResolveHubCredentialsDeps): ResolveHubCredentialsResult {
+  const fromEnv = loadHubEnvCredentials(deps.env);
+  const homeDir = safeHomeDir(deps.homeDir);
+  const fromFile = homeDir !== undefined ? readCredentialsFile(join(homeDir, CREDENTIALS_FILE)) : {};
+
+  const url = fromEnv.url ?? fromFile.url;
+  const email = fromEnv.email ?? fromFile.email;
+  const password = fromEnv.password ?? fromFile.password;
+
+  if (!url || !email || !password) return { credentials: undefined };
+
+  const validation = validateHubUrl(url);
+  if (!validation.ok) return { credentials: undefined, invalidReason: validation.reason };
+
+  return { credentials: { url, email, password } };
+}

package/src/adapters/jsonl-work-log.ts

@@ -0,0 +1,67 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { dedupeById } from "../domain/task-view.ts";
+import type { WorkLog } from "../ports/work-log.ts";
+import type { WorkRecord } from "../domain/work-record.ts";
+import { isWorkRecord } from "../domain/work-record.ts";
+
+const LOG_FILE_NAME = "worklog.jsonl";
+
+/**
+ * Append-only JSONL {@link WorkLog} backed by `<dir>/worklog.jsonl`.
+ * A record is written with a single `appendFileSync` call so a parent and
+ * its subagent children can write concurrently without interleaving lines.
+ */
+export class JsonlWorkLog implements WorkLog {
+  private readonly dir: string;
+
+  constructor(dir: string) {
+    this.dir = dir;
+  }
+
+  private get filePath(): string {
+    return join(this.dir, LOG_FILE_NAME);
+  }
+
+  append(record: WorkRecord): void {
+    mkdirSync(this.dir, { recursive: true });
+    appendFileSync(this.filePath, `${JSON.stringify(record)}\n`);
+  }
+
+  /**
+   * Cheap change signal: `mtimeMs:size` of the log file, computed with a
+   * single `statSync` rather than reading the file. `"0:0"` when the file
+   * does not exist yet (before the first `append`).
+   */
+  version(): string {
+    try {
+      const stats = statSync(this.filePath);
+      return `${stats.mtimeMs}:${stats.size}`;
+    } catch {
+      return "0:0";
+    }
+  }
+
+  readAll(): WorkRecord[] {
+    if (!existsSync(this.filePath)) return [];
+    const content = readFileSync(this.filePath, "utf8");
+    const records: WorkRecord[] = [];
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (isWorkRecord(parsed)) {
+          records.push(parsed);
+        }
+        // Tolerate a structurally invalid record (e.g. an incompatible
+        // schema or a torn write that still parses as JSON); skip it.
+      } catch {
+        // Tolerate malformed lines (e.g. a torn write); skip them.
+      }
+    }
+    // One id can be in the file twice (written at settle, then re-appended by
+    // crash recovery): every reader gets it once — see dedupeById.
+    return dedupeById(records);
+  }
+}