@webpresso/agent-kit 0.21.0

package/dist/esm/compiler/orphans.js

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+const GENERATED_SKILL_DIRS = ['.claude/skills', '.windsurf/skills', '.agents/skills'];
+function listDirEntries(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+function listCanonicalSkills(cwd) {
+    const canonicalDir = join(cwd, '.agent', 'skills');
+    if (!existsSync(canonicalDir))
+        return new Set();
+    try {
+        return new Set(readdirSync(canonicalDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => e.name));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function findOrphanedSkills(cwd) {
+    const canonical = listCanonicalSkills(cwd);
+    const orphans = [];
+    for (const runtimeDir of GENERATED_SKILL_DIRS) {
+        const absDir = join(cwd, runtimeDir);
+        for (const name of listDirEntries(absDir)) {
+            if (!canonical.has(name)) {
+                orphans.push({
+                    name,
+                    path: join(absDir, name),
+                    runtimeDir,
+                });
+            }
+        }
+    }
+    return orphans;
+}
+export async function removeOrphanedSkills(orphans, dryRun) {
+    const canonicalPrefix = '.agent/';
+    for (const orphan of orphans) {
+        // Safety guard: never remove anything under .agent/
+        if (orphan.path.includes(`${canonicalPrefix}skills`)) {
+            throw new Error(`removeOrphanedSkills: refusing to remove canonical source path: ${orphan.path}`);
+        }
+        if (!dryRun) {
+            rmSync(orphan.path, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=orphans.js.map

package/dist/esm/compiler/schema.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+declare const skillArgumentSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const skillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    when_to_use: z.ZodOptional<z.ZodString>;
+    'argument-hint': z.ZodOptional<z.ZodString>;
+    arguments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    'disable-model-invocation': z.ZodOptional<z.ZodBoolean>;
+    'user-invocable': z.ZodOptional<z.ZodBoolean>;
+    'allowed-tools': z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export declare const commandFrontmatterSchema: z.ZodObject<{
+    description: z.ZodString;
+    agent: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const agentFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    model: z.ZodOptional<z.ZodString>;
+    permissionMode: z.ZodOptional<z.ZodString>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    hooks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    isolation: z.ZodOptional<z.ZodEnum<{
+        worktree: "worktree";
+    }>>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;
+export type CommandFrontmatter = z.infer<typeof commandFrontmatterSchema>;
+export type AgentFrontmatter = z.infer<typeof agentFrontmatterSchema>;
+export type SkillArgument = z.infer<typeof skillArgumentSchema>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/compiler/schema.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+// Argument descriptor used in SKILL.md frontmatter
+const skillArgumentSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    required: z.boolean().optional(),
+});
+export const skillFrontmatterSchema = z
+    .object({
+    name: z.string(),
+    description: z.string(),
+})
+    .passthrough()
+    .extend({
+    when_to_use: z.string().optional(),
+    'argument-hint': z.string().optional(),
+    arguments: z.array(skillArgumentSchema).optional(),
+    'disable-model-invocation': z.boolean().optional(),
+    'user-invocable': z.boolean().optional(),
+    'allowed-tools': z.array(z.string()).optional(),
+});
+export const commandFrontmatterSchema = z
+    .object({
+    description: z.string(),
+})
+    .passthrough()
+    .extend({
+    agent: z.string().optional(),
+    model: z.string().optional(),
+});
+export const agentFrontmatterSchema = z
+    .object({
+    name: z.string(),
+    description: z.string(),
+})
+    .passthrough()
+    .extend({
+    tools: z.array(z.unknown()).optional(),
+    disallowedTools: z.array(z.unknown()).optional(),
+    model: z.string().optional(),
+    permissionMode: z.string().optional(),
+    skills: z.array(z.unknown()).optional(),
+    mcpServers: z.record(z.string(), z.unknown()).optional(),
+    hooks: z.record(z.string(), z.unknown()).optional(),
+    maxTurns: z.number().optional(),
+    isolation: z.enum(['worktree']).optional(),
+    color: z.string().optional(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/esm/config/docs-lint/cli/check-internal-links.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+/**
+ * Internal Markdown Link Checker
+ *
+ * Validates that internal doc links (./foo.md, ../bar.md, docs/x.md)
+ * point to files that actually exist.
+ *
+ * Usage:
+ *   tsx check-internal-links.ts                    # Check all docs
+ *   tsx check-internal-links.ts file1.md file2.md  # Check specific files
+ */
+export {};
+//# sourceMappingURL=check-internal-links.d.ts.map

package/dist/esm/config/docs-lint/cli/check-internal-links.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+/**
+ * Internal Markdown Link Checker
+ *
+ * Validates that internal doc links (./foo.md, ../bar.md, docs/x.md)
+ * point to files that actually exist.
+ *
+ * Usage:
+ *   tsx check-internal-links.ts                    # Check all docs
+ *   tsx check-internal-links.ts file1.md file2.md  # Check specific files
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { glob } from 'glob';
+// Match markdown links: [text](path.md) or [text](path.md#anchor)
+const LINK_PATTERN = /\[([^\]]*)\]\(([^)]+\.md(?:#[^)]*)?)\)/g;
+/**
+ * Check if a link should be skipped
+ */
+function shouldSkipRawLink(rawLink) {
+    if (rawLink.startsWith('http://') || rawLink.startsWith('https://'))
+        return true;
+    if (rawLink.startsWith('file://'))
+        return true;
+    if (/[{$]/.test(rawLink))
+        return true;
+    return false;
+}
+/**
+ * Resolve a link path to an absolute path
+ */
+function resolveLinkTarget(linkPath, fileDir) {
+    if (linkPath.startsWith('/')) {
+        return join(process.cwd(), linkPath);
+    }
+    return resolve(fileDir, linkPath);
+}
+/**
+ * Process a single match and return a link object if valid
+ */
+function processLinkMatch(match, fileDir, lineNumber) {
+    const rawLink = match[2];
+    if (!rawLink)
+        return null;
+    if (shouldSkipRawLink(rawLink))
+        return null;
+    const linkPath = rawLink.split('#')[0];
+    if (!linkPath)
+        return null;
+    return {
+        link: rawLink,
+        target: resolveLinkTarget(linkPath, fileDir),
+        line: lineNumber,
+    };
+}
+function extractLinks(content, filePath) {
+    const links = [];
+    const lines = content.split('\n');
+    const fileDir = dirname(filePath);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line)
+            continue;
+        const regex = new RegExp(LINK_PATTERN.source, LINK_PATTERN.flags);
+        let match;
+        match = regex.exec(line);
+        while (match !== null) {
+            const linkObj = processLinkMatch(match, fileDir, i + 1);
+            if (linkObj) {
+                links.push(linkObj);
+            }
+            match = regex.exec(line);
+        }
+    }
+    return links;
+}
+function checkFile(filePath) {
+    const broken = [];
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const links = extractLinks(content, filePath);
+        for (const { link, target, line } of links) {
+            if (!existsSync(target)) {
+                broken.push({
+                    file: filePath,
+                    line,
+                    link,
+                    target,
+                });
+            }
+        }
+    }
+    catch {
+        // Skip unreadable files
+    }
+    return broken;
+}
+/**
+ * Get files to check based on args or glob
+ */
+function getFilesToCheck(args) {
+    if (args.length > 0) {
+        return Promise.resolve(args.map((f) => resolve(process.cwd(), f)));
+    }
+    return glob(['docs/**/*.md', 'CLAUDE.md', '.agent/rules/agent-guide.md', 'README.md', '.claude/**/*.md'], {
+        cwd: process.cwd(),
+        ignore: ['**/node_modules/**', '.claude/worktrees/**', '.tmp/**'],
+        absolute: true,
+    });
+}
+/**
+ * Group broken links by file
+ */
+function groupBrokenLinksByFile(allBroken) {
+    const byFile = new Map();
+    for (const broken of allBroken) {
+        const relPath = broken.file.replace(`${process.cwd()}/`, '');
+        const existing = byFile.get(relPath) || [];
+        existing.push(broken);
+        byFile.set(relPath, existing);
+    }
+    return byFile;
+}
+/**
+ * Print broken links report
+ */
+function printBrokenLinksReport(byFile) {
+    for (const [file, links] of byFile) {
+        console.log(`  ${file}:`);
+        for (const { line, link } of links) {
+            console.log(`    L${line}: ${link}`);
+        }
+        console.log();
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const files = await getFilesToCheck(args);
+    let allBroken = [];
+    for (const file of files) {
+        if (!existsSync(file))
+            continue;
+        allBroken = allBroken.concat(checkFile(file));
+    }
+    if (!allBroken.length) {
+        if (!args.length) {
+            console.log(`✓ No broken internal links (checked ${files.length} files)`);
+        }
+        process.exit(0);
+    }
+    console.log(`\n❌ Found ${allBroken.length} broken internal link(s):\n`);
+    printBrokenLinksReport(groupBrokenLinksByFile(allBroken));
+    process.exit(1);
+}
+if (import.meta.main) {
+    main().catch((error) => {
+        console.error('Error checking internal links:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=check-internal-links.js.map

package/dist/esm/config/docs-lint/cli/check-refs.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+/**
+ * Dead Reference Detection
+ *
+ * Finds documentation that references code files that no longer exist.
+ * Helps identify stale docs that need updating after code refactors.
+ */
+export {};
+//# sourceMappingURL=check-refs.d.ts.map

package/dist/esm/config/docs-lint/cli/check-refs.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env bun
+/**
+ * Dead Reference Detection
+ *
+ * Finds documentation that references code files that no longer exist.
+ * Helps identify stale docs that need updating after code refactors.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { glob } from 'glob';
+const DOCS_ROOT = process.cwd();
+/** File path patterns to extract from docs */
+const FILE_PATTERNS = [
+    // Explicit file paths in backticks: `src/handlers/foo.ts`
+    /`((?:apps|packages|tooling|infra|scripts|e2e)\/[a-zA-Z0-9\-_/.]+\.[a-zA-Z]+)`/g,
+    // File paths in markdown links: [text](src/foo.ts)
+    /\]\(((?:apps|packages|tooling|infra|scripts|e2e)\/[a-zA-Z0-9\-_/.]+\.[a-zA-Z]+)/g,
+    // Path patterns after "in" or "at": in src/handlers/foo.ts
+    /(?:in|at|from|see)\s+`?((?:apps|packages|tooling|infra|scripts|e2e)\/[a-zA-Z0-9\-_/.]+\.[a-zA-Z]+)`?/gi,
+];
+/** Directory patterns */
+const DIR_PATTERNS = [
+    // Directory paths in backticks: `apps/workers/chef/`
+    /`((?:apps|packages|tooling|infra|scripts|e2e)\/[a-zA-Z0-9\-_/]+\/)`/g,
+];
+/** Patterns to skip (templates, examples) */
+const SKIP_PATTERNS = [
+    /\$\{/, // Template literals
+    /\*/, // Glob patterns
+    /\.\.\./, // Ellipsis in paths
+    /<[^>]+>/, // Placeholder paths
+    /example/i, // Example paths
+];
+function shouldSkip(ref) {
+    return SKIP_PATTERNS.some((pattern) => pattern.test(ref));
+}
+/**
+ * Extract a single match from a regex execution
+ */
+function extractMatchRef(match, type) {
+    if (!match?.[1])
+        return null;
+    const ref = type === 'directory' ? match[1].replace(/\/$/, '') : match[1];
+    return shouldSkip(ref) ? null : ref;
+}
+function extractPatternMatches(line, lineNum, patterns, type) {
+    const refs = [];
+    for (const pattern of patterns) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match = null;
+        match = regex.exec(line);
+        while (match !== null) {
+            const ref = extractMatchRef(match, type);
+            if (ref) {
+                refs.push({ ref, line: lineNum, type });
+            }
+            match = regex.exec(line);
+        }
+    }
+    return refs;
+}
+function dedupeRefs(refs) {
+    const seen = new Set();
+    return refs.filter((r) => {
+        const key = `${r.ref}:${r.line}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function extractRefs(content) {
+    const refs = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const lineNum = i + 1;
+        const line = lines[i];
+        if (!line || line.trimStart().startsWith('```'))
+            continue;
+        refs.push(...extractPatternMatches(line, lineNum, FILE_PATTERNS, 'file'));
+        refs.push(...extractPatternMatches(line, lineNum, DIR_PATTERNS, 'directory'));
+    }
+    return dedupeRefs(refs);
+}
+function checkRefExists(ref) {
+    const fullPath = join(DOCS_ROOT, ref);
+    return existsSync(fullPath);
+}
+function validateFile(file) {
+    const dead = [];
+    const content = readFileSync(file, 'utf-8');
+    const refs = extractRefs(content);
+    for (const { ref, line, type } of refs) {
+        if (!checkRefExists(ref)) {
+            dead.push({
+                docFile: relative(DOCS_ROOT, file),
+                line,
+                reference: ref,
+                type,
+            });
+        }
+    }
+    return dead;
+}
+/**
+ * Group dead references by file
+ */
+function groupByFile(allDead) {
+    const byFile = new Map();
+    for (const dead of allDead) {
+        const existing = byFile.get(dead.docFile) || [];
+        existing.push(dead);
+        byFile.set(dead.docFile, existing);
+    }
+    return byFile;
+}
+/**
+ * Print dead reference report
+ */
+function printDeadRefReport(byFile) {
+    for (const [file, refs] of byFile) {
+        console.log(`  ${file}:`);
+        for (const { line, reference, type } of refs) {
+            const icon = type === 'directory' ? '📁' : '📄';
+            console.log(`    L${line}: ${icon} ${reference}`);
+        }
+        console.log();
+    }
+}
+async function main() {
+    const files = await glob(['docs/**/*.md', 'CLAUDE.md', '.agent/rules/agent-guide.md', '.claude/**/*.md'], {
+        cwd: DOCS_ROOT,
+        ignore: [
+            '**/node_modules/**',
+            '.claude/worktrees/**',
+            '.tmp/**',
+            'webpresso/blueprints/completed/**',
+            'webpresso/blueprints/archived/**',
+            'docs/evaluations/archive/**',
+        ],
+        absolute: true,
+    });
+    let allDead = [];
+    for (const file of files) {
+        const dead = validateFile(file);
+        allDead = allDead.concat(dead);
+    }
+    if (!allDead.length) {
+        console.log(`✓ No dead code references found (checked ${files.length} docs)`);
+        process.exit(0);
+    }
+    console.log(`\n⚠ Found ${allDead.length} dead reference(s) to non-existent code:\n`);
+    const byFile = groupByFile(allDead);
+    printDeadRefReport(byFile);
+    console.log('These docs reference code that no longer exists.');
+    console.log('Update the docs or remove stale references.\n');
+    process.exit(0);
+}
+if (import.meta.main) {
+    main().catch((error) => {
+        console.error('Error checking code references:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=check-refs.js.map

package/dist/esm/config/docs-lint/cli/check-stale.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+/**
+ * Stale Document Detection
+ *
+ * Finds documentation files with last_updated older than MAX_AGE_DAYS.
+ * Exits with code 1 if stale docs are found (fails CI).
+ */
+export {};
+//# sourceMappingURL=check-stale.d.ts.map

package/dist/esm/config/docs-lint/cli/check-stale.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+/**
+ * Stale Document Detection
+ *
+ * Finds documentation files with last_updated older than MAX_AGE_DAYS.
+ * Exits with code 1 if stale docs are found (fails CI).
+ */
+import matter from 'gray-matter';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { glob } from 'glob';
+const MAX_AGE_DAYS = 90;
+const DOCS_ROOT = process.cwd();
+const AGENT_GUIDE_PATH = '.agent/rules/agent-guide.md';
+/** Paths that are exempt from staleness checks */
+const EXEMPT_PATTERNS = [
+    'webpresso/blueprints/completed/',
+    'webpresso/blueprints/archived/',
+    'docs/evaluations/archive/',
+    'docs/research/', // Research papers are reference material
+    'docs/cookbook/', // Cookbook recipes rarely change
+];
+function isExempt(filePath) {
+    return EXEMPT_PATTERNS.some((pattern) => filePath.includes(pattern));
+}
+function parseDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'string') {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    return null;
+}
+function getDaysSince(date) {
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+/**
+ * Check a single file for staleness
+ */
+function checkFileForStaleness(file) {
+    try {
+        const content = readFileSync(file, 'utf-8');
+        const { data } = matter(content);
+        if (!data.last_updated)
+            return null;
+        const lastUpdated = parseDate(data.last_updated);
+        if (!lastUpdated)
+            return null;
+        const ageDays = getDaysSince(lastUpdated);
+        if (ageDays <= MAX_AGE_DAYS)
+            return null;
+        const dateStr = lastUpdated.toISOString().split('T')[0] ?? 'unknown';
+        return {
+            path: relative(DOCS_ROOT, file),
+            lastUpdated: dateStr,
+            ageDays,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function findStaleDocs() {
+    const files = await glob(['docs/**/*.md', 'CLAUDE.md', AGENT_GUIDE_PATH], {
+        cwd: DOCS_ROOT,
+        ignore: ['**/node_modules/**'],
+    });
+    const staleDocs = [];
+    for (const file of files) {
+        if (isExempt(file))
+            continue;
+        const staleDoc = checkFileForStaleness(file);
+        if (staleDoc) {
+            staleDocs.push(staleDoc);
+        }
+    }
+    return staleDocs.toSorted((a, b) => b.ageDays - a.ageDays);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const blockCritical = args.includes('--block-critical');
+    const staleDocs = await findStaleDocs();
+    if (!staleDocs.length) {
+        console.log(`✓ No stale documents found (threshold: ${MAX_AGE_DAYS} days)`);
+        process.exit(0);
+    }
+    const criticalStale = staleDocs.filter((d) => d.path === AGENT_GUIDE_PATH);
+    const normalStale = staleDocs.filter((d) => d.path !== AGENT_GUIDE_PATH);
+    if (blockCritical && criticalStale.length > 0) {
+        console.log(`\n❌ CRITICAL: agent-guide.md is stale (>${MAX_AGE_DAYS} days). Commit blocked.\n`);
+        for (const doc of criticalStale) {
+            console.log(`  ${doc.path}\n    └─ last_updated: ${doc.lastUpdated} (${doc.ageDays} days ago)`);
+        }
+        console.log('\nYou MUST update agent-guide.md to proceed.');
+        process.exit(1);
+    }
+    if (normalStale.length > 0) {
+        console.log(`\n⚠ Found ${normalStale.length} stale document(s) (>${MAX_AGE_DAYS} days old) - Consider updating:\n`);
+        for (const doc of normalStale) {
+            console.log(`  ${doc.path}`);
+            console.log(`    └─ last_updated: ${doc.lastUpdated} (${doc.ageDays} days ago)`);
+        }
+    }
+    // Always exit 0 unless critical blocked
+    process.exit(0);
+}
+if (import.meta.main) {
+    main().catch((error) => {
+        console.error('Error checking for stale docs:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=check-stale.js.map

package/dist/esm/config/docs-lint/cli/commands/migrate-command.d.ts

@@ -0,0 +1,22 @@
+import type { MigratorDeps } from '#config/docs-lint/cli/interfaces';
+export interface MigrateOptions {
+    files?: string[];
+    dryRun?: boolean;
+    backup?: boolean;
+    verbose?: boolean;
+    force?: boolean;
+}
+export declare class MigrateCommand {
+    private deps;
+    constructor(deps: MigratorDeps);
+    run(options: MigrateOptions): Promise<number>;
+    private getFilesToMigrate;
+    private migrateFile;
+    private createSkippedResult;
+    private extractExistingMetadata;
+    private handleDryRun;
+    private handleBackup;
+    private formatResults;
+}
+export declare function createMigrateCommand(deps?: MigratorDeps): MigrateCommand;
+//# sourceMappingURL=migrate-command.d.ts.map