@vibe-agent-toolkit/cli 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/commands/claude/marketplace/validate.js

@@ -7,22 +7,27 @@
  * - LICENSE file must exist (error)
  * - README.md should exist (warning)
  * - CHANGELOG.md should exist (warning)
+ *
+ * Publishes the `Report<T>` envelope (`validate-schema.ts`): every finding flat
+ * with its `location` relative to `data.root`, one `data.plugins` row per
+ * declared local plugin walked.
  */
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { validateMarketplace, validateSkill, } from '@vibe-agent-toolkit/agent-skills';
+import { readdirSync } from 'node:fs';
+import { materializeIssue, validateMarketplace, validateSkill, } from '@vibe-agent-toolkit/agent-skills';
 import { validatePlugin } from '@vibe-agent-toolkit/claude-marketplace';
-import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/schema';
-import { direntKindFollowingSync, findProjectRoot, isPathAbsentError, issueLocation, isVatError, normalizePath, PathEscapesRootError, relativeEscapesRoot, safePath, toForwardSlash, toForwardSlashAnyPlatform } from '@vibe-agent-toolkit/utils';
+import { buildReport, summarizeIssues, toFindings, } from '@vibe-agent-toolkit/schema';
+import { direntKindFollowingSync, everywhere, findProjectRoot, followedKindSync, forEachInOrder, fsFaultOf, isLinkChainRefusedError, isPathAbsentError, issueLocation, isVatError, mapInOrder, normalizePath, PathEscapesRootError, pathPresent, relativeEscapesRoot, safePath, toForwardSlash, toForwardSlashAnyPlatform } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
-import { formatDuration, reportCommandError } from '../../../utils/command-error.js';
+import { refusalCodeOf } from '../../../utils/command-refusal.js';
 import { loadConfig } from '../../../utils/config-loader.js';
-import { summarizeFindings } from '../../../utils/issue-rendering.js';
+import { endWithReport, NOTHING_FINISHED, publishedReport, refusalReport } from '../../../utils/document-writer.js';
 import { resolveIssueSeverity } from '../../../utils/issue-severity.js';
 import { createLogger } from '../../../utils/logger.js';
-import { writeYamlOutput } from '../../../utils/output.js';
-import { relativizePathEntries } from '../../../utils/relativize-paths.js';
-import { runIntegrityFinding } from '../../../utils/run-integrity.js';
-import { finishCommand } from '../../phase-utils.js';
+import { assertReadableDirectoryArgument } from '../../../utils/project-root-policy.js';
+import { relativizePath } from '../../../utils/relativize-paths.js';
+import { RUN_INTEGRITY_CODE, runIntegrityFinding, warnRunIntegrity } from '../../../utils/run-integrity.js';
+/** `vat claude marketplace validate` offers no `--strict`: warnings never fail it. */
+const GATE = { strict: false };
 /**
  * Check for required/recommended files in the marketplace root.
  */
@@ -34,7 +39,8 @@ function checkMarketplaceFiles(marketplacePath) {
         { file: 'CHANGELOG.md', code: 'MARKETPLACE_MISSING_CHANGELOG', severity: 'warning', verb: 'recommended for tracking changes' },
     ];
     for (const check of fileChecks) {
-        if (!existsSync(safePath.join(marketplacePath, check.file))) {
+        // A probe the OS refuses is the marketplace's source fault, never "missing".
+        if (!pathPresent(safePath.join(marketplacePath, check.file), { follow: marketplacePath }, everywhere('source'), 'probe')) {
             issues.push({
                 severity: check.severity,
                 code: check.code,
@@ -71,6 +77,8 @@ class WalkBoundary {
     marketplacePath;
     realRoot;
     refused = [];
+    /** Root-relative paths inside a validated plugin the OS would not let the walk read. */
+    unread = [];
     constructor(marketplacePath, realRoot) {
         this.marketplacePath = marketplacePath;
         this.realRoot = realRoot;
@@ -81,12 +89,41 @@ class WalkBoundary {
      * beneath it is visited either, because nothing beneath it was read.
      */
     contains(abs) {
-        const real = toForwardSlash(normalizePath(abs));
-        if (!relativeEscapesRoot(safePath.relative(this.realRoot, real)))
+        if (this.resolvesInside(abs))
             return true;
         this.refused.push(issueLocation(abs, this.marketplacePath));
         return false;
     }
+    /**
+     * Whether `abs`'s real path — its links read beneath the root first — sits under the root. A
+     * chain through a network or device path leaves the root by definition, and is never handed to
+     * the kernel: it is outside.
+     */
+    resolvesInside(abs) {
+        try {
+            return !relativeEscapesRoot(safePath.relative(this.realRoot, toForwardSlash(normalizePath(abs, this.marketplacePath))));
+        }
+        catch (error) {
+            if (!isLinkChainRefusedError(error))
+                throw error;
+            return false;
+        }
+    }
+    /**
+     * Record `abs` as a path the OS refused to let the walk read, and return its
+     * `SCAN_PATH_UNREADABLE` warning. The record, not the warning, is what the
+     * builder turns into the run-integrity refusal: a severity override may
+     * silence the warning, never the fact that nothing behind the path was read.
+     * Anything that is not a filesystem refusal is a defect and is rethrown.
+     */
+    unreadable(abs, error) {
+        const fault = fsFaultOf(error);
+        if (fault === undefined)
+            throw error;
+        const location = issueLocation(abs, this.marketplacePath);
+        this.unread.push(location);
+        return materializeIssue('SCAN_PATH_UNREADABLE', { location, detail: `${location}: read refused with ${fault.errno}` });
+    }
 }
 /**
  * Validate all SKILL.md files within a plugin's skills/ directory.
@@ -100,23 +137,52 @@ class WalkBoundary {
  */
 async function validatePluginSkills(pluginDir, marketplacePath, boundary, validation) {
     const skillsDir = safePath.join(pluginDir, 'skills');
-    if (!existsSync(skillsDir) || !boundary.contains(skillsDir))
+    // Containment first: it reads the chain, so a link out (a network one included) is refused by
+    // name before anything follows it; an absent `skills/` is inside and then not present.
+    if (!boundary.contains(skillsDir))
         return [];
-    const issues = [];
-    const skillEntries = readdirSync(skillsDir, { withFileTypes: true });
-    for (const skillEntry of skillEntries) {
-        const skillDir = safePath.join(skillsDir, skillEntry.name);
-        if (!isDirectory(skillDir) || !boundary.contains(skillDir))
-            continue;
-        const skillMdPath = safePath.join(skillDir, 'SKILL.md');
-        if (!existsSync(skillMdPath) || !boundary.contains(skillMdPath))
-            continue;
+    let skillEntries;
+    try {
+        if (!pathPresent(skillsDir, { follow: marketplacePath }, everywhere('source'), 'probe'))
+            return [];
+        skillEntries = readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        return resolveIssueSeverity([boundary.unreadable(skillsDir, error)], validation);
+    }
+    // In order: `boundary` records refused and unread paths in the order the run names them.
+    const perSkill = await mapInOrder(skillEntries, (skillEntry) => validateOneSkill(safePath.join(skillsDir, skillEntry.name), marketplacePath, boundary, validation));
+    return perSkill.flat();
+}
+/**
+ * Validate one entry of a plugin's `skills/`: nothing when it is not a skill
+ * directory holding a SKILL.md under the root. A skill the OS will not let the
+ * run stat or read is one this gate did not check — named through `boundary`
+ * and refused by the builder, never a crash (it was INTERNAL_ERROR, exit 2).
+ */
+async function validateOneSkill(skillDir, marketplacePath, boundary, validation) {
+    const refusedAt = (path, error) => resolveIssueSeverity([boundary.unreadable(path, error)], validation);
+    // Containment before every followed probe: `contains` reads the chain and refuses a link out
+    // (a network one included) by name, so the probe after it only ever follows a chain in the root.
+    try {
+        if (!boundary.contains(skillDir) || !isDirectory(skillDir, marketplacePath))
+            return [];
+    }
+    catch (error) {
+        return refusedAt(skillDir, error);
+    }
+    const skillMdPath = safePath.join(skillDir, 'SKILL.md');
+    try {
+        if (!boundary.contains(skillMdPath) || !pathPresent(skillMdPath, { follow: marketplacePath }, everywhere('source'), 'probe'))
+            return [];
         // Severity only (no `allow`), resolved here so a default-`ignore` code can still be raised.
         const severity = validation?.severity === undefined ? {} : { severity: validation.severity };
-        const skillResult = await validateSkill({ skillPath: skillMdPath, rootDir: skillDir, locationRoot: marketplacePath, validation: severity });
-        issues.push(...skillResult.issues);
+        const skillResult = await validateSkill({ skillPath: skillMdPath, rootDir: skillDir, locationRoot: marketplacePath, validation: severity, side: 'source' });
+        return skillResult.issues;
+    }
+    catch (error) {
+        return refusedAt(skillMdPath, error);
     }
-    return issues;
 }
 /**
  * Whether `dir` is a directory. `false` for a file and for nothing — both are
@@ -125,9 +191,9 @@ async function validatePluginSkills(pluginDir, marketplacePath, boundary, valida
  * resolve, sending the reader to create a directory that is there. The refusal
  * propagates and the command refuses the run by errno, like every other verb.
  */
-function isDirectory(dir) {
+function isDirectory(dir, within) {
     try {
-        return statSync(dir).isDirectory();
+        return followedKindSync(dir, within) === 'directory';
     }
     catch (error) {
         if (isPathAbsentError(error))
@@ -181,9 +247,19 @@ function containedPluginDir(marketplacePath, realRoot, source) {
             throw error;
         return undefined;
     }
-    if (!isDirectory(lexical))
+    let real;
+    try {
+        if (!isDirectory(lexical, marketplacePath))
+            return undefined;
+        real = toForwardSlash(normalizePath(lexical, marketplacePath));
+    }
+    catch (error) {
+        // A source whose link chain names a network or device path leaves the root by definition: it
+        // names nothing this command may enter, and the builder refuses the run by name from its absence.
+        if (!isLinkChainRefusedError(error))
+            throw error;
         return undefined;
-    const real = toForwardSlash(normalizePath(lexical));
+    }
     return relativeEscapesRoot(safePath.relative(realRoot, real)) ? undefined : { lexical, real };
 }
 /**
@@ -215,11 +291,10 @@ function containedPluginDir(marketplacePath, realRoot, source) {
  * `validation` is the governing project's severity map (see
  * {@link resolveProjectValidationConfig}). It is applied to each plugin result
  * HERE rather than to the flat list at the end because the emitted document
- * publishes both: `issues` and `plugins[].issues` are two views of the same
- * findings, plus `plugins[].status`. Resolving once, at the producer, is what
- * keeps them from disagreeing — a suppressed warning still listed under
- * `plugins[]`, or a plugin `status: warning` above an issue list that no longer
- * contains a warning.
+ * publishes both: the envelope's `findings` and each `data.plugins[]` row's
+ * `status` + `summary` tally the same findings. Resolving once, at the
+ * producer, is what keeps them from disagreeing — a row counting a warning
+ * the envelope suppressed, or a row `findings` over nothing published.
  */
 async function validateDeclaredPlugins(marketplacePath, declared, validation) {
     const pluginResults = [];
@@ -227,34 +302,38 @@ async function validateDeclaredPlugins(marketplacePath, declared, validation) {
     // Keyed by REAL path: one directory is validated once however many entries
     // name it, and the same key is what `undeclaredPluginDirs` compares against.
     const validatedByDir = new Map();
-    const realRoot = toForwardSlash(normalizePath(marketplacePath));
+    // The marketplace root is the operator's own argument: its own `within`.
+    const realRoot = toForwardSlash(normalizePath(marketplacePath, marketplacePath));
     const boundary = new WalkBoundary(marketplacePath, realRoot);
-    for (const entry of declared) {
+    // In order: `validatedByDir` dedupes a directory two entries name, which a
+    // concurrent first visit would validate twice.
+    await forEachInOrder(declared, async (entry) => {
         // A source that names nothing inside the root — nothing at all, a file,
         // an absolute path, a `..` climb, a symlink out — is simply absent from the
         // results, and the builder refuses the run by name from that absence.
         const dir = containedPluginDir(marketplacePath, realRoot, entry.source);
         if (dir === undefined)
-            continue;
+            return;
         // Two entries, one directory: the directory's findings were collected
         // twice and COUNTED twice (`PLUGIN_MISSING_AUTHOR: 2` for one file). Each
         // entry still gets its row — the manifest declared two — but the file is
         // inspected once and its findings enter `issues` once.
         const seen = validatedByDir.get(dir.real);
         if (seen !== undefined) {
-            pluginResults.push({ ...entry, result: seen });
-            continue;
+            pluginResults.push({ ...entry, ...seen });
+            return;
         }
-        const result = await validateContainedPlugin(dir.lexical, marketplacePath, boundary, validation);
-        validatedByDir.set(dir.real, result);
-        pluginResults.push({ ...entry, result });
-        issues.push(...result.issues);
+        const contained = await validateContainedPlugin(dir.lexical, marketplacePath, boundary, validation);
+        validatedByDir.set(dir.real, contained);
+        pluginResults.push({ ...entry, ...contained });
+        issues.push(...contained.result.issues);
         issues.push(...await validatePluginSkills(dir.lexical, marketplacePath, boundary, validation));
-    }
+    });
     return {
         pluginResults,
         undeclared: undeclaredPluginDirs(marketplacePath, new Set(validatedByDir.keys())),
         refused: boundary.refused,
+        unread: boundary.unread,
         issues,
     };
 }
@@ -263,21 +342,26 @@ async function validateDeclaredPlugins(marketplacePath, declared, validation) {
  * of the root, in which case the manifest is refused by name and the plugin's
  * row says so instead of carrying findings about a file the run did not read.
  *
- * The row keeps `status: 'error'` with no issues: the error is the refusal
- * the builder publishes once for the run, and a `success` row for a plugin
- * whose manifest was never opened would be the reassuring lie this whole
- * boundary exists to refuse.
+ * The row is published with `manifestRead: false` and nothing counted: the
+ * error is the refusal the builder publishes once for the run, and a bare
+ * `ok` row for a plugin whose manifest was never opened would be the
+ * reassuring lie this whole boundary exists to refuse — `manifestRead` is
+ * what tells the two apart. A manifest the OS will not read is the same
+ * claim: the row is `manifestRead: false` and the builder names it in that refusal.
  */
 async function validateContainedPlugin(pluginDir, marketplacePath, boundary, validation) {
     const manifestPath = safePath.join(pluginDir, '.claude-plugin', 'plugin.json');
-    if (existsSync(manifestPath) && !boundary.contains(manifestPath)) {
+    // No presence probe: `contains` reads the chain, and an absent (or dangling) manifest is inside.
+    if (!boundary.contains(manifestPath)) {
         return {
-            path: pluginDir,
-            type: 'claude-plugin',
-            status: 'error',
-            summary: `Plugin manifest not read: ${issueLocation(manifestPath, marketplacePath)} resolves outside the marketplace root`,
-            issues: [],
-            issueCounts: countBySeverity([]),
+            manifestRead: false,
+            result: {
+                path: pluginDir,
+                type: 'claude-plugin',
+                ...summarizeIssues([]),
+                description: `Plugin manifest not read: ${issueLocation(manifestPath, marketplacePath)} resolves outside the marketplace root`,
+                issues: [],
+            },
         };
     }
     // `locationRoot` is not optional here even though the parameter is: omitted,
@@ -286,12 +370,19 @@ async function validateContainedPlugin(pluginDir, marketplacePath, boundary, val
     // and skill findings beside them — and every plugin's manifest collapses to
     // the same `.claude-plugin/plugin.json`.
     const rawResult = await validatePlugin(pluginDir, { strict: true, locationRoot: marketplacePath });
+    // A manifest the OS refused is a `SCAN_PATH_UNREADABLE` WARNING from the
+    // validator — right for `vat audit`, a pass for this gate. Read off the RAW
+    // issues, so a severity override cannot turn "not read" back into "read".
+    const manifestLocation = issueLocation(manifestPath, marketplacePath);
+    const manifestRead = !rawResult.issues.some((issue) => issue.code === 'SCAN_PATH_UNREADABLE' && issue.location === manifestLocation);
     const pluginIssues = resolveIssueSeverity(rawResult.issues, validation);
     return {
-        ...rawResult,
-        issues: pluginIssues,
-        status: calculateValidationStatus(pluginIssues),
-        issueCounts: countBySeverity(pluginIssues),
+        manifestRead,
+        result: {
+            ...rawResult,
+            issues: pluginIssues,
+            ...summarizeIssues(pluginIssues),
+        },
     };
 }
 /**
@@ -304,15 +395,35 @@ async function validateContainedPlugin(pluginDir, marketplacePath, boundary, val
  */
 function undeclaredPluginDirs(marketplacePath, validatedDirs) {
     const pluginsDir = safePath.join(marketplacePath, 'plugins');
-    if (!existsSync(pluginsDir))
+    if (!pathPresent(pluginsDir, { follow: marketplacePath }, everywhere('source'), 'probe'))
         return [];
     return readdirSync(pluginsDir, { withFileTypes: true })
         // Followed: a plugin directory that is a link is a plugin the marketplace
         // ships, and `validatedDirs` is real paths for exactly that reason.
-        .filter((entry) => direntKindFollowingSync(pluginsDir, entry) === 'directory')
-        .map((entry) => safePath.join(pluginsDir, entry.name))
-        .filter((dir) => !validatedDirs.has(toForwardSlash(normalizePath(dir))))
-        .map((dir) => issueLocation(dir, marketplacePath));
+        .flatMap((entry) => {
+        const dir = safePath.join(pluginsDir, entry.name);
+        const real = undeclaredCandidateIdentity(pluginsDir, entry, marketplacePath);
+        return real === undefined || validatedDirs.has(real) ? [] : [issueLocation(dir, marketplacePath)];
+    });
+}
+/**
+ * The real path of a `plugins/` entry that resolves to a directory, or `undefined` when it does
+ * not. An entry whose link chain names a network or device path is never followed: no declared
+ * source can resolve to it (the source lane refuses the same chain), so it is listed by its own
+ * spelling — named, never silently dropped.
+ */
+function undeclaredCandidateIdentity(pluginsDir, entry, within) {
+    const dir = safePath.join(pluginsDir, entry.name);
+    try {
+        if (direntKindFollowingSync(pluginsDir, entry, within) !== 'directory')
+            return undefined;
+        return toForwardSlash(normalizePath(dir, within));
+    }
+    catch (error) {
+        if (!isLinkChainRefusedError(error))
+            throw error;
+        return dir;
+    }
 }
 /**
  * The `validation` config governing findings about `marketplacePath`.
@@ -352,7 +463,7 @@ function resolveProjectValidationConfig(marketplacePath, logger) {
     if (projectRoot === null)
         return undefined;
     try {
-        return loadConfig(projectRoot)?.skills?.defaults?.validation;
+        return loadConfig(projectRoot, 'source')?.skills?.defaults?.validation;
     }
     catch (error) {
         logger.error(`Warning: could not read ${projectRoot} config for validation.severity overrides — ` +
@@ -378,8 +489,8 @@ function resolveProjectValidationConfig(marketplacePath, logger) {
  *
  * Severity resolution is likewise INSIDE this function rather than a step the
  * command adds after it. Its absence is the whole defect this addressed, and a
- * command-body step is one a caller can forget: with it here, the flat `issues`
- * list and `plugins[].issues` derive from a single resolved set, and the
+ * command-body step is one a caller can forget: with it here, the envelope's
+ * `findings` and the `data.plugins[]` tallies derive from a single resolved set, and the
  * smallest testable entry point is the one that includes the filter. The run's
  * `status` — and with it the exit code — is derived one step later, in
  * {@link buildMarketplaceValidateReport}, from the issues the document actually
@@ -402,70 +513,53 @@ export async function collectMarketplaceFindings(marketplacePath, logger) {
     // These issues are deliberately NOT severity-resolved: an override governs
     // findings ABOUT a marketplace that could be read, not the failure to read
     // one. Resolving them would let `MARKETPLACE_MISSING_MANIFEST: ignore` empty
-    // the list and report `status: success` beside a summary saying the manifest
-    // is missing — a run that never happened claiming it passed.
-    if (marketplaceResult.status === 'error') {
+    // the list and report `status: ok` beside a manifest that is missing — a run that never happened claiming it passed.
+    if (marketplaceResult.summary.errors > 0) {
         return {
             marketplaceResult,
             pluginResults: [],
             undeclared: [],
             refused: [],
+            unread: [],
             issues: [...marketplaceResult.issues],
         };
     }
     const validation = resolveProjectValidationConfig(marketplacePath, logger);
     const fileIssues = checkMarketplaceFiles(marketplacePath);
-    const { pluginResults, undeclared, refused, issues: pluginIssues } = await validateDeclaredPlugins(marketplacePath, marketplaceResult.metadata?.localPluginSources ?? [], validation);
+    const { pluginResults, undeclared, refused, unread, issues: pluginIssues } = await validateDeclaredPlugins(marketplacePath, marketplaceResult.metadata?.localPluginSources ?? [], validation);
     const issues = [
         ...resolveIssueSeverity(marketplaceResult.issues, validation),
         ...resolveIssueSeverity(fileIssues, validation),
         ...pluginIssues,
     ];
-    return { marketplaceResult, pluginResults, undeclared, refused, issues };
+    return { marketplaceResult, pluginResults, undeclared, refused, unread, issues };
 }
 /**
- * Group key for findings that carry no `location` at all.
- *
- * A symbol rather than a sentinel string, and it is deliberately NOT published
- * as one: every `location` in this document must satisfy the anchor contract —
- * `join(root, location)` names a real file — so a row keyed `(no location)`
- * would be a path that resolves to nothing, which is the coordinate lie `root`
- * exists to prevent. The row is published with `unlocated: true` and no
- * `location` instead. Dropping such findings was the other option and is the
- * worse one: grouping by `location` is exactly the operation that silently
- * loses them, and a shorter summary is the reassuring failure.
- */
-const UNLOCATED = Symbol('unlocated');
-/**
- * Collapse a flat finding list onto one counts-only row per `location`.
- *
- * `location` is this command's per-asset unit: `plugins/alpha/.claude-plugin/
- * plugin.json`, `plugins/beta/skills/x/SKILL.md`. Rows come out in first-seen
- * order, and a location with no findings has no row — there is nothing to
- * filter here, because a location only exists in this listing by having emitted
- * something.
+ * The plugin entries the run examined: every REMOTE entry — the manifest's
+ * schema is its whole validation, and it passed — plus every declared local
+ * plugin the walk reached. A local entry whose source did not resolve is not
+ * counted; the builder's run-integrity finding names it.
  *
- * Every value is passed through un-rebased: `location` is already relative to
- * the report's stated `root`, and `relative()` is not idempotent (see
- * {@link MarketplaceValidateReportInput.root}).
+ * Remote entries count because an all-remote marketplace is a real verdict
+ * about a manifest whose every entry validated, not a run over nothing.
  */
-export function summarizeIssuesByLocation(issues) {
-    const byLocation = new Map();
-    for (const issue of issues) {
-        const key = issue.location ?? UNLOCATED;
-        const existing = byLocation.get(key);
-        if (existing) {
-            existing.push(issue);
-        }
-        else {
-            byLocation.set(key, [issue]);
-        }
-    }
-    return [...byLocation.entries()].map(([key, locationIssues]) => {
-        const { codes, ...counts } = summarizeFindings(locationIssues);
-        const anchor = typeof key === 'string' ? { location: key } : { unlocated: true };
-        return { ...anchor, ...counts, codes };
-    });
+function pluginEntriesExamined(marketplace, pluginResults) {
+    const declared = marketplace?.pluginEntries ?? 0;
+    const local = marketplace?.localPluginSources?.length ?? 0;
+    return declared - local + pluginResults.length;
+}
+/** The manifest's facts the document publishes, or `null` when it did not validate. */
+function marketplaceData(marketplace) {
+    if (marketplace === undefined)
+        return null;
+    const { name, description, version, pluginEntries, localPluginSources } = marketplace;
+    return {
+        ...(name === undefined ? {} : { name }),
+        ...(description === undefined ? {} : { description }),
+        ...(version === undefined ? {} : { version }),
+        ...(pluginEntries === undefined ? {} : { pluginEntries }),
+        ...(localPluginSources === undefined ? {} : { localPluginSources }),
+    };
 }
 /**
  * Build the report `vat claude marketplace validate` publishes on stdout.
@@ -475,57 +569,50 @@ export function summarizeIssuesByLocation(issues) {
  * builder serves both exits (manifest-missing bail and full run) so the
  * document has a single shape either way.
  *
+ * `status` and `summary` are derived by `buildReport` from the findings — the
+ * run-integrity refusal below included — so the status, the counts and the
+ * exit code cannot disagree. A plugin row's `summary` is the tally of the
+ * findings its own validator published; every finding itself is on the
+ * envelope, once.
+ *
  * Being pure is also the limit of what it can guarantee: it re-bases `path`,
  * and passes `issues` through verbatim. The single-coordinate-system property
  * is therefore only as true as its inputs — see `root` above — and is enforced
  * against a real marketplace in `payload-path-coordinates.test.ts`, not here.
  */
 export function buildMarketplaceValidateReport(input) {
-    const { root, marketplace, pluginResults, undeclared, refused, bailSummary, duration, verbose } = input;
-    const issues = [
-        ...unfinishedRunFinding(marketplace, pluginResults, refused),
+    const { root, marketplace, pluginResults, undeclared, refused } = input;
+    const unread = [...unreadManifests(pluginResults, refused, root), ...input.unread];
+    const findings = toFindings([
+        ...unfinishedRunFinding(marketplace, pluginResults, refused, unread),
         ...input.issues,
-    ];
-    const issueCounts = countBySeverity(issues);
-    const plugins = pluginResults.map(({ name, source, result }) => ({
+    ]);
+    const plugins = pluginResults.map(({ name, source, result, manifestRead }) => ({
         name,
         source,
-        path: result.path,
-        status: result.status,
-        metadata: result.metadata,
-        issues: result.issues,
+        path: relativizePath(result.path, root),
+        manifestRead,
+        ...summarizeIssues(toFindings(result.issues)),
     }));
-    return {
-        // Derived from the issues THIS document publishes — the refusal above
-        // included — so the status, the counts and the listing cannot disagree, and
-        // the exit code the command takes from it cannot either.
-        status: calculateValidationStatus(issues),
-        // Stated once, and the only absolute path in the document.
-        root,
-        ...(marketplace ? { marketplace } : {}),
-        // The numerator. Beside `marketplace.localPluginSources` it says whether
-        // every declared source resolved; without it "three local plugins, all
-        // clean" and "three local plugins, none looked at" are the same document.
-        pluginsValidated: pluginResults.length,
-        plugins: relativizePathEntries(plugins, root),
-        // Named, not graded — see `validateDeclaredPlugins`. Always present, so an
-        // empty list is a statement that `plugins/` was looked at.
-        undeclared: [...undeclared],
-        // Paths the walk would not open (real path outside the root) — see
-        // `WalkBoundary`. Always present: an empty list says every path the run
-        // read was under `root`, which is the containment claim the help text makes.
-        refused: [...refused],
-        // One row per inspected asset by default; the flat per-issue list under
-        // `--verbose`. Either way every `location` stays relative to `root` above.
-        issues: verbose === true ? issues : summarizeIssuesByLocation(issues),
-        // Counts ride beside the status: `status` names only the worst ACTIONABLE
-        // severity, so an info-only run is `success` and the info would otherwise
-        // be unreported.
-        issueCounts,
-        summary: bailSummary
-            ?? `${issueCounts.errors} error(s), ${issueCounts.warnings} warning(s), ${issueCounts.info} info`,
-        duration,
-    };
+    return buildReport({
+        examined: pluginEntriesExamined(marketplace, pluginResults),
+        findings,
+        data: {
+            // Stated once, and the only absolute path in the document.
+            root,
+            marketplace: marketplaceData(marketplace),
+            plugins,
+            // Named, not graded — see `validateDeclaredPlugins`. Always present, so an
+            // empty list is a statement that `plugins/` was looked at.
+            undeclared: [...undeclared],
+            // Paths the walk would not open (real path outside the root) — see
+            // `WalkBoundary`. Always present: an empty list says every path the run
+            // read was under `root`, which is the containment claim the help text makes.
+            refused: [...refused],
+        },
+        gate: GATE,
+        durationMs: input.durationMs,
+    });
 }
 /**
  * The refusal for a run in which a declared local source did not resolve.
@@ -570,10 +657,10 @@ export function buildMarketplaceValidateReport(input) {
  * @param refused - Root-relative paths the walk would not open
  * @returns The one finding, or nothing
  */
-function unfinishedRunFinding(marketplace, validated, refused) {
+function unfinishedRunFinding(marketplace, validated, refused, unread) {
     const declared = marketplace?.localPluginSources ?? [];
     const unresolved = declared.filter((entry) => !validated.some((v) => v.name === entry.name && v.source === entry.source));
-    if (unresolved.length === 0 && refused.length === 0)
+    if (unresolved.length === 0 && refused.length === 0 && unread.length === 0)
         return [];
     const parts = [];
     if (unresolved.length > 0) {
@@ -596,17 +683,46 @@ function unfinishedRunFinding(marketplace, validated, refused) {
             + ' they hold — this command never leaves the directory it was pointed at. Replace each link'
             + ' with the files it points at, or move its target under the marketplace root.');
     }
+    if (unread.length > 0) {
+        const named = unread.map((path) => `\`${path}\``).join(', ');
+        parts.push(`The operating system refused to let this run read ${unread.length} path(s) inside a validated plugin: ${named}`
+            + ' (the SCAN_PATH_UNREADABLE finding beside each names the errno). Nothing behind them was'
+            + ' checked — a plugin.json\'s manifest checks, a skill\'s SKILL.md checks — so this document is'
+            + ' not a verdict about them. Make each path readable — check its permissions and ownership — and re-run.');
+    }
     return [runIntegrityFinding(parts.join(' '))];
 }
 /**
- * Validate a marketplace and hand back its document and exit code, printing
- * nothing on stdout.
+ * The root-relative manifest of every plugin row whose manifest was not read
+ * for a reason OTHER than a link out of the root — those are already named in
+ * `refused`. Derived from the document's own rows, like the rest of the refusal.
+ */
+function unreadManifests(pluginResults, refused, root) {
+    const manifests = pluginResults
+        .filter((row) => !row.manifestRead)
+        .map((row) => toForwardSlash(safePath.join(relativizePath(row.result.path, root), '.claude-plugin', 'plugin.json')))
+        .filter((manifest) => !refused.includes(manifest));
+    return [...new Set(manifests)];
+}
+/** The human half, on stderr: every error in full, and the rest under `--verbose`. */
+function logFindings(report, verbose, logger) {
+    for (const finding of report.findings) {
+        if (!verbose && finding.severity !== 'error' && finding.code !== RUN_INTEGRITY_CODE)
+            continue;
+        const anchor = finding.location === undefined ? '' : `${finding.location}: `;
+        logger.error(`  ${anchor}${finding.severity}: ${finding.message} [${finding.code}]`);
+    }
+    const { errors, warnings, info } = report.summary;
+    logger.info(`${errors} error(s), ${warnings} warning(s), ${info} info`);
+}
+/**
+ * Validate a marketplace and hand back its report, printing nothing on stdout.
  *
  * The phase entry point for `vat verify`, which runs this once per configured
- * marketplace IN ITS OWN PROCESS. Progress and findings still go to stderr as
- * they always did; only the decision of where the document lands moves to the
- * caller — stdout for a command-line run, `phases[].report` for an orchestrated
- * one.
+ * marketplace, and the command's own. The report is the one BEFORE the
+ * writer's run-integrity pass: inside an orchestrator, `runPhase` applies the same
+ * pass to this phase's report, by the declaration this verb gives its own writer. A refusal is the envelope's error
+ * branch, its message already on stderr.
  */
 export async function runMarketplaceValidatePhase(targetPath, options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
@@ -614,39 +730,54 @@ export async function runMarketplaceValidatePhase(targetPath, options) {
     try {
         const marketplacePath = safePath.resolve(targetPath ?? '.');
         logger.info(`Validating marketplace: ${marketplacePath}`);
-        const { marketplaceResult, pluginResults, undeclared, refused, issues } = await collectMarketplaceFindings(marketplacePath, logger);
-        // A bailed run reports WHY it stopped; a completed run reports what it
-        // found. Both emit through the one builder, so the document has a single
-        // shape either way.
-        const bailed = marketplaceResult.status === 'error';
-        const document = buildMarketplaceValidateReport({
+        const { marketplaceResult, pluginResults, undeclared, refused, unread, issues } = await collectMarketplaceFindings(marketplacePath, logger);
+        const report = buildMarketplaceValidateReport({
             root: marketplacePath,
             marketplace: marketplaceResult.metadata,
             pluginResults,
             undeclared,
             refused,
+            unread,
             issues,
-            ...(bailed ? { bailSummary: marketplaceResult.summary } : {}),
-            duration: formatDuration(Date.now() - startTime),
-            verbose: options.verbose === true,
+            durationMs: Date.now() - startTime,
         });
-        // From the DOCUMENT, so the exit code and the published status are one
-        // derivation — the run-integrity refusal lands in the builder, and an exit
-        // code computed upstream of it would answer 0 over `status: error`.
-        return { document, exitCode: document.status === 'error' ? 1 : 0 };
+        logFindings(report, options.verbose === true, logger);
+        return { report };
     }
     catch (error) {
-        return {
-            document: reportCommandError(error, logger, startTime, 'MarketplaceValidate'),
-            exitCode: 2,
-            failed: true,
-        };
+        return { report: refusedReport(error) };
     }
 }
+/** The error branch for a run that could not do its job — classified by code, never by message. */
+function refusedReport(error) {
+    return refusalReport(refusalCodeOf(error), error, GATE, NOTHING_FINISHED);
+}
+/**
+ * The command lane: the operator's `[path]` is judged before anything runs.
+ *
+ * A path naming nothing is the invocation's mistake (`USAGE_INVALID`); one the
+ * OS will not list is the input's (`INPUT_UNREADABLE`). Neither is a finding
+ * about a marketplace. Only the TYPED argument is judged: `vat verify` hands
+ * the phase a path it computed (`dist/.claude/plugins/marketplaces/<name>`),
+ * where an absent directory is an unbuilt marketplace — a finding about the
+ * project (`MARKETPLACE_MISSING_MANIFEST`), not an invocation mistake.
+ */
 async function marketplaceValidateCommand(targetPath, options) {
-    // `undefined`: this command offers no `--format`, so its failure envelope is
-    // YAML like its report.
-    finishCommand(await runMarketplaceValidatePhase(targetPath, options), writeYamlOutput, undefined);
+    let report;
+    try {
+        const marketplacePath = assertReadableDirectoryArgument(targetPath ?? '.');
+        ({ report } = await runMarketplaceValidatePhase(marketplacePath, options));
+    }
+    catch (error) {
+        // Only the argument check throws here: the phase returns its own refusals.
+        report = refusedReport(error);
+    }
+    const published = publishedReport('claude marketplace validate', report);
+    // The writer's own zero-examined refusal, warned in the lane that publishes it.
+    if (published !== report)
+        warnRunIntegrity(published);
+    // This command offers no `--format`: its document is YAML.
+    endWithReport('claude marketplace validate', published, 'yaml');
 }
 export function createMarketplaceValidateCommand() {
     const command = new Command('validate');
@@ -654,7 +785,7 @@ export function createMarketplaceValidateCommand() {
         .description('Validate a marketplace directory for publishing')
         .argument('[path]', 'Path to marketplace directory (default: current directory)')
         .option('-d, --debug', 'Enable debug logging')
-        .option('-v, --verbose', 'Show all scanned resources, including those without issues')
+        .option('-v, --verbose', 'Print every finding in full on stderr, not only the errors')
         .action(marketplaceValidateCommand)
         .addHelpText('after', `
 Description:
@@ -663,40 +794,53 @@ Description:
 
   Plugin versions are required (error, not warning) in strict marketplace validation.
 
-Output (YAML on stdout):
-  root: the marketplace directory — every location below is relative to it
-  status, issueCounts, summary, duration, marketplace, plugins
-  pluginsValidated: how many of the manifest's relative-path sources
-          (marketplace.localPluginSources) resolved to a directory and were
-          validated — each plugins[] row names the entry it satisfies. A
-          declared source that does not resolve is reported as
-          RESOURCE_CHECK_BROKEN at error (exit 1), naming it, rather than as
-          a pass — a plugin the manifest ships and this run never saw is not
-          a verdict. A source is never followed outside the root: an absolute
-          path or a ".." segment fails the manifest schema, and a symlink that
-          points out is refused like an unresolved source. Co-located
-          marketplaces (source: "./") are validated at the root. An
-          all-remote marketplace has nothing local and stays green.
-  undeclared: directories under plugins/ that no manifest entry names.
+Output (YAML on stdout — the report envelope):
+  status: ok | findings | error. findings means at least one finding was
+          published; error means the run did not finish (error.code says why).
+  examined: the plugin entries validated — every remote entry of
+          marketplace.json plus each declared local plugin the walk reached.
+  summary: the findings by severity.
+  findings[]: every finding, flat — {code, severity, message, location, …};
+          location is relative to data.root.
+  data.root: the marketplace directory — every path in the document is
+          relative to it.
+  data.marketplace: the manifest's name, version, pluginEntries and
+          localPluginSources; null when the manifest is missing or invalid.
+  data.plugins[]: one row per declared local plugin walked — {name, source,
+          path, manifestRead, status, summary}. A declared source that does
+          not resolve is reported as RESOURCE_CHECK_BROKEN at error (exit 1),
+          naming it, rather than as a pass — a plugin the manifest ships and
+          this run never saw is not a verdict. A source is never followed
+          outside the root: an absolute path or a ".." segment fails the
+          manifest schema, and a symlink that points out is refused like an
+          unresolved source. Co-located marketplaces (source: "./") are
+          validated at the root. An all-remote marketplace has nothing local
+          to walk; its entries still count as examined.
+  data.undeclared: directories under plugins/ that no manifest entry names.
           Listed only — they cannot be installed, so they are neither
           validated nor a failure.
-  refused: paths inside a validated plugin this run would not open because
-          they resolve outside the root (a skills/ dir, skill dir, SKILL.md
-          or plugin.json that is a symlink pointing out). Containment is by
-          real path at every depth, not only at the declared source; each is
-          named here and in the RESOURCE_CHECK_BROKEN finding (exit 1).
-
-  issues: one row per inspected location, carrying only that location's counts
-          ({location, errors?, warnings?, info?, codes}). A zero bucket is
-          omitted, and a location with no findings has no row.
+  data.refused: paths inside a validated plugin this run would not open
+          because they resolve outside the root (a skills/ dir, skill dir,
+          SKILL.md or plugin.json that is a symlink pointing out). Containment
+          is by real path at every depth, not only at the declared source;
+          each is named here and in the RESOURCE_CHECK_BROKEN finding (exit 1).
+          A plugin.json the OS will not read is the same: its row is
+          manifestRead: false and the RESOURCE_CHECK_BROKEN finding names it
+          (exit 1) beside the SCAN_PATH_UNREADABLE warning — never a pass. So
+          is a plugin's skills/ directory the OS will not list, or a skill
+          directory or SKILL.md it will not stat or read: named in that
+          finding (exit 1), each beside its SCAN_PATH_UNREADABLE warning.
 
-  --verbose replaces those rows with the flat per-issue list (message, fix and
-  all). That form is for '> file' then grep, not for reading.
+  stderr prints every error in full; --verbose adds every warning and info.
+  The document is the same either way.
 
-Exit Codes:
-  0 - All validations passed (warnings allowed)
-  1 - Validation errors found
-  2 - System error (directory not found, etc.)
+Exit Codes (derived from the document):
+  0 - status ok, or findings with no error-severity finding
+  1 - status findings with at least one error-severity finding (including a
+      marketplace declaring no plugin entry: nothing was examined)
+  2 - status error: the run did not finish — USAGE_INVALID for a path that
+      does not exist or is not a directory, INPUT_UNREADABLE for one the OS
+      will not list
 
 Example:
   $ vat claude marketplace validate .         # Validate current directory