@kentwynn/kgraph 0.1.2 → 0.1.4

package/README.md

@@ -82,28 +82,29 @@ kgraph context "auth token refresh" --json
 
 ## AI Tool Integrations
 
-KGraph writes local instruction files so AI tools know how to use the repository knowledge layer during normal coding chats.
+KGraph writes local instruction files and command/prompt packs so AI tools can use the repository knowledge layer during normal coding chats.
 
-| Integration | Instruction file |
-| --- | --- |
-| Codex | `AGENTS.md` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| Cursor | `.cursor/rules/kgraph.mdc` |
-| Claude Code | `CLAUDE.md` |
+| Integration | Always-on guidance | KGraph command assets |
+| --- | --- | --- |
+| Codex | `AGENTS.md` | `.agents/skills/kgraph*/SKILL.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.github/prompts/kgraph*.prompt.md` |
+| Cursor | `.cursor/rules/kgraph.mdc` | `.cursor/rules/kgraph-commands.mdc` |
+| Claude Code | `CLAUDE.md` | `.claude/commands/kgraph*.md` |
 
 Example:
 
 ```bash
-kgraph integrate add codex cursor
+kgraph integrate add codex copilot cursor claude-code
 kgraph integrate list
 ```
 
-Generated instructions teach AI tools to:
+This gives supported tools reusable KGraph workflows similar to Spec Kit-style commands:
+
+- KGraph context: query `kgraph context "<topic>"` before broad repo exploration
+- KGraph update: save durable chat/debugging/workflow discoveries to `.kgraph/inbox/`, then run `kgraph update`
+- KGraph scan: run `kgraph scan` after refactors, file moves, renamed functions, or dependency changes
 
-- 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
+The exact invocation depends on the host tool. Copilot uses prompt files, Codex uses skills, Cursor uses rules, and Claude Code uses command files.
 
 KGraph-managed instruction blocks preserve existing user-authored content.
 
@@ -115,7 +116,7 @@ KGraph-managed instruction blocks preserve existing user-authored content.
 - 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
+- Integration management and command packs 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
 

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+export declare function renderRootHelp(useColor?: boolean): string;

package/dist/cli/help.js

@@ -0,0 +1,60 @@
+import { Chalk } from "chalk";
+import figlet from "figlet";
+export function renderRootHelp(useColor = supportsColor()) {
+    const theme = new Chalk({ level: useColor ? 3 : 0 });
+    const command = (name, description) => `  ${theme.green(name.padEnd(30))} ${description}`;
+    const logo = renderLogo();
+    return [
+        "",
+        theme.hex("#7dd3fc").bold(logo),
+        "",
+        `  ${theme.bold("KGraph")} ${theme.dim("Persistent repo intelligence for AI coding tools")}`,
+        "",
+        `  ${theme.hex("#c084fc")("Build a local knowledge layer that helps Codex, Copilot, Cursor,")}`,
+        `  ${theme.hex("#c084fc")("and Claude Code reuse repo structure, decisions, and debugging history.")}`,
+        "",
+        theme.bold("Usage"),
+        "  kgraph <command> [options]",
+        "",
+        theme.bold("Start"),
+        command("init", "Create .kgraph/ workspace"),
+        command("init --integrations codex,cursor", "Initialize and connect AI tools"),
+        "",
+        theme.bold("Workflows"),
+        command("scan", "Refresh file, symbol, import, and relationship maps"),
+        command("context \"auth token refresh\"", "Return compact context for an AI chat"),
+        command("update", "Process .kgraph/inbox Markdown cognition notes"),
+        "",
+        theme.bold("Integrations"),
+        command("integrate list", "Show configured AI tool integrations"),
+        command("integrate add codex copilot", "Write KGraph instructions for AI tools"),
+        command("integrate remove cursor", "Remove KGraph-managed instruction blocks"),
+        "",
+        theme.bold("Options"),
+        command("-V, --version", "Show version"),
+        command("-h, --help", "Show this help"),
+        "",
+        `${theme.yellow("Examples")}`,
+        "  kgraph init --integrations codex,copilot,cursor",
+        "  kgraph scan",
+        "  kgraph context \"blog admin token usage\" --json",
+        "",
+        theme.dim("Docs: https://github.com/kentwynn/KGraph#readme"),
+        ""
+    ].join("\n");
+}
+function renderLogo() {
+    try {
+        return figlet.textSync("KGraph", {
+            font: "ANSI Shadow",
+            horizontalLayout: "default",
+            verticalLayout: "default"
+        });
+    }
+    catch {
+        return "KGraph";
+    }
+}
+function supportsColor() {
+    return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+}

package/dist/cli/index.js

@@ -7,12 +7,22 @@ import { registerScanCommand } from "./commands/scan.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerContextCommand } from "./commands/context.js";
 import { registerIntegrateCommand } from "./commands/integrate.js";
+import { renderRootHelp } from "./help.js";
 export function createProgram() {
     const program = new Command();
     program
         .name("kgraph")
         .description("Persistent repo intelligence for AI coding assistants")
-        .version("0.1.1");
+        .version("0.1.2")
+        .addHelpText("beforeAll", renderRootHelp())
+        .helpOption(false);
+    program.option("-h, --help", "Show this help");
+    program.hook("preAction", (thisCommand) => {
+        if (thisCommand.opts().help) {
+            console.log(renderRootHelp());
+            process.exitCode = 0;
+        }
+    });
     registerInitCommand(program);
     registerScanCommand(program);
     registerUpdateCommand(program);
@@ -21,7 +31,13 @@ export function createProgram() {
     return program;
 }
 if (isCliEntrypoint()) {
-    await createProgram().parseAsync(process.argv);
+    const program = createProgram();
+    if (process.argv.length <= 2 || process.argv.includes("-h") || process.argv.includes("--help")) {
+        console.log(renderRootHelp());
+    }
+    else {
+        await program.parseAsync(process.argv);
+    }
 }
 function isCliEntrypoint() {
     if (!process.argv[1]) {

package/dist/config/config.js

@@ -4,7 +4,36 @@ import { pathExists } from "../storage/kgraph-paths.js";
 import { KGraphError } from "../cli/errors.js";
 export const DEFAULT_CONFIG = {
     include: ["**/*"],
-    exclude: [".git", "node_modules", "dist", "build", ".next", "coverage", ".kgraph"],
+    exclude: [
+        ".git",
+        "node_modules",
+        "dist",
+        "build",
+        ".next",
+        "coverage",
+        ".kgraph",
+        ".npm-cache",
+        ".cache",
+        ".turbo",
+        ".vite",
+        ".nuxt",
+        ".output",
+        ".vercel",
+        ".serverless",
+        ".agents",
+        ".specify",
+        "specs",
+        ".cursor",
+        ".claude",
+        ".github/copilot-instructions.md",
+        ".github/prompts",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "REQUIREMENTS.md",
+        "*.log",
+        "*.tgz",
+        ".DS_Store"
+    ],
     languages: {
         precise: [".js", ".jsx", ".ts", ".tsx"]
     },
@@ -39,7 +68,7 @@ export async function loadConfig(workspace) {
 export function normalizeConfig(config) {
     return {
         include: Array.isArray(config.include) ? config.include : DEFAULT_CONFIG.include,
-        exclude: Array.isArray(config.exclude) ? config.exclude : DEFAULT_CONFIG.exclude,
+        exclude: mergeUnique(DEFAULT_CONFIG.exclude, Array.isArray(config.exclude) ? config.exclude : []),
         languages: {
             precise: Array.isArray(config.languages?.precise)
                 ? config.languages.precise
@@ -52,6 +81,9 @@ export function normalizeConfig(config) {
         integrations: normalizeIntegrations(config.integrations)
     };
 }
+function mergeUnique(base, extra) {
+    return [...new Set([...base, ...extra])];
+}
 function normalizeIntegrations(value) {
     if (!Array.isArray(value)) {
         return [];

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

@@ -9,5 +9,31 @@ export const claudeCodeAdapter = {
 - 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.
+`,
+    commandFiles: [
+        {
+            path: ".claude/commands/kgraph.md",
+            content: `Use KGraph persistent repo intelligence for the current request.
+
+1. Infer the topic from the user's request.
+2. Run \`kgraph context "<topic>"\`.
+3. Use the returned files, symbols, relationships, and cognition before broad exploration.
+4. Save durable discoveries to \`.kgraph/inbox/\` and run \`kgraph update\` when appropriate.
+`
+        },
+        {
+            path: ".claude/commands/kgraph-update.md",
+            content: `Preserve useful chat knowledge in KGraph.
+
+Create a concise Markdown note in \`.kgraph/inbox/\` from durable discoveries in this conversation, then run \`kgraph update\`.
+`
+        },
+        {
+            path: ".claude/commands/kgraph-scan.md",
+            content: `Refresh KGraph structural maps.
+
+Run \`kgraph scan\` after code structure changes and report the scan summary.
 `
+        }
+    ]
 };

package/dist/integrations/adapters/codex.js

@@ -9,5 +9,48 @@ export const codexAdapter = {
 - 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.
+`,
+    commandFiles: [
+        {
+            path: ".agents/skills/kgraph/SKILL.md",
+            content: `---
+name: "kgraph"
+description: "Use KGraph persistent repo intelligence for the current coding task."
+---
+
+Use this skill when the user asks to use KGraph, requests repo context, or asks you to avoid rediscovering repository structure.
+
+Workflow:
+
+1. Infer the current topic from the user request.
+2. Run \`kgraph context "<topic>"\` before broad repo exploration.
+3. Use KGraph's files, symbols, relationships, and cognition as navigation hints.
+4. After durable discoveries, write a concise Markdown note to \`.kgraph/inbox/\`.
+5. Run \`kgraph update\` if you created an inbox note.
+6. Run \`kgraph scan\` after structural changes.
+`
+        },
+        {
+            path: ".agents/skills/kgraph-update/SKILL.md",
+            content: `---
+name: "kgraph-update"
+description: "Preserve useful chat discoveries into KGraph cognition."
+---
+
+Use this skill when the user asks to update KGraph memory or preserve what was learned.
+
+Write a concise Markdown note under \`.kgraph/inbox/\` with durable architecture, debugging, workflow, file, symbol, or gotcha knowledge. Then run \`kgraph update\`.
+`
+        },
+        {
+            path: ".agents/skills/kgraph-scan/SKILL.md",
+            content: `---
+name: "kgraph-scan"
+description: "Refresh KGraph structural maps after code changes."
+---
+
+Run \`kgraph scan\` after files move, functions are renamed, folders are refactored, or dependencies change. Report the scan summary and any obvious exclude/config problems.
 `
+        }
+    ]
 };

package/dist/integrations/adapters/copilot.js

@@ -9,5 +9,45 @@ export const copilotAdapter = {
 - 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.
+`,
+    commandFiles: [
+        {
+            path: ".github/prompts/kgraph.prompt.md",
+            content: `---
+mode: agent
+description: Use KGraph persistent repo intelligence for this request
+---
+
+Use KGraph for the current task.
+
+1. If the user provided a topic, run \`kgraph context "<topic>"\` first. If not, infer a concise topic from the request.
+2. Use the returned files, symbols, relationships, and cognition before broad repository exploration.
+3. If you discover durable architecture, debugging, workflow, or gotcha knowledge, create a Markdown note in \`.kgraph/inbox/\`.
+4. If you add an inbox note, run \`kgraph update\`.
+5. If code structure changed, run \`kgraph scan\`.
+`
+        },
+        {
+            path: ".github/prompts/kgraph-update.prompt.md",
+            content: `---
+mode: agent
+description: Preserve recent useful chat knowledge in KGraph
+---
+
+Create a concise Markdown cognition note in \`.kgraph/inbox/\` from the useful stable knowledge in this conversation, then run \`kgraph update\`.
+
+Capture only durable information: architecture discoveries, debugging conclusions, workflow conventions, important files, important functions, and gotchas. Do not store temporary chatter.
+`
+        },
+        {
+            path: ".github/prompts/kgraph-scan.prompt.md",
+            content: `---
+mode: agent
+description: Refresh KGraph structural maps after repository changes
+---
+
+Run \`kgraph scan\` and report the number of files and symbols scanned. If scan output suggests generated/cache files were included, mention that the exclude configuration may need adjustment.
 `
+        }
+    ]
 };

package/dist/integrations/adapters/cursor.js

@@ -14,5 +14,23 @@ alwaysApply: true
 - 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.
+`,
+    commandFiles: [
+        {
+            path: ".cursor/rules/kgraph-commands.mdc",
+            content: `---
+description: KGraph command workflows for repo context, update, and scan
+alwaysApply: false
+---
+
+# KGraph Commands
+
+Use these workflows when the user asks for KGraph:
+
+- KGraph context: run \`kgraph context "<topic>"\` before broad exploration.
+- KGraph update: write durable findings to \`.kgraph/inbox/\`, then run \`kgraph update\`.
+- KGraph scan: run \`kgraph scan\` after refactors, file moves, renamed functions, or dependency changes.
 `
+        }
+    ]
 };

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

@@ -4,6 +4,11 @@ export interface IntegrationAdapter {
     label: string;
     targetPath: string;
     instructions: string;
+    commandFiles?: IntegrationCommandFile[];
+}
+export interface IntegrationCommandFile {
+    path: string;
+    content: string;
 }
 export declare function listIntegrationAdapters(): IntegrationAdapter[];
 export declare function getIntegrationAdapter(name: string): IntegrationAdapter;

package/dist/integrations/integration-store.js

@@ -27,6 +27,7 @@ export async function addIntegrations(workspace, names) {
         };
         byName.set(adapter.name, next);
         await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, adapter.instructions);
+        await writeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         changed.push(next);
     }
     config.integrations = [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
@@ -40,6 +41,7 @@ export async function removeIntegrations(workspace, names) {
     for (const name of removeNames) {
         const adapter = getIntegrationAdapter(name);
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
+        await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         removed.push(adapter.name);
     }
     config.integrations = config.integrations.filter((integration) => !removeNames.has(integration.name));
@@ -66,3 +68,15 @@ async function removeIntegrationInstructions(rootPath, targetPath, integrationNa
     }
     await writeFile(fullPath, next, "utf8");
 }
+async function writeIntegrationCommandFiles(rootPath, files) {
+    for (const file of files) {
+        const fullPath = path.join(rootPath, file.path);
+        await mkdir(path.dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, file.content.trimEnd() + "\n", "utf8");
+    }
+}
+async function removeIntegrationCommandFiles(rootPath, files) {
+    for (const file of files) {
+        await rm(path.join(rootPath, file.path), { force: true });
+    }
+}

package/dist/scanner/file-classifier.d.ts

@@ -1,4 +1,5 @@
 import type { KGraphConfig } from "../types/config.js";
 export declare function shouldExclude(repoPath: string, config: KGraphConfig): boolean;
+export declare function buildFastGlobIgnore(exclude: string[]): string[];
 export declare function detectLanguage(filePath: string): string;
 export declare function isPreciseLanguage(filePath: string, config: KGraphConfig): boolean;

package/dist/scanner/file-classifier.js

@@ -10,11 +10,27 @@ const LANGUAGE_BY_EXTENSION = {
     ".yml": "yaml"
 };
 export function shouldExclude(repoPath, config) {
-    const parts = repoPath.split(/[\\/]/);
-    return config.exclude.some((pattern) => {
-        const normalized = pattern.replace(/\/$/, "");
-        return parts.includes(normalized) || repoPath === normalized || repoPath.startsWith(`${normalized}/`);
-    });
+    const normalizedPath = normalizeRepoPath(repoPath);
+    return config.exclude.some((pattern) => matchesExcludePattern(normalizedPath, pattern));
+}
+export function buildFastGlobIgnore(exclude) {
+    const patterns = new Set();
+    for (const pattern of exclude) {
+        const normalized = normalizeRepoPath(pattern).replace(/\/$/, "");
+        if (!normalized) {
+            continue;
+        }
+        if (hasGlob(normalized)) {
+            patterns.add(normalized);
+            patterns.add(`**/${normalized}`);
+            continue;
+        }
+        patterns.add(normalized);
+        patterns.add(`**/${normalized}`);
+        patterns.add(`${normalized}/**`);
+        patterns.add(`**/${normalized}/**`);
+    }
+    return [...patterns];
 }
 export function detectLanguage(filePath) {
     return LANGUAGE_BY_EXTENSION[path.extname(filePath)] ?? "unknown";
@@ -22,3 +38,50 @@ export function detectLanguage(filePath) {
 export function isPreciseLanguage(filePath, config) {
     return config.languages.precise.includes(path.extname(filePath));
 }
+function matchesExcludePattern(repoPath, pattern) {
+    const normalized = normalizeRepoPath(pattern).replace(/\/$/, "");
+    if (!normalized) {
+        return false;
+    }
+    if (hasGlob(normalized)) {
+        return globToRegExp(normalized).test(repoPath) || globToRegExp(`**/${normalized}`).test(repoPath);
+    }
+    if (repoPath === normalized || repoPath.startsWith(`${normalized}/`)) {
+        return true;
+    }
+    if (!normalized.includes("/")) {
+        return repoPath.split("/").includes(normalized);
+    }
+    return false;
+}
+function normalizeRepoPath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+function hasGlob(pattern) {
+    return /[*?[\]{}]/.test(pattern);
+}
+function globToRegExp(pattern) {
+    let source = "";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const next = pattern[index + 1];
+        if (char === "*" && next === "*") {
+            source += ".*";
+            index += 1;
+            continue;
+        }
+        if (char === "*") {
+            source += "[^/]*";
+            continue;
+        }
+        if (char === "?") {
+            source += "[^/]";
+            continue;
+        }
+        source += escapeRegExp(char);
+    }
+    return new RegExp(`^${source}$`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}

package/dist/scanner/repo-scanner.js

@@ -2,7 +2,7 @@ import { readFile, stat } from "node:fs/promises";
 import crypto from "node:crypto";
 import path from "node:path";
 import fg from "fast-glob";
-import { detectLanguage, isPreciseLanguage, shouldExclude } from "./file-classifier.js";
+import { buildFastGlobIgnore, detectLanguage, isPreciseLanguage, shouldExclude } from "./file-classifier.js";
 import { extractTsSymbols } from "./ts-symbol-extractor.js";
 export async function scanRepository(rootPath, config, previous) {
     const entries = await fg(config.include, {
@@ -10,7 +10,7 @@ export async function scanRepository(rootPath, config, previous) {
         dot: true,
         onlyFiles: true,
         unique: true,
-        ignore: config.exclude.map((item) => `**/${item}/**`)
+        ignore: buildFastGlobIgnore(config.exclude)
     });
     const files = [];
     const symbols = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -38,8 +38,10 @@
   },
   "homepage": "https://github.com/kentwynn/KGraph#readme",
   "dependencies": {
+    "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
+    "figlet": "^1.11.0",
     "typescript": "^5.9.3",
     "yaml": "^2.5.1"
   },