@kentwynn/kgraph 0.1.24 → 0.1.26

package/README.md

@@ -100,13 +100,18 @@ kgraph init
 # 2. Optional: connect AI tools so they know the KGraph workflow
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 
-# 3. Run the normal workflow for a topic
+# 3. Optional: configure deep language extractors for non-TS repos
+kgraph extractor add jvm python
+
+# 4. Run the normal workflow for a topic
 kgraph "auth token refresh"
 
-# 4. Check health if something feels off
+# 5. Check health if something feels off
 kgraph doctor
 ```
 
+`kgraph init` now scans once, then prints relevant next steps. When KGraph can detect likely AI tools on the machine, it recommends matching integrations. When the repository contains languages that only have basic built-in extraction today, it recommends optional deep extractors and prints the exact install/configure commands.
+
 After useful AI work, assistants save durable runtime-capture notes into `.kgraph/inbox/`. These notes are not project documentation; they are KGraph input files that the next `kgraph` run processes automatically. You can also process them directly with `kgraph update`.
 
 Normal agent flow is intentionally small:
@@ -138,7 +143,7 @@ This is optional. Claude Code can use generated hook scripts for automatic captu
 kgraph init
 ```
 
-Required once per repo. Creates `.kgraph/` and the local config.
+Required once per repo. Creates `.kgraph/`, writes the local config, runs the first scan, and prints suggested next actions based on the detected repo languages and likely local AI tools.
 
 ```bash
 kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
@@ -258,6 +263,18 @@ New integrations default to `always` mode because coding agents often under-clas
 | Codex | `AGENTS.md`, `.agents/skills/kgraph/SKILL.md` |
 | GitHub Copilot | `.github/copilot-instructions.md`, `.github/prompts/*` |
 | Cursor | `.cursor/rules/kgraph.mdc` |
+
+## Optional Deep Extractors
+
+KGraph ships with built-in extractors for several languages, but TypeScript and JavaScript still have the deepest built-in analysis today. For languages such as Java, Kotlin, Python, Go, Rust, C/C++, and C#, `kgraph init` can recommend optional deep extractors when those languages are detected in the repository.
+
+```bash
+kgraph extractor list
+kgraph extractor add jvm python
+kgraph extractor remove jvm
+```
+
+`extractor add` writes extractor configuration into `.kgraph/config.yaml` and prints the exact `npm install -D ...` command for the matching optional packages. This is explicit on purpose: KGraph recommends install commands by default rather than silently changing package-manager state.
 | Claude Code | `CLAUDE.md`, `.claude/commands/*` |
 | Gemini CLI | `GEMINI.md` |
 | Windsurf | `.windsurf/rules/kgraph.md` |

package/dist/cli/commands/extractor.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerExtractorCommand(program: Command): void;

package/dist/cli/commands/extractor.js

@@ -0,0 +1,50 @@
+import { installCommandForExtractors, normalizeExtractorNames, } from '../../extractors/extractor-registry.js';
+import { addExtractors, listExtractors, removeExtractors, } from '../../extractors/extractor-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerExtractorCommand(program) {
+    const extractor = program
+        .command('extractor')
+        .description('Manage optional deep language extractors');
+    extractor
+        .command('list')
+        .description('List configured optional extractors')
+        .action(() => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const extractors = await listExtractors(workspace);
+        if (extractors.length === 0) {
+            console.log('No extractors configured.');
+            return;
+        }
+        for (const item of extractors) {
+            console.log(`${item.name} ${item.enabled ? 'enabled' : 'disabled'} ${item.packageName} ${item.packageInstalled ? 'present' : 'missing'}`);
+        }
+    }));
+    extractor
+        .command('add')
+        .description('Configure optional deep extractors')
+        .argument('<names...>')
+        .action((names) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const normalized = normalizeExtractorNames(names);
+        if (normalized.length === 0) {
+            throw new KGraphError('Provide at least one extractor name.');
+        }
+        const changed = await addExtractors(workspace, normalized);
+        console.log(`Configured extractors: ${changed.map((item) => item.name).join(', ')}`);
+        console.log(`Install packages: ${installCommandForExtractors(changed.map((item) => item.packageName))}`);
+    }));
+    extractor
+        .command('remove')
+        .description('Remove optional deep extractors')
+        .argument('<names...>')
+        .action((names) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const normalized = normalizeExtractorNames(names);
+        if (normalized.length === 0) {
+            throw new KGraphError('Provide at least one extractor name.');
+        }
+        const removed = await removeExtractors(workspace, normalized);
+        console.log(`Removed extractors: ${removed.join(', ')}`);
+    }));
+}

package/dist/cli/commands/init.d.ts

@@ -1,2 +1,2 @@
-import type { Command } from "commander";
+import type { Command } from 'commander';
 export declare function registerInitCommand(program: Command): void;

package/dist/cli/commands/init.js

@@ -1,28 +1,95 @@
-import { writeDefaultConfig } from "../../config/config.js";
-import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
-import { addIntegrations } from "../../integrations/integration-store.js";
-import { ensureWorkspace } from "../../storage/kgraph-paths.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { loadConfig, writeDefaultConfig } from '../../config/config.js';
+import { installCommandForExtractors } from '../../extractors/extractor-registry.js';
+import { addExtractors } from '../../extractors/extractor-store.js';
+import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
+import { addIntegrations } from '../../integrations/integration-store.js';
+import { scanRepository } from '../../scanner/repo-scanner.js';
+import { ensureWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps, writeMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+import { promptForInitExtractors, promptForInitIntegrations, shouldPromptForInitExtractors, shouldPromptForInitIntegrations, } from '../init-prompt.js';
+import { detectMachineIntegrationRecommendations, recommendedExtractorsForInit, recommendedIntegrationsForInit, } from '../init-recommendations.js';
+import { renderInitSummary } from '../init-summary.js';
 export function registerInitCommand(program) {
     program
-        .command("init")
-        .description("Initialize a .kgraph workspace")
-        .option("--integration <name>", "Configure an AI tool integration", collectOption, [])
-        .option("--integrations <names>", "Configure comma-separated AI tool integrations")
-        .option("--mode <mode>", "Integration mode: smart, always, manual, or off", "always")
+        .command('init')
+        .description('Initialize a .kgraph workspace')
+        .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
+        .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
-        console.log(wroteConfig ? "Initialized .kgraph workspace." : ".kgraph workspace already initialized.");
+        console.log(wroteConfig
+            ? 'Initialized .kgraph workspace.'
+            : '.kgraph workspace already initialized.');
         const names = normalizeIntegrationNames([
             ...(options.integration ?? []),
-            ...(options.integrations ? [options.integrations] : [])
+            ...(options.integrations ? [options.integrations] : []),
         ]);
         if (names.length > 0) {
             const mode = normalizeIntegrationMode(options.mode);
             const changed = await addIntegrations(workspace, names, mode);
-            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
         }
+        let config = await loadConfig(workspace);
+        const previousMaps = await readMaps(workspace);
+        const result = await scanRepository(workspace.rootPath, config, {
+            files: previousMaps.fileMap.files,
+            symbols: previousMaps.symbolMap.symbols,
+            dependencies: previousMaps.dependencyMap.dependencies,
+            relationships: previousMaps.relationshipMap.relationships,
+            warnings: [],
+        });
+        await writeMaps(workspace, result);
+        console.log(`Scanned ${result.files.length} files and ${result.symbols.length} symbols.`);
+        const detectedMachineIntegrations = await detectMachineIntegrationRecommendations();
+        let recommendedIntegrations = recommendedIntegrationsForInit({
+            configuredIntegrations: config.integrations,
+            detectedIntegrations: detectedMachineIntegrations,
+        });
+        let recommendedExtractors = recommendedExtractorsForInit({
+            files: result.files,
+            configuredExtractors: config.extractors,
+        });
+        if (shouldPromptForInitIntegrations({
+            explicitIntegrationsRequested: names.length > 0,
+            configuredIntegrations: config.integrations,
+        })) {
+            const selected = await promptForInitIntegrations(recommendedIntegrations);
+            if (selected.length > 0) {
+                const changed = await addIntegrations(workspace, selected, 'always');
+                console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
+                config = await loadConfig(workspace);
+                recommendedIntegrations = recommendedIntegrationsForInit({
+                    configuredIntegrations: config.integrations,
+                    detectedIntegrations: detectedMachineIntegrations,
+                });
+            }
+        }
+        if (shouldPromptForInitExtractors({
+            configuredExtractors: config.extractors,
+        })) {
+            const selected = await promptForInitExtractors(recommendedExtractors);
+            if (selected.length > 0) {
+                const changed = await addExtractors(workspace, selected);
+                console.log(`Configured extractors: ${changed.map((item) => item.name).join(', ')}`);
+                console.log(`Install packages: ${installCommandForExtractors(changed.map((item) => item.packageName))}`);
+                config = await loadConfig(workspace);
+                recommendedExtractors = recommendedExtractorsForInit({
+                    files: result.files,
+                    configuredExtractors: config.extractors,
+                });
+            }
+        }
+        console.log('');
+        console.log(renderInitSummary({
+            files: result.files,
+            integrations: config.integrations,
+            recommendedIntegrations,
+            extractors: config.extractors,
+            recommendedExtractors,
+        }));
     }));
 }
 function collectOption(value, previous) {
@@ -30,8 +97,11 @@ function collectOption(value, previous) {
     return previous;
 }
 function normalizeIntegrationMode(value) {
-    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+    if (value === 'smart' ||
+        value === 'always' ||
+        value === 'manual' ||
+        value === 'off') {
         return value;
     }
-    throw new KGraphError("--mode must be smart, always, manual, or off.");
+    throw new KGraphError('--mode must be smart, always, manual, or off.');
 }

package/dist/cli/commands/integrate.d.ts

@@ -1,2 +1,2 @@
-import type { Command } from "commander";
+import type { Command } from 'commander';
 export declare function registerIntegrateCommand(program: Command): void;

package/dist/cli/commands/integrate.js

@@ -1,63 +1,75 @@
-import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode } from "../../integrations/integration-store.js";
-import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
-import { assertWorkspace } from "../../storage/kgraph-paths.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
+import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode, } from '../../integrations/integration-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
 export function registerIntegrateCommand(program) {
-    const integrate = program.command("integrate").description("Manage AI tool integrations");
-    integrate.command("list").description("List configured integrations").action(() => runCommand(async () => {
+    const integrate = program
+        .command('integrate')
+        .description('Manage AI tool integrations');
+    integrate
+        .command('list')
+        .description('List configured integrations')
+        .action(() => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const integrations = await listIntegrations(workspace);
         if (integrations.length === 0) {
-            console.log("No integrations configured.");
+            console.log('No integrations configured.');
             return;
         }
         for (const integration of integrations) {
-            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
+            console.log(`${integration.name} ${integration.enabled ? 'enabled' : 'disabled'} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? 'present' : 'missing'}`);
         }
     }));
     integrate
-        .command("add")
-        .description("Add AI tool integrations")
-        .argument("<names...>")
-        .option("--mode <mode>", "smart, always, manual, or off", "always")
+        .command('add')
+        .description('Add AI tool integrations')
+        .argument('<names...>')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const mode = normalizeIntegrationMode(options.mode);
         const changed = await addIntegrations(workspace, normalized, mode);
-        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
     }));
     integrate
-        .command("set")
-        .description("Set AI tool integration mode")
-        .argument("<names...>")
-        .requiredOption("--mode <mode>", "smart, always, manual, or off")
+        .command('set')
+        .description('Set AI tool integration mode')
+        .argument('<names...>')
+        .requiredOption('--mode <mode>', 'smart, always, manual, or off')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const mode = normalizeIntegrationMode(options.mode);
         const changed = await setIntegrationMode(workspace, normalized, mode);
-        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
     }));
-    integrate.command("remove").description("Remove AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
+    integrate
+        .command('remove')
+        .description('Remove AI tool integrations')
+        .argument('<names...>')
+        .action((names) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const removed = await removeIntegrations(workspace, normalized);
-        console.log(`Removed integrations: ${removed.join(", ")}`);
+        console.log(`Removed integrations: ${removed.join(', ')}`);
     }));
 }
 function normalizeIntegrationMode(value) {
-    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+    if (value === 'smart' ||
+        value === 'always' ||
+        value === 'manual' ||
+        value === 'off') {
         return value;
     }
-    throw new KGraphError("--mode must be smart, always, manual, or off.");
+    throw new KGraphError('--mode must be smart, always, manual, or off.');
 }

package/dist/cli/help.js

@@ -47,6 +47,11 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
+        theme.bold('Extractors'),
+        command('extractor list', 'Show configured optional deep extractors'),
+        command('extractor add jvm python', 'Configure optional deep extractors and print install commands'),
+        command('extractor remove jvm', 'Remove extractor configuration'),
+        '',
         theme.bold('Options'),
         command('-V, --version', 'Show version'),
         command('-h, --help', 'Show this help'),

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { registerContextCommand } from './commands/context.js';
 import { registerDoctorCommand } from './commands/doctor.js';
+import { registerExtractorCommand } from './commands/extractor.js';
 import { registerHistoryCommand } from './commands/history.js';
 import { registerImpactCommand } from './commands/impact.js';
 import { registerInitCommand } from './commands/init.js';
@@ -43,6 +44,7 @@ export function createProgram() {
     registerUpdateCommand(program);
     registerContextCommand(program);
     registerImpactCommand(program);
+    registerExtractorCommand(program);
     registerIntegrateCommand(program);
     registerVisualizeCommand(program);
     registerHistoryCommand(program);

package/dist/cli/init-prompt.d.ts

@@ -0,0 +1,13 @@
+import type { ExtractorConfig, ExtractorName, IntegrationConfig, IntegrationName } from '../types/config.js';
+import type { InitExtractorRecommendation, InitIntegrationRecommendation } from './init-recommendations.js';
+export declare function shouldPromptForInitIntegrations(options: {
+    explicitIntegrationsRequested: boolean;
+    configuredIntegrations: Pick<IntegrationConfig, 'name'>[];
+    interactive?: boolean;
+}): boolean;
+export declare function promptForInitIntegrations(recommendations: InitIntegrationRecommendation[]): Promise<IntegrationName[]>;
+export declare function shouldPromptForInitExtractors(options: {
+    configuredExtractors: Pick<ExtractorConfig, 'name'>[];
+    interactive?: boolean;
+}): boolean;
+export declare function promptForInitExtractors(recommendations: InitExtractorRecommendation[]): Promise<ExtractorName[]>;

package/dist/cli/init-prompt.js

@@ -0,0 +1,124 @@
+import * as clack from '@clack/prompts';
+import { listExtractorAdapters } from '../extractors/extractor-registry.js';
+import { listIntegrationAdapters } from '../integrations/integration-registry.js';
+// --- Integration prompt ---
+export function shouldPromptForInitIntegrations(options) {
+    const interactive = options.interactive ?? isInteractiveTerminal();
+    return (interactive &&
+        !options.explicitIntegrationsRequested &&
+        options.configuredIntegrations.length === 0);
+}
+export async function promptForInitIntegrations(recommendations) {
+    const recNames = recommendations.map((item) => item.name);
+    const action = await clack.select({
+        message: 'AI tool integrations',
+        options: [
+            ...(recommendations.length > 0
+                ? [
+                    {
+                        value: 'recommended',
+                        label: `Use recommended (${recNames.join(', ')})`,
+                        hint: recommendations
+                            .map((item) => `${item.name} — ${item.reason}`)
+                            .join('; '),
+                    },
+                ]
+                : []),
+            { value: 'custom', label: 'Custom selection' },
+            { value: 'skip', label: 'Skip' },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'skip') {
+        return [];
+    }
+    if (action === 'recommended') {
+        return recNames;
+    }
+    const recommendedNames = new Set(recNames);
+    const otherAdapters = listIntegrationAdapters().filter((adapter) => !recommendedNames.has(adapter.name));
+    const allOptions = [
+        ...recommendations.map((rec) => ({
+            value: rec.name,
+            label: rec.name,
+            hint: rec.reason,
+        })),
+        ...otherAdapters.map((adapter) => ({
+            value: adapter.name,
+            label: adapter.name,
+        })),
+    ];
+    const selected = await clack.multiselect({
+        message: 'Select integrations (space to toggle, enter to confirm)',
+        options: allOptions,
+        required: false,
+    });
+    if (clack.isCancel(selected)) {
+        return [];
+    }
+    return selected;
+}
+// --- Extractor prompt ---
+export function shouldPromptForInitExtractors(options) {
+    const interactive = options.interactive ?? isInteractiveTerminal();
+    return interactive && options.configuredExtractors.length === 0;
+}
+export async function promptForInitExtractors(recommendations) {
+    const recNames = recommendations.map((item) => item.name);
+    const hasRecommendations = recommendations.length > 0;
+    const action = await clack.select({
+        message: 'Optional deep language extractors',
+        options: [
+            ...(hasRecommendations
+                ? [
+                    {
+                        value: 'recommended',
+                        label: `Use recommended (${recNames.join(', ')})`,
+                        hint: recommendations
+                            .map((item) => `${item.name} for ${item.languages.join(', ')}`)
+                            .join('; '),
+                    },
+                ]
+                : []),
+            {
+                value: 'custom',
+                label: 'Custom selection',
+                hint: hasRecommendations
+                    ? undefined
+                    : 'no language-specific extractors detected; pick manually',
+            },
+            { value: 'skip', label: 'Skip' },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'skip') {
+        return [];
+    }
+    if (action === 'recommended') {
+        return recNames;
+    }
+    const recommendedNames = new Set(recNames);
+    const otherAdapters = listExtractorAdapters().filter((adapter) => !recommendedNames.has(adapter.name));
+    const allOptions = [
+        ...recommendations.map((rec) => ({
+            value: rec.name,
+            label: rec.name,
+            hint: `${rec.languages.join(', ')} — ${rec.packageName} (recommended)`,
+        })),
+        ...otherAdapters.map((adapter) => ({
+            value: adapter.name,
+            label: adapter.name,
+            hint: `${adapter.languages.join(', ')} — ${adapter.packageName}`,
+        })),
+    ];
+    const selected = await clack.multiselect({
+        message: 'Select extractors (space to toggle, enter to confirm)',
+        options: allOptions,
+        required: false,
+    });
+    if (clack.isCancel(selected)) {
+        return [];
+    }
+    return selected;
+}
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}

package/dist/cli/init-recommendations.d.ts

@@ -0,0 +1,31 @@
+import type { ExtractorConfig, ExtractorName, IntegrationConfig, IntegrationName } from '../types/config.js';
+import type { RepositoryFile } from '../types/maps.js';
+export interface InitIntegrationRecommendation {
+    name: IntegrationName;
+    reason: string;
+}
+export interface InitExtractorRecommendation {
+    name: ExtractorName;
+    packageName: string;
+    languages: string[];
+}
+interface MachineDetectionContext {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+    exists?: (targetPath: string) => Promise<boolean>;
+    readDir?: (targetPath: string) => Promise<string[]>;
+    localAppData?: string;
+}
+export declare function detectMachineIntegrationRecommendations(context?: MachineDetectionContext): Promise<InitIntegrationRecommendation[]>;
+export declare function recommendedIntegrationsForInit(options: {
+    configuredIntegrations: Pick<IntegrationConfig, 'name'>[];
+    detectedIntegrations: InitIntegrationRecommendation[];
+}): InitIntegrationRecommendation[];
+export declare function recommendedExtractorsForInit(options: {
+    files: RepositoryFile[];
+    configuredExtractors: Pick<ExtractorConfig, 'name'>[];
+}): InitExtractorRecommendation[];
+export declare function integrationSetupCommand(recommendations: InitIntegrationRecommendation[]): string | undefined;
+export declare function extractorSetupCommands(recommendations: InitExtractorRecommendation[]): string[];
+export {};