failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/src/hooks/session-pause.ts

@@ -0,0 +1,267 @@
+/**
+ * Per-session enforcement pause — the state behind `failproofai config --pause`.
+ *
+ * A pause suspends LOCAL policy (builtins, explicit custom, convention) for one
+ * agent session, for a bounded time. It is deliberately NOT configuration:
+ *
+ *  - Config is persistent, merged across project/local/global, and routinely
+ *    committed to git. A paused enforcement state written there would outlive
+ *    the session that asked for it and travel to everyone who checks out the
+ *    branch — enforcement silently off for a whole team.
+ *  - So pause state lives here, under `~/.failproofai/state/sessions/`, owner-
+ *    only, keyed by session, and carrying an absolute expiry.
+ *
+ * Disk is the source of truth rather than the daemon: most machines have no
+ * daemon at all, and even where one exists the CLI that writes a pause is a
+ * different process from the hook that reads it. A daemon may cache this; it
+ * must not own it.
+ *
+ * Expiry is evaluated at READ time against the clock, never by a sweeper. A
+ * stale file is therefore inert rather than dangerous — the failure mode worth
+ * engineering against is not "the pause didn't work", it is "the pause silently
+ * never ended".
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { writeJsonAtomically } from "../../lib/atomic-write";
+import { getAllHookActivityEntries } from "./hook-activity-store";
+import { sessionPauseDir } from "./fp-home";
+
+const SCHEMA_VERSION = 1;
+
+/** Default when `--pause` is given no duration. */
+export const PAUSE_DEFAULT_MS = 30 * 60_000;
+
+/**
+ * Hard ceiling. Config may lower this, never raise it — a ceiling a project
+ * could raise is not a ceiling, and the whole point is that a forgotten pause
+ * costs little.
+ */
+export const PAUSE_CEILING_MS = 8 * 60 * 60_000;
+
+export interface ActivePause {
+  sessionId: string;
+  /** Epoch ms. */
+  pausedAt: number;
+  /**
+   * Epoch ms of the FIRST pause in this unbroken run, which the ceiling is
+   * measured from.
+   *
+   * `pausedAt` moves to now on every renewal, so a ceiling measured from it is
+   * not a ceiling at all: `--pause 8h` every seven hours suspends enforcement
+   * indefinitely, one legal command at a time, and each individual pause passes
+   * every check. This field is what makes 8h mean 8h. Carried forward by
+   * `writePause` while a pause is still live, and reset once one has expired —
+   * the limit is on how long enforcement can stay off in one stretch, not a
+   * daily quota.
+   */
+  firstPausedAt: number;
+  /** Epoch ms. Always finite — there is no unbounded pause. */
+  expiresAt: number;
+  /** Free-form provenance, e.g. "cli". Recorded so the activity log can say who. */
+  setBy: string;
+  /** Where it was issued from, for `--status` and for cwd-based resolution. */
+  cwd?: string;
+}
+
+interface StoredPause extends ActivePause {
+  schemaVersion: number;
+}
+
+export function pauseStateDir(): string {
+  const override = process.env.FAILPROOFAI_STATE_DIR;
+  if (override) return resolve(override, "sessions");
+  return sessionPauseDir();
+}
+
+/**
+ * Filename is a digest of the session id, not the id itself.
+ *
+ * Session ids come from twelve different agent CLIs and are not a format we
+ * control — Hermes and OpenClaw mint their own, and nothing stops one
+ * containing a path separator or `..`. Hashing sidesteps the entire class
+ * rather than trying to enumerate what is safe; the real id is stored inside
+ * the file, so `--status` and `--all` still report it.
+ */
+function pauseFilePath(sessionId: string): string {
+  const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+  return join(pauseStateDir(), `${digest}.json`);
+}
+
+/**
+ * Parse `10m` / `2h` / `90s`, or a bare integer read as minutes.
+ *
+ * Refuses anything over the ceiling rather than silently clamping: someone
+ * typing `--pause 12h` has a expectation about how long enforcement is off,
+ * and quietly giving them 8h is worse than telling them no.
+ */
+export function parsePauseDuration(input: string | undefined, ceilingMs = PAUSE_CEILING_MS): number {
+  if (input === undefined || input === "") return Math.min(PAUSE_DEFAULT_MS, ceilingMs);
+
+  const match = /^(\d+)\s*(s|m|h)?$/i.exec(input.trim());
+  if (!match) {
+    throw new Error(
+      `Invalid duration ${JSON.stringify(input)}. Use e.g. 30m, 2h, 90s (a bare number means minutes).`,
+    );
+  }
+  const value = Number(match[1]);
+  const unit = (match[2] ?? "m").toLowerCase();
+  const ms = unit === "s" ? value * 1000 : unit === "h" ? value * 3_600_000 : value * 60_000;
+
+  if (ms <= 0) throw new Error("Duration must be greater than zero.");
+  if (ms > ceilingMs) {
+    throw new Error(`Duration ${input} exceeds the maximum pause of ${formatDuration(ceilingMs)}.`);
+  }
+  return ms;
+}
+
+/** Human-readable, for CLI output and log reasons. */
+export function formatDuration(ms: number): string {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours}h` : `${hours}h${rest}m`;
+}
+
+function parseStored(raw: unknown): StoredPause | null {
+  if (!raw || typeof raw !== "object") return null;
+  const p = raw as Partial<StoredPause>;
+  if (p.schemaVersion !== SCHEMA_VERSION) return null;
+  if (typeof p.sessionId !== "string" || p.sessionId.length === 0) return null;
+  if (!Number.isFinite(p.pausedAt) || !Number.isFinite(p.expiresAt)) return null;
+  const pausedAt = p.pausedAt as number;
+  // A file written before this field existed measures its ceiling from the
+  // only start it recorded. Same meaning for a pause that was never renewed.
+  const firstPausedAt = Number.isFinite(p.firstPausedAt) ? (p.firstPausedAt as number) : pausedAt;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sessionId: p.sessionId,
+    pausedAt,
+    firstPausedAt,
+    // Clamped at READ time, not only at write. The ceiling has to hold against
+    // a file this process did not write: `~/.failproofai/state/sessions/` is
+    // owner-writable by design, and an `expiresAt` a year out would otherwise
+    // be honoured on every subsequent tool call forever. Enforcing it here
+    // means the bound is a property of the pause, not of the path that created
+    // it.
+    expiresAt: Math.min(p.expiresAt as number, firstPausedAt + PAUSE_CEILING_MS),
+    setBy: typeof p.setBy === "string" ? p.setBy : "unknown",
+    ...(typeof p.cwd === "string" ? { cwd: p.cwd } : {}),
+  };
+}
+
+/**
+ * The active pause for a session, or null.
+ *
+ * Never throws: this is called on the hook path, and a malformed or unreadable
+ * state file must mean "enforcement is ON" rather than crashing the evaluation.
+ * Failing toward enforcement is the only safe direction here.
+ */
+export function readActivePause(sessionId: string | undefined, now = Date.now()): ActivePause | null {
+  if (!sessionId) return null;
+  try {
+    const path = pauseFilePath(sessionId);
+    if (!existsSync(path)) return null;
+    const stored = parseStored(JSON.parse(readFileSync(path, "utf8")));
+    if (!stored) return null;
+    if (stored.expiresAt <= now) return null; // expired — inert, not dangerous
+    const { schemaVersion: _ignored, ...pause } = stored;
+    return pause;
+  } catch {
+    return null;
+  }
+}
+
+export function writePause(opts: {
+  sessionId: string;
+  durationMs: number;
+  cwd?: string;
+  setBy?: string;
+  now?: number;
+}): ActivePause {
+  const now = opts.now ?? Date.now();
+  // Carry the run's original start forward while a pause is still live, so a
+  // renewal extends the same stretch rather than starting a fresh ceiling.
+  const existing = readActivePause(opts.sessionId, now);
+  const firstPausedAt = existing?.firstPausedAt ?? now;
+  const pause: ActivePause = {
+    sessionId: opts.sessionId,
+    pausedAt: now,
+    firstPausedAt,
+    // The requested duration, but never past the ceiling measured from the
+    // start of the run. A renewal can shorten a pause; it cannot outrun 8h.
+    expiresAt: Math.min(now + opts.durationMs, firstPausedAt + PAUSE_CEILING_MS),
+    setBy: opts.setBy ?? "cli",
+    ...(opts.cwd ? { cwd: opts.cwd } : {}),
+  };
+  mkdirSync(pauseStateDir(), { recursive: true, mode: 0o700 });
+  writeJsonAtomically(pauseFilePath(opts.sessionId), { schemaVersion: SCHEMA_VERSION, ...pause });
+  return pause;
+}
+
+/** Returns true if a pause file was removed. */
+export function clearPause(sessionId: string): boolean {
+  const path = pauseFilePath(sessionId);
+  if (!existsSync(path)) return false;
+  try {
+    rmSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every pause that has not yet expired, newest first. Expired files are ignored. */
+export function listActivePauses(now = Date.now()): ActivePause[] {
+  const dir = pauseStateDir();
+  if (!existsSync(dir)) return [];
+  const out: ActivePause[] = [];
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const stored = parseStored(JSON.parse(readFileSync(join(dir, name), "utf8")));
+      if (!stored || stored.expiresAt <= now) continue;
+      const { schemaVersion: _ignored, ...pause } = stored;
+      out.push(pause);
+    } catch {
+      // A single unreadable file must not hide every other pause from --status.
+    }
+  }
+  return out.sort((a, b) => b.pausedAt - a.pausedAt);
+}
+
+/**
+ * The session to act on when the user names none.
+ *
+ * Whoever types the command has no session id — it exists only inside the hook
+ * payload. But every hook event already records `sessionId` alongside `cwd` and
+ * a timestamp, so the most recent session seen in this directory is derivable
+ * from data we already write. Returns null when nothing recent matches, so the
+ * caller can say so instead of guessing at a stranger's session.
+ */
+export function resolveSessionForCwd(cwd: string, maxAgeMs = 12 * 3_600_000, now = Date.now()): string | null {
+  let best: { sessionId: string; timestamp: number } | null = null;
+  let entries;
+  try {
+    entries = getAllHookActivityEntries();
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.sessionId || entry.cwd !== cwd) continue;
+    if (now - entry.timestamp > maxAgeMs) continue;
+    if (!best || entry.timestamp > best.timestamp) {
+      best = { sessionId: entry.sessionId, timestamp: entry.timestamp };
+    }
+  }
+  return best?.sessionId ?? null;
+}

package/src/hooks/setup-state.ts

@@ -0,0 +1,256 @@
+/**
+ * What is already set up on this machine, and where.
+ *
+ * Two questions live here, both of which used to be answered ad hoc in two
+ * different places:
+ *
+ *   1. "Has this user ever completed setup?"  — drives first-run onboarding.
+ *   2. "Is this cwd a project, a home directory, or both?" — drives which
+ *      scope the wizard offers to configure.
+ *
+ * Both are pure functions over the filesystem so they can be unit-tested
+ * without a TTY, a wizard, or a real home directory. Every path is derived
+ * from an injectable `home`/`cwd` rather than read from the environment at
+ * call time, because the wizard, the CLI entry point and the tests each have
+ * a different idea of where "home" is.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { getIntegration } from "./integrations";
+import { INTEGRATION_TYPES } from "./types";
+import { globalPolicyConfigFile, launcherMarker as layoutLauncherMarker } from "./fp-home";
+
+/** Which config a wizard run is going to write. */
+export type SetupTarget = "user" | "project" | "both";
+
+export interface SetupState {
+  /** Absolute cwd this was resolved against. */
+  cwd: string;
+  /** Absolute home directory this was resolved against. */
+  home: string;
+  /**
+   * The directory a project-scope write would land in — the nearest ancestor
+   * holding a `.failproofai/`, else `cwd` itself. Never the home directory:
+   * `~/.failproofai` is the GLOBAL config, and treating it as a project root
+   * would make a wizard run from `~` offer to "configure this project" and
+   * then write the global file under a project label.
+   */
+  projectRoot: string;
+  /** `~/.failproofai/policies-config.json` exists. */
+  hasGlobalConfig: boolean;
+  /** `<projectRoot>/.failproofai/policies-config.json` exists. */
+  hasProjectConfig: boolean;
+  /** Any agent CLI has failproofai hooks installed at user scope. */
+  hasGlobalHooks: boolean;
+  /** The legacy first-run marker written by earlier versions. */
+  hasLegacyMarker: boolean;
+  /** cwd resolves to the home directory itself. */
+  inHomeDir: boolean;
+}
+
+export function globalConfigPath(home: string = homedir()): string {
+  return globalPolicyConfigFile(home);
+}
+
+export function projectConfigPath(projectRoot: string): string {
+  return resolve(projectRoot, ".failproofai", "policies-config.json");
+}
+
+function legacyMarkerPath(home: string): string {
+  return layoutLauncherMarker(home);
+}
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The nearest ancestor of `start` holding a `.failproofai/` directory, or
+ * `start` itself when there is none.
+ *
+ * Mirrors `hooks-config.findProjectConfigDir`, but takes `home` as a
+ * parameter instead of calling `homedir()` — the wizard needs to resolve this
+ * against a caller-supplied home in tests, and the two must not disagree
+ * about where the walk stops or the wizard would offer to write a project
+ * config at a path the policy loader never reads.
+ */
+export function findProjectRoot(start: string, home: string = homedir()): string {
+  // Both sides real-resolved for the same reason `detectSetupState` does it:
+  // a symlinked home would never equal the walked path, so the walk would run
+  // straight past home and could claim `~` — whose `.failproofai/` is the
+  // global config — as a project root.
+  const resolvedHome = realResolve(home);
+  let dir = realResolve(start);
+  while (dir !== resolvedHome) {
+    if (isDir(resolve(dir, ".failproofai"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(start);
+}
+
+/**
+ * Whether any agent CLI carries failproofai hooks at user scope.
+ *
+ * Deliberately ignores project scope: a checkout that happens to contain
+ * committed project hooks (this repo does) must not convince the wizard that
+ * the MACHINE has been set up.
+ */
+export function hasGlobalHooksInstalled(): boolean {
+  for (const id of INTEGRATION_TYPES) {
+    try {
+      if (getIntegration(id).hooksInstalledInSettings("user")) return true;
+    } catch {
+      // A malformed settings file is not evidence of an install.
+    }
+  }
+  return false;
+}
+
+/**
+ * `resolve()` plus symlink resolution, falling back to the lexical path.
+ *
+ * `$HOME` is very often a symlink (`/home/x` → `/mnt/data/x`, macOS
+ * `/tmp` → `/private/tmp`) while a shell's cwd reports the real path. Compared
+ * lexically, the two never match: `inHomeDir` reads false while standing in
+ * home, and the wizard offers to "configure this project" pointing at the home
+ * directory — whose `.failproofai/` is the GLOBAL config. Comparing real paths
+ * is what makes "am I in my home directory" answerable.
+ *
+ * Falls back to the lexical path when the target does not exist (a cwd that
+ * has been deleted, a home that has not been created yet), because a missing
+ * path is not a reason to fail detection.
+ */
+function realResolve(path: string): string {
+  const lexical = resolve(path);
+  try {
+    return realpathSync(lexical);
+  } catch {
+    return lexical;
+  }
+}
+
+export function detectSetupState(
+  cwd: string = process.cwd(),
+  home: string = homedir(),
+): SetupState {
+  const resolvedCwd = realResolve(cwd);
+  const resolvedHome = realResolve(home);
+  const projectRoot = findProjectRoot(resolvedCwd, resolvedHome);
+
+  return {
+    cwd: resolvedCwd,
+    home: resolvedHome,
+    projectRoot,
+    hasGlobalConfig: existsSync(globalConfigPath(resolvedHome)),
+    // When cwd IS home, `projectRoot` is home and its `.failproofai` is the
+    // global config — reporting that as a project config would double-count
+    // one file as two scopes and offer "Both" for a single target.
+    hasProjectConfig:
+      projectRoot !== resolvedHome && existsSync(projectConfigPath(projectRoot)),
+    hasGlobalHooks: hasGlobalHooksInstalled(),
+    hasLegacyMarker: existsSync(legacyMarkerPath(resolvedHome)),
+    inHomeDir: resolvedCwd === resolvedHome,
+  };
+}
+
+/**
+ * Whether this machine has ever completed setup.
+ *
+ * Deliberately NOT just the marker file. The marker is one of three
+ * independent signals, and any of them means "configured":
+ *
+ *   • a global policies-config.json  — the wizard, or `policies --install`,
+ *     has written real configuration
+ *   • user-scope hooks in any agent CLI — enforcement is live even if the
+ *     config file was hand-deleted
+ *   • the legacy marker — so users onboarded by an earlier version are never
+ *     shown the wizard a second time
+ *
+ * Relying on the marker alone made deleting one file re-run onboarding on a
+ * fully configured machine; relying on hooks alone re-ran it for anyone who
+ * had uninstalled hooks but kept their policy config. Requiring all three
+ * would never fire for a genuinely fresh install. The union is the only
+ * combination that is right in each case.
+ */
+export function isConfigured(state: SetupState = detectSetupState()): boolean {
+  return state.hasGlobalConfig || state.hasGlobalHooks || state.hasLegacyMarker;
+}
+
+export interface TargetChoice {
+  label: string;
+  value: SetupTarget;
+  hint: string;
+  /** True when this target would UPDATE existing config rather than create it. */
+  existing: boolean;
+}
+
+/**
+ * The scope choices to offer, ordered so the most likely intent is first
+ * (and therefore pre-selected).
+ *
+ * The ordering rule is "what did the user point us at": run from inside a
+ * project, the project comes first; run from home — where there is no project
+ * to configure — only the global row is offered, because a "Just this
+ * project" row pointing at `~` would write `~/.failproofai/` and call the
+ * machine-wide config a project.
+ */
+export function buildTargetChoices(state: SetupState): TargetChoice[] {
+  const globalRow: TargetChoice = {
+    label: state.hasGlobalConfig ? "Update my global policies" : "Set up global policies",
+    value: "user",
+    hint: "applies in every project on this machine",
+    existing: state.hasGlobalConfig,
+  };
+
+  // From home (or anywhere with no project marker above it) there is no
+  // second target to offer.
+  if (state.inHomeDir || state.projectRoot === state.home) {
+    return [globalRow];
+  }
+
+  const projectRow: TargetChoice = {
+    label: state.hasProjectConfig
+      ? "Update this project's policies"
+      : "Set up this project's policies",
+    value: "project",
+    hint: homeify(state.projectRoot, state.home),
+    existing: state.hasProjectConfig,
+  };
+
+  const bothRow: TargetChoice = {
+    label: "Both",
+    value: "both",
+    hint: "global defaults, plus overrides for this project",
+    existing: state.hasGlobalConfig && state.hasProjectConfig,
+  };
+
+  // Inside a project, the project is the likelier intent — unless nothing
+  // global exists yet, in which case the machine has never been set up and
+  // configuring only this one project would leave every other project
+  // unprotected without saying so.
+  return state.hasGlobalConfig
+    ? [projectRow, globalRow, bothRow]
+    : [globalRow, projectRow, bothRow];
+}
+
+/** `/home/x/y` → `~/y`, for display only. */
+export function homeify(path: string, home: string = homedir()): string {
+  const resolvedHome = resolve(home);
+  const resolvedPath = resolve(path);
+  if (resolvedPath === resolvedHome) return "~";
+  return resolvedPath.startsWith(resolvedHome + "/")
+    ? `~${resolvedPath.slice(resolvedHome.length)}`
+    : resolvedPath;
+}
+
+/** The scopes a `SetupTarget` expands to. */
+export function scopesFor(target: SetupTarget): Array<"user" | "project"> {
+  return target === "both" ? ["user", "project"] : [target];
+}