@secemp/elwood 0.1.0

package/src/loader.js

@@ -0,0 +1,306 @@
+/**
+ * loader.js
+ *
+ * Ties together locate → parse → instrument → load.
+ *
+ * The instrumented code is written to a temp `.mjs` file under
+ * `/tmp/elwood-<hash>/` and loaded via dynamic `import()` so that:
+ *  - The original ESM imports inside cli.js are honoured by the Node.js
+ *    loader (they cannot be executed inside vm.runInNewContext).
+ *  - We keep the hook injection clean — no eval(), no new Function().
+ *
+ * Teardown removes the temp directory when the caller is done.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { locate } from './locate.js';
+import { parseBundle, generateCode } from './ast-tools.js';
+import { injectHooks, detectBundlerPattern, extractFunctionMap, findCliExports, injectCliExports } from './instrumenter.js';
+
+// ---------------------------------------------------------------------------
+// Types (JSDoc)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} LoadOptions
+ * @property {string}          [cliPath]          - Override the auto-located cli.js path.
+ * @property {boolean}         [instrument]       - Enable/disable instrumentation (default: true).
+ * @property {(string|RegExp)[]} [intercept]      - Function name patterns to intercept.
+ * @property {string}          [hookVar]          - Global hook-registry name (default: '__elwoodHooks').
+ * @property {boolean}         [wrapApiCalls]     - Wrap fetch() API calls (default: true).
+ * @property {boolean}         [wrapToolExecutions] - Wrap tool-execution patterns (default: true).
+ * @property {boolean}         [wrapAsyncGenerators] - Wrap async generators (default: true).
+ * @property {boolean}         [wrapFunctionCalls] - Wrap matched function declarations (default: true).
+ * @property {string}          [tempDir]          - Custom temp directory base (default: os.tmpdir()).
+ * @property {boolean}         [keepTemp]         - Do not delete temp files on teardown (default: false).
+ * @property {boolean}         [verbose]          - Print progress messages (default: false).
+ */
+
+/**
+ * @typedef {Object} LoadResult
+ * @property {any}      module       - The default export of the dynamically imported module.
+ * @property {any}      exports      - All named exports of the dynamically imported module.
+ * @property {string}   tempFile     - Path to the temp instrumented file.
+ * @property {string}   cliPath      - Resolved path to cli.js.
+ * @property {string}   version      - cli.js package version string.
+ * @property {number}   patchCount   - Number of hook-injection sites inserted.
+ * @property {HookPoint[]} hookPoints - Metadata about each injection.
+ * @property {BundlerInfo} bundlerInfo - Detected bundler metadata.
+ * @property {() => void} teardown   - Call this to delete the temp file when done.
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a short content-addressed hash for a string.
+ *
+ * @param {string} content
+ * @returns {string} 12-character hex string
+ */
+function contentHash(content) {
+  return createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+/**
+ * Write `content` to a fresh temp directory and return the file path.
+ *
+ * @param {string} content     - JS source to write
+ * @param {string} baseTmpDir  - base temp directory (e.g. /tmp)
+ * @param {boolean} keepTemp   - if true, skip any existing temp to avoid re-parse
+ * @returns {{ filePath: string, dir: string, isReused: boolean }}
+ */
+function writeTempModule(content, baseTmpDir, keepTemp) {
+  const hash = contentHash(content);
+  const dir = join(baseTmpDir, `elwood-${hash}`);
+  const filePath = join(dir, 'bundle.mjs');
+
+  if (keepTemp && existsSync(filePath)) {
+    return { filePath, dir, isReused: true };
+  }
+
+  mkdirSync(dir, { recursive: true });
+
+  // Write a package.json so Node treats this directory as ESM
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    writeFileSync(pkgPath, JSON.stringify({ type: 'module' }, null, 2), 'utf8');
+  }
+
+  writeFileSync(filePath, content, 'utf8');
+  return { filePath, dir, isReused: false };
+}
+
+/**
+ * Remove a temp directory tree.
+ *
+ * @param {string} dir
+ */
+function removeTempDir(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup — ignore errors
+  }
+}
+
+// ---------------------------------------------------------------------------
+// instrument()
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse and instrument a CLI bundle in memory, returning the generated code.
+ *
+ * This is the lower-level API — it does not load/import anything.
+ *
+ * @param {LoadOptions} [options]
+ * @returns {Promise<{
+ *   code: string,
+ *   cliPath: string,
+ *   version: string,
+ *   patchCount: number,
+ *   hookPoints: import('./instrumenter.js').HookPoint[],
+ *   bundlerInfo: import('./instrumenter.js').BundlerInfo,
+ *   cliExportsFound: import('./instrumenter.js').CliExports | null,
+ * }>}
+ */
+async function instrument(options = {}) {
+  const {
+    cliPath: cliPathOverride,
+    instrument: doInstrument = true,
+    intercept = [],
+    hookVar = '__elwoodHooks',
+    wrapApiCalls = true,
+    wrapToolExecutions = true,
+    wrapAsyncGenerators = true,
+    wrapFunctionCalls = true,
+    verbose = false,
+  } = options;
+
+  const log = verbose ? (...args) => console.log('[elwood]', ...args) : () => {};
+
+  // ── 1. Locate cli.js ──────────────────────────────────────────────────────
+  log('Locating Claude Code CLI...');
+  const location = cliPathOverride
+    ? {
+        cliPath: cliPathOverride,
+        sdkPath: null,
+        packageDir: '',
+        version: 'unknown',
+      }
+    : await locate();
+
+  const { cliPath, version } = location;
+  log(`Found: ${cliPath} (v${version})`);
+
+  // ── 2. Parse ──────────────────────────────────────────────────────────────
+  const originalSource = readFileSync(cliPath, 'utf8');
+  const fileSizeMB = (originalSource.length / 1024 / 1024).toFixed(2);
+  log(`Parsing ${fileSizeMB} MB bundle...`);
+
+  const ast = parseBundle(cliPath);
+  log('Parse complete.');
+
+  // ── 3. Detect bundler pattern ─────────────────────────────────────────────
+  log('Detecting bundler pattern...');
+  const bundlerInfo = detectBundlerPattern(ast);
+  log(`Bundler: ${bundlerInfo.bundler} (${bundlerInfo.clues[0] ?? 'unknown'})`);
+
+  // ── 4. Instrument ─────────────────────────────────────────────────────────
+  let patchCount = 0;
+  let hookPoints = [];
+
+  if (doInstrument) {
+    log('Injecting hooks...');
+    const result = injectHooks(ast, {
+      intercept,
+      hookVar,
+      wrapApiCalls,
+      wrapToolExecutions,
+      wrapAsyncGenerators,
+      wrapFunctionCalls,
+    });
+    patchCount = result.patchCount;
+    hookPoints = result.hookPoints;
+    log(`Injected ${patchCount} hook site(s) across ${hookPoints.length} function(s).`);
+  } else {
+    log('Instrumentation disabled — passing bundle through unchanged.');
+  }
+
+  // ── 4b. Find and inject CLI exports (agentLoop, appStateFactory, guard) ────
+  let cliExportsFound = null;
+  if (doInstrument) {
+    log('Fingerprinting CLI exports (agentLoop, appStateFactory)...');
+    try {
+      cliExportsFound = findCliExports(ast);
+      log(
+        `Found agentLoop="${cliExportsFound.agentLoop?.name}" ` +
+        `(confidence=${cliExportsFound.agentLoop?.confidence?.toFixed(2)}), ` +
+        `appStateFactory="${cliExportsFound.appStateFactory?.name}" ` +
+        `(confidence=${cliExportsFound.appStateFactory?.confidence?.toFixed(2)})`
+      );
+      injectCliExports(ast, cliExportsFound);
+      log('CLI export injections applied.');
+    } catch (err) {
+      log(`Warning: CLI export fingerprinting failed: ${err.message}`);
+      // Non-fatal: hooks still work, but query() won't be available
+    }
+  }
+
+  // ── 5. Generate code ──────────────────────────────────────────────────────
+  // Pass originalSource so @babel/generator uses source-range-based generation,
+  // preserving original minified identifier names (e.g. MC1, be, Be5, Ga0).
+  // Without this, @babel/generator regenerates identifiers from AST node IDs,
+  // producing different names (e.g. Hi8, ft8) that don't match the safeRef() calls
+  // in the injected register code.
+  log('Generating instrumented code...');
+  const { code } = generateCode(ast, {}, originalSource);
+  log(`Generated ${(code.length / 1024 / 1024).toFixed(2)} MB.`);
+
+  return { code, cliPath, version, patchCount, hookPoints, bundlerInfo, cliExportsFound };
+}
+
+// ---------------------------------------------------------------------------
+// load()
+// ---------------------------------------------------------------------------
+
+/**
+ * Full pipeline: locate → parse → instrument → write temp file → dynamic import.
+ *
+ * @param {LoadOptions} [options]
+ * @returns {Promise<LoadResult>}
+ */
+async function load(options = {}) {
+  const {
+    tempDir: tempDirBase = tmpdir(),
+    keepTemp = false,
+    verbose = false,
+  } = options;
+
+  const log = verbose ? (...args) => console.log('[elwood]', ...args) : () => {};
+
+  // ── Steps 1-5: instrument ─────────────────────────────────────────────────
+  const { code, cliPath, version, patchCount, hookPoints, bundlerInfo, cliExportsFound } =
+    await instrument(options);
+
+  // ── 6. Write to temp file ─────────────────────────────────────────────────
+  const { filePath: tempFile, dir: tempDirPath, isReused } = writeTempModule(
+    code,
+    tempDirBase,
+    keepTemp
+  );
+
+  if (isReused) {
+    log(`Reusing cached temp file: ${tempFile}`);
+  } else {
+    log(`Written instrumented bundle to: ${tempFile}`);
+  }
+
+  // ── 7. Dynamic import ─────────────────────────────────────────────────────
+  log('Dynamically importing instrumented bundle...');
+  let mod;
+  try {
+    mod = await import(/* @vite-ignore */ tempFile);
+  } catch (importErr) {
+    // Provide a helpful error message that distinguishes instrumentation
+    // problems from genuine cli.js errors.
+    throw new Error(
+      `elwood: Failed to import instrumented bundle at ${tempFile}.\n` +
+      `This may indicate an instrumentation error.  Try load({ instrument: false })\n` +
+      `to verify the original bundle imports cleanly.\n\n` +
+      `Underlying error: ${importErr.message}`
+    );
+  }
+  log('Import successful.');
+
+  // ── 8. Build result ────────────────────────────────────────────────────────
+  const exports = { ...mod };
+  const defaultExport = mod.default ?? mod;
+
+  function teardown() {
+    if (!keepTemp) {
+      removeTempDir(tempDirPath);
+      log(`Removed temp dir: ${tempDirPath}`);
+    }
+  }
+
+  return {
+    module: defaultExport,
+    exports,
+    tempFile,
+    cliPath,
+    version,
+    patchCount,
+    hookPoints,
+    bundlerInfo,
+    cliExportsFound,
+    teardown,
+  };
+}
+
+export { load, instrument };

package/src/locate.js

@@ -0,0 +1,296 @@
+/**
+ * locate.js
+ *
+ * Locates the installed Claude Code CLI (cli.js and optionally sdk.mjs).
+ *
+ * Resolution order:
+ *  0. Node.js module resolution via createRequire — cross-platform, no subprocess.
+ *     Works on Windows/macOS/Linux as long as @anthropic-ai/claude-code is in
+ *     the module graph (installed globally or locally).
+ *  1. `which` npm package (cross-platform, no subprocess) + symlink chain.
+ *  2. Enumerate nvm-managed Node.js versions.
+ *  3. Static fallback paths.
+ *  4. Derive from process.execPath.
+ */
+
+import { createRequire } from 'node:module';
+import {
+  existsSync,
+  realpathSync,
+  readFileSync,
+  readlinkSync,
+  readdirSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+// createRequire anchored to this file so resolution walks node_modules correctly
+const _require = createRequire(import.meta.url);
+
+// ---------------------------------------------------------------------------
+// Fallback package directory candidates
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a list of candidate @anthropic-ai/claude-code directories from all
+ * nvm-managed Node.js versions found under ~/.nvm.
+ */
+function buildNvmFallbacksSync() {
+  const nvmDir = process.env.NVM_DIR ?? join(process.env.HOME ?? '~', '.nvm');
+  const versionsRoot = join(nvmDir, 'versions', 'node');
+
+  if (!existsSync(versionsRoot)) return [];
+
+  try {
+    return readdirSync(versionsRoot).map(v =>
+      join(versionsRoot, v, 'lib', 'node_modules', '@anthropic-ai', 'claude-code')
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Static fallback list of well-known global install locations.
+ */
+function staticFallbacks() {
+  const home = process.env.HOME ?? '';
+  return [
+    join(home, '.nvm', 'versions', 'node', 'v22.0.0', 'lib', 'node_modules', '@anthropic-ai', 'claude-code'),
+    join(home, '.nvm', 'versions', 'node', 'v20.0.0', 'lib', 'node_modules', '@anthropic-ai', 'claude-code'),
+    join(home, '.nvm', 'versions', 'node', 'v18.0.0', 'lib', 'node_modules', '@anthropic-ai', 'claude-code'),
+    '/usr/local/lib/node_modules/@anthropic-ai/claude-code',
+    '/usr/lib/node_modules/@anthropic-ai/claude-code',
+    '/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code',
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Safe wrapper around fs.realpathSync — returns null on any error.
+ *
+ * @param {string} p
+ * @returns {string | null}
+ */
+function safeRealpath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk up the directory tree from `startDir` looking for a directory that
+ * contains `cli.js` (the claude-code package root).
+ *
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+function findPackageDirUpward(startDir) {
+  let current = startDir;
+
+  for (let depth = 0; depth < 30; depth++) {
+    if (existsSync(join(current, 'cli.js'))) {
+      return current;
+    }
+
+    // Check common nesting: current/@anthropic-ai/claude-code
+    const nested = join(current, '@anthropic-ai', 'claude-code');
+    if (existsSync(join(nested, 'cli.js'))) {
+      return nested;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) break; // reached fs root
+    current = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Collect every path in the symlink chain starting from `startPath`.
+ * Each element is one hop resolved relative to the previous one.
+ *
+ * @param {string} startPath
+ * @returns {string[]}
+ */
+function collectSymlinkChain(startPath) {
+  const chain = [startPath];
+  let current = startPath;
+
+  for (let i = 0; i < 20; i++) {
+    let target;
+    try {
+      target = readlinkSync(current);
+    } catch {
+      // Not a symlink (or error) — end of chain
+      break;
+    }
+
+    // Resolve relative targets relative to the symlink's directory
+    const next = resolve(dirname(current), target);
+    if (chain.includes(next)) break; // cycle guard
+    chain.push(next);
+    current = next;
+  }
+
+  // Also include the fully-resolved real path (handles multi-hop quietly)
+  const real = safeRealpath(startPath);
+  if (real && !chain.includes(real)) {
+    chain.push(real);
+  }
+
+  return chain;
+}
+
+/**
+ * Read the `version` field from a package directory's package.json.
+ *
+ * @param {string} packageDir
+ * @returns {string}
+ */
+function readPackageVersion(packageDir) {
+  const pkgPath = join(packageDir, 'package.json');
+  if (!existsSync(pkgPath)) return 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Build a result object for a found package directory.
+ *
+ * @param {string} packageDir
+ * @returns {{ cliPath: string, sdkPath: string|null, packageDir: string, version: string }}
+ */
+function buildResult(packageDir) {
+  const cliPath = join(packageDir, 'cli.js');
+  const sdkCandidate = join(packageDir, 'sdk.mjs');
+  return {
+    cliPath,
+    sdkPath: existsSync(sdkCandidate) ? sdkCandidate : null,
+    packageDir,
+    version: readPackageVersion(packageDir),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main locate() function
+// ---------------------------------------------------------------------------
+
+/**
+ * Locate the Claude Code CLI installation.
+ *
+ * Resolution order:
+ *  1. Follow the symlink chain of `which claude` and walk each hop upward
+ *     looking for a directory that contains cli.js.
+ *  2. Enumerate nvm-managed Node.js versions and check each one.
+ *  3. Check static fallback paths.
+ *  4. Derive a path from the currently running Node.js executable.
+ *
+ * @returns {Promise<{ cliPath: string, sdkPath: string|null, packageDir: string, version: string }>}
+ * @throws {Error} if no installation can be found
+ */
+async function locate() {
+  // ── Strategy 0: Node.js module resolution (cross-platform, no subprocess) ──
+  // Uses createRequire to resolve @anthropic-ai/claude-code/package.json, then
+  // derives cli.js from that directory.  This is how sdk.mjs itself finds cli.js
+  // internally and works on Windows/macOS/Linux without any subprocess.
+  try {
+    // resolve the package root via its package.json
+    const pkgJsonPath = _require.resolve('@anthropic-ai/claude-code/package.json');
+    const pkgDir = dirname(pkgJsonPath);
+    if (existsSync(join(pkgDir, 'cli.js'))) return buildResult(pkgDir);
+  } catch { /* package not resolvable from this location — fall through */ }
+
+  // Also try resolving sdk.mjs (the "main" entry) to derive the directory
+  try {
+    const sdkPath = _require.resolve('@anthropic-ai/claude-code');
+    const pkgDir = dirname(sdkPath);
+    if (existsSync(join(pkgDir, 'cli.js'))) return buildResult(pkgDir);
+  } catch { /* not found */ }
+
+  // import.meta.resolve is available in Node 18.19+ / 20.0+
+  // We use a dynamic eval-style call to avoid a syntax error on older runtimes
+  try {
+    const resolved = await (async () => {
+      // This will throw on runtimes that don't support import.meta.resolve
+      return import.meta.resolve?.('@anthropic-ai/claude-code/package.json');
+    })();
+    if (resolved) {
+      const { fileURLToPath } = await import('node:url');
+      const pkgDir = dirname(fileURLToPath(resolved));
+      if (existsSync(join(pkgDir, 'cli.js'))) return buildResult(pkgDir);
+    }
+  } catch { /* not available */ }
+
+  // ── Strategy 1: `which` npm package + symlink chain (cross-platform, no subprocess) ──
+  // Uses the `which` npm package (263M downloads/week) — handles Windows PATHEXT,
+  // pure JS, no child_process.exec.
+  let whichResult = null;
+  try {
+    const { default: which } = await import('which');
+    whichResult = which.sync('claude', { nothrow: true });
+  } catch {
+    /* which package not available or claude not on PATH */
+  }
+
+  if (whichResult) {
+    const chain = collectSymlinkChain(whichResult);
+
+    for (const hop of chain) {
+      const hopDir = dirname(hop);
+      const found = findPackageDirUpward(hopDir);
+      if (found) return buildResult(found);
+    }
+  }
+
+  // ── Strategy 2: nvm version enumeration ───────────────────────────────────
+  for (const dir of buildNvmFallbacksSync()) {
+    if (existsSync(join(dir, 'cli.js'))) return buildResult(dir);
+  }
+
+  // ── Strategy 3: static fallbacks ──────────────────────────────────────────
+  for (const dir of staticFallbacks()) {
+    if (existsSync(join(dir, 'cli.js'))) return buildResult(dir);
+  }
+
+  // ── Strategy 4: derive from current node executable ───────────────────────
+  // e.g. /home/user/.nvm/versions/node/v22.0.0/bin/node
+  //   → /home/user/.nvm/versions/node/v22.0.0/lib/node_modules/@anthropic-ai/claude-code
+  const nodeExecDir = dirname(process.execPath); // …/bin
+  const nodePrefix = dirname(nodeExecDir);       // …/versions/node/vX.Y.Z
+  const derivedDir = join(nodePrefix, 'lib', 'node_modules', '@anthropic-ai', 'claude-code');
+  if (existsSync(join(derivedDir, 'cli.js'))) return buildResult(derivedDir);
+
+  throw new Error(
+    [
+      'Could not locate the Claude Code CLI (cli.js).',
+      whichResult
+        ? `  which('claude') → ${whichResult} (followed symlinks but cli.js not found nearby)`
+        : '  which(\'claude\') → (not found on PATH)',
+      '  Tried nvm version directories, common global install paths, and node prefix.',
+      '  Ensure @anthropic-ai/claude-code is installed globally:',
+      '    npm install -g @anthropic-ai/claude-code',
+    ].join('\n')
+  );
+}
+
+/**
+ * Async wrapper around locate() — returns a Promise for ergonomic use with
+ * top-level await.
+ *
+ * @returns {Promise<{ cliPath: string, sdkPath: string|null, packageDir: string, version: string }>}
+ */
+/** Alias — locate() is already async; this exists for API symmetry. */
+const locateAsync = locate;
+
+export { locate, locateAsync };
+export default locate;