@kentwynn/kgraph 0.1.6 → 0.1.8

package/README.md

@@ -1,148 +1,220 @@
 # KGraph
 
-Persistent repository intelligence for AI coding tools.
+> **Persistent repository intelligence for AI coding tools.**
+> Stop paying the context tax on every session. KGraph gives your AI assistant a memory.
 
-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 It Matters
+## The Problem
 
-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.
+Every AI coding session starts with the same expensive ritual:
 
-KGraph turns that repeated exploration into durable repository intelligence:
-
-```text
-AI chat or developer note
--> KGraph cognition inbox
--> structured repo knowledge
--> compact context for future AI sessions
+```
+"Let me read your package.json..."
+"Let me trace the imports in auth.ts..."
+"Let me find where sessions are created..."
+"Let me understand the database layer..."
 ```
 
-The result is faster navigation, lower token waste, and more consistent understanding across coding sessions.
+On a medium-sized codebase, this exploration burns **3,000–8,000 tokens** before the AI writes a single line of code. Multiply that across 10 sessions per day and you're spending the majority of your context budget re-learning things you already know.
 
-## Install
+Worse: AI tools forget. The debugging insight from Tuesday, the architecture decision from last sprint, the "don't touch this or it breaks payments" gotcha — gone after every session.
 
-Run the latest published package:
+---
+
+## The Solution
+
+KGraph builds a local knowledge layer that grows with your project. It maps your codebase once, captures reasoning from your AI sessions, and serves compact, targeted context on demand.
 
-```bash
-npx @kentwynn/kgraph@latest init
 ```
+Without KGraph                     With KGraph
+─────────────────────────────────  ──────────────────────────────────
+Session start: ~5,000 tokens       Session start: ~300 tokens
+exploring files and structure      kgraph context "auth token refresh"
 
-Run a specific stable version:
+Re-learns same architecture        Recalls prior decisions instantly
+every single session               from cognition store
 
-```bash
-npx @kentwynn/kgraph@0.1.0 init
+Context limit hit mid-task         Full context budget for actual work
+
+Debugging insight lost forever     Captured in .kgraph/inbox/
+                                   available in every future session
 ```
 
-Install globally if you use KGraph often:
+---
+
+## Token Savings — What This Looks Like in Practice
+
+A typical `kgraph context` response for a focused topic:
 
-```bash
-npm install -g @kentwynn/kgraph@latest
-kgraph --version
 ```
+topic: auth token refresh
 
-## Quick Start
+files:
+  src/lib/auth.ts           (createSession, validateToken, refreshToken)
+  app/api/auth/route.ts     (POST handler → createSession)
+  middleware.ts             (reads session cookie, calls validateToken)
 
-Initialize KGraph in a repository and connect your AI tools:
+key relationships:
+  POST /api/auth → createSession → writes JWT to cookie
+  middleware → validateToken → redirects on expiry
 
-```bash
-kgraph init --integrations codex,copilot,cursor
+cognition:
+  refreshToken has a race condition under concurrent requests — see issue #47
+  JWT secret must come from env, never hardcoded — broke staging in March
+  token TTL is 15 min by design, not a bug
 ```
 
-Scan the codebase:
+**~280 tokens.** The equivalent file-by-file exploration: **4,200+ tokens.**  
+That's a **15x reduction** in context cost for navigation alone.
+
+The gap widens every week as cognition accumulates — past decisions, debugging discoveries, and architectural gotchas that would otherwise cost the AI thousands of tokens to re-derive.
+
+---
+
+## How It Works
 
-```bash
-kgraph scan
 ```
+┌─────────────────────────────────────────────────────────────┐
+│                        Your Codebase                        │
+└──────────────────────────────┬──────────────────────────────┘
+                               │  kgraph scan
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  .kgraph/                                                   │
+│  ├── maps/          file graph, symbol index, imports       │
+│  ├── cognition.md   decisions, gotchas, debugging history   │
+│  └── config.yaml    include/exclude rules                   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │  kgraph context "topic"
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  AI Tool  (Copilot / Codex / Cursor / Claude Code)          │
+│  Reads compact context → navigates directly → works faster  │
+└─────────────────────────────────────────────────────────────┘
+                               │  session ends
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│  .kgraph/inbox/     AI drops a note: what it learned        │
+│                     kgraph update → distilled into          │
+│                     cognition.md for the next session       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+This creates a **compounding feedback loop**: the more you use KGraph, the richer the cognition store, the less exploration the AI needs to do.
 
-Ask for compact context before working on an area:
+---
+
+## Install
 
 ```bash
-kgraph context "auth token refresh"
+npm install -g @kentwynn/kgraph@latest
+kgraph --version
 ```
 
-Process saved chat notes and debugging conclusions:
+Or run without installing:
 
 ```bash
-kgraph update
+npx @kentwynn/kgraph@latest init
 ```
 
-## CLI
+---
+
+## Quick Start
 
 ```bash
-kgraph init
-kgraph init --integrations codex,cursor
-kgraph integrate list
-kgraph integrate add codex copilot cursor claude-code
-kgraph integrate remove cursor
+# 1. Initialize and connect your AI tools
+kgraph init --integrations codex,copilot,cursor,claude-code
+
+# 2. Scan the codebase
 kgraph scan
-kgraph update
+
+# 3. Ask for context before exploring (your AI does this automatically)
 kgraph context "auth token refresh"
-kgraph context "auth token refresh" --json
+
+# 4. After an AI session, save what was learned
+kgraph update
 ```
 
-## AI Tool Integrations
+That's the entire loop. From session 2 onward, your AI tool loads existing intelligence before touching a single file.
 
-KGraph writes local instruction files and command/prompt packs so AI tools can use the repository knowledge layer during normal coding chats.
+---
 
-| 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` | Built into the KGraph Cursor rule |
-| Claude Code | `CLAUDE.md` | `.claude/commands/kgraph.md` |
+## AI Tool Integrations
 
-Example:
+`kgraph integrate` writes instruction files and command/skill packs directly into your repo so each tool knows how to use the knowledge layer — no manual setup.
 
 ```bash
 kgraph integrate add codex copilot cursor claude-code
 kgraph integrate list
 ```
 
-This gives each supported tool one reusable KGraph entry point similar to a Spec Kit-style command:
+| Tool           | Always-on instruction             | Skills / commands                                                   |
+| -------------- | --------------------------------- | ------------------------------------------------------------------- |
+| GitHub Copilot | `.github/copilot-instructions.md` | `/kgraph-scan` · `/kgraph-update` · `/kgraph-visualize`             |
+| Codex          | `AGENTS.md`                       | `.agents/skills/kgraph/SKILL.md` (VS Code Agent Skills standard)    |
+| Cursor         | `.cursor/rules/kgraph.mdc`        | Built into the rule                                                 |
+| Claude Code    | `CLAUDE.md`                       | `/kgraph` · `/kgraph-scan` · `/kgraph-update` · `/kgraph-visualize` |
 
-- 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
+Each integration installs a `/kgraph` skill or command that handles the full workflow automatically: load context → work → capture findings → update cognition. `/kgraph-scan`, `/kgraph-update`, and `/kgraph-visualize` are available for manual maintenance.
 
-The exact invocation depends on the host tool. Copilot uses one prompt file, Codex uses one skill, Cursor uses one rule, and Claude Code uses one command file. Scan and update are workflows inside that single KGraph entry point, not separate duplicated commands.
+Existing user content in `AGENTS.md`, `CLAUDE.md`, etc. is preserved — KGraph manages only its own clearly-marked blocks.
 
-KGraph-managed instruction blocks preserve existing user-authored content.
+---
 
-## Features
+## CLI Reference
 
-- 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 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
+```bash
+kgraph init                                     # initialize .kgraph/ workspace
+kgraph init --integrations codex,copilot        # init + configure integrations
 
-## How KGraph Grows
+kgraph scan                                     # scan codebase, update maps
+kgraph context "auth token refresh"             # get compact context for a topic
+kgraph context "auth token refresh" --json      # machine-readable output
+kgraph update                                   # process inbox notes into cognition
 
-KGraph is designed to improve as the project changes:
+kgraph integrate list                           # show integration status
+kgraph integrate add codex copilot cursor       # add integrations
+kgraph integrate remove cursor                  # remove an integration
 
-```text
-kgraph scan
-  refreshes current structure
+kgraph visualize                                # interactive graph at http://localhost:4242
+kgraph visualize --port 3000                    # custom port
+kgraph visualize --no-open                      # print URL, don't open browser
 
-AI chat or developer note
-  captures useful reasoning in .kgraph/inbox/
+kgraph history                                  # timeline of processed cognition sessions
+kgraph history --last 10                        # show last 10 entries
+kgraph history --json                           # machine-readable output
+```
 
-kgraph update
-  converts notes into durable cognition
+---
 
-kgraph context "<topic>"
-  returns focused repository context for future work
-```
+## What KGraph Tracks
+
+| Category          | Examples                                                               |
+| ----------------- | ---------------------------------------------------------------------- |
+| **File map**      | every source file, language, size                                      |
+| **Symbol index**  | functions, classes, methods, exports per file                          |
+| **Import graph**  | which files import which, dependency chains                            |
+| **Relationships** | call sites, re-exports, shared types                                   |
+| **Cognition**     | past decisions, architectural constraints, debugging insights, gotchas |
+
+Supported languages: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, PHP, Swift, and 30+ more — detected by file extension, no configuration needed.
+
+---
+
+## Local-First, Zero Dependencies
 
-This creates a feedback loop where normal development and AI-assisted debugging gradually improve the repository knowledge map.
+KGraph requires nothing beyond Node.js ≥ 20:
 
-## Local-First
+- No accounts or API keys
+- No embeddings or vector databases
+- No cloud services or telemetry
+- No background daemons
+- No model provider
 
-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.
+All data lives in `.kgraph/` as human-readable JSON, YAML, and Markdown. Commit it, diff it, inspect it anytime.
+
+---
 
 ## Development
 
@@ -150,26 +222,62 @@ KGraph stores project intelligence in local files inside `.kgraph/`. The MVP doe
 npm install
 npm run build
 npm test
+```
+
+Test a command without installing:
+
+```bash
 npm run kgraph -- init --integrations codex,cursor
+npm run kgraph -- context "auth token refresh"
 ```
 
-## Release
+Install the local build globally to test the `kgraph` binary end-to-end:
 
-CI runs build, tests, package checks, and generated-artifact hygiene on pushes and pull requests.
+```bash
+npm install -g .
+kgraph --version
+kgraph init --integrations codex,copilot
+```
 
-Releases are tag-driven. Bump the package version, push the commit, then push the matching tag:
+---
+
+## Release
+
+Releases are tag-driven. Bump the version, push the commit and tag:
 
 ```bash
 npm version patch
 git push origin main --follow-tags
 ```
 
-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.
+CI verifies the tag matches `package.json`, checks the version is unpublished, publishes to npm, creates a GitHub Release, and attaches the tarball.
+
+---
+
+## Visualization
+
+```bash
+kgraph visualize
+```
+
+Starts a local server at `http://localhost:4242` and opens an interactive dependency graph in your browser. No install required — two CDN scripts (Cytoscape.js + dagre layout) are loaded at view time.
+
+**What you see:**
+
+- File nodes colored by language (TypeScript, JavaScript, Markdown, YAML, …)
+- Cognition notes as diamonds, colored by health (green = current, amber = mixed, red = stale)
+- Import edges showing real dependency flow
+- Dashed blue edges linking cognition notes to the files they describe
+- Click any node for a metadata panel (path, size, domain, related symbols)
+- Toggle cognition overlay on/off
+- Switch layout: Hierarchical (default), Force-directed, Grid, Concentric
+- **Export PNG** — 2× resolution, dark background, ready for reports or slides
+
+---
 
 ## Roadmap
 
-- richer language scanners
-- better cognition extraction
-- graph visualization
-- Git-aware history and rename detection
-- optional editor and MCP integrations
+- Git-aware history and rename tracking
+- richer language scanners (deeper AST, cross-file type resolution)
+- MCP server for editor tool-call access
+- team-shared cognition via committed `.kgraph/`

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

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+export interface HistoryEntry {
+    timestamp: Date;
+    filename: string;
+    title: string;
+    author?: string;
+}
+export declare function registerHistoryCommand(program: Command): void;
+export declare function readHistoryEntries(processedPath: string, rootPath: string): Promise<HistoryEntry[]>;
+/**
+ * Parses the UTC timestamp embedded in a processed interaction filename.
+ * Filename format: 2026-05-09T09-36-06-247Z-slug.md
+ * (colons and dot replaced by dashes when written to disk)
+ */
+export declare function parseTimestampFromFilename(filename: string): Date | undefined;
+export declare function renderHistory(entries: HistoryEntry[], useColor?: boolean): string;

package/dist/cli/commands/history.js

@@ -0,0 +1,124 @@
+import { Chalk } from 'chalk';
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { assertWorkspace, pathExists } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+const execFileAsync = promisify(execFile);
+export function registerHistoryCommand(program) {
+    program
+        .command('history')
+        .description('Show a timeline of processed cognition sessions')
+        .option('--last <n>', 'Show only the last N entries')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const entries = await readHistoryEntries(workspace.processedInteractionsPath, workspace.rootPath);
+        const limit = options.last !== undefined ? parseInt(options.last, 10) : 0;
+        if (options.last !== undefined && (isNaN(limit) || limit < 1)) {
+            throw new KGraphError('--last must be a positive integer.');
+        }
+        const shown = limit > 0 ? entries.slice(-limit) : entries;
+        if (options.json) {
+            console.log(JSON.stringify(shown.map((e) => ({
+                timestamp: e.timestamp.toISOString(),
+                filename: e.filename,
+                title: e.title,
+                ...(e.author !== undefined ? { author: e.author } : {}),
+            })), null, 2));
+        }
+        else {
+            console.log(renderHistory(shown));
+        }
+    }));
+}
+export async function readHistoryEntries(processedPath, rootPath) {
+    if (!(await pathExists(processedPath))) {
+        return [];
+    }
+    const dirents = await readdir(processedPath, { withFileTypes: true });
+    const filenames = dirents
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => e.name)
+        .sort(); // ISO-prefixed filenames sort chronologically
+    const entries = [];
+    for (const filename of filenames) {
+        const timestamp = parseTimestampFromFilename(filename);
+        if (!timestamp)
+            continue;
+        const filePath = path.join(processedPath, filename);
+        const content = await readFile(filePath, 'utf8');
+        const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? filename;
+        const relPath = path.relative(rootPath, filePath);
+        const author = await getGitAuthor(rootPath, relPath);
+        entries.push({ timestamp, filename, title, author });
+    }
+    return entries;
+}
+/**
+ * Parses the UTC timestamp embedded in a processed interaction filename.
+ * Filename format: 2026-05-09T09-36-06-247Z-slug.md
+ * (colons and dot replaced by dashes when written to disk)
+ */
+export function parseTimestampFromFilename(filename) {
+    const match = filename.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z-/);
+    if (!match)
+        return undefined;
+    const iso = `${match[1]}T${match[2]}:${match[3]}:${match[4]}.${match[5]}Z`;
+    const d = new Date(iso);
+    return isNaN(d.getTime()) ? undefined : d;
+}
+export function renderHistory(entries, useColor = supportsColor()) {
+    const chalk = new Chalk({ level: useColor ? 3 : 0 });
+    if (entries.length === 0) {
+        return ('\n' +
+            chalk.dim('  No processed cognition notes found. Write Markdown notes to .kgraph/inbox/ and run `kgraph update`.') +
+            '\n');
+    }
+    const header = `  ${chalk.bold('KGraph History')}  ${chalk.dim(`· ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`)}`;
+    const lines = ['', header, ''];
+    const titleWidth = Math.max(...entries.map((e) => e.title.length));
+    for (const entry of entries) {
+        const when = chalk.dim(`${formatDate(entry.timestamp)}  ${formatTime(entry.timestamp)}`);
+        const title = chalk.bold(entry.title.padEnd(titleWidth));
+        const who = entry.author !== undefined
+            ? chalk.cyan(`by ${entry.author}`)
+            : chalk.dim('(uncommitted)');
+        lines.push(`  ${when}   ${title}  ${who}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+async function getGitAuthor(rootPath, relFilePath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '--format=%an', '-1', '--', relFilePath], { cwd: rootPath, timeout: 3000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatDate(d) {
+    const months = [
+        'Jan',
+        'Feb',
+        'Mar',
+        'Apr',
+        'May',
+        'Jun',
+        'Jul',
+        'Aug',
+        'Sep',
+        'Oct',
+        'Nov',
+        'Dec',
+    ];
+    return `${months[d.getUTCMonth()]} ${String(d.getUTCDate()).padStart(2, ' ')}, ${d.getUTCFullYear()}`;
+}
+function formatTime(d) {
+    return `${String(d.getUTCHours()).padStart(2, '0')}:${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+function supportsColor() {
+    return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+}

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

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

package/dist/cli/commands/visualize.js

@@ -0,0 +1,73 @@
+import { exec } from 'node:child_process';
+import { createServer } from 'node:http';
+import { loadConfig } from '../../config/config.js';
+import { readCognitionNotes } from '../../storage/cognition-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { buildGraph } from '../../visualization/graph-builder.js';
+import { renderHtml } from '../../visualization/html-template.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerVisualizeCommand(program) {
+    program
+        .command('visualize')
+        .description('Start a local server and open the interactive dependency graph in browser')
+        .option('--port <port>', 'Port to listen on', '4242')
+        .option('--no-open', 'Print URL without opening browser')
+        .action((options) => runCommand(async () => {
+        const port = parseInt(options.port, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            throw new KGraphError('Invalid port. Use a value between 1 and 65535.');
+        }
+        const workspace = await assertWorkspace(process.cwd());
+        if (!(await mapsExist(workspace))) {
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+        }
+        const [maps, cognition] = await Promise.all([
+            readMaps(workspace),
+            readCognitionNotes(workspace),
+        ]);
+        await loadConfig(workspace); // ensure workspace is valid
+        const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, cognition);
+        const html = renderHtml(graphData, workspace.rootPath);
+        await serveGraph(html, port, options.open);
+    }));
+}
+async function serveGraph(html, port, autoOpen) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((_req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                reject(new KGraphError(`Port ${port} is already in use. Try --port <number>.`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            const url = `http://localhost:${port}`;
+            console.log(`\nKGraph visualization at ${url}\n`);
+            console.log('Press Ctrl+C to stop.');
+            if (autoOpen) {
+                openBrowser(url);
+            }
+        });
+        process.on('SIGINT', () => {
+            server.close(() => {
+                console.log('\nVisualization server stopped.');
+                resolve();
+                process.exit(0);
+            });
+        });
+    });
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin'
+        ? `open "${url}"`
+        : process.platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    exec(cmd);
+}