@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/ai/profiles.js

@@ -0,0 +1,61 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var profiles_exports = {};
+__export(profiles_exports, {
+  EDIT_ONLY_PROFILE: () => EDIT_ONLY_PROFILE,
+  FULL_FIX_PROFILE: () => FULL_FIX_PROFILE,
+  READ_ONLY_PROFILE: () => READ_ONLY_PROFILE
+});
+module.exports = __toCommonJS(profiles_exports);
+const READ_ONLY_PROFILE = {
+  allow: [],
+  disallow: ["Bash", "Edit", "MultiEdit", "Write"],
+  permissionMode: "dontAsk",
+  tools: ["Glob", "Grep", "Read", "WebFetch", "WebSearch"]
+};
+const EDIT_ONLY_PROFILE = {
+  allow: [],
+  disallow: ["Bash", "WebFetch", "WebSearch"],
+  permissionMode: "acceptEdits",
+  tools: ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+};
+const FULL_FIX_PROFILE = {
+  allow: [
+    "Bash(git status:*)",
+    "Bash(git diff:*)",
+    "Bash(git log:*)",
+    "Bash(git add:*)",
+    "Bash(git commit:*)",
+    "Bash(node:*)",
+    "Bash(pnpm exec:*)",
+    "Bash(pnpm run:*)",
+    "Bash(pnpm test:*)"
+  ],
+  disallow: ["WebFetch", "WebSearch"],
+  permissionMode: "acceptEdits",
+  tools: ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EDIT_ONLY_PROFILE,
+  FULL_FIX_PROFILE,
+  READ_ONLY_PROFILE
+});

package/dist/ai/spawn.d.mts

@@ -0,0 +1,49 @@
+/**
+ * @file Locked-down spawn for AI agent CLIs (Claude / Codex / Gemini /
+ *   OpenCode). Per the CLAUDE.md "Programmatic Claude calls" rule: every
+ *   headless invocation MUST set the four lockdown flags (tools / disallow /
+ *   permissionMode / no-session-persistence). The helper enforces this at the
+ *   type level (`SpawnAiAgentOptions` requires the relevant fields) AND at the
+ *   spawn site (per-agent flag translator). Why CLI subprocess instead of an
+ *   SDK call: the fleet's contract matches what the local user sees when
+ *   invoking the CLI — same auth config, same model availability, same tool
+ *   permissions. SDK calls would diverge on auth handling and force per-agent
+ *   SDK installs. Retry: 3 attempts on overload (HTTP 529 / "Overloaded"), exp.
+ *   backoff (5s / 15s / 45s). Each retry is a fresh subprocess.
+ */
+import type { AgentSpawnResult, AiAgentName, SpawnAiAgentOptions } from './types.mts';
+export declare function backoffFor(attempt: number): number;
+/**
+ * Build CLI arg list for a given agent. The flag names differ across agents but
+ * the conceptual surface is the same: "here are the allowed tools, here are the
+ * denied tools, here is the permission mode, do not persist a session." This
+ * translator is the single source of truth for how each agent's flags map.
+ *
+ * Update sites (when an agent changes its flag surface): 1. The relevant case
+ * below. 2. The agent's docs link (cited inline).
+ */
+export declare function buildArgs(agent: AiAgentName, opts: SpawnAiAgentOptions): string[];
+export declare function isOverloaded(stdout: string, stderr: string): boolean;
+export declare function pickAgent(requested: AiAgentName | undefined, cwd: string): Promise<AiAgentName>;
+/**
+ * Spawn an AI agent CLI subprocess with the locked-down flag set.
+ *
+ * @example
+ *   ```ts
+ *   import { EDIT_ONLY_PROFILE } from '@socketsecurity/lib/ai/profiles'
+ *   import { spawnAiAgent } from '@socketsecurity/lib/ai/spawn'
+ *
+ *   const result = await spawnAiAgent({
+ *   ...EDIT_ONLY_PROFILE,
+ *   prompt: 'Fix the lint findings in src/foo.ts',
+ *   cwd: process.cwd(),
+ *   model: 'claude-sonnet-4-6',
+ *   timeoutMs: 5 * 60 * 1000,
+ *   })
+ *   if (result.exitCode !== 0) { ... }
+ *   ```
+ *
+ *   Throws when the requested agent isn't on PATH (or, when no agent
+ *   is requested, when none of the known agents are on PATH).
+ */
+export declare function spawnAiAgent(opts: SpawnAiAgentOptions): Promise<AgentSpawnResult>;

package/dist/ai/spawn.js

@@ -0,0 +1,207 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var spawn_exports = {};
+__export(spawn_exports, {
+  backoffFor: () => backoffFor,
+  buildArgs: () => buildArgs,
+  isOverloaded: () => isOverloaded,
+  pickAgent: () => pickAgent,
+  spawnAiAgent: () => spawnAiAgent
+});
+module.exports = __toCommonJS(spawn_exports);
+var import_message = require("../errors/message");
+var import_object = require("../primordials/object");
+var import_child = require("../process/spawn/child");
+var import_errors = require("../process/spawn/errors");
+var import_discover = require("./discover");
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 5e3;
+function backoffFor(attempt) {
+  return BACKOFF_BASE_MS * 3 ** (attempt - 1);
+}
+function buildArgs(agent, opts) {
+  const allAllowed = [...opts.tools, ...opts.allow ?? []];
+  switch (agent) {
+    case "claude": {
+      const args = [
+        "--print",
+        "--no-session-persistence",
+        "--permission-mode",
+        opts.permissionMode,
+        "--add-dir",
+        opts.cwd
+      ];
+      for (const dir of opts.addDirs ?? []) {
+        args.push("--add-dir", dir);
+      }
+      if (opts.model) {
+        args.push("--model", opts.model);
+      }
+      if (allAllowed.length > 0) {
+        args.push("--allowedTools", ...allAllowed);
+      }
+      if (opts.disallow.length > 0) {
+        args.push("--disallowedTools", ...opts.disallow);
+      }
+      if (opts.extraArgs) {
+        args.push(...opts.extraArgs);
+      }
+      return args;
+    }
+    case "codex": {
+      const args = ["--print"];
+      if (opts.permissionMode === "plan") {
+        args.push("--read-only");
+      }
+      if (opts.model) {
+        args.push("--model", opts.model);
+      }
+      if (allAllowed.length > 0) {
+        args.push("--tools", allAllowed.join(","));
+      }
+      if (opts.disallow.length > 0) {
+        args.push("--disallow-tools", opts.disallow.join(","));
+      }
+      args.push("--cwd", opts.cwd);
+      if (opts.extraArgs) {
+        args.push(...opts.extraArgs);
+      }
+      return args;
+    }
+    case "gemini": {
+      const args = ["--no-interactive", "--workspace", opts.cwd];
+      if (opts.model) {
+        args.push("--model", opts.model);
+      }
+      if (allAllowed.length > 0) {
+        args.push("--allowed-tools", allAllowed.join(","));
+      }
+      if (opts.disallow.length > 0) {
+        args.push("--denied-tools", opts.disallow.join(","));
+      }
+      if (opts.permissionMode === "plan") {
+        args.push("--read-only");
+      }
+      if (opts.extraArgs) {
+        args.push(...opts.extraArgs);
+      }
+      return args;
+    }
+    case "opencode": {
+      const args = ["--print", "--cwd", opts.cwd];
+      if (opts.model) {
+        args.push("--model", opts.model);
+      }
+      if (allAllowed.length > 0) {
+        args.push("--tools", allAllowed.join(","));
+      }
+      if (opts.disallow.length > 0) {
+        args.push("--no-tools", opts.disallow.join(","));
+      }
+      if (opts.extraArgs) {
+        args.push(...opts.extraArgs);
+      }
+      return args;
+    }
+  }
+}
+function isOverloaded(stdout, stderr) {
+  const re = /API Error: 529|Overloaded/i;
+  return re.test(stdout) || re.test(stderr);
+}
+async function pickAgent(requested, cwd) {
+  const discovered = await (0, import_discover.discoverAiAgents)({ repoRoot: cwd });
+  if (requested) {
+    if (!(requested in discovered)) {
+      throw new Error(
+        `spawnAiAgent: requested agent "${requested}" is not on PATH. Install the CLI or pass a different agent. Discovered: ${(0, import_object.ObjectKeys)(discovered).join(", ") || "(none)"}`
+      );
+    }
+    return requested;
+  }
+  if ("claude" in discovered) {
+    return "claude";
+  }
+  for (const candidate of ["codex", "opencode", "gemini"]) {
+    if (candidate in discovered) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    "spawnAiAgent: no AI agent CLI on PATH. Install one of: claude, codex, opencode, gemini."
+  );
+}
+async function spawnAiAgent(opts) {
+  const agent = await pickAgent(opts.agent, opts.cwd);
+  const args = buildArgs(agent, opts);
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+  let attempts = 0;
+  const start = Date.now();
+  while (attempts < MAX_ATTEMPTS) {
+    attempts += 1;
+    stdout = "";
+    stderr = "";
+    exitCode = 0;
+    try {
+      const child = (0, import_child.spawn)(agent, args, {
+        cwd: opts.cwd,
+        stdio: "pipe",
+        stdioString: true,
+        timeout: opts.timeoutMs
+      });
+      child.stdin?.end(opts.prompt);
+      const result = await child;
+      stdout = String(result.stdout ?? "");
+      stderr = String(result.stderr ?? "");
+      exitCode = result.code ?? 0;
+    } catch (e) {
+      if ((0, import_errors.isSpawnError)(e)) {
+        stdout = String(e.stdout ?? "");
+        stderr = String(e.stderr ?? "");
+        exitCode = e.code ?? 1;
+      } else {
+        stderr = (0, import_message.errorMessage)(e);
+        exitCode = 1;
+      }
+    }
+    if (!isOverloaded(stdout, stderr) || attempts >= MAX_ATTEMPTS) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, backoffFor(attempts)));
+  }
+  return {
+    attempts,
+    durationMs: Date.now() - start,
+    exitCode,
+    stderr,
+    stdout
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  backoffFor,
+  buildArgs,
+  isOverloaded,
+  pickAgent,
+  spawnAiAgent
+});

package/dist/ai/types.d.mts

@@ -0,0 +1,117 @@
+/**
+ * @file Shared types for the locked-down AI agent surface. The fleet runs
+ *   Claude / Codex / OpenCode / Gemini through CLI subprocesses, never via SDK
+ *   calls. These types model the cross- agent contract: a permission mode, a
+ *   tool allowlist, a tool denylist, a prompt, a working directory. Per-agent
+ *   flag translation lives in `spawn.ts` — callers pass the uniform
+ *   `SpawnAiAgentOptions` and the helper produces the right CLI args for the
+ *   chosen agent.
+ */
+/**
+ * The set of AI agents the helper can drive. Each must be installed as a CLI on
+ * PATH; discovery happens via `discoverAiAgents()`.
+ */
+export type AiAgentName = 'claude' | 'codex' | 'gemini' | 'opencode';
+/**
+ * Permission mode passed to the agent's CLI. The fleet rule (CLAUDE.md
+ * "Programmatic Claude calls") requires every headless call to set one of these
+ * explicitly — never the agent's default.
+ *
+ * - `acceptEdits` — Edit/Write proceed without prompting. Required for fix-mode
+ *   skills; `dontAsk` would DENY rather than auto-accept.
+ * - `dontAsk` — read-only / no-mutation use. AskUserQuestion calls are
+ *   suppressed.
+ * - `plan` — research / proposal mode. The agent can read but cannot write or run
+ *   tools that mutate state.
+ */
+export type PermissionMode = 'acceptEdits' | 'dontAsk' | 'plan';
+/**
+ * Result of an agent spawn. Consumers should inspect `exitCode` before using
+ * `stdout` — non-zero usually means the agent's CLI itself rejected, not just
+ * that the prompt failed.
+ */
+export interface AgentSpawnResult {
+    readonly attempts: number;
+    readonly durationMs: number;
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/**
+ * Inputs to a single agent spawn.
+ *
+ * Required: `prompt`, `cwd`, `tools`, `disallow`, `permissionMode`.
+ *
+ * Pre-built profiles in `profiles.ts` cover the common shapes
+ * (READ_ONLY_PROFILE, EDIT_ONLY_PROFILE) — callers spread the profile and
+ * override per-call (model, timeout, addDirs).
+ *
+ * Why the lockdown fields are required (not defaulted to a permissive shape):
+ * the CLAUDE.md rule says "all four lockdown flags MUST be set on every spawn."
+ * Making them required at the type level is the type-system version of that
+ * rule.
+ */
+export interface SpawnAiAgentOptions {
+    /**
+     * Optional explicit agent. Defaults to claude when discovered.
+     */
+    readonly agent?: AiAgentName;
+    /**
+     * Allow-list extras (Bash glob patterns, MCP tools, etc.).
+     */
+    readonly allow?: readonly string[];
+    /**
+     * Extra dirs the agent can read (e.g. parent of cwd for monorepo).
+     */
+    readonly addDirs?: readonly string[];
+    /**
+     * Tool denylist — required to enforce the lockdown.
+     */
+    readonly disallow: readonly string[];
+    /**
+     * Override the agent's flag list (rare; for one-off advanced cases).
+     */
+    readonly extraArgs?: readonly string[];
+    /**
+     * Model name override; agent default if absent.
+     */
+    readonly model?: string;
+    /**
+     * Permission mode — see PermissionMode docstring.
+     */
+    readonly permissionMode: PermissionMode;
+    /**
+     * The prompt sent on stdin.
+     */
+    readonly prompt: string;
+    /**
+     * Repository / working directory for the agent.
+     */
+    readonly cwd: string;
+    /**
+     * Per-call timeout (ms). Caller should set for predictable bounds.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Tool allowlist. Required to enforce the lockdown.
+     */
+    readonly tools: readonly string[];
+}
+/**
+ * The cwd-aware "is this binary on PATH?" snapshot. Each entry is the absolute
+ * path resolved by `which`; missing agents are absent from the map (not
+ * present-with-undefined).
+ */
+export type DiscoveredAgents = Readonly<Partial<Record<AiAgentName, string>>>;
+/**
+ * Cleanup policy for `spawnAiAgentsInWorktrees`. Default 'always'.
+ *
+ * - `always` — remove the worktree after the per-item function returns,
+ *   regardless of success/failure or whether changes were committed. Matches
+ *   the "leave no trace" expectation.
+ * - `never` — never auto-remove. Caller (or human inspector) cleans up. Useful
+ *   for debugging.
+ * - `on-empty` — remove only if the worktree had no changes (committed or
+ *   staged). Preserves evidence on failure.
+ */
+export type WorktreeCleanup = 'always' | 'never' | 'on-empty';

package/dist/ai/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/ai/worktree.d.mts

@@ -0,0 +1,104 @@
+/**
+ * @file Run AI agents in parallel, each in its own git worktree, and merge
+ *   results back to the base branch. The fleet's CLAUDE.md "Parallel Claude
+ *   sessions" rule mandates worktree isolation when multiple agents touch the
+ *   same checkout. This helper enforces that contract: each item gets a fresh
+ *   worktree branched from the base, the per-item function runs inside it, then
+ *   the helper either fast-forward-merges the worktree branch back into the
+ *   base (when changes were committed) or removes the worktree silently (when
+ *   no changes happened). Concurrency: caller-controlled with a default cap of
+ *   4. Per the "Programmatic Claude calls" CLAUDE.md rule, very high
+ *   concurrency saturates the API rate limits; 4 is safe headroom for most
+ *   accounts. The hard cap of 8 prevents accidental flag-finger disasters.
+ *   Cleanup policy: see `WorktreeCleanup` in types.mts. Default 'always' —
+ *   fail-or-pass, the worktree is removed.
+ */
+import type { WorktreeCleanup } from './types.mts';
+export interface WorktreeRunOptions {
+    /**
+     * Base repo path (the primary checkout).
+     */
+    readonly baseRepo: string;
+    /**
+     * Branch to merge results into. Default: current branch of baseRepo.
+     */
+    readonly branch?: string;
+    /**
+     * Cleanup policy. Default 'always'.
+     */
+    readonly cleanup?: WorktreeCleanup;
+    /**
+     * Parallel cap. Default 4, max 8.
+     */
+    readonly concurrency?: number;
+    /**
+     * Prefix for worktree branch + dir names. Default 'agent-task'.
+     */
+    readonly namePrefix?: string;
+    /**
+     * Where worktrees live on disk. Default: `${tmpdir}/${prefix}-<n>`.
+     */
+    readonly worktreeRoot?: string;
+}
+export interface WorktreeRunContext {
+    /**
+     * Worktree dir on disk.
+     */
+    readonly cwd: string;
+    /**
+     * Branch name created for this worktree.
+     */
+    readonly branch: string;
+    /**
+     * 0-indexed item position.
+     */
+    readonly index: number;
+}
+export interface WorktreeRunSettled<T> {
+    readonly cleanup: 'removed' | 'kept';
+    readonly error?: unknown;
+    readonly merged: boolean;
+    readonly status: 'fulfilled' | 'rejected';
+    readonly value?: T | undefined;
+    readonly worktreePath: string;
+}
+export declare function currentBranch(repo: string): string;
+export declare function git(cwd: string, ...args: string[]): string;
+export declare function hasCommittedChanges(worktree: string, baseBranch: string): boolean;
+export declare function hasStagedOrUnstaged(worktree: string): boolean;
+export declare function runOne<I, T>(item: I, index: number, worktreeBranch: string, worktreePath: string, baseRepo: string, branch: string, cleanup: WorktreeCleanup, fn: (item: I, ctx: WorktreeRunContext) => Promise<T>): Promise<WorktreeRunSettled<T>>;
+/**
+ * Run `fn` for each item in parallel, each invocation isolated in its own git
+ * worktree. Results are merged back into the base branch with `git merge
+ * --ff-only`; non-FF merges are reported as failures and the worktree is
+ * preserved (regardless of cleanup policy).
+ *
+ * @example
+ *   ;```ts
+ *   import { spawnAiAgentsInWorktrees } from '@socketsecurity/lib/ai/worktree'
+ *   import { spawnAiAgent } from '@socketsecurity/lib/ai/spawn'
+ *   import { EDIT_ONLY_PROFILE } from '@socketsecurity/lib/ai/profiles'
+ *
+ *   const repos = ['socket-addon', 'socket-btm', 'socket-lib']
+ *   const settled = await spawnAiAgentsInWorktrees(
+ *     repos,
+ *     async ({ cwd }) => {
+ *       return await spawnAiAgent({
+ *         ...EDIT_ONLY_PROFILE,
+ *         prompt: 'Run the cleanup task',
+ *         cwd,
+ *       })
+ *     },
+ *     {
+ *       baseRepo: '/Users/<user>/projects/socket-wheelhouse',
+ *       concurrency: 3,
+ *       cleanup: 'on-empty',
+ *     },
+ *   )
+ *   ```
+ */
+export declare function spawnAiAgentsInWorktrees<I, T>(items: readonly I[], fn: (item: I, ctx: WorktreeRunContext) => Promise<T>, options: WorktreeRunOptions): Promise<ReadonlyArray<WorktreeRunSettled<T>>>;
+export declare function tryGit(cwd: string, ...args: string[]): {
+    ok: boolean;
+    output: string;
+};