@webpresso/agent-kit 0.21.0

package/dist/esm/audit/audit-tph.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+/**
+ * Audit: Testing Philosophy Helper (TPH)
+ *
+ * Detects testing philosophy violations that GritQL patterns cannot express:
+ * - Files with >3 vi.mock() calls (over-mocking)
+ * - .test.ts files that mock internal @myorg/* packages (should be .integration.test.ts)
+ *
+ * GritQL handles: toBeTruthy/toBeFalsy, toBeDefined/toBeUndefined, bare toHaveBeenCalled,
+ *                 vi.mock('@myorg/*') detection.
+ *
+ * Usage:
+ *   just audit-tph
+ *   bun apps/scripts/src/audit/audit-tph.ts [--max-mocks N]
+ */
+import { runTphAudit } from './audit-tph-runner.js';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let maxMocks;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === '--max-mocks' && next) {
+            maxMocks = Number.parseInt(next, 10);
+            i++;
+        }
+    }
+    return { maxMocks };
+}
+if (import.meta.main) {
+    const { maxMocks } = parseArgs();
+    const root = process.cwd();
+    runTphAudit(root, maxMocks !== undefined ? { maxMocks } : undefined).catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=audit-tph.js.map

package/dist/esm/audit/blueprint-db-consistency.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `wp audit blueprint-db-consistency` — SQL-backed consistency check between
+ * the SQLite blueprints DB and the filesystem.
+ *
+ * Alpha gate: only runs meaningful checks when WP_USE_SQL_AUDITS=1.
+ * Without the flag returns a disabled notice (pass: true).
+ *
+ * Checks (when enabled):
+ * 1. Every `blueprints` row's `file_path` actually exists on disk.
+ * 2. Every blueprint `_overview.md` on disk has a corresponding DB row.
+ * 3. `content_hash` in DB matches the current SHA-256 of the file content.
+ */
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditBlueprintDbConsistency(cwd: string): Promise<RepoAuditResult>;
+//# sourceMappingURL=blueprint-db-consistency.d.ts.map

package/dist/esm/audit/blueprint-db-consistency.js

@@ -0,0 +1,109 @@
+/**
+ * `wp audit blueprint-db-consistency` — SQL-backed consistency check between
+ * the SQLite blueprints DB and the filesystem.
+ *
+ * Alpha gate: only runs meaningful checks when WP_USE_SQL_AUDITS=1.
+ * Without the flag returns a disabled notice (pass: true).
+ *
+ * Checks (when enabled):
+ * 1. Every `blueprints` row's `file_path` actually exists on disk.
+ * 2. Every blueprint `_overview.md` on disk has a corresponding DB row.
+ * 3. `content_hash` in DB matches the current SHA-256 of the file content.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { glob } from 'glob';
+const DB_PATH = path.join('.agent', '.blueprints.db');
+const _DISABLED_RESULT = {
+    ok: true,
+    title: 'Blueprint DB consistency (SQL)',
+    checked: 0,
+    violations: [],
+    // message is not part of RepoAuditResult — surface it in the title instead
+};
+function computeSha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+export async function auditBlueprintDbConsistency(cwd) {
+    if (!process.env['WP_USE_SQL_AUDITS']) {
+        return {
+            ok: true,
+            title: 'Blueprint DB consistency (SQL) — disabled (set WP_USE_SQL_AUDITS=1)',
+            checked: 0,
+            violations: [],
+        };
+    }
+    const dbFile = path.join(cwd, DB_PATH);
+    if (!existsSync(dbFile)) {
+        return {
+            ok: true,
+            title: 'Blueprint DB consistency (SQL)',
+            checked: 0,
+            violations: [],
+        };
+    }
+    const { Database } = await import('#db/sqlite.js');
+    const db = new Database(dbFile, { readonly: true });
+    const violations = [];
+    try {
+        // -----------------------------------------------------------------------
+        // 1 + 3: rows in DB → verify file exists and hash matches
+        // -----------------------------------------------------------------------
+        const rows = db
+            .prepare('SELECT slug, file_path, content_hash FROM blueprints')
+            .all();
+        let checked = rows.length;
+        for (const row of rows) {
+            const absPath = path.isAbsolute(row.file_path) ? row.file_path : path.join(cwd, row.file_path);
+            if (!existsSync(absPath)) {
+                violations.push({
+                    file: row.file_path,
+                    message: `Blueprint row for slug '${row.slug}' points to a file that no longer exists on disk`,
+                });
+                continue;
+            }
+            const content = readFileSync(absPath, 'utf8');
+            const actualHash = computeSha256(content);
+            if (actualHash !== row.content_hash) {
+                violations.push({
+                    file: row.file_path,
+                    message: `content_hash mismatch for slug '${row.slug}': DB has ${row.content_hash.slice(0, 8)}… but file hashes to ${actualHash.slice(0, 8)}…`,
+                });
+            }
+        }
+        // -----------------------------------------------------------------------
+        // 2: files on disk → verify each has a DB row
+        // -----------------------------------------------------------------------
+        const dbPaths = new Set(rows.map((r) => r.file_path));
+        // Blueprints follow blueprints/<status>/<slug>/_overview.md convention
+        const overviewFiles = await glob('blueprints/**/_overview.md', {
+            cwd,
+            absolute: false,
+            ignore: ['node_modules/**'],
+        });
+        checked += overviewFiles.length;
+        for (const rel of overviewFiles) {
+            const normalised = rel.replace(/\\/g, '/');
+            // DB may store absolute or repo-relative paths — check both forms
+            const abs = path.join(cwd, rel);
+            const hasRow = dbPaths.has(normalised) || dbPaths.has(abs);
+            if (!hasRow) {
+                violations.push({
+                    file: normalised,
+                    message: `Blueprint file exists on disk but has no corresponding row in the DB (run 'wp ingest' to update)`,
+                });
+            }
+        }
+        return {
+            ok: violations.length === 0,
+            title: 'Blueprint DB consistency (SQL)',
+            checked,
+            violations,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=blueprint-db-consistency.js.map

package/dist/esm/audit/blueprint-lifecycle-sql.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `wp audit blueprint-lifecycle-sql` — SQL-backed rewrite of the existing
+ * blueprint-lifecycle audit.
+ *
+ * Uses the SQLite replica as the primary source when the DB file exists.
+ * Falls back to the markdown-based audit when the DB has not been built yet.
+ *
+ * SQL checks (when DB exists):
+ * 1. Blueprints with status='in-progress' that have 0 tasks (invalid).
+ * 2. Blueprints whose `status` column doesn't match the directory segment
+ *    derived from `file_path` (e.g. stored in completed/ but status=in-progress).
+ * 3. Tasks in state 'in-progress' whose dependencies are not all done.
+ * 4. Blueprints with progress_pct < 100 but status='completed'.
+ */
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditBlueprintLifecycleSql(cwd: string): Promise<RepoAuditResult>;
+//# sourceMappingURL=blueprint-lifecycle-sql.d.ts.map

package/dist/esm/audit/blueprint-lifecycle-sql.js

@@ -0,0 +1,136 @@
+/**
+ * `wp audit blueprint-lifecycle-sql` — SQL-backed rewrite of the existing
+ * blueprint-lifecycle audit.
+ *
+ * Uses the SQLite replica as the primary source when the DB file exists.
+ * Falls back to the markdown-based audit when the DB has not been built yet.
+ *
+ * SQL checks (when DB exists):
+ * 1. Blueprints with status='in-progress' that have 0 tasks (invalid).
+ * 2. Blueprints whose `status` column doesn't match the directory segment
+ *    derived from `file_path` (e.g. stored in completed/ but status=in-progress).
+ * 3. Tasks in state 'in-progress' whose dependencies are not all done.
+ * 4. Blueprints with progress_pct < 100 but status='completed'.
+ */
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { migrateLegacyAgentDb } from '#db/legacy-migration.js';
+import { resolveBlueprintProjectionDbPath } from '#db/paths.js';
+// Legacy fallback path — kept for the brief window where a migration may have
+// just-happened (Task 1.1 / F12 / R10 / E12). Worktree-scoped path is canonical.
+const LEGACY_DB_PATH = path.join('.agent', '.blueprints.db');
+export async function auditBlueprintLifecycleSql(cwd) {
+    // F12/R10/E12: trigger one-shot migration before resolving the DB so a stray
+    // legacy file is moved (and gone) before we count rows. After this call the
+    // canonical worktree-scoped path is the single source of truth.
+    migrateLegacyAgentDb(cwd);
+    // Prefer the canonical worktree-scoped path. If the migration failed because
+    // the destination already existed, the warning is already logged; we trust
+    // the canonical DB and never read the legacy file in addition, which would
+    // double-count rows.
+    let dbFile;
+    try {
+        dbFile = resolveBlueprintProjectionDbPath(cwd);
+    }
+    catch {
+        dbFile = path.join(cwd, LEGACY_DB_PATH);
+    }
+    if (!existsSync(dbFile)) {
+        // DB not yet built — fall back to markdown-based audit
+        const { auditBlueprintLifecycle } = await import('./repo-guardrails.js');
+        return auditBlueprintLifecycle(cwd);
+    }
+    const { Database } = await import('#db/sqlite.js');
+    const db = new Database(dbFile, { readonly: true });
+    const violations = [];
+    let checked = 0;
+    try {
+        // -----------------------------------------------------------------------
+        // 1. in-progress blueprints with 0 tasks
+        // -----------------------------------------------------------------------
+        const inProgressNoTasks = db
+            .prepare(`SELECT b.slug, b.file_path
+         FROM blueprints b
+         WHERE b.status = 'in-progress'
+           AND NOT EXISTS (
+             SELECT 1 FROM tasks t WHERE t.blueprint_slug = b.slug
+           )`)
+            .all();
+        checked += inProgressNoTasks.length;
+        for (const row of inProgressNoTasks) {
+            violations.push({
+                file: row.file_path,
+                message: `Blueprint '${row.slug}' is in-progress but has 0 tasks — in-progress blueprints must have at least one task`,
+            });
+        }
+        // -----------------------------------------------------------------------
+        // 2. status/directory mismatch
+        //    Derive the directory segment from the file_path and compare to status.
+        //    Blueprint file_path convention: blueprints/<status>/<slug>/_overview.md
+        // -----------------------------------------------------------------------
+        const allBlueprints = db
+            .prepare('SELECT slug, status, file_path, progress_pct FROM blueprints')
+            .all();
+        checked += allBlueprints.length;
+        for (const row of allBlueprints) {
+            // Derive directory status from the path: second segment after 'blueprints/'
+            const segments = row.file_path.replace(/\\/g, '/').split('/');
+            const blueprintsIdx = segments.lastIndexOf('blueprints');
+            const dirStatus = blueprintsIdx >= 0 ? segments[blueprintsIdx + 1] : null;
+            if (dirStatus !== null && dirStatus !== row.status) {
+                violations.push({
+                    file: row.file_path,
+                    message: `Blueprint '${row.slug}' has status='${row.status}' but lives in the '${dirStatus}/' directory`,
+                });
+            }
+        }
+        // -----------------------------------------------------------------------
+        // 3. Tasks in-progress with unsatisfied dependencies
+        // -----------------------------------------------------------------------
+        const blockedInProgress = db
+            .prepare(`SELECT t.id, t.task_id, t.blueprint_slug, t.status
+         FROM tasks t
+         WHERE t.status = 'in-progress'
+           AND EXISTS (
+             SELECT 1
+             FROM task_dependencies td
+             JOIN tasks dep ON dep.id = td.depends_on_task_id
+             WHERE td.task_id = t.id
+               AND dep.status != 'done'
+           )`)
+            .all();
+        checked += blockedInProgress.length;
+        for (const row of blockedInProgress) {
+            violations.push({
+                message: `Task '${row.task_id}' in blueprint '${row.blueprint_slug}' is in-progress but has unmet dependencies`,
+            });
+        }
+        // -----------------------------------------------------------------------
+        // 4. Completed blueprints with progress_pct < 100
+        // -----------------------------------------------------------------------
+        const incompleteCompleted = db
+            .prepare(`SELECT slug, file_path, progress_pct
+         FROM blueprints
+         WHERE status = 'completed'
+           AND progress_pct IS NOT NULL
+           AND progress_pct < 100`)
+            .all();
+        checked += incompleteCompleted.length;
+        for (const row of incompleteCompleted) {
+            violations.push({
+                file: row.file_path,
+                message: `Blueprint '${row.slug}' is marked completed but progress_pct is ${row.progress_pct}% (expected 100)`,
+            });
+        }
+        return {
+            ok: violations.length === 0,
+            title: 'Blueprint lifecycle (SQL)',
+            checked,
+            violations,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=blueprint-lifecycle-sql.js.map

package/dist/esm/audit/broken-refs.d.ts

@@ -0,0 +1,26 @@
+import type { RepoAuditViolation } from './repo-guardrails.js';
+export interface BrokenRefViolation extends RepoAuditViolation {
+    file: string;
+    link: string;
+    message: string;
+}
+export interface BrokenRefsResult {
+    violations: BrokenRefViolation[];
+    checked: number;
+    pass: boolean;
+}
+export interface BrokenRefsOptions {
+    staged?: boolean;
+}
+/**
+ * Audit broken relative links in agent markdown files.
+ */
+export declare function auditBrokenRefs(cwd: string, options?: BrokenRefsOptions): BrokenRefsResult;
+/**
+ * Adapter to return a RepoAuditResult shape for registry integration.
+ */
+export declare function auditBrokenRefsAsRepoResult(cwd: string, options?: BrokenRefsOptions): ReturnType<typeof auditBrokenRefs> & {
+    ok: boolean;
+    title: string;
+};
+//# sourceMappingURL=broken-refs.d.ts.map

package/dist/esm/audit/broken-refs.js

@@ -0,0 +1,181 @@
+/**
+ * `wp audit broken-refs` — checks for unresolved relative links in agent
+ * markdown files.
+ *
+ * Walks:
+ *   - `.agent/**\/*.md`
+ *   - `AGENTS.md` (repo root)
+ *   - `CLAUDE.md` (repo root)
+ *
+ * Skips refs to generated paths (`.claude/rules/`, `.claude/skills/`,
+ * `.agents/skills/`, etc.)
+ * since those are gitignored generated outputs.
+ *
+ * Uses `remark` + `remark-validate-links` to find unresolved relative links.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Patterns for generated/gitignored output paths — these refs are skipped.
+ */
+const GENERATED_PATH_PATTERNS = [
+    /^\.claude\/rules\//,
+    /^\.claude\/skills\//,
+    /^\.agents\/skills\//,
+    /^\.cursor\/rules\//,
+    /^\.gemini\/commands\//,
+    /^\.windsurf\/skills\//,
+    /^\.opencode\/commands\//,
+    /^node_modules\//,
+];
+function isGeneratedRef(ref) {
+    const normalized = ref.replace(/^\//, '');
+    return GENERATED_PATH_PATTERNS.some((pat) => pat.test(normalized));
+}
+function walkMdFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...walkMdFiles(fullPath));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                files.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return files.sort();
+}
+function getStagedFiles(cwd) {
+    try {
+        const output = execSync('git diff --staged --name-only', { cwd, encoding: 'utf8' });
+        const files = new Set(output
+            .split('\n')
+            .map((f) => f.trim())
+            .filter((f) => f.length > 0)
+            .map((f) => path.resolve(cwd, f)));
+        return files;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect relative link targets from markdown content using a simple regex
+ * parser. We avoid loading remark dynamically in tests by keeping this
+ * light-weight; the full remark pipeline is used in `checkFileWithRemark`.
+ *
+ * Returns array of { link, line } objects.
+ */
+function extractRelativeLinks(content) {
+    const results = [];
+    // Match markdown links: [text](href) and ![alt](src) — only relative hrefs
+    const linkRe = /!?\[(?:[^\]]*)\]\(([^)]+)\)/g;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        let m;
+        const localRe = new RegExp(linkRe.source, 'g');
+        while ((m = localRe.exec(line)) !== null) {
+            const href = m[1]?.trim() ?? '';
+            // Skip absolute URLs, anchors-only, and mailto
+            if (href.startsWith('http://') ||
+                href.startsWith('https://') ||
+                href.startsWith('#') ||
+                href.startsWith('mailto:')) {
+                continue;
+            }
+            results.push({ link: href, line: i + 1 });
+        }
+    }
+    return results;
+}
+/**
+ * Check if a relative link resolves to an existing file from the given source file's directory.
+ */
+function isLinkResolvable(sourceFile, link, repoRoot) {
+    // Strip fragment (#anchor) from link
+    const linkWithoutFragment = link.split('#')[0] ?? '';
+    if (linkWithoutFragment === '')
+        return true; // anchor-only within same file
+    const sourceDir = path.dirname(sourceFile);
+    const resolved = path.resolve(sourceDir, linkWithoutFragment);
+    // Must be within repo root
+    const rel = path.relative(repoRoot, resolved);
+    if (rel.startsWith('..'))
+        return true; // outside repo — skip
+    if (isGeneratedRef(rel))
+        return true;
+    return existsSync(resolved);
+}
+/**
+ * Audit broken relative links in agent markdown files.
+ */
+export function auditBrokenRefs(cwd, options = {}) {
+    // Collect candidate files
+    const agentDir = path.join(cwd, '.agent');
+    const candidateFiles = [
+        ...walkMdFiles(agentDir),
+        path.join(cwd, 'AGENTS.md'),
+        path.join(cwd, 'CLAUDE.md'),
+    ].filter((f) => existsSync(f));
+    let stagedFiles = null;
+    if (options.staged) {
+        stagedFiles = getStagedFiles(cwd);
+    }
+    const violations = [];
+    let checked = 0;
+    for (const filePath of candidateFiles) {
+        // In staged mode, skip files not in the staged set
+        if (stagedFiles !== null) {
+            const absPath = path.resolve(cwd, filePath);
+            if (!stagedFiles.has(absPath))
+                continue;
+        }
+        let content;
+        try {
+            content = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        checked++;
+        const relPath = path.relative(cwd, filePath);
+        const links = extractRelativeLinks(content);
+        for (const { link, line } of links) {
+            if (isGeneratedRef(link))
+                continue;
+            if (!isLinkResolvable(filePath, link, cwd)) {
+                violations.push({
+                    file: relPath,
+                    link,
+                    message: `Unresolved relative link at line ${line}: ${link}`,
+                });
+            }
+        }
+    }
+    return {
+        violations,
+        checked,
+        pass: violations.length === 0,
+    };
+}
+/**
+ * Adapter to return a RepoAuditResult shape for registry integration.
+ */
+export function auditBrokenRefsAsRepoResult(cwd, options = {}) {
+    const result = auditBrokenRefs(cwd, options);
+    return {
+        ...result,
+        ok: result.pass,
+        title: 'Broken refs audit',
+    };
+}
+//# sourceMappingURL=broken-refs.js.map

package/dist/esm/audit/bucket-boundary.d.ts

@@ -0,0 +1,21 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export type BucketName = 'platform' | 'tenant-orchestration' | 'tenant-artifacts';
+export interface BucketViolation {
+    package: string;
+    rule: 'code-level' | 'wrangler-binding';
+    description: string;
+    severity: 'error' | 'warning';
+}
+export interface BucketBoundaryOptions {
+    /** Restrict to packages touched in git diff --name-only origin/main */
+    changedOnly?: boolean;
+    /** Zero-tolerance: allowlist entries become errors too */
+    strict?: boolean;
+    /** Monorepo root (defaults to cwd) */
+    root?: string;
+}
+/**
+ * Main audit entry point.
+ */
+export declare function auditBucketBoundary(root: string, options?: BucketBoundaryOptions): Promise<RepoAuditResult>;
+//# sourceMappingURL=bucket-boundary.d.ts.map