@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.11

package/dist/commands/ard/emit.js

@@ -0,0 +1,338 @@
+/**
+ * `vat ard emit` — write the project's `/.well-known/ard.json`.
+ *
+ * **Emit, never depend.** This command produces a document and stops. Nothing
+ * in VAT reads one back, and no VAT behaviour is derived from one — ARD is
+ * v0.91, status Proposal, and wiring internals to a moving shape is the cost
+ * this rule avoids.
+ */
+import { existsSync } from 'node:fs';
+import { ArdDerivationError, buildArdEntries, buildArdManifest, findShadowedArdOverrideKeys, writeArdManifest, } from '@vibe-agent-toolkit/resources';
+import { buildReport, exitCodeForReport, reportSchema } from '@vibe-agent-toolkit/schema';
+import { safePath, VatError } from '@vibe-agent-toolkit/utils';
+import { z } from 'zod';
+import { handleReportCommandError, handleReportExpectedFailure } from '../../utils/command-error.js';
+import { loadConfig } from '../../utils/config-loader.js';
+import { createLogger } from '../../utils/logger.js';
+import { writeJsonOutput } from '../../utils/output.js';
+import { readPackageJsonOrAbsent } from '../../utils/package-json.js';
+import { discoverSkillsFromConfig } from '../skills/skill-discovery.js';
+import { collectArdSurfaces } from './surfaces.js';
+/** Default destination, relative to the project root — the path ARD publishes at. */
+export const DEFAULT_ARD_OUTPUT = '.well-known/ard.json';
+/** The config filename every VAT project declares its surfaces in. */
+const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
+/** No manifest could be built, and this says which absence caused it. */
+export class ArdConfigMissingError extends VatError {
+    projectRoot;
+    absence;
+    constructor(projectRoot, absence) {
+        super('ARD_CONFIG_MISSING', ABSENCE_MESSAGES[absence](projectRoot));
+        this.projectRoot = projectRoot;
+        this.absence = absence;
+    }
+}
+const ABSENCE_MESSAGES = {
+    'no-project-root': (projectRoot) => `Project root ${projectRoot} does not exist. Pass --project-root a directory that does, or ` +
+        'run `vat ard emit` from inside the project.',
+    'no-config-file': (projectRoot) => `No ${CONFIG_FILENAME} found in ${projectRoot}. ` +
+        'ARD entries are derived from the surfaces that file declares, so there is nothing to emit.',
+    'no-ard-block': (projectRoot) => `No \`ard:\` configuration found for ${projectRoot}. ` +
+        `Add an \`ard:\` block with a \`publisher\` domain to ${CONFIG_FILENAME}.`,
+};
+/**
+ * The project's own package version, when it has one.
+ *
+ * The npm package version is the only version this project recognises, and an
+ * adopter's is the only one VAT can honestly stamp on an entry. Absent, the
+ * field is simply omitted. A `package.json` that is there and is not JSON is
+ * refused by name instead: it used to be read as "no version" too, and a
+ * manifest emitted with no `version` from a tree npm itself cannot read is a
+ * manifest that hid the one fact worth reporting.
+ */
+function readProjectVersion(projectRoot) {
+    const parsed = readPackageJsonOrAbsent(safePath.join(projectRoot, 'package.json'));
+    const version = parsed?.['version'];
+    // `""` is ABSENT, not a version. A `package.json` carrying it emitted
+    // `"version": ""` on every entry at exit 0 — a field asserting a version
+    // that does not exist. The entry schema now refuses it too, so leaving this
+    // would turn a blank field into a hard emission failure instead.
+    if (typeof version !== 'string' || version === '')
+        return undefined;
+    return version;
+}
+/**
+ * Build and write the manifest.
+ *
+ * @throws {ArdConfigMissingError} when no config, or no `ard:` block, is found.
+ * @throws {ArdDerivationError} when a surface cannot be turned into a
+ *   conformant entry — a missing `ard.baseUrl`, an unusable URN segment, or a
+ *   trust identity that does not align with the publisher.
+ */
+export async function runArdEmit(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!existsSync(projectRoot)) {
+        throw new ArdConfigMissingError(projectRoot, 'no-project-root');
+    }
+    const config = loadConfig(projectRoot);
+    if (config === undefined) {
+        throw new ArdConfigMissingError(projectRoot, 'no-config-file');
+    }
+    const ard = config.ard;
+    if (ard === undefined) {
+        throw new ArdConfigMissingError(projectRoot, 'no-ard-block');
+    }
+    const { surfaces, skipped } = collectArdSurfaces(config, {
+        version: readProjectVersion(projectRoot),
+        // The SAME discovery `vat verify` runs, so the two commands cannot disagree
+        // about which skills this project has. Omitted entirely when the project
+        // declares no `skills` block: there is nothing to cross-check, and passing
+        // `[]` would claim discovery ran and found nothing.
+        ...(config.skills === undefined
+            ? {}
+            : {
+                // `'refuse'`: a manifest cross-checked against a partial skill list
+                // would advertise or omit entries on a population it never saw. The
+                // throw is an invocation failure → exit 2 (see the catch in
+                // `ardEmitCommand`).
+                discoveredSkills: (await discoverSkillsFromConfig(config.skills, projectRoot, 'refuse')).map((skill) => skill.name),
+            }),
+    });
+    const manifest = buildArdManifest(buildArdEntries(surfaces, ard));
+    const outputPath = safePath.resolve(projectRoot, options.output ?? DEFAULT_ARD_OUTPUT);
+    await writeArdManifest(manifest, outputPath);
+    return {
+        outputPath,
+        entryCount: manifest.entries.length,
+        skipped,
+        shadowed: findShadowedArdOverrideKeys(surfaces, ard),
+    };
+}
+/**
+ * The codes this run's findings carry. Not registry codes: nothing here is a
+ * validation an adopter tunes through `validation.severity` — a skipped
+ * surface is a fact about what the manifest could not advertise, and its
+ * severity is the run's to decide.
+ */
+export const ARD_EMIT_CODES = {
+    /** A configured surface that became no entry, and why — the thing `--strict` gates. */
+    SURFACE_SKIPPED: 'ARD_SURFACE_SKIPPED',
+    /**
+     * A bare `ard.entries` key a qualified key for the same surface outranked.
+     * Not a failure — the precedence is deterministic and documented — but the
+     * losing block is dead config, and an author cannot see that from the file.
+     */
+    OVERRIDE_KEY_SHADOWED: 'ARD_OVERRIDE_KEY_SHADOWED',
+    /**
+     * The project was read and declares no `ard:` block, so no manifest was
+     * built. A finding at `error` — exit 1 — because the PROJECT is the subject,
+     * not the invocation: it is fixed by editing config.
+     */
+    NOT_CONFIGURED: 'ARD_NOT_CONFIGURED',
+    /** A declared surface could not be derived into a conformant entry, so no manifest was written. */
+    DERIVATION_FAILED: 'ARD_DERIVATION_FAILED',
+    /** `--strict` refused a manifest that leaves a declared surface (or everything) unadvertised. */
+    STRICT_REFUSED: 'ARD_STRICT_REFUSED',
+};
+/**
+ * What the run reports beyond its findings.
+ *
+ * 🪤 `entryCount: 0` is the empty manifest. A run that wrote `{"entries":[]}`
+ * and one that wrote a full catalogue both used to end at exit 0 with a
+ * cheerful line on stdout, and nothing a machine could read told them apart —
+ * so a CI step that emits and publishes was green over a discovery document
+ * advertising nothing. The envelope's `examined` is every configured surface
+ * the run considered, so "nothing declared" (`examined: 0`) and "everything
+ * declared was skipped" (`examined: N`, `entryCount: 0`) read differently too.
+ */
+export const ArdEmitDataSchema = z.object({
+    /** Where the manifest was written — `null` when the project produced none. */
+    outputPath: z.string().nullable(),
+    entryCount: z.number().int().nonnegative(),
+    /**
+     * Counts BESIDE the findings. The count is what a CI step gates on without
+     * a JSON path into an array; the finding is what the human it pages then
+     * acts on. Publishing only one of them answers "how many" or "which", never
+     * both.
+     */
+    skippedCount: z.number().int().nonnegative(),
+    shadowedCount: z.number().int().nonnegative(),
+}).strict();
+/** The document `--format json` publishes. */
+export const ARD_EMIT_REPORT_SCHEMA = reportSchema(ArdEmitDataSchema);
+/** The finding one skipped surface becomes. Its text is the stderr line, so the two channels agree. */
+function skippedFinding(item) {
+    return {
+        code: ARD_EMIT_CODES.SURFACE_SKIPPED,
+        severity: 'warning',
+        message: `skipped ${item.kind} "${item.name}": ${item.reason}`,
+    };
+}
+/** The finding one shadowed override key becomes, pointing at the dead config block. */
+function shadowedFinding(item) {
+    return {
+        code: ARD_EMIT_CODES.OVERRIDE_KEY_SHADOWED,
+        severity: 'info',
+        message: `ignored \`ard.entries.${item.shadowedKey}\`: the ${item.kind} "${item.name}" is also named ` +
+            `by \`ard.entries."${item.winningKey}"\`, and the kind-qualified key wins. Nothing in the ` +
+            'bare block was read — fold it into the qualified one or delete it.',
+        field: `ard.entries.${item.shadowedKey}`,
+    };
+}
+/** Pure: the report a result becomes, so the status rule is unit-testable. */
+export function buildArdEmitReport(result) {
+    return buildReport({
+        // Every configured surface the run considered: the ones that became
+        // entries and the ones it had to skip.
+        examined: result.entryCount + result.skipped.length,
+        findings: [...result.skipped.map(skippedFinding), ...result.shadowed.map(shadowedFinding)],
+        data: {
+            outputPath: result.outputPath,
+            entryCount: result.entryCount,
+            skippedCount: result.skipped.length,
+            shadowedCount: result.shadowed.length,
+        },
+    });
+}
+/**
+ * Why `--strict` fails this run, or `undefined` when it does not.
+ *
+ * ⚠️ A shadowed override key is deliberately NOT a strict failure: the
+ * precedence is deterministic and documented, the entry is still emitted, and
+ * nothing about the published manifest is wrong. What `--strict` gates is the
+ * manifest's CONTENT — a surface an author declared and a consumer will never
+ * see, and the empty document that is the limit case of that.
+ */
+function strictFailure(report) {
+    const { skippedCount, entryCount } = report.data;
+    if (skippedCount > 0) {
+        const surfaces = skippedCount === 1 ? '1 configured surface was' : `${skippedCount} configured surfaces were`;
+        // Not "see above": in `--format json` the reasons are IN the report, not on
+        // stderr, so a message naming a position would be wrong on one of the two
+        // channels.
+        return `--strict: ${surfaces} not advertised — each is named, with its reason, in this run's \`findings\`.`;
+    }
+    if (entryCount === 0) {
+        return '--strict: the manifest advertises nothing. Nothing this project declares became an ARD entry.';
+    }
+    return undefined;
+}
+/**
+ * The report for a project VAT read and could build no manifest for.
+ *
+ * 🚨 These endings used to publish the envelope's ERROR branch (`status:
+ * error`) and exit 1 — a document saying "could not do its job" beside a code
+ * saying "the project failed its gate". They are findings about the project,
+ * so they are published as findings and the code is derived from them.
+ *
+ * @param code - Which refusal
+ * @param message - What the operator must change
+ * @returns The report, at `error` severity, with nothing written
+ */
+function buildArdRefusalReport(code, message) {
+    return buildReport({
+        examined: 0,
+        findings: [{ code, severity: 'error', message }],
+        data: { outputPath: null, entryCount: 0, skippedCount: 0, shadowedCount: 0 },
+    });
+}
+/**
+ * The report `--strict` publishes: the same one, with the refusal as a finding.
+ *
+ * It used to be a stderr line beside a document that still said `status: ok`,
+ * and an exit 1 the document did not explain.
+ *
+ * @param report - What the run built
+ * @returns The report, with a `STRICT_REFUSED` error when `--strict` refuses it
+ */
+function withStrictVerdict(report) {
+    const failure = strictFailure(report);
+    if (failure === undefined)
+        return report;
+    return {
+        ...buildReport({
+            examined: report.examined,
+            findings: [...report.findings, { code: ARD_EMIT_CODES.STRICT_REFUSED, severity: 'error', message: failure }],
+            data: report.data,
+        }),
+        ...(report.durationMs === undefined ? {} : { durationMs: report.durationMs }),
+    };
+}
+/** The human rendering: findings on stderr, the one summary line on stdout. */
+function writeArdEmitText(report) {
+    for (const finding of report.findings) {
+        process.stderr.write(`${finding.message}\n`);
+    }
+    const { entryCount, outputPath } = report.data;
+    if (outputPath !== null) {
+        process.stdout.write(`Wrote ${entryCount} ARD entr${entryCount === 1 ? 'y' : 'ies'} to ${outputPath}\n`);
+    }
+}
+/**
+ * Publish a report in the operator's format and end on the code it DERIVES.
+ *
+ * @param report - The document
+ * @param format - `json`, or anything else for the human rendering
+ */
+function publishArdReport(report, format) {
+    if (format === 'json') {
+        // The report carries every skipped and shadowed surface in full, so the
+        // stderr lines would be the same facts twice on two channels.
+        writeJsonOutput(report);
+    }
+    else {
+        writeArdEmitText(report);
+    }
+    process.exit(exitCodeForReport(report));
+}
+/** Action handler for `vat ard emit`. */
+export async function ardEmitCommand(options) {
+    const logger = createLogger(options.debug === true ? { debug: true } : {});
+    const startTime = Date.now();
+    try {
+        const built = { ...buildArdEmitReport(await runArdEmit(options)), durationMs: Date.now() - startTime };
+        publishArdReport(options.strict === true ? withStrictVerdict(built) : built, options.format);
+    }
+    catch (error) {
+        // 🔑 THE RULE, in one sentence: **exit 1 means VAT read this project and
+        // produced no manifest by its own rules — it declares no `ard:` block, or a
+        // surface could not be derived into a conformant entry; exit 2 means VAT
+        // never got that far — no project root, no config file, a config it cannot
+        // parse, or an unexpected internal failure.**
+        //
+        // ⚠️ Not "1 is reserved for a check that ran and failed": `ard emit` is not
+        // a check, and "no `ard:` block" is not a failed one. The distinction that
+        // matters to a caller is whether the PROJECT is the subject (1) or the
+        // INVOCATION is (2) — the first is fixed by editing config, the second by
+        // fixing the command line or the file itself. A CI job that tolerates
+        // repositories which have not opted into ARD keys on exactly that split.
+        //
+        // Exit 2 is also what `vat okf validate` documents for the same conditions,
+        // and what an invalid config already did here through `handleReportCommandError`.
+        // The old split had a missing config file exiting 1 and an invalid one
+        // exiting 2 while the help called 2 "Unexpected internal failure" — so a CI
+        // job reading 2 as a crash was paged for a typo.
+        //
+        // ⚠️ Both endings publish their document through `handleReportExpectedFailure`,
+        // in the format the operator asked for. Written inline they published
+        // NOTHING — a `--format json` run of the commonest case of all, a
+        // repository that never opted into ARD, wrote zero bytes to stdout and left
+        // a CI wrapper parsing stderr for a fact the report is supposed to carry.
+        //
+        // 🪤 `return` the call, though its type is `never`: under test `process.exit`
+        // is a spy that RETURNS, so a bare call falls through to the handler below
+        // and the run records a second exit — the same reason the inline endings
+        // this replaced each carried a `return`.
+        if (error instanceof ArdConfigMissingError && error.absence === 'no-ard-block') {
+            return publishArdReport({ ...buildArdRefusalReport(ARD_EMIT_CODES.NOT_CONFIGURED, error.message), durationMs: Date.now() - startTime }, options.format);
+        }
+        if (error instanceof ArdDerivationError) {
+            return publishArdReport({ ...buildArdRefusalReport(ARD_EMIT_CODES.DERIVATION_FAILED, error.message), durationMs: Date.now() - startTime }, options.format);
+        }
+        if (error instanceof ArdConfigMissingError) {
+            return handleReportExpectedFailure(error.message, startTime, options.format);
+        }
+        handleReportCommandError(error, logger, startTime, 'ARD emit', options.format);
+    }
+}
+//# sourceMappingURL=emit.js.map

package/dist/commands/ard/emit.js.map

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

package/dist/commands/ard/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `vat ard` — Agentic Resource Discovery emission.
+ *
+ * Not registered in `command-loaders.ts` by this module: the loader table is
+ * owned elsewhere, and this file only builds the command.
+ */
+import { Command } from 'commander';
+export { ardEmitCommand, buildArdEmitReport, runArdEmit, ArdConfigMissingError, DEFAULT_ARD_OUTPUT, type ArdEmitReport, } from './emit.js';
+export { collectArdSurfaces, type ArdSurfaceCollection, type SkippedArdSurface } from './surfaces.js';
+/** Build the `vat ard` command group. */
+export declare function createArdCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/ard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/ard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEtG,yCAAyC;AACzC,wBAAgB,gBAAgB,IAAI,OAAO,CAoF1C"}

package/dist/commands/ard/index.js

@@ -0,0 +1,84 @@
+/**
+ * `vat ard` — Agentic Resource Discovery emission.
+ *
+ * Not registered in `command-loaders.ts` by this module: the loader table is
+ * owned elsewhere, and this file only builds the command.
+ */
+import { Command, Option } from 'commander';
+import { ardEmitCommand, DEFAULT_ARD_OUTPUT } from './emit.js';
+export { ardEmitCommand, buildArdEmitReport, runArdEmit, ArdConfigMissingError, DEFAULT_ARD_OUTPUT, } from './emit.js';
+export { collectArdSurfaces } from './surfaces.js';
+/** Build the `vat ard` command group. */
+export function createArdCommand() {
+    const ard = new Command('ard');
+    ard.description('Emit an Agentic Resource Discovery (ARD) manifest for this project').addHelpText('after', `
+Description:
+  ARD has no registry and no upload: a publisher hosts a JSON-LD document at
+  https://{domain}/.well-known/ard.json and registries crawl it. VAT builds that
+  document out of the surfaces this project already declares.
+
+  ⚠️ ARD is v0.91, status Proposal. VAT emits against it and reads nothing back.
+`);
+    ard
+        .command('emit')
+        .description('Build the ARD manifest and write it to disk')
+        .option('-o, --output <path>', `Output path (default: ${DEFAULT_ARD_OUTPUT})`)
+        .option('--project-root <dir>', 'Project root to read the config from (default: cwd)')
+        .addOption(
+    // Rejected by Commander rather than falling through to `text`, as the
+    // sibling `vat okf validate` does: `--format Json` in a pipeline must
+    // fail HERE, where the mistake is, not downstream in `jq`.
+    new Option('--format <format>', 'Output format: text (default) or json')
+        .choices(['text', 'json'])
+        .default('text'))
+        .option('--strict', 'Exit 1 when the manifest advertises nothing, or a configured surface was skipped')
+        .option('--debug', 'Verbose logging to stderr')
+        .action(ardEmitCommand)
+        .addHelpText('after', `
+Derivation:
+  Every published skill in \`skills.config\` becomes an entry, typed
+  application/ai-skill+md — a media type VAT COINS, since the specification
+  names none for a skill (it occurs once, in an example).
+
+  A marketplace, an OKF bundle and an MCP server are emitted ONLY when the
+  author supplies \`ard.entries."<kind>:<name>".type\`; the specification names
+  no media type for any of them, and VAT does not guess. Skipped surfaces are
+  reported on stderr — including a \`skills.config\` key that discovery does not
+  find, which is never advertised.
+
+  \`ard.entries\` is keyed by "<kind>:<name>" — skills, marketplaces and OKF
+  bundles are independent key spaces, so a bare name that matches two of them
+  is REFUSED rather than applied to both.
+
+  \`representativeQueries\` is authored, never generated. Its absence is a
+  conformance WARNING upstream, not an error — an honest gap beats a
+  fabricated query that makes a resource discoverable for the wrong task.
+
+Requirements:
+  ard.publisher  Required — anchors every entry URN.
+  ard.baseUrl    Required in practice — VAT has no inline artifact document for
+                 these surfaces, so without it no entry has a \`url\` or a
+                 \`data\` and emission fails.
+
+Exit Codes:
+  0 - Manifest written — INCLUDING one that advertises nothing. An empty
+      \`entries\` list is a legal ARD document, and skipped surfaces are reported
+      on stderr at this exit code. Gate on \`--format json\` (the report
+      envelope: \`examined\`, \`findings\`, \`summary\`, \`data.entryCount\`,
+      \`data.skippedCount\`; schema: packages/cli/schemas/ard-emit.json), or
+      make both conditions fail with \`--strict\`
+  1 - No \`ard:\` block, or a surface that could not be derived — each an
+      error-severity finding about the PROJECT (ARD_NOT_CONFIGURED,
+      ARD_DERIVATION_FAILED), with \`data.outputPath\` null as nothing was
+      written. Under \`--strict\`, also an empty manifest or a skipped surface
+      (ARD_STRICT_REFUSED). The code is derived from the report, never chosen
+      beside it
+  2 - System error (no project root, no config file, invalid config, unexpected
+      internal failure)
+
+Example:
+  $ vat ard emit --format json --strict
+`);
+    return ard;
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/ard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/ard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,kBAAkB,GAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAqD,MAAM,eAAe,CAAC;AAEtG,yCAAyC;AACzC,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IAE/B,GAAG,CAAC,WAAW,CAAC,oEAAoE,CAAC,CAAC,WAAW,CAC/F,OAAO,EACP;;;;;;;CAOH,CACE,CAAC;IAEF,GAAG;SACA,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,6CAA6C,CAAC;SAC1D,MAAM,CAAC,qBAAqB,EAAE,yBAAyB,kBAAkB,GAAG,CAAC;SAC7E,MAAM,CAAC,sBAAsB,EAAE,qDAAqD,CAAC;SACrF,SAAS;IACR,sEAAsE;IACtE,sEAAsE;IACtE,2DAA2D;IAC3D,IAAI,MAAM,CAAC,mBAAmB,EAAE,uCAAuC,CAAC;SACrE,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACzB,OAAO,CAAC,MAAM,CAAC,CACnB;SACA,MAAM,CACL,UAAU,EACV,kFAAkF,CACnF;SACA,MAAM,CAAC,SAAS,EAAE,2BAA2B,CAAC;SAC9C,MAAM,CAAC,cAAc,CAAC;SACtB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CL,CACI,CAAC;IAEJ,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/commands/ard/surfaces.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Reading the project config for the surfaces an ARD manifest can advertise.
+ *
+ * Everything here is pure — config in, surfaces out — so the derivation rules
+ * are unit-testable without touching a filesystem or a manifest.
+ *
+ * ## Two collectors, because two rules
+ *
+ * A **skill** derives its media type from the surface kind alone, so every
+ * published skill becomes an entry with no author action. A **marketplace**, an
+ * **OKF bundle** and an MCP server derive nothing: the ARD specification names
+ * no media type for any of them (see `deriveArdMediaType`), so they are emitted
+ * only when the author supplies `ard.entries.<name>.type`, and are otherwise
+ * *reported as skipped* — never silently dropped, and never guessed at.
+ */
+import { type ArdSurface, type ArdSurfaceKind, type ProjectConfig } from '@vibe-agent-toolkit/resources';
+/** A surface VAT declined to emit, and the reason a reader can act on. */
+export interface SkippedArdSurface {
+    readonly name: string;
+    readonly kind: ArdSurfaceKind;
+    readonly reason: string;
+}
+export interface ArdSurfaceCollection {
+    readonly surfaces: readonly ArdSurface[];
+    readonly skipped: readonly SkippedArdSurface[];
+}
+/** Facts that apply to every surface in a run, derived once by the caller. */
+export interface ArdSurfaceDefaults {
+    /** The project's own package version, when it has one. */
+    readonly version?: string | undefined;
+    /**
+     * Names of the skills `skills.include` discovery actually found.
+     *
+     * 🚨 Without this, every `skills.config` key was advertised on the author's
+     * word alone: a project with NO `skills/` directory and two config keys
+     * emitted two entries carrying real URLs at exit 0, with nothing on stderr —
+     * a published discovery document that is entirely 404s. The `skipped` channel
+     * exists so a surface is never silently DROPPED; the mirror case, silently
+     * INVENTING one, had no guard at all.
+     *
+     * Supplied by the caller rather than crawled here so this module stays pure,
+     * and `undefined` rather than `[]` when discovery did not run — an empty
+     * array is the answer "nothing exists", which must not be spelled the same
+     * way as "nobody asked".
+     */
+    readonly discoveredSkills?: readonly string[] | undefined;
+}
+/**
+ * Every surface the project config declares, split into what VAT will emit and
+ * what it declined to.
+ *
+ * @throws never — a config with no `ard` block yields an empty collection; the
+ *   caller decides whether that is a failure (`runArdEmit` does).
+ */
+export declare function collectArdSurfaces(config: ProjectConfig, defaults: ArdSurfaceDefaults): ArdSurfaceCollection;
+//# sourceMappingURL=surfaces.d.ts.map

package/dist/commands/ard/surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../../../src/commands/ard/surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC3D;AA+ID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAwBtB"}