specforge-mcp 0.1.0

package/dist/engine/config-health/ts-checker-scripts.js

@@ -0,0 +1,141 @@
+// engine/config-health/ts-checker-scripts.ts — SPEC-042
+// Checks for package.json scripts and husky hooks referencing missing tools/scripts.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { glob } from 'glob';
+async function readFileSafe(filePath) {
+    try {
+        return await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+async function fileExists(filePath) {
+    const content = await readFileSafe(filePath);
+    return content !== '';
+}
+// ---------------------------------------------------------------------------
+// Check: package.json scripts referencing non-installed commands
+// ---------------------------------------------------------------------------
+/**
+ * Detect package.json scripts that reference commands that are not installed
+ * in node_modules/.bin (e.g., "test": "vitest run" when vitest is not in deps).
+ */
+export async function checkPackageScripts(projectPath) {
+    const findings = [];
+    const pkgContent = await readFileSafe(join(projectPath, 'package.json'));
+    if (!pkgContent) {
+        return findings;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(pkgContent);
+    }
+    catch {
+        findings.push({
+            severity: 'error',
+            checker: 'package-scripts',
+            file: 'package.json',
+            message: 'package.json is not valid JSON',
+            fix: 'Fix the JSON syntax in package.json',
+        });
+        return findings;
+    }
+    const scripts = pkg.scripts ?? {};
+    const allDeps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+    };
+    // Commands to check — map CLI binary name to package name
+    const CLI_TO_PACKAGE = {
+        vitest: 'vitest',
+        jest: 'jest',
+        mocha: 'mocha',
+        eslint: 'eslint',
+        prettier: 'prettier',
+        tsc: 'typescript',
+        ts_node: 'ts-node',
+        'ts-node': 'ts-node',
+        tsx: 'tsx',
+        webpack: 'webpack',
+        vite: 'vite',
+        rollup: 'rollup',
+        esbuild: 'esbuild',
+    };
+    for (const [scriptName, scriptCmd] of Object.entries(scripts)) {
+        // Extract the first word (the command binary)
+        const firstWord = scriptCmd.trim().split(/\s+/)[0] ?? '';
+        const pkg_name = CLI_TO_PACKAGE[firstWord];
+        if (pkg_name && !(pkg_name in allDeps)) {
+            // Also check if the binary exists in node_modules/.bin
+            const binPath = join(projectPath, 'node_modules', '.bin', firstWord);
+            const binExists = await fileExists(binPath);
+            if (!binExists) {
+                findings.push({
+                    severity: 'error',
+                    checker: 'package-scripts',
+                    file: 'package.json',
+                    message: `Script '${scriptName}' uses '${firstWord}' but '${pkg_name}' is not in dependencies or node_modules/.bin`,
+                    fix: `Install the missing package: pnpm add -D ${pkg_name}`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Check: Husky hooks referencing missing scripts
+// ---------------------------------------------------------------------------
+/**
+ * Detect husky hooks (.husky/pre-commit, etc.) that reference scripts or
+ * files that don't exist in the project.
+ */
+export async function checkHuskyScripts(projectPath) {
+    const findings = [];
+    const huskyDir = join(projectPath, '.husky');
+    let hookFiles;
+    try {
+        hookFiles = await glob('*', {
+            cwd: huskyDir,
+            nodir: true,
+        });
+    }
+    catch {
+        return findings; // No .husky directory
+    }
+    for (const hookFile of hookFiles) {
+        const hookPath = join(huskyDir, hookFile);
+        const content = await readFileSafe(hookPath);
+        if (!content) {
+            continue;
+        }
+        // Extract script references: lines that run shell scripts
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i]?.trim() ?? '';
+            if (!line || line.startsWith('#')) {
+                continue;
+            }
+            // Check for references like: bash scripts/check.sh or ./scripts/check.sh
+            const scriptMatch = /(?:bash|sh)\s+([\w./-]+\.sh)/.exec(line);
+            if (scriptMatch) {
+                const scriptRef = scriptMatch[1] ?? '';
+                const scriptPath = join(projectPath, scriptRef);
+                const exists = await fileExists(scriptPath);
+                if (!exists) {
+                    findings.push({
+                        severity: 'error',
+                        checker: 'husky-scripts',
+                        file: `.husky/${hookFile}`,
+                        line: i + 1,
+                        message: `Husky hook references script '${scriptRef}' that does not exist`,
+                        fix: `Create the script at '${scriptRef}' or remove the reference from .husky/${hookFile}`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=ts-checker-scripts.js.map

package/dist/engine/config-health/ts-checker-scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts-checker-scripts.js","sourceRoot":"","sources":["../../../src/engine/config-health/ts-checker-scripts.ts"],"names":[],"mappings":"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"}

package/dist/engine/config-health/ts-checker.d.ts

@@ -0,0 +1,19 @@
+import type { ConfigHealthFinding } from '../../types/index.js';
+export { checkPackageScripts, checkHuskyScripts } from './ts-checker-scripts.js';
+/**
+ * Detect .ts files in the project root that are not covered by tsconfig.json
+ * include patterns. This catches config files (vitest.config.ts, eslint.config.ts)
+ * that developers forget to include.
+ */
+export declare function checkTsCoverage(projectPath: string): Promise<ConfigHealthFinding[]>;
+/**
+ * Detect known-invalid options in vitest.config.ts. These are options that
+ * were removed or moved in vitest v4+ (e.g., minWorkers, maxWorkers are now
+ * top-level, not under poolOptions.threads).
+ */
+export declare function checkVitestSchema(projectPath: string): Promise<ConfigHealthFinding[]>;
+/**
+ * Detect known-deprecated options in jest.config.ts/js.
+ */
+export declare function checkJestSchema(projectPath: string): Promise<ConfigHealthFinding[]>;
+//# sourceMappingURL=ts-checker.d.ts.map

package/dist/engine/config-health/ts-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts-checker.d.ts","sourceRoot":"","sources":["../../../src/engine/config-health/ts-checker.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAuBjF;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmFzF;AAMD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmD3F;AAMD;;GAEG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA0CzF"}

package/dist/engine/config-health/ts-checker.js

@@ -0,0 +1,203 @@
+// engine/config-health/ts-checker.ts — SPEC-042
+// TypeScript/JavaScript configuration health checks.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { glob } from 'glob';
+import healthSchemas from '../../config/config-health-schemas.json' with { type: 'json' };
+export { checkPackageScripts, checkHuskyScripts } from './ts-checker-scripts.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readFileSafe(filePath) {
+    try {
+        return await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+async function fileExists(filePath) {
+    const content = await readFileSafe(filePath);
+    return content !== '';
+}
+// ---------------------------------------------------------------------------
+// Check: TS files not covered by tsconfig include patterns
+// ---------------------------------------------------------------------------
+/**
+ * Detect .ts files in the project root that are not covered by tsconfig.json
+ * include patterns. This catches config files (vitest.config.ts, eslint.config.ts)
+ * that developers forget to include.
+ */
+export async function checkTsCoverage(projectPath) {
+    const findings = [];
+    const tsconfigPath = join(projectPath, 'tsconfig.json');
+    const tsconfigContent = await readFileSafe(tsconfigPath);
+    if (!tsconfigContent) {
+        return findings;
+    }
+    let tsconfig;
+    try {
+        tsconfig = JSON.parse(tsconfigContent);
+    }
+    catch {
+        findings.push({
+            severity: 'error',
+            checker: 'ts-coverage',
+            file: 'tsconfig.json',
+            message: 'tsconfig.json is not valid JSON — TypeScript compiler cannot parse it',
+            fix: 'Run `tsc --noEmit` to see the parse error and fix it',
+        });
+        return findings;
+    }
+    // If no include array is specified, TypeScript includes everything by default
+    if (!tsconfig.include) {
+        return findings;
+    }
+    // Find .ts files in the project root (not node_modules, not dist)
+    let rootTsFiles;
+    try {
+        rootTsFiles = await glob('*.ts', {
+            cwd: projectPath,
+            nodir: true,
+            ignore: ['node_modules/**', 'dist/**'],
+        });
+    }
+    catch {
+        return findings;
+    }
+    const includePatterns = tsconfig.include;
+    const excludePatterns = tsconfig.exclude ?? ['node_modules', 'dist'];
+    for (const tsFile of rootTsFiles) {
+        const isExcluded = excludePatterns.some((p) => tsFile === p || tsFile.startsWith(p.replace('/**', '/')));
+        if (isExcluded) {
+            continue;
+        }
+        // Check if the file matches any include pattern
+        const isCovered = includePatterns.some((pattern) => {
+            // Handle glob patterns like "src/**/*" or "src"
+            if (pattern === tsFile) {
+                return true;
+            }
+            if (pattern.endsWith('/**/*') || pattern.endsWith('/**')) {
+                return false;
+            }
+            // Pattern like "src/**" does not match root-level files
+            if (pattern.includes('/')) {
+                return false;
+            }
+            // Pattern like "**/*" or "**" would match all
+            if (pattern === '**/*' || pattern === '**') {
+                return true;
+            }
+            return false;
+        });
+        if (!isCovered) {
+            findings.push({
+                severity: 'warning',
+                checker: 'ts-coverage',
+                file: tsFile,
+                message: `'${tsFile}' is not covered by tsconfig.json include patterns — IDE may show errors`,
+                fix: `Add '${tsFile}' or a pattern like '*.ts' to the 'include' array in tsconfig.json`,
+            });
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Check: Invalid options in vitest.config.ts
+// ---------------------------------------------------------------------------
+/**
+ * Detect known-invalid options in vitest.config.ts. These are options that
+ * were removed or moved in vitest v4+ (e.g., minWorkers, maxWorkers are now
+ * top-level, not under poolOptions.threads).
+ */
+export async function checkVitestSchema(projectPath) {
+    const findings = [];
+    // Check if vitest is installed
+    const vitestPath = join(projectPath, 'node_modules', 'vitest');
+    const isInstalled = await fileExists(join(vitestPath, 'package.json'));
+    if (!isInstalled) {
+        findings.push({
+            severity: 'info',
+            checker: 'vitest-schema',
+            file: 'vitest.config.ts',
+            message: 'vitest not installed — skipping vitest config check',
+            fix: 'Install vitest: pnpm add -D vitest',
+        });
+        return findings;
+    }
+    const configFiles = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts'];
+    let configContent = '';
+    let configFile = '';
+    for (const fname of configFiles) {
+        const content = await readFileSafe(join(projectPath, fname));
+        if (content) {
+            configContent = content;
+            configFile = fname;
+            break;
+        }
+    }
+    if (!configContent) {
+        return findings;
+    }
+    const invalidOptions = healthSchemas.vitest.knownInvalidOptions;
+    for (const option of invalidOptions) {
+        // Match patterns like: minWorkers: 2, minWorkers:2, minWorkers : 2
+        const optionName = option.split('.').pop() ?? option;
+        const pattern = new RegExp(`\\b${optionName}\\s*:`);
+        if (pattern.test(configContent)) {
+            findings.push({
+                severity: 'warning',
+                checker: 'vitest-schema',
+                file: configFile,
+                message: `'${option}' is not a valid vitest v4+ InlineConfig option — silently ignored`,
+                fix: `Remove '${optionName}' from vitest config. In vitest v4+, use top-level 'minWorkers'/'maxWorkers' directly under the 'test' key`,
+            });
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Check: Invalid options in jest.config.{ts,js}
+// ---------------------------------------------------------------------------
+/**
+ * Detect known-deprecated options in jest.config.ts/js.
+ */
+export async function checkJestSchema(projectPath) {
+    const findings = [];
+    const jestPath = join(projectPath, 'node_modules', 'jest');
+    const isInstalled = await fileExists(join(jestPath, 'package.json'));
+    if (!isInstalled) {
+        return findings; // Jest not installed — skip silently (not vitest project)
+    }
+    const configFiles = ['jest.config.ts', 'jest.config.js', 'jest.config.mjs'];
+    let configContent = '';
+    let configFile = '';
+    for (const fname of configFiles) {
+        const content = await readFileSafe(join(projectPath, fname));
+        if (content) {
+            configContent = content;
+            configFile = fname;
+            break;
+        }
+    }
+    if (!configContent) {
+        return findings;
+    }
+    const deprecatedOptions = healthSchemas.jest.knownDeprecatedOptions;
+    for (const option of deprecatedOptions) {
+        const optionName = option.split('.').pop() ?? option;
+        const pattern = new RegExp(`\\b${optionName}\\s*:`);
+        if (pattern.test(configContent)) {
+            findings.push({
+                severity: 'warning',
+                checker: 'jest-schema',
+                file: configFile,
+                message: `'${option}' is a deprecated Jest config option`,
+                fix: `Remove or migrate '${optionName}' — see Jest migration guide for the replacement`,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=ts-checker.js.map

package/dist/engine/config-health/ts-checker.js.map

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

package/dist/engine/context/health.d.ts

@@ -0,0 +1,12 @@
+import type { DocHealthReport } from '../../types/index.js';
+import type { NoteInfo, SpecInfo } from '../../types/docs.js';
+export type { NoteInfo, SpecInfo };
+/** Detect specs that are done and had no updates for ARCHIVABLE_DAYS days. */
+export declare function detectArchivableSpecs(specs: SpecInfo[]): string[];
+/** Detect notes whose specId points to a non-existent spec. */
+export declare function detectOrphanNotes(notes: NoteInfo[], specs: SpecInfo[]): string[];
+/** Calculate health score 0-100 based on orphan ratio and archivable ratio. */
+export declare function calculateHealthScore(totalNotes: number, orphanCount: number, archivableCount: number, totalSpecs: number): number;
+/** Generate a DocHealthReport from notes and specs data. */
+export declare function generateDocHealthReport(notes: NoteInfo[], specs: SpecInfo[]): DocHealthReport;
+//# sourceMappingURL=health.d.ts.map

package/dist/engine/context/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/engine/context/health.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE9D,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAInC,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAajE;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAKhF;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACjB,MAAM,CAQR;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,eAAe,CAqB7F"}

package/dist/engine/context/health.js

@@ -0,0 +1,62 @@
+const ARCHIVABLE_DAYS = 30;
+/** Detect specs that are done and had no updates for ARCHIVABLE_DAYS days. */
+export function detectArchivableSpecs(specs) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - ARCHIVABLE_DAYS);
+    return specs
+        .filter((s) => {
+        if (s.status !== 'done') {
+            return false;
+        }
+        const updated = s.updatedAt ? new Date(s.updatedAt) : null;
+        return updated === null || updated < cutoff;
+    })
+        .map((s) => s.id);
+}
+/** Detect notes whose specId points to a non-existent spec. */
+export function detectOrphanNotes(notes, specs) {
+    const specIds = new Set(specs.map((s) => s.id));
+    return notes
+        .filter((n) => n.specId !== undefined && n.specId !== '' && !specIds.has(n.specId))
+        .map((n) => n.key);
+}
+/** Calculate health score 0-100 based on orphan ratio and archivable ratio. */
+export function calculateHealthScore(totalNotes, orphanCount, archivableCount, totalSpecs) {
+    if (totalNotes === 0 && totalSpecs === 0) {
+        return 100;
+    }
+    const orphanRatio = totalNotes > 0 ? orphanCount / totalNotes : 0;
+    const archivableRatio = totalSpecs > 0 ? archivableCount / totalSpecs : 0;
+    const penalty = orphanRatio * 40 + archivableRatio * 30;
+    return Math.max(0, Math.round(100 - penalty));
+}
+/** Generate a DocHealthReport from notes and specs data. */
+export function generateDocHealthReport(notes, specs) {
+    const archivableSpecs = detectArchivableSpecs(specs);
+    const orphanNotes = detectOrphanNotes(notes, specs);
+    const score = calculateHealthScore(notes.length, orphanNotes.length, archivableSpecs.length, specs.length);
+    return {
+        archivable: archivableSpecs,
+        orphans: orphanNotes,
+        outdated: [],
+        score,
+        summary: buildSummary(score, archivableSpecs.length, orphanNotes.length),
+        totalNotes: notes.length,
+        totalSpecs: specs.length,
+        generatedAt: new Date().toISOString(),
+    };
+}
+function buildSummary(score, archivable, orphans) {
+    const parts = [`Health score: ${score}/100.`];
+    if (archivable > 0) {
+        parts.push(`${archivable} spec(s) are archivable (done >30 days).`);
+    }
+    if (orphans > 0) {
+        parts.push(`${orphans} orphan note(s) reference non-existent specs.`);
+    }
+    if (archivable === 0 && orphans === 0) {
+        parts.push('Everything looks clean!');
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=health.js.map

package/dist/engine/context/health.js.map

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

package/dist/engine/context/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tags.js';
+export * from './health.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/context/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/engine/context/index.js

@@ -0,0 +1,4 @@
+// engine/context — barrel export
+export * from './tags.js';
+export * from './health.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/context/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/engine/context/tags.d.ts

@@ -0,0 +1,21 @@
+import type { NoteTag } from '../../types/index.js';
+/** Parse YAML frontmatter from a markdown string. Returns parsed fields and body. */
+export declare function extractFrontmatter(raw: string): {
+    meta: Record<string, unknown>;
+    body: string;
+};
+/** Build a YAML frontmatter block from a metadata object. */
+export declare function buildFrontmatter(meta: Record<string, unknown>): string;
+/** Strip frontmatter from content, returning only the body. */
+export declare function stripFrontmatter(content: string): string;
+/** Parse NoteTag[] from raw frontmatter tags array. Validates tags. */
+export declare function parseTagsFromMeta(rawTags: unknown): NoteTag[];
+/** Build the complete .md content string with frontmatter. */
+export declare function buildNoteContent(body: string, meta: {
+    key: string;
+    tags: NoteTag[];
+    specId?: string;
+    createdAt: string;
+    expiresAt?: string;
+}): string;
+//# sourceMappingURL=tags.d.ts.map

package/dist/engine/context/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/engine/context/tags.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAIpD,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC/C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAiCA;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CActE;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAK7D;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7F,MAAM,CAaR"}

package/dist/engine/context/tags.js

@@ -0,0 +1,83 @@
+const VALID_TAGS = ['pending', 'decision', 'idea', 'bug', 'blocker'];
+/** Parse YAML frontmatter from a markdown string. Returns parsed fields and body. */
+export function extractFrontmatter(raw) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
+    if (!match) {
+        return { meta: {}, body: raw };
+    }
+    /* v8 ignore next 2 */
+    const yamlBlock = match[1] ?? '';
+    const body = match[2] ?? '';
+    const meta = {};
+    for (const line of yamlBlock.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1) {
+            continue;
+        }
+        const key = line.slice(0, colon).trim();
+        const val = line.slice(colon + 1).trim();
+        if (!key) {
+            continue;
+        }
+        // Parse arrays: [a, b, c]
+        if (val.startsWith('[') && val.endsWith(']')) {
+            meta[key] = val
+                .slice(1, -1)
+                .split(',')
+                .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+                .filter(Boolean);
+        }
+        else if (val === 'null' || val === '') {
+            meta[key] = null;
+        }
+        else {
+            meta[key] = val.replace(/^['"]|['"]$/g, '');
+        }
+    }
+    return { meta, body };
+}
+/** Build a YAML frontmatter block from a metadata object. */
+export function buildFrontmatter(meta) {
+    const lines = ['---'];
+    for (const [key, val] of Object.entries(meta)) {
+        if (val === null || val === undefined) {
+            continue;
+        }
+        if (Array.isArray(val)) {
+            lines.push(`${key}: [${val.join(', ')}]`);
+        }
+        else if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
+            lines.push(`${key}: ${val}`);
+        }
+    }
+    lines.push('---');
+    return lines.join('\n') + '\n';
+}
+/** Strip frontmatter from content, returning only the body. */
+export function stripFrontmatter(content) {
+    const { body } = extractFrontmatter(content);
+    return body;
+}
+/** Parse NoteTag[] from raw frontmatter tags array. Validates tags. */
+export function parseTagsFromMeta(rawTags) {
+    if (!Array.isArray(rawTags)) {
+        return [];
+    }
+    return rawTags.filter((t) => VALID_TAGS.includes(t));
+}
+/** Build the complete .md content string with frontmatter. */
+export function buildNoteContent(body, meta) {
+    const frontmatterFields = {
+        key: meta.key,
+        tags: meta.tags.length > 0 ? meta.tags : [],
+        createdAt: meta.createdAt,
+    };
+    if (meta.specId) {
+        frontmatterFields.specId = meta.specId;
+    }
+    if (meta.expiresAt) {
+        frontmatterFields.expiresAt = meta.expiresAt;
+    }
+    return buildFrontmatter(frontmatterFields) + body;
+}
+//# sourceMappingURL=tags.js.map

package/dist/engine/context/tags.js.map

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

package/dist/engine/context-merger.d.ts

@@ -0,0 +1,23 @@
+import type { ProjectKnowledge, ContributedContext, ContextConflict, ContextMergeResult } from '../types/index.js';
+/**
+ * Inspect the current knowledge and return a list of areas that need
+ * additional documentation from the user.
+ */
+export declare function detectMissingAreas(knowledge: ProjectKnowledge): string[];
+/**
+ * Build an agent-idiomatic prompt that asks the user to share reference docs.
+ * The prompt explains what types of files are accepted and what areas need coverage.
+ */
+export declare function buildRequestPrompt(missingAreas: string[], knowledge: ProjectKnowledge): string;
+/**
+ * Compare auto-detected knowledge with contributed context and return
+ * a list of conflicting fields that the agent must resolve.
+ */
+export declare function detectConflicts(existing: ProjectKnowledge, contributed: ContributedContext): ContextConflict[];
+/**
+ * Merge contributed context into existing knowledge.
+ * Auto-detected values are NEVER overwritten — conflicts are reported instead.
+ * Returns the list of fields that were successfully merged and any conflicts found.
+ */
+export declare function mergeContext(existing: ProjectKnowledge, contributed: ContributedContext): ContextMergeResult;
+//# sourceMappingURL=context-merger.d.ts.map

package/dist/engine/context-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-merger.d.ts","sourceRoot":"","sources":["../../src/engine/context-merger.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAEf,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAS3B;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAoCxE;AAoBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,gBAAgB,GAAG,MAAM,CA8C9F;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,kBAAkB,GAC9B,eAAe,EAAE,CAkDnB;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,kBAAkB,GAC9B,kBAAkB,CA0CpB"}