@kentwynn/kgraph 0.1.7 → 0.1.8

package/dist/cli/help.js

@@ -1,58 +1,60 @@
-import { Chalk } from "chalk";
-import figlet from "figlet";
+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");
+        '',
+        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'),
+        command('visualize', 'Interactive dependency graph at http://localhost:4242'),
+        command('history', 'Timeline of processed cognition sessions'),
+        '',
+        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"
+        return figlet.textSync('KGraph', {
+            font: 'ANSI Shadow',
+            horizontalLayout: 'default',
+            verticalLayout: 'default',
         });
     }
     catch {
-        return "KGraph";
+        return 'KGraph';
     }
 }
 function supportsColor() {

package/dist/cli/index.js

@@ -4,10 +4,12 @@ import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { registerContextCommand } from './commands/context.js';
+import { registerHistoryCommand } from './commands/history.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerScanCommand } from './commands/scan.js';
 import { registerUpdateCommand } from './commands/update.js';
+import { registerVisualizeCommand } from './commands/visualize.js';
 import { renderRootHelp } from './help.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -31,6 +33,8 @@ export function createProgram() {
     registerUpdateCommand(program);
     registerContextCommand(program);
     registerIntegrateCommand(program);
+    registerVisualizeCommand(program);
+    registerHistoryCommand(program);
     return program;
 }
 if (isCliEntrypoint()) {

package/dist/cognition/markdown-note-parser.d.ts

@@ -1,2 +1,2 @@
-import type { ParsedCognitionNote } from "../types/cognition.js";
+import type { ParsedCognitionNote } from '../types/cognition.js';
 export declare function parseMarkdownNote(markdown: string): ParsedCognitionNote;

package/dist/cognition/markdown-note-parser.js

@@ -1,37 +1,36 @@
-import YAML from "yaml";
-const PATH_REF = /(?:^|\s)([\w./-]+\.(?:ts|tsx|js|jsx|json|md|yaml|yml))(?:\s|$|[),.;])/g;
-const SYMBOL_REF = /`?([A-Za-z_$][\w$]{2,})`?/g;
+import YAML from 'yaml';
+const PATH_REF = /(?:^|\s|`?)([\w./-]+\.(?:ts|tsx|js|jsx|json|md|yaml|yml))(?:\s|$|[),.;`])/g;
 export function parseMarkdownNote(markdown) {
     const warnings = [];
     const { frontmatter, body } = splitFrontmatter(markdown, warnings);
     const sections = parseSections(body);
-    const frontmatterTitle = typeof frontmatter.title === "string" ? frontmatter.title : undefined;
-    const title = extractTitle(body) ?? frontmatterTitle ?? "Untitled Cognition Note";
-    const combined = Object.values(sections).join("\n");
+    const frontmatterTitle = typeof frontmatter.title === 'string' ? frontmatter.title : undefined;
+    const title = extractTitle(body) ?? frontmatterTitle ?? 'Untitled Cognition Note';
+    const combined = Object.values(sections).join('\n');
     return {
         title,
-        domain: typeof frontmatter.domain === "string" ? frontmatter.domain : undefined,
+        domain: typeof frontmatter.domain === 'string' ? frontmatter.domain : undefined,
         tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
         summary: sections.Summary,
         sections,
         relatedFiles: unique(extractMatches(combined, PATH_REF)),
         relatedSymbols: unique(extractSymbolRefs(combined)),
-        warnings
+        warnings,
     };
 }
 function splitFrontmatter(markdown, warnings) {
-    if (!markdown.startsWith("---\n")) {
+    if (!markdown.startsWith('---\n')) {
         return { frontmatter: {}, body: markdown };
     }
-    const end = markdown.indexOf("\n---", 4);
+    const end = markdown.indexOf('\n---', 4);
     if (end === -1) {
-        warnings.push("Frontmatter start found without closing delimiter.");
+        warnings.push('Frontmatter start found without closing delimiter.');
         return { frontmatter: {}, body: markdown };
     }
     try {
         return {
             frontmatter: (YAML.parse(markdown.slice(4, end)) ?? {}),
-            body: markdown.slice(end + 4)
+            body: markdown.slice(end + 4),
         };
     }
     catch (error) {
@@ -53,7 +52,7 @@ function parseSections(body) {
         sections[heading] = body.slice(start, end).trim();
     }
     if (Object.keys(sections).length === 0) {
-        sections.Summary = body.replace(/^#\s+.+$/m, "").trim();
+        sections.Summary = body.replace(/^#\s+.+$/m, '').trim();
     }
     return sections;
 }
@@ -61,10 +60,22 @@ function extractMatches(text, regex) {
     return [...text.matchAll(regex)].map((match) => match[1]);
 }
 function extractSymbolRefs(text) {
-    const stopwords = new Set(["Summary", "Related", "Files", "Functions", "Decisions", "Debugging", "Conclusions"]);
-    return [...text.matchAll(SYMBOL_REF)]
-        .map((match) => match[1])
-        .filter((item) => !stopwords.has(item) && !item.includes("."));
+    const stopwords = new Set([
+        'Summary',
+        'Related',
+        'Files',
+        'Functions',
+        'Decisions',
+        'Debugging',
+        'Conclusions',
+    ]);
+    // Backtick-quoted: accept any identifier in backticks
+    const backtickSymbols = [...text.matchAll(/`([A-Za-z_$][\w$]{2,})`/g)].map((m) => m[1]);
+    // Plain text: only camelCase, PascalCase, ALL_CAPS, or snake_case (must contain uppercase or underscore after first char)
+    const plainSymbols = [...text.matchAll(/\b([A-Za-z_$][\w$]{2,})\b/g)]
+        .map((m) => m[1])
+        .filter((item) => /[A-Z_]/.test(item.slice(1)));
+    return unique([...backtickSymbols, ...plainSymbols].filter((item) => !stopwords.has(item) && !item.includes('.')));
 }
 function unique(items) {
     return [...new Set(items)];

package/dist/context/context-query.d.ts

@@ -1,7 +1,6 @@
-import type { KGraphConfig } from "../types/config.js";
-import type { ContextResponse } from "../types/cognition.js";
-import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from "../types/maps.js";
-import type { KGraphWorkspace } from "../types/config.js";
+import type { ContextResponse } from '../types/cognition.js';
+import type { KGraphConfig, KGraphWorkspace } from '../types/config.js';
+import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
 export declare function queryContext(workspace: KGraphWorkspace, config: KGraphConfig, maps: {
     fileMap: FileMap;
     symbolMap: SymbolMap;

package/dist/context/context-query.js

@@ -1,34 +1,45 @@
-import { readCognitionNotes, readDomainRecords } from "../storage/cognition-store.js";
-import { rankByFields } from "./ranking.js";
+import { readCognitionNotes, readDomainRecords, } from '../storage/cognition-store.js';
+import { rankByFields } from './ranking.js';
 export async function queryContext(workspace, config, maps, query) {
     const cognition = await readCognitionNotes(workspace);
     const domains = await readDomainRecords(workspace);
     const max = config.maxContextItems;
     const relevantFiles = rankByFields(query, maps.fileMap.files, [
-        { name: "path", value: (file) => file.path },
-        { name: "language", value: (file) => file.language }
+        { name: 'path', value: (file) => file.path },
+        { name: 'language', value: (file) => file.language },
     ]).slice(0, max);
     const relevantSymbols = rankByFields(query, maps.symbolMap.symbols, [
-        { name: "name", value: (symbol) => symbol.name },
-        { name: "path", value: (symbol) => symbol.filePath },
-        { name: "kind", value: (symbol) => symbol.kind }
+        { name: 'name', value: (symbol) => symbol.name },
+        { name: 'path', value: (symbol) => symbol.filePath },
+        { name: 'kind', value: (symbol) => symbol.kind },
     ]).slice(0, max);
     const relevantCognition = rankByFields(query, cognition, [
-        { name: "title", value: (note) => note.title },
-        { name: "domain", value: (note) => note.domain },
-        { name: "tags", value: (note) => note.tags },
-        { name: "files", value: (note) => note.relatedFiles },
-        { name: "symbols", value: (note) => note.relatedSymbols },
-        { name: "summary", value: (note) => note.summary }
+        { name: 'title', value: (note) => note.title },
+        { name: 'domain', value: (note) => note.domain },
+        { name: 'tags', value: (note) => note.tags },
+        { name: 'files', value: (note) => note.relatedFiles },
+        { name: 'symbols', value: (note) => note.relatedSymbols },
+        { name: 'summary', value: (note) => note.summary },
     ]).slice(0, max);
     const matchedDomains = rankByFields(query, domains, [
-        { name: "name", value: (domain) => domain.name },
-        { name: "tags", value: (domain) => domain.tags },
-        { name: "path", value: (domain) => domain.pathHints }
+        { name: 'name', value: (domain) => domain.name },
+        { name: 'tags', value: (domain) => domain.tags },
+        { name: 'path', value: (domain) => domain.pathHints },
     ]).slice(0, max);
+    const filePaths = new Set(maps.fileMap.files.map((f) => f.path));
+    const symbolNames = new Set(maps.symbolMap.symbols.map((s) => s.name));
     const staleReferences = cognition
-        .filter((note) => note.referencesStatus === "stale" || note.referencesStatus === "unresolved" || note.referencesStatus === "mixed")
-        .flatMap((note) => [...note.relatedFiles, ...note.relatedSymbols].map((ref) => `${note.title}: ${ref}`));
+        .filter((note) => note.referencesStatus === 'stale' ||
+        note.referencesStatus === 'unresolved' ||
+        note.referencesStatus === 'mixed')
+        .flatMap((note) => [
+        ...note.relatedFiles
+            .filter((f) => !filePaths.has(f))
+            .map((ref) => `${note.title}: ${ref}`),
+        ...note.relatedSymbols
+            .filter((s) => !symbolNames.has(s))
+            .map((ref) => `${note.title}: ${ref}`),
+    ]);
     return {
         query,
         matchedDomains,
@@ -37,6 +48,6 @@ export async function queryContext(workspace, config, maps, query) {
         relevantCognition,
         relationships: maps.relationshipMap.relationships.slice(0, max),
         staleReferences,
-        warnings: []
+        warnings: [],
     };
 }

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

@@ -16,6 +16,8 @@ Before exploring the repository, run \`kgraph context "<topic>"\` to load existi
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
 4. Save durable discoveries to \`.kgraph/inbox/\` and immediately run \`kgraph update\`.
 5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\` and report the summary. Skip it otherwise.
+6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 `,
         },
         {
@@ -26,6 +28,16 @@ Before exploring the repository, run \`kgraph context "<topic>"\` to load existi
         {
             path: '.claude/commands/kgraph-update.md',
             content: `Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-visualize.md',
+            content: `Run \`kgraph visualize\` to start an interactive dependency graph at http://localhost:4242. Opens in browser automatically. Use \`--no-open\` to print URL only, \`--port <n>\` for a custom port.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-history.md',
+            content: `Run \`kgraph history\` to show a timeline of all processed cognition sessions. Includes git author attribution when available. Use \`--last <n>\` to limit entries, \`--json\` for machine-readable output.
 `,
         },
     ],

package/dist/integrations/adapters/codex.js

@@ -23,6 +23,8 @@ Workflow:
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
 4. After durable discoveries, write a concise Markdown note to \`.kgraph/inbox/\` and immediately run \`kgraph update\`.
 5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\`. Skip it otherwise.
+6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 `,
         },
     ],

package/dist/integrations/adapters/copilot.js

@@ -10,8 +10,8 @@ Before exploring the repository, run \`kgraph context "<topic>"\` to load existi
         {
             path: '.github/prompts/kgraph-scan.prompt.md',
             content: `---
-mode: agent
 description: Refresh KGraph file, symbol, import, and relationship maps
+agent: agent
 ---
 
 Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
@@ -20,11 +20,31 @@ Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
         {
             path: '.github/prompts/kgraph-update.prompt.md',
             content: `---
-mode: agent
 description: Process KGraph inbox notes into durable cognition
+agent: agent
 ---
 
 Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-visualize.prompt.md',
+            content: `---
+description: Open interactive KGraph dependency graph in browser
+agent: agent
+---
+
+Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-history.prompt.md',
+            content: `---
+description: Show timeline of KGraph cognition sessions with git attribution
+agent: agent
+---
+
+Run \`kgraph history\` to display the timeline of all processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
 `,
         },
     ],

package/dist/integrations/adapters/cursor.js

@@ -9,7 +9,7 @@ alwaysApply: true
 
 ## KGraph Workflow
 
-Before exploring the repository, run \`kgraph context "<topic>"\` to load existing repo intelligence. Run \`kgraph scan\` and \`kgraph update\` manually when needed.
+Before exploring the repository, run \`kgraph context "<topic>"\` to load existing repo intelligence. Run \`kgraph scan\` and \`kgraph update\` manually when needed. Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242. Run \`kgraph history\` to review the timeline of past cognition sessions.
 `,
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/visualization/graph-builder.d.ts

@@ -0,0 +1,16 @@
+import type { CognitionNote } from '../types/cognition.js';
+import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
+export interface CytoscapeElement {
+    data: Record<string, unknown>;
+    classes?: string;
+}
+export interface GraphData {
+    elements: CytoscapeElement[];
+    meta: {
+        fileCount: number;
+        symbolCount: number;
+        cognitionCount: number;
+        generatedAt: string;
+    };
+}
+export declare function buildGraph(fileMap: FileMap, symbolMap: SymbolMap, dependencyMap: DependencyMap, _relationshipMap: RelationshipMap, cognitionNotes: CognitionNote[]): GraphData;

package/dist/visualization/graph-builder.js

@@ -0,0 +1,100 @@
+const LANGUAGE_COLORS = {
+    typescript: '#3b82f6',
+    javascript: '#f59e0b',
+    json: '#6b7280',
+    markdown: '#10b981',
+    yaml: '#8b5cf6',
+    css: '#06b6d4',
+    html: '#f97316',
+};
+const STATUS_COLORS = {
+    current: '#10b981',
+    mixed: '#f59e0b',
+    stale: '#ef4444',
+    unresolved: '#6b7280',
+};
+export function buildGraph(fileMap, symbolMap, dependencyMap, _relationshipMap, cognitionNotes) {
+    const elements = [];
+    const edgeIds = new Set();
+    for (const file of fileMap.files) {
+        elements.push({
+            data: {
+                id: file.id,
+                label: file.path.split('/').pop() ?? file.path,
+                path: file.path,
+                language: file.language,
+                color: LANGUAGE_COLORS[file.language] ?? '#94a3b8',
+                type: 'file',
+                size: file.sizeBytes,
+                scanStatus: file.scanStatus,
+            },
+            classes: `file ${file.language}`,
+        });
+    }
+    for (const note of cognitionNotes) {
+        const id = `cognition-${note.id}`;
+        elements.push({
+            data: {
+                id,
+                label: note.title,
+                color: STATUS_COLORS[note.referencesStatus] ?? STATUS_COLORS.unresolved,
+                type: 'cognition',
+                referencesStatus: note.referencesStatus,
+                domain: note.domain ?? '',
+                relatedFiles: note.relatedFiles,
+                relatedSymbols: note.relatedSymbols,
+            },
+            classes: `cognition ${note.referencesStatus}`,
+        });
+        for (const filePath of note.relatedFiles) {
+            const target = fileMap.files.find((f) => f.path === filePath);
+            if (target) {
+                const edgeId = `${id}-ref-${target.id}`;
+                if (!edgeIds.has(edgeId)) {
+                    edgeIds.add(edgeId);
+                    elements.push({
+                        data: {
+                            id: edgeId,
+                            source: id,
+                            target: target.id,
+                            type: 'cognition-ref',
+                            label: '',
+                        },
+                        classes: 'cognition-ref',
+                    });
+                }
+            }
+        }
+    }
+    for (const dep of dependencyMap.dependencies) {
+        if (dep.kind !== 'local' || !dep.resolvedFile)
+            continue;
+        const src = fileMap.files.find((f) => f.path === dep.fromFile);
+        const tgt = fileMap.files.find((f) => f.path === dep.resolvedFile);
+        if (src && tgt && src.id !== tgt.id) {
+            const edgeId = `import-${src.id}-${tgt.id}`;
+            if (!edgeIds.has(edgeId)) {
+                edgeIds.add(edgeId);
+                elements.push({
+                    data: {
+                        id: edgeId,
+                        source: src.id,
+                        target: tgt.id,
+                        type: 'import',
+                        label: '',
+                    },
+                    classes: 'import',
+                });
+            }
+        }
+    }
+    return {
+        elements,
+        meta: {
+            fileCount: fileMap.files.length,
+            symbolCount: symbolMap.symbols.length,
+            cognitionCount: cognitionNotes.length,
+            generatedAt: new Date().toISOString(),
+        },
+    };
+}

package/dist/visualization/html-template.d.ts

@@ -0,0 +1,2 @@
+import type { GraphData } from './graph-builder.js';
+export declare function renderHtml(graphData: GraphData, rootPath: string): string;