@webpresso/agent-kit 0.21.0

package/dist/esm/audit/tech-debt.js

@@ -0,0 +1,107 @@
+/**
+ * `wp audit tech-debt` — validates tech-debt files against the schema.
+ *
+ * Checks:
+ * - Each file parses against the Zod schema (all required fields, valid enums)
+ * - Each file lives in the directory matching its `status` frontmatter
+ * - Critical severity items have weekly cadence (schema refinement)
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { techDebtFrontmatterSchema } from '#tech-debt/schema';
+const STATUS_DIRS = ['accepted', 'needs-remediation', 'monitoring', 'resolved'];
+function relativePath(root, filePath) {
+    return path.relative(root, filePath);
+}
+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();
+}
+/**
+ * Audit all tech-debt markdown files under `root`.
+ *
+ * The root should be the directory that contains the status subdirectories
+ * (accepted/, needs-remediation/, monitoring/, resolved/).
+ */
+export function auditTechDebt(root) {
+    const violations = [];
+    let checked = 0;
+    for (const statusDir of STATUS_DIRS) {
+        const dir = path.join(root, statusDir);
+        if (!existsSync(dir))
+            continue;
+        const files = walkMdFiles(dir);
+        for (const filePath of files) {
+            checked++;
+            const rel = relativePath(root, filePath);
+            let raw;
+            try {
+                raw = readFileSync(filePath, 'utf8');
+            }
+            catch (err) {
+                violations.push({
+                    file: rel,
+                    message: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            let data;
+            try {
+                const parsed = matter(raw);
+                data = parsed.data;
+            }
+            catch (err) {
+                violations.push({
+                    file: rel,
+                    message: `Cannot parse frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+            // Validate against the Zod schema
+            const result = techDebtFrontmatterSchema.safeParse(data);
+            if (!result.success) {
+                for (const issue of result.error.issues) {
+                    const fieldPath = issue.path.length > 0 ? ` (${issue.path.join('.')})` : '';
+                    violations.push({
+                        file: rel,
+                        message: `Schema validation failed${fieldPath}: ${issue.message}`,
+                    });
+                }
+                continue;
+            }
+            // Check: file lives in the directory matching its `status` field
+            const fileStatus = result.data.status;
+            if (fileStatus !== statusDir) {
+                violations.push({
+                    file: rel,
+                    message: `Status mismatch: frontmatter says '${fileStatus}' but file is in '${statusDir}/' directory`,
+                });
+            }
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: 'Tech-debt audit',
+        checked,
+        violations,
+    };
+}
+//# sourceMappingURL=tech-debt.js.map

package/dist/esm/audit/vision-doc.d.ts

@@ -0,0 +1,21 @@
+import { type RepoAuditResult } from './repo-guardrails.js';
+export interface VisionRequiredSection {
+    /** Human-readable label used in error messages. */
+    label: string;
+    /** Lowercase H2 heading texts that satisfy this section (case-insensitive match). */
+    synonyms: readonly string[];
+}
+export interface VisionOptions {
+    /** Path to VISION.md, relative to root. Default: `'VISION.md'`. */
+    visionPath?: string;
+    /** Maximum line count for the body (frontmatter excluded). Default: 100. */
+    maxLines?: number;
+    /** Maximum word count for the body. Default: 1500. */
+    maxWords?: number;
+    /** Required H2 sections. Each is satisfied if any synonym matches a present heading. */
+    requiredSections?: readonly VisionRequiredSection[];
+    /** Soft-warn (not error) if `last_updated` is older than this many days. Default: 365. 0 disables. */
+    staleAfterDays?: number;
+}
+export declare function auditVision(rootDirectory?: string, options?: VisionOptions): RepoAuditResult;
+//# sourceMappingURL=vision-doc.d.ts.map

package/dist/esm/audit/vision-doc.js

@@ -0,0 +1,136 @@
+/**
+ * `wp audit vision` — enforce VISION.md structure, length, and freshness.
+ *
+ * Every repo that runs `wp setup` should have a concise VISION.md at root that
+ * defines the project's purpose and boundaries. This audit gates structure
+ * (frontmatter + required H2 sections), length (lines + words), and warns on
+ * staleness. Composes into `wp audit quality` so it runs in consumers' CI by
+ * default.
+ *
+ * The companion scaffolder (`wp setup --with vision`) drops a starter file
+ * from `catalog/vision/VISION.md.tmpl`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseFrontmatter, } from './repo-guardrails.js';
+const DEFAULT_REQUIRED_SECTIONS = [
+    { label: 'Problem', synonyms: ['the problem', 'problem'] },
+    { label: 'North star', synonyms: ['north star', 'vision', 'goal'] },
+    {
+        label: 'Boundaries',
+        synonyms: ['boundaries', 'out of scope', 'non-goals', 'non goals', 'scope', 'in scope'],
+    },
+    { label: 'Principles', synonyms: ['design principles', 'principles'] },
+];
+const DEFAULT_MAX_LINES = 100;
+const DEFAULT_MAX_WORDS = 1500;
+const DEFAULT_STALE_AFTER_DAYS = 365;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+export function auditVision(rootDirectory = process.cwd(), options = {}) {
+    const root = resolve(rootDirectory);
+    const relativeName = options.visionPath ?? 'VISION.md';
+    const visionPath = resolve(root, relativeName);
+    const violations = [];
+    if (!existsSync(visionPath)) {
+        return {
+            ok: false,
+            title: 'VISION.md',
+            checked: 0,
+            violations: [
+                {
+                    file: relativeName,
+                    message: `${relativeName} is required at repo root — run \`wp setup --with vision\` to scaffold one.`,
+                },
+            ],
+        };
+    }
+    const content = readFileSync(visionPath, 'utf8');
+    const frontmatter = parseFrontmatter(content);
+    const body = stripFrontmatter(content);
+    const type = frontmatter.type;
+    if (type !== 'vision') {
+        violations.push({
+            file: relativeName,
+            message: type
+                ? `Frontmatter type must be 'vision' (got ${JSON.stringify(type)})`
+                : `Missing required frontmatter field: type (must be 'vision')`,
+        });
+    }
+    const lastUpdated = frontmatter.last_updated;
+    if (!lastUpdated) {
+        violations.push({
+            file: relativeName,
+            message: `Missing required frontmatter field: last_updated (YYYY-MM-DD)`,
+        });
+    }
+    else if (!ISO_DATE.test(lastUpdated) || Number.isNaN(Date.parse(lastUpdated))) {
+        violations.push({
+            file: relativeName,
+            message: `last_updated must be a YYYY-MM-DD date (got ${JSON.stringify(lastUpdated)})`,
+        });
+    }
+    else {
+        const staleAfter = options.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+        if (staleAfter > 0) {
+            const ageDays = Math.floor((Date.now() - Date.parse(lastUpdated)) / 86_400_000);
+            if (ageDays > staleAfter) {
+                console.warn(`[vision-warn] ${relativeName}: last_updated is ${ageDays} days old (>${staleAfter}). Consider refreshing.`);
+            }
+        }
+    }
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxWords = options.maxWords ?? DEFAULT_MAX_WORDS;
+    const bodyLines = body.split(/\r?\n/).length;
+    const bodyWords = body.split(/\s+/).filter((word) => word.length > 0).length;
+    if (bodyLines > maxLines) {
+        violations.push({
+            file: relativeName,
+            message: `Body is ${bodyLines} lines; cap is ${maxLines}. VISION.md must stay concise.`,
+        });
+    }
+    if (bodyWords > maxWords) {
+        violations.push({
+            file: relativeName,
+            message: `Body is ${bodyWords} words; cap is ${maxWords}. VISION.md must stay concise.`,
+        });
+    }
+    const firstHeading = /^#\s+(.+)$/m.exec(body);
+    if (!firstHeading) {
+        violations.push({
+            file: relativeName,
+            message: `Missing H1 (e.g. '# <name> Vision')`,
+        });
+    }
+    else if (!/vision/i.test(firstHeading[1] ?? '')) {
+        violations.push({
+            file: relativeName,
+            message: `H1 must contain 'Vision' (got ${JSON.stringify(firstHeading[1])})`,
+        });
+    }
+    const requiredSections = options.requiredSections ?? DEFAULT_REQUIRED_SECTIONS;
+    const presentH2s = new Set([...body.matchAll(/^##\s+(.+?)\s*$/gm)].map((match) => (match[1] ?? '').trim().toLowerCase()));
+    for (const section of requiredSections) {
+        const matched = section.synonyms.some((synonym) => presentH2s.has(synonym.toLowerCase()));
+        if (!matched) {
+            violations.push({
+                file: relativeName,
+                message: `Missing required section: '## ${section.label}' (or one of: ${section.synonyms.join(', ')})`,
+            });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: 'VISION.md',
+        checked: 1,
+        violations,
+    };
+}
+function stripFrontmatter(markdown) {
+    if (!markdown.startsWith('---'))
+        return markdown;
+    const end = markdown.indexOf('\n---', 3);
+    if (end === -1)
+        return markdown;
+    return markdown.slice(end + 4).replace(/^\s*\n/, '');
+}
+//# sourceMappingURL=vision-doc.js.map

package/dist/esm/blueprint/aggregate.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Read-only aggregate helpers across selected blueprint projects (Task 3.1).
+ *
+ * Fans out read-only queries to N project projection DBs (resolved by Task 1.2's
+ * `resolveBlueprintProjects`), checks freshness (Task 1.3 — `checkFreshness`),
+ * tags every row with its source `project_id`, and merges results in memory.
+ *
+ * Design notes:
+ *
+ * - **No global projection DB.** Each project owns a worktree-scoped SQLite
+ *   file resolved by Task 1.1's `resolveBlueprintProjectionDbPath`. This helper
+ *   opens those DBs one at a time and unions the rows in JS — no schema
+ *   change, no parallel projection.
+ *
+ * - **Failure isolation.** A broken/missing/stale DB for one project records a
+ *   structured failure entry and continues. The aggregate call never throws
+ *   for per-project errors — callers see `ok: true` with `failures` populated.
+ *
+ * - **Stale projection → `next_action: 'reingest_project'`** (F11/R9). The
+ *   offending `project_id` is included in the failure entry; the caller can
+ *   re-ingest that one project without disturbing the others.
+ *
+ * - **Duplicate slugs.** When two projects expose the same blueprint slug,
+ *   both rows appear in `rows` (tagged by `project_id`) and the slug is also
+ *   listed under `duplicate_slugs`. Callers MUST disambiguate; this helper
+ *   refuses to silently pick one.
+ *
+ * - **F15 — read-only target shape.** `ReadTarget = { project_id?, scope? }`.
+ *   It does NOT extend the `MutationTarget` zod base. Including a mutation
+ *   field (`worktree_path`, etc.) at parse time is a type error. Mutation
+ *   tools must not share this shape.
+ */
+import type { Database } from '#db/sqlite.js';
+import { z } from 'zod';
+import { type NextAction } from './next-action.js';
+import { type BlueprintProjectRef, type ResolveBlueprintProjectsOptions } from './projects.js';
+export declare const READ_TARGET_SCOPES: readonly ["current", "roots", "workspace", "all"];
+export type ReadTargetScope = (typeof READ_TARGET_SCOPES)[number];
+/**
+ * Input shape for read-only aggregate calls (F15).
+ *
+ * Read-only paths accept `scope` (per-project fan-out) and/or an explicit
+ * `project_id`. They MUST NOT accept a mutation-target field like
+ * `worktree_path` — those belong on `MutationTarget` (Task 2.2).
+ *
+ * `.strict()` rejects unknown keys at zod parse time so callers cannot smuggle
+ * a `worktree_path` or similar through this surface.
+ */
+export declare const readTargetSchema: z.ZodObject<{
+    project_id: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        current: "current";
+        roots: "roots";
+        workspace: "workspace";
+    }>>;
+}, z.core.$strict>;
+export type ReadTarget = z.infer<typeof readTargetSchema>;
+/**
+ * Per-project failure record. The aggregate call captures one of these
+ * instead of throwing when a project DB cannot be read.
+ */
+export interface AggregateFailure {
+    readonly project_id: string;
+    readonly worktree_path: string;
+    readonly next_action: NextAction;
+}
+/**
+ * Row tagging contract: every row returned from an aggregate call carries the
+ * source `project_id`. The reader callback never sees a tagged row; this
+ * module decorates after the read completes.
+ */
+export type TaggedRow<TRow> = TRow & {
+    readonly project_id: string;
+};
+export interface AggregateResult<TRow> {
+    readonly rows: ReadonlyArray<TaggedRow<TRow>>;
+    /**
+     * Slugs that appeared in more than one project's rows. Surfaced so callers
+     * can refuse to act on an ambiguous slug. Empty when no row carries a `slug`
+     * field or when no duplicates exist.
+     */
+    readonly duplicate_slugs: ReadonlyArray<string>;
+    readonly failures: ReadonlyArray<AggregateFailure>;
+    readonly projects: ReadonlyArray<{
+        readonly project_id: string;
+        readonly worktree_path: string;
+    }>;
+}
+export interface ProjectReaderContext {
+    readonly project: BlueprintProjectRef;
+    readonly db: Database;
+}
+/**
+ * Caller-supplied read fn. Runs against one already-open DB and returns
+ * un-tagged rows. The aggregate helper handles tagging, merging, and
+ * disambiguation.
+ *
+ * MUST be read-only. There is no write transaction or lock acquired here.
+ */
+export type ProjectReader<TRow> = (ctx: ProjectReaderContext) => ReadonlyArray<TRow>;
+export interface AggregateBlueprintRowsOptions<TRow> {
+    readonly target: ReadTarget;
+    readonly read: ProjectReader<TRow>;
+    /**
+     * Injectable project resolver options — same surface as Task 1.2. Tests
+     * pass `workspaceRepos`, `rootsProvider`, `git`, etc., to avoid spawning
+     * real git or touching the filesystem outside a temp dir.
+     */
+    readonly resolveOptions?: ResolveBlueprintProjectsOptions;
+    /**
+     * Hook for tests to override how each project's DB is opened. Production
+     * code uses the default `openDb` from `#db/connection.js`.
+     */
+    readonly openDbFor?: (project: BlueprintProjectRef) => {
+        readonly db: Database;
+        readonly close: () => void;
+    };
+}
+/**
+ * Run a read-only reader against every selected project and merge the rows.
+ *
+ * Behaviour summary (acceptance reference):
+ *
+ *  - **Tagged rows:** every row in `rows` carries `project_id` of the source
+ *    project. The reader callback never sees this field.
+ *  - **Failure isolation:** a broken DB, a stale projection, or a reader
+ *    exception records a `failures[]` entry and the aggregate call still
+ *    returns `ok`. Other projects continue.
+ *  - **Stale projection:** returns `next_action: 'reingest_project'` with the
+ *    offending `project_id` in `failures[]`. Does NOT throw.
+ *  - **Scope:** `'current' | 'roots' | 'workspace' | 'all'` selects which
+ *    resolved projects to fan out across. `'current'` is the default when
+ *    neither `scope` nor `project_id` is provided.
+ *  - **Duplicate slugs:** rows with a string `slug` field are checked; any
+ *    slug appearing in more than one project is surfaced in
+ *    `duplicate_slugs[]`. Callers MUST refuse to silently pick one.
+ *  - **Read-only:** the input schema (`readTargetSchema`) has no mutation
+ *    fields; `.strict()` rejects extras at zod parse time.
+ *
+ * The reader is given an already-open DB and is expected to issue ordinary
+ * read queries (e.g. the existing query templates under `src/blueprint/db/`).
+ * Connection lifecycle is owned by the aggregate helper.
+ */
+export declare function aggregateBlueprintRows<TRow extends Record<string, unknown>>(options: AggregateBlueprintRowsOptions<TRow>): Promise<AggregateResult<TRow>>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/esm/blueprint/aggregate.js

@@ -0,0 +1,217 @@
+/**
+ * Read-only aggregate helpers across selected blueprint projects (Task 3.1).
+ *
+ * Fans out read-only queries to N project projection DBs (resolved by Task 1.2's
+ * `resolveBlueprintProjects`), checks freshness (Task 1.3 — `checkFreshness`),
+ * tags every row with its source `project_id`, and merges results in memory.
+ *
+ * Design notes:
+ *
+ * - **No global projection DB.** Each project owns a worktree-scoped SQLite
+ *   file resolved by Task 1.1's `resolveBlueprintProjectionDbPath`. This helper
+ *   opens those DBs one at a time and unions the rows in JS — no schema
+ *   change, no parallel projection.
+ *
+ * - **Failure isolation.** A broken/missing/stale DB for one project records a
+ *   structured failure entry and continues. The aggregate call never throws
+ *   for per-project errors — callers see `ok: true` with `failures` populated.
+ *
+ * - **Stale projection → `next_action: 'reingest_project'`** (F11/R9). The
+ *   offending `project_id` is included in the failure entry; the caller can
+ *   re-ingest that one project without disturbing the others.
+ *
+ * - **Duplicate slugs.** When two projects expose the same blueprint slug,
+ *   both rows appear in `rows` (tagged by `project_id`) and the slug is also
+ *   listed under `duplicate_slugs`. Callers MUST disambiguate; this helper
+ *   refuses to silently pick one.
+ *
+ * - **F15 — read-only target shape.** `ReadTarget = { project_id?, scope? }`.
+ *   It does NOT extend the `MutationTarget` zod base. Including a mutation
+ *   field (`worktree_path`, etc.) at parse time is a type error. Mutation
+ *   tools must not share this shape.
+ */
+import { z } from 'zod';
+import { openDb } from '#db/connection.js';
+import { checkFreshness } from './freshness.js';
+import { makeNextAction } from './next-action.js';
+import { resolveBlueprintProjects, } from './projects.js';
+// ---------------------------------------------------------------------------
+// Public types — ReadTarget (F15: distinct from MutationTarget)
+// ---------------------------------------------------------------------------
+export const READ_TARGET_SCOPES = ['current', 'roots', 'workspace', 'all'];
+/**
+ * Input shape for read-only aggregate calls (F15).
+ *
+ * Read-only paths accept `scope` (per-project fan-out) and/or an explicit
+ * `project_id`. They MUST NOT accept a mutation-target field like
+ * `worktree_path` — those belong on `MutationTarget` (Task 2.2).
+ *
+ * `.strict()` rejects unknown keys at zod parse time so callers cannot smuggle
+ * a `worktree_path` or similar through this surface.
+ */
+export const readTargetSchema = z
+    .object({
+    project_id: z.string().min(1).optional(),
+    scope: z.enum(READ_TARGET_SCOPES).optional(),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Internals — scope filter
+// ---------------------------------------------------------------------------
+/**
+ * Apply the read-target filter to the resolved project list.
+ *
+ * - `project_id` is the highest-precedence filter; when present, exactly one
+ *   project is selected (or zero if no match).
+ * - `scope` selects a band: `'current'` keeps only the current project (the
+ *   first in source order is the current project per Task 1.2 priority);
+ *   `'roots'` keeps MCP-root projects; `'workspace'` keeps workspace-config
+ *   and git-worktree projects; `'all'` keeps everything resolved.
+ * - When neither is set, the safe default is `'current'`.
+ */
+function selectProjects(projects, target) {
+    if (target.project_id !== undefined) {
+        return projects.filter((p) => p.project_id === target.project_id);
+    }
+    const scope = target.scope ?? 'current';
+    if (scope === 'all')
+        return [...projects];
+    if (scope === 'current') {
+        const current = projects.find((p) => p.source === 'current');
+        return current ? [current] : projects.length > 0 && projects[0] ? [projects[0]] : [];
+    }
+    if (scope === 'roots') {
+        return projects.filter((p) => p.source === 'mcp_roots');
+    }
+    // scope === 'workspace'
+    return projects.filter((p) => p.source === 'workspace_config' || p.source === 'git_worktree');
+}
+// ---------------------------------------------------------------------------
+// Internals — per-project read with failure isolation
+// ---------------------------------------------------------------------------
+function defaultOpen(project) {
+    return openDb(project.db_path);
+}
+async function runOneProject(project, read, openDbFor) {
+    // Freshness gate (Task 1.3 / F11) — refuse stale or missing projections with
+    // a structured hint. Read-only aggregate calls must not auto-rebuild DBs:
+    // callers need an explicit per-project failure they can surface or repair.
+    const fresh = checkFreshness({
+        worktree_path: project.worktree_path,
+        db_path: project.db_path,
+    });
+    if (!fresh.ok) {
+        return {
+            project,
+            rows: [],
+            failure: {
+                project_id: project.project_id,
+                worktree_path: project.worktree_path,
+                next_action: fresh.next_action,
+            },
+        };
+    }
+    let conn = null;
+    try {
+        conn = openDbFor(project);
+        const rows = read({ project, db: conn.db });
+        return { project, rows, failure: null };
+    }
+    catch (err) {
+        return {
+            project,
+            rows: [],
+            failure: {
+                project_id: project.project_id,
+                worktree_path: project.worktree_path,
+                next_action: makeNextAction('reingest_project', `Failed to read projection at ${project.db_path}: ${stringifyError(err)}`),
+            },
+        };
+    }
+    finally {
+        try {
+            conn?.close();
+        }
+        catch {
+            // Best-effort close; an already-failed read should not mask itself.
+        }
+    }
+}
+function stringifyError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function collectDuplicateSlugs(rows) {
+    const seen = new Map();
+    for (const row of rows) {
+        const maybe = row;
+        const slug = maybe.slug;
+        if (typeof slug !== 'string' || slug.length === 0)
+            continue;
+        seen.set(slug, (seen.get(slug) ?? 0) + 1);
+    }
+    const dups = [];
+    for (const [slug, count] of seen) {
+        if (count > 1)
+            dups.push(slug);
+    }
+    dups.sort();
+    return dups;
+}
+// ---------------------------------------------------------------------------
+// Public API — the one aggregate primitive
+// ---------------------------------------------------------------------------
+/**
+ * Run a read-only reader against every selected project and merge the rows.
+ *
+ * Behaviour summary (acceptance reference):
+ *
+ *  - **Tagged rows:** every row in `rows` carries `project_id` of the source
+ *    project. The reader callback never sees this field.
+ *  - **Failure isolation:** a broken DB, a stale projection, or a reader
+ *    exception records a `failures[]` entry and the aggregate call still
+ *    returns `ok`. Other projects continue.
+ *  - **Stale projection:** returns `next_action: 'reingest_project'` with the
+ *    offending `project_id` in `failures[]`. Does NOT throw.
+ *  - **Scope:** `'current' | 'roots' | 'workspace' | 'all'` selects which
+ *    resolved projects to fan out across. `'current'` is the default when
+ *    neither `scope` nor `project_id` is provided.
+ *  - **Duplicate slugs:** rows with a string `slug` field are checked; any
+ *    slug appearing in more than one project is surfaced in
+ *    `duplicate_slugs[]`. Callers MUST refuse to silently pick one.
+ *  - **Read-only:** the input schema (`readTargetSchema`) has no mutation
+ *    fields; `.strict()` rejects extras at zod parse time.
+ *
+ * The reader is given an already-open DB and is expected to issue ordinary
+ * read queries (e.g. the existing query templates under `src/blueprint/db/`).
+ * Connection lifecycle is owned by the aggregate helper.
+ */
+export async function aggregateBlueprintRows(options) {
+    // Reject mutation-shaped inputs at the boundary.
+    const parsedTarget = readTargetSchema.parse(options.target);
+    const projects = await resolveBlueprintProjects(options.resolveOptions ?? {});
+    const selected = selectProjects(projects, parsedTarget);
+    const openDbFor = options.openDbFor ?? defaultOpen;
+    const merged = [];
+    const failures = [];
+    const visited = [];
+    for (const project of selected) {
+        visited.push({ project_id: project.project_id, worktree_path: project.worktree_path });
+        const outcome = await runOneProject(project, options.read, openDbFor);
+        if (outcome.failure !== null) {
+            failures.push(outcome.failure);
+            continue;
+        }
+        for (const row of outcome.rows) {
+            merged.push({ ...row, project_id: project.project_id });
+        }
+    }
+    return {
+        rows: merged,
+        duplicate_slugs: collectDuplicateSlugs(merged),
+        failures,
+        projects: visited,
+    };
+}
+//# sourceMappingURL=aggregate.js.map