@kentwynn/kgraph 0.1.0 → 0.1.1

package/README.md

@@ -1,200 +1,174 @@
 # KGraph
 
-Persistent repo intelligence for AI coding assistants.
+Persistent repository intelligence for AI coding tools.
 
-KGraph is a local-first CLI for building an inspectable knowledge layer around a codebase. It helps AI coding sessions stop rediscovering the same repository structure, workflows, architecture decisions, and debugging history every time a new chat starts.
+KGraph is a local-first CLI that builds an inspectable knowledge layer for a codebase. It helps tools like Codex, GitHub Copilot, Cursor, and Claude Code reuse repository structure, workflow knowledge, debugging history, and architecture decisions instead of rediscovering them in every chat.
 
-## Why KGraph
+## Why It Matters
 
-The biggest waste in AI-assisted coding is often not generation. It is repeated exploration:
+AI coding sessions spend a large part of their budget finding context: reading files, tracing imports, locating the right functions, and re-learning decisions that were already discovered in previous work.
 
-- rereading the same files
-- rediscovering the same architecture
-- re-inferring the same workflows
-- repeating prior debugging conclusions
-- spending tokens just to find the right place to work
+KGraph turns that repeated exploration into durable repository intelligence:
 
-KGraph stores durable repository context in a local `.kgraph/` workspace so future AI sessions can navigate directly to relevant files, symbols, domains, and prior cognition.
-
-## What KGraph Is
-
-KGraph is:
-
-- persistent repo cognition
-- semantic navigation infrastructure
-- a context engineering layer
-- local filesystem-based project intelligence
-- an inspectable map of structure, relationships, and durable notes
-
-KGraph is not:
+```text
+AI chat or developer note
+-> KGraph cognition inbox
+-> structured repo knowledge
+-> compact context for future AI sessions
+```
 
-- an AI coding assistant
-- a chatbot
-- a vector database
-- a simple RAG wrapper
-- a cloud service
-- an autonomous agent system
+The result is faster navigation, lower token waste, and more consistent understanding across coding sessions.
 
-## Install And Run
+## Install
 
-KGraph is designed to feel like other developer-native CLI tools: one command to try it, optional global install if you use it often, and a quick version check before running commands.
+Run the latest published package:
 
-Public npm usage is the intended distribution path once the package is published.
+```bash
+npx @kentwynn/kgraph@latest init
+```
 
-Install and run a specific stable release:
+Run a specific stable version:
 
 ```bash
 npx @kentwynn/kgraph@0.1.0 init
 ```
 
-Or run the latest published release:
+Install globally if you use KGraph often:
 
 ```bash
-npx @kentwynn/kgraph@latest init
+npm install -g @kentwynn/kgraph@latest
+kgraph --version
 ```
 
-Use the CLI directly after initialization:
+## Quick Start
+
+Initialize KGraph in a repository and connect your AI tools:
 
 ```bash
-npx @kentwynn/kgraph@latest scan
-npx @kentwynn/kgraph@latest update
-npx @kentwynn/kgraph@latest context "auth token refresh"
+kgraph init --integrations codex,copilot,cursor
 ```
 
-Optional global installation:
+Scan the codebase:
 
 ```bash
-npm install -g @kentwynn/kgraph@latest
-kgraph --version
-kgraph init
 kgraph scan
-kgraph update
-kgraph context "auth token refresh"
 ```
 
-Current local development flow from a fresh clone:
+Ask for compact context before working on an area:
 
 ```bash
-npm install
-npm run build
-npm run kgraph -- --version
-npm run kgraph -- init
-npm run kgraph -- scan
-npm run kgraph -- update
-npm run kgraph -- context "auth token refresh"
+kgraph context "auth token refresh"
 ```
 
-Until the npm package is publicly released, use the local development commands or install directly from the release workflow artifact.
+Process saved chat notes and debugging conclusions:
 
-## MVP CLI
+```bash
+kgraph update
+```
 
-The MVP command surface is intentionally small:
+## CLI
 
 ```bash
 kgraph init
+kgraph init --integrations codex,cursor
+kgraph integrate list
+kgraph integrate add codex copilot cursor claude-code
+kgraph integrate remove cursor
 kgraph scan
 kgraph update
 kgraph context "auth token refresh"
+kgraph context "auth token refresh" --json
 ```
 
-`init` creates the local `.kgraph/` workspace. `scan` refreshes deterministic structure maps. `update` processes Markdown cognition notes. `context` returns compact repository context for a topic.
+## AI Tool Integrations
 
-The package is prepared for npm-style CLI distribution. The MVP includes CI and release artifact packaging, but automatic npm publishing is intentionally left for a later release policy.
+KGraph writes local instruction files so AI tools know how to use the repository knowledge layer during normal coding chats.
 
-## Local-First Privacy
+| Integration | Instruction file |
+| --- | --- |
+| Codex | `AGENTS.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Cursor | `.cursor/rules/kgraph.mdc` |
+| Claude Code | `CLAUDE.md` |
 
-KGraph writes project intelligence to local files in `.kgraph/`.
+Example:
 
-The MVP does not require:
+```bash
+kgraph integrate add codex cursor
+kgraph integrate list
+```
 
-- accounts
-- telemetry
-- cloud infrastructure
-- hosted services
-- databases
-- LLM providers
-- embeddings
-- vector search
-- background daemons
+Generated instructions teach AI tools to:
 
-Generated KGraph data is meant to be human-readable and inspectable with normal text tools.
+- query `kgraph context "<topic>"` before broad repo exploration
+- save useful architecture, workflow, and debugging discoveries to `.kgraph/inbox/`
+- run `kgraph update` to turn notes into durable cognition
+- run `kgraph scan` after refactors, file moves, or renamed functions
 
-## MVP Scope
+KGraph-managed instruction blocks preserve existing user-authored content.
 
-The first version focuses on:
+## Features
 
-- initializing `.kgraph/`
-- scanning repository files
-- extracting JavaScript and TypeScript symbols
-- writing file, symbol, dependency, and relationship maps
-- processing Markdown cognition notes
-- returning compact context for a query
-- keeping maps current as code changes
+- Local `.kgraph/` workspace for repository intelligence
+- JavaScript and TypeScript file, import, export, function, class, and method maps
+- Deterministic relationship maps between files and symbols
+- Markdown cognition inbox for AI chat summaries, decisions, gotchas, and debugging notes
+- Compact context output for AI assistants and scripts
+- JSON output for tool-friendly context retrieval
+- Integration management for Codex, Copilot, Cursor, and Claude Code
+- Stale-reference handling when code changes over time
+- Local-first storage with human-readable JSON, YAML, and Markdown
 
-Out of scope for the MVP:
+## How KGraph Grows
 
-- npm publishing automation
-- deployment
-- cloud infrastructure
-- hosted dashboards
-- graph databases
-- vector databases
-- embeddings
-- autonomous agents
-- VS Code extension
+KGraph is designed to improve as the project changes:
 
-## CI
+```text
+kgraph scan
+  refreshes current structure
 
-The CI pipeline is intentionally small and practical. It runs on pushes to `main` and pull requests targeting `main`, and validates:
+AI chat or developer note
+  captures useful reasoning in .kgraph/inbox/
 
-```bash
-npm ci
-npm run build
-npm test
-npm pack --dry-run
-npm run check:artifacts
-```
+kgraph update
+  converts notes into durable cognition
 
-`check:artifacts` fails if local/generated Spec Kit or KGraph artifacts are committed by mistake, including:
+kgraph context "<topic>"
+  returns focused repository context for future work
+```
 
-- `.kgraph/`
-- `.specify/`
-- `.agents/`
-- `AGENTS.md`
-- `REQUIREMENTS.md`
-- `specs/`
+This creates a feedback loop where normal development and AI-assisted debugging gradually improve the repository knowledge map.
 
-## CD
+## Local-First
 
-For a CLI package, CD means packaging an intentional release, not deploying infrastructure.
+KGraph stores project intelligence in local files inside `.kgraph/`. The MVP does not require accounts, telemetry, hosted services, databases, model providers, embeddings, or background daemons.
 
-KGraph includes a release package workflow that runs only when a maintainer pushes a version tag such as `v0.1.0` or starts the workflow manually. It repeats the core gates, creates the npm tarball, and uploads the package as a GitHub Actions artifact:
+## Development
 
 ```bash
-npm ci
+npm install
 npm run build
 npm test
-npm run check:artifacts
-npm pack
+npm run kgraph -- init --integrations codex,cursor
 ```
 
-This gives maintainers an inspectable package artifact before public npm publishing is enabled.
+## Release
 
-## Roadmap
+CI runs build, tests, package checks, and generated-artifact hygiene on pushes and pull requests.
 
-Near-term:
+Releases are tag-driven. Bump the package version, push the commit, then push the matching tag:
 
-- stabilize the CLI contract
-- improve JS/TS symbol extraction
-- improve cognition note parsing
-- validate context quality against real repositories
-- make package publishing safe and intentional
+```bash
+npm version patch
+git push origin main --follow-tags
+```
 
-Later:
+The release workflow verifies that the tag matches `package.json`, checks that the npm version has not already been published, publishes the package to npm, creates a GitHub Release, and attaches the packed tarball. Manual workflow runs package the project for inspection but do not publish to npm.
+
+## Roadmap
 
 - richer language scanners
+- better cognition extraction
+- graph visualization
 - Git-aware history and rename detection
-- optional MCP integration
-- optional editor integrations
-- visual graph exploration
-- optional LLM-assisted cognition extraction
+- optional editor and MCP integrations

package/dist/cli/commands/init.js

@@ -1,10 +1,29 @@
 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 { runCommand } from "../errors.js";
 export function registerInitCommand(program) {
-    program.command("init").description("Initialize a .kgraph workspace").action(() => runCommand(async () => {
+    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")
+        .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.");
+        const names = normalizeIntegrationNames([
+            ...(options.integration ?? []),
+            ...(options.integrations ? [options.integrations] : [])
+        ]);
+        if (names.length > 0) {
+            const changed = await addIntegrations(workspace, names);
+            console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+        }
     }));
 }
+function collectOption(value, previous) {
+    previous.push(value);
+    return previous;
+}

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

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

package/dist/cli/commands/integrate.js

@@ -0,0 +1,36 @@
+import { addIntegrations, listIntegrations, removeIntegrations } 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";
+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 workspace = await assertWorkspace(process.cwd());
+        const integrations = await listIntegrations(workspace);
+        if (integrations.length === 0) {
+            console.log("No integrations configured.");
+            return;
+        }
+        for (const integration of integrations) {
+            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
+        }
+    }));
+    integrate.command("add").description("Add 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.");
+        }
+        const changed = await addIntegrations(workspace, normalized);
+        console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+    }));
+    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.");
+        }
+        const removed = await removeIntegrations(workspace, normalized);
+        console.log(`Removed integrations: ${removed.join(", ")}`);
+    }));
+}

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { registerInitCommand } from "./commands/init.js";
 import { registerScanCommand } from "./commands/scan.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerContextCommand } from "./commands/context.js";
+import { registerIntegrateCommand } from "./commands/integrate.js";
 export function createProgram() {
     const program = new Command();
     program
@@ -14,6 +15,7 @@ export function createProgram() {
     registerScanCommand(program);
     registerUpdateCommand(program);
     registerContextCommand(program);
+    registerIntegrateCommand(program);
     return program;
 }
 if (import.meta.url === `file://${process.argv[1]}`) {

package/dist/config/config.d.ts

@@ -1,5 +1,6 @@
 import type { KGraphConfig, KGraphWorkspace } from "../types/config.js";
 export declare const DEFAULT_CONFIG: KGraphConfig;
 export declare function writeDefaultConfig(workspace: KGraphWorkspace): Promise<boolean>;
+export declare function saveConfig(workspace: KGraphWorkspace, config: KGraphConfig): Promise<void>;
 export declare function loadConfig(workspace: KGraphWorkspace): Promise<KGraphConfig>;
 export declare function normalizeConfig(config: Partial<KGraphConfig>): KGraphConfig;

package/dist/config/config.js

@@ -9,7 +9,8 @@ export const DEFAULT_CONFIG = {
         precise: [".js", ".jsx", ".ts", ".tsx"]
     },
     maxContextItems: 8,
-    domainHints: {}
+    domainHints: {},
+    integrations: []
 };
 export async function writeDefaultConfig(workspace) {
     if (await pathExists(workspace.configPath)) {
@@ -18,6 +19,9 @@ export async function writeDefaultConfig(workspace) {
     await writeFile(workspace.configPath, YAML.stringify(DEFAULT_CONFIG), "utf8");
     return true;
 }
+export async function saveConfig(workspace, config) {
+    await writeFile(workspace.configPath, YAML.stringify(config), "utf8");
+}
 export async function loadConfig(workspace) {
     if (!(await pathExists(workspace.configPath))) {
         return DEFAULT_CONFIG;
@@ -44,6 +48,35 @@ export function normalizeConfig(config) {
         maxContextItems: typeof config.maxContextItems === "number" && config.maxContextItems > 0
             ? config.maxContextItems
             : DEFAULT_CONFIG.maxContextItems,
-        domainHints: config.domainHints && typeof config.domainHints === "object" ? config.domainHints : {}
+        domainHints: config.domainHints && typeof config.domainHints === "object" ? config.domainHints : {},
+        integrations: normalizeIntegrations(config.integrations)
     };
 }
+function normalizeIntegrations(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const seen = new Set();
+    const integrations = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const candidate = item;
+        if (typeof candidate.name !== "string" ||
+            typeof candidate.targetPath !== "string" ||
+            seen.has(candidate.name)) {
+            continue;
+        }
+        if (!["claude-code", "codex", "copilot", "cursor"].includes(candidate.name)) {
+            continue;
+        }
+        seen.add(candidate.name);
+        integrations.push({
+            name: candidate.name,
+            enabled: candidate.enabled !== false,
+            targetPath: candidate.targetPath
+        });
+    }
+    return integrations;
+}

package/dist/integrations/adapters/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from "../integration-registry.js";
+export declare const claudeCodeAdapter: IntegrationAdapter;

package/dist/integrations/adapters/claude-code.js

@@ -0,0 +1,13 @@
+export const claudeCodeAdapter = {
+    name: "claude-code",
+    label: "Claude Code",
+    targetPath: "CLAUDE.md",
+    instructions: `## KGraph Workflow
+
+- Start repository work by checking \`kgraph context "<topic>"\` when the user asks about a domain, bug, workflow, or feature.
+- Convert stable discoveries from chat into Markdown notes under \`.kgraph/inbox/\`.
+- Run \`kgraph update\` to preserve those notes as durable cognition.
+- Run \`kgraph scan\` after structural code changes.
+- Run \`kgraph visualize\` when visualization support is available and the user wants to inspect the current knowledge map.
+`
+};

package/dist/integrations/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from "../integration-registry.js";
+export declare const codexAdapter: IntegrationAdapter;

package/dist/integrations/adapters/codex.js

@@ -0,0 +1,13 @@
+export const codexAdapter = {
+    name: "codex",
+    label: "Codex",
+    targetPath: "AGENTS.md",
+    instructions: `## KGraph Workflow
+
+- Before broad repository exploration, run \`kgraph context "<topic>"\` to load current repo intelligence.
+- After useful debugging, architecture discovery, workflow learning, or implementation work, write a concise Markdown note into \`.kgraph/inbox/\`.
+- Run \`kgraph update\` after adding inbox notes so KGraph preserves durable cognition.
+- Run \`kgraph scan\` after file moves, function renames, refactors, or other structural changes.
+- When visualization support is available and the developer asks to inspect KGraph, run \`kgraph visualize\` and report the generated local artifact.
+`
+};

package/dist/integrations/adapters/copilot.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from "../integration-registry.js";
+export declare const copilotAdapter: IntegrationAdapter;

package/dist/integrations/adapters/copilot.js

@@ -0,0 +1,13 @@
+export const copilotAdapter = {
+    name: "copilot",
+    label: "GitHub Copilot",
+    targetPath: ".github/copilot-instructions.md",
+    instructions: `## KGraph Workflow
+
+- Use \`kgraph context "<topic>"\` before scanning many files manually.
+- Preserve stable findings by creating Markdown notes in \`.kgraph/inbox/\`.
+- Use \`kgraph update\` to process chat summaries and debugging conclusions into durable cognition.
+- Use \`kgraph scan\` when code structure changes.
+- Use \`kgraph visualize\` when visualization support is available and the developer asks to inspect the repository knowledge map.
+`
+};

package/dist/integrations/adapters/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from "../integration-registry.js";
+export declare const cursorAdapter: IntegrationAdapter;

package/dist/integrations/adapters/cursor.js

@@ -0,0 +1,18 @@
+export const cursorAdapter = {
+    name: "cursor",
+    label: "Cursor",
+    targetPath: ".cursor/rules/kgraph.mdc",
+    instructions: `---
+description: Use KGraph persistent repo intelligence before broad repository exploration
+alwaysApply: true
+---
+
+## KGraph Workflow
+
+- Query \`kgraph context "<topic>"\` before broad file searches when repo cognition may already exist.
+- Store durable chat, debugging, architecture, and workflow discoveries as Markdown notes in \`.kgraph/inbox/\`.
+- Run \`kgraph update\` after adding useful notes.
+- Run \`kgraph scan\` after refactors, moved folders, renamed functions, or other structure changes.
+- Run \`kgraph visualize\` when visualization support is available and the developer asks to inspect the KGraph map.
+`
+};

package/dist/integrations/instruction-blocks.d.ts

@@ -0,0 +1,2 @@
+export declare function upsertManagedBlock(content: string, integrationName: string, instructions: string): string;
+export declare function removeManagedBlock(content: string, integrationName: string): string;

package/dist/integrations/instruction-blocks.js

@@ -0,0 +1,27 @@
+const MARKER_PREFIX = "<!--";
+const MARKER_SUFFIX = "-->";
+export function upsertManagedBlock(content, integrationName, instructions) {
+    const normalized = content.trimEnd();
+    const block = renderManagedBlock(integrationName, instructions);
+    const pattern = managedBlockPattern(integrationName);
+    if (pattern.test(content)) {
+        return content.replace(pattern, block);
+    }
+    return `${normalized}${normalized ? "\n\n" : ""}${block}\n`;
+}
+export function removeManagedBlock(content, integrationName) {
+    return content.replace(managedBlockPattern(integrationName), "").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+function renderManagedBlock(integrationName, instructions) {
+    return [
+        `${MARKER_PREFIX} BEGIN KGRAPH ${integrationName} ${MARKER_SUFFIX}`,
+        instructions.trim(),
+        `${MARKER_PREFIX} END KGRAPH ${integrationName} ${MARKER_SUFFIX}`
+    ].join("\n");
+}
+function managedBlockPattern(integrationName) {
+    return new RegExp(`${escapeRegExp(MARKER_PREFIX)} BEGIN KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}[\\s\\S]*?${escapeRegExp(MARKER_PREFIX)} END KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}\\n?`, "m");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/integrations/integration-registry.d.ts

@@ -0,0 +1,10 @@
+import type { IntegrationName } from "../types/config.js";
+export interface IntegrationAdapter {
+    name: IntegrationName;
+    label: string;
+    targetPath: string;
+    instructions: string;
+}
+export declare function listIntegrationAdapters(): IntegrationAdapter[];
+export declare function getIntegrationAdapter(name: string): IntegrationAdapter;
+export declare function normalizeIntegrationNames(values: string[] | undefined): IntegrationName[];

package/dist/integrations/integration-registry.js

@@ -0,0 +1,39 @@
+import { claudeCodeAdapter } from "./adapters/claude-code.js";
+import { codexAdapter } from "./adapters/codex.js";
+import { copilotAdapter } from "./adapters/copilot.js";
+import { cursorAdapter } from "./adapters/cursor.js";
+const ADAPTERS = [
+    claudeCodeAdapter,
+    codexAdapter,
+    copilotAdapter,
+    cursorAdapter
+].sort((left, right) => left.name.localeCompare(right.name));
+export function listIntegrationAdapters() {
+    return ADAPTERS;
+}
+export function getIntegrationAdapter(name) {
+    const adapter = ADAPTERS.find((item) => item.name === name);
+    if (!adapter) {
+        throw new Error(`Unsupported integration "${name}". Supported integrations: ${ADAPTERS.map((item) => item.name).join(", ")}`);
+    }
+    return adapter;
+}
+export function normalizeIntegrationNames(values) {
+    if (!values || values.length === 0) {
+        return [];
+    }
+    const names = [];
+    const seen = new Set();
+    for (const value of values) {
+        for (const raw of value.split(",")) {
+            const name = raw.trim();
+            if (!name || seen.has(name)) {
+                continue;
+            }
+            const adapter = getIntegrationAdapter(name);
+            seen.add(adapter.name);
+            names.push(adapter.name);
+        }
+    }
+    return names;
+}

package/dist/integrations/integration-store.d.ts

@@ -0,0 +1,10 @@
+import type { IntegrationConfig, IntegrationName, KGraphWorkspace } from "../types/config.js";
+export interface IntegrationStatus {
+    name: IntegrationName;
+    enabled: boolean;
+    targetPath: string;
+    targetExists: boolean;
+}
+export declare function listIntegrations(workspace: KGraphWorkspace): Promise<IntegrationStatus[]>;
+export declare function addIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationConfig[]>;
+export declare function removeIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationName[]>;

package/dist/integrations/integration-store.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadConfig, saveConfig } from "../config/config.js";
+import { pathExists } from "../storage/kgraph-paths.js";
+import { getIntegrationAdapter } from "./integration-registry.js";
+import { removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
+export async function listIntegrations(workspace) {
+    const config = await loadConfig(workspace);
+    const statuses = await Promise.all(config.integrations.map(async (integration) => ({
+        name: integration.name,
+        enabled: integration.enabled,
+        targetPath: integration.targetPath,
+        targetExists: await pathExists(path.join(workspace.rootPath, integration.targetPath))
+    })));
+    return statuses.sort((left, right) => left.name.localeCompare(right.name));
+}
+export async function addIntegrations(workspace, names) {
+    const config = await loadConfig(workspace);
+    const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
+    const changed = [];
+    for (const name of names) {
+        const adapter = getIntegrationAdapter(name);
+        const next = {
+            name: adapter.name,
+            enabled: true,
+            targetPath: adapter.targetPath
+        };
+        byName.set(adapter.name, next);
+        await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, adapter.instructions);
+        changed.push(next);
+    }
+    config.integrations = [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+    await saveConfig(workspace, config);
+    return changed;
+}
+export async function removeIntegrations(workspace, names) {
+    const config = await loadConfig(workspace);
+    const removeNames = new Set(names);
+    const removed = [];
+    for (const name of removeNames) {
+        const adapter = getIntegrationAdapter(name);
+        await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
+        removed.push(adapter.name);
+    }
+    config.integrations = config.integrations.filter((integration) => !removeNames.has(integration.name));
+    await saveConfig(workspace, config);
+    return removed.sort((left, right) => left.localeCompare(right));
+}
+async function writeIntegrationInstructions(rootPath, targetPath, integrationName, instructions) {
+    const fullPath = path.join(rootPath, targetPath);
+    const existing = (await pathExists(fullPath)) ? await readFile(fullPath, "utf8") : "";
+    const next = upsertManagedBlock(existing, integrationName, instructions);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, next, "utf8");
+}
+async function removeIntegrationInstructions(rootPath, targetPath, integrationName) {
+    const fullPath = path.join(rootPath, targetPath);
+    if (!(await pathExists(fullPath))) {
+        return;
+    }
+    const existing = await readFile(fullPath, "utf8");
+    const next = removeManagedBlock(existing, integrationName);
+    if (next.trim().length === 0) {
+        await rm(fullPath, { force: true });
+        return;
+    }
+    await writeFile(fullPath, next, "utf8");
+}

package/dist/types/config.d.ts

@@ -6,11 +6,18 @@ export interface KGraphConfig {
     };
     maxContextItems: number;
     domainHints: Record<string, DomainHint>;
+    integrations: IntegrationConfig[];
 }
 export interface DomainHint {
     paths?: string[];
     tags?: string[];
 }
+export type IntegrationName = "claude-code" | "codex" | "copilot" | "cursor";
+export interface IntegrationConfig {
+    name: IntegrationName;
+    enabled: boolean;
+    targetPath: string;
+}
 export interface KGraphWorkspace {
     rootPath: string;
     kgraphPath: string;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
-    "kgraph": "./dist/cli/index.js"
+    "kgraph": "dist/cli/index.js"
   },
   "files": [
     "dist",