@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/packages/tools/codegraph/dist/index.js

@@ -0,0 +1,343 @@
+import { findProjectRoot } from './lib/cg-instance.js';
+import { handleInit } from './lib/cmd-init.js';
+import { handleSync } from './lib/cmd-sync.js';
+import { handleStatus } from './lib/cmd-status.js';
+import { handleSearch } from './lib/cmd-search.js';
+import { handleExplore } from './lib/cmd-explore.js';
+import { handleSurvey } from './lib/cmd-survey.js';
+import { handleListApis } from './lib/cmd-list-apis.js';
+import { handleVerify } from './lib/cmd-verify.js';
+export async function codegraphHandler(args, context) {
+    const stdout = context.stdout || process.stdout;
+    const stderr = context.stderr || process.stderr;
+    const projectRoot = findProjectRoot(context.cwd || process.cwd());
+    // Parse --json flag early (can appear anywhere)
+    const jsonIndex = args.indexOf('--json');
+    const isJson = jsonIndex >= 0;
+    if (jsonIndex >= 0)
+        args.splice(jsonIndex, 1);
+    // Main help: no args, --help, -h, or "help" subcommand
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+        printHelp(stdout);
+        return 0;
+    }
+    const subcommand = args[0];
+    // Per-subcommand help: e.g., "apltk codegraph search --help"
+    // Check for --help/-h at position 1 (after the subcommand name)
+    const rest = args.slice(1);
+    if (rest.includes('--help') || rest.includes('-h')) {
+        printSubcommandHelp(subcommand, stdout, stderr);
+        return 0;
+    }
+    // Parse --spec <dir> for verify
+    const specIndex = rest.indexOf('--spec');
+    let specDir;
+    if (specIndex >= 0 && specIndex + 1 < rest.length) {
+        specDir = rest[specIndex + 1];
+        rest.splice(specIndex, 2);
+    }
+    // Parse --all flag for list-apis
+    const allIndex = rest.indexOf('--all');
+    const isAll = allIndex >= 0;
+    if (allIndex >= 0)
+        rest.splice(allIndex, 1);
+    // Parse --index flag for init
+    const shouldIndex = rest.includes('--index');
+    const indexIdx = rest.indexOf('--index');
+    if (indexIdx >= 0)
+        rest.splice(indexIdx, 1);
+    // Parse --feature <name> for survey
+    const featureIndex = rest.indexOf('--feature');
+    let featureName;
+    if (featureIndex >= 0 && featureIndex + 1 < rest.length) {
+        featureName = rest[featureIndex + 1];
+        rest.splice(featureIndex, 2);
+    }
+    // Parse limit for search
+    const limitIndex = rest.indexOf('--limit');
+    let limit;
+    if (limitIndex >= 0 && limitIndex + 1 < rest.length) {
+        limit = parseInt(rest[limitIndex + 1], 10);
+        rest.splice(limitIndex, 2);
+    }
+    try {
+        switch (subcommand) {
+            case 'init':
+                return await handleInit(projectRoot, { index: shouldIndex, json: isJson });
+            case 'sync':
+                return await handleSync(projectRoot, { json: isJson });
+            case 'status':
+                return await handleStatus(projectRoot, { json: isJson });
+            case 'search': {
+                const query = rest.join(' ');
+                if (!query) {
+                    stderr.write('Usage: apltk codegraph search <query> [--limit N] [--json]\n');
+                    return 1;
+                }
+                return await handleSearch(projectRoot, query, { limit, json: isJson });
+            }
+            case 'explore': {
+                const query = rest.join(' ');
+                if (!query) {
+                    stderr.write('Usage: apltk codegraph explore <query> [--json]\n');
+                    return 1;
+                }
+                return await handleExplore(projectRoot, query, { json: isJson, feature: featureName });
+            }
+            case 'survey': {
+                const dirPath = rest[0] || '.';
+                return await handleSurvey(projectRoot, dirPath, { feature: featureName, json: isJson });
+            }
+            case 'list-apis': {
+                const pathArg = rest[0];
+                const combinedPath = featureName
+                    ? (pathArg ? `${featureName}/${pathArg.replace(/^\//, '')}` : featureName)
+                    : pathArg;
+                return await handleListApis(projectRoot, combinedPath, { all: isAll, json: isJson });
+            }
+            case 'verify': {
+                if (!specDir) {
+                    stderr.write('Usage: apltk codegraph verify --spec <spec-dir> [--json]\n');
+                    return 1;
+                }
+                return await handleVerify(projectRoot, specDir, { json: isJson });
+            }
+            default:
+                stderr.write(`Unknown subcommand: ${subcommand}\n\n`);
+                printHelp(stderr);
+                return 1;
+        }
+    }
+    catch (error) {
+        if (error.code === 'MODULE_NOT_FOUND' || (error.message && error.message.includes('Cannot find module'))) {
+            stderr.write('`@colbymchenry/codegraph` is not installed. Run `npm install @colbymchenry/codegraph` in your project directory.\n');
+        }
+        else {
+            stderr.write(`Error running codegraph ${subcommand}: ${error.message}\n`);
+        }
+        return 1;
+    }
+}
+function printHelp(stream) {
+    stream.write(`Usage: apltk codegraph <subcommand> [options]
+
+CodeGraph code intelligence — parse source code into a knowledge graph
+of symbols (functions, classes) and relationships (call edges), backed by
+a local SQLite database with FTS5 full-text search.
+
+Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph).
+
+Subcommands:
+
+  lifecycle:
+    init               Initialize CodeGraph for the project
+                       --index    Run initial indexing immediately after init
+                       --json     JSON output
+
+    sync               Sync the index with current file state
+                       --json     JSON output
+
+    status             Show index statistics (files, nodes, edges, languages)
+                       --json     JSON output
+
+  discovery:
+    search <query>     Search the code graph for symbols via FTS5
+                       --limit N  Max results (default: 20, max: 100)
+                       --json     JSON output
+
+    explore <query>    Deep-dive on a symbol — show callers, callees, and source
+                       --feature <name>  Only show results within this feature
+                       --json            JSON output
+
+    survey [dir]       Scan a directory, suggest submodule groupings and
+                       cross-boundary edges for atlas modelling
+                       --feature <name>  Feature context for grouping
+                       --json            JSON output
+
+    list-apis [path]   List public APIs in the project or within a sub-path
+                       --all      Include non-exported (internal) symbols
+                       --json     JSON output
+
+  validation:
+    verify --spec <dir>
+                       Verify a spec overlay against actual code —
+                       checks that every declared feature, submodule,
+                       function, and edge exists in the code graph
+                       --json     JSON output
+
+Global options:
+    --json             Output as JSON instead of human-readable format
+    --help, -h         Show this help message
+
+Use "apltk codegraph <subcommand> --help" for per-subcommand details.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+  apltk codegraph status --json
+  apltk codegraph search getUser
+  apltk codegraph search getUser --limit 5 --json
+  apltk codegraph explore handleLogin
+  apltk codegraph survey src/
+  apltk codegraph survey src/ --feature auth --json
+  apltk codegraph list-apis --all
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
+`);
+}
+function printSubcommandHelp(subcommand, stream, errStream) {
+    const PAD = '  ';
+    const helps = {
+        init: `Usage: apltk codegraph init [--index] [--json]
+
+Initialize the CodeGraph knowledge graph for the project.
+Creates the .codegraph/ directory and SQLite database.
+
+Flags:
+  --index    Run initial indexing immediately after init, so the
+             knowledge graph is ready for queries right away.
+             Without this flag, you need to run "apltk codegraph sync"
+             separately before searching or exploring.
+  --json     Output confirmation as JSON.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+`,
+        sync: `Usage: apltk codegraph sync [--json]
+
+Sync the code graph index with the current state of files on disk.
+Parses changed files and updates the SQLite database.
+
+This is needed after you modify source files if you want queries
+to reflect the latest code. Runs incrementally — only reprocesses
+files whose mtime has changed.
+
+Flags:
+  --json     Output sync results (files added/removed/updated) as JSON.
+
+Examples:
+  apltk codegraph sync
+  apltk codegraph sync --json
+`,
+        status: `Usage: apltk codegraph status [--json]
+
+Show index statistics: file count, symbol (node) count, edge count,
+languages detected, and last-sync timestamp.
+
+Flags:
+  --json     Output full statistics as a JSON object.
+
+Examples:
+  apltk codegraph status
+  apltk codegraph status --json
+`,
+        search: `Usage: apltk codegraph search <query> [--limit N] [--json]
+
+Full-text search the code graph for symbols (functions, classes, variables).
+Uses FTS5 (SQLite full-text search) under the hood.
+
+Arguments:
+  query      Search term (required). Matches against symbol names and
+             source code content.
+
+Flags:
+  --limit N  Max results to return (default: 20, max: 100).
+  --json     Output results as a JSON array.
+
+Examples:
+  apltk codegraph search getUser
+  apltk codegraph search handleLogin --limit 5
+  apltk codegraph search "class.*Handler" --limit 10 --json
+`,
+        explore: `Usage: apltk codegraph explore <query> [--feature <name>] [--json]
+
+Deep-dive on a symbol — shows who calls it, what it calls, and its
+full source code. Useful for understanding how a function or class
+fits into the broader codebase.
+
+Arguments:
+  query      Symbol name to explore (required).
+
+Flags:
+  --feature <name>
+             Scope results to only show callers/callees within a
+             specific feature directory (e.g. "auth", "billing").
+  --json     Output full exploration data as JSON (callers, callees,
+             source code, file path, line numbers).
+
+Examples:
+  apltk codegraph explore handleLogin
+  apltk codegraph explore authenticate --feature auth
+  apltk codegraph explore sendEmail --json
+`,
+        survey: `Usage: apltk codegraph survey [dir] [--feature <name>] [--json]
+
+Scan a directory and produce a structured survey report with suggested
+submodule groupings, cross-boundary edges, and entry points.
+
+This is the primary input for the "init-project-html" skill's Step 1 —
+it tells the LLM how to model features and submodules for the atlas.
+
+Arguments:
+  dir        Directory to scan (default: current directory ".").
+
+Flags:
+  --feature <name>
+             Feature context: scope the survey to only one feature's
+             boundary. Helps the grouper cluster symbols more accurately.
+  --json     Output survey results as JSON — best for LLM consumption.
+
+Examples:
+  apltk codegraph survey
+  apltk codegraph survey src/
+  apltk codegraph survey src/auth --feature auth --json
+`,
+        'list-apis': `Usage: apltk codegraph list-apis [path] [--all] [--json]
+
+List public (exported) symbols in the project or a specific sub-path.
+Useful for understanding the public surface area of a module.
+
+Arguments:
+  path       Sub-path to scan (e.g. "src/auth"). When omitted, scans
+             the entire project.
+
+Flags:
+  --all      Include non-exported (internal) symbols in the listing.
+  --json     Output API list as JSON.
+
+Examples:
+  apltk codegraph list-apis
+  apltk codegraph list-apis src/auth
+  apltk codegraph list-apis --all --json
+`,
+        verify: `Usage: apltk codegraph verify --spec <spec-dir> [--json]
+
+Verify a spec overlay's architecture proposals against actual code.
+Checks that every feature, submodule, function, and edge referenced
+in the overlay's atlas state actually exists in the code graph.
+
+Flags:
+  --spec <spec-dir>
+             Path to the spec directory containing an architecture_diff/
+             overlay (required). For example, "docs/plans/2026-05-11/add-2fa".
+  --json     Output verification results as JSON (passed/failed checks).
+
+Examples:
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa --json
+`,
+    };
+    const text = helps[subcommand];
+    if (text) {
+        stream.write(text);
+    }
+    else {
+        errStream.write(`Unknown subcommand: "${subcommand}". Use "apltk codegraph --help" for the list of available subcommands.\n`);
+    }
+}
+export const tool = {
+    name: 'codegraph',
+    category: 'Code analysis',
+    description: 'CodeGraph code intelligence — init, sync, status, search, explore, survey, list-apis, verify',
+    handler: codegraphHandler,
+};

package/packages/tools/codegraph/dist/lib/cg-instance.d.ts

@@ -0,0 +1,29 @@
+export declare function getCodeGraphModule(): {
+    CodeGraph: any;
+    findNearestCodeGraphRoot: any;
+};
+/**
+ * Locate the project root by walking up from the given directory.
+ * Returns the nearest parent containing `.codegraph/`, or falls back
+ * to the nearest parent containing `package.json`.
+ */
+export declare function findProjectRoot(startPath?: string): string;
+/**
+ * Initialize a CodeGraph index for the given project root.
+ *
+ * If the project is already initialized, throws an error suggesting
+ * `apltk codegraph sync` instead. Otherwise, initializes a new CodeGraph
+ * project. When `options.index` is true, runs initial indexing after init.
+ *
+ * Note: `CodeGraph.init()` supports an `{ index: true }` shorthand that
+ * runs initial indexing inline -- this deviates from a two-step init-then-index
+ * pattern but is the supported API through the npm package.
+ */
+export declare function createOrOpenIndex(projectRoot: string, options?: {
+    index?: boolean;
+    onProgress?: (progress: any) => void;
+}): Promise<any>;
+/**
+ * Close a CodeGraph instance and release resources.
+ */
+export declare function closeIndex(cg: any): void;

package/packages/tools/codegraph/dist/lib/cg-instance.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let _codeGraphModule = null;
+export function getCodeGraphModule() {
+    if (!_codeGraphModule) {
+        _codeGraphModule = require('@colbymchenry/codegraph');
+    }
+    return _codeGraphModule;
+}
+/**
+ * Locate the project root by walking up from the given directory.
+ * Returns the nearest parent containing `.codegraph/`, or falls back
+ * to the nearest parent containing `package.json`.
+ */
+export function findProjectRoot(startPath) {
+    const cwd = startPath || process.cwd();
+    const codegraphRoot = getCodeGraphModule().findNearestCodeGraphRoot(cwd);
+    if (codegraphRoot)
+        return codegraphRoot;
+    // Fallback: walk up looking for package.json
+    let dir = path.resolve(cwd);
+    while (true) {
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return cwd; // hit filesystem root
+        dir = parent;
+    }
+}
+/**
+ * Initialize a CodeGraph index for the given project root.
+ *
+ * If the project is already initialized, throws an error suggesting
+ * `apltk codegraph sync` instead. Otherwise, initializes a new CodeGraph
+ * project. When `options.index` is true, runs initial indexing after init.
+ *
+ * Note: `CodeGraph.init()` supports an `{ index: true }` shorthand that
+ * runs initial indexing inline -- this deviates from a two-step init-then-index
+ * pattern but is the supported API through the npm package.
+ */
+export async function createOrOpenIndex(projectRoot, options) {
+    const isInit = getCodeGraphModule().CodeGraph.isInitialized(projectRoot);
+    if (isInit) {
+        throw new Error(`Project is already initialized at ${projectRoot}. Use \`apltk codegraph sync\` to update the index.`);
+    }
+    return getCodeGraphModule().CodeGraph.init(projectRoot, {
+        index: options?.index ?? false,
+        onProgress: options?.onProgress,
+    });
+}
+/**
+ * Close a CodeGraph instance and release resources.
+ */
+export function closeIndex(cg) {
+    cg.close();
+}

package/packages/tools/codegraph/dist/lib/cg-instance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/tools/codegraph/dist/lib/cg-instance.test.js

@@ -0,0 +1,27 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createOrOpenIndex } from './cg-instance.js';
+describe('createOrOpenIndex', () => {
+    let tmpDir;
+    before(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-test-'));
+    });
+    after(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('should throw when project is already initialized', async () => {
+        // Arrange: create .codegraph/ and codegraph.db to simulate an initialized project
+        const codegraphDir = path.join(tmpDir, '.codegraph');
+        fs.mkdirSync(codegraphDir, { recursive: true });
+        fs.writeFileSync(path.join(codegraphDir, 'codegraph.db'), '');
+        // Act & Assert
+        await assert.rejects(() => createOrOpenIndex(tmpDir), (err) => {
+            assert.ok(err instanceof Error);
+            assert.match(err.message, /sync/);
+            return true;
+        });
+    });
+});

package/packages/tools/codegraph/dist/lib/cmd-explore.d.ts

@@ -0,0 +1,5 @@
+export interface ExploreOptions {
+    json?: boolean;
+    feature?: string;
+}
+export declare function handleExplore(projectRoot: string, query: string, options?: ExploreOptions): Promise<number>;

package/packages/tools/codegraph/dist/lib/cmd-explore.js

@@ -0,0 +1,95 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { closeIndex } from './cg-instance.js';
+import { formatOutput } from './formatter.js';
+export async function handleExplore(projectRoot, query, options = {}) {
+    const { CodeGraph } = require('@colbymchenry/codegraph');
+    const cg = await CodeGraph.open(projectRoot, { sync: false, readOnly: true });
+    // Step 1: Search for the query
+    const searchResults = cg.searchNodes(query, { limit: 10 });
+    if (searchResults.length === 0) {
+        process.stdout.write('No symbols found matching the query.\n');
+        closeIndex(cg);
+        return 0;
+    }
+    const details = [];
+    for (const result of searchResults) {
+        const node = result.node;
+        const callers = cg.getCallers(node.id).map((c) => ({
+            name: c.node.name,
+            filePath: c.node.filePath,
+            startLine: c.node.startLine,
+        }));
+        const callees = cg.getCallees(node.id).map((c) => ({
+            name: c.node.name,
+            filePath: c.node.filePath,
+            startLine: c.node.startLine,
+        }));
+        const code = await cg.getCode(node.id);
+        details.push({
+            name: node.name,
+            kind: node.kind,
+            filePath: node.filePath,
+            startLine: node.startLine,
+            endLine: node.endLine,
+            qualifiedName: node.qualifiedName,
+            signature: node.signature,
+            callers,
+            callees,
+            code,
+        });
+    }
+    closeIndex(cg);
+    if (options.json) {
+        process.stdout.write(formatOutput(details, { json: true }) + '\n');
+        return 0;
+    }
+    // Human-readable output — group by filePath
+    const grouped = new Map();
+    for (const d of details) {
+        const group = grouped.get(d.filePath) ?? [];
+        group.push(d);
+        grouped.set(d.filePath, group);
+    }
+    if (options.feature) {
+        process.stdout.write(`Feature: ${options.feature}\n`);
+    }
+    for (const [filePath, symbols] of grouped) {
+        process.stdout.write(`\n=== ${filePath} ===\n\n`);
+        for (const d of symbols) {
+            process.stdout.write(`  ${d.name} [${d.kind}] line ${d.startLine}-${d.endLine}\n`);
+            process.stdout.write(`    QName: ${d.qualifiedName}\n`);
+            if (d.signature)
+                process.stdout.write(`    Signature: ${d.signature}\n`);
+            process.stdout.write(`    Callers (${d.callers.length}):\n`);
+            if (d.callers.length === 0) {
+                process.stdout.write('      (none)\n');
+            }
+            else {
+                for (const c of d.callers.slice(0, 20)) {
+                    process.stdout.write(`      ${c.name}  ${c.filePath}:${c.startLine}\n`);
+                }
+            }
+            process.stdout.write(`    Callees (${d.callees.length}):\n`);
+            if (d.callees.length === 0) {
+                process.stdout.write('      (none)\n');
+            }
+            else {
+                for (const c of d.callees.slice(0, 20)) {
+                    process.stdout.write(`      ${c.name}  ${c.filePath}:${c.startLine}\n`);
+                }
+            }
+            if (d.code) {
+                process.stdout.write(`    Source (${d.filePath}):\n`);
+                const lines = d.code.split('\n');
+                for (let i = 0; i < Math.min(lines.length, 30); i++) {
+                    process.stdout.write(`      ${lines[i]}\n`);
+                }
+                if (lines.length > 30) {
+                    process.stdout.write(`      ... (${lines.length - 30} more lines)\n`);
+                }
+            }
+        }
+    }
+    return 0;
+}

package/packages/tools/codegraph/dist/lib/cmd-explore.test.d.ts

@@ -0,0 +1 @@
+export {};