@naswerks/periscope 1.0.0 → 1.0.1

package/src/host/config-file.ts

@@ -0,0 +1,246 @@
+/**
+ * The config file: the CLI as a first-class writer, so a library user with no UI is not env-only.
+ *
+ * It lives beside the credential files on purpose. `periscopeCredentialDir(env)` is the single
+ * source both the token cache's location and the gate's protected set derive from, so a config file
+ * written under it is protected from the sessions this host runs by having been put there — not by
+ * somebody remembering to add a line. (Nothing in it is secret today; the property costs nothing
+ * and the alternative is a second directory with a second protection question.)
+ *
+ * The environment still wins, per key. The file is a fallback for an absence: a value here is
+ * consulted only when the same variable is unset or empty in the process environment, so a
+ * deployment that sets env vars is configured by them alone — and there is
+ * never a precedence question to look up, because a stated env var makes the file's value
+ * unreachable. `withConfigFallback` is the one place that rule is implemented.
+ *
+ * The key set is closed, on both the write and the read. An unknown key written is refused naming
+ * the legal set (a typo'd key that "worked" would configure nothing, silently). An unknown key
+ * read is a problem too, for the same reason from the other side: this host wrote none, so one in
+ * the file is a hand-edit that does nothing, the misconfiguration nobody finds. And
+ * `PERISCOPE_CONFIG_DIR` is deliberately not settable here: it is what says where this file is,
+ * and a file that could move itself is a bootstrap circle.
+ *
+ * Sync I/O throughout, deliberately: `serve()` stays synchronous (its own docblock says why), and a
+ * one-shot read at boot plus a one-shot write per `config` invocation need no event loop.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+
+import { join, periscopeCredentialDir } from './paths.js';
+
+/**
+ * Every key the config file may carry — the environment variables the composition root reads,
+ * minus `PERISCOPE_CONFIG_DIR` (the bootstrap exclusion above).
+ */
+export const CONFIG_KEYS = [
+  'PERISCOPE_CONTROLLER_URL',
+  'PERISCOPE_DECISION_URL',
+  'PERISCOPE_HOST_ID',
+  'PERISCOPE_WORKSPACE_ROOT',
+  'PERISCOPE_REPOSITORY_ROOT',
+  'PERISCOPE_BRANCH_SCHEME',
+  'PERISCOPE_WORKSPACE_KEY',
+  'PERISCOPE_AGENT_HOME',
+] as const;
+
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+
+/**
+ * The keys a controller may set over the wire (`host_configure`): where this machine's things are,
+ * and where its control plane is. The two URLs are written to the file and never applied to
+ * the live link: the host dials what it dialled until its next start, and names the keys as pending
+ * in its answer and in every hello until then. Never the host id (a paired credential outranks it
+ * anyway) or the default workspace key (a start-up posture, screened at boot).
+ */
+export const WIRE_CONFIGURABLE_KEYS = [
+  'PERISCOPE_WORKSPACE_ROOT',
+  'PERISCOPE_REPOSITORY_ROOT',
+  'PERISCOPE_BRANCH_SCHEME',
+  'PERISCOPE_AGENT_HOME',
+  'PERISCOPE_CONTROLLER_URL',
+  'PERISCOPE_DECISION_URL',
+] as const satisfies readonly ConfigKey[];
+
+export type WireConfigurableKey = (typeof WIRE_CONFIGURABLE_KEYS)[number];
+
+/** The wire-settable keys that take effect only at the next start: the control-plane addresses. */
+export const RESTART_KEYS = [
+  'PERISCOPE_CONTROLLER_URL',
+  'PERISCOPE_DECISION_URL',
+] as const satisfies readonly WireConfigurableKey[];
+
+export function isWireConfigurableKey(value: string): value is WireConfigurableKey {
+  return (WIRE_CONFIGURABLE_KEYS as readonly string[]).includes(value);
+}
+
+export function isConfigKey(value: string): value is ConfigKey {
+  return (CONFIG_KEYS as readonly string[]).includes(value);
+}
+
+/** Where the config file lives, or null when there is nowhere to keep one (no home, no override). */
+export function configFilePath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const dir = periscopeCredentialDir(env);
+  return dir === null ? null : join(dir, 'config.json');
+}
+
+/** What a read found: the values, or the named problem that makes them unusable. */
+export interface ConfigFileReading {
+  readonly values: Readonly<Record<string, string>>;
+  /** Null when the file is usable (a missing file is usable: it reads as empty). */
+  readonly problem: string | null;
+}
+
+/**
+ * Read the config file. A MISSING file is `{}` — the ordinary state of every machine that has
+ * never run `periscope config`. A file that exists and cannot be used is a PROBLEM, never a silent
+ * empty: falling back would make a corrupt file behave like a deliberate absence, which is the
+ * exact ambiguity the paired credential's fatal-on-corrupt posture exists to end.
+ */
+export function readConfigFile(env: NodeJS.ProcessEnv = process.env): ConfigFileReading {
+  const path = configFilePath(env);
+  if (path === null) return { values: {}, problem: null };
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { values: {}, problem: null };
+    return {
+      values: {},
+      problem: `the config file at ${path} exists and cannot be read: ${describe(error)}`,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      values: {},
+      problem: `the config file at ${path} is not JSON: ${describe(error)}`,
+    };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return {
+      values: {},
+      problem: `the config file at ${path} must hold one JSON object of string values`,
+    };
+  }
+
+  const values: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!isConfigKey(key)) {
+      return {
+        values: {},
+        problem:
+          `the config file at ${path} carries an unknown key '${key}' — this host reads only ` +
+          `${CONFIG_KEYS.join(', ')}, so the entry would configure nothing`,
+      };
+    }
+    if (typeof value !== 'string') {
+      return {
+        values: {},
+        problem: `the config file at ${path} carries a non-string value for '${key}'`,
+      };
+    }
+    values[key] = value;
+  }
+  return { values, problem: null };
+}
+
+/**
+ * Write one entry, creating the directory and file as needed. Returns null, or the named problem.
+ * Refuses an unknown key BEFORE touching the disk — see the closed-set rule in the header.
+ */
+export function writeConfigEntry(env: NodeJS.ProcessEnv, key: string, value: string): string | null {
+  if (!isConfigKey(key)) {
+    return `'${key}' is not a config key this host reads — the legal keys are ${CONFIG_KEYS.join(', ')}`;
+  }
+  const path = configFilePath(env);
+  if (path === null) {
+    return 'there is nowhere to keep a config file — no home directory and no PERISCOPE_CONFIG_DIR';
+  }
+  const existing = readConfigFile(env);
+  if (existing.problem !== null) {
+    // Never merged-over: writing "around" a corrupt file destroys whatever the operator hand-wrote.
+    return `${existing.problem} — fix or remove it before writing`;
+  }
+  try {
+    const dir = path.slice(0, path.lastIndexOf('/'));
+    mkdirSync(dir, { recursive: true });
+    const next = { ...existing.values, [key]: value };
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return null;
+  } catch (error) {
+    return `the config file at ${path} could not be written: ${describe(error)}`;
+  }
+}
+
+/** One entry of a multi-key write: a value to set, or null to remove the key. */
+export interface ConfigEntryWrite {
+  readonly key: string;
+  readonly value: string | null;
+}
+
+/**
+ * Write several entries as one read-modify-write, creating the directory and file as needed.
+ * Returns null, or the named problem. Every key is screened BEFORE the disk is touched, so a set
+ * with one bad key writes nothing; a null value removes its key. The same corrupt-file posture as
+ * the single-entry write: never merged over.
+ */
+export function writeConfigEntries(
+  env: NodeJS.ProcessEnv,
+  entries: readonly ConfigEntryWrite[],
+): string | null {
+  for (const entry of entries) {
+    if (!isConfigKey(entry.key)) {
+      return `'${entry.key}' is not a config key this host reads — the legal keys are ${CONFIG_KEYS.join(', ')}`;
+    }
+  }
+  const path = configFilePath(env);
+  if (path === null) {
+    return 'there is nowhere to keep a config file — no home directory and no PERISCOPE_CONFIG_DIR';
+  }
+  const existing = readConfigFile(env);
+  if (existing.problem !== null) {
+    return `${existing.problem} — fix or remove it before writing`;
+  }
+  try {
+    const dir = path.slice(0, path.lastIndexOf('/'));
+    mkdirSync(dir, { recursive: true });
+    const next: Record<string, string> = { ...existing.values };
+    for (const entry of entries) {
+      if (entry.value === null) delete next[entry.key];
+      else next[entry.key] = entry.value;
+    }
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return null;
+  } catch (error) {
+    return `the config file at ${path} could not be written: ${describe(error)}`;
+  }
+}
+
+/**
+ * The environment, with file values FILLING ABSENCES — the one implementation of "env wins".
+ *
+ * Returns a NEW plain object; the process environment is never mutated. Only the closed key set is
+ * consulted, so nothing outside it (identity configuration, the config dir itself) can arrive from
+ * a file. Empty-string env values count as absent, matching how the composition root reads them.
+ */
+export function withConfigFallback(
+  env: NodeJS.ProcessEnv,
+  values: Readonly<Record<string, string>>,
+): NodeJS.ProcessEnv {
+  const merged: NodeJS.ProcessEnv = { ...env };
+  for (const key of CONFIG_KEYS) {
+    const fromEnv = env[key];
+    const fromFile = values[key];
+    if ((fromEnv === undefined || fromEnv === '') && fromFile !== undefined && fromFile !== '') {
+      merged[key] = fromFile;
+    }
+  }
+  return merged;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/host/git-facts.ts

@@ -0,0 +1,119 @@
+/**
+ * Which worktree and which branch a directory sits in: the "where" half of every transition.
+ *
+ * Why this is read at all: a trace whose location is a bare path answers "where" with something
+ * a reader still has to go and look up. Worktree and branch are what makes a transition legible on
+ * its own, which is the whole bar the state model is held to.
+ *
+ * It reads; it never provisions. No `git` subprocess, no writes, no repository creation, just
+ * two small file reads. Creating and managing worktrees is a different job and stays one.
+ *
+ * `.git` is often a file, not a directory, and that is the trap this file exists around.
+ * In a linked worktree, `.git` is a text file holding `gitdir: <path>` and pointing at a directory
+ * under the main repository's `.git/worktrees/`. A walk-up that looks for a `.git` directory finds
+ * nothing there and reports "not a repository", which is wrong, silently, in exactly the
+ * environment agents are most often given.
+ *
+ * Every failure is a named null, never an exception and never an empty string. Three ordinary
+ * situations produce no branch: the directory is not in a repository at all (normal — a plain
+ * working directory is a legitimate place to run), HEAD is detached (there IS no branch name), or
+ * HEAD is unreadable. An empty string would make all three indistinguishable from each other and
+ * from a branch literally named "".
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+import type { TransitionWhere } from '../state/model.js';
+
+/** How far up to walk. A repository root further than this from cwd is not a case worth serving. */
+const MAX_DEPTH = 64;
+
+/** A `.git` entry found on the way up: the worktree that holds it and the git directory it names. */
+interface GitLocation {
+  readonly worktree: string;
+  readonly gitDir: string;
+}
+
+/**
+ * The `where` for a directory. Never throws — the caller stamps this onto every transition, so a
+ * throw here would take out the state record along with the fact it was decorating.
+ */
+export function readWhere(cwd: string): TransitionWhere {
+  const located = locateGit(cwd);
+  if (located === null) {
+    return { cwd, worktree: null, branch: null, unknownReason: 'not inside a git repository' };
+  }
+
+  const head = readHead(located.gitDir);
+  return {
+    cwd,
+    worktree: located.worktree,
+    branch: head.branch,
+    unknownReason: head.reason,
+  };
+}
+
+/** Walk up from `start` for a `.git` entry, accepting both the directory and the pointer-file form. */
+function locateGit(start: string): GitLocation | null {
+  let current = resolve(start);
+
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const marker = join(current, '.git');
+    const kind = entryKind(marker);
+
+    if (kind === 'dir') return { worktree: current, gitDir: marker };
+    if (kind === 'file') {
+      const pointed = readGitDirPointer(marker, current);
+      // A `.git` file that does not parse is still a `.git` file: this IS the worktree root, and
+      // saying so with an unreadable HEAD beats walking past it and reporting "not a repository".
+      return { worktree: current, gitDir: pointed ?? marker };
+    }
+
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+
+  return null;
+}
+
+function entryKind(path: string): 'dir' | 'file' | 'absent' {
+  try {
+    const stats = statSync(path);
+    return stats.isDirectory() ? 'dir' : 'file';
+  } catch {
+    return 'absent';
+  }
+}
+
+/** `gitdir: <path>` out of a linked worktree's `.git` file. Relative paths resolve against it. */
+function readGitDirPointer(marker: string, worktree: string): string | null {
+  try {
+    const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(marker, 'utf8'));
+    const target = pointer?.[1]?.trim();
+    if (target === undefined || target.length === 0) return null;
+    return isAbsolute(target) ? target : resolve(worktree, target);
+  } catch {
+    return null;
+  }
+}
+
+/** The branch, or which of the ordinary situations means there is not one. */
+function readHead(gitDir: string): { branch: string | null; reason: string | null } {
+  let raw: string;
+  try {
+    raw = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+  } catch {
+    return { branch: null, reason: 'HEAD could not be read' };
+  }
+
+  const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(raw);
+  if (ref?.[1] !== undefined) return { branch: ref[1].trim(), reason: null };
+
+  // A bare object id is a detached HEAD: there genuinely is no branch, which is different from
+  // failing to find one, and a reader deciding whether a run is on the branch it should be needs
+  // to be able to tell those apart.
+  if (/^[0-9a-f]{40}$/i.test(raw)) return { branch: null, reason: 'HEAD is detached' };
+
+  return { branch: null, reason: `HEAD is in an unrecognised form: ${raw.slice(0, 40)}` };
+}

package/src/host/hooks.ts

@@ -0,0 +1,102 @@
+/**
+ * Turns the coverage table into the `options.hooks` object the SDK actually takes.
+ *
+ * Registration is derived from the table, not written beside it. The list of events registered
+ * here is the list `coverage.ts` marks `wired`, so the table cannot claim an event is wired while
+ * the wiring quietly lacks it. A table that can disagree with the code is a document that will.
+ *
+ * Every handler is wrapped, because a throwing hook is fail-open. A hook that throws is treated
+ * by the CLI as absent rather than as a refusal (observed behaviour, not an assumption). For an
+ * observer that would mean a lost transition and nothing else, which is precisely the silent loss
+ * this model exists to prevent, so the wrapper is here and not left to the caller.
+ *
+ * This handler never decides anything. It returns an empty output on every path, including the
+ * failure path. `HookCallbackMatcher.hooks` is an array and the SDK runs every entry, so a
+ * permission-decision handler registers on the same event alongside this one; neither has to know
+ * about the other, and observation cannot accidentally become authorization.
+ */
+import type { HookCallbackMatcher, HookInput, HookJSONOutput, HookRegistrations } from './agent-process.js';
+import type { SessionObserver } from '../state/observer.js';
+import { HOOK_COVERAGE } from '../state/coverage.js';
+import { HOOK_EVENTS } from '../state/model.js';
+
+/** Told about a handler that threw, so a fail-open hook is never a silent one. */
+export type HookFailureListener = (failure: { event: string; error: unknown }) => void;
+
+export interface ObservationHookOptions {
+  readonly observer: SessionObserver;
+  readonly onHandlerFailure?: HookFailureListener;
+}
+
+/** Every event the table marks `wired`, in the SDK's own order. */
+export function wiredHookEvents(): readonly string[] {
+  return HOOK_EVENTS.filter((event) => HOOK_COVERAGE[event].handling === 'wired');
+}
+
+/**
+ * The `hooks` object for a session, registering exactly the wired events.
+ *
+ * No matcher is set: a matcher filters by tool name, and this observes every tool. The absence is
+ * deliberate rather than an omission.
+ */
+export function observationHooks(options: ObservationHookOptions): HookRegistrations {
+  const handler = (input: HookInput): Promise<HookJSONOutput> => {
+    try {
+      // The results are not read here. A transition the machine refuses is reported on
+      // `machine.onRejected` and counted in `rejectedCount`, the one channel every refused record
+      // takes whatever lane produced it; reporting it again from this handler would count one
+      // refusal twice. The observer builds a request only for an event it names, so an event this
+      // package does not know records nothing rather than producing a refusal to route.
+      options.observer.observeHook(input);
+    } catch (error) {
+      // A throw here would make the CLI treat the hook as absent, which is the fail-open hole. It
+      // is caught, reported, and never rethrown; losing one observation loudly beats losing the
+      // handler entirely and silently. The listener is guarded too: a reporter that throws must
+      // not reopen the hole it exists to report.
+      try {
+        options.onHandlerFailure?.({ event: input.hook_event_name, error });
+      } catch {
+        // Nothing further can be reported; the handler still answers.
+      }
+    }
+    return Promise.resolve({});
+  };
+
+  // One matcher object per event. A shared instance would let a `timeout` or `matcher` set on one
+  // event's entry apply to every event.
+  const registrations: HookRegistrations = {};
+  for (const event of HOOK_EVENTS) {
+    if (HOOK_COVERAGE[event].handling !== 'wired') continue;
+    const matcher: HookCallbackMatcher = { hooks: [handler] };
+    registrations[event] = [matcher];
+  }
+  return registrations;
+}
+
+/**
+ * Combine independent hook registrations, concatenating the matchers per event.
+ *
+ * This is the seam that keeps observation and authorization apart. A permission decision and a
+ * state record answer different questions, have different consumers and fail differently, and the
+ * failure this package is built against is exactly what happens when they share a guard: the
+ * control concern wins, and the observability loss is silent. Two matchers on one event, merged
+ * here, means neither can suppress the other because neither knows the other exists.
+ *
+ * "Earlier arguments run first" is true of dispatch and false of completion. Handlers on one
+ * event have their synchronous prologues run in array order, and are then awaited concurrently
+ * (observed behaviour, not an assumption). So a handler may rely on an earlier one having started
+ * and must never rely on it having finished: anything order-dependent belongs before the first
+ * `await`. (The
+ * gate's permission entry opens from its hold timer, not in its prologue, so it depends on no
+ * registration order; it registers second by convention.)
+ */
+export function mergeHooks(...registrations: readonly HookRegistrations[]): HookRegistrations {
+  const merged: HookRegistrations = {};
+  for (const registration of registrations) {
+    for (const [event, matchers] of Object.entries(registration)) {
+      const key = event as keyof HookRegistrations;
+      merged[key] = [...(merged[key] ?? []), ...(matchers ?? [])];
+    }
+  }
+  return merged;
+}