@orchestrator-claude/definitions 3.32.1 → 3.33.0

package/hooks/lib/additional-directories-sync.ts

@@ -0,0 +1,295 @@
+/**
+ * additional-directories-sync.ts — RFC-040 TD-204 ⑤-B.
+ *
+ * Drives (never enforces) a settings.json's
+ * `.permissions.additionalDirectories` from the Postgres SoT (registered
+ * projects — read via `listRegisteredProjects()` in api-client.ts, the SAME
+ * `ProjectRegistryService` domain path C2 `/resolve` reads from).
+ *
+ * ★ Union-merge law (THE #1 care, TD-204 §3a):
+ *
+ *     result = existingManualEntries ∪ registeredProjectRoots
+ *
+ * NEVER a replace. De-duped. Existing order preserved; new entries
+ * appended. The real machine's `~/.claude/settings.json` already carries
+ * manual entries (`trc`, `red-bull`) that a blind write would wipe — this
+ * module exists specifically so that never happens.
+ *
+ * Prune policy v1 = ADDITIVE-ONLY: a project that is later unregistered
+ * does not have its dir revoked by this sync. `readManagedSidecar` /
+ * `writeManagedSidecarAtomic` persist the union of every root path this
+ * sync has ever added, as a design-for-it primitive a future prune-capable
+ * version can diff against (`manualEntries = additionalDirectories \
+ * managedSidecar`) — NOT wired to any pruning behaviour in v1.
+ *
+ * Honest limit (TD-204 §39): `additionalDirectories` is the operator's own
+ * Claude Code trust control (user settings), not a Postgres-enforced
+ * boundary. This module DRIVES (auto-populates) it; Class-A hooks
+ * (workflow-guard.ts) are the actual backstop. Never described as
+ * "enforcement".
+ *
+ * Installer-compatible (TD-204 §75-77): every function is pure/injectable
+ * — `settingsPath`/`sidecarPath` are always explicit parameters, never a
+ * hardcoded `~/.claude` path or a RUN-02 dev-checkout symlink assumption.
+ * Mirrored into packages/definitions/hooks/lib/ via
+ * scripts/sync-hook-mirrors.ts (DISTRIBUTABLE_LIBS) so the future
+ * `orch-defs install` can import this exact module.
+ *
+ * Write safety: read-modify-write via a pure JSON-preserving merge, then
+ * `writeSettingsAtomic` — back up the prior file, write a temp file in the
+ * SAME directory, validate it re-parses as JSON, atomic-rename over the
+ * target. Any failure before the rename leaves the real file byte-for-byte
+ * untouched (never a partial write of the settings file the operator's
+ * Claude Code process reads).
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  copyFileSync,
+  unlinkSync,
+  mkdirSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface MergeResult {
+  /** Final additionalDirectories array (existing ∪ registered), de-duped, order-stable. */
+  merged: string[];
+  /** Entries newly appended this run (registered roots not already present). */
+  added: string[];
+}
+
+export interface ManagedSidecar {
+  /** Every root path this sync has ever added — additive-only union across runs. */
+  managedPaths: string[];
+  updatedAt: string;
+}
+
+export type SyncOutcome =
+  | { ok: true; dryRun: boolean; merged: string[]; added: string[]; backupPath?: string }
+  | {
+      ok: false;
+      reason: 'settings-file-not-found' | 'invalid-json' | 'write-failed';
+      error?: string;
+    };
+
+export interface SyncOptions {
+  settingsPath: string;
+  registeredRoots: readonly string[];
+  dryRun?: boolean;
+  /** Sidecar path override (tests / callers). Defaults to a file alongside settingsPath. */
+  sidecarPath?: string;
+}
+
+// ─── Pure merge (no I/O) ─────────────────────────────────────────────────
+
+/**
+ * Union-merge law (THE #1 care): result = existingManualEntries ∪
+ * registeredProjectRoots. Never a replace. De-dupe. Preserve existing
+ * order; append new entries at the end. Defensive: filters out any
+ * non-string / empty-string entry from either side without throwing.
+ */
+export function mergeAdditionalDirectories(
+  existing: readonly string[] | undefined,
+  registeredRoots: readonly string[]
+): MergeResult {
+  const normalizedExisting = Array.isArray(existing)
+    ? existing.filter((entry): entry is string => typeof entry === 'string' && entry !== '')
+    : [];
+  const seen = new Set(normalizedExisting);
+  const added: string[] = [];
+
+  for (const root of registeredRoots) {
+    if (typeof root !== 'string' || root === '' || seen.has(root)) continue;
+    seen.add(root);
+    added.push(root);
+  }
+
+  return { merged: [...normalizedExisting, ...added], added };
+}
+
+/**
+ * Applies the union-merge to a full settings object, preserving EVERY other
+ * key (top-level and inside `.permissions`) untouched. Never mutates the
+ * input object.
+ */
+export function applyAdditionalDirectoriesToSettings(
+  settings: Record<string, unknown>,
+  registeredRoots: readonly string[]
+): { settings: Record<string, unknown>; added: string[] } {
+  const permissions =
+    settings.permissions && typeof settings.permissions === 'object'
+      ? (settings.permissions as Record<string, unknown>)
+      : {};
+
+  const existing = Array.isArray(permissions.additionalDirectories)
+    ? (permissions.additionalDirectories as unknown[]).filter(
+        (e): e is string => typeof e === 'string'
+      )
+    : undefined;
+
+  const { merged, added } = mergeAdditionalDirectories(existing, registeredRoots);
+
+  return {
+    settings: {
+      ...settings,
+      permissions: {
+        ...permissions,
+        additionalDirectories: merged,
+      },
+    },
+    added,
+  };
+}
+
+// ─── Atomic write (backup -> temp -> validate -> rename) ─────────────────
+
+/**
+ * Read-modify-write safety: back up the prior file first (timestamped,
+ * same directory), write to a temp file in the SAME directory (same-
+ * filesystem rename is atomic on POSIX), validate the temp file re-parses
+ * as JSON, then rename over the target. On any failure BEFORE the rename,
+ * the original file is untouched — never a partial write of the real
+ * settings file. The temp file is best-effort cleaned up on any failure.
+ *
+ * Returns the backup path, or `undefined` when no prior file existed (a
+ * fresh file was created — nothing to back up).
+ */
+export function writeSettingsAtomic(
+  settingsPath: string,
+  settings: Record<string, unknown>
+): string | undefined {
+  let backupPath: string | undefined;
+  if (existsSync(settingsPath)) {
+    backupPath = `${settingsPath}.bak.${String(Date.now())}`;
+    copyFileSync(settingsPath, backupPath);
+  }
+
+  const tempPath = `${settingsPath}.tmp.${String(process.pid)}.${String(Date.now())}`;
+  const content = JSON.stringify(settings, null, 2);
+
+  try {
+    writeFileSync(tempPath, content, 'utf-8');
+    // Validate before ever touching the real file.
+    JSON.parse(readFileSync(tempPath, 'utf-8'));
+    renameSync(tempPath, settingsPath);
+  } catch (err) {
+    if (existsSync(tempPath)) {
+      try {
+        unlinkSync(tempPath);
+      } catch {
+        // best-effort cleanup — the original file is already safe either way
+      }
+    }
+    throw err;
+  }
+
+  return backupPath;
+}
+
+// ─── Managed-paths sidecar (design-for-it, v1 additive-only) ─────────────
+
+export function readManagedSidecar(sidecarPath: string): ManagedSidecar {
+  try {
+    if (!existsSync(sidecarPath)) return { managedPaths: [], updatedAt: '' };
+    const raw = JSON.parse(readFileSync(sidecarPath, 'utf-8')) as Partial<ManagedSidecar>;
+    return {
+      managedPaths: Array.isArray(raw.managedPaths)
+        ? raw.managedPaths.filter((p): p is string => typeof p === 'string')
+        : [],
+      updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : '',
+    };
+  } catch {
+    return { managedPaths: [], updatedAt: '' };
+  }
+}
+
+export function writeManagedSidecarAtomic(
+  sidecarPath: string,
+  managedPaths: readonly string[]
+): void {
+  mkdirSync(dirname(sidecarPath), { recursive: true });
+  const tempPath = `${sidecarPath}.tmp.${String(process.pid)}.${String(Date.now())}`;
+  const record: ManagedSidecar = {
+    managedPaths: [...managedPaths],
+    updatedAt: new Date().toISOString(),
+  };
+
+  try {
+    writeFileSync(tempPath, JSON.stringify(record, null, 2), 'utf-8');
+    JSON.parse(readFileSync(tempPath, 'utf-8'));
+    renameSync(tempPath, sidecarPath);
+  } catch (err) {
+    if (existsSync(tempPath)) {
+      try {
+        unlinkSync(tempPath);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    throw err;
+  }
+}
+
+// ─── Orchestration ─────────────────────────────────────────────────────────
+
+/**
+ * Reads `settingsPath`, union-merges `registeredRoots` into
+ * `.permissions.additionalDirectories`, and (unless `dryRun`) writes the
+ * result back atomically plus updates the managed-paths sidecar.
+ *
+ * Fail-SAFE, not fail-open: a missing or unparseable settings file returns
+ * `ok: false` and touches NOTHING — this module never creates a brand-new
+ * settings.json (the real file always pre-exists per TD-204 §0) and never
+ * risks writing on top of content it could not fully understand.
+ */
+export function syncAdditionalDirectories(options: SyncOptions): SyncOutcome {
+  const { settingsPath, registeredRoots, dryRun = false } = options;
+  const sidecarPath =
+    options.sidecarPath ?? join(dirname(settingsPath), '.orchestrator-managed-directories.json');
+
+  if (!existsSync(settingsPath)) {
+    return { ok: false, reason: 'settings-file-not-found' };
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    const raw = readFileSync(settingsPath, 'utf-8');
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'invalid-json',
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const { settings: nextSettings, added } = applyAdditionalDirectoriesToSettings(
+    parsed,
+    registeredRoots
+  );
+  const permissions = nextSettings.permissions as Record<string, unknown>;
+  const merged = permissions.additionalDirectories as string[];
+
+  if (dryRun) {
+    return { ok: true, dryRun: true, merged, added };
+  }
+
+  try {
+    const backupPath = writeSettingsAtomic(settingsPath, nextSettings);
+    const sidecar = readManagedSidecar(sidecarPath);
+    const managedUnion = Array.from(new Set([...sidecar.managedPaths, ...registeredRoots]));
+    writeManagedSidecarAtomic(sidecarPath, managedUnion);
+    return { ok: true, dryRun: false, merged, added, ...(backupPath ? { backupPath } : {}) };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'write-failed',
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}