@secemp/elwood 0.1.0

package/src/ast-tools.js

@@ -0,0 +1,182 @@
+/**
+ * ast-tools.js
+ *
+ * Low-level Babel AST helpers: parse, traverse, and generate.
+ *
+ * Parser options are tuned for the Claude Code CLI bundle, which is a
+ * minified ESM file (sourceType: 'module') and may contain JSX and
+ * TypeScript-style syntax emitted by the bundler.  The same options are used
+ * in generic-dependency-splitter.js — reused verbatim here.
+ */
+
+import { readFileSync } from 'node:fs';
+import { parse as babelParse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+import _generate from '@babel/generator';
+import * as t from '@babel/types';
+
+// Handle both CommonJS-wrapped and native ESM default exports from Babel
+const traverse = _traverse.default ?? _traverse;
+const generate = _generate.default ?? _generate;
+
+// ---------------------------------------------------------------------------
+// Parser configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Babel parser options that work for the Claude Code CLI bundle.
+ *
+ * Key choices:
+ *  - sourceType: 'module'       — cli.js starts with `import {…} from …`
+ *  - errorRecovery: true        — minified code sometimes hits minor spec
+ *                                 edge-cases; we want a best-effort parse
+ *  - plugins: jsx + typescript  — bundlers may leave JSX/TS syntax behind;
+ *                                 decorators-legacy for class decorators
+ */
+const PARSER_OPTIONS = {
+  sourceType: 'module',
+  plugins: ['jsx', 'typescript', 'decorators-legacy'],
+  errorRecovery: true,
+  // Increase token limit for 9 MB+ bundles
+  createParenthesizedExpressions: false,
+};
+
+// ---------------------------------------------------------------------------
+// Core API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a file from disk and parse it into a Babel AST.
+ *
+ * @param {string} filePath - absolute path to the JS/MJS file
+ * @param {import('@babel/parser').ParserOptions} [extraOptions] - merged with defaults
+ * @returns {import('@babel/types').File} Babel AST File node
+ */
+function parseBundle(filePath, extraOptions = {}) {
+  const code = readFileSync(filePath, 'utf8');
+  return parseBundleCode(code, { ...PARSER_OPTIONS, ...extraOptions });
+}
+
+/**
+ * Parse a string of code into a Babel AST.
+ *
+ * @param {string} code
+ * @param {import('@babel/parser').ParserOptions} [extraOptions]
+ * @returns {import('@babel/types').File}
+ */
+function parseBundleCode(code, extraOptions = {}) {
+  const options = { ...PARSER_OPTIONS, ...extraOptions };
+
+  // Babel's parse() may throw even with errorRecovery for some edge cases.
+  // If it does, try again with a more permissive set.
+  try {
+    return babelParse(code, options);
+  } catch (firstErr) {
+    try {
+      return babelParse(code, {
+        ...options,
+        // Drop TypeScript plugin as a last resort — it can trip on some
+        // patterns the ts plugin considers invalid even in JS files.
+        plugins: ['jsx', 'decorators-legacy'],
+      });
+    } catch {
+      // Re-throw the original, more informative error
+      throw firstErr;
+    }
+  }
+}
+
+/**
+ * Traverse a Babel AST with a visitor object.
+ *
+ * This is a thin wrapper around @babel/traverse that handles the CJS/ESM
+ * default-export discrepancy and provides consistent call semantics.
+ *
+ * @param {import('@babel/types').File} ast  - root AST node (File or Program)
+ * @param {import('@babel/traverse').Visitor} visitors - visitor map
+ * @param {Record<string, unknown>} [scope]  - optional scope bindings passed as state
+ * @returns {void}
+ */
+function traverseBundle(ast, visitors, scope = {}) {
+  traverse(ast, visitors, /* scope */ undefined, /* state */ scope);
+}
+
+/**
+ * Generate JavaScript source code from a Babel AST node.
+ *
+ * @param {import('@babel/types').Node} ast  - any Babel node (File, Program, expression…)
+ * @param {import('@babel/generator').GeneratorOptions} [options]
+ * @param {string} [originalSource]  - original source code; when provided, @babel/generator
+ *   uses source-range-based generation to preserve original identifier names rather than
+ *   regenerating them from AST node IDs.  This is critical for CLI export fingerprinting:
+ *   without it, minified names like `MC1` get replaced by Babel-internal names like `Hi8`.
+ * @returns {{ code: string, map: object | null }}
+ */
+function generateCode(ast, options = {}, originalSource) {
+  const result = generate(
+    ast,
+    {
+      // Compact output — we're not trying to produce readable code, just
+      // functional instrumented code.  Set to false for debugging.
+      compact: false,
+      concise: false,
+      comments: true,
+      ...options,
+    },
+    originalSource
+  );
+
+  return result;
+}
+
+/**
+ * Convenience: parse → traverse → generate in one call.
+ *
+ * @param {string} filePath
+ * @param {import('@babel/traverse').Visitor} visitors
+ * @param {import('@babel/generator').GeneratorOptions} [genOptions]
+ * @returns {{ code: string, ast: import('@babel/types').File }}
+ */
+function transformBundle(filePath, visitors, genOptions = {}) {
+  const ast = parseBundle(filePath);
+  traverseBundle(ast, visitors);
+  const { code } = generateCode(ast, genOptions);
+  return { code, ast };
+}
+
+/**
+ * Convenience: parse a code string → traverse → generate.
+ *
+ * @param {string} code
+ * @param {import('@babel/traverse').Visitor} visitors
+ * @param {import('@babel/generator').GeneratorOptions} [genOptions]
+ * @returns {{ code: string, ast: import('@babel/types').File }}
+ */
+function transformCode(code, visitors, genOptions = {}) {
+  const ast = parseBundleCode(code);
+  traverseBundle(ast, visitors);
+  const { code: out } = generateCode(ast, genOptions);
+  return { code: out, ast };
+}
+
+// ---------------------------------------------------------------------------
+// Re-export babel utilities so callers don't need direct babel deps
+// ---------------------------------------------------------------------------
+
+export {
+  // Core API
+  parseBundle,
+  parseBundleCode,
+  traverseBundle,
+  generateCode,
+  transformBundle,
+  transformCode,
+
+  // Re-exports of the underlying Babel primitives
+  traverse,
+  generate,
+  t,
+
+  // Parser options — exported so other modules can extend them
+  PARSER_OPTIONS,
+};

package/src/index.js

@@ -0,0 +1,70 @@
+/**
+ * elwood — public API
+ *
+ * Programmatically import and instrument the locally installed Claude Code CLI
+ * via Babel AST.
+ *
+ * Usage:
+ *
+ *   import { locate, load, instrument } from 'elwood';
+ *
+ *   // Install hooks before loading
+ *   globalThis.__elwoodHooks = {
+ *     onCall(fnName, args)       { console.log('[call]', fnName); },
+ *     onApiCall(label, url)      { console.log('[api]', url); },
+ *     onToolCall(name, firstArg) { console.log('[tool]', name, firstArg); },
+ *     onStream(generatorName)    { console.log('[stream]', generatorName); },
+ *   };
+ *
+ *   const { module, exports, teardown } = await load({ verbose: true });
+ *   // … use exports …
+ *   teardown(); // clean up the temp file
+ */
+
+// ── Location ────────────────────────────────────────────────────────────────
+export { locate, locateAsync } from './locate.js';
+
+// ── Load + instrument pipeline ───────────────────────────────────────────────
+export { load, instrument } from './loader.js';
+
+// ── Raw AST tools ────────────────────────────────────────────────────────────
+export {
+  parseBundle,
+  parseBundleCode,
+  traverseBundle,
+  generateCode,
+  transformBundle,
+  transformCode,
+  PARSER_OPTIONS,
+} from './ast-tools.js';
+
+// ── Instrumentation primitives ───────────────────────────────────────────────
+export {
+  injectHooks,
+  detectBundlerPattern,
+  extractFunctionMap,
+  findCliExports,
+  injectCliExports,
+  DEFAULT_HOOK_VAR,
+  ANTHROPIC_API_HOST,
+} from './instrumenter.js';
+
+// ── Subprocess-free query() ──────────────────────────────────────────────────
+export {
+  query,
+  AbortError,
+  tool,
+  createSdkMcpServer,
+  preload,
+  // Hook event and exit reason constants
+  HOOK_EVENTS,
+  EXIT_REASONS,
+  // Session utility functions (pure Node.js file I/O)
+  listSessions,
+  getSessionMessages,
+  getSessionInfo,
+  // V2 Session API (UNSTABLE)
+  unstable_v2_createSession,
+  unstable_v2_resumeSession,
+  unstable_v2_prompt,
+} from './query.js';