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

package/dist/utils/document-writer.js

@@ -0,0 +1,319 @@
+/**
+ * The ONE writer of a `vat` command's stdout document.
+ *
+ * Every shape a command publishes is registered in `report-schemas.ts`, and
+ * this module is how it leaves: the document is looked up by verb, passed
+ * through the run-integrity refusal the registry's denominator declares,
+ * validated against its own published schema, rendered as yaml, json or text,
+ * and — for the `end…` functions — the process ends on the code the WRITTEN
+ * document derives. `local/no-stdout-outside-writer` keeps every other route
+ * to stdout out of `commands/`.
+ *
+ * 🔑 **Validated before a byte leaves.** A document the published schema
+ * rejects is a defect in VAT, and it throws here — the last resort ends it on
+ * `ERROR` — rather than shipping a shape an adopter's parser was promised
+ * would never appear.
+ */
+import { writeFileSync } from 'node:fs';
+import { buildErrorReport, CODE_REGISTRY, errorDiagnostics, exitCodeForReport, } from '@vibe-agent-toolkit/schema';
+import { isFsFaultError, suppressedFaultsOf, TREE_CLEANUP_INCOMPLETE_CODE } from '@vibe-agent-toolkit/utils';
+import { parse as parseYaml } from 'yaml';
+import { artifactShapeFor, exitCodeForExternal, reportShapeFor, } from '../report-schemas.js';
+import { errorMessageOf, refusalCodeOf, withFsFaultRemedy } from './command-refusal.js';
+import { debugDiagnosticsEnabled } from './debug-diagnostics.js';
+import { renderYamlDocument, writeStdoutSync } from './output.js';
+import { withRunIntegrity } from './run-integrity.js';
+/** One finding as a compiler-style line: `location:line:column: severity: message [code]`. */
+function findingLine(finding) {
+    const anchor = [finding.location, finding.line, finding.column].filter((part) => part !== undefined).join(':');
+    const line = `${finding.severity}: ${finding.message} [${finding.code}]`;
+    return anchor === '' ? line : `${anchor}: ${line}`;
+}
+/**
+ * The generic `--format text` rendering: one line per finding, then the status
+ * line with the counts and the denominator.
+ */
+function renderReportText(report, unit) {
+    const { errors, warnings, info } = report.summary;
+    const lines = report.findings.map(findingLine);
+    if (report.status === 'error')
+        lines.push(`error: ${report.error.message} [${report.error.code}]`);
+    lines.push(`status: ${report.status} — ${errors} errors, ${warnings} warnings, ${info} info (examined ${report.examined} ${unit})`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Write `document` in a structured format — `text` has no structure, so it is YAML.
+ *
+ * YAML opens with `---` and has NO trailing marker: `---` opens a document, so a
+ * trailer made every stdout a two-document stream a plain `YAML.parse()` refused.
+ *
+ * The ordinary stream write, not {@link writeStdoutSync}: a document follows
+ * progress written through `console.log`, and a synchronous fd-1 write would
+ * jump ahead of anything still buffered there. `makeStdioBlocking()` at startup
+ * makes both channels synchronous, so nothing is lost at `process.exit`.
+ */
+function writeStructured(document, format) {
+    process.stdout.write(format === 'json' ? `${JSON.stringify(document, null, 2)}\n` : `---\n${renderYamlDocument(document)}`);
+}
+/**
+ * The document a report verb publishes, without writing it: the run-integrity
+ * refusal its registered denominator declares, then its published schema.
+ *
+ * For a lane that needs the published document before writing it — a command
+ * that warns on stderr with the refusal the writer adds. {@link writeDocument}
+ * goes through it too. (A phase of `vat build` / `validate` / `verify` hands
+ * back its report BEFORE this pass: the orchestrator judges zero examined on
+ * the whole run.)
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @returns The document as published
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export function publishedReport(verb, report) {
+    const entry = reportShapeFor(verb);
+    const published = withRunIntegrity(report, entry.examined);
+    entry.schema.parse(published);
+    return published;
+}
+/**
+ * Publish a report verb's document.
+ *
+ * @param verb - The registered verb, as typed after `vat`
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ * @returns The document actually written — after the run-integrity refusal
+ * @throws When the verb is unregistered or its schema rejects the document (a defect)
+ */
+export function writeDocument(verb, report, format) {
+    const entry = reportShapeFor(verb);
+    const written = publishedReport(verb, report);
+    if (format === 'text') {
+        const text = entry.renderText === undefined
+            ? renderReportText(written, entry.examined.unit)
+            : entry.renderText(written);
+        if (text !== '')
+            process.stdout.write(text);
+    }
+    else {
+        writeStructured(written, format);
+    }
+    return written;
+}
+/**
+ * Publish a report verb's document and end on the code it derives.
+ *
+ * @param verb - The registered verb
+ * @param report - The document as the verb built it
+ * @param format - How to render it
+ */
+export function endWithReport(verb, report, format) {
+    process.exit(exitCodeForReport(writeDocument(verb, report, format)));
+}
+/** The explicit "nothing finished" — spelled out at the call site, never defaulted. */
+export const NOTHING_FINISHED = Object.freeze({ examined: 0, findings: [], data: null });
+/**
+ * Publish the envelope's error branch — the run could not do its job — with
+ * whatever finished, and end on `ERROR`.
+ *
+ * The message also goes to stderr, where a human reads it; `INTERNAL_ERROR`
+ * adds the stack, since that one is VAT's defect to report, and under
+ * `--debug` every refusal does — the flag exists to name the throw site.
+ *
+ * @param verb - The registered verb
+ * @param code - Which refusal: `USAGE_INVALID` for the invocation's mistake,
+ *   `INPUT_UNREADABLE` for an input that cannot be read, `INTERNAL_ERROR` only
+ *   for a failure VAT did not anticipate
+ * @param error - The thrown value, or the message
+ * @param format - How to render the document
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ */
+export function endWithRefusal(verb, code, error, format, gate, finished) {
+    process.exit(exitCodeForReport(writeDocument(verb, refusalReport(code, error, gate, finished), format)));
+}
+/**
+ * A refusal's human half: its message on stderr — the code's own description
+ * when the thrown value carries none — plus the stack for a VAT defect, or for
+ * any refusal under `--debug`, which exists to name the throw site.
+ *
+ * @returns The message the published document carries
+ */
+function announceRefusal(code, error) {
+    const raw = errorMessageOf(error);
+    const message = raw === '' ? CODE_REGISTRY[code].description : withFsFaultRemedy(raw, error);
+    process.stderr.write(`${message}\n`);
+    if (code === 'INTERNAL_ERROR' || debugDiagnosticsEnabled())
+        process.stderr.write(`${errorDiagnostics(error)}\n`);
+    return message;
+}
+/**
+ * The envelope's error branch for a refusal, with its human half already on
+ * stderr — what {@link endWithRefusal} writes, for the lane that hands the
+ * report on instead (a phase an orchestrator folds, or an orchestrator's own
+ * refusal).
+ *
+ * @param code - Which refusal (see {@link endWithRefusal})
+ * @param error - The thrown value, or the message
+ * @param gate - The gate the run was judged by
+ * @param finished - The work that finished, or {@link NOTHING_FINISHED}
+ * @returns The error report, not yet published
+ */
+export function refusalReport(code, error, gate, finished) {
+    const message = announceRefusal(code, error);
+    return buildErrorReport({
+        error: { code, message },
+        gate,
+        examined: finished.examined,
+        findings: [...finished.findings, ...leftoverFindingsOf(error)],
+        data: finished.data,
+    });
+}
+/**
+ * What the failure path could not clean up — a temporary directory, a staged tree —
+ * recorded beside the thrown error (`suppressedFaultsOf`), as warnings naming each.
+ * Recorded beside, never on its cause chain: a leftover is never the run's refusal.
+ */
+export function leftoverFindingsOf(error) {
+    return suppressedFaultsOf(error).map((fault) => {
+        process.stderr.write(`warning: ${errorMessageOf(fault)}\n`);
+        return leftoverIssueOf(fault);
+    });
+}
+/**
+ * The {@link leftoverIssue} a failure to remove something stands for: its message, and — for a
+ * classified fault — the path it names (the entry left).
+ *
+ * @param fault - What the removal threw: a parked entry an uninstall or a clear could not delete
+ *   (`applyTreePlanOrLeftover`'s `leftover`), or a suppressed fault beside a refusal
+ */
+export function leftoverIssueOf(fault) {
+    return leftoverIssue(errorMessageOf(fault), isFsFaultError(fault) ? fault.path : undefined);
+}
+/**
+ * Something a run made and could not remove — a temporary directory, a staged or parked tree —
+ * as the ONE warning every lane names it with ({@link TREE_CLEANUP_INCOMPLETE_CODE}), whether the
+ * run then refused or finished.
+ *
+ * @param message - What was left, and why it stayed
+ * @param path - The entry left, when known: its `link`
+ */
+export function leftoverIssue(message, path) {
+    return {
+        code: TREE_CLEANUP_INCOMPLETE_CODE,
+        severity: 'warning',
+        message,
+        // `link`, never `location`: a report's location is project-relative, and this is an absolute path (a temp dir, a staged tree).
+        ...(path === undefined ? {} : { link: path }),
+        fix: 'Remove what the message names yourself, making it writable first if the OS refused; nothing VAT made uses it.',
+    };
+}
+/**
+ * Read a report verb's document another `vat` process already wrote — a
+ * supervised child — checking it IS that verb's document: parsed in the format
+ * it was asked for and validated against the published schema.
+ *
+ * @param verb - The registered verb whose document `text` claims to be
+ * @param text - The document as the child wrote it
+ * @param format - The format the child was asked for
+ * @returns The text with the report it parses to, for {@link endWithForwardedDocument}
+ * @throws When `text` does not parse, or its schema rejects it — a truncated
+ *   write among them, which the caller decides how to report
+ */
+export function readForwardedDocument(verb, text, format) {
+    const parsed = format === 'json' ? JSON.parse(text) : parseYaml(text);
+    reportShapeFor(verb).schema.parse(parsed);
+    return { text, report: parsed };
+}
+/**
+ * Publish a forwarded document byte for byte and end on the code the document
+ * derives — never on the code the process that wrote it happened to exit with.
+ *
+ * @param document - What {@link readForwardedDocument} accepted
+ */
+export function endWithForwardedDocument(document) {
+    writeStdoutSync(document.text);
+    process.exit(exitCodeForReport(document.report));
+}
+/**
+ * Publish an externally owned payload verbatim and end on the code its
+ * registered adapter maps `outcome` to.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param payload - The payload as its owner shaped it
+ * @param format - How to render it (`text` renders YAML)
+ * @param outcome - What the external write did
+ */
+export function writeExternalDocument(verb, payload, format, outcome) {
+    writeStructured(payload, format);
+    process.exit(exitCodeForExternal(verb, outcome));
+}
+/**
+ * End an external verb whose run threw: publish `{ error: { code, message } }`
+ * — the one failure payload every external verb shares, since the payload it
+ * would have passed through never arrived — and end on the code its adapter
+ * maps `failed` to. The code is the thrown value's own ({@link refusalCodeOf}):
+ * a missing key or a bad argument is `USAGE_INVALID`, a refused or unanswered
+ * API call `EXTERNAL_API_FAILED`, anything uncoded `INTERNAL_ERROR`.
+ *
+ * @param verb - A verb of an `external` entry
+ * @param error - What the run threw
+ * @param format - How to render the payload
+ */
+export function endWithExternalRefusal(verb, error, format) {
+    const code = refusalCodeOf(error);
+    const message = announceRefusal(code, error);
+    writeExternalDocument(verb, { error: { code, message } }, format, { kind: 'failed', cause: message });
+}
+/**
+ * The one serializer for a `legacy` entry's document: unvalidated, and typed
+ * to the legacy verbs so no report verb can take this path.
+ *
+ * @param _verb - A verb of a `legacy` entry
+ * @param document - The legacy document
+ * @param format - How to render it
+ * @param text - The verb's own `--format text` rendering, written as-is; with
+ *   none (a refusal has no human rendering of its own) `text` renders YAML.
+ *   Required, so a caller says which it means
+ */
+export function writeLegacyDocument(_verb, document, format, text) {
+    // The verb's TYPE is the guarantee — only a legacy verb compiles here.
+    if (format === 'text' && text !== undefined) {
+        // Synchronously, as `claude context` always wrote it: its text can run long and the verb exits straight after.
+        writeStdoutSync(text);
+        return;
+    }
+    writeStructured(document, format);
+}
+/** Validate a payload against its artifact entry's schema, when it declares one. */
+function validatedArtifact(name, channel, payload) {
+    artifactShapeFor(name, channel).schema?.parse(payload);
+}
+/**
+ * Publish a stdout artifact — a config to paste, a file's text — and nothing else.
+ *
+ * @param name - The registered stdout artifact
+ * @param payload - The artifact; a string for `raw`
+ * @param format - `yaml` / `json`, or `raw` to write a string as-is
+ */
+export function writeArtifact(name, payload, format) {
+    validatedArtifact(name, 'stdout', payload);
+    if (format === 'raw') {
+        process.stdout.write(String(payload));
+        return;
+    }
+    writeStructured(payload, format);
+}
+/**
+ * Write a registered file artifact: YAML for a `.yaml`/`.yml` path, JSON otherwise.
+ *
+ * @param name - The registered file artifact
+ * @param path - Where to write it
+ * @param payload - The artifact
+ */
+export function writeArtifactFile(name, path, payload) {
+    validatedArtifact(name, 'file', payload);
+    const text = /\.ya?ml$/.test(path) ? renderYamlDocument(payload) : `${JSON.stringify(payload, null, 2)}\n`;
+    writeFileSync(path, text, 'utf-8');
+}
+//# sourceMappingURL=document-writer.js.map

package/dist/utils/document-writer.js.map

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

package/dist/utils/help-loader.d.ts

@@ -24,8 +24,8 @@ export declare function loadVerboseHelp(section?: string): string;
  * handed to the pipe, so `process.exit` has nothing left to lose.
  *
  * The loop itself now lives in `output.ts` as `writeStdoutSync`, because the very
- * same defect was later found in `writeYamlOutput` — every command's YAML summary
- * was being truncated at one pipe buffer. Two copies of this reasoning is exactly
+ * same defect was later found in the command-document writer — every command's
+ * YAML summary was being truncated at one pipe buffer. Two copies of this reasoning is exactly
  * how the second lane went unfixed for so long, so there is one.
  */
 export declare function writeHelpSync(content: string): void;

package/dist/utils/help-loader.js

@@ -52,8 +52,8 @@ Please report this issue at: https://github.com/jdutton/vibe-agent-toolkit/issue
  * handed to the pipe, so `process.exit` has nothing left to lose.
  *
  * The loop itself now lives in `output.ts` as `writeStdoutSync`, because the very
- * same defect was later found in `writeYamlOutput` — every command's YAML summary
- * was being truncated at one pipe buffer. Two copies of this reasoning is exactly
+ * same defect was later found in the command-document writer — every command's
+ * YAML summary was being truncated at one pipe buffer. Two copies of this reasoning is exactly
  * how the second lane went unfixed for so long, so there is one.
  */
 export function writeHelpSync(content) {

package/dist/utils/install-plan.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What the flat-skill install verbs — `vat claude plugin install` (its skill lanes), `vat agent install` and
+ * `vat skills install` — share about planning an install onto the tree-change primitive: the
+ * one change a skill copy is, the one link policy of a tree an install copies from, the one
+ * refusal an occupied destination is, and the one way an archive's `$TMPDIR` staging is disposed of.
+ */
+import { type SkillZipEntry } from '@vibe-agent-toolkit/agent-skills';
+import type { ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { type FsSide, type LinkPolicy, type Ownership, type TreeChange } from '@vibe-agent-toolkit/utils';
+/** The ownership of a skill destination: `--force` takes whatever is there; otherwise it must be free. */
+export declare function skillOwnership(force: boolean): Ownership;
+/**
+ * The link policy of a tree an install copies from, by the side it is on.
+ *
+ * - `environment` — VAT's own staging, holding what the archive module extracted: files and
+ *   directories, never a link. So a link found there is `refuse`d — never followed, never
+ *   copied — and an archive lane cannot install what its archive did not hold.
+ * - anything else — a directory the operator named. Its links are kept as links (`preserve`),
+ *   each already held inside the tree it is copied with ({@link installUnit}).
+ */
+export declare function installLinks(side: FsSide): LinkPolicy;
+/** Where an install reads from: the directory the operator named (or VAT's staging), and the side it is on. */
+interface InstallSourceTree {
+    readonly root: string;
+    readonly side: FsSide;
+}
+/**
+ * One tree an install is about to copy — a skill, a marketplace, a plugin — as the directory to
+ * copy it from, refused when copying it would install something its source does not hold.
+ *
+ * A staged tree (`environment`) is returned as it is: it holds no link ({@link installLinks}).
+ * A tree in the operator's own directory is judged twice, because a copy keeps its links as
+ * links, verbatim:
+ *
+ * - `dir` itself may be a link (a skill directory linked into `dist/skills/`), but only to
+ *   somewhere inside the directory the operator named;
+ * - no link inside it may lead outside it — `keys -> ../../../secret` stays inside the package
+ *   it was written in and points at the installing user's own files once it is installed.
+ *
+ * @param tree - The directory the operator named, and its side
+ * @param dir - The tree to copy: `tree.root` or a directory found under it
+ * @param what - What the tree is, for the refusal: `the skill directory`
+ * @returns The directory to copy from: `dir`, or for an operator's tree its real path, so the copy's root is never a link
+ * @throws VatError `COPY_LINK_ESCAPES_SOURCE` (`INPUT_UNREADABLE`) naming the link; FsFaultError on
+ *   the tree's side when the OS refuses to examine it
+ */
+export declare function installUnit(tree: InstallSourceTree, dir: string, what: string): string;
+/**
+ * One skill copied whole into place, every read of `source` classified on `side` — the
+ * operator's tree (`source`) or VAT's own staging an archive was extracted into (`environment`)
+ * — and its links held to that side's policy ({@link installLinks}).
+ */
+export declare function skillCopyChange(skill: {
+    readonly name: string;
+    readonly source: string;
+    readonly dest: string;
+}, side: FsSide, force: boolean): TreeChange;
+/**
+ * Where the skill is inside a skill ZIP, by the ONE layout rule every verb that takes one shares
+ * (`skillZipLayout`: `SKILL.md` at the top level, or directly inside the archive's single
+ * top-level folder) — or the refusal of an archive that is neither. The archive is the input, so
+ * the refusal is `INPUT_UNREADABLE`, decided from the entry list before anything is installed or sent.
+ *
+ * @param zipPath - The archive the operator named, for the message
+ * @param entries - Every entry of the archive, as `extractArchive` / `openArchive` list them
+ * @returns The folder the skill is in, relative to the archive's top level: `''`, or the one top-level folder
+ * @throws CommandRefusalError `INPUT_UNREADABLE`
+ */
+export declare function requireSkillZipLayout(zipPath: string, entries: readonly SkillZipEntry[]): string;
+/**
+ * Extract a skill ZIP into `into`, a fresh staging directory, and answer where the skill is in it.
+ * The ONE extraction of a skill ZIP, for every verb that takes one: held to the archive policy and
+ * limits, to the one layout rule ({@link requireSkillZipLayout}), and written WITHOUT what the
+ * host that made the archive added beside the skill (`hostAddedToSkillZip`: a top-level
+ * `__MACOSX/`, a `.DS_Store`) — the layout rule does not count those, so nothing installs or
+ * sends them.
+ *
+ * @param zipPath - The archive the operator named
+ * @param into - VAT's staging directory to extract into
+ * @returns The skill's directory: `into`, or the archive's one top-level folder under it
+ * @throws ArchiveRefusedError or CommandRefusalError (`INPUT_UNREADABLE`) for an archive VAT does not
+ *   take, with nothing written; FsFaultError as `extractArchive` raises it
+ */
+export declare function extractSkillZip(zipPath: string, into: string): Promise<string>;
+/** A destination taken without `--force`, as the invocation's refusal saying how to proceed; anything else as itself. */
+export declare function occupiedRefusal(error: unknown): unknown;
+/**
+ * Run `work` in a fresh staging directory under `$TMPDIR` (`withTempDir`), disposed of after. A
+ * directory that will not go once `work` finished is not a refusal of the install it outlived:
+ * it is handed to `onLeftover` as the warning naming it. A failure of `work` is rethrown, the
+ * staging's own leftover recorded beside it (`suppressedFaultsOf`).
+ *
+ * @param prefix - The `mkdtemp` prefix, so a leaked directory names its owner
+ * @param work - Given the staging directory
+ * @param onLeftover - Given the warning for a staging directory that outlived a finished `work`
+ */
+export declare function inStaging(prefix: string, work: (dir: string) => Promise<void>, onLeftover: (issue: ValidationIssue) => void): Promise<void>;
+export {};
+//# sourceMappingURL=install-plan.d.ts.map

package/dist/utils/install-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-plan.d.ts","sourceRoot":"","sources":["../../src/utils/install-plan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAuB,KAAK,aAAa,EAAkB,MAAM,kCAAkC,CAAC;AAC3G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAEL,KAAK,MAAM,EAGX,KAAK,UAAU,EAEf,KAAK,SAAS,EAKd,KAAK,UAAU,EAKhB,MAAM,2BAA2B,CAAC;AAMnC,0GAA0G;AAC1G,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAErD;AAED,+GAA+G;AAC/G,UAAU,iBAAiB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,CAQ1J;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAIhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF;AAED,yHAAyH;AACzH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjJ"}

package/dist/utils/install-plan.js

@@ -0,0 +1,146 @@
+/**
+ * What the flat-skill install verbs — `vat claude plugin install` (its skill lanes), `vat agent install` and
+ * `vat skills install` — share about planning an install onto the tree-change primitive: the
+ * one change a skill copy is, the one link policy of a tree an install copies from, the one
+ * refusal an occupied destination is, and the one way an archive's `$TMPDIR` staging is disposed of.
+ */
+import { hostAddedToSkillZip, skillZipLayout } from '@vibe-agent-toolkit/agent-skills';
+import { CopyLinkEscapesSourceError, HOST_PATH_FLAVOR, isVatError, normalizePath, refuseEscapingLinks, safePath, toForwardSlash, TREE_DEST_OCCUPIED_CODE, treeChain, treeContainment, withFsFaultSync, withTempDir, } from '@vibe-agent-toolkit/utils';
+import { ARCHIVE_LIMITS, extractArchive } from '@vibe-agent-toolkit/utils/archive';
+import { CommandRefusalError, errorMessageOf } from './command-refusal.js';
+import { leftoverIssue } from './document-writer.js';
+/** The ownership of a skill destination: `--force` takes whatever is there; otherwise it must be free. */
+export function skillOwnership(force) {
+    return force ? { kind: 'force' } : { kind: 'must-be-free' };
+}
+/**
+ * The link policy of a tree an install copies from, by the side it is on.
+ *
+ * - `environment` — VAT's own staging, holding what the archive module extracted: files and
+ *   directories, never a link. So a link found there is `refuse`d — never followed, never
+ *   copied — and an archive lane cannot install what its archive did not hold.
+ * - anything else — a directory the operator named. Its links are kept as links (`preserve`),
+ *   each already held inside the tree it is copied with ({@link installUnit}).
+ */
+export function installLinks(side) {
+    return side === 'environment' ? 'refuse' : 'preserve';
+}
+/**
+ * One tree an install is about to copy — a skill, a marketplace, a plugin — as the directory to
+ * copy it from, refused when copying it would install something its source does not hold.
+ *
+ * A staged tree (`environment`) is returned as it is: it holds no link ({@link installLinks}).
+ * A tree in the operator's own directory is judged twice, because a copy keeps its links as
+ * links, verbatim:
+ *
+ * - `dir` itself may be a link (a skill directory linked into `dist/skills/`), but only to
+ *   somewhere inside the directory the operator named;
+ * - no link inside it may lead outside it — `keys -> ../../../secret` stays inside the package
+ *   it was written in and points at the installing user's own files once it is installed.
+ *
+ * @param tree - The directory the operator named, and its side
+ * @param dir - The tree to copy: `tree.root` or a directory found under it
+ * @param what - What the tree is, for the refusal: `the skill directory`
+ * @returns The directory to copy from: `dir`, or for an operator's tree its real path, so the copy's root is never a link
+ * @throws VatError `COPY_LINK_ESCAPES_SOURCE` (`INPUT_UNREADABLE`) naming the link; FsFaultError on
+ *   the tree's side when the OS refuses to examine it
+ */
+export function installUnit(tree, dir, what) {
+    if (tree.side === 'environment')
+        return dir;
+    return withFsFaultSync({ side: tree.side, origin: 'content', action: `examine the links of ${what} ${dir}`, path: dir }, () => {
+        // `dir` may itself be a link, or below one: its chain is read by text first (the one resolver),
+        // so the kernel never resolves a link to a network path, or one leaving the tree, to answer this.
+        if (treeChain(tree.root, dir, HOST_PATH_FLAVOR).kind === 'refused')
+            throw new CopyLinkEscapesSourceError(dir, tree.root);
+        // An absent `dir` is not this check's to name: resolving it below raises the OS's own answer.
+        if (treeContainment(tree.root, dir) === 'outside')
+            throw new CopyLinkEscapesSourceError(dir, tree.root);
+        const real = toForwardSlash(normalizePath(dir, tree.root));
+        refuseEscapingLinks({
+            root: real,
+            placement: 'relocated',
+            side: tree.side,
+            flavor: HOST_PATH_FLAVOR,
+            tree: `${what} ${dir}`,
+            within: 'it',
+            consequence: 'An install keeps a link as a link, so once installed this one would point at files its source does not hold',
+        });
+        return real;
+    });
+}
+/**
+ * One skill copied whole into place, every read of `source` classified on `side` — the
+ * operator's tree (`source`) or VAT's own staging an archive was extracted into (`environment`)
+ * — and its links held to that side's policy ({@link installLinks}).
+ */
+export function skillCopyChange(skill, side, force) {
+    return {
+        op: 'replace',
+        dest: skill.dest,
+        ownership: skillOwnership(force),
+        fill: { from: 'copy', source: skill.source, side, links: installLinks(side) },
+        label: `skill ${skill.name}`,
+    };
+}
+/**
+ * Where the skill is inside a skill ZIP, by the ONE layout rule every verb that takes one shares
+ * (`skillZipLayout`: `SKILL.md` at the top level, or directly inside the archive's single
+ * top-level folder) — or the refusal of an archive that is neither. The archive is the input, so
+ * the refusal is `INPUT_UNREADABLE`, decided from the entry list before anything is installed or sent.
+ *
+ * @param zipPath - The archive the operator named, for the message
+ * @param entries - Every entry of the archive, as `extractArchive` / `openArchive` list them
+ * @returns The folder the skill is in, relative to the archive's top level: `''`, or the one top-level folder
+ * @throws CommandRefusalError `INPUT_UNREADABLE`
+ */
+export function requireSkillZipLayout(zipPath, entries) {
+    const layout = skillZipLayout(entries);
+    if ('refused' in layout)
+        throw new CommandRefusalError('INPUT_UNREADABLE', `${zipPath} is not a skill ZIP, nothing was changed: ${layout.refused}.`);
+    return layout.root;
+}
+/**
+ * Extract a skill ZIP into `into`, a fresh staging directory, and answer where the skill is in it.
+ * The ONE extraction of a skill ZIP, for every verb that takes one: held to the archive policy and
+ * limits, to the one layout rule ({@link requireSkillZipLayout}), and written WITHOUT what the
+ * host that made the archive added beside the skill (`hostAddedToSkillZip`: a top-level
+ * `__MACOSX/`, a `.DS_Store`) — the layout rule does not count those, so nothing installs or
+ * sends them.
+ *
+ * @param zipPath - The archive the operator named
+ * @param into - VAT's staging directory to extract into
+ * @returns The skill's directory: `into`, or the archive's one top-level folder under it
+ * @throws ArchiveRefusedError or CommandRefusalError (`INPUT_UNREADABLE`) for an archive VAT does not
+ *   take, with nothing written; FsFaultError as `extractArchive` raises it
+ */
+export async function extractSkillZip(zipPath, into) {
+    const entries = await extractArchive({ file: zipPath, side: 'source' }, into, { format: 'zip', limits: ARCHIVE_LIMITS, omit: (entry) => hostAddedToSkillZip(entry.name) });
+    return safePath.join(into, requireSkillZipLayout(zipPath, entries));
+}
+/** A destination taken without `--force`, as the invocation's refusal saying how to proceed; anything else as itself. */
+export function occupiedRefusal(error) {
+    if (!isVatError(error, TREE_DEST_OCCUPIED_CODE))
+        return error;
+    return new CommandRefusalError('USAGE_INVALID', `Something already exists where the install goes: ${error.message}. Use --force to overwrite.`, { cause: error });
+}
+/**
+ * Run `work` in a fresh staging directory under `$TMPDIR` (`withTempDir`), disposed of after. A
+ * directory that will not go once `work` finished is not a refusal of the install it outlived:
+ * it is handed to `onLeftover` as the warning naming it. A failure of `work` is rethrown, the
+ * staging's own leftover recorded beside it (`suppressedFaultsOf`).
+ *
+ * @param prefix - The `mkdtemp` prefix, so a leaked directory names its owner
+ * @param work - Given the staging directory
+ * @param onLeftover - Given the warning for a staging directory that outlived a finished `work`
+ */
+export async function inStaging(prefix, work, onLeftover) {
+    const { value: stagedIn, leftover } = await withTempDir(prefix, async (dir) => {
+        await work(dir);
+        return dir;
+    });
+    if (leftover === undefined)
+        return;
+    onLeftover(leftoverIssue(`The install is complete, but its staging directory ${stagedIn} could not be removed: ${errorMessageOf(leftover)}`, stagedIn));
+}
+//# sourceMappingURL=install-plan.js.map

package/dist/utils/install-plan.js.map

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

package/dist/utils/issue-anchor.d.ts

@@ -22,5 +22,5 @@ import type { ValidationIssue } from '@vibe-agent-toolkit/schema';
  * Returns `undefined` when the issue carries no anchor at all, so callers can
  * skip the line entirely rather than print an empty label.
  */
-export declare function formatIssueAnchor(issue: ValidationIssue): string | undefined;
+export declare function formatIssueAnchor(issue: Pick<ValidationIssue, 'location' | 'line' | 'field'>): string | undefined;
 //# sourceMappingURL=issue-anchor.d.ts.map

package/dist/utils/issue-anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-anchor.d.ts","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAe5E"}
+{"version":3,"file":"issue-anchor.d.ts","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAejH"}

package/dist/utils/issue-anchor.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue-anchor.js","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC;IAC1E,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC;IACjE,IAAI,CAAC,WAAW,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,MAAM,GAAG,WAAW,CAAC,CAAC,CAAE,KAAK,CAAC,QAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAC7C,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,GAAG,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,KAAe,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,KAAK,CAAC,KAAe,GAAG,CAAC;IACjG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"issue-anchor.js","sourceRoot":"","sources":["../../src/utils/issue-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA2D;IAC3F,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC;IAC1E,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC;IACjE,IAAI,CAAC,WAAW,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,MAAM,GAAG,WAAW,CAAC,CAAC,CAAE,KAAK,CAAC,QAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;IAC7C,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,GAAG,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,KAAe,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,KAAK,CAAC,KAAe,GAAG,CAAC;IACjG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}