@intutic/sync-daemon 1.9.0 → 1.10.1

package/dist/lib/egressPolicy.js

@@ -0,0 +1,126 @@
+/**
+ * egressPolicy.ts — ships the workspace's central egress policy *to* the
+ * machine, so an admin sets `enforce`/`monitor` + an allow list once in the
+ * control plane rather than in every developer's local proxy config
+ * (LLD #63 §4). Mirrors `policySnapshot.ts` / `approvedBypasses.ts`: fetch from
+ * the control plane, write a local artifact under `.intutic/hooks` with
+ * integrity headers, and let the consumer (here the Rust proxy) read it.
+ *
+ * # The contract with the proxy
+ *
+ * `.intutic/hooks/egress-policy.json` — same directory as the policy snapshot
+ * and for the same reason: `.intutic/hooks` is in `UNIVERSAL_PROTECTED_PATHS`,
+ * so a gate already refuses an agent's own write there. The file carries its
+ * own integrity: `digest` (sha256 of a canonical `mode\nallow…` string, first
+ * 32 hex) and `workspace`. The proxy recomputes the digest and refuses a file
+ * whose digest or workspace does not match, keeping its config-derived policy
+ * instead — a corrupt or foreign file degrades to "local config", never to a
+ * weaker enforcement than the operator configured.
+ *
+ * `mode: null` means "central management not configured": the proxy keeps its
+ * local `intutic_settings.egress` / `INTUTIC_EGRESS_MODE`. A `mode` of
+ * `off`/`monitor`/`enforce` is authoritative for the mode; the `allow` list is
+ * UNIONed with the proxy's local allow entries so a developer's local infra
+ * allowances are never dropped.
+ *
+ * @module
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { createHash } from 'node:crypto';
+import { createLogger } from '@intutic/logger';
+const log = createLogger('sync-egress-policy');
+export const DEFAULT_EGRESS_CACHE_DIR = path.join(os.homedir(), '.intutic', 'hooks');
+export const EGRESS_POLICY_FILE = 'egress-policy.json';
+/**
+ * Trims trailing `/` without a regex — see the identical helper in
+ * `approvedBypasses.ts`: `/\/+$/` is flagged by CodeQL as a polynomial-time
+ * pattern on external input, and a loop sidesteps the whole category.
+ */
+function trimTrailingSlashes(s) {
+    let end = s.length;
+    while (end > 0 && s.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return s.slice(0, end);
+}
+/**
+ * The canonical string the digest is computed over — identical on the daemon
+ * (here) and the proxy (Rust `load_local_egress_file`), so both derive the same
+ * digest. Mode (or empty) then each allow entry, newline-joined. Allow entries
+ * are hosts/CIDRs and never contain newlines.
+ */
+export function egressDigestInput(mode, allow) {
+    return [mode ?? '', ...allow].join('\n');
+}
+/** Fetch this workspace's central egress policy. Returns null on any failure —
+ *  the caller keeps the previous cache file rather than replacing it with
+ *  nothing, the same rule the policy snapshot follows. */
+export async function fetchWorkspaceEgressPolicy(opts) {
+    const url = `${trimTrailingSlashes(opts.controlPlaneUrl)}/api/v1/workspace/egress-policy` +
+        `?workspaceId=${encodeURIComponent(opts.workspaceId)}`;
+    try {
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${opts.apiKey}`, 'x-workspace-id': opts.workspaceId },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            log.warn({ action: 'egress_fetch_failed', status: res.status }, 'egress-policy returned non-OK');
+            return null;
+        }
+        const body = (await res.json());
+        if (typeof body !== 'object' || body === null)
+            return null;
+        const rec = body;
+        const mode = rec.mode === 'off' || rec.mode === 'monitor' || rec.mode === 'enforce' ? rec.mode : null;
+        const allow = Array.isArray(rec.allow)
+            ? rec.allow.filter((a) => typeof a === 'string' && a.length > 0)
+            : [];
+        return { mode, allow };
+    }
+    catch (err) {
+        log.warn({ action: 'egress_fetch_failed', err }, 'egress-policy unreachable');
+        return null;
+    }
+}
+/** Write the cache file atomically, digest + workspace header included — same
+ *  read-only-by-rename posture as the policy snapshot. Exported so a test can
+ *  assert the on-disk shape directly. */
+export async function writeEgressPolicy(policy, workspaceId, cacheDir = DEFAULT_EGRESS_CACHE_DIR) {
+    const digest = createHash('sha256')
+        .update(egressDigestInput(policy.mode, policy.allow))
+        .digest('hex')
+        .slice(0, 32);
+    const doc = {
+        workspace: workspaceId,
+        digest,
+        generated: new Date().toISOString(),
+        mode: policy.mode,
+        allow: policy.allow,
+    };
+    const text = JSON.stringify(doc, null, 2) + '\n';
+    await fs.mkdir(cacheDir, { recursive: true });
+    const target = path.join(cacheDir, EGRESS_POLICY_FILE);
+    const tmp = target + '.tmp';
+    await fs.writeFile(tmp, text, { encoding: 'utf-8' });
+    await fs.chmod(tmp, 0o444);
+    await fs.rename(tmp, target);
+    log.debug({ action: 'egress_policy_written', digest, mode: policy.mode, count: policy.allow.length, dir: cacheDir }, 'Egress policy cache refreshed');
+    return { digest, mode: policy.mode };
+}
+/** Fetch and write in one call. Safe to run on every sync cycle. Never throws —
+ *  a failed poll must not take down the sync loop, and leaves the previous
+ *  cache in place. */
+export async function refreshEgressPolicy(opts) {
+    const policy = await fetchWorkspaceEgressPolicy(opts);
+    if (policy === null)
+        return null;
+    try {
+        return await writeEgressPolicy(policy, opts.workspaceId, opts.cacheDir ?? DEFAULT_EGRESS_CACHE_DIR);
+    }
+    catch (err) {
+        log.warn({ action: 'egress_policy_write_failed', err }, 'Could not write egress-policy cache');
+        return null;
+    }
+}
+//# sourceMappingURL=egressPolicy.js.map

package/dist/lib/egressPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egressPolicy.js","sourceRoot":"","sources":["../../src/lib/egressPolicy.ts"],"names":[],"mappings":"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"}

package/dist/lib/gitWorktrees.d.ts

@@ -0,0 +1,140 @@
+/**
+ * gitWorktrees.ts — discovers every `git worktree` checkout of a repo the
+ * sync daemon is watching, so project-tier governance files can be written
+ * into each one, not just the main checkout.
+ *
+ * # The gap this closes
+ *
+ * `git worktree add <path>` creates a second, fully independent WORKING
+ * TREE that shares the main checkout's `.git` object store (via a `.git`
+ * FILE pointing back at `<main>/.git/worktrees/<name>`) but has its own
+ * untracked files. Every project-tier governance file this product writes
+ * — `.claude/settings.json`, `.cursor/hooks.json`, `.intutic/hooks/*`,
+ * `AGENTS.md`'s sibling hook registrations, the wrapped `.mcp.json` entries,
+ * etc. — is untracked by convention (SOP content is workspace-specific and
+ * synced from the control plane, not committed). That means none of it
+ * exists in a worktree's working tree by default: `writeConfigFiles`/
+ * `injectMcpServer` running against only the main checkout's `workspaceRoot`
+ * leaves every OTHER worktree of that same repo completely ungoverned,
+ * regardless of what the main checkout has configured.
+ *
+ * This was already true for any hand-rolled `git worktree` workflow before
+ * this module existed — Xirp (an orchestrator that spawns CLI agents each
+ * inside its own tmux session + git worktree, see `tools/cli/src/harness/
+ * xirp.ts`) is what surfaced it, but the fix here is general: it benefits
+ * ANY worktree-based workflow, Xirp-managed or not. See TD-390.
+ *
+ * # Verifying the mechanics for real
+ *
+ * Confirmed against a real throwaway repo during this module's development
+ * (not asserted from memory of git's docs): an untracked file written into
+ * a main checkout is NOT visible from a `git worktree add`-created sibling
+ * checkout's directory. `git worktree list --porcelain`'s block format,
+ * including `locked`/`prunable`/`bare`/`detached` fields, was captured from
+ * a real `git worktree list --porcelain` run (this module's own test suite
+ * builds the same kind of fixture, in an isolated temp directory, rather
+ * than relying on this description alone).
+ *
+ * @module
+ */
+/** One block of `git worktree list --porcelain` output, parsed. */
+export interface WorktreeInfo {
+    /** Absolute path to this worktree's working directory. */
+    path: string;
+    /** Commit the worktree's HEAD points at, or null if not reported (bare). */
+    head: string | null;
+    /** Branch ref this worktree has checked out (e.g. `refs/heads/main`), or
+     *  null when detached or bare. */
+    branch: string | null;
+    /** True if this worktree's HEAD is detached (no branch checked out). */
+    detached: boolean;
+    /** True for the bare-repository worktree entry — the repo root itself
+     *  when it has no working tree of its own files (only ever the first
+     *  entry, and only for a bare repo). */
+    bare: boolean;
+    /** True if this worktree is locked (`git worktree lock`) — git will not
+     *  prune it even if its directory looks gone. Locking does not restrict
+     *  reading or writing ordinary files in it, so this does not by itself
+     *  change whether `discoverWorktrees` includes the path. */
+    locked: boolean;
+    /** Reason string passed to `git worktree lock --reason`, if any. */
+    lockedReason: string | null;
+    /** True if git has flagged this worktree's directory as missing/invalid
+     *  and a candidate for `git worktree prune`. */
+    prunable: boolean;
+    /** Reason string git reports for why this worktree is prunable, if any. */
+    prunableReason: string | null;
+}
+/**
+ * Parses `git worktree list --porcelain` output.
+ *
+ * Real format (verified against a live `git worktree list --porcelain` run,
+ * git 2.x): one block per worktree, separated by a blank line, each line a
+ * bare keyword or `<keyword> <value>`:
+ *
+ * ```
+ * worktree /path/to/main
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * branch refs/heads/master
+ *
+ * worktree /path/to/locked-wt
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * branch refs/heads/feature2
+ * locked testing lock
+ *
+ * worktree /path/to/detached-wt
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * detached
+ * ```
+ *
+ * Deliberately implemented with plain string methods (`startsWith`/`slice`)
+ * rather than a line-matching regex — this parses `git`-controlled, not
+ * attacker-controlled, input, but a sibling Wave 1 phase shipped a
+ * CodeQL-flagged polynomial-regex bug from exactly this kind of "just trim
+ * a path" text handling, so the same class of construct is avoided here on
+ * principle even though the input source differs.
+ */
+export declare function parseWorktreeListPorcelain(output: string): WorktreeInfo[];
+/**
+ * Discovers every worktree of the git repository containing `repoRoot`,
+ * returning the absolute paths that should be treated as additional
+ * project-tier workspace roots.
+ *
+ * Filtering decisions, made explicit rather than left implicit:
+ *
+ * - **The main checkout is included.** `git worktree list` always lists it
+ *   first (confirmed against a live run) — it needs no special-casing by
+ *   callers; a caller that already writes to `repoRoot` directly can simply
+ *   skip a returned path equal to `repoRoot` if it wants to avoid a
+ *   redundant duplicate write, but the list is uniformly correct either way.
+ * - **Locked worktrees are included.** `git worktree lock` only prevents
+ *   git's own pruning of a worktree it cannot otherwise verify still
+ *   exists (e.g. on removable storage) — it says nothing about whether the
+ *   directory is currently present and writable, which it normally is.
+ *   Excluding locked worktrees would silently under-cover a workflow (like
+ *   Xirp's) that locks worktrees deliberately to protect them from being
+ *   pruned out from under a long-running session — exactly the worktrees
+ *   most worth covering.
+ * - **Prunable worktrees are EXCLUDED.** `prunable` means git itself has
+ *   flagged the worktree's directory as missing or otherwise administratively
+ *   invalid. Writing into that path would either fail or (via this
+ *   codebase's `mkdir(dir, { recursive: true })` write convention) silently
+ *   RECREATE a directory git considers gone — resurrecting a deleted
+ *   worktree's folder with governance files nobody asked for. Skipping it
+ *   is what "don't write into a directory git says isn't really there"
+ *   means in practice.
+ * - **Bare-repository entries are EXCLUDED.** A bare repo's own `worktree`
+ *   porcelain entry names its root path but has no working tree of ordinary
+ *   files to write project-tier config into.
+ *
+ * Best-effort by design: returns `[]` (never throws) if `repoRoot` is not
+ * inside a git repository, if `git` is not on `PATH`, or on any other
+ * failure — this is additive coverage on top of the existing single-root
+ * write path, so a git failure here must not break the sync cycle that
+ * already succeeds for the main `workspaceRoot`. This also means a
+ * non-worktree, single-checkout project (the common case) is a harmless
+ * no-extra-work path: `git worktree list` still runs, still succeeds, and
+ * returns exactly one entry (the main checkout itself).
+ */
+export declare function discoverWorktrees(repoRoot: string): Promise<string[]>;
+//# sourceMappingURL=gitWorktrees.d.ts.map

package/dist/lib/gitWorktrees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitWorktrees.d.ts","sourceRoot":"","sources":["../../src/lib/gitWorktrees.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAOH,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;sCACkC;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;IACjB;;4CAEwC;IACxC,IAAI,EAAE,OAAO,CAAA;IACb;;;gEAG4D;IAC5D,MAAM,EAAE,OAAO,CAAA;IACf,oEAAoE;IACpE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B;oDACgD;IAChD,QAAQ,EAAE,OAAO,CAAA;IACjB,2EAA2E;IAC3E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAuDzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgB3E"}

package/dist/lib/gitWorktrees.js

@@ -0,0 +1,191 @@
+/**
+ * gitWorktrees.ts — discovers every `git worktree` checkout of a repo the
+ * sync daemon is watching, so project-tier governance files can be written
+ * into each one, not just the main checkout.
+ *
+ * # The gap this closes
+ *
+ * `git worktree add <path>` creates a second, fully independent WORKING
+ * TREE that shares the main checkout's `.git` object store (via a `.git`
+ * FILE pointing back at `<main>/.git/worktrees/<name>`) but has its own
+ * untracked files. Every project-tier governance file this product writes
+ * — `.claude/settings.json`, `.cursor/hooks.json`, `.intutic/hooks/*`,
+ * `AGENTS.md`'s sibling hook registrations, the wrapped `.mcp.json` entries,
+ * etc. — is untracked by convention (SOP content is workspace-specific and
+ * synced from the control plane, not committed). That means none of it
+ * exists in a worktree's working tree by default: `writeConfigFiles`/
+ * `injectMcpServer` running against only the main checkout's `workspaceRoot`
+ * leaves every OTHER worktree of that same repo completely ungoverned,
+ * regardless of what the main checkout has configured.
+ *
+ * This was already true for any hand-rolled `git worktree` workflow before
+ * this module existed — Xirp (an orchestrator that spawns CLI agents each
+ * inside its own tmux session + git worktree, see `tools/cli/src/harness/
+ * xirp.ts`) is what surfaced it, but the fix here is general: it benefits
+ * ANY worktree-based workflow, Xirp-managed or not. See TD-390.
+ *
+ * # Verifying the mechanics for real
+ *
+ * Confirmed against a real throwaway repo during this module's development
+ * (not asserted from memory of git's docs): an untracked file written into
+ * a main checkout is NOT visible from a `git worktree add`-created sibling
+ * checkout's directory. `git worktree list --porcelain`'s block format,
+ * including `locked`/`prunable`/`bare`/`detached` fields, was captured from
+ * a real `git worktree list --porcelain` run (this module's own test suite
+ * builds the same kind of fixture, in an isolated temp directory, rather
+ * than relying on this description alone).
+ *
+ * @module
+ */
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFile = promisify(_execFile);
+/**
+ * Parses `git worktree list --porcelain` output.
+ *
+ * Real format (verified against a live `git worktree list --porcelain` run,
+ * git 2.x): one block per worktree, separated by a blank line, each line a
+ * bare keyword or `<keyword> <value>`:
+ *
+ * ```
+ * worktree /path/to/main
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * branch refs/heads/master
+ *
+ * worktree /path/to/locked-wt
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * branch refs/heads/feature2
+ * locked testing lock
+ *
+ * worktree /path/to/detached-wt
+ * HEAD 56bdba0a04f83da4e821a0a3e7a6208d43fcaec5
+ * detached
+ * ```
+ *
+ * Deliberately implemented with plain string methods (`startsWith`/`slice`)
+ * rather than a line-matching regex — this parses `git`-controlled, not
+ * attacker-controlled, input, but a sibling Wave 1 phase shipped a
+ * CodeQL-flagged polynomial-regex bug from exactly this kind of "just trim
+ * a path" text handling, so the same class of construct is avoided here on
+ * principle even though the input source differs.
+ */
+export function parseWorktreeListPorcelain(output) {
+    const blocks = output.split('\n\n');
+    const worktrees = [];
+    for (const block of blocks) {
+        const trimmedBlock = block.trim();
+        if (!trimmedBlock)
+            continue;
+        let path = '';
+        let head = null;
+        let branch = null;
+        let detached = false;
+        let bare = false;
+        let locked = false;
+        let lockedReason = null;
+        let prunable = false;
+        let prunableReason = null;
+        for (const rawLine of trimmedBlock.split('\n')) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            if (line === 'bare') {
+                bare = true;
+            }
+            else if (line === 'detached') {
+                detached = true;
+            }
+            else if (line.startsWith('worktree ')) {
+                path = line.slice('worktree '.length).trim();
+            }
+            else if (line.startsWith('HEAD ')) {
+                head = line.slice('HEAD '.length).trim();
+            }
+            else if (line.startsWith('branch ')) {
+                branch = line.slice('branch '.length).trim();
+            }
+            else if (line === 'locked') {
+                locked = true;
+            }
+            else if (line.startsWith('locked ')) {
+                locked = true;
+                lockedReason = line.slice('locked '.length).trim() || null;
+            }
+            else if (line === 'prunable') {
+                prunable = true;
+            }
+            else if (line.startsWith('prunable ')) {
+                prunable = true;
+                prunableReason = line.slice('prunable '.length).trim() || null;
+            }
+            // Any other line is a porcelain field this parser does not know about
+            // yet (git has added a few over the years) — ignored rather than
+            // treated as an error, so a future git version adding a new field
+            // degrades gracefully instead of breaking discovery entirely.
+        }
+        if (path) {
+            worktrees.push({ path, head, branch, detached, bare, locked, lockedReason, prunable, prunableReason });
+        }
+    }
+    return worktrees;
+}
+/**
+ * Discovers every worktree of the git repository containing `repoRoot`,
+ * returning the absolute paths that should be treated as additional
+ * project-tier workspace roots.
+ *
+ * Filtering decisions, made explicit rather than left implicit:
+ *
+ * - **The main checkout is included.** `git worktree list` always lists it
+ *   first (confirmed against a live run) — it needs no special-casing by
+ *   callers; a caller that already writes to `repoRoot` directly can simply
+ *   skip a returned path equal to `repoRoot` if it wants to avoid a
+ *   redundant duplicate write, but the list is uniformly correct either way.
+ * - **Locked worktrees are included.** `git worktree lock` only prevents
+ *   git's own pruning of a worktree it cannot otherwise verify still
+ *   exists (e.g. on removable storage) — it says nothing about whether the
+ *   directory is currently present and writable, which it normally is.
+ *   Excluding locked worktrees would silently under-cover a workflow (like
+ *   Xirp's) that locks worktrees deliberately to protect them from being
+ *   pruned out from under a long-running session — exactly the worktrees
+ *   most worth covering.
+ * - **Prunable worktrees are EXCLUDED.** `prunable` means git itself has
+ *   flagged the worktree's directory as missing or otherwise administratively
+ *   invalid. Writing into that path would either fail or (via this
+ *   codebase's `mkdir(dir, { recursive: true })` write convention) silently
+ *   RECREATE a directory git considers gone — resurrecting a deleted
+ *   worktree's folder with governance files nobody asked for. Skipping it
+ *   is what "don't write into a directory git says isn't really there"
+ *   means in practice.
+ * - **Bare-repository entries are EXCLUDED.** A bare repo's own `worktree`
+ *   porcelain entry names its root path but has no working tree of ordinary
+ *   files to write project-tier config into.
+ *
+ * Best-effort by design: returns `[]` (never throws) if `repoRoot` is not
+ * inside a git repository, if `git` is not on `PATH`, or on any other
+ * failure — this is additive coverage on top of the existing single-root
+ * write path, so a git failure here must not break the sync cycle that
+ * already succeeds for the main `workspaceRoot`. This also means a
+ * non-worktree, single-checkout project (the common case) is a harmless
+ * no-extra-work path: `git worktree list` still runs, still succeeds, and
+ * returns exactly one entry (the main checkout itself).
+ */
+export async function discoverWorktrees(repoRoot) {
+    try {
+        const { stdout } = await execFile('git', ['worktree', 'list', '--porcelain'], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            timeout: 5000,
+        });
+        return parseWorktreeListPorcelain(stdout)
+            .filter((wt) => !wt.bare && !wt.prunable)
+            .map((wt) => wt.path);
+    }
+    catch {
+        // Not a git repo, git not installed, or a transient failure — additive
+        // coverage, so this degrades to "no extra worktrees found", not a
+        // thrown error the caller must handle.
+        return [];
+    }
+}
+//# sourceMappingURL=gitWorktrees.js.map

package/dist/lib/gitWorktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitWorktrees.js","sourceRoot":"","sources":["../../src/lib/gitWorktrees.ts"],"names":[],"mappings":"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"}