@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/darwin-keychain-boundary.ts

@@ -0,0 +1,148 @@
+/**
+ * Darwin worker Keychain boundary (issue #704).
+ *
+ * Non-interactive local/worktree workers are spawned with the host environment,
+ * so worker descendants (e.g. `claude doctor` probing Keychain writes through
+ * `security -i`) reach the logged-in user's GUI Keychain session and launch
+ * SecurityAgent dialogs from a supposedly non-interactive cluster.
+ *
+ * On darwin, worker spawn envs get a managed shim directory prepended to PATH
+ * containing a `security` wrapper that fails closed on interactive invocations
+ * (`-i`, `-p`, or no arguments) with a deterministic diagnostic, and execs the
+ * real /usr/bin/security for every other subcommand so provider authentication
+ * (e.g. `security find-generic-password`) keeps working.
+ *
+ * Docker isolation never reaches this code path, and non-darwin platforms are
+ * left untouched. Set ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN=1 to opt out.
+ */
+import { randomUUID } from 'node:crypto';
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
+interface DarwinKeychainBoundaryOptions {
+  platform?: string;
+  shimBaseDir?: string;
+  realSecurityPath?: string;
+}
+const SHIM_DIR_RELATIVE_PATH = path.join('.zeroshot', 'keychain-shim');
+const REAL_SECURITY_PATH = '/usr/bin/security';
+const OPT_OUT_ENV_VAR = 'ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN';
+function shellQuote(value: unknown): string {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+function buildSecurityShimScript(realSecurityPath: string): string {
+  return `#!/bin/sh
+# Managed by Zeroshot (src/darwin-keychain-boundary.js). Do not edit.
+#
+# Non-interactive Zeroshot workers must not open the logged-in user's GUI
+# Keychain session (SecurityAgent). Interactive \`security\` invocations fail
+# closed here; every other subcommand is passed through to the real binary so
+# provider authentication keeps working.
+REAL_SECURITY=${shellQuote(realSecurityPath)}
+if [ "\${${OPT_OUT_ENV_VAR}:-0}" = "1" ]; then
+  exec "$REAL_SECURITY" "$@"
+fi
+fail_closed() {
+  echo "zeroshot: blocked interactive 'security' invocation from a non-interactive worker (argv: $*)." >&2
+  echo "zeroshot: this cluster has no interactive Keychain session, so SecurityAgent prompts are disabled." >&2
+  echo "zeroshot: run the cluster with Docker isolation or configure explicit credentials for the tool that "\
+"attempted Keychain access." >&2
+  echo "zeroshot: set ${OPT_OUT_ENV_VAR}=1 to restore interactive Keychain access." >&2
+  exit 1
+}
+# \`security\` without arguments enters interactive mode.
+[ "$#" -eq 0 ] && fail_closed
+# Global options precede the subcommand. -i (interactive) and -p (prompt,
+# implies -i) must not reach the real binary; option letters may be bundled
+# (e.g. -qi). Scanning stops at the first non-option token (the subcommand).
+for arg in "$@"; do
+  case "$arg" in
+    -*i*|-*p*) fail_closed "$@" ;;
+    -*) ;;
+    *) break ;;
+  esac
+done
+exec "$REAL_SECURITY" "$@"
+`;
+}
+/** Create or refresh the managed directory containing the `security` shim. */
+function ensureDarwinKeychainShimDir(options: DarwinKeychainBoundaryOptions = {}): string {
+  const shimDir = options.shimBaseDir || path.join(os.homedir(), SHIM_DIR_RELATIVE_PATH);
+  const script = buildSecurityShimScript(options.realSecurityPath || REAL_SECURITY_PATH);
+  const shimPath = path.join(shimDir, 'security');
+  fs.mkdirSync(shimDir, { recursive: true });
+  let existing: string | null = null;
+  try {
+    existing = fs.readFileSync(shimPath, 'utf8');
+  } catch {
+    // Missing or unreadable: (re)write below.
+  }
+  if (existing !== script) {
+    const tempPath = path.join(shimDir, `.security.${process.pid}.${randomUUID()}.tmp`);
+    try {
+      fs.writeFileSync(tempPath, script, { mode: 0o755, flag: 'wx' });
+      // The creation mode is subject to umask. Set the final mode before the
+      // rename so the live path is never observable as non-executable.
+      fs.chmodSync(tempPath, 0o755);
+      fs.renameSync(tempPath, shimPath);
+    } catch (error: unknown) {
+      try {
+        // Remove any unpublished partial file without masking the publication
+        // failure that caused this cleanup path.
+        fs.rmSync(tempPath, { force: true });
+      } catch (cleanupError: unknown) {
+        if (error instanceof Error) {
+          error.message += ` Cleanup also failed: ${errorMessage(cleanupError)}.`;
+        }
+      }
+      throw error;
+    }
+  } else {
+    // An existing matching shim may have drifted permissions.
+    fs.chmodSync(shimPath, 0o755);
+  }
+  return shimDir;
+}
+/** Prepend the Keychain boundary shim to a worker spawn environment's PATH. */
+function applyDarwinKeychainBoundaryToEnv(
+  env: NodeJS.ProcessEnv,
+  options: DarwinKeychainBoundaryOptions = {}
+): NodeJS.ProcessEnv {
+  const platform = options.platform || process.platform;
+  if (platform !== 'darwin') {
+    return env;
+  }
+  if (env[OPT_OUT_ENV_VAR] === '1' || process.env[OPT_OUT_ENV_VAR] === '1') {
+    return env;
+  }
+  let shimDir: string;
+  try {
+    shimDir = ensureDarwinKeychainShimDir(options);
+  } catch (error: unknown) {
+    throw new Error(
+      `Failed to install the darwin Keychain boundary shim: ${errorMessage(error)}. ` +
+        `Non-interactive workers must not reach the interactive Keychain session; ` +
+        `use Docker isolation or set ${OPT_OUT_ENV_VAR}=1 to opt out.`
+    );
+  }
+  // Darwin environment keys are case-sensitive: descendants consult PATH,
+  // never a differently-cased key such as Path. Preserve empty components
+  // because POSIX interprets them as the current directory. An absent PATH
+  // retains Node/libuv's default Unix search path after the shim, while an
+  // explicitly empty PATH retains its empty component (`<shim>:`).
+  const existingEntries =
+    env.PATH === undefined
+      ? ['/usr/bin', '/bin']
+      : String(env.PATH)
+          .split(path.delimiter)
+          .filter((entry) => entry !== shimDir);
+  env.PATH = [shimDir, ...existingEntries].join(path.delimiter);
+  return env;
+}
+export = {
+  applyDarwinKeychainBoundaryToEnv,
+  ensureDarwinKeychainShimDir,
+};

package/src/guidance-topics.js

@@ -1,10 +1,9 @@
+"use strict";
 const USER_GUIDANCE_CLUSTER = 'USER_GUIDANCE_CLUSTER';
 const USER_GUIDANCE_AGENT = 'USER_GUIDANCE_AGENT';
-
 const GUIDANCE_TOPICS = [USER_GUIDANCE_CLUSTER, USER_GUIDANCE_AGENT];
-
 module.exports = {
-  USER_GUIDANCE_CLUSTER,
-  USER_GUIDANCE_AGENT,
-  GUIDANCE_TOPICS,
+    USER_GUIDANCE_CLUSTER,
+    USER_GUIDANCE_AGENT,
+    GUIDANCE_TOPICS,
 };

package/src/guidance-topics.ts

@@ -0,0 +1,10 @@
+const USER_GUIDANCE_CLUSTER = 'USER_GUIDANCE_CLUSTER';
+const USER_GUIDANCE_AGENT = 'USER_GUIDANCE_AGENT';
+
+const GUIDANCE_TOPICS = [USER_GUIDANCE_CLUSTER, USER_GUIDANCE_AGENT] as const;
+
+export = {
+  USER_GUIDANCE_CLUSTER,
+  USER_GUIDANCE_AGENT,
+  GUIDANCE_TOPICS,
+};

package/src/input-helpers.js

@@ -1,3 +1,6 @@
+"use strict";
+const fs = require("fs");
+const path = require("path");
 /**
  * Input Helpers - Create input data from text or files
  *
@@ -5,61 +8,37 @@
  * - Plain text input
  * - File input (markdown)
  */
-
-const fs = require('fs');
-const path = require('path');
-
 class InputHelpers {
-  /**
-   * Create a plain text input wrapper
-   * @param {String} text - Plain text input
-   * @returns {Object} Structured context
-   */
-  static createTextInput(text) {
-    return {
-      number: null,
-      title: 'Manual Input',
-      body: text,
-      labels: [],
-      comments: [],
-      url: null,
-      context: `# Manual Input\n\n${text}\n`,
-    };
-  }
-
-  /**
-   * Create input from markdown file
-   * @param {String} filePath - Path to markdown file (.md or .markdown)
-   * @returns {Object} Structured context matching issue format
-   */
-  static createFileInput(filePath) {
-    // Resolve relative paths
-    const resolvedPath = path.resolve(filePath);
-
-    // Validate file exists
-    if (!fs.existsSync(resolvedPath)) {
-      throw new Error(`File not found: ${filePath}`);
+    static createTextInput(text) {
+        return {
+            number: null,
+            title: 'Manual Input',
+            body: text,
+            labels: [],
+            comments: [],
+            url: null,
+            context: `# Manual Input\n\n${text}\n`,
+        };
+    }
+    static createFileInput(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const fileContent = fs.readFileSync(resolvedPath, 'utf8');
+        const headerMatch = /^#\s+(.+)$/m.exec(fileContent);
+        const extractedTitle = headerMatch?.[1]?.trim() ?? null;
+        const fallbackTitle = path.basename(filePath, path.extname(filePath));
+        const title = extractedTitle || fallbackTitle;
+        return {
+            number: null,
+            title,
+            body: fileContent,
+            labels: [],
+            comments: [],
+            url: null,
+            context: `# ${title}\n\n${fileContent}\n`,
+        };
     }
-
-    // Read file content
-    const fileContent = fs.readFileSync(resolvedPath, 'utf8');
-
-    // Extract title from first header or use filename
-    const headerMatch = fileContent.match(/^#\s+(.+)$/m);
-    const extractedTitle = headerMatch ? headerMatch[1].trim() : null;
-    const fallbackTitle = path.basename(filePath, path.extname(filePath));
-    const title = extractedTitle || fallbackTitle;
-
-    return {
-      number: null,
-      title,
-      body: fileContent,
-      labels: [],
-      comments: [],
-      url: null,
-      context: `# ${title}\n\n${fileContent}\n`,
-    };
-  }
 }
-
 module.exports = InputHelpers;

package/src/input-helpers.ts

@@ -0,0 +1,58 @@
+import fs = require('fs');
+import path = require('path');
+
+interface ManualInput {
+  number: null;
+  title: string;
+  body: string;
+  labels: unknown[];
+  comments: unknown[];
+  url: null;
+  context: string;
+}
+
+/**
+ * Input Helpers - Create input data from text or files
+ *
+ * Provides fallback input methods for non-issue-based input:
+ * - Plain text input
+ * - File input (markdown)
+ */
+class InputHelpers {
+  static createTextInput(text: string): ManualInput {
+    return {
+      number: null,
+      title: 'Manual Input',
+      body: text,
+      labels: [],
+      comments: [],
+      url: null,
+      context: `# Manual Input\n\n${text}\n`,
+    };
+  }
+
+  static createFileInput(filePath: string): ManualInput {
+    const resolvedPath = path.resolve(filePath);
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const fileContent = fs.readFileSync(resolvedPath, 'utf8');
+    const headerMatch = /^#\s+(.+)$/m.exec(fileContent);
+    const extractedTitle = headerMatch?.[1]?.trim() ?? null;
+    const fallbackTitle = path.basename(filePath, path.extname(filePath));
+    const title = extractedTitle || fallbackTitle;
+
+    return {
+      number: null,
+      title,
+      body: fileContent,
+      labels: [],
+      comments: [],
+      url: null,
+      context: `# ${title}\n\n${fileContent}\n`,
+    };
+  }
+}
+
+export = InputHelpers;

package/src/ledger-sequence.js

@@ -1,63 +1,60 @@
+"use strict";
 const MAX_SQLITE_ROWID = 9223372036854775807n;
 const CANONICAL_SEQUENCE = /^(0|[1-9][0-9]*)$/;
-
 function canonicalMessageSequence(value, name = 'message sequence') {
-  let sequence;
-  if (typeof value === 'string' && CANONICAL_SEQUENCE.test(value)) {
-    sequence = value;
-  } else if (Number.isSafeInteger(value) && value >= 0) {
-    // Accept legacy JSON state while normalizing every new boundary to a
-    // JSON-safe decimal string.
-    sequence = String(value);
-  } else {
-    throw new TypeError(`${name} must be a canonical non-negative decimal string`);
-  }
-
-  if (BigInt(sequence) > MAX_SQLITE_ROWID) {
-    throw new RangeError(`${name} exceeds the SQLite rowid range`);
-  }
-  return sequence;
+    let sequence;
+    if (typeof value === 'string' && CANONICAL_SEQUENCE.test(value)) {
+        sequence = value;
+    }
+    else if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+        // Accept legacy JSON state while normalizing every new boundary to a
+        // JSON-safe decimal string.
+        sequence = String(value);
+    }
+    else {
+        throw new TypeError(`${name} must be a canonical non-negative decimal string`);
+    }
+    if (BigInt(sequence) > MAX_SQLITE_ROWID) {
+        throw new RangeError(`${name} exceeds the SQLite rowid range`);
+    }
+    return sequence;
 }
-
 function messageSequenceFromSql(value, name = 'message sequence') {
-  if (typeof value === 'bigint') {
-    if (value < 0n || value > MAX_SQLITE_ROWID) {
-      throw new RangeError(`${name} is outside the SQLite rowid range`);
+    if (typeof value === 'bigint') {
+        if (value < 0n || value > MAX_SQLITE_ROWID) {
+            throw new RangeError(`${name} is outside the SQLite rowid range`);
+        }
+        return value.toString();
     }
-    return value.toString();
-  }
-  return canonicalMessageSequence(value, name);
+    return canonicalMessageSequence(value, name);
 }
-
 function messageSequenceToSql(value, name = 'message sequence') {
-  return BigInt(canonicalMessageSequence(value, name));
+    return BigInt(canonicalMessageSequence(value, name));
 }
-
 function compareMessageSequences(left, right) {
-  const leftValue = messageSequenceToSql(left, 'left message sequence');
-  const rightValue = messageSequenceToSql(right, 'right message sequence');
-  if (leftValue < rightValue) {
-    return -1;
-  }
-  if (leftValue > rightValue) {
-    return 1;
-  }
-  return 0;
+    const leftValue = messageSequenceToSql(left, 'left message sequence');
+    const rightValue = messageSequenceToSql(right, 'right message sequence');
+    if (leftValue < rightValue) {
+        return -1;
+    }
+    if (leftValue > rightValue) {
+        return 1;
+    }
+    return 0;
 }
-
 function tryCanonicalMessageSequence(value) {
-  try {
-    return canonicalMessageSequence(value);
-  } catch {
-    return null;
-  }
+    try {
+        return canonicalMessageSequence(value);
+    }
+    catch {
+        return null;
+    }
 }
-
 module.exports = {
-  MAX_SQLITE_ROWID,
-  canonicalMessageSequence,
-  compareMessageSequences,
-  messageSequenceFromSql,
-  messageSequenceToSql,
-  tryCanonicalMessageSequence,
+    MAX_SQLITE_ROWID,
+    canonicalMessageSequence,
+    compareMessageSequences,
+    messageSequenceFromSql,
+    messageSequenceToSql,
+    tryCanonicalMessageSequence,
 };

package/src/ledger-sequence.ts

@@ -0,0 +1,63 @@
+const MAX_SQLITE_ROWID = 9223372036854775807n;
+const CANONICAL_SEQUENCE = /^(0|[1-9][0-9]*)$/;
+
+function canonicalMessageSequence(value: unknown, name = 'message sequence'): string {
+  let sequence: string;
+  if (typeof value === 'string' && CANONICAL_SEQUENCE.test(value)) {
+    sequence = value;
+  } else if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    // Accept legacy JSON state while normalizing every new boundary to a
+    // JSON-safe decimal string.
+    sequence = String(value);
+  } else {
+    throw new TypeError(`${name} must be a canonical non-negative decimal string`);
+  }
+
+  if (BigInt(sequence) > MAX_SQLITE_ROWID) {
+    throw new RangeError(`${name} exceeds the SQLite rowid range`);
+  }
+  return sequence;
+}
+
+function messageSequenceFromSql(value: unknown, name = 'message sequence'): string {
+  if (typeof value === 'bigint') {
+    if (value < 0n || value > MAX_SQLITE_ROWID) {
+      throw new RangeError(`${name} is outside the SQLite rowid range`);
+    }
+    return value.toString();
+  }
+  return canonicalMessageSequence(value, name);
+}
+
+function messageSequenceToSql(value: unknown, name = 'message sequence'): bigint {
+  return BigInt(canonicalMessageSequence(value, name));
+}
+
+function compareMessageSequences(left: unknown, right: unknown): -1 | 0 | 1 {
+  const leftValue = messageSequenceToSql(left, 'left message sequence');
+  const rightValue = messageSequenceToSql(right, 'right message sequence');
+  if (leftValue < rightValue) {
+    return -1;
+  }
+  if (leftValue > rightValue) {
+    return 1;
+  }
+  return 0;
+}
+
+function tryCanonicalMessageSequence(value: unknown): string | null {
+  try {
+    return canonicalMessageSequence(value);
+  } catch {
+    return null;
+  }
+}
+
+export = {
+  MAX_SQLITE_ROWID,
+  canonicalMessageSequence,
+  compareMessageSequences,
+  messageSequenceFromSql,
+  messageSequenceToSql,
+  tryCanonicalMessageSequence,
+};

package/src/legacy-lib/clusters-registry.ts

@@ -0,0 +1,40 @@
+/**
+ * Single read/write path for clusters.json.
+ *
+ * All callers that need the raw registry (Orchestrator, id-detector, gc,
+ * socket-discovery, CLI) go through readClustersFileSync/writeClustersFileAtomic
+ * instead of ad-hoc JSON.parse(fs.readFileSync(...)) / fs.writeFileSync(...).
+ *
+ * Writes are atomic (temp file + rename) so a reader can never observe a
+ * partially-written file, even without taking the write lock. Callers that
+ * read-modify-write (Orchestrator._saveClusters) still need proper-lockfile
+ * around the whole operation to avoid losing concurrent updates.
+ */
+
+import fs = require('fs');
+import path = require('path');
+
+function clustersFilePath(storageDir: string): string {
+  return path.join(storageDir, 'clusters.json');
+}
+
+/** Read clusters.json. Returns an empty registry if the file is missing. */
+function readClustersFileSync(storageDir: string): unknown {
+  const clustersFile = clustersFilePath(storageDir);
+  if (!fs.existsSync(clustersFile)) {
+    return {};
+  }
+  const raw = fs.readFileSync(clustersFile, 'utf8');
+  const parsed: unknown = JSON.parse(raw);
+  return parsed;
+}
+
+/** Write clusters.json atomically through a process-scoped temporary file. */
+function writeClustersFileAtomic(storageDir: string, data: unknown): void {
+  const clustersFile = clustersFilePath(storageDir);
+  const tmpPath = `${clustersFile}.tmp-${process.pid}`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpPath, clustersFile);
+}
+
+export = { clustersFilePath, readClustersFileSync, writeClustersFileAtomic };