@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/compose/compose.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { type ResolvedBlockRegistry } from "./registry-resolve.js";
+export declare const composeInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    profile: z.ZodLiteral<"admin-crud">;
+    kind: z.ZodEnum<{
+        detail: "detail";
+        form: "form";
+        list: "list";
+    }>;
+    spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    profile: z.ZodLiteral<"ops-report">;
+    spec: z.ZodUnknown;
+}, z.core.$strict>], "profile">;
+export type ComposeInput = z.infer<typeof composeInputSchema>;
+export interface ComposeDiagnostic {
+    readonly path: string;
+    readonly message: string;
+}
+export interface ComposeResult {
+    readonly ok: boolean;
+    readonly profile: "admin-crud" | "ops-report" | "unknown";
+    /** Legal admin-crud returns the input spec unchanged (validate-only). */
+    readonly spec: unknown;
+    readonly diagnostics: readonly ComposeDiagnostic[];
+    readonly registrySource?: "project" | "snapshot";
+    readonly registryVersion?: string;
+    readonly warnings: readonly string[];
+    /**
+     * Admin-crud only: true when top-level `blocks[]` types were checked against
+     * the registry. false when paint-path shape succeeded without blocks[] checks.
+     * Omitted for ops-report / unknown profile.
+     */
+    readonly blockTypesValidated?: boolean;
+}
+/** Structural paint-path shape used by platform JsonRender list consumers. */
+export declare function isPaintPathListSpec(spec: Record<string, unknown>): boolean;
+/**
+ * Profile-discriminated compose validation (tool-level).
+ * Registry resolve may walk the filesystem from `cwd` / `process.cwd()` when
+ * `resolvedRegistry` is not injected.
+ */
+export declare function composeValidate(raw: unknown, options?: {
+    readonly cwd?: string;
+    readonly resolvedRegistry?: ResolvedBlockRegistry;
+}): ComposeResult;

package/dist/esm/compose/compose.js

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import { opsReportSpecSchema } from "./ops-report-schema.js";
+import { blockNamesForView, resolveBlockRegistry, } from "./registry-resolve.js";
+const adminKindSchema = z.enum(["list", "detail", "form"]);
+const adminCrudInputSchema = z
+    .object({
+    profile: z.literal("admin-crud"),
+    kind: adminKindSchema,
+    /**
+     * Page-definition `blocks[]` and/or JsonRender* list/detail/form shapes.
+     * Empty objects and non-records are illegal (honesty contract).
+     */
+    spec: z.record(z.string(), z.unknown()),
+})
+    .strict();
+const opsReportInputSchema = z
+    .object({
+    profile: z.literal("ops-report"),
+    spec: z.unknown(),
+})
+    .strict();
+export const composeInputSchema = z.discriminatedUnion("profile", [
+    adminCrudInputSchema,
+    opsReportInputSchema,
+]);
+function zodToDiagnostics(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.join(".") : "(root)",
+        message: issue.message,
+    }));
+}
+/** Structural paint-path shape used by platform JsonRender list consumers. */
+export function isPaintPathListSpec(spec) {
+    return typeof spec["entity"] === "string" && Array.isArray(spec["columns"]);
+}
+function isPaintPathDetailOrFormSpec(spec) {
+    // Lightweight honesty: non-empty object with at least one recognized key.
+    return (typeof spec["entity"] === "string" ||
+        typeof spec["title"] === "string" ||
+        Array.isArray(spec["fields"]) ||
+        Array.isArray(spec["sections"]));
+}
+function hasRecognizedAdminShape(kind, spec) {
+    if (Array.isArray(spec["blocks"]))
+        return true;
+    if (kind === "list")
+        return isPaintPathListSpec(spec);
+    return isPaintPathDetailOrFormSpec(spec);
+}
+function slotDefsForBlock(registry, kind, type) {
+    const def = registry.blocks.find((b) => b.name === type && b.view === kind);
+    if (!def?.slots || !Array.isArray(def.slots))
+        return [];
+    const out = [];
+    for (const raw of def.slots) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const rec = raw;
+        const name = rec["name"];
+        if (typeof name !== "string" || name.length === 0)
+            continue;
+        const acceptsRaw = rec["accepts"];
+        const accepts = Array.isArray(acceptsRaw)
+            ? acceptsRaw.filter((a) => typeof a === "string")
+            : [];
+        out.push({ name, accepts });
+    }
+    return out;
+}
+/**
+ * Slot children are only hard-checked when they look like typed registry blocks
+ * (`{ type: string, ... }`). String enums (JsonRender list actions) and ActionSpec
+ * objects (`id`/`label`) are legal paint shapes — warn that they were not
+ * registry-type-checked instead of dishonestly rejecting them.
+ */
+function validateSlotChildren(blockPath, block, slots, diagnostics, warnings) {
+    for (const slot of slots) {
+        const value = block[slot.name];
+        if (value === undefined)
+            continue;
+        const items = Array.isArray(value) ? value : [value];
+        const acceptsList = [...slot.accepts].sort().join(", ");
+        for (const [childIndex, child] of items.entries()) {
+            const path = `${blockPath}.${slot.name}.${childIndex}`;
+            // JsonRender-style string action enums (e.g. "create" | "export")
+            if (typeof child === "string") {
+                warnings.push(`${path}: slot "${slot.name}" string child not registry-type-checked (paint-path action enum shape)`);
+                continue;
+            }
+            if (child === null || typeof child !== "object" || Array.isArray(child)) {
+                warnings.push(`${path}: slot "${slot.name}" child is not a typed block object; not registry-type-checked`);
+                continue;
+            }
+            const childType = child["type"];
+            if (typeof childType !== "string" || childType.length === 0) {
+                // ActionSpec-like { id, label, ... } without registry type
+                warnings.push(`${path}: slot "${slot.name}" object has no string type; not registry-type-checked`);
+                continue;
+            }
+            if (slot.accepts.length > 0 && !slot.accepts.includes(childType)) {
+                diagnostics.push({
+                    path: `${path}.type`,
+                    message: `illegal slot type "${childType}" for "${slot.name}"; accepts: ${acceptsList}`,
+                });
+            }
+        }
+    }
+}
+function validateAdminBlocks(kind, spec, resolved) {
+    const diagnostics = [];
+    const warnings = [];
+    const allowed = blockNamesForView(resolved.registry, kind);
+    const allowedList = [...allowed].sort().join(", ");
+    const blocks = spec["blocks"];
+    if (Object.keys(spec).length === 0) {
+        diagnostics.push({
+            path: "spec",
+            message: "admin-crud spec is empty; provide blocks[] (page composition) or a paint-path shape (e.g. list entity+columns)",
+        });
+        return { diagnostics, warnings, blockTypesValidated: false };
+    }
+    if (blocks === undefined) {
+        if (!hasRecognizedAdminShape(kind, spec)) {
+            diagnostics.push({
+                path: "spec",
+                message: "admin-crud spec has no blocks[] and no recognized paint-path fields; cannot claim registry validation",
+            });
+            return { diagnostics, warnings, blockTypesValidated: false };
+        }
+        warnings.push("admin-crud spec has no top-level blocks[]; registry block types were not checked (paint-path / JsonRender shape).");
+        return { diagnostics, warnings, blockTypesValidated: false };
+    }
+    if (!Array.isArray(blocks)) {
+        diagnostics.push({ path: "spec.blocks", message: "blocks must be an array" });
+        return { diagnostics, warnings, blockTypesValidated: false };
+    }
+    for (const [index, block] of blocks.entries()) {
+        if (block === null || typeof block !== "object" || Array.isArray(block)) {
+            diagnostics.push({ path: `spec.blocks.${index}`, message: "block must be an object" });
+            continue;
+        }
+        const record = block;
+        const type = record["type"];
+        if (typeof type !== "string" || type.length === 0) {
+            diagnostics.push({
+                path: `spec.blocks.${index}.type`,
+                message: "block requires string type",
+            });
+            continue;
+        }
+        if (!allowed.has(type)) {
+            diagnostics.push({
+                path: `spec.blocks.${index}.type`,
+                message: `illegal block type "${type}" for ${kind}; allowed: ${allowedList}`,
+            });
+            continue;
+        }
+        const def = resolved.registry.blocks.find((b) => b.name === type && b.view === kind);
+        if (def?.deprecated === true) {
+            warnings.push(`spec.blocks.${index}.type "${type}" is deprecated in the registry`);
+        }
+        const slots = slotDefsForBlock(resolved.registry, kind, type);
+        if (slots.length > 0) {
+            validateSlotChildren(`spec.blocks.${index}`, record, slots, diagnostics, warnings);
+        }
+    }
+    return { diagnostics, warnings, blockTypesValidated: true };
+}
+/**
+ * Profile-discriminated compose validation (tool-level).
+ * Registry resolve may walk the filesystem from `cwd` / `process.cwd()` when
+ * `resolvedRegistry` is not injected.
+ */
+export function composeValidate(raw, options = {}) {
+    const parsed = composeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            profile: "unknown",
+            spec: null,
+            diagnostics: zodToDiagnostics(parsed.error),
+            warnings: [],
+        };
+    }
+    const input = parsed.data;
+    /** Prefer original caller object identity for admin-crud passthrough. */
+    const originalSpec = raw !== null && typeof raw === "object" && !Array.isArray(raw) && "spec" in raw
+        ? raw.spec
+        : input.spec;
+    if (input.profile === "ops-report") {
+        const ops = opsReportSpecSchema.safeParse(input.spec);
+        if (!ops.success) {
+            return {
+                ok: false,
+                profile: "ops-report",
+                spec: originalSpec,
+                diagnostics: zodToDiagnostics(ops.error),
+                warnings: [],
+            };
+        }
+        return {
+            ok: true,
+            profile: "ops-report",
+            spec: ops.data,
+            diagnostics: [],
+            warnings: [],
+        };
+    }
+    // admin-crud: validate-only — return caller's spec object unchanged when legal
+    let resolved = options.resolvedRegistry;
+    if (!resolved) {
+        try {
+            resolved = resolveBlockRegistry({ cwd: options.cwd });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                profile: "admin-crud",
+                spec: originalSpec,
+                diagnostics: [{ path: "registry", message }],
+                warnings: [],
+            };
+        }
+    }
+    const { diagnostics: blockDiagnostics, warnings: blockWarnings, blockTypesValidated, } = validateAdminBlocks(input.kind, input.spec, resolved);
+    const warnings = [...resolved.warnings, ...blockWarnings];
+    if (blockDiagnostics.length > 0) {
+        return {
+            ok: false,
+            profile: "admin-crud",
+            spec: originalSpec,
+            diagnostics: blockDiagnostics,
+            registrySource: resolved.source,
+            registryVersion: resolved.registryVersion,
+            warnings,
+            blockTypesValidated,
+        };
+    }
+    return {
+        ok: true,
+        profile: "admin-crud",
+        spec: originalSpec,
+        diagnostics: [],
+        registrySource: resolved.source,
+        registryVersion: resolved.registryVersion,
+        warnings,
+        blockTypesValidated,
+    };
+}

package/dist/esm/compose/escape-html.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Single HTML encode chokepoint for compose/ops-report output.
+ * All untrusted strings must pass through here before interpolation.
+ */
+export declare function escapeHtml(value: string): string;

package/dist/esm/compose/escape-html.js

@@ -0,0 +1,12 @@
+/**
+ * Single HTML encode chokepoint for compose/ops-report output.
+ * All untrusted strings must pass through here before interpolation.
+ */
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/esm/compose/ops-report-render.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Render a validated OpsReportSpec to self-contained HTML.
+ * Callers should pass already-validated specs; this re-parses for safety.
+ */
+export declare function renderOpsReportHtml(input: unknown): string;

package/dist/esm/compose/ops-report-render.js

@@ -0,0 +1,71 @@
+import { escapeHtml } from "./escape-html.js";
+import { opsReportSpecSchema } from "./ops-report-schema.js";
+const CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'";
+/**
+ * Render a validated OpsReportSpec to self-contained HTML.
+ * Callers should pass already-validated specs; this re-parses for safety.
+ */
+export function renderOpsReportHtml(input) {
+    const spec = opsReportSpecSchema.parse(input);
+    return renderValidatedOpsReport(spec);
+}
+function renderValidatedOpsReport(spec) {
+    const metrics = spec.metrics
+        .map((metric) => `<div class="card"><div class="metric">${escapeHtml(String(metric.value))}</div><div>${escapeHtml(metric.label)}</div></div>`)
+        .join("");
+    const warnings = spec.warnings.length > 0
+        ? `<h2>Warnings</h2><ul>${spec.warnings
+            .map((warning) => `<li>${escapeHtml(warning)}</li>`)
+            .join("")}</ul>`
+        : "";
+    const sections = spec.sections
+        .map((section) => {
+        const body = section.body ? `<p>${escapeHtml(section.body)}</p>` : "";
+        const list = section.list && section.list.length > 0
+            ? `<ul>${section.list.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>`
+            : "";
+        return `<section><h2>${escapeHtml(section.heading)}</h2>${body}${list}</section>`;
+    })
+        .join("");
+    const tables = spec.tables
+        .map((table) => {
+        const title = table.title ? `<h2>${escapeHtml(table.title)}</h2>` : "";
+        const head = table.headers.map((header) => `<th>${escapeHtml(header)}</th>`).join("");
+        const body = table.rows
+            .map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(String(cell))}</td>`).join("")}</tr>`)
+            .join("");
+        return `${title}<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+    })
+        .join("");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${CSP}">
+<title>${escapeHtml(spec.title)}</title>
+<style>
+:root{color-scheme:light dark;font-family:Inter,system-ui,sans-serif;--bg:#f8fafc;--fg:#0f172a;--card:#fff;--muted:#64748b;--line:#cbd5e1}
+@media (prefers-color-scheme:dark){:root{--bg:#020617;--fg:#e2e8f0;--card:#0f172a;--muted:#94a3b8;--line:#334155}}
+body{margin:0;background:var(--bg);color:var(--fg);padding:2rem}
+main{max-width:1200px;margin:auto}
+.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(12rem,1fr));gap:1rem}
+.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:1rem}
+.metric{font-size:2rem;font-weight:800}
+table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:14px;overflow:hidden;margin:1rem 0}
+th,td{text-align:left;padding:.75rem;border-bottom:1px solid var(--line);vertical-align:top}
+th{color:var(--muted);font-size:.8rem;text-transform:uppercase}
+.muted{color:var(--muted)}
+</style>
+</head>
+<body>
+<main>
+<h1>${escapeHtml(spec.title)}</h1>
+<p class="muted">Generated ${escapeHtml(spec.generatedAt)}. Self-contained local report; no external assets.</p>
+${warnings}
+${metrics ? `<section class="cards">${metrics}</section>` : ""}
+${sections}
+${tables}
+</main>
+</body>
+</html>`;
+}

package/dist/esm/compose/ops-report-schema.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+/** Flat section only — no nesting (plan Fx17). */
+export declare const opsReportSectionSchema: z.ZodObject<{
+    heading: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    list: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const opsReportMetricSchema: z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+}, z.core.$strict>;
+export declare const opsReportTableSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    headers: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strict>;
+/**
+ * Minimal ops-report IR. Not a general page AST.
+ * Nesting under sections is rejected by the section schema (flat only).
+ */
+/** Flat ops-report only; section objects are `.strict()` so nested keys fail at the section boundary. */
+export declare const opsReportSpecSchema: z.ZodObject<{
+    title: z.ZodString;
+    generatedAt: z.ZodString;
+    metrics: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strict>>>>;
+    tables: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        headers: z.ZodArray<z.ZodString>;
+        rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    }, z.core.$strict>>>>;
+    warnings: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    sections: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        heading: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        list: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>;
+export type OpsReportSpec = z.infer<typeof opsReportSpecSchema>;
+export type OpsReportSection = z.infer<typeof opsReportSectionSchema>;

package/dist/esm/compose/ops-report-schema.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+/** Flat section only — no nesting (plan Fx17). */
+export const opsReportSectionSchema = z
+    .object({
+    heading: z.string().min(1),
+    body: z.string().optional(),
+    list: z.array(z.string()).optional(),
+})
+    .strict()
+    .superRefine((section, ctx) => {
+    if (section.body === undefined && section.list === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "section requires body and/or list",
+            path: ["body"],
+        });
+    }
+});
+const finiteNumber = z.number().finite();
+const cellValue = z.union([z.string(), finiteNumber]);
+export const opsReportMetricSchema = z
+    .object({
+    label: z.string().min(1),
+    value: cellValue,
+})
+    .strict();
+export const opsReportTableSchema = z
+    .object({
+    title: z.string().optional(),
+    headers: z.array(z.string()).min(1),
+    rows: z.array(z.array(cellValue)),
+})
+    .strict()
+    .superRefine((table, ctx) => {
+    const expected = table.headers.length;
+    for (const [rowIndex, row] of table.rows.entries()) {
+        if (row.length !== expected) {
+            ctx.addIssue({
+                code: "custom",
+                message: `row has ${row.length} cell(s); expected ${expected} to match headers`,
+                path: ["rows", rowIndex],
+            });
+        }
+    }
+});
+/**
+ * Minimal ops-report IR. Not a general page AST.
+ * Nesting under sections is rejected by the section schema (flat only).
+ */
+/** Flat ops-report only; section objects are `.strict()` so nested keys fail at the section boundary. */
+export const opsReportSpecSchema = z
+    .object({
+    title: z.string().min(1),
+    generatedAt: z.string().min(1),
+    metrics: z.array(opsReportMetricSchema).optional().default([]),
+    tables: z.array(opsReportTableSchema).optional().default([]),
+    warnings: z.array(z.string()).optional().default([]),
+    sections: z.array(opsReportSectionSchema).optional().default([]),
+})
+    .strict();

package/dist/esm/compose/preview.d.ts

@@ -0,0 +1,14 @@
+export interface PreviewOpsReportOptions {
+    readonly cwd?: string;
+    readonly spec: unknown;
+    /** Override output path (tests). */
+    readonly outputPath?: string;
+}
+export interface PreviewOpsReportResult {
+    readonly path: string;
+}
+/**
+ * Validate ops-report spec, write HTML under state-root (or override), return path only.
+ * No browser open.
+ */
+export declare function previewOpsReport(options: PreviewOpsReportOptions): PreviewOpsReportResult;

package/dist/esm/compose/preview.js

@@ -0,0 +1,32 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getSurfacePath, NotInGitRepoError } from "#paths/state-root.js";
+import { composeValidate } from "./compose.js";
+import { renderOpsReportHtml } from "./ops-report-render.js";
+/**
+ * Validate ops-report spec, write HTML under state-root (or override), return path only.
+ * No browser open.
+ */
+export function previewOpsReport(options) {
+    const composed = composeValidate({ profile: "ops-report", spec: options.spec }, { cwd: options.cwd });
+    if (!composed.ok) {
+        const detail = composed.diagnostics.map((d) => `${d.path}: ${d.message}`).join("; ");
+        throw new Error(`ops-report compose failed: ${detail}`);
+    }
+    const html = renderOpsReportHtml(composed.spec);
+    const path = options.outputPath ??
+        (() => {
+            try {
+                return getSurfacePath("compose/ops-report.html", "worktree", options.cwd);
+            }
+            catch (error) {
+                if (error instanceof NotInGitRepoError) {
+                    return join(options.cwd ?? process.cwd(), ".webpresso", "compose", "ops-report.html");
+                }
+                throw error;
+            }
+        })();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, html, "utf8");
+    return { path };
+}

package/dist/esm/compose/registry-resolve.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/**
+ * Local reader capability floor for project registries (agent-kit consumer).
+ * Bump in the same PR as catalog/compose/admin-blocks-registry.json major/minor
+ * advances. Does not import @webpresso/schema (SEA / nondeterminism lock).
+ */
+export declare const READER_REGISTRY_VERSION: "1.0.0";
+export declare const blockRegistrySchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    version: z.ZodString;
+    minVersion: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        view: z.ZodEnum<{
+            detail: "detail";
+            form: "form";
+            list: "list";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        variants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        slots: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        permissions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type BlockRegistry = z.infer<typeof blockRegistrySchema>;
+export type RegistrySource = "project" | "snapshot";
+export interface ResolvedBlockRegistry {
+    readonly registry: BlockRegistry;
+    readonly source: RegistrySource;
+    readonly registryVersion: string;
+    readonly path: string;
+    readonly warnings: readonly string[];
+    /** True when a `.webpresso/` tree was found but project registry was missing. */
+    readonly webpressoPresentWithoutRegistry: boolean;
+}
+export declare function defaultSnapshotPath(): string;
+/**
+ * Whether a loaded project registry is readable by this agent-kit consumer.
+ * - registry.version major must match the reader major
+ * - if registry.minVersion is set, reader must be >= that floor (semver order)
+ */
+export declare function isProjectRegistryCompatibleWithReader(registry: BlockRegistry, readerVersion?: string): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Two-tier registry resolution (v0):
+ * 1. Nearest project `.webpresso/` (within git/webpressorc boundary) — if it has
+ *    generated blocks registry, use it
+ * 2. Else catalog snapshot (with warning when that project `.webpresso/` lacks registry)
+ *
+ * Never dynamically imports @webpresso/schema.
+ * Never climbs past the project boundary into `~/.webpresso` (managed worktree host)
+ * or other ancestor projects (avoids silent wrong-project catalog).
+ */
+export declare function resolveBlockRegistry(options?: {
+    readonly cwd?: string;
+    readonly snapshotPath?: string;
+}): ResolvedBlockRegistry;
+export declare function blockNamesForView(registry: BlockRegistry, view: "list" | "detail" | "form"): ReadonlySet<string>;