@webpresso/agent-kit 0.21.0

package/dist/esm/config/docs-lint/generator/frontmatter-validator.js

@@ -0,0 +1,72 @@
+/**
+ * Creates a missing field error
+ */
+function createMissingFieldError(fieldName, fieldDef) {
+    return {
+        code: 'MISSING_REQUIRED_FRONTMATTER',
+        message: `Missing required frontmatter field '${fieldName}'`,
+        field: fieldName,
+        expected: fieldDef.description ?? 'a value',
+    };
+}
+/**
+ * Validates a field value against an enum constraint
+ */
+function validateEnumValue(fieldName, value, enumValues) {
+    if (!enumValues.includes(value)) {
+        return {
+            code: 'INVALID_FRONTMATTER_VALUE',
+            message: `Invalid value for '${fieldName}': '${value}'. Must be one of: ${enumValues.join(', ')}`,
+            field: fieldName,
+            expected: enumValues.join(', '),
+            actual: value,
+        };
+    }
+    return null;
+}
+/**
+ * Validates a field value against a fixed value constraint
+ */
+function validateFixedValue(fieldName, value, expectedValue) {
+    if (value !== expectedValue) {
+        return {
+            code: 'INVALID_FRONTMATTER_VALUE',
+            message: `Invalid value for '${fieldName}': '${value}'. Must be '${expectedValue}'`,
+            field: fieldName,
+            expected: expectedValue,
+            actual: value,
+        };
+    }
+    return null;
+}
+/**
+ * Validates a single frontmatter field
+ */
+function validateField(fieldName, fieldDef, value) {
+    if (value === undefined || value === null) {
+        return createMissingFieldError(fieldName, fieldDef);
+    }
+    if (fieldDef.enum && typeof value === 'string') {
+        return validateEnumValue(fieldName, value, fieldDef.enum);
+    }
+    if (fieldDef.value && typeof value === 'string') {
+        return validateFixedValue(fieldName, value, fieldDef.value);
+    }
+    return null;
+}
+/**
+ * Validates frontmatter against template schema
+ */
+export function validateFrontmatter(frontmatter, schema) {
+    const errors = [];
+    const requiredFields = schema.frontmatter?.required ?? {};
+    for (const [fieldName, fieldDef] of Object.entries(requiredFields)) {
+        const value = frontmatter[fieldName];
+        const error = validateField(fieldName, fieldDef, value);
+        if (error) {
+            errors.push(error);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=frontmatter-validator.js.map

package/dist/esm/config/docs-lint/generator/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Documentation Generator
+ *
+ * AST-aware Markdown generator for documentation synthesis.
+ * Combines deterministic SSOT sections with AI-generated narrative using unified/remark.
+ */
+export { validateFrontmatter } from './frontmatter-validator.js';
+export { generateDoc } from './markdown-generator.js';
+export { getAvailableTemplates, loadTemplate } from './template-loader.js';
+export type { FrontmatterField, GenerateDocInput, GenerateDocResult, LlmBlock, SectionDefinition, SsotData, TemplateSchema, ValidationError, ValidationErrorCode, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/config/docs-lint/generator/index.js

@@ -0,0 +1,10 @@
+/**
+ * Documentation Generator
+ *
+ * AST-aware Markdown generator for documentation synthesis.
+ * Combines deterministic SSOT sections with AI-generated narrative using unified/remark.
+ */
+export { validateFrontmatter } from './frontmatter-validator.js';
+export { generateDoc } from './markdown-generator.js';
+export { getAvailableTemplates, loadTemplate } from './template-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/config/docs-lint/generator/markdown-generator.d.ts

@@ -0,0 +1,6 @@
+import type { GenerateDocInput, GenerateDocResult } from './types.js';
+/**
+ * Main document generation function.
+ */
+export declare function generateDoc(input: GenerateDocInput): GenerateDocResult;
+//# sourceMappingURL=markdown-generator.d.ts.map

package/dist/esm/config/docs-lint/generator/markdown-generator.js

@@ -0,0 +1,78 @@
+import { stringify as yamlStringify } from 'yaml';
+import { validateFrontmatter } from './frontmatter-validator.js';
+import { loadTemplate } from './template-loader.js';
+/**
+ * Generates YAML frontmatter string
+ */
+function generateFrontmatter(frontmatter) {
+    const cleanFrontmatter = {};
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (value !== undefined) {
+            cleanFrontmatter[key] = value;
+        }
+    }
+    if (!Object.keys(cleanFrontmatter).length) {
+        return '';
+    }
+    return `---\n${yamlStringify(cleanFrontmatter)}---\n`;
+}
+/**
+ * Generates markdown sections from SSOT data and LLM blocks
+ */
+function generateSections(ssotSections, llmBlocks) {
+    const parts = [];
+    for (const [sectionName, content] of Object.entries(ssotSections)) {
+        parts.push(`## ${sectionName}\n\n${content}`);
+    }
+    for (const block of llmBlocks) {
+        parts.push(`## ${block.section}\n\n${block.content}`);
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Processes raw markdown after deterministic generation.
+ *
+ * The folded runtime surface intentionally avoids the former sub-package-only
+ * remark/unified dependencies until package manifest wiring is consolidated.
+ * The generator already emits normalized markdown, so the no-op processor keeps
+ * API behavior available without pulling CLI/template dependencies into this
+ * task.
+ */
+function processMarkdown(rawMarkdown) {
+    return {
+        success: true,
+        markdown: rawMarkdown,
+    };
+}
+/**
+ * Main document generation function.
+ */
+export function generateDoc(input) {
+    const templateResult = loadTemplate(input.template);
+    if (!templateResult.success) {
+        return {
+            success: false,
+            errors: templateResult.errors,
+        };
+    }
+    // Schema is guaranteed to exist when success is true
+    const { schema } = templateResult;
+    if (!schema) {
+        return {
+            success: false,
+            errors: [{ code: 'TEMPLATE_PARSE_ERROR', message: 'Template schema is undefined' }],
+        };
+    }
+    const frontmatterErrors = validateFrontmatter(input.ssot.frontmatter, schema);
+    if (frontmatterErrors.length > 0) {
+        return {
+            success: false,
+            errors: frontmatterErrors,
+        };
+    }
+    const frontmatterStr = generateFrontmatter(input.ssot.frontmatter);
+    const sectionsStr = generateSections(input.ssot.sections, input.llmBlocks);
+    const rawMarkdown = `${frontmatterStr}\n${sectionsStr}\n`;
+    return processMarkdown(rawMarkdown);
+}
+//# sourceMappingURL=markdown-generator.js.map

package/dist/esm/config/docs-lint/generator/template-loader.d.ts

@@ -0,0 +1,18 @@
+import type { TemplateSchema, ValidationError } from './types.js';
+/**
+ * Result of loading a template
+ */
+export interface LoadTemplateResult {
+    success: boolean;
+    schema?: TemplateSchema;
+    errors?: ValidationError[];
+}
+/**
+ * Loads a template schema from templates/{name}.yaml
+ */
+export declare function loadTemplate(templateName: string): LoadTemplateResult;
+/**
+ * Gets list of available template names
+ */
+export declare function getAvailableTemplates(): string[];
+//# sourceMappingURL=template-loader.d.ts.map

package/dist/esm/config/docs-lint/generator/template-loader.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRootDir = dirname(dirname(__dirname));
+/**
+ * Resolves the templates directory path
+ */
+function getTemplatesDir() {
+    return join(packageRootDir, 'templates');
+}
+/**
+ * Loads a template schema from templates/{name}.yaml
+ */
+export function loadTemplate(templateName) {
+    const templatesDir = getTemplatesDir();
+    const templatePath = join(templatesDir, `${templateName}.yaml`);
+    if (!existsSync(templatePath)) {
+        return {
+            success: false,
+            errors: [
+                {
+                    code: 'TEMPLATE_NOT_FOUND',
+                    message: `Template '${templateName}' not found at ${templatePath}. Available templates are in templates/`,
+                    field: 'template',
+                    expected: 'valid template name',
+                    actual: templateName,
+                },
+            ],
+        };
+    }
+    try {
+        const content = readFileSync(templatePath, 'utf-8');
+        const schema = parseYaml(content);
+        return {
+            success: true,
+            schema,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            errors: [
+                {
+                    code: 'TEMPLATE_PARSE_ERROR',
+                    message: `Failed to parse template '${templateName}': ${message}`,
+                    field: 'template',
+                },
+            ],
+        };
+    }
+}
+/**
+ * Gets list of available template names
+ */
+export function getAvailableTemplates() {
+    const templatesDir = getTemplatesDir();
+    if (!existsSync(templatesDir)) {
+        return [];
+    }
+    const files = readdirSync(templatesDir);
+    return files.filter((f) => f.endsWith('.yaml')).map((f) => f.replace('.yaml', ''));
+}
+//# sourceMappingURL=template-loader.js.map

package/dist/esm/config/docs-lint/generator/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Template schema types loaded from templates/*.yaml
+ */
+export interface TemplateSchema {
+    name: string;
+    description: string;
+    frontmatter: {
+        required: Record<string, FrontmatterField>;
+        optional?: Record<string, FrontmatterField>;
+    };
+    sections: {
+        required: SectionDefinition[];
+        optional?: SectionDefinition[];
+    };
+    location: {
+        patterns: string[];
+        exclude?: string[];
+    };
+    naming: {
+        pattern: string;
+        case: 'lower' | 'upper' | 'exact';
+        description?: string;
+        notes?: string;
+    };
+}
+export interface FrontmatterField {
+    value?: string;
+    enum?: string[];
+    type?: 'string' | 'date' | 'array';
+    format?: string;
+    description?: string;
+}
+export interface SectionDefinition {
+    name: string;
+    pattern?: string;
+    description?: string;
+}
+/**
+ * SSOT data that populates deterministic sections
+ */
+export interface SsotData {
+    /** Key-value pairs for frontmatter fields */
+    frontmatter: Record<string, string | string[] | undefined>;
+    /** Named sections with their markdown content */
+    sections: Record<string, string>;
+}
+/**
+ * LLM-generated narrative blocks
+ */
+export interface LlmBlock {
+    /** Section name this block belongs to */
+    section: string;
+    /** Markdown content from LLM */
+    content: string;
+    /** Optional metadata about generation */
+    metadata?: {
+        model?: string;
+        tokens?: number;
+        timestamp?: string;
+    };
+}
+/**
+ * Input for generateDoc function
+ */
+export interface GenerateDocInput {
+    /** Template name (matches templates/{name}.yaml) */
+    template: string;
+    /** SSOT data for deterministic sections */
+    ssot: SsotData;
+    /** LLM-generated narrative blocks */
+    llmBlocks: LlmBlock[];
+}
+/**
+ * Result from generateDoc function
+ */
+export interface GenerateDocResult {
+    /** Whether generation succeeded */
+    success: boolean;
+    /** Generated markdown content (if success) */
+    markdown?: string;
+    /** Validation errors (if failed) */
+    errors?: ValidationError[];
+}
+/**
+ * Validation error with actionable context
+ */
+export interface ValidationError {
+    /** Error code for programmatic handling */
+    code: ValidationErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Field or section that failed validation */
+    field?: string;
+    /** Expected value or pattern */
+    expected?: string;
+    /** Actual value received */
+    actual?: string;
+}
+export type ValidationErrorCode = 'TEMPLATE_NOT_FOUND' | 'TEMPLATE_PARSE_ERROR' | 'MISSING_REQUIRED_FRONTMATTER' | 'INVALID_FRONTMATTER_VALUE' | 'MISSING_REQUIRED_SECTION' | 'INVALID_SECTION_CONTENT' | 'LLM_BLOCK_INVALID_SECTION' | 'DUPLICATE_SECTION';
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/config/docs-lint/generator/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/config/docs-lint/index.d.ts

@@ -0,0 +1,34 @@
+import type { DocType } from './schemas/index.js';
+export * from './parsers/index.js';
+export * from './schemas/index.js';
+export type { DocType, DocTypeConfig, ValidationError as SchemaValidationError, } from './schemas/index.js';
+export type { ParsedDocument } from './parsers/frontmatter.js';
+export interface ValidationError {
+    file: string;
+    line?: number;
+    column?: number;
+    severity: 'error' | 'warning';
+    source: 'schema' | 'markdownlint' | 'vale' | 'structure' | 'context-limits' | 'blueprint-format';
+    message: string;
+    ruleId?: string;
+}
+export interface ContextFileLimits {
+    maxLines: number;
+    warnLines: number;
+    maxTokens?: number;
+    warnTokens?: number;
+    description: string;
+}
+export interface ValidationResult {
+    file: string;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    valid: boolean;
+}
+export interface MigrationResult {
+    file: string;
+    action: 'added' | 'updated' | 'skipped' | 'error';
+    docType: DocType;
+    message?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/config/docs-lint/index.js

@@ -0,0 +1,3 @@
+export * from './parsers/index.js';
+export * from './schemas/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/config/docs-lint/parsers/bold-metadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Parser for legacy bold metadata blocks used in implementation plans.
+ * Converts **Key**: Value format to frontmatter-compatible object.
+ */
+interface BoldMetadata {
+    status?: string;
+    complexity?: string;
+    last_updated?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Detect if content contains bold metadata block.
+ */
+export declare function hasBoldMetadata(content: string): boolean;
+/**
+ * Parse bold metadata block from content.
+ * Returns parsed metadata and the content without the metadata block.
+ */
+export declare function parseBoldMetadata(content: string): {
+    metadata: BoldMetadata;
+    contentWithoutMetadata: string;
+};
+/**
+ * Convert bold metadata values to frontmatter-compatible format.
+ */
+export declare function normalizeBoldMetadata(metadata: BoldMetadata): Record<string, unknown>;
+export {};
+//# sourceMappingURL=bold-metadata.d.ts.map

package/dist/esm/config/docs-lint/parsers/bold-metadata.js

@@ -0,0 +1,176 @@
+/**
+ * Parser for legacy bold metadata blocks used in implementation plans.
+ * Converts **Key**: Value format to frontmatter-compatible object.
+ */
+/**
+ * Pattern to match bold metadata lines: **Key**: Value
+ */
+const BOLD_METADATA_PATTERN = /^\*\*([^*]+)\*\*:\s*(.+)$/;
+/**
+ * Common metadata keys in implementation plans
+ */
+const KNOWN_KEYS = {
+    Type: 'type',
+    Status: 'status',
+    Complexity: 'complexity',
+    'Last Updated': 'last_updated',
+    Epic: 'epic',
+    Priority: 'priority',
+    Owner: 'owner',
+    Category: 'category',
+    Focus: 'focus',
+};
+/**
+ * Detect if content contains bold metadata block.
+ */
+export function hasBoldMetadata(content) {
+    const lines = content.split('\n').slice(0, 20); // Check first 20 lines
+    let foundCount = 0;
+    for (const line of lines) {
+        if (BOLD_METADATA_PATTERN.test(line.trim())) {
+            foundCount++;
+        }
+    }
+    // Need at least 1 bold metadata line
+    return foundCount >= 1;
+}
+/**
+ * Find the first H1 title line index in the content
+ */
+function findTitleLineIndex(lines) {
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i]?.trim().startsWith('# ')) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Parse a single metadata line and return key-value pair if valid
+ */
+function parseMetadataLine(line) {
+    const match = line.trim().match(BOLD_METADATA_PATTERN);
+    if (!match)
+        return null;
+    const rawKey = match[1];
+    const rawValue = match[2];
+    if (!rawKey || !rawValue)
+        return null;
+    const key = KNOWN_KEYS[rawKey] ?? rawKey.toLowerCase().replace(/\s+/g, '_');
+    return { key, value: rawValue.trim() };
+}
+/**
+ * Check if we should stop searching for metadata
+ */
+function shouldStopSearching(line, hasFoundMetadata) {
+    const trimmed = line.trim();
+    return (hasFoundMetadata &&
+        trimmed !== '' &&
+        !trimmed.startsWith('>') &&
+        !trimmed.startsWith('#') &&
+        !BOLD_METADATA_PATTERN.test(trimmed));
+}
+/**
+ * Search for metadata in a range of lines
+ */
+function searchMetadataInRange(ctx, start, end) {
+    for (let i = start; i < end; i++) {
+        const currentLine = ctx.lines[i];
+        if (!currentLine)
+            continue;
+        const parsed = parseMetadataLine(currentLine);
+        if (parsed) {
+            ctx.metadata[parsed.key] = parsed.value;
+            ctx.metadataLineIndices.push(i);
+        }
+        else if (shouldStopSearching(currentLine, ctx.metadataLineIndices.length > 0)) {
+            break;
+        }
+    }
+}
+/**
+ * Get search ranges based on title position
+ */
+function getSearchRanges(titleLineIndex, linesLength) {
+    const ranges = [];
+    if (titleLineIndex > 0) {
+        ranges.push({ start: 0, end: titleLineIndex });
+    }
+    if (titleLineIndex >= 0) {
+        const searchStart = titleLineIndex + 1;
+        ranges.push({ start: searchStart, end: Math.min(searchStart + 15, linesLength) });
+    }
+    else {
+        ranges.push({ start: 0, end: Math.min(20, linesLength) });
+    }
+    return ranges;
+}
+/**
+ * Parse bold metadata block from content.
+ * Returns parsed metadata and the content without the metadata block.
+ */
+export function parseBoldMetadata(content) {
+    const lines = content.split('\n');
+    const ctx = { lines, metadata: {}, metadataLineIndices: [] };
+    const titleLineIndex = findTitleLineIndex(lines);
+    const searchRanges = getSearchRanges(titleLineIndex, lines.length);
+    for (const { start, end } of searchRanges) {
+        searchMetadataInRange(ctx, start, end);
+    }
+    const filteredLines = lines.filter((_, i) => !ctx.metadataLineIndices.includes(i));
+    let cleanedContent = filteredLines.join('\n');
+    cleanedContent = cleanedContent.replace(/^(# .+\n)\n{3,}/m, '$1\n\n');
+    return {
+        metadata: ctx.metadata,
+        contentWithoutMetadata: cleanedContent,
+    };
+}
+/**
+ * Convert bold metadata values to frontmatter-compatible format.
+ */
+export function normalizeBoldMetadata(metadata) {
+    const result = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined)
+            continue;
+        switch (key) {
+            case 'type':
+                // Normalize type to lowercase: "Core" -> "core"
+                result.type = value.toLowerCase();
+                break;
+            case 'status':
+                // Normalize status values: "In Progress" -> "in-progress"
+                result.status = value.toLowerCase().replace(/\s+/g, '-');
+                break;
+            case 'complexity':
+                // Keep uppercase: XS, S, M, L, XL
+                result.complexity = value.toUpperCase();
+                break;
+            case 'last_updated':
+                // Parse date formats: "2025-12-05" or "December 5, 2025"
+                result.last_updated = parseDate(value);
+                break;
+            default:
+                result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Parse various date formats to YYYY-MM-DD.
+ */
+function parseDate(dateStr) {
+    // Already in YYYY-MM-DD format
+    if (/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+        return dateStr;
+    }
+    // Try parsing with Date
+    const date = new Date(dateStr);
+    if (!Number.isNaN(date.getTime())) {
+        const result = date.toISOString().split('T')[0];
+        return result ?? dateStr;
+    }
+    // Return as-is if we can't parse
+    return dateStr;
+}
+//# sourceMappingURL=bold-metadata.js.map

package/dist/esm/config/docs-lint/parsers/frontmatter.d.ts

@@ -0,0 +1,20 @@
+export interface ParsedDocument {
+    frontmatter: Record<string, unknown>;
+    content: string;
+    hasFrontmatter: boolean;
+}
+/**
+ * Parse a markdown file and extract frontmatter.
+ * Uses gray-matter for YAML frontmatter parsing.
+ */
+export declare function parseFrontmatter(content: string): ParsedDocument;
+/**
+ * Generate YAML frontmatter string from an object.
+ */
+export declare function generateFrontmatter(data: Record<string, unknown>): string;
+/**
+ * Add or update frontmatter in a markdown document.
+ * Returns the new document content.
+ */
+export declare function updateFrontmatter(content: string, newData: Record<string, unknown>): string;
+//# sourceMappingURL=frontmatter.d.ts.map