@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/knowledge/project-detector.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @file project-detector.ts
+ * v10.0 — Project-kind detection for the KB CLI.
+ *
+ * Scans the project root for well-known manifest files in a fixed priority
+ * order and returns a {@link ProjectInfo} describing what kind of project we
+ * are looking at.  Detection is purely filesystem-based (no parsing) so it is
+ * safe to call before any adapter / AI logic.
+ *
+ * Used by:
+ *   - `cf knowledge init` (CLI):
+ *      • TS  → continue existing build flow
+ *      • non-TS → emit a friendly "v10.0 only supports TypeScript" message
+ *      • unknown → emit a list of expected manifest files
+ *   - future adapters (v10.1+): higher tiers will use `sourceRoots` to drive
+ *     module discovery, replacing the hard-coded `src/` path.
+ *
+ * Priority order (first match wins):
+ *   1. `package.json` + `src/`               → typescript
+ *   2. `pom.xml`                              → java
+ *   3. `build.gradle` / `build.gradle.kts`    → java
+ *   4. `pyproject.toml`                       → python
+ *   5. `setup.py`                             → python
+ *   6. `go.mod`                               → go
+ *   7. `Cargo.toml`                           → rust
+ *   8. (none of the above)                    → unknown
+ *
+ * NOTE: only TypeScript currently has its `sourceRoots` populated.  Other
+ * kinds return `sourceRoots: []` — Tier 2/3 will fill those in.
+ */
+export type ProjectKind = 'typescript' | 'java' | 'python' | 'go' | 'rust' | 'monorepo' | 'unknown';
+/**
+ * The result of inspecting a project root.
+ *
+ * `reason` describes which manifest file (or absence thereof) drove the
+ * classification — useful in CLI error messages.
+ */
+export interface ProjectInfo {
+    kind: ProjectKind;
+    /** Absolute paths to discovered source roots; `[]` for unknown / not-yet-implemented kinds. */
+    sourceRoots: string[];
+    /** Human-readable explanation (e.g. `"package.json + src/ found"`). */
+    reason: string;
+}
+/**
+ * One sub-project inside a monorepo root.
+ *
+ * `name` is the literal directory name (e.g. `aipin-consumer`) — it becomes the
+ * KB module name verbatim (monorepo OQ2: never fall back to an adapter's default
+ * module name like Java's `app`).
+ */
+export interface SubprojectInfo {
+    /** Directory name, e.g. `"aipin-consumer"`. */
+    name: string;
+    /** Absolute path to the sub-project root. */
+    path: string;
+    /** Identifier of the adapter that recognised this sub-project. */
+    adapterName: string;
+}
+/**
+ * Result of a successful monorepo probe — at least two direct sub-directories
+ * are each recognised by some {@link LanguageAdapter}.
+ */
+export interface MonorepoInfo {
+    kind: 'monorepo';
+    subprojects: SubprojectInfo[];
+    reason: string;
+}
+/**
+ * List the names of direct child directories of `projectRoot` that pass the
+ * monorepo candidate filter. Used both by {@link detectMonorepo} and by the CLI
+ * warning text when degrading a true-generic project (so the operator can see
+ * what was scanned).
+ *
+ * Best-effort: any fs error yields `[]`.
+ */
+export declare function listCandidateSubdirs(projectRoot: string): string[];
+/**
+ * Detect a polyglot / multi-package monorepo rooted at `projectRoot`.
+ *
+ * A monorepo is recognised when the root itself has NO single-language adapter
+ * match (callers should only reach here after `getAdapter(projectRoot)` returned
+ * `null`) yet ≥ 2 direct child directories are each recognised by some adapter
+ * (they carry `package.json` / `pom.xml` / `build.gradle` / `go.mod` /
+ * `Cargo.toml` / `pyproject.toml` …).
+ *
+ * The `≥ 2` threshold avoids classifying a project that merely nests one library
+ * as a monorepo.
+ *
+ * @returns a {@link MonorepoInfo} when ≥ 2 sub-projects are found, else `null`.
+ */
+export declare function detectMonorepo(projectRoot: string): MonorepoInfo | null;
+/**
+ * Detect the project kind rooted at `projectRoot`.
+ *
+ * @param projectRoot absolute path to the project root.
+ * @returns a {@link ProjectInfo} describing the detected kind, source roots and a
+ *          human-readable reason.
+ */
+export declare function detectProject(projectRoot: string): ProjectInfo;
+//# sourceMappingURL=project-detector.d.ts.map

package/dist/knowledge/project-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-detector.d.ts","sourceRoot":"","sources":["../../src/knowledge/project-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAWH,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,+FAA+F;IAC/F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AA2CD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAWlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA0BvE;AAcD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CA4E9D"}

package/dist/knowledge/project-detector.js

@@ -0,0 +1,223 @@
+/**
+ * @file project-detector.ts
+ * v10.0 — Project-kind detection for the KB CLI.
+ *
+ * Scans the project root for well-known manifest files in a fixed priority
+ * order and returns a {@link ProjectInfo} describing what kind of project we
+ * are looking at.  Detection is purely filesystem-based (no parsing) so it is
+ * safe to call before any adapter / AI logic.
+ *
+ * Used by:
+ *   - `cf knowledge init` (CLI):
+ *      • TS  → continue existing build flow
+ *      • non-TS → emit a friendly "v10.0 only supports TypeScript" message
+ *      • unknown → emit a list of expected manifest files
+ *   - future adapters (v10.1+): higher tiers will use `sourceRoots` to drive
+ *     module discovery, replacing the hard-coded `src/` path.
+ *
+ * Priority order (first match wins):
+ *   1. `package.json` + `src/`               → typescript
+ *   2. `pom.xml`                              → java
+ *   3. `build.gradle` / `build.gradle.kts`    → java
+ *   4. `pyproject.toml`                       → python
+ *   5. `setup.py`                             → python
+ *   6. `go.mod`                               → go
+ *   7. `Cargo.toml`                           → rust
+ *   8. (none of the above)                    → unknown
+ *
+ * NOTE: only TypeScript currently has its `sourceRoots` populated.  Other
+ * kinds return `sourceRoots: []` — Tier 2/3 will fill those in.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAdapter } from './adapters/index.js';
+/**
+ * Directory names that are never treated as candidate sub-projects when
+ * scanning a monorepo root. These are tooling / build / doc directories that
+ * would otherwise create noise (and, for `node_modules`, an explosion of false
+ * positives from nested `package.json` files).
+ */
+const MONOREPO_SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'target',
+    'build',
+    'dist',
+    'docs',
+    'logs',
+    'scripts',
+    'tools',
+    'out',
+    'coverage',
+    'vendor',
+    '.idea',
+    '.vscode',
+]);
+/**
+ * Decide whether a direct child directory of a monorepo root is a candidate
+ * sub-project (i.e. worth probing with an adapter).
+ *
+ * Skip rules (mirror the spec's design convention):
+ *   - explicit skip-list (`node_modules`, `docs`, `target`, …)
+ *   - dot-directories (`.git`, `.github`, …)
+ *   - ALL-CAPS directories (`LICENSES`, `SECURITY`) — these are conventionally
+ *     metadata, not code.
+ */
+function isCandidateSubdir(name) {
+    if (MONOREPO_SKIP_DIRS.has(name))
+        return false;
+    if (name.startsWith('.'))
+        return false;
+    // ALL-CAPS (with optional digits / underscores) → treat as metadata dir.
+    if (/^[A-Z0-9_]+$/.test(name))
+        return false;
+    return true;
+}
+/**
+ * List the names of direct child directories of `projectRoot` that pass the
+ * monorepo candidate filter. Used both by {@link detectMonorepo} and by the CLI
+ * warning text when degrading a true-generic project (so the operator can see
+ * what was scanned).
+ *
+ * Best-effort: any fs error yields `[]`.
+ */
+export function listCandidateSubdirs(projectRoot) {
+    let entries;
+    try {
+        entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && isCandidateSubdir(e.name))
+        .map((e) => e.name)
+        .sort();
+}
+/**
+ * Detect a polyglot / multi-package monorepo rooted at `projectRoot`.
+ *
+ * A monorepo is recognised when the root itself has NO single-language adapter
+ * match (callers should only reach here after `getAdapter(projectRoot)` returned
+ * `null`) yet ≥ 2 direct child directories are each recognised by some adapter
+ * (they carry `package.json` / `pom.xml` / `build.gradle` / `go.mod` /
+ * `Cargo.toml` / `pyproject.toml` …).
+ *
+ * The `≥ 2` threshold avoids classifying a project that merely nests one library
+ * as a monorepo.
+ *
+ * @returns a {@link MonorepoInfo} when ≥ 2 sub-projects are found, else `null`.
+ */
+export function detectMonorepo(projectRoot) {
+    const candidates = listCandidateSubdirs(projectRoot);
+    const subprojects = [];
+    for (const name of candidates) {
+        const subPath = path.join(projectRoot, name);
+        let adapter;
+        try {
+            adapter = getAdapter(subPath);
+        }
+        catch {
+            adapter = null;
+        }
+        if (adapter) {
+            subprojects.push({ name, path: subPath, adapterName: adapter.name });
+        }
+    }
+    if (subprojects.length < 2)
+        return null;
+    return {
+        kind: 'monorepo',
+        subprojects,
+        reason: `${subprojects.length} sub-projects detected: ${subprojects
+            .map((s) => `${s.name} (${s.adapterName})`)
+            .join(', ')}`,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+function exists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect the project kind rooted at `projectRoot`.
+ *
+ * @param projectRoot absolute path to the project root.
+ * @returns a {@link ProjectInfo} describing the detected kind, source roots and a
+ *          human-readable reason.
+ */
+export function detectProject(projectRoot) {
+    // 1. TypeScript: require BOTH package.json and src/ to avoid false positives
+    //    on plain Node CLI repos with no source tree.
+    const hasPackageJson = exists(path.join(projectRoot, 'package.json'));
+    const hasSrcDir = exists(path.join(projectRoot, 'src'));
+    if (hasPackageJson && hasSrcDir) {
+        return {
+            kind: 'typescript',
+            sourceRoots: [path.join(projectRoot, 'src')],
+            reason: 'package.json + src/ found',
+        };
+    }
+    // 2. Java (Maven)
+    if (exists(path.join(projectRoot, 'pom.xml'))) {
+        return {
+            kind: 'java',
+            sourceRoots: [],
+            reason: 'pom.xml found',
+        };
+    }
+    // 3. Java (Gradle)
+    if (exists(path.join(projectRoot, 'build.gradle')) ||
+        exists(path.join(projectRoot, 'build.gradle.kts'))) {
+        return {
+            kind: 'java',
+            sourceRoots: [],
+            reason: 'build.gradle(.kts) found',
+        };
+    }
+    // 4. Python (PEP 621)
+    if (exists(path.join(projectRoot, 'pyproject.toml'))) {
+        return {
+            kind: 'python',
+            sourceRoots: [],
+            reason: 'pyproject.toml found',
+        };
+    }
+    // 5. Python (legacy)
+    if (exists(path.join(projectRoot, 'setup.py'))) {
+        return {
+            kind: 'python',
+            sourceRoots: [],
+            reason: 'setup.py found',
+        };
+    }
+    // 6. Go
+    if (exists(path.join(projectRoot, 'go.mod'))) {
+        return {
+            kind: 'go',
+            sourceRoots: [],
+            reason: 'go.mod found',
+        };
+    }
+    // 7. Rust
+    if (exists(path.join(projectRoot, 'Cargo.toml'))) {
+        return {
+            kind: 'rust',
+            sourceRoots: [],
+            reason: 'Cargo.toml found',
+        };
+    }
+    // 8. None of the above
+    return {
+        kind: 'unknown',
+        sourceRoots: [],
+        reason: 'no recognised manifest file found',
+    };
+}
+//# sourceMappingURL=project-detector.js.map

package/dist/knowledge/project-detector.js.map

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

package/dist/knowledge/prompt.d.ts

@@ -0,0 +1,228 @@
+/**
+ * @file prompt.ts
+ * AI prompt engineering layer for the KB system (Phase 1D).
+ *
+ * Provides two prompt builders:
+ *  - buildModulePrompt  → per-module knowledge page generation
+ *  - buildOverviewPrompt → cross-module overview / architecture page
+ *
+ * And one response parser:
+ *  - parseAIResponse → extracts `content` + `refs` from raw AI output
+ *
+ * Defence lines 1–2 (of 5):
+ *  1. System prompt rules that forbid hallucination
+ *  2. Source truncation ceiling (≤ 30K tokens ≈ 90K chars)
+ *
+ * No AI calls are made in this file — it only produces prompt strings.
+ */
+/**
+ * A single symbol extracted from the TypeScript Compiler API static scan.
+ * Mirrors `RepoMapSymbol` in types.ts — inlined here so Phase 1D compiles
+ * independently of Phase 1A merge order.
+ */
+export interface RepoMapSymbol {
+    /** File path relative to `src/` (e.g. `daemon/server.ts`). */
+    file: string;
+    /** 1-based line number where the symbol declaration starts. */
+    line: number;
+    /**
+     * Symbol kind as recognised by the TypeScript Compiler API.
+     */
+    kind: 'class' | 'function' | 'method' | 'interface' | 'type' | 'const' | 'enum';
+    /**
+     * Fully-qualified symbol name.
+     * Methods are written as `ClassName.methodName`.
+     */
+    name: string;
+    /** Complete type signature without the body. */
+    signature: string;
+    /** Whether the symbol carries an `export` modifier. */
+    exports: boolean;
+}
+/**
+ * A source-code reference returned by the AI inside a KB page.
+ * Mirrors `KBRef` in types.ts.
+ */
+export interface KBRef {
+    /** File path relative to project root (e.g. `src/daemon/server.ts`). */
+    file: string;
+    /** 1-based starting line number. */
+    lineStart: number;
+    /** 1-based ending line number (inclusive), if the reference spans a range. */
+    lineEnd?: number;
+    /** Qualified symbol name at this location (e.g. `SocketServer.start`). */
+    symbol?: string;
+}
+/**
+ * Input bag passed to `buildModulePrompt`.
+ */
+export interface PromptInput {
+    /** Module name (e.g. `daemon`, `skills`, `core`). */
+    moduleName: string;
+    /**
+     * Project name used in the system prompt (e.g. `claude-forge`, `wb-boot`).
+     * Typically derived from `path.basename(projectRoot)`.
+     */
+    projectName: string;
+    /**
+     * Subset of the repo-map symbols that belong to this module.
+     * Injected as structured JSON so the AI can pick line numbers from it.
+     */
+    repoMapSubset: RepoMapSymbol[];
+    /**
+     * Source file contents for this module.
+     * Will be truncated to KB_MAX_CHARS_PER_MODULE before building the prompt.
+     */
+    fileContents: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+/**
+ * A fully-formed prompt ready to be sent to the AI.
+ * `expectedSchema` tells the caller how to parse the response.
+ */
+export interface AIPrompt {
+    system: string;
+    user: string;
+    /**
+     * Describes the expected response format.
+     * `'module-page'`    → JSON with `{ content: string, refs: KBRef[] }`.
+     * `'plain-markdown'` → Raw markdown body; caller uses content as-is without
+     *                      `parseAIResponse`. Used by cross-module pages
+     *                      (overview/architecture/decisions/glossary/tech-stack).
+     */
+    expectedSchema: 'module-page' | 'plain-markdown';
+}
+/**
+ * The structured payload extracted from a raw AI response.
+ */
+export interface AIResponse {
+    /** Full markdown content of the compiled KB page. */
+    content: string;
+    /** Source-code references cited in the content. */
+    refs: Array<{
+        file: string;
+        lineStart: number;
+        lineEnd?: number;
+        symbol?: string;
+    }>;
+}
+/**
+ * Constructs the AI prompt for compiling a single module knowledge page.
+ *
+ * Defence line 1 — system prompt rules forbid hallucination.
+ * Defence line 2 — source content truncated to ≤ 90K chars (≈ 30K tokens).
+ *
+ * @param input  Module name, repo-map subset, and source file contents.
+ * @returns      A fully-formed `AIPrompt` ready to send to the AI.
+ */
+export declare function buildModulePrompt(input: PromptInput): AIPrompt;
+/**
+ * Constructs the AI prompt for compiling the cross-module overview page.
+ *
+ * Input is an array of `{ name, summary }` objects — one per module.
+ * The AI is instructed to produce **plain markdown** (not JSON-wrapped).
+ *
+ * @param allModuleSummaries  Summaries extracted from each compiled module page.
+ * @returns                   A fully-formed `AIPrompt`.
+ */
+export declare function buildOverviewPrompt(allModuleSummaries: Array<{
+    name: string;
+    summary: string;
+}>, projectName: string): AIPrompt;
+/**
+ * Strip outer markdown code fences from AI-generated content.
+ *
+ * Handles common fence patterns:
+ *  - ` ```markdown\n...\n``` `
+ *  - ` ```md\n...\n``` `
+ *  - ` ```\n...\n``` `
+ *
+ * Used by cross-module page compilation to unwrap plain-markdown responses.
+ *
+ * @param content  Raw AI response text.
+ * @returns        Content with outer fences removed, or original if no fence detected.
+ */
+export declare function stripMarkdownFence(content: string): string;
+/**
+ * Parses the raw string returned by the AI into an `AIResponse`.
+ *
+ * Handles three common wrapping styles produced by different AI models:
+ *  1. Plain JSON object `{ "content": ..., "refs": [...] }`
+ *  2. Markdown fenced block `` ```json\n{...}\n``` ``
+ *  3. Markdown fenced block without language tag `` ```\n{...}\n``` ``
+ *
+ * Validation rules applied to `refs`:
+ *  - Each element must have `file` (string) and `lineStart` (number).
+ *  - Elements failing these checks are **silently dropped** (other valid refs
+ *    are preserved).
+ *
+ * @param raw  Raw string returned by the AI.
+ * @returns    Parsed `AIResponse`, or `null` when parsing fails or the
+ *             top-level schema is invalid.  Callers should treat `null` as
+ *             "AI returned non-conforming output" and handle accordingly.
+ */
+export declare function parseAIResponse(raw: string): AIResponse | null;
+/**
+ * Build the AI prompt for `architecture.md`.
+ *
+ * Input is module summaries + a flattened mini repo-map (one row per exported
+ * top-level symbol). The AI is instructed to emit plain markdown — the caller
+ * does NOT run `parseAIResponse` on the result.
+ */
+export declare function buildArchitecturePrompt(input: {
+    moduleSummaries: Array<{
+        name: string;
+        summary: string;
+    }>;
+    repoMapMini: Array<{
+        module: string;
+        symbol: string;
+        kind: string;
+    }>;
+    projectName: string;
+}): AIPrompt;
+/**
+ * Build the AI prompt for `decisions.md`.
+ *
+ * Combines the "关键设计决策" sections from every module page with the latest
+ * git log (one-line). The AI should abstract project-level decisions, NOT
+ * paraphrase git commits.
+ */
+export declare function buildDecisionsPrompt(input: {
+    moduleDecisions: Array<{
+        name: string;
+        decisions: string;
+    }>;
+    recentCommits: string[];
+    projectName: string;
+}): AIPrompt;
+/**
+ * Build the AI prompt for `glossary.md`.
+ *
+ * Input is the full content of every module page plus the project-root
+ * CLAUDE.md (if present). The AI extracts proper-noun terms only (never
+ * generic programming jargon).
+ */
+export declare function buildGlossaryPrompt(input: {
+    moduleContents: Array<{
+        name: string;
+        content: string;
+    }>;
+    claudeMdContent: string | null;
+    projectName: string;
+}): AIPrompt;
+/**
+ * Build the AI prompt for `tech-stack.md`.
+ *
+ * Inputs are the raw text of `package.json`, `tsconfig.json` and
+ * `vitest.config.ts`. tsconfig / vitest are optional (null when missing).
+ */
+export declare function buildTechStackPrompt(input: {
+    packageJson: string;
+    tsconfig: string | null;
+    vitestConfig: string | null;
+    projectName: string;
+}): AIPrompt;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/knowledge/prompt.d.ts.map

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