@the-open-engine/zeroshot 6.38.1 → 6.39.1

package/src/copy-worker.ts

@@ -0,0 +1,88 @@
+/**
+ * Copy Worker - Worker thread for parallel file copying
+ *
+ * Handles copying a batch of files from source to destination.
+ * Used by IsolationManager._copyDirExcluding() for parallel copying.
+ */
+import fs = require('fs');
+import { parentPort, workerData } from 'worker_threads';
+import {
+  copyErrorCode,
+  createCopyBoundary,
+  isCopyContainmentError,
+  isCopyRecord,
+  resolveCopyPath,
+} from './copy-containment';
+import type { CopyBoundary } from './copy-containment';
+interface CopyWorkerData {
+  files: string[];
+  sourceBase: string;
+  destBase: string;
+  expectedBoundary: CopyBoundary;
+}
+interface CopyError {
+  file: string;
+  name: string;
+  code: string | null;
+  message: string;
+  relativePath: unknown;
+}
+function isCopyWorkerData(value: unknown): value is CopyWorkerData {
+  if (!isCopyRecord(value)) {
+    return false;
+  }
+  return (
+    Array.isArray(value.files) &&
+    value.files.every((entry: unknown) => typeof entry === 'string') &&
+    typeof value.sourceBase === 'string' &&
+    typeof value.destBase === 'string' &&
+    isCopyRecord(value.expectedBoundary)
+  );
+}
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+const rawWorkerData: unknown = workerData;
+if (!isCopyWorkerData(rawWorkerData)) {
+  throw new TypeError('copy worker requires files, sourceBase, and destBase');
+}
+const { files, sourceBase, destBase, expectedBoundary } = rawWorkerData;
+const copyBoundary = createCopyBoundary(sourceBase, destBase, expectedBoundary);
+let copied = 0;
+let skipped = 0;
+let error: CopyError | null = null;
+for (const relativePath of files) {
+  try {
+    // Phase two creates every parent directory. Re-resolve the source and
+    // destination immediately before the only worker filesystem effect.
+    const { sourcePath, destinationPath } = resolveCopyPath(copyBoundary, relativePath);
+    fs.copyFileSync(sourcePath, destinationPath);
+    copied++;
+  } catch (caughtError: unknown) {
+    // Skip files we can't copy (permission denied, broken symlinks, etc.)
+    const code = copyErrorCode(caughtError);
+    if (
+      !isCopyContainmentError(caughtError) &&
+      (code === 'EACCES' || code === 'EPERM' || code === 'ENOENT')
+    ) {
+      skipped++;
+      continue;
+    }
+    error = {
+      file: relativePath,
+      name: caughtError instanceof Error ? caughtError.name : 'Error',
+      code,
+      message: errorMessage(caughtError),
+      relativePath:
+        isCopyRecord(caughtError) && 'relativePath' in caughtError
+          ? caughtError.relativePath
+          : relativePath,
+    };
+    break;
+  }
+}
+// Report results back to main thread
+if (!parentPort) {
+  throw new Error('copy worker requires a parent port');
+}
+parentPort.postMessage({ copied, skipped, error });

package/src/darwin-keychain-boundary.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Darwin worker Keychain boundary (issue #704).
  *
@@ -15,46 +16,41 @@
  * Docker isolation never reaches this code path, and non-darwin platforms are
  * left untouched. Set ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN=1 to opt out.
  */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { randomUUID } = require('node:crypto');
-
+const node_crypto_1 = require("node:crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 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) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-
 function buildSecurityShimScript(realSecurityPath) {
-  return `#!/bin/sh
+    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: 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).
@@ -65,110 +61,83 @@ for arg in "$@"; do
     *) break ;;
   esac
 done
-
 exec "$REAL_SECURITY" "$@"
 `;
 }
-
-/**
- * Create (or refresh) the managed shim directory containing the `security`
- * wrapper. Idempotent: the script is only rewritten when its content changes.
- *
- * @param {object} [options]
- * @param {string} [options.shimBaseDir] - Shim directory (tests only); defaults to ~/.zeroshot/keychain-shim.
- * @param {string} [options.realSecurityPath] - Real binary to exec (tests only); defaults to /usr/bin/security.
- * @returns {string} Absolute path of the shim directory.
- */
+/** Create or refresh the managed directory containing the `security` shim. */
 function ensureDarwinKeychainShimDir(options = {}) {
-  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 = 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`);
+    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 = null;
     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) {
-      try {
-        // Remove any unpublished partial file without masking the publication
-        // failure that caused this cleanup path.
-        fs.rmSync(tempPath, { force: true });
-      } catch (cleanupError) {
-        error.message += ` Cleanup also failed: ${cleanupError.message}.`;
-      }
-      throw error;
+        existing = fs.readFileSync(shimPath, 'utf8');
+    }
+    catch {
+        // Missing or unreadable: (re)write below.
     }
-  } else {
-    // An existing matching shim may have drifted permissions.
-    fs.chmodSync(shimPath, 0o755);
-  }
-
-  return shimDir;
+    if (existing !== script) {
+        const tempPath = path.join(shimDir, `.security.${process.pid}.${(0, node_crypto_1.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) {
+            try {
+                // Remove any unpublished partial file without masking the publication
+                // failure that caused this cleanup path.
+                fs.rmSync(tempPath, { force: true });
+            }
+            catch (cleanupError) {
+                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 env's PATH.
- *
- * No-op off darwin and when the operator opted out via
- * ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN=1. Fails closed (throws) when the shim
- * cannot be installed: spawning the worker anyway would silently re-expose the
- * interactive Keychain session.
- *
- * @param {object} env - Spawn env to mutate (also returned).
- * @param {object} [options]
- * @param {string} [options.platform] - Platform override (tests only).
- * @param {string} [options.shimBaseDir] - See ensureDarwinKeychainShimDir.
- * @param {string} [options.realSecurityPath] - See ensureDarwinKeychainShimDir.
- * @returns {object} The same env object.
- */
+/** Prepend the Keychain boundary shim to a worker spawn environment's PATH. */
 function applyDarwinKeychainBoundaryToEnv(env, options = {}) {
-  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') {
+    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;
+    try {
+        shimDir = ensureDarwinKeychainShimDir(options);
+    }
+    catch (error) {
+        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;
-  }
-
-  let shimDir;
-  try {
-    shimDir = ensureDarwinKeychainShimDir(options);
-  } catch (error) {
-    throw new Error(
-      `Failed to install the darwin Keychain boundary shim: ${error.message}. ` +
-        `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;
 }
-
 module.exports = {
-  applyDarwinKeychainBoundaryToEnv,
-  ensureDarwinKeychainShimDir,
+    applyDarwinKeychainBoundaryToEnv,
+    ensureDarwinKeychainShimDir,
 };

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;