@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/knowledge/repo-map.js

@@ -0,0 +1,408 @@
+/**
+ * @file repo-map.ts
+ * Static layer of the KB system (Phase 1B).
+ *
+ * Uses the TypeScript Compiler API to extract symbols from the project's
+ * `src/` directory and produces a compact `RepoMap` JSON that downstream
+ * AI-compilation and query layers can consume.
+ *
+ * No AI calls are made here — this is a pure static-analysis pass.
+ */
+import * as ts from 'typescript';
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+// ─────────────────────────────────────────────────────────────────────────────
+// File discovery
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Recursively collect all `.ts` source files under `srcDir`,
+ * skipping `.test.ts`, `node_modules`, and hidden directories.
+ */
+function collectTsFiles(srcDir) {
+    const results = [];
+    function walk(dir) {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile() &&
+                entry.name.endsWith('.ts') &&
+                !entry.name.endsWith('.test.ts') &&
+                !entry.name.endsWith('.d.ts')) {
+                results.push(full);
+            }
+        }
+    }
+    walk(srcDir);
+    return results;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Git helper
+// ─────────────────────────────────────────────────────────────────────────────
+function getGitShortHash() {
+    try {
+        return execSync('git rev-parse --short HEAD', {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return 'no-git';
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// AST helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function hasExportModifier(node) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const mods = ts.getModifiers(node);
+    if (!mods)
+        return false;
+    return mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+}
+function getJsDocText(node, sourceFile) {
+    const full = node.getFullText(sourceFile);
+    // Look for /** ... */ block that precedes the node's own text
+    const own = node.getText(sourceFile);
+    const leading = full.slice(0, full.length - own.length);
+    const match = leading.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
+    if (!match)
+        return undefined;
+    const text = match[1]
+        .split('\n')
+        .map((l) => l.replace(/^\s*\*\s?/, ''))
+        .join(' ')
+        .trim();
+    return text.length > 200 ? text.slice(0, 197) + '...' : text || undefined;
+}
+/**
+ * Extract a single-line signature from a node (body stripped, max 200 chars).
+ *
+ * Strategy: grab the source text up to (but not including) the opening brace
+ * of the body, then collapse whitespace.
+ */
+function extractSignature(node, sourceFile) {
+    const src = sourceFile.text;
+    let endPos;
+    if (ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isArrowFunction(node)) {
+        // End just before the body block
+        endPos = node.body?.getStart(sourceFile) ?? node.getEnd();
+    }
+    else if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+        endPos = node.members.pos; // '{' is right at members.pos - 1
+    }
+    else if (ts.isInterfaceDeclaration(node)) {
+        endPos = node.members.pos;
+    }
+    else {
+        endPos = node.getEnd();
+    }
+    let raw = src.substring(node.getStart(sourceFile), endPos);
+    // Collapse whitespace and newlines to single spaces
+    raw = raw.replace(/\s+/g, ' ').trim();
+    // Remove trailing '{' that may have leaked
+    raw = raw.replace(/\s*\{?\s*$/, '').trim();
+    return raw.length > 200 ? raw.slice(0, 197) + '...' : raw;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Visitor
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Depth-first AST visit.
+ *
+ * Only top-level declarations and class members are captured.
+ * Nested functions (e.g. a function inside another function body) are skipped
+ * unless `depth === 0` or the parent is a ClassDeclaration.
+ */
+function visit(node, sourceFile, srcDir, symbols, depth, parentClassName) {
+    const relFile = relative(srcDir, sourceFile.fileName);
+    function lineOf(n) {
+        return ts.getLineAndCharacterOfPosition(sourceFile, n.getStart(sourceFile)).line + 1;
+    }
+    // ── Class declaration ──────────────────────────────────────────────────────
+    if (ts.isClassDeclaration(node) && depth === 0) {
+        const name = node.name?.text;
+        if (name) {
+            symbols.push({
+                file: relFile,
+                line: lineOf(node),
+                kind: 'class',
+                name,
+                signature: extractSignature(node, sourceFile),
+                exports: hasExportModifier(node),
+                docComment: getJsDocText(node, sourceFile),
+            });
+            // Visit class members at depth 1 (class body)
+            for (const member of node.members) {
+                visit(member, sourceFile, srcDir, symbols, 1, name);
+            }
+        }
+        return; // Don't recurse further — we handle members above
+    }
+    // ── Method / constructor / accessor (inside class) ─────────────────────────
+    if (depth === 1 && parentClassName) {
+        if (ts.isMethodDeclaration(node) ||
+            ts.isConstructorDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node)) {
+            let memberName;
+            if (ts.isConstructorDeclaration(node)) {
+                memberName = 'constructor';
+            }
+            else {
+                const key = node.name;
+                memberName =
+                    ts.isIdentifier(key) || ts.isStringLiteral(key) ? key.text : key.getText(sourceFile);
+            }
+            const qualName = `${parentClassName}.${memberName}`;
+            const isPrivate = (() => {
+                if (!ts.canHaveModifiers(node))
+                    return false;
+                const mods = ts.getModifiers(node);
+                return mods
+                    ? mods.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword)
+                    : false;
+            })();
+            symbols.push({
+                file: relFile,
+                line: lineOf(node),
+                kind: 'method',
+                name: qualName,
+                signature: extractSignature(node, sourceFile),
+                exports: !isPrivate,
+                docComment: getJsDocText(node, sourceFile),
+            });
+            return; // Don't recurse into method bodies
+        }
+        // Other class members (properties, etc.) — skip
+        return;
+    }
+    // ── Function declaration (top-level only) ─────────────────────────────────
+    if (ts.isFunctionDeclaration(node) && depth === 0) {
+        const name = node.name?.text;
+        if (name) {
+            symbols.push({
+                file: relFile,
+                line: lineOf(node),
+                kind: 'function',
+                name,
+                signature: extractSignature(node, sourceFile),
+                exports: hasExportModifier(node),
+                docComment: getJsDocText(node, sourceFile),
+            });
+        }
+        return; // Skip inner functions
+    }
+    // ── Interface declaration ──────────────────────────────────────────────────
+    if (ts.isInterfaceDeclaration(node) && depth === 0) {
+        const name = node.name.text;
+        symbols.push({
+            file: relFile,
+            line: lineOf(node),
+            kind: 'interface',
+            name,
+            signature: extractSignature(node, sourceFile),
+            exports: hasExportModifier(node),
+            docComment: getJsDocText(node, sourceFile),
+        });
+        return;
+    }
+    // ── Type alias ─────────────────────────────────────────────────────────────
+    if (ts.isTypeAliasDeclaration(node) && depth === 0) {
+        const name = node.name.text;
+        symbols.push({
+            file: relFile,
+            line: lineOf(node),
+            kind: 'type',
+            name,
+            signature: extractSignature(node, sourceFile),
+            exports: hasExportModifier(node),
+            docComment: getJsDocText(node, sourceFile),
+        });
+        return;
+    }
+    // ── Enum declaration ───────────────────────────────────────────────────────
+    if (ts.isEnumDeclaration(node) && depth === 0) {
+        const name = node.name.text;
+        symbols.push({
+            file: relFile,
+            line: lineOf(node),
+            kind: 'enum',
+            name,
+            signature: `enum ${name}`,
+            exports: hasExportModifier(node),
+            docComment: getJsDocText(node, sourceFile),
+        });
+        return;
+    }
+    // ── Variable statement (export const / const with arrow fn) ───────────────
+    if (ts.isVariableStatement(node) && depth === 0) {
+        const isExported = hasExportModifier(node);
+        for (const decl of node.declarationList.declarations) {
+            if (!ts.isIdentifier(decl.name))
+                continue;
+            const name = decl.name.text;
+            // Build signature: `const name: Type` or `const name = <arrow>`
+            let sig;
+            if (decl.type) {
+                sig = `const ${name}: ${decl.type.getText(sourceFile)}`;
+            }
+            else if (decl.initializer && ts.isArrowFunction(decl.initializer)) {
+                // Arrow function — include param list and return type
+                const arrowSig = extractSignature(decl.initializer, sourceFile);
+                sig = `const ${name} = ${arrowSig}`;
+            }
+            else {
+                // Short initializer
+                const init = decl.initializer?.getText(sourceFile) ?? '';
+                const short = init.length > 60 ? init.slice(0, 57) + '...' : init;
+                sig = short ? `const ${name} = ${short}` : `const ${name}`;
+            }
+            if (sig.length > 200)
+                sig = sig.slice(0, 197) + '...';
+            symbols.push({
+                file: relFile,
+                line: lineOf(decl),
+                kind: 'const',
+                name,
+                signature: sig,
+                exports: isExported,
+                docComment: getJsDocText(node, sourceFile),
+            });
+        }
+        return;
+    }
+    // ── Recurse into top-level containers (modules, namespaces, etc.) ──────────
+    if (depth === 0) {
+        ts.forEachChild(node, (child) => visit(child, sourceFile, srcDir, symbols, 0));
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Scan the `srcDir` directory and extract all symbols using the TypeScript
+ * Compiler API.
+ *
+ * @param srcDir Absolute path to `src/` (e.g. `path.join(cwd, 'src')`).
+ * @returns A fully-populated `RepoMap`.
+ */
+export function buildRepoMap(srcDir) {
+    const tsFiles = collectTsFiles(srcDir);
+    const program = ts.createProgram(tsFiles, {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        allowJs: false,
+        skipLibCheck: true,
+        noEmit: true,
+    });
+    const symbols = [];
+    for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile)
+            continue;
+        // Only process files that live under srcDir
+        if (!sourceFile.fileName.startsWith(srcDir))
+            continue;
+        ts.forEachChild(sourceFile, (child) => visit(child, sourceFile, srcDir, symbols, 0));
+    }
+    const scannedFiles = program
+        .getSourceFiles()
+        .filter((sf) => !sf.isDeclarationFile && sf.fileName.startsWith(srcDir));
+    return {
+        version: '1.0',
+        generated_at: new Date().toISOString(),
+        source_hash: getGitShortHash(),
+        symbols,
+        file_count: scannedFiles.length,
+        symbol_count: symbols.length,
+    };
+}
+/**
+ * v10.0 — Single-file symbol extraction.
+ *
+ * Adapter-friendly variant of {@link buildRepoMap}: parses one file's content
+ * via the TypeScript Compiler API and returns its symbols.  Used by
+ * `TypeScriptAdapter.parseSymbols` so adapters can drive the static layer one
+ * file at a time without re-running `ts.createProgram` for the whole repo.
+ *
+ * The existing batch path (`buildRepoMap`) is preserved verbatim so v9.5.x
+ * behavior is unchanged in v10.0.
+ *
+ * @param fileName     Absolute path of the file (used for diagnostics + line info).
+ * @param sourceText   File contents.
+ * @param projectRelPath Path written into `RepoMapSymbol.file` (relative to the
+ *                       project root, e.g. `src/daemon/server.ts`). The legacy
+ *                       batch path stores paths relative to `src/`; adapters
+ *                       are responsible for passing a value compatible with
+ *                       their KB layout.
+ * @returns extracted symbols (possibly empty).
+ */
+export function parseFileSymbols(fileName, sourceText, projectRelPath) {
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.ES2022, 
+    /* setParentNodes */ true, ts.ScriptKind.TS);
+    const symbols = [];
+    // visit() expects a `srcDir` so that `relative(srcDir, sourceFile.fileName)`
+    // produces the desired `RepoMapSymbol.file`.  We synthesize one such that the
+    // computed relative path equals `projectRelPath`.
+    const syntheticSrcDir = fileName.endsWith(projectRelPath)
+        ? fileName.slice(0, fileName.length - projectRelPath.length).replace(/[/\\]$/, '')
+        : '';
+    ts.forEachChild(sourceFile, (child) => visit(child, sourceFile, syntheticSrcDir, symbols, 0));
+    return symbols;
+}
+/**
+ * Persist a `RepoMap` to `<outDir>/repo-map.json`.
+ */
+export function writeRepoMap(outDir, repoMap) {
+    const dest = join(outDir, 'repo-map.json');
+    writeFileSync(dest, JSON.stringify(repoMap, null, 2), 'utf8');
+}
+/**
+ * Load an existing `RepoMap` from `<outDir>/repo-map.json`.
+ * Returns `null` if the file does not exist or cannot be parsed.
+ */
+export function loadRepoMap(outDir) {
+    const src = join(outDir, 'repo-map.json');
+    if (!existsSync(src))
+        return null;
+    try {
+        const raw = readFileSync(src, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return all symbols whose `file` path starts with `src/<moduleName>/`.
+ *
+ * @param repoMap  The repo-map to filter.
+ * @param moduleName  Module directory name (e.g. `'daemon'`).
+ */
+export function filterByModule(repoMap, moduleName) {
+    const prefix = `${moduleName}/`;
+    return repoMap.symbols.filter((s) => s.file.startsWith(prefix));
+}
+/**
+ * Look up a single symbol by its fully-qualified name (exact match).
+ *
+ * @param repoMap  The repo-map to search.
+ * @param name  Symbol name (e.g. `'SocketServer'` or `'SocketServer.start'`).
+ */
+export function lookupSymbol(repoMap, name) {
+    return repoMap.symbols.find((s) => s.name === name) ?? null;
+}
+//# sourceMappingURL=repo-map.js.map

package/dist/knowledge/repo-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-map.js","sourceRoot":"","sources":["../../src/knowledge/repo-map.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/tools/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file index.ts
+ * Barrel re-export for the v9.1 Knowledge Base MCP tool helpers.
+ *
+ * These functions are consumed by the MCP server layer (`src/mcp/server.ts`)
+ * but can also be imported directly by tests or future CLI shims.
+ */
+export { knowledgeQuery, } from './knowledge-query.js';
+export type { KnowledgeQueryParams, KnowledgeQueryResult, KnowledgeQueryPageHit, KnowledgeQueryContext, } from './knowledge-query.js';
+export { knowledgeGetPage, } from './knowledge-get-page.js';
+export type { KnowledgeGetPageParams, KnowledgeGetPageResult, KnowledgeGetPagePayload, KnowledgeGetPageContext, } from './knowledge-get-page.js';
+export { repoMapLookup, } from './repo-map-lookup.js';
+export type { RepoMapLookupParams, RepoMapLookupResult, RepoMapLookupMode, RepoMapLookupContext, } from './repo-map-lookup.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knowledge/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC"}

package/dist/knowledge/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * @file index.ts
+ * Barrel re-export for the v9.1 Knowledge Base MCP tool helpers.
+ *
+ * These functions are consumed by the MCP server layer (`src/mcp/server.ts`)
+ * but can also be imported directly by tests or future CLI shims.
+ */
+export { knowledgeQuery, } from './knowledge-query.js';
+export { knowledgeGetPage, } from './knowledge-get-page.js';
+export { repoMapLookup, } from './repo-map-lookup.js';
+//# sourceMappingURL=index.js.map

package/dist/knowledge/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/knowledge/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,GACf,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EACL,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EACL,aAAa,GACd,MAAM,sBAAsB,CAAC"}

package/dist/knowledge/tools/knowledge-get-page.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file knowledge-get-page.ts
+ * MCP tool: `knowledge_get_page`
+ *
+ * Wrap `getPage` from `../query.ts` with:
+ *   - Path-traversal guards (reject `..`, absolute paths, escape attempts)
+ *   - Byte-level truncation with `truncated: true` + `original_bytes`
+ *   - `{ ok: false, error }` business errors instead of throws
+ *
+ * See spec §2.2 and §4.7.
+ */
+import type { KBRef } from '../types.js';
+export interface KnowledgeGetPageParams {
+    /** Page name, relative to `.forge-knowledge/`, e.g. `"modules/daemon.md"`. */
+    name: string;
+    /** Max bytes of `content` returned; default 50000, max 200000. */
+    max_bytes?: number;
+}
+export interface KnowledgeGetPagePayload {
+    name: string;
+    title: string;
+    content: string;
+    refs: KBRef[];
+    generated_at: string;
+    source_hash: string;
+    /** Byte length of the returned `content` (after truncation, if any). */
+    bytes: number;
+}
+export type KnowledgeGetPageResult = {
+    ok: true;
+    page: KnowledgeGetPagePayload;
+    truncated: boolean;
+    /** Present only when `truncated=true`. */
+    original_bytes?: number;
+} | {
+    ok: false;
+    error: 'page_not_found' | 'kb_not_built' | 'invalid_name';
+    name?: string;
+    hint?: string;
+};
+export interface KnowledgeGetPageContext {
+    projectRoot?: string;
+    sessionId?: string;
+}
+export declare function knowledgeGetPage(params: KnowledgeGetPageParams, context?: KnowledgeGetPageContext): Promise<KnowledgeGetPageResult>;
+//# sourceMappingURL=knowledge-get-page.d.ts.map

package/dist/knowledge/tools/knowledge-get-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-get-page.d.ts","sourceRoot":"","sources":["../../../src/knowledge/tools/knowledge-get-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAQzC,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,KAAK,EAAE,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAC9B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,uBAAuB,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAqCD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CA2DjC"}

package/dist/knowledge/tools/knowledge-get-page.js

@@ -0,0 +1,101 @@
+/**
+ * @file knowledge-get-page.ts
+ * MCP tool: `knowledge_get_page`
+ *
+ * Wrap `getPage` from `../query.ts` with:
+ *   - Path-traversal guards (reject `..`, absolute paths, escape attempts)
+ *   - Byte-level truncation with `truncated: true` + `original_bytes`
+ *   - `{ ok: false, error }` business errors instead of throws
+ *
+ * See spec §2.2 and §4.7.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { getPage } from '../query.js';
+import * as K from '../constants.js';
+import { logger } from '../../core/utils/logger.js';
+const DEFAULT_MAX_BYTES = 50_000; // 50 KB
+// ─────────────────────────────────────────────────────────────────────────────
+// Path-traversal guard
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Reject any `name` that:
+ *   - contains `..` segments
+ *   - is an absolute path (`/foo` or `C:\foo`)
+ *   - resolves outside the KB directory
+ *
+ * Throws `Error('invalid_name: <reason>')` on any violation.
+ */
+function validatePageName(name, kbDir) {
+    if (name.includes('..')) {
+        throw new Error('invalid_name: contains ".."');
+    }
+    if (path.isAbsolute(name)) {
+        throw new Error('invalid_name: must be relative');
+    }
+    // Windows drive letter (e.g. "C:foo")
+    if (/^[a-zA-Z]:/.test(name)) {
+        throw new Error('invalid_name: drive-letter prefix not allowed');
+    }
+    // Defence-in-depth: resolved path must stay inside kbDir
+    const resolved = path.resolve(kbDir, name);
+    const resolvedKb = path.resolve(kbDir);
+    if (!resolved.startsWith(resolvedKb + path.sep) && resolved !== resolvedKb) {
+        throw new Error('invalid_name: escapes knowledge directory');
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+export async function knowledgeGetPage(params, context = {}) {
+    const projectRoot = context.projectRoot ?? process.cwd();
+    const kbDir = path.join(projectRoot, K.KB_DIRNAME);
+    const maxBytes = params.max_bytes ?? DEFAULT_MAX_BYTES;
+    logger.info(`[knowledge_get_page] name="${params.name}" max_bytes=${maxBytes}` +
+        (context.sessionId ? ` session=${context.sessionId}` : ''));
+    // ── Path-traversal guard (throws on violation) ────────────────────────────
+    validatePageName(params.name, kbDir);
+    // ── KB existence check ────────────────────────────────────────────────────
+    if (!fs.existsSync(kbDir)) {
+        return {
+            ok: false,
+            error: 'kb_not_built',
+            name: params.name,
+            hint: 'Knowledge base not built. Run: cf knowledge build --apply',
+        };
+    }
+    const page = await getPage(params.name, projectRoot);
+    if (!page) {
+        return {
+            ok: false,
+            error: 'page_not_found',
+            name: params.name,
+            hint: 'Use knowledge_query or list pages via `cf knowledge list`',
+        };
+    }
+    // ── Byte-level truncation ─────────────────────────────────────────────────
+    const originalLength = page.content.length;
+    let content = page.content;
+    let truncated = false;
+    let originalBytes;
+    if (originalLength > maxBytes) {
+        content = page.content.slice(0, maxBytes);
+        truncated = true;
+        originalBytes = originalLength;
+    }
+    return {
+        ok: true,
+        page: {
+            name: page.name,
+            title: page.title,
+            content,
+            refs: page.refs,
+            generated_at: page.generated_at,
+            source_hash: page.source_hash,
+            bytes: content.length,
+        },
+        truncated,
+        ...(truncated ? { original_bytes: originalBytes } : {}),
+    };
+}
+//# sourceMappingURL=knowledge-get-page.js.map

package/dist/knowledge/tools/knowledge-get-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-get-page.js","sourceRoot":"","sources":["../../../src/knowledge/tools/knowledge-get-page.ts"],"names":[],"mappings":"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"}