@vibe-agent-toolkit/cli 0.1.41-rc.7 → 0.1.41

package/dist/commands/audit/distributed-tree.js

@@ -0,0 +1,319 @@
+/**
+ * "Is this tree repository SOURCE, or an artifact somebody published?"
+ *
+ * `vat audit` needs an answer before it can run the presence-side detectors —
+ * `PACKAGED_AGENT_INSTRUCTION_FILE` above all — because the same `CLAUDE.md`
+ * means opposite things on the two sides of that line. Sitting beside a source
+ * `SKILL.md` in a working repo it is ordinary repo guidance that ships nowhere;
+ * sitting in a built bundle or an installed plugin it demonstrably travelled to
+ * a consumer.
+ *
+ * ## The discriminator this replaced, and why it was wrong
+ *
+ * The first answer was "does the project's `vibe-agent-toolkit.config.yaml`
+ * declare this SKILL.md, matched by absolute path?" — no match meant the tree
+ * had been handed to us. Two ordinary cases falsify that inference, and both
+ * were observed on adopter fixtures:
+ *
+ * - **A repo that has not adopted VAT at all** has no config, so nothing is
+ *   declared. `vat audit` on a fresh repo is the first command a new user runs,
+ *   and it greeted them with a warning whose first remedy is "remove the file,
+ *   or move it outside the directory that is packaged" — about guidance that
+ *   ships nowhere.
+ * - **An adopting repo whose `include` globs do not enumerate every skill
+ *   directory in the tree** — drafts, vendored copies, test fixtures. Not being
+ *   named by a glob is not evidence of publication.
+ *
+ * ## What replaced it
+ *
+ * Two observable facts about where the file actually LIVES, in this order:
+ *
+ * 1. **Inside a Claude install root** (`plugins/`, `skills/`, `marketplaces/`
+ *    under `$CLAUDE_CONFIG_DIR` or `~/.claude`) — the directories whose entire
+ *    purpose is holding artifacts an installer put there. This clause wins over
+ *    the git test below, and it must: Claude Code installs a marketplace by
+ *    `git clone`, so an installed tree's files are TRACKED SOURCE — of somebody
+ *    else's repository. For a git-distributed plugin, tracked source *is* what
+ *    ships, which is precisely how a scaffold template like Anthropic's
+ *    `dataverse` `templates/CLAUDE.md` reaches every consumer. Judging that tree
+ *    by tracked-ness would silence the dominant audited population.
+ *
+ *    Both halves of that sentence are statements about somebody else's product,
+ *    and clause 1 outranking clause 2 rests on them. No test in this repo can
+ *    contradict either — they can only be re-read:
+ *
+ * @vendor-claim reviewed=2026-08-02 verify=Install a marketplace with /plugin marketplace add and confirm ~/.claude/plugins/marketplaces/<name> is a git working copy; confirm dataverse still ships templates/CLAUDE.md
+ *
+ * 2. **Not git-visible source** — the `SKILL.md` is gitignored, or it lies
+ *    outside any git repository. A built `dist/` bundle is gitignored; an
+ *    unpacked tarball is outside a repo; a working tree's skill is neither.
+ *
+ * Neither clause consults the project's config, and neither is CONDITIONAL on it:
+ * `vat audit` asks this question in its config-aware lane exactly as it does in
+ * its wild one. The config-declaration test was not merely replaced inside this
+ * module — it also had to stop gating whether this module is reached, or it
+ * survives at the caller in its purest form, where it can only suppress.
+ *
+ * Untracked-but-not-ignored is deliberately SOURCE, not "distributed": that is
+ * a skill the author has written and not yet committed, and treating authoring
+ * in progress as a distribution artifact would make the first audit of a new
+ * skill the loudest one. `GitTracker`'s active set (`git ls-files --cached
+ * --others --exclude-standard`) answers exactly this three-way question in O(1),
+ * which is why this module reuses it rather than adding a second git-status path.
+ *
+ * Deliberately NOT inferred from a `dist/` path substring or from a bundle's
+ * frontmatter `name`: both assert a cause the code cannot observe, and adopter
+ * output directories vary. Location under an install root is not that kind of
+ * guess — it is the same directory constant the `--user` scan itself is defined
+ * by, resolved from {@link getClaudeUserPaths}.
+ *
+ * ## Known limits, both deliberate
+ *
+ * - A skill the author writes IN PLACE under `~/.claude/skills/` and keeps in a
+ *   dotfiles repo is reported, because it is indistinguishable by location from
+ *   an installed one. The install root is what a consumer's Claude reads from;
+ *   a skill living there is being consumed either way.
+ * - A third-party skills repo audited by `vat audit <git-url>` is a clone, so
+ *   its skills read as source and stay silent. That is consistent: auditing
+ *   somebody's repo source is the same situation as auditing your own. A
+ *   third-party *plugin* still reports, because the plugin lane crawls the whole
+ *   plugin tree independently of this classifier.
+ *
+ * ## When git cannot be consulted
+ *
+ * Clause 2 is only as good as git's willingness to answer, and `gitLsFiles`
+ * returns the same `null` for a missing binary, a corrupt `.git` and an
+ * unreadable one. That `null` used to arrive here as "not ignored" — i.e. source,
+ * i.e. silence — so the detector switched itself off and the run still reported
+ * `status: success` with nothing to indicate why. This module therefore has a
+ * third answer, `'indeterminate'`, and reports it (see
+ * {@link distributedTreeFindings}) rather than guessing in either direction.
+ */
+import { detectPackagedAgentInstructionFiles, materializeIssue } from '@vibe-agent-toolkit/agent-skills';
+import { getClaudeUserPaths } from '@vibe-agent-toolkit/claude-marketplace';
+import { gitFindRoot, GitTracker, issueLocation, normalizePath, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
+/** Cache of (gitRoot → initialized GitTracker) to avoid re-spawning ls-files. */
+const gitTrackerCache = new Map();
+/**
+ * Get (or build) the pre-populated tracker for one git root.
+ *
+ * Shared with `resolveScanContext` in audit.ts so a run pays for `git ls-files`
+ * once per repository, whether the caller wants scan-time gitignore filtering or
+ * the provenance answer below.
+ */
+export async function getOrCreateGitTracker(gitRoot) {
+    const cached = gitTrackerCache.get(gitRoot);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const tracker = new GitTracker(gitRoot);
+    await tracker.initialize();
+    gitTrackerCache.set(gitRoot, tracker);
+    return tracker;
+}
+/**
+ * Cache of (canonical SKILL.md path → verdict).
+ *
+ * The walk asks the same question about the same skill twice: once to decide
+ * whether this skill's crawl OWNS the subtree below it (see
+ * {@link crawlOwnsSubtree}) and once when the crawl runs. Both answers derive
+ * from filesystem and git state, which is fixed for the duration of one audit —
+ * so it is memoized rather than re-derived, and cleared alongside the tracker it
+ * is derived from, which is what every reset path already calls.
+ */
+const provenanceCache = new Map();
+/** Clear the per-root tracker cache (see `resetAuditCaches`). */
+export function resetGitTrackerCache() {
+    gitTrackerCache.clear();
+    provenanceCache.clear();
+}
+/**
+ * The silent verdict, spelled once.
+ *
+ * Three call sites now test for it — the two clauses that return it and
+ * {@link crawlOwnsSubtree}, which is defined as "not this" — and a verdict
+ * literal that drifts in one of them fails open.
+ */
+const REPO_SOURCE = 'repo-source';
+/**
+ * One canonical, forward-slashed spelling of a path — symlinks resolved, and on a
+ * case-insensitive filesystem (macOS, NTFS) the case as it is stored on disk.
+ *
+ * Every comparison in this module goes through it, and both sides of every
+ * comparison do, because two unrelated defects follow from comparing paths as the
+ * caller happened to spell them:
+ *
+ * - `~/.claude` is very often a SYMLINK into a dotfiles checkout. Auditing that
+ *   checkout by its real path missed the install-root clause entirely: the same
+ *   physical files, two verdicts, decided by which spelling was typed.
+ * - `GitTracker`'s active set is keyed by exact string while the `existsSync`
+ *   qualifier beside it is case-INsensitive, so `<repo>/Skills/demo/SKILL.md`
+ *   read as "absent from the set and present on disk" ⇒ ignored ⇒ distributed:
+ *   a false finding against tracked source, reachable by tab-completion.
+ *
+ * Canonicalising the SKILL.md before deriving the git root is what keeps the
+ * second fix honest — the tracker's own keys are built from the root it is given,
+ * so a canonical lookup against a non-canonical root would miss every time.
+ */
+function canonicalPath(filePath) {
+    return toForwardSlash(normalizePath(safePath.resolve(filePath)));
+}
+/**
+ * True when `absolutePath` is `root` or lies beneath it.
+ *
+ * Both sides are put through {@link toForwardSlash} first: a Windows caller can
+ * hand us a backslash path, and a prefix test across mixed separators reports a
+ * sibling directory as "outside" — the exact shape that would quietly turn this
+ * whole clause off on one platform.
+ *
+ * Exported because `audit.ts` asks the same containment question of the same
+ * kind of path when deciding which crawl owns a subtree; a second spelling of a
+ * prefix test is how the separator bug gets reintroduced on one side only.
+ */
+export function isWithin(root, absolutePath) {
+    const normalizedRoot = toForwardSlash(root);
+    const normalizedPath = toForwardSlash(absolutePath);
+    return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
+}
+/**
+ * Is this path inside one of the directories Claude installs packages INTO?
+ *
+ * Resolved per call, never memoized at module load: `CLAUDE_CONFIG_DIR` is an
+ * environment variable the operator (and every test fixture) is entitled to
+ * change between runs, and a cached answer would describe the wrong machine.
+ */
+function isUnderClaudeInstallRoot(canonicalAbsolutePath) {
+    const { pluginsDir, skillsDir, marketplacesDir } = getClaudeUserPaths();
+    // marketplacesDir is nested under pluginsDir; listed anyway so the set reads as
+    // the three install destinations rather than as an accident of layout.
+    return [pluginsDir, skillsDir, marketplacesDir].some((dir) => isWithin(canonicalPath(dir), canonicalAbsolutePath));
+}
+/**
+ * Classify the tree holding `skillMdPath`. See this module's header for the
+ * reasoning behind each clause and the order they are applied in.
+ */
+export async function classifyScannedSkillTree(skillMdPath) {
+    const absolute = canonicalPath(skillMdPath);
+    const memoized = provenanceCache.get(absolute);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    const verdict = await classifyUncached(absolute);
+    provenanceCache.set(absolute, verdict);
+    return verdict;
+}
+/** {@link classifyScannedSkillTree}'s clauses, on an already-canonical path. */
+async function classifyUncached(absolute) {
+    if (isUnderClaudeInstallRoot(absolute)) {
+        return 'distributed';
+    }
+    const gitRoot = gitFindRoot(safePath.resolve(absolute, '..'));
+    if (gitRoot === null) {
+        return 'distributed';
+    }
+    const tracker = await getOrCreateGitTracker(gitRoot);
+    // Fail CLOSED. `isIgnoredByActiveSet` cannot distinguish "git says this file is
+    // tracked" from "git was never asked", and both come back `false` ⇒
+    // `'repo-source'` ⇒ silence. So the detector used to switch itself off — with a
+    // green status and no diagnostic — whenever `git` was missing from `PATH` or the
+    // repository's `.git` was corrupt or unreadable. Ask whether git answered before
+    // reading anything into its answer.
+    if (!tracker.isUsable()) {
+        return 'indeterminate';
+    }
+    return tracker.isIgnoredByActiveSet(absolute) ? 'distributed' : REPO_SOURCE;
+}
+/**
+ * Will a crawl rooted at this SKILL.md's directory actually report the WHOLE
+ * subtree beneath it — nested skills included?
+ *
+ * The question the directory walk needs before it descends, and it is not the
+ * same as "is there a SKILL.md here". {@link distributedTreeFindings} matches at
+ * any depth, so a distributed (or unclassifiable) skill's crawl covers every
+ * descendant and they must stand down or one file is counted once per ancestor.
+ * A `repo-source` skill's crawl does not run at all, so standing its descendants
+ * down would convert a double count into silence — and provenance is NOT
+ * monotone down a tree: a gitignored bundle can sit inside a tracked source
+ * skill, and a scan rooted above `<claudeDir>/skills` reaches an install root
+ * from outside one.
+ */
+export async function crawlOwnsSubtree(skillMdPath) {
+    return (await classifyScannedSkillTree(skillMdPath)) !== REPO_SOURCE;
+}
+/**
+ * The tree's own directory, spelled as a location a reader can act on.
+ *
+ * `issueLocation` is `path.relative`, so it answers `''` when the subject IS the
+ * anchor — and that is not an exotic case here, it is the ORDINARY
+ * `vat audit <bundle-path>` invocation: the audited target and the tree are the
+ * same directory. `''` then reached the report as `location: ""` and, interpolated
+ * into the detail below, produced `( (1 agent-instruction file(s) …))` — an empty
+ * positional part that reads as a rendering bug. `.` is that same directory
+ * spelled as something a consumer can open, resolve and glob.
+ *
+ * Fixed HERE rather than inside `issueLocation` deliberately. `issueLocation` is
+ * a relativizer shared by ~20 producers, and only its CALLER knows whether "the
+ * anchor root itself" is a subject its findings can have; for the producers that
+ * anchor a file against a containing directory, subject-equals-anchor cannot
+ * happen at all. The sibling `Location: (validation.allow.<CODE>)` findings look
+ * like this defect and are NOT it: those are `ALLOW_UNUSED`/`ALLOW_EXPIRED` meta
+ * issues that carry no `location` whatsoever (only a `field` pointing into the
+ * project config), which `formatIssueAnchor` renders as `(field)` on purpose.
+ *
+ * @see `anchoredPath` in `agent-skills/src/files-config.ts` and the `|| '.'` in
+ *   `cli/src/commands/claude/plugin/plugin-files.ts` — the same fallback, spelled
+ *   twice already. Consolidating all three into one utils-level helper is a wider
+ *   change than this fix.
+ */
+function treeLocation(treeRoot, locationRoot) {
+    return issueLocation(treeRoot, locationRoot) || '.';
+}
+/**
+ * The agent-instruction files present in a skill's own directory, when that
+ * directory is a distributed tree. Empty otherwise — including when the caller
+ * says a plugin lane already owns this subtree.
+ *
+ * `[]` declared dests, from BOTH callers, including the config-aware one that does
+ * hold a `files:` block. The parameter takes skill-OUTPUT-relative dests, and the
+ * tree crawled here is not an output tree — it is wherever the SKILL.md lives, so
+ * a `dest` and a path relative to this root are two different coordinate systems.
+ * Feeding dests in would exempt by accidental basename agreement and mislabel it
+ * as intent. `vat verify` is the lane that maps a built bundle back to the config
+ * that produced it, with both sides in output coordinates, and it applies the
+ * explicit-`files:` exemption there — which is what
+ * `PACKAGED_AGENT_INSTRUCTION_FILE`'s own remediation already tells readers.
+ *
+ * @param crawlTree `false` when a plugin lane already crawled this subtree.
+ *   REQUIRED and never defaulted, because the wrong answer is silent in both
+ *   directions: a skill nested inside a plugin is already crawled by
+ *   `validatePlugin` at any depth, so crawling again reports one file twice,
+ *   while omitting it for a standalone bundle is the blindness this pass exists
+ *   to end.
+ */
+export async function distributedTreeFindings(skillPath, locationRoot, crawlTree) {
+    if (!crawlTree)
+        return [];
+    const provenance = await classifyScannedSkillTree(skillPath);
+    if (provenance === REPO_SOURCE)
+        return [];
+    const treeRoot = safePath.resolve(skillPath, '..');
+    const present = detectPackagedAgentInstructionFiles(treeRoot, locationRoot, []);
+    if (provenance === 'distributed')
+        return present;
+    // Provenance is unknown. Report the unknown, not the files: calling them
+    // packaged would assert that they travelled to a consumer, which is exactly the
+    // fact that could not be established. And say nothing at all when the tree holds
+    // none — with nothing to classify, no answer was lost, and a healthy git would
+    // have been silent here too. That keeps the notice proportional to the actual
+    // ambiguity instead of warning once per skill across a git-less container.
+    if (present.length === 0)
+        return [];
+    const location = treeLocation(treeRoot, locationRoot);
+    return [
+        materializeIssue('TREE_PROVENANCE_INDETERMINATE', {
+            location,
+            detail: `${location} (${present.length} agent-instruction file(s) found, unclassified)`,
+        }),
+    ];
+}
+//# sourceMappingURL=distributed-tree.js.map

package/dist/commands/audit/distributed-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distributed-tree.js","sourceRoot":"","sources":["../../../src/commands/audit/distributed-tree.ts"],"names":[],"mappings":"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"}

package/dist/commands/audit.d.ts

@@ -31,6 +31,32 @@ export interface VATProjectContext {
  * Top-level command: vat audit [path]
  */
 export declare function createAuditCommand(): Command;
+/**
+ * Which of the Claude install roots a `--user` run actually walks.
+ *
+ * The three roots read as siblings and are NOT: `marketplacesDir` is
+ * `<claudeDir>/plugins/marketplaces`, i.e. INSIDE `pluginsDir`. A recursive walk
+ * of `plugins/` already reaches every installed marketplace, so scanning
+ * `marketplaces/` afterwards audited each marketplace-installed plugin and skill
+ * a SECOND time, in a second result, under the identical `path:`. On one real
+ * machine that turned 7 distinct agent-instruction files into 12 reported rows —
+ * and it inflates every finding class, not one code, because the whole subject
+ * is re-audited rather than one detector re-firing.
+ *
+ * The containment test is `isWithin`, the same one the provenance classifier
+ * uses, so "inside" means the same thing on both sides and on Windows.
+ *
+ * Gated on `recursive`, and that is not defensive dressing: under
+ * `--no-recursive` a walk of `plugins/` stops at its top level and never reaches
+ * `marketplaces/`, so dropping the nested root there would replace a double
+ * count with no coverage at all.
+ *
+ * Pure, and exported for that reason: the shape of the defect is "the list of
+ * roots was wrong", which is assertable as a list.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export declare function userScanTargets(candidates: readonly string[], recursive: boolean): string[];
 /**
  * The invocation scan root: the ONE base every `path` and `location` in a
  * report is expressed relative to.
@@ -78,6 +104,11 @@ export declare function getValidationResults(scanPath: string, recursive: boolea
  * Non-plugin results are skipped silently.
  * When effectiveSettings is provided, also runs settings conflict detection.
  *
+ * `locationRoot` is the invocation scan root: the ONE base every emitted
+ * evidence `location.file` is relative to. One audit run spans many plugin
+ * directories, so anchoring evidence at each plugin would mix coordinate
+ * systems in a single document.
+ *
  * When vatContext is provided, config-layer `targets` declarations are
  * threaded through to the analyzer so `vat audit .` inside a VAT project
  * matches `vat skills validate` verdicts. See
@@ -85,7 +116,7 @@ export declare function getValidationResults(scanPath: string, recursive: boolea
  *
  * @internal Exported for integration testing only — not part of the public CLI API.
  */
-export declare function runCompatAnalysis(results: ValidationResult[], logger: ReturnType<typeof createLogger>, effectiveSettings?: EffectiveSettings, vatContext?: VATProjectContext | null): Promise<Map<string, CompatibilityResult>>;
+export declare function runCompatAnalysis(results: ValidationResult[], logger: ReturnType<typeof createLogger>, locationRoot: string, effectiveSettings?: EffectiveSettings, vatContext?: VATProjectContext | null): Promise<Map<string, CompatibilityResult>>;
 declare function calculateSummary(results: ValidationResult[], startTime: number, compatMap: Map<string, CompatibilityResult> | undefined, verbose: boolean, root: string): {
     files: (ValidationResult & {
         compatibility?: CompatibilityResult;
@@ -96,6 +127,43 @@ declare function calculateSummary(results: ValidationResult[], startTime: number
     duration: string;
     root: string;
 };
+/**
+ * The stderr findings report for a set of audit results — the HUMAN channel.
+ *
+ * Deliberately NOT the YAML document. `vat audit` publishes a machine-readable
+ * report on stdout that CI and tooling parse, and that document carries every
+ * finding at every verbosity; this stream is read by a person, and on a 90-skill
+ * corpus it printed 26,480 lines, 3,480 of them occurrences of a single
+ * high-cardinality warning code. The two channels answer different questions, so
+ * only this one collapses.
+ *
+ * Which findings render in full is not decided here — it is
+ * {@link issuesToRenderAtVerbosity}, shared with the other findings-reporting
+ * verbs so `vat audit`, `vat skills validate` and `vat skills build` cannot drift
+ * onto three answers again. Errors always render; warnings and info collapse
+ * unless `verbose`; allow-listed findings never render.
+ *
+ * The severity breakdown on each file's heading is load-bearing, not decoration.
+ * For a warning-only file at default verbosity that heading is the ENTIRE report
+ * for that file, so dropping the counts would turn the collapse into silence —
+ * the failure direction `issue-rendering.ts` exists to prevent. The trailing
+ * line names the collapsed total and both ways to see it, for the same reason.
+ *
+ * That trailing line points at THIS audit's YAML report, deliberately — do not
+ * broaden it back into a claim about "the YAML report" in general. It is only
+ * true of the verbs that emit full `issues:` arrays, and which verbs those are
+ * has changed: `vat skills build` now publishes them too, so the sentence is
+ * shared rather than re-spelled (see `formatCollapsedFindingsHint`, which takes
+ * the report name for exactly this reason). Any verb that publishes counts alone
+ * must still not use it — there, it would send a CI consumer to a document that
+ * cannot answer the question.
+ *
+ * Pure: takes results, returns lines. It reads `issues` and never rewrites it,
+ * because `runAuditAtPath` builds the YAML document from the very same array.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export declare function formatAuditFindingsLines(results: readonly ValidationResult[], root: string, verbose: boolean): string[];
 /**
  * Reset all module-level audit caches. Must be called at the start of every
  * independent audit invocation so in-process callers (CLI entrypoint AND

package/dist/commands/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"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"}