@vibe-agent-toolkit/cli 0.1.34-rc.2 → 0.1.34

package/dist/commands/corpus/seed.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Seed schema + parser for `corpus/seed.yaml`. The seed is the committed
+ * config of plugins tracked by `vat corpus scan`. Per-entry `validation:`
+ * mirrors the `skills.defaults.validation` block of the project config
+ * schema (severity overrides + allow entries).
+ */
+import { z } from 'zod';
+declare const ValidationAllowEntrySchema: z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    reason: string;
+}, {
+    code: string;
+    reason: string;
+}>;
+declare const ValidationBlockSchema: z.ZodObject<{
+    severity: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["error", "warning", "info", "ignore"]>>>;
+    allow: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        reason: string;
+    }, {
+        code: string;
+        reason: string;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    allow?: {
+        code: string;
+        reason: string;
+    }[] | undefined;
+    severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+}, {
+    allow?: {
+        code: string;
+        reason: string;
+    }[] | undefined;
+    severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+}>;
+declare const PluginEntrySchema: z.ZodObject<{
+    source: z.ZodString;
+    name: z.ZodString;
+    validation: z.ZodOptional<z.ZodObject<{
+        severity: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["error", "warning", "info", "ignore"]>>>;
+        allow: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            reason: string;
+        }, {
+            code: string;
+            reason: string;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        allow?: {
+            code: string;
+            reason: string;
+        }[] | undefined;
+        severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+    }, {
+        allow?: {
+            code: string;
+            reason: string;
+        }[] | undefined;
+        severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    source: string;
+    validation?: {
+        allow?: {
+            code: string;
+            reason: string;
+        }[] | undefined;
+        severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+    } | undefined;
+}, {
+    name: string;
+    source: string;
+    validation?: {
+        allow?: {
+            code: string;
+            reason: string;
+        }[] | undefined;
+        severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+    } | undefined;
+}>;
+declare const SeedSchema: z.ZodObject<{
+    plugins: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        name: z.ZodString;
+        validation: z.ZodOptional<z.ZodObject<{
+            severity: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["error", "warning", "info", "ignore"]>>>;
+            allow: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                code: z.ZodString;
+                reason: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                reason: string;
+            }, {
+                code: string;
+                reason: string;
+            }>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        }, {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        source: string;
+        validation?: {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        } | undefined;
+    }, {
+        name: string;
+        source: string;
+        validation?: {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        } | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    plugins: {
+        name: string;
+        source: string;
+        validation?: {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        } | undefined;
+    }[];
+}, {
+    plugins: {
+        name: string;
+        source: string;
+        validation?: {
+            allow?: {
+                code: string;
+                reason: string;
+            }[] | undefined;
+            severity?: Record<string, "error" | "warning" | "info" | "ignore"> | undefined;
+        } | undefined;
+    }[];
+}>;
+export type ValidationAllowEntry = z.infer<typeof ValidationAllowEntrySchema>;
+export type ValidationBlock = z.infer<typeof ValidationBlockSchema>;
+export type PluginEntry = z.infer<typeof PluginEntrySchema>;
+export type Seed = z.infer<typeof SeedSchema>;
+/**
+ * Load and validate `corpus/seed.yaml` (or another seed-shaped YAML file).
+ * Throws on missing file, malformed YAML, schema violations, duplicate
+ * `source` keys, or duplicate `name` labels.
+ */
+export declare function loadSeedFile(path: string): Seed;
+export {};
+//# sourceMappingURL=seed.d.ts.map

package/dist/commands/corpus/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../src/commands/corpus/seed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,0BAA0B;;;;;;;;;EAG9B,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;EAKhB,CAAC;AAEZ,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASZ,CAAC;AAEZ,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIL,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAyB/C"}

package/dist/commands/corpus/seed.js

@@ -0,0 +1,63 @@
+/**
+ * Seed schema + parser for `corpus/seed.yaml`. The seed is the committed
+ * config of plugins tracked by `vat corpus scan`. Per-entry `validation:`
+ * mirrors the `skills.defaults.validation` block of the project config
+ * schema (severity overrides + allow entries).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import * as yaml from 'js-yaml';
+import { z } from 'zod';
+const ValidationAllowEntrySchema = z.object({
+    code: z.string().min(1),
+    reason: z.string().min(1),
+});
+const ValidationBlockSchema = z
+    .object({
+    severity: z.record(z.string(), z.enum(['error', 'warning', 'info', 'ignore'])).optional(),
+    allow: z.array(ValidationAllowEntrySchema).optional(),
+})
+    .strict();
+const PluginEntrySchema = z
+    .object({
+    source: z.string().min(1),
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[A-Za-z0-9_-]+$/, 'name must be [A-Za-z0-9_-]+ (presentation label)'),
+    validation: ValidationBlockSchema.optional(),
+})
+    .strict();
+const SeedSchema = z
+    .object({
+    plugins: z.array(PluginEntrySchema).min(1),
+})
+    .strict();
+/**
+ * Load and validate `corpus/seed.yaml` (or another seed-shaped YAML file).
+ * Throws on missing file, malformed YAML, schema violations, duplicate
+ * `source` keys, or duplicate `name` labels.
+ */
+export function loadSeedFile(path) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-supplied seed file path
+    if (!existsSync(path)) {
+        throw new Error(`Seed file not found: ${path}`);
+    }
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- caller-supplied seed file path
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = yaml.load(raw);
+    const seed = SeedSchema.parse(parsed);
+    const sources = new Set();
+    const names = new Set();
+    for (const entry of seed.plugins) {
+        if (sources.has(entry.source)) {
+            throw new Error(`Seed has duplicate source: ${entry.source}`);
+        }
+        if (names.has(entry.name)) {
+            throw new Error(`Seed has duplicate name: ${entry.name}`);
+        }
+        sources.add(entry.source);
+        names.add(entry.name);
+    }
+    return seed;
+}
+//# sourceMappingURL=seed.js.map

package/dist/commands/corpus/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../src/commands/corpus/seed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzF,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,KAAK,CAAC,kBAAkB,EAAE,kDAAkD,CAAC;IAChF,UAAU,EAAE,qBAAqB,CAAC,QAAQ,EAAE;CAC7C,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,UAAU,GAAG,CAAC;KACjB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3C,CAAC;KACD,MAAM,EAAE,CAAC;AAOZ;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,qGAAqG;IACrG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,qGAAqG;IACrG,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/commands/inventory.d.ts

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+export interface InventoryCommandOptions {
+    user?: boolean;
+    system?: boolean;
+    format?: 'yaml' | 'json';
+    shallow?: boolean;
+    debug?: boolean;
+}
+/**
+ * Create and configure the `vat inventory` command.
+ */
+export declare function createInventoryCommand(): Command;
+/**
+ * Action handler for `vat inventory [path]`.
+ */
+export declare function inventoryCommand(pathArg: string | undefined, options: InventoryCommandOptions): Promise<void>;
+//# sourceMappingURL=inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../src/commands/inventory.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,MAAM,WAAW,uBAAuB;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAgChD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/commands/inventory.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { serializeInventory, serializeInventoryShallow, } from '@vibe-agent-toolkit/agent-skills';
+import { extractClaudeInstallInventory, extractClaudeMarketplaceInventory, extractClaudePluginInventory, extractClaudeSkillInventory, getClaudeUserPaths, } from '@vibe-agent-toolkit/claude-marketplace';
+import { safePath } from '@vibe-agent-toolkit/utils';
+import { Command } from 'commander';
+import { handleCommandError } from '../utils/command-error.js';
+import { createLogger } from '../utils/logger.js';
+/**
+ * Create and configure the `vat inventory` command.
+ */
+export function createInventoryCommand() {
+    const command = new Command('inventory');
+    command
+        .description('Extract structural inventory of a plugin, marketplace, skill, or install root')
+        .argument('[path]', 'Path to inventory (directory or SKILL.md)')
+        .option('--user', 'Inventory the user-level Claude install (~/.claude/plugins)')
+        .option('--system', 'Inventory the system-level Claude install')
+        .option('--format <yaml|json>', 'Output format', 'yaml')
+        .option('--shallow', 'Omit nested inventories (paths only)')
+        .option('--debug', 'Verbose logging to stderr')
+        .action(inventoryCommand)
+        .addHelpText('after', `
+Description:
+  Extract and emit the structural inventory of a Claude plugin, marketplace,
+  skill, or install root. Outputs YAML to stdout by default. Runs no validation
+  detectors — pure structural enumeration.
+
+Output:
+  - schema: vat.inventory/v1alpha
+  - kind: marketplace | plugin | skill | install
+  - vendor: claude-code
+  - declared / discovered / references / unexpected (per kind)
+  - parseErrors: any manifest parse failures
+
+Exit Codes:
+  0 - Inventory extracted (parse errors surface in output, not as exit code)
+  2 - System error (path not found, --system not supported, etc.)
+
+Example:
+  $ vat inventory my-plugin/                # Inventory a single plugin
+`);
+    return command;
+}
+/**
+ * Action handler for `vat inventory [path]`.
+ */
+export async function inventoryCommand(pathArg, options) {
+    const logger = createLogger(options.debug === true ? { debug: true } : {});
+    const startTime = Date.now();
+    try {
+        const inv = await routeInventory(pathArg, options);
+        const format = options.format ?? 'yaml';
+        const out = options.shallow === true
+            ? serializeInventoryShallow(inv, format)
+            : serializeInventory(inv, format);
+        process.stdout.write(out);
+        process.exit(0);
+    }
+    catch (error) {
+        handleCommandError(error, logger, startTime, 'Inventory');
+    }
+}
+async function routeInventory(pathArg, options) {
+    if (options.user === true) {
+        return extractClaudeInstallInventory(getClaudeUserPaths());
+    }
+    if (options.system === true) {
+        throw new Error('--system inventory is not implemented in this version');
+    }
+    if (!pathArg) {
+        throw new Error('Path argument is required (or use --user / --system).');
+    }
+    const absolute = safePath.resolve(pathArg);
+    if (absolute.endsWith('SKILL.md') || absolute.endsWith('skill.md')) {
+        return extractClaudeSkillInventory(absolute);
+    }
+    const claudePluginDir = safePath.join(absolute, '.claude-plugin');
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- absolute is caller-resolved, used for presence check only
+    const hasMarketplace = existsSync(safePath.join(claudePluginDir, 'marketplace.json'));
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- absolute is caller-resolved, used for presence check only
+    const hasPlugin = existsSync(safePath.join(claudePluginDir, 'plugin.json'));
+    // A directory with marketplace.json but no plugin.json is a marketplace root.
+    // When both are present, the plugin extractor takes precedence (plugin is installed,
+    // marketplace.json is a cached metadata artifact alongside it).
+    if (hasMarketplace && !hasPlugin) {
+        return extractClaudeMarketplaceInventory(absolute);
+    }
+    return extractClaudePluginInventory(absolute);
+}
+//# sourceMappingURL=inventory.js.map

package/dist/commands/inventory.js.map

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

package/dist/utils/git-url.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Parsed representation of a git URL accepted by `vat audit`.
+ *
+ * - `cloneUrl` is the URL passed to `git clone` (after stripping ref/subpath
+ *   fragments and after expanding GitHub shorthand to a full HTTPS URL).
+ * - `ref` is an optional branch or tag name (deep commit SHAs are not
+ *   guaranteed to work with shallow clone — see design spec for details).
+ * - `subpath` is an optional subdirectory within the cloned repo to audit.
+ */
+export interface ParsedGitUrl {
+    cloneUrl: string;
+    ref?: string;
+    subpath?: string;
+}
+/**
+ * Parse a string into a {@link ParsedGitUrl}.
+ *
+ * Accepted forms:
+ *  - `https://host/owner/repo.git`
+ *  - `https://host/owner/repo.git#ref`
+ *  - `https://host/owner/repo.git#ref:subpath`
+ *  - `https://github.com/owner/repo/tree/<ref>/<subpath>` (GitHub web URL)
+ *  - `owner/repo` (GitHub shorthand → expanded to HTTPS)
+ *  - `git@host:owner/repo.git`
+ *  - `ssh://git@host/owner/repo.git`
+ *
+ * Throws on malformed input.
+ */
+export declare function parseGitUrl(input: string): ParsedGitUrl;
+/**
+ * Detect whether a string should be treated as a git URL (for the polymorphic
+ * `[git-url-or-path]` audit argument). True for:
+ *  - http(s):// URLs
+ *  - ssh:// URLs
+ *  - file:// URLs (used by integration tests against local bare repos)
+ *  - git@host:path scp-style URLs
+ *  - GitHub shorthand `owner/repo` (strict — no extensions, no extra slashes)
+ *
+ * Everything else (including relative paths like `./foo/bar`, absolute paths,
+ * and multi-segment paths like `foo/bar/baz`) is treated as a filesystem path.
+ */
+export declare function isGitUrl(input: string): boolean;
+//# sourceMappingURL=git-url.d.ts.map

package/dist/utils/git-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-url.d.ts","sourceRoot":"","sources":["../../src/utils/git-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAgEvD;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAmB/C"}

package/dist/utils/git-url.js

@@ -0,0 +1,135 @@
+/**
+ * Split a URL with an optional `#ref[:subpath]` fragment into the base URL
+ * and fragment components. Keeps the fragment-handling logic local so the
+ * per-form regexes can stay simple and anchored.
+ */
+function splitFragment(input) {
+    const hashIndex = input.indexOf('#');
+    if (hashIndex === -1) {
+        return { base: input };
+    }
+    const base = input.slice(0, hashIndex);
+    const fragment = input.slice(hashIndex + 1);
+    const colonIndex = fragment.indexOf(':');
+    if (colonIndex === -1) {
+        return { base, ref: fragment };
+    }
+    return {
+        base,
+        ref: fragment.slice(0, colonIndex),
+        subpath: fragment.slice(colonIndex + 1),
+    };
+}
+/**
+ * Parse a string into a {@link ParsedGitUrl}.
+ *
+ * Accepted forms:
+ *  - `https://host/owner/repo.git`
+ *  - `https://host/owner/repo.git#ref`
+ *  - `https://host/owner/repo.git#ref:subpath`
+ *  - `https://github.com/owner/repo/tree/<ref>/<subpath>` (GitHub web URL)
+ *  - `owner/repo` (GitHub shorthand → expanded to HTTPS)
+ *  - `git@host:owner/repo.git`
+ *  - `ssh://git@host/owner/repo.git`
+ *
+ * Throws on malformed input.
+ */
+export function parseGitUrl(input) {
+    const trimmed = input.trim();
+    if (trimmed === '') {
+        throw new Error(`Invalid git URL or path: <empty>.`);
+    }
+    // file:// form: file:///path/to/repo[#ref[:subpath]] — used primarily by
+    // integration tests that clone a local bare repo. `git clone` accepts
+    // file:// natively.
+    if (trimmed.startsWith('file://')) {
+        const { base, ref, subpath } = splitFragment(trimmed);
+        return buildParsed(base, ref, subpath);
+    }
+    // HTTPS .git form: https://host/path.git[#ref[:subpath]]
+    if (/^https?:\/\//.test(trimmed)) {
+        const { base, ref, subpath } = splitFragment(trimmed);
+        if (base.endsWith('.git')) {
+            return buildParsed(base, ref, subpath);
+        }
+        // GitHub web URL: https://github.com/owner/repo/tree/<ref>[/<subpath>]
+        const ghWeb = 
+        // eslint-disable-next-line security/detect-unsafe-regex -- Anchored ^...$ with bounded character classes; the only variable-length group is the trailing subpath. Safe from ReDoS.
+        /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/tree\/([^/]+)(?:\/(.+))?$/.exec(trimmed);
+        if (ghWeb) {
+            const owner = ghWeb[1] ?? '';
+            const repo = ghWeb[2] ?? '';
+            const webRef = ghWeb[3];
+            const webSubpath = ghWeb[4];
+            return buildParsed(`https://github.com/${owner}/${repo}.git`, webRef, webSubpath);
+        }
+    }
+    // SSH ssh:// form: ssh://git@host/path[#ref[:subpath]]
+    if (trimmed.startsWith('ssh://')) {
+        const { base, ref, subpath } = splitFragment(trimmed);
+        return buildParsed(base, ref, subpath);
+    }
+    // SSH scp-like form: git@host:owner/repo.git[#ref[:subpath]]
+    // Anchored, no alternation with nested quantifiers — safe from ReDoS.
+    if (/^[^@\s]+@[^:\s]+:[^#\s]+/.test(trimmed)) {
+        const { base, ref, subpath } = splitFragment(trimmed);
+        return buildParsed(base, ref, subpath);
+    }
+    // GitHub shorthand: owner/repo[#ref[:subpath]] (single slash in base)
+    const { base, ref, subpath } = splitFragment(trimmed);
+    const shorthand = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(base);
+    if (shorthand) {
+        const owner = shorthand[1] ?? '';
+        const repo = shorthand[2] ?? '';
+        return buildParsed(`https://github.com/${owner}/${repo}.git`, ref, subpath);
+    }
+    throw new Error(`Invalid git URL or path: ${input}. Accepted forms: ` +
+        `https://<host>/<owner>/<repo>.git, ` +
+        `git@<host>:<owner>/<repo>.git, ` +
+        `<owner>/<repo>, or a local filesystem path.`);
+}
+function buildParsed(cloneUrl, ref, subpath) {
+    const result = { cloneUrl };
+    if (ref !== undefined && ref !== '')
+        result.ref = ref;
+    if (subpath !== undefined && subpath !== '')
+        result.subpath = subpath;
+    return result;
+}
+/**
+ * Detect whether a string should be treated as a git URL (for the polymorphic
+ * `[git-url-or-path]` audit argument). True for:
+ *  - http(s):// URLs
+ *  - ssh:// URLs
+ *  - file:// URLs (used by integration tests against local bare repos)
+ *  - git@host:path scp-style URLs
+ *  - GitHub shorthand `owner/repo` (strict — no extensions, no extra slashes)
+ *
+ * Everything else (including relative paths like `./foo/bar`, absolute paths,
+ * and multi-segment paths like `foo/bar/baz`) is treated as a filesystem path.
+ */
+export function isGitUrl(input) {
+    const trimmed = input.trim();
+    if (trimmed === '')
+        return false;
+    if (/^https?:\/\//.test(trimmed))
+        return true;
+    if (trimmed.startsWith('ssh://'))
+        return true;
+    if (trimmed.startsWith('file://'))
+        return true;
+    // Match the same scp-style pattern parseGitUrl uses, including the
+    // requirement of a non-empty path segment after the colon. Without the
+    // trailing `[^#\s]+`, `isGitUrl` would accept inputs like `foo@host:`
+    // that parseGitUrl then rejects with a less-helpful error.
+    if (/^[^@\s]+@[^:\s]+:[^#\s]+/.test(trimmed))
+        return true;
+    // Strict GitHub shorthand: exactly two segments, no extension on second,
+    // no path separators beyond the single /. Strip any `#ref[:subpath]`
+    // fragment first so `owner/repo#main` and `owner/repo#main:sub` are
+    // recognized — `parseGitUrl` handles fragments uniformly across forms.
+    const hashIndex = trimmed.indexOf('#');
+    const base = hashIndex === -1 ? trimmed : trimmed.slice(0, hashIndex);
+    return /^[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+$/.test(base);
+}
+//# sourceMappingURL=git-url.js.map

package/dist/utils/git-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-url.js","sourceRoot":"","sources":["../../src/utils/git-url.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;IACjC,CAAC;IACD,OAAO;QACL,IAAI;QACJ,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC;QAClC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,yEAAyE;IACzE,sEAAsE;IACtE,oBAAoB;IACpB,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,OAAO,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,yDAAyD;IACzD,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QAED,uEAAuE;QACvE,MAAM,KAAK;QACT,mLAAmL;QACnL,yFAAyF,CAAC,IAAI,CAC5F,OAAO,CACR,CAAC;QACJ,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACxB,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5B,OAAO,WAAW,CAAC,sBAAsB,KAAK,IAAI,IAAI,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,OAAO,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,6DAA6D;IAC7D,sEAAsE;IACtE,IAAI,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,OAAO,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,sEAAsE;IACtE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,wCAAwC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,WAAW,CAAC,sBAAsB,KAAK,IAAI,IAAI,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,KAAK,CACb,4BAA4B,KAAK,oBAAoB;QACnD,qCAAqC;QACrC,iCAAiC;QACjC,6CAA6C,CAChD,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB,EAAE,GAAY,EAAE,OAAgB;IACnE,MAAM,MAAM,GAAiB,EAAE,QAAQ,EAAE,CAAC;IAC1C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC;IACtD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACtE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,mEAAmE;IACnE,uEAAuE;IACvE,sEAAsE;IACtE,2DAA2D;IAC3D,IAAI,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1D,yEAAyE;IACzE,qEAAqE;IACrE,oEAAoE;IACpE,uEAAuE;IACvE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtE,OAAO,kCAAkC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/docs/audit.md

@@ -16,13 +16,14 @@ The `vat audit` command provides comprehensive validation for Claude plugins, ma
 ## Usage
 
 ```bash
-vat audit [path] [options]
+vat audit [git-url-or-path] [options]
 ```
 
 ### Arguments
 
-- `[path]` - Path to audit (optional, default: current directory)
-  - Can be: directory, registry file, SKILL.md file, or resource directory
+- `[git-url-or-path]` - Path or git URL to audit (optional, default: current directory)
+  - Local path: directory, registry file, SKILL.md file, or resource directory
+  - Git URL: HTTPS, SSH, GitHub shorthand, or GitHub web URL (see "Auditing a remote git repo" below)
 
 ### Options
 
@@ -483,6 +484,56 @@ if [ $? -ne 0 ]; then
 fi
 ```
 
+## Auditing a remote git repo
+
+`vat audit` accepts a git URL in addition to a local path. When given a URL, VAT performs a shallow clone into a temporary directory, runs the audit against the cloned tree, and always cleans up the tempdir on exit.
+
+### Accepted URL forms
+
+| Form | Example |
+|---|---|
+| HTTPS git URL | `https://github.com/foo/bar.git` |
+| HTTPS with ref | `https://github.com/foo/bar.git#v1.2.3` |
+| HTTPS with ref + subpath | `https://github.com/foo/bar.git#main:plugins/baz` |
+| GitHub web URL | `https://github.com/foo/bar/tree/main/plugins/baz` |
+| GitHub shorthand | `foo/bar` |
+| GitHub shorthand with ref | `foo/bar#main` |
+| GitHub shorthand with ref + subpath | `foo/bar#main:plugins/baz` |
+| SSH (scp form) | `git@github.com:foo/bar.git` |
+| SSH (URL form) | `ssh://git@github.com/foo/bar.git` |
+
+The `#ref[:subpath]` fragment form works on every URL form above.
+
+### Output
+
+Output begins with a provenance header showing the URL, ref, and resolved commit SHA, then the normal audit output with paths relative to the cloned repo root. Each header line is emitted as a YAML comment so the rest of the output remains pipe-parseable (`vat audit <url> | yq` works without preprocessing):
+
+```
+# Audited: https://github.com/foo/bar.git @ main (commit abc123de)
+# Subpath: plugins/baz
+---
+status: success
+files:
+  - path: plugins/baz/SKILL.md
+    ...
+```
+
+### Authentication
+
+Authentication is entirely passthrough to your local `git` configuration. SSH URLs use your SSH agent / keys; HTTPS URLs use whatever credential helper your `git` is configured with. VAT itself does not read tokens, environment variables, or credential files.
+
+To audit a private repo: ensure `git clone <url>` works on your machine, then `vat audit <url>` will work too.
+
+### Debugging
+
+Pass `--debug` to preserve the cloned tempdir for inspection (its location is printed to stderr at exit). You are responsible for cleanup when using this flag.
+
+### Limitations
+
+- `--depth 1` cloning cannot resolve arbitrary deep commit SHAs. Use a branch or tag name for the ref.
+- GitHub web URLs are parsed only for `github.com`. For GitLab/Bitbucket/Gitea, use the `.git` URL form directly.
+- Cache-skip-on-unchanged-SHA is not implemented in v1; every URL audit pays the clone cost.
+
 ## Cross-Platform Considerations
 
 ### Path Separators