@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/cli/commands/worktree/router-dispatch.js

@@ -15,9 +15,10 @@ import { runWorktreeSetup, runWorktreeTeardown } from "#worktrees/lifecycle-scri
 import { hydrateWorktreeDependencies, reconcileWorktreeDependencies, } from "#worktrees/dependencies.js";
 import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.js";
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
-import { formatTargetDirtyRefusal } from "#worktrees/owner-dirt.js";
+import { formatBoundedPaths, formatTargetDirtyRefusal, parsePorcelainV1Z, } from "#worktrees/owner-dirt.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
 import { findRegistryCandidatesByPath, planStaleWorktreeRegistryPrune, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
+import { isStaleWorktreeRegistration, pruneStaleGitWorktreeMetadata, } from "#worktrees/git-metadata.js";
 import { buildRegistryRepoRootMap, classifyOrphanCandidate, discoverOrphanScanCandidates, resolveRepoRootFromGitPointer, } from "#worktrees/orphan-scan.js";
 function parseDepsOption(value) {
     if (value === undefined || value === null || value === "")
@@ -165,9 +166,24 @@ export function planMergeCleanup(targetPath, baseRef) {
         mergeArgs: ["merge", "--ff-only", baseRef],
     };
 }
-function primaryStashMessage(input) {
-    const current = input.currentBranch || "(detached)";
-    return `wp worktree merge-cleanup preserve primary state from ${current} before syncing ${input.expectedPrimaryBranch} and removing ${basename(input.targetPath)}`;
+/**
+ * Refusal for a DIRTY primary checkout. Reuses the same low-level porcelain
+ * parser and bounded-list formatter `formatTargetDirtyRefusal` uses for the
+ * target worktree (`#worktrees/owner-dirt.js`) — this is NOT a classifier:
+ * it never decides whose dirt it is or whether it's "safe" to move. A dirty
+ * primary always refuses; this only lists the paths so the human knows what
+ * blocked the command.
+ */
+function formatPrimaryDirtyRefusal(repoRoot, porcelainZ) {
+    const paths = [
+        ...new Set(parsePorcelainV1Z(porcelainZ).flatMap((record) => record.paths.filter((path) => path.length > 0))),
+    ].toSorted();
+    return [
+        `wp worktree merge-cleanup refused: primary checkout ${repoRoot} has uncommitted changes`,
+        "Paths:",
+        formatBoundedPaths(paths),
+        "fix: commit or `git stash` the listed paths yourself (or `wp blueprint abandon <slug> --confirm` if this is leftover blueprint draft scaffold), then re-run merge-cleanup",
+    ].join("\n");
 }
 export function decideMergeCleanup(input) {
     const entry = input.entries.find((candidate) => candidate.path === input.targetPath);
@@ -193,34 +209,18 @@ export function decideMergeCleanup(input) {
         throw new Error(`wp worktree merge-cleanup refused: ${input.targetPath} has uncommitted changes`);
     }
     if (input.repoDirty) {
-        if (input.stashPrimary === true) {
-            return {
-                ...plan,
-                stashArgs: [
-                    "stash",
-                    "push",
-                    "--include-untracked",
-                    "--message",
-                    primaryStashMessage({
-                        currentBranch: input.currentBranch,
-                        expectedPrimaryBranch: plan.expectedPrimaryBranch,
-                        targetPath: input.targetPath,
-                    }),
-                ],
-                ...(input.currentBranch !== plan.expectedPrimaryBranch
-                    ? {
-                        switchArgs: ["switch", plan.expectedPrimaryBranch],
-                        preservedPrimaryBranch: input.currentBranch || "(detached)",
-                    }
-                    : {
-                        preservedPrimaryBranch: input.currentBranch || "(detached)",
-                    }),
-            };
-        }
-        throw new Error(`wp worktree merge-cleanup refused: primary checkout ${input.repoRoot} has uncommitted changes`);
+        // A dirty primary ALWAYS refuses -- unconditionally, regardless of
+        // --switch-primary/--stash-primary. merge-cleanup never stashes primary
+        // state; it never decides whose dirt it is or whether moving it is safe.
+        throw new Error(input.repoPorcelainZ !== undefined
+            ? formatPrimaryDirtyRefusal(input.repoRoot, input.repoPorcelainZ)
+            : `wp worktree merge-cleanup refused: primary checkout ${input.repoRoot} has uncommitted changes`);
     }
     if (input.currentBranch !== plan.expectedPrimaryBranch) {
-        if (input.stashPrimary === true) {
+        // --switch-primary bypasses ONLY this refusal, and only for a CLEAN
+        // primary: switching a clean checkout to the expected branch is
+        // harmless (nothing to lose), unlike stashing dirty state.
+        if (input.switchPrimary === true) {
             return {
                 ...plan,
                 switchArgs: ["switch", plan.expectedPrimaryBranch],
@@ -456,10 +456,14 @@ function handleRefresh(opts) {
 async function handlePrune(opts) {
     if (!opts.all)
         throw new Error("Usage: wp worktree prune --all");
+    const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
+    // Reconcile git's own admin records FIRST: a hand-deleted worktree directory
+    // leaves a record that still claims its branch, and it would otherwise report
+    // as live below and pin the matching registry entry in place too.
+    const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, listEntries(repoRoot));
     // Repository-scoped, three-state prune: only THIS repo's entries that are
     // proven stale against a COMPLETE git-live inventory are dropped; unknown,
     // other-repo, and live-legacy entries are retained.
-    const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
     const inventory = buildWorktreeInventory(repoRoot);
     const result = planStaleWorktreeRegistryPrune({
         inventory,
@@ -468,6 +472,13 @@ async function handlePrune(opts) {
     await removeCodexProjectTrusts(result.removed.map((entry) => entry.path));
     result.commit();
     console.log(`Pruned ${result.removed.length} stale managed registry entr${result.removed.length === 1 ? "y" : "ies"}.`);
+    if (gitPruned.error)
+        console.log(`warning: git worktree prune failed: ${gitPruned.error}`);
+    else {
+        console.log(`Cleared ${gitPruned.prunedPaths.length} stale git worktree registration${gitPruned.prunedPaths.length === 1 ? "" : "s"}.`);
+        for (const path of gitPruned.prunedPaths)
+            console.log(`  ${path}`);
+    }
     for (const warning of result.warnings)
         console.log(`warning: ${warning}`);
 }
@@ -546,6 +557,23 @@ async function handleRemove(nameOrPath, opts) {
     const repoRoot = resolvePrimaryRoot(callerRoot, entries);
     const resolved = resolveWorktreePath(nameOrPath, entries);
     const entry = entries.find((candidate) => candidate.path === resolved);
+    // The directory is already gone (hand-deleted, or a failed earlier removal):
+    // `git worktree remove` cannot act on it and teardown scripts have no cwd, so
+    // reconcile git's leftover admin record instead of failing.
+    if (isStaleWorktreeRegistration(entry, resolved, existsSync)) {
+        // Staleness is not a bypass for the managed-root boundary, which is the
+        // same protection the MCP surface applies to registry-gone stale targets.
+        if (!isManagedWorktreePath(canonicalizeWorktreePath(resolved), resolveKnownManagedWorktreeRoots())) {
+            throw new Error(`Refusing to reconcile ${resolved}: its directory is gone but it is not under a known managed worktree root.`);
+        }
+        const gitPruned = pruneStaleGitWorktreeMetadata(repoRoot, entries);
+        if (gitPruned.error)
+            throw new Error(`git worktree prune failed: ${gitPruned.error}`);
+        await removeCodexProjectTrust(resolved);
+        removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
+        console.log(`Cleared stale worktree registration for ${resolved} (directory already gone).`);
+        return;
+    }
     if (!opts.force) {
         runWorktreeTeardown(readConfig(resolved) ?? readConfig(repoRoot), {
             worktreePath: resolved,
@@ -713,6 +741,22 @@ async function handleMergeCleanup(nameOrPath, opts) {
         })()
         : undefined;
     const targetBlueprintSlug = inferBlueprintSlugFromOwnerPath(resolved);
+    // `--switch-primary`/legacy `--stash-primary` only ever bypasses the
+    // clean-primary wrong-branch refusal; a dirty primary always refuses (see
+    // `decideMergeCleanup`), so merge-cleanup never stashes primary state.
+    const switchPrimary = opts.switchPrimary === true || opts.stashPrimary === true;
+    const repoDirty = isDirty(repoRoot);
+    const repoPorcelainZ = repoDirty
+        ? (() => {
+            const status = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all", "--ignored=no", "-z"], { cwd: repoRoot, encoding: "utf8" });
+            // Unlike the target-worktree probe, do NOT substitute a sentinel path
+            // on failure: a fake "(git-status-failed)" path in the refusal message
+            // would misrepresent what's actually dirty. Leaving this undefined
+            // falls back to the generic (path-free) refusal in decideMergeCleanup
+            // -- the refusal itself is unaffected either way.
+            return status.status === 0 ? String(status.stdout ?? "") : undefined;
+        })()
+        : undefined;
     const plan = decideMergeCleanup({
         repoRoot,
         targetPath: resolved,
@@ -720,16 +764,15 @@ async function handleMergeCleanup(nameOrPath, opts) {
         entries,
         registryEntries: scopedRegistryEntries,
         currentBranch: currentBranch(repoRoot),
-        repoDirty: isDirty(repoRoot),
+        repoDirty,
         targetDirty,
-        stashPrimary: opts.stashPrimary === true,
+        switchPrimary,
         ...(targetPorcelainZ !== undefined ? { targetPorcelainZ } : {}),
         ...(targetBlueprintSlug !== undefined ? { targetBlueprintSlug } : {}),
+        ...(repoPorcelainZ !== undefined ? { repoPorcelainZ } : {}),
     });
     if (opts.dryRun) {
         console.log("[dry-run] Would run merge cleanup:");
-        if (plan.stashArgs)
-            console.log(`  stash:  git ${plan.stashArgs.join(" ")}`);
         if (plan.switchArgs)
             console.log(`  switch: git ${plan.switchArgs.join(" ")}`);
         console.log(`  remove: git ${plan.removeArgs.join(" ")}`);
@@ -737,12 +780,6 @@ async function handleMergeCleanup(nameOrPath, opts) {
         console.log(`  sync:   git ${plan.mergeArgs.join(" ")}`);
         return;
     }
-    if (plan.stashArgs) {
-        const stashResult = spawnSync("git", [...plan.stashArgs], { cwd: repoRoot, stdio: "inherit" });
-        if (stashResult.status !== 0) {
-            throw new Error("git stash push failed");
-        }
-    }
     if (plan.switchArgs) {
         const switchResult = spawnSync("git", [...plan.switchArgs], {
             cwd: repoRoot,
@@ -775,13 +812,8 @@ async function handleMergeCleanup(nameOrPath, opts) {
         throw new Error(`git merge --ff-only ${baseRef} failed`);
     }
     console.log(`Removed worktree ${resolved} and fast-forwarded ${repoRoot} to ${baseRef}.`);
-    if (plan.stashArgs) {
-        const stashRef = spawnSync("git", ["stash", "list", "--format=%gd %gs", "-n", "1"], {
-            cwd: repoRoot,
-            encoding: "utf8",
-        });
-        const summary = String(stashRef.stdout ?? "").trim();
-        console.log(`Preserved prior primary checkout state${plan.preservedPrimaryBranch ? ` from ${plan.preservedPrimaryBranch}` : ""} in ${summary || "git stash list"}.`);
+    if (plan.switchArgs && plan.preservedPrimaryBranch) {
+        console.log(`Switched primary checkout from ${plan.preservedPrimaryBranch} to ${plan.expectedPrimaryBranch}.`);
     }
 }
 export async function executeWorktreeSubcommand(subcommand, args, opts) {

package/dist/esm/cli/commands/worktree/router.js

@@ -27,7 +27,9 @@ const HELP_TEXT = [
     "  --dry-run           Print the resolved worktree target without writing",
     "  --no-setup          Skip configured worktree.setup scripts (new only)",
     "  --force             Skip configured teardown scripts and force removal",
-    "  --stash-primary     Stash dirty primary state and switch to the expected primary branch before merge-cleanup",
+    "  --switch-primary    Switch a CLEAN primary checkout to the expected branch before merge-cleanup",
+    "                      (a DIRTY primary always refuses, with or without this flag; it is never stashed)",
+    "  --stash-primary     Deprecated alias for --switch-primary. No longer stashes anything.",
     "  --orphans           Filesystem-level orphan sweep for prune (see prune --orphans above)",
     "  --repo-id <id>      Scope prune --orphans to one repo namespace under repos/<id>",
     "  --yes               Alias for --force (prune --orphans only)",
@@ -44,7 +46,8 @@ export function registerWorktreeRouter(cli) {
         .option("--no-setup", "Skip configured worktree.setup scripts (new only)")
         .option("--deps <mode>", "Dependency hydration for new: install-locked (default, pnpm GVS path) or reconcile")
         .option("--force", "Skip configured teardown scripts and force removal (remove/merge-cleanup only)")
-        .option("--stash-primary", "Stash dirty primary state and switch to the expected primary branch before merge-cleanup")
+        .option("--switch-primary", "Switch a CLEAN primary checkout to the expected branch before merge-cleanup (a dirty primary always refuses; never stashed)")
+        .option("--stash-primary", "Deprecated alias for --switch-primary. No longer stashes anything.")
         .option("--all", "Use global managed inventory where supported")
         .option("--repo <dir>", "Repo root for refresh/rebind (default: cwd)")
         .option("--orphans", "Filesystem-level orphan sweep for prune (dry-run unless --force/--yes)")

package/dist/esm/cli/direct-provider-launch.js

@@ -11,7 +11,7 @@ import { canonicalizeWorktreePath } from "#worktrees/identity.js";
 import { dashProviderOwnershipName, parseDashPermissionMode, } from "#cli/commands/dash/provider-capabilities.js";
 import { optionalToolCanonicalCommand } from "#cli/optional-tools.js";
 import { commandExists } from "#runtime/command-exists.js";
-import { ensureCodexProjectMcpServers, ensureCodexWebpressoMcp, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
+import { ensureCodexProjectMcpServers, findInstalledCodexPluginMcpManifests, pruneLegacyCodexWebpressoMcp, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
 export class DirectProviderLaunchPreparationError extends Error {
     action;
     constructor(message, action) {
@@ -91,11 +91,19 @@ function validateDirectProviderLaunch(provider, cwd) {
         vpCommand,
     };
 }
+/**
+ * `wp codex` is the only path that reaches machines which never re-run setup,
+ * so it carries the legacy-channel retirement too. The surviving channel is
+ * the bundled Codex plugin: probe its cache directly and WARN when it is
+ * absent. A `codex plugin marketplace` subprocess here would add latency to
+ * every launch and could hard-fail a machine where the plugin already works —
+ * a degraded session beats a blocked launch.
+ */
 function ensureCodexSessionTooling(repoRoot) {
     const options = { dryRun: false, overwrite: false };
-    const webpresso = ensureCodexWebpressoMcp({ options });
-    if (webpresso.kind === "codex-webpresso-mcp-not-installed") {
-        throw new DirectProviderLaunchPreparationError(`Codex webpresso MCP is not configured because no usable agent-kit install root was found. Checked: ${webpresso.checked.join(", ") || "(none)"}`, "Run `wp setup --yes-global` from this repo, then retry `wp codex`.");
+    pruneLegacyCodexWebpressoMcp({ options });
+    if (findInstalledCodexPluginMcpManifests().length === 0) {
+        console.warn("⚠ The webpresso Codex plugin is not installed, so the webpresso MCP server will be unavailable in this session. Run `wp setup` to install it.");
     }
     const project = ensureCodexProjectMcpServers({ repoRoot, options });
     if (project.kind === "codex-project-mcp-invalid") {

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

@@ -5,5 +5,14 @@ export interface FlattenedAssets {
 }
 /** Reads `.agent/{skills,commands,agents}/` and returns an in-memory flattened structure. */
 export declare function flattenAgentDir(agentDir: string): FlattenedAssets;
-/** Writes flattened assets to a directory structure mirroring rulesync's expected layout. */
+/**
+ * Writes flattened assets to the layout rulesync reads.
+ *
+ * The three shapes are not interchangeable, and getting one wrong is silent:
+ * rulesync discovers skills by globbing `skills/` for *directories* and reading
+ * `SKILL.md` inside each, reads subagents from `subagents/` (not `agents/`),
+ * and reads commands as flat `commands/*.md`. An asset written in the wrong
+ * shape is simply never seen — rulesync still exits 0, having generated
+ * nothing for it.
+ */
 export declare function writeFlattenedAssets(assets: FlattenedAssets, outDir: string): Promise<void>;

package/dist/esm/compiler/flatten.js

@@ -60,19 +60,29 @@ export function flattenAgentDir(agentDir) {
     }
     return { skills, commands, agents };
 }
-/** Writes flattened assets to a directory structure mirroring rulesync's expected layout. */
+/**
+ * Writes flattened assets to the layout rulesync reads.
+ *
+ * The three shapes are not interchangeable, and getting one wrong is silent:
+ * rulesync discovers skills by globbing `skills/` for *directories* and reading
+ * `SKILL.md` inside each, reads subagents from `subagents/` (not `agents/`),
+ * and reads commands as flat `commands/*.md`. An asset written in the wrong
+ * shape is simply never seen — rulesync still exits 0, having generated
+ * nothing for it.
+ */
 export async function writeFlattenedAssets(assets, outDir) {
-    const subdirs = ["skills", "commands", "agents"];
+    const subdirs = ["skills", "commands", "subagents"];
     for (const sub of subdirs) {
         mkdirSync(join(outDir, sub), { recursive: true });
     }
     for (const [name, content] of Object.entries(assets.skills)) {
-        writeFileSync(join(outDir, "skills", `${name}.md`), content);
+        mkdirSync(join(outDir, "skills", name), { recursive: true });
+        writeFileSync(join(outDir, "skills", name, "SKILL.md"), content);
     }
     for (const [name, content] of Object.entries(assets.commands)) {
         writeFileSync(join(outDir, "commands", `${name}.md`), content);
     }
     for (const [name, content] of Object.entries(assets.agents)) {
-        writeFileSync(join(outDir, "agents", `${name}.md`), content);
+        writeFileSync(join(outDir, "subagents", `${name}.md`), content);
     }
 }

package/dist/esm/compose/admin-blocks-registry-integrity.d.ts

@@ -0,0 +1,22 @@
+import { type BlockRegistry } from "./registry-resolve.js";
+export interface SnapshotIntegrityResult {
+    readonly ok: boolean;
+    readonly path: string;
+    readonly registry?: BlockRegistry;
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Fail-on-drift **equivalent** for agent-kit CI without a framework dependency:
+ * load the committed catalog snapshot and enforce generator-contract invariants
+ * (schema parse, version shape, unique name+view, well-formed slots).
+ *
+ * Full regenerate-and-diff against `@webpresso/codegen` remains a cross-repo
+ * operator step; this gate prevents a rotten or hand-broken snapshot from landing.
+ */
+/**
+ * Check (does not throw). Callers must inspect `.ok` — this is a gate helper,
+ * not a Node assertion that aborts the process.
+ */
+export declare function checkAdminBlocksSnapshotIntegrity(options?: {
+    readonly snapshotPath?: string;
+}): SnapshotIntegrityResult;

package/dist/esm/compose/admin-blocks-registry-integrity.js

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import { blockRegistrySchema, defaultSnapshotPath, } from "./registry-resolve.js";
+const SEMVER_LIKE = /^\d+\.\d+\.\d+/;
+const slotSchemaLoose = {
+    isSlot(value) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const rec = value;
+        return typeof rec["name"] === "string" && rec["name"].length > 0;
+    },
+};
+/**
+ * Fail-on-drift **equivalent** for agent-kit CI without a framework dependency:
+ * load the committed catalog snapshot and enforce generator-contract invariants
+ * (schema parse, version shape, unique name+view, well-formed slots).
+ *
+ * Full regenerate-and-diff against `@webpresso/codegen` remains a cross-repo
+ * operator step; this gate prevents a rotten or hand-broken snapshot from landing.
+ */
+/**
+ * Check (does not throw). Callers must inspect `.ok` — this is a gate helper,
+ * not a Node assertion that aborts the process.
+ */
+export function checkAdminBlocksSnapshotIntegrity(options = {}) {
+    const path = options.snapshotPath ?? defaultSnapshotPath();
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, path, diagnostics: [`cannot read snapshot: ${detail}`] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, path, diagnostics: [`snapshot is not valid JSON: ${detail}`] };
+    }
+    const result = blockRegistrySchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            ok: false,
+            path,
+            diagnostics: result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`),
+        };
+    }
+    const registry = result.data;
+    if (!SEMVER_LIKE.test(registry.version)) {
+        diagnostics.push(`version "${registry.version}" is not semver-like`);
+    }
+    if (registry.minVersion !== undefined && !SEMVER_LIKE.test(registry.minVersion)) {
+        diagnostics.push(`minVersion "${registry.minVersion}" is not semver-like`);
+    }
+    const seen = new Set();
+    for (const [index, block] of registry.blocks.entries()) {
+        const key = `${block.view}::${block.name}`;
+        if (seen.has(key)) {
+            diagnostics.push(`duplicate block ${key} at index ${index}`);
+        }
+        seen.add(key);
+        if (block.slots !== undefined) {
+            if (!Array.isArray(block.slots)) {
+                diagnostics.push(`blocks[${index}].slots must be an array`);
+                continue;
+            }
+            for (const [slotIndex, slot] of block.slots.entries()) {
+                if (!slotSchemaLoose.isSlot(slot)) {
+                    diagnostics.push(`blocks[${index}].slots[${slotIndex}] requires string name`);
+                    continue;
+                }
+                const accepts = slot.accepts;
+                if (accepts !== undefined) {
+                    if (!Array.isArray(accepts) || accepts.some((a) => typeof a !== "string")) {
+                        diagnostics.push(`blocks[${index}].slots[${slotIndex}].accepts must be string[] when present`);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        ok: diagnostics.length === 0,
+        path,
+        registry,
+        diagnostics,
+    };
+}

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

@@ -26,7 +26,15 @@ export interface ComposeResult {
     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

package/dist/esm/compose/compose.js

@@ -6,7 +6,10 @@ const adminCrudInputSchema = z
     .object({
     profile: z.literal("admin-crud"),
     kind: adminKindSchema,
-    /** Opaque page/spec payload; blocks[] validated against registry when present. */
+    /**
+     * 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();
@@ -26,25 +29,118 @@ function zodToDiagnostics(error) {
         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) {
-        warnings.push("admin-crud spec has no top-level blocks[]; registry types were not checked (validate-only passthrough).");
-        return { diagnostics, warnings };
+        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 };
+        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 type = block["type"];
+        const record = block;
+        const type = record["type"];
         if (typeof type !== "string" || type.length === 0) {
             diagnostics.push({
                 path: `spec.blocks.${index}.type`,
@@ -55,11 +151,20 @@ function validateAdminBlocks(kind, spec, resolved) {
         if (!allowed.has(type)) {
             diagnostics.push({
                 path: `spec.blocks.${index}.type`,
-                message: `illegal block type "${type}" for ${kind}; allowed: ${[...allowed].sort().join(", ")}`,
+                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 };
+    return { diagnostics, warnings, blockTypesValidated: true };
 }
 /**
  * Profile-discriminated compose validation (tool-level).
@@ -118,7 +223,7 @@ export function composeValidate(raw, options = {}) {
             };
         }
     }
-    const { diagnostics: blockDiagnostics, warnings: blockWarnings } = validateAdminBlocks(input.kind, input.spec, resolved);
+    const { diagnostics: blockDiagnostics, warnings: blockWarnings, blockTypesValidated, } = validateAdminBlocks(input.kind, input.spec, resolved);
     const warnings = [...resolved.warnings, ...blockWarnings];
     if (blockDiagnostics.length > 0) {
         return {
@@ -129,6 +234,7 @@ export function composeValidate(raw, options = {}) {
             registrySource: resolved.source,
             registryVersion: resolved.registryVersion,
             warnings,
+            blockTypesValidated,
         };
     }
     return {
@@ -139,5 +245,6 @@ export function composeValidate(raw, options = {}) {
         registrySource: resolved.source,
         registryVersion: resolved.registryVersion,
         warnings,
+        blockTypesValidated,
     };
 }