@secemp/elwood 0.1.0

package/examples/basic.js

@@ -0,0 +1,240 @@
+/**
+ * examples/basic.js
+ *
+ * Minimal demonstration of the `elwood` library.
+ *
+ * Run:
+ *   node examples/basic.js
+ *
+ * What it does:
+ *  1. Locates the installed Claude Code CLI (cli.js) automatically.
+ *  2. Installs hook callbacks that log every intercepted event.
+ *  3. Parses + instruments the CLI bundle via Babel AST.
+ *  4. Reports statistics: how many hook sites were injected, which bundler
+ *     pattern was detected, and a sample of the function map.
+ *
+ * The example deliberately does NOT fully import the instrumented bundle
+ * (step 4 of load()) because executing the CLI's top-level side effects
+ * would start the actual Claude Code process.  If you do want to load it,
+ * uncomment the `load()` section at the bottom.
+ */
+
+import {
+  locate,
+  instrument,
+  parseBundle,
+  detectBundlerPattern,
+  extractFunctionMap,
+} from '../src/index.js';
+
+// Increase heap for large bundles when running this example directly:
+//   node --max-old-space-size=4096 examples/basic.js
+
+// ---------------------------------------------------------------------------
+// 0. Install global hooks (must happen before the bundle executes)
+// ---------------------------------------------------------------------------
+
+globalThis.__elwoodHooks = {
+  /**
+   * Fires at the top of any function whose name matched the `intercept` list.
+   *
+   * @param {string} fnName   - the function's identifier name
+   * @param {IArguments | any[]} args - the call-time arguments
+   */
+  onCall(fnName, args) {
+    console.log(`  [hook:onCall]   ${fnName}() called with ${Array.isArray(args) ? args.length : '?'} arg(s)`);
+  },
+
+  /**
+   * Fires when a fetch() call is detected that targets an Anthropic API URL.
+   *
+   * @param {string} label  - always 'fetch'
+   * @param {string} url    - the URL passed to fetch()
+   */
+  onApiCall(label, url) {
+    console.log(`  [hook:onApiCall]  ${label} → ${url}`);
+  },
+
+  /**
+   * Fires when a tool-execution call pattern is detected.
+   *
+   * @param {string} callee    - the function/method name
+   * @param {string} firstArg  - the first argument (typically the tool name)
+   */
+  onToolCall(callee, firstArg) {
+    console.log(`  [hook:onToolCall] ${callee}(${JSON.stringify(firstArg)}, …)`);
+  },
+
+  /**
+   * Fires at the top of any async generator function (streaming pattern).
+   *
+   * @param {string} generatorName - inferred name of the generator
+   */
+  onStream(generatorName) {
+    console.log(`  [hook:onStream]   async generator ${generatorName} started`);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 1. Locate the CLI
+// ---------------------------------------------------------------------------
+
+console.log('='.repeat(60));
+console.log('elwood — basic example');
+console.log('='.repeat(60));
+
+console.log('\n[1] Locating Claude Code CLI...');
+
+// You can override the auto-detection by passing an explicit cliPath below.
+// Recommended: use the v22 9MB bundle — the v18 13MB bundle requires more heap.
+//   Hint: node --max-old-space-size=8192 examples/basic.js
+let location;
+try {
+  location = await locate();
+} catch (err) {
+  console.error('\nFailed to locate cli.js:', err.message);
+  process.exit(1);
+}
+
+// If locate() found the larger v18 bundle and a smaller v22 one exists,
+// silently prefer the v22 bundle for this example to avoid OOM.
+{
+  const { existsSync } = await import('node:fs');
+  const v22cli =
+    (process.env.HOME ?? '') +
+    '/.nvm/versions/node/v22.0.0/lib/node_modules/@anthropic-ai/claude-code/cli.js';
+  if (existsSync(v22cli) && v22cli !== location.cliPath) {
+    console.log(`    [note] preferring v22 bundle (${v22cli}) for memory efficiency`);
+    location = {
+      cliPath: v22cli,
+      sdkPath: null,
+      packageDir: v22cli.replace('/cli.js', ''),
+      version: '2.0.0',
+    };
+  }
+}
+
+const { cliPath, sdkPath, packageDir, version } = location;
+
+console.log(`    cliPath    : ${cliPath}`);
+console.log(`    sdkPath    : ${sdkPath ?? '(not found)'}`);
+console.log(`    packageDir : ${packageDir}`);
+console.log(`    version    : ${version}`);
+
+// ---------------------------------------------------------------------------
+// 2. Parse the bundle and detect its structure
+// ---------------------------------------------------------------------------
+
+console.log('\n[2] Parsing the CLI bundle (this may take a few seconds)...');
+console.time('    parse');
+
+let ast;
+try {
+  ast = parseBundle(cliPath);
+} catch (err) {
+  console.error('\nFailed to parse cli.js:', err.message);
+  process.exit(1);
+}
+
+console.timeEnd('    parse');
+
+// Bundler detection
+console.log('\n[3] Detecting bundler pattern...');
+const bundlerInfo = detectBundlerPattern(ast);
+console.log(`    bundler      : ${bundlerInfo.bundler}`);
+console.log(`    moduleCount  : ${bundlerInfo.moduleCount}`);
+console.log(`    wrappers     : ${bundlerInfo.wrapperNames.slice(0, 5).join(', ') || '(none)'}`);
+console.log(`    hasLazyInits : ${bundlerInfo.hasLazyInits}`);
+console.log('    clues        :');
+for (const clue of bundlerInfo.clues) {
+  console.log(`      • ${clue}`);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Build the function map (sample first 10)
+// ---------------------------------------------------------------------------
+
+console.log('\n[4] Extracting function map (sample)...');
+console.time('    extractFunctionMap');
+const fnMap = extractFunctionMap(ast);
+console.timeEnd('    extractFunctionMap');
+
+console.log(`    Total named functions found: ${fnMap.size}`);
+console.log('    Sample (first 10):');
+
+let i = 0;
+for (const [name, entry] of fnMap) {
+  if (i++ >= 10) break;
+  const purpose = entry.inferredPurpose ?? '(unknown)';
+  console.log(`      ${name.padEnd(25)} [${entry.kind.padEnd(11)}] purpose: ${purpose}`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Run the instrumentation pipeline (WITHOUT loading)
+// ---------------------------------------------------------------------------
+
+console.log('\n[5] Running instrumentation pipeline...');
+console.time('    instrument');
+
+let result;
+try {
+  result = await instrument({
+    cliPath,
+    // Intercept functions whose names match these patterns — purely illustrative,
+    // since a minified bundle uses short names.  Swap for real patterns if
+    // you reverse-engineer specific function names via fnMap above.
+    intercept: [],
+    wrapApiCalls: true,
+    wrapToolExecutions: true,
+    wrapAsyncGenerators: true,
+    wrapFunctionCalls: false, // keep fast — no generic function wrapping
+    verbose: false,
+  });
+} catch (err) {
+  console.error('\nInstrumentation failed:', err.message);
+  process.exit(1);
+}
+
+console.timeEnd('    instrument');
+
+console.log(`    patchCount : ${result.patchCount}`);
+console.log(`    hookPoints : ${result.hookPoints.length} site(s)`);
+console.log(`    codeSize   : ${(result.code.length / 1024 / 1024).toFixed(2)} MB`);
+
+if (result.hookPoints.length > 0) {
+  console.log('    Sample hook points:');
+  for (const hp of result.hookPoints.slice(0, 5)) {
+    console.log(`      • [${hp.type.padEnd(16)}] ${hp.name ?? '(anonymous)'}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 5. (Optional) Full load — uncomment to actually import the instrumented bundle
+// ---------------------------------------------------------------------------
+
+/*
+import { load } from '../src/index.js';
+
+console.log('\n[6] Loading the instrumented bundle via dynamic import...');
+console.log('    WARNING: this will execute the CLI bundle top-level code.');
+console.time('    load');
+
+const loaded = await load({
+  cliPath,
+  instrument: true,
+  wrapApiCalls: true,
+  wrapToolExecutions: true,
+  verbose: true,
+  keepTemp: false,
+});
+
+console.timeEnd('    load');
+console.log(`    exports: ${Object.keys(loaded.exports).join(', ')}`);
+
+// Clean up the temp file
+loaded.teardown();
+*/
+
+console.log('\n' + '='.repeat(60));
+console.log('Done.');
+console.log('='.repeat(60));

package/examples/smoke-test.js

@@ -0,0 +1,296 @@
+/**
+ * smoke-test.js
+ *
+ * Verifies that the elwood SDK loads correctly and all public APIs
+ * have the expected shape. Does NOT make any API calls (no ANTHROPIC_API_KEY needed).
+ *
+ * Checks:
+ *   1. preload() completes (Babel AST pipeline works)
+ *   2. Version, patch count, hook points count are printed
+ *   3. HOOK_EVENTS contains the expected event names
+ *   4. EXIT_REASONS contains the expected reason strings
+ *   5. tool() returns an object with { name, description, inputSchema, handler }
+ *   6. createSdkMcpServer() returns something (Promise or object)
+ *   7. query is a function
+ *   8. Session utilities (listSessions, getSessionMessages, getSessionInfo) are functions
+ *   9. V2 session APIs are functions
+ *   10. AbortError is a proper Error subclass
+ *
+ * Run:
+ *   node examples/smoke-test.js
+ */
+
+import {
+  // Core query
+  query,
+  AbortError,
+
+  // Tool / MCP helpers
+  tool,
+  createSdkMcpServer,
+  preload,
+
+  // Constants
+  HOOK_EVENTS,
+  EXIT_REASONS,
+
+  // Session utilities
+  listSessions,
+  getSessionMessages,
+  getSessionInfo,
+
+  // V2 Session API
+  unstable_v2_createSession,
+  unstable_v2_resumeSession,
+  unstable_v2_prompt,
+
+  // AST tools (for completeness)
+  locate,
+  load,
+  instrument,
+  parseBundle,
+  detectBundlerPattern,
+  extractFunctionMap,
+  injectHooks,
+} from '../src/index.js';
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, label) {
+  if (condition) {
+    console.log(`  [PASS] ${label}`);
+    passed++;
+  } else {
+    console.error(`  [FAIL] ${label}`);
+    failed++;
+  }
+}
+
+console.log('='.repeat(60));
+console.log('elwood smoke test');
+console.log('='.repeat(60));
+
+// ---------------------------------------------------------------------------
+// 1. Verify exports exist and have the right types
+// ---------------------------------------------------------------------------
+console.log('\n[1] Checking exported functions and constants...');
+
+assert(typeof query === 'function', 'query is a function');
+assert(typeof tool === 'function', 'tool is a function');
+assert(typeof createSdkMcpServer === 'function', 'createSdkMcpServer is a function');
+assert(typeof preload === 'function', 'preload is a function');
+assert(typeof locate === 'function', 'locate is a function');
+assert(typeof load === 'function', 'load is a function');
+assert(typeof instrument === 'function', 'instrument is a function');
+assert(typeof parseBundle === 'function', 'parseBundle is a function');
+assert(typeof detectBundlerPattern === 'function', 'detectBundlerPattern is a function');
+assert(typeof extractFunctionMap === 'function', 'extractFunctionMap is a function');
+assert(typeof injectHooks === 'function', 'injectHooks is a function');
+
+// Session utilities
+assert(typeof listSessions === 'function', 'listSessions is a function');
+assert(typeof getSessionMessages === 'function', 'getSessionMessages is a function');
+assert(typeof getSessionInfo === 'function', 'getSessionInfo is a function');
+
+// V2 session API
+assert(typeof unstable_v2_createSession === 'function', 'unstable_v2_createSession is a function');
+assert(typeof unstable_v2_resumeSession === 'function', 'unstable_v2_resumeSession is a function');
+assert(typeof unstable_v2_prompt === 'function', 'unstable_v2_prompt is a function');
+
+// AbortError
+assert(typeof AbortError === 'function', 'AbortError is a function (class)');
+const abortErr = new AbortError('test');
+assert(abortErr instanceof Error, 'AbortError instance is an Error');
+assert(abortErr.name === 'AbortError', 'AbortError.name is "AbortError"');
+assert(abortErr.message === 'test', 'AbortError.message is "test"');
+
+// ---------------------------------------------------------------------------
+// 2. HOOK_EVENTS verification
+// ---------------------------------------------------------------------------
+console.log('\n[2] Verifying HOOK_EVENTS...');
+
+assert(Array.isArray(HOOK_EVENTS), 'HOOK_EVENTS is an array');
+assert(Object.isFrozen(HOOK_EVENTS), 'HOOK_EVENTS is frozen');
+assert(HOOK_EVENTS.length >= 10, `HOOK_EVENTS has ${HOOK_EVENTS.length} entries (>= 10)`);
+
+const expectedHookEvents = [
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+  'SubagentStart',
+  'SubagentStop',
+  'PreCompact',
+  'PermissionRequest',
+];
+for (const event of expectedHookEvents) {
+  assert(HOOK_EVENTS.includes(event), `HOOK_EVENTS contains "${event}"`);
+}
+
+// ---------------------------------------------------------------------------
+// 3. EXIT_REASONS verification
+// ---------------------------------------------------------------------------
+console.log('\n[3] Verifying EXIT_REASONS...');
+
+assert(Array.isArray(EXIT_REASONS), 'EXIT_REASONS is an array');
+assert(Object.isFrozen(EXIT_REASONS), 'EXIT_REASONS is frozen');
+
+const expectedExitReasons = [
+  'clear',
+  'logout',
+  'prompt_input_exit',
+  'other',
+  'bypass_permissions_disabled',
+];
+for (const reason of expectedExitReasons) {
+  assert(EXIT_REASONS.includes(reason), `EXIT_REASONS contains "${reason}"`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. tool() returns the right shape
+// ---------------------------------------------------------------------------
+console.log('\n[4] Verifying tool() return shape...');
+
+const testTool = tool(
+  'test_tool',
+  'A test tool for smoke testing',
+  {
+    type: 'object',
+    properties: { input: { type: 'string' } },
+    required: ['input'],
+  },
+  async (args) => ({ content: [{ type: 'text', text: `Echo: ${args.input}` }] })
+);
+
+assert(typeof testTool === 'object' && testTool !== null, 'tool() returns an object');
+assert(testTool.name === 'test_tool', 'tool().name is "test_tool"');
+assert(testTool.description === 'A test tool for smoke testing', 'tool().description is correct');
+assert(typeof testTool.inputSchema === 'object', 'tool().inputSchema is an object');
+assert(typeof testTool.handler === 'function', 'tool().handler is a function');
+
+// Verify handler works
+const handlerResult = await testTool.handler({ input: 'hello' });
+assert(
+  handlerResult.content[0].text === 'Echo: hello',
+  'tool().handler returns correct content'
+);
+
+// ---------------------------------------------------------------------------
+// 5. createSdkMcpServer() returns something
+// ---------------------------------------------------------------------------
+console.log('\n[5] Verifying createSdkMcpServer()...');
+
+const mcpResult = createSdkMcpServer({
+  name: 'smoke-test-server',
+  version: '0.0.1',
+  tools: [testTool],
+});
+
+// createSdkMcpServer returns either a sync object or a Promise
+const isPromise = mcpResult && typeof mcpResult.then === 'function';
+const isObject = typeof mcpResult === 'object' && mcpResult !== null;
+assert(isPromise || isObject, `createSdkMcpServer() returns a ${isPromise ? 'Promise' : 'sync object'}`);
+
+if (isPromise) {
+  // If it's a promise, verify it resolves (or fails gracefully)
+  try {
+    const resolved = await mcpResult;
+    assert(
+      resolved && typeof resolved === 'object',
+      'createSdkMcpServer() promise resolves to an object'
+    );
+    assert(resolved.type === 'sdk', 'resolved.type is "sdk"');
+    assert(resolved.name === 'smoke-test-server', 'resolved.name is "smoke-test-server"');
+  } catch (err) {
+    // It's acceptable for createSdkMcpServer to fail if no McpServer class is available
+    console.log(`  [INFO] createSdkMcpServer() promise rejected: ${err.message?.slice(0, 80)}`);
+    console.log('  [INFO] This is expected if @modelcontextprotocol/sdk is not installed');
+  }
+} else {
+  assert(mcpResult.type === 'sdk', 'result.type is "sdk"');
+  assert(mcpResult.name === 'smoke-test-server', 'result.name is "smoke-test-server"');
+}
+
+// ---------------------------------------------------------------------------
+// 6. query() is callable (but we don't actually run it)
+// ---------------------------------------------------------------------------
+console.log('\n[6] Verifying query() is callable...');
+
+assert(typeof query === 'function', 'query is a function');
+
+// Verify it returns an async generator when called
+const gen = query({ prompt: 'test', options: {} });
+assert(
+  gen !== null && typeof gen === 'object',
+  'query() returns a non-null object'
+);
+assert(typeof gen[Symbol.asyncIterator] === 'function', 'query() returns an async iterable');
+assert(typeof gen.interrupt === 'function', 'query() result has interrupt() method');
+assert(typeof gen.setModel === 'function', 'query() result has setModel() method');
+assert(typeof gen.setPermissionMode === 'function', 'query() result has setPermissionMode() method');
+assert(typeof gen.supportedModels === 'function', 'query() result has supportedModels() method');
+assert(typeof gen.supportedCommands === 'function', 'query() result has supportedCommands() method');
+assert(typeof gen.mcpServerStatus === 'function', 'query() result has mcpServerStatus() method');
+assert(typeof gen.close === 'function', 'query() result has close() method');
+
+// Clean up: close the generator without iterating (avoids loading cli.js)
+try {
+  gen.close();
+} catch {
+  // ignore
+}
+
+// ---------------------------------------------------------------------------
+// 7. listSessions works (reads from filesystem, no API key needed)
+// ---------------------------------------------------------------------------
+console.log('\n[7] Verifying session utilities...');
+
+const sessions = await listSessions();
+assert(Array.isArray(sessions), 'listSessions() returns an array');
+console.log(`  [INFO] Found ${sessions.length} session(s) in ~/.claude/projects/`);
+
+if (sessions.length > 0) {
+  const first = sessions[0];
+  assert(typeof first.sessionId === 'string', 'session has sessionId');
+  assert(typeof first.projectPath === 'string', 'session has projectPath');
+  assert(first.mtime instanceof Date, 'session has mtime as Date');
+
+  const info = await getSessionInfo(first.sessionId);
+  if (info) {
+    assert(typeof info.messageCount === 'number', 'getSessionInfo returns messageCount');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 8. Locate CLI (verifies the AST pipeline can find cli.js)
+// ---------------------------------------------------------------------------
+console.log('\n[8] Locating Claude Code CLI...');
+
+try {
+  const loc = await locate();
+  assert(typeof loc.cliPath === 'string', `CLI found at: ${loc.cliPath}`);
+  assert(typeof loc.version === 'string', `CLI version: ${loc.version}`);
+  console.log(`  [INFO] packageDir: ${loc.packageDir}`);
+} catch (err) {
+  console.log(`  [WARN] locate() failed: ${err.message?.slice(0, 80)}`);
+  console.log('  [WARN] This is expected if Claude Code CLI is not installed');
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+console.log('\n' + '='.repeat(60));
+console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log('='.repeat(60));
+
+if (failed > 0) {
+  console.error('\nSmoke test FAILED');
+  process.exit(1);
+} else {
+  console.log('\nSmoke test passed!');
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@secemp/elwood",
+  "version": "0.1.0",
+  "description": "Programmatically import and instrument the locally installed Claude Code CLI via Babel AST",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/secemp9/elwood.git"
+  },
+  "homepage": "https://github.com/secemp9/elwood",
+  "bugs": {
+    "url": "https://github.com/secemp9/elwood/issues"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.28.0",
+    "@babel/parser": "^7.28.0",
+    "@babel/traverse": "^7.28.0",
+    "@babel/types": "^7.28.0",
+    "which": "^4.0.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^10.0.0"
+  },
+  "scripts": {
+    "test": "node scripts/test-query-full.js && node scripts/test-gap-fixes.js && node scripts/test-hooks-behavioral.js && node scripts/test-mcp-behavioral.js",
+    "test:examples": "node scripts/test-examples.js",
+    "smoke": "node examples/smoke-test.js",
+    "example": "node examples/01-basic-query.js"
+  },
+  "keywords": [
+    "claude",
+    "anthropic",
+    "babel",
+    "ast",
+    "instrumentation",
+    "cli"
+  ],
+  "license": "MIT"
+}