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

package/dist/commands/claude/org/skills.d.ts

@@ -1,4 +1,376 @@
+import type { MultipartFile, MultipartResult, OrgApiClient } from '@vibe-agent-toolkit/claude-marketplace';
+import type { ValidationConfig } from '@vibe-agent-toolkit/schema';
 import { Command } from 'commander';
+import type { OrgCommandFailure } from './helpers.js';
+export interface SkillUploadResult {
+    id: string;
+    displayTitle: string;
+    version: string;
+    createdAt: string;
+}
+interface UploadLogger {
+    info: (msg: string) => void;
+    /**
+     * REQUIRED, not optional. An optional `warn` invites `logger.warn?.(…)`,
+     * which drops the message wherever a caller supplied only `info` — and a
+     * warning that vanishes depending on its caller is the exact shape this
+     * command keeps being audited for.
+     */
+    warn: (msg: string) => void;
+}
+/** Read `POST /v1/skills` — the shape measured against the live API. */
+export declare function readCreateSkillResponse(raw: unknown): SkillUploadResult;
+/** The document a delete command publishes. */
+export interface SkillDeleteResult {
+    readonly id: string;
+    readonly deleted: boolean;
+}
+/**
+ * Read a DELETE response into the result a delete command prints.
+ *
+ * 🔑 Same class of problem as {@link readSkillUploadResponse} — the client's
+ * `<T>` is an assertion, not a check — but the OPPOSITE verdict on an empty
+ * body, and deliberately so. The client used to reject a 2xx carrying no body
+ * with a parse error, which reported a 204 DELETE that SUCCEEDED as a failure;
+ * that is fixed, and the value now handed to this reader for such a response is
+ * `undefined`. Refusing it here, the way an upload response is refused, would
+ * reinstate the same lie one layer up — and reading `.id` off it, which is what
+ * the two call sites did, is a `TypeError` in place of a report.
+ *
+ * So an empty body is read as the success it is: the status already said the
+ * resource is gone, the id is the one this process asked for, and there is
+ * nothing else to learn. Measured live behaviour today is a JSON body carrying
+ * `type: skill_deleted`, so the empty case is LATENT rather than a live
+ * regression — but it is one 204 away, and a latent `TypeError` is not a
+ * contract.
+ *
+ * `deleted` is false only when the body affirmatively names a DIFFERENT
+ * outcome, which is the one case where the API is saying something this command
+ * must not paper over — and {@link reportDelete} is what makes the run END that
+ * way rather than merely say so in a field nothing reads.
+ *
+ * ⚠️ `expectedTypes` is a LIST because only one member of it is measured.
+ * `skill_deleted` came back from a live `DELETE /v1/skills/{id}`;
+ * `skill_version_deleted` is the plausible spelling for the version endpoint and
+ * has never been seen. A single guessed string would make every version delete
+ * report `deleted: false` — and now exit 1 — if the vendor spells it differently
+ * by one character. Accepting either keeps the check honest about what it knows:
+ * a body naming something that is neither is a real divergence worth failing on.
+ */
+export declare function readDeleteResponse(raw: unknown, requestedId: string, expectedTypes: readonly string[]): SkillDeleteResult;
+/** The success types measured against the live `DELETE /v1/skills/{id}`. */
+export declare const SKILL_DELETED_TYPES: readonly string[];
+/**
+ * The success types a version delete may answer with — see
+ * {@link readDeleteResponse} for why this is two and not one.
+ */
+export declare const SKILL_VERSION_DELETED_TYPES: readonly string[];
+/**
+ * A delete's document, tagged as a FAILED run when the API said the thing was
+ * not deleted.
+ *
+ * 🔑 Without this, `deleted: false` was computed, printed under
+ * `status: success`, and exited 0 — the exact "the run completed and its outcome
+ * is wrong" shape that {@link orgCommandFailure} was added in this same change to
+ * fix for `--from-npm`, in the one branch that never got wired to it. A CI
+ * wrapper spelled `vat claude org skills delete X || fail` reported green while
+ * the skill was still there.
+ *
+ * The document is still PUBLISHED — the id and the verdict are what the operator
+ * needs — and only the exit code changes. Throwing instead would end non-zero and
+ * discard the report.
+ */
+export declare function reportDelete(raw: unknown, requestedId: string, expectedTypes: readonly string[]): SkillDeleteResult | OrgCommandFailure;
+/** The document a version delete publishes: which version, of which skill. */
+export interface SkillVersionDeleteResult extends SkillDeleteResult {
+    readonly version: string;
+}
+/**
+ * A version delete's document — the same verdict as {@link reportDelete}, about
+ * a subject that can actually be identified.
+ *
+ * 🚨 **The version-delete document used to name no version at all, and its `id`
+ * meant two different things depending on the response.** It went through
+ * `reportDelete(raw, skillId, …)`, so `readDeleteResponse` returned the API's
+ * ECHOED id when there was a body — the VERSION identifier — and fell back to
+ * the requested id — the SKILL identifier — on a 204. Two runs of the same
+ * command therefore published `id` fields from two different namespaces, and
+ * neither run's document said which of a skill's versions had been destroyed.
+ * An audit trail of an irreversible operation that cannot name what it destroyed
+ * is not an audit trail.
+ *
+ * Both fields are now local knowledge, which is the whole point: this process
+ * asked to delete `version` of `skillId` and the API confirmed a deletion, so
+ * nothing about the subject's identity has to be recovered from the response
+ * shape. The response is still read — for the VERDICT, which is the one thing
+ * only the API knows.
+ */
+export declare function reportVersionDelete(raw: unknown, skillId: string, version: string): SkillVersionDeleteResult | OrgCommandFailure;
+/**
+ * Add the versions a `--all` run destroyed to its report, preserving whatever
+ * verdict {@link reportDelete} reached.
+ *
+ * Unwrapping and re-wrapping rather than spreading into the tagged value: the
+ * failure tag sits BESIDE the document, so a naive `{ ...result, deletedVersions }`
+ * on a failure would produce an object carrying `orgCommandFailed` next to the
+ * skill's fields and publish the tag as part of the operator's document.
+ */
+export declare function mergeDeleteReport(result: SkillDeleteResult | OrgCommandFailure, deletedVersions: readonly string[]): object;
+/** Read `POST /v1/skills/{id}/versions`. */
+export declare function readSkillVersionResponse(raw: unknown): SkillUploadResult;
+/**
+ * Build the multipart request body for an upload, refusing it before anything is
+ * sent when THAT BODY is OVER the API's upload ceiling.
+ *
+ * 🔑 **The ceiling is INCLUSIVE, and that is measured rather than reasoned.** A
+ * request body of exactly {@link API_SKILL_MAX_UPLOAD_BYTES} bytes is ACCEPTED;
+ * one byte more is refused `413`:
+ *
+ * | raw file bytes | + framing | = body | live API |
+ * |---|---|---|---|
+ * | 31,456,735 | 545 | **31,457,280** | `status: success` |
+ * | 31,456,736 | 545 | 31,457,281 | `413` |
+ *
+ * So the comparison here is `>`, not `>=`. An earlier version of this code used
+ * `>=` on the argument that firing AT the ceiling was the conservative reading —
+ * an argument that was never measured, and the measurement above refutes it. It
+ * is not conservative: it refuses a body the API takes, and the operator has no
+ * way to tell that VAT and not Anthropic said no.
+ *
+ * ⚠️ **The build-time lane deliberately differs, and must not be "harmonised"
+ * with this one.** `checkPackagedSizeLimit` fires when FILE BYTES reach the same
+ * number — `>=` — because framing is never zero, so files totalling exactly the
+ * limit always produce a request LARGER than the limit and therefore a real 413.
+ * Two lanes, two measures, two rules: **file bytes `>=` refuse; request bytes `>`
+ * refuse.** Both are right about the quantity each can see.
+ *
+ * THE one gate every upload passes through, whichever shape it started as. The
+ * check used to live inside the directory-packaging step alone, so
+ * `skills install big-skill.zip` — the one input that is by construction a
+ * single large binary, and the shape the check was written for — reached the
+ * wire unmeasured.
+ *
+ * 🔑 **It weighs the BODY, not the sum of the file bytes.** The API measures the
+ * request, and the request is this buffer. Summing `file.content.length` — what
+ * this did — ignores the per-part framing `buildMultipartFormData` adds: a
+ * 51-byte boundary line, a `Content-Disposition` of 61 bytes plus the filename, a
+ * 42-byte content-type-and-blank-line and a 2-byte trailing CRLF, so 156 bytes
+ * plus the filename PER FILE, plus a 53-byte terminator. A 1,000-file bundle
+ * therefore carries ~180 KiB that the old measure could not see, and a bundle
+ * whose content sat just under the ceiling passed the pre-flight and then earned
+ * the 413 this check exists to prevent — 11 seconds for 30 MB, measured.
+ *
+ * No headroom constant closes that gap, and none is added: the exact number is
+ * available for free by building the body first and asking it how long it is.
+ * The body is then RETURNED, so the bytes that were weighed are the bytes that go
+ * out; a gate that only inspected its inputs would be one refactor away from
+ * measuring something the caller no longer sends.
+ *
+ * The build-time `PACKAGED_SIZE_EXCEEDS_API_LIMIT` cannot do this — there is no
+ * request at build time — so it weighs files on disk and says so. The two
+ * messages name what each measured rather than pretending to be the same number.
+ */
+export declare function buildUploadBodyOrRefuse(fields: Record<string, string>, files: readonly MultipartFile[], bundleRoot?: string): MultipartResult;
+/**
+ * A vendor refusal this CLI can answer with a specific next command.
+ *
+ * `matches` are ALL required, and are deliberately more than one: a single word
+ * like `version` appears in refusals that have nothing to do with this case, so
+ * each entry names both the subject the API is talking about and the verdict it
+ * reached about it.
+ */
+interface VendorRefusalRemedy {
+    /** Every pattern must match the API's message for the remedy to apply. */
+    readonly matches: readonly RegExp[];
+    /** Appended to the vendor's sentence — never substituted for it. */
+    readonly remedy: string;
+}
+/**
+ * A failed request, re-thrown with the command that answers it when — and only
+ * when — the API said one of the specific things listed by the caller.
+ *
+ * **What is matched, exactly:** an {@link ApiRequestError} whose `statusCode` is
+ * 400 and whose message satisfies every pattern of one {@link
+ * VendorRefusalRemedy}. Both live wordings are measured, not guessed:
+ * `400 Skill cannot reuse an existing display_title` and
+ * `400 Cannot delete skill with existing versions. Delete all versions first.`
+ *
+ * **How it fails safe:** anything that does not match is returned UNTOUCHED, so
+ * an unrelated 400 keeps the API's exact words and gets no misleading remedy. If
+ * the vendor rewords a refusal, the operator loses a hint — they never gain a
+ * wrong one. The remedy is appended, so the vendor's sentence survives in full.
+ *
+ * One mechanism, several refusals, and each call site passes only the refusals
+ * that are REACHABLE from it — a second copy of this matcher per case is how the
+ * two would come to disagree about what "fail safe" means.
+ */
+export declare function withRemedy(error: unknown, candidates: readonly VendorRefusalRemedy[]): unknown;
+/**
+ * The skill still has versions, so it cannot be deleted.
+ *
+ * `--all` leads, because it IS the one-step path: the `--all` branch of this
+ * command fetches every version and deletes them before deleting the skill. The
+ * by-hand sequence follows for an operator who wants to see what is there first.
+ * Naming only `versions delete` would send them round a loop they can already
+ * ask the CLI to run.
+ */
+export declare const EXISTING_VERSIONS_REFUSAL: VendorRefusalRemedy;
+/** Only the CREATE path can earn a duplicate-title refusal — see {@link uploadSkillDir}. */
+export declare function withDuplicateTitleRemedy(error: unknown): unknown;
+/**
+ * The version's SKILL.md declares a different `name` than the skill it is being
+ * added to.
+ *
+ * The server enforces name consistency per `skill_id` (measured), which is why
+ * `versions add` cannot silently re-root a skill's file tree and why this is the
+ * one refusal that endpoint can earn. The remedy names both fixes, because which
+ * one is right depends on what the operator meant: keep the skill and put its
+ * name back, or publish the renamed tree as the separate skill it now is.
+ *
+ * ⚠️ The vendor's exact wording here has NOT been measured, only the fact of the
+ * refusal. `withRemedy` fails safe on no match — the operator loses a hint, never
+ * gains a wrong one — so a guessed pattern is the conservative thing to ship.
+ */
+export declare const VERSION_NAME_MISMATCH_REFUSAL: VendorRefusalRemedy;
+/** Only the VERSION path can earn a name-consistency refusal — see {@link uploadSkillVersionDir}. */
+export declare function withVersionRootRemedy(error: unknown): unknown;
+/**
+ * A failure that got NO answer from the server, re-thrown saying what was
+ * actually sent and what a retry would risk.
+ *
+ * ⛔ **The trigger is a RECORDED FACT, never the error's class.** This used to
+ * read `if (error instanceof ApiRequestError) return error;` — "a completed
+ * exchange always arrives as an `ApiRequestError`, so anything else must be a
+ * dropped connection". The first half is true and the converse is not, and the
+ * converse is what shipped: `buildSkillsHeaders()` throws a plain `Error` before
+ * a socket is ever opened, so
+ * `ANTHROPIC_API_KEY= vat claude org skills install <dir>` told a first-time
+ * operator, on top of the real "no key" message, that a connection had closed,
+ * that VAT had sent 6.8 KiB (the length of a buffer that never left the process),
+ * and that the outcome was unknown — then sent them to a recovery command that
+ * fails with the identical missing-key error. Three false statements and a loop.
+ *
+ * So the gate is POSITIVE and evidential: annotate only an
+ * {@link ApiTransportError}, which exists only once the transport has been
+ * reached and carries `bytesSent` read off the socket at failure time. Anything
+ * else — a missing credential, a bad URL, a response VAT refused to read —
+ * passes through with its own message untouched.
+ *
+ * Two outcomes, because the byte count decides which is TRUE:
+ *
+ * - **Nothing left the machine** (`bytesSent === 0`: DNS never resolved, the
+ *   connection was refused, the handshake failed). The outcome is not unknown,
+ *   it is known: nothing happened. Saying "check what exists" here would send
+ *   an operator to look for a skill that was never sent.
+ * - **Some bytes went out and no status came back.** Now the outcome genuinely
+ *   is unknown, and the part the operator cannot see is how far it got. The
+ *   client never replays a POST — one that failed with no status may still have
+ *   taken effect — so the retry is theirs, and it can leave two skills behind.
+ *
+ * **No threshold.** There is no constant here for "close to the ceiling" and
+ * there must not be: an invented margin is a number nobody can re-derive. The
+ * bytes sent, the body size and the ceiling are printed and the reader draws
+ * their own conclusion.
+ */
+export declare function explainAnsweredNothing(error: unknown, bodyBytes: number): unknown;
+/**
+ * Resolve a `<source>` CLI argument to an absolute path.
+ *
+ * 🪤 The test used to be `source.startsWith('/')`, which is false for
+ * `D:\builds\skill` — so a Windows operator's absolute path was joined onto the
+ * working directory and reported back as `Source not found: <cwd>/D:/builds/skill`.
+ * {@link isAbsoluteAnyPlatform} answers for POSIX roots, drive letters and UNC
+ * paths on EVERY host, so the behaviour is the same wherever it runs and a
+ * POSIX-only CI can see the drive-letter case at all.
+ */
+export declare function resolveSourceArgument(source: string): string;
+/** What {@link inspectZipArchive} can tell a caller about an archive. */
+export interface ZipInspection {
+    /** The API-enforced quantity: the sum of every entry's declared size. */
+    readonly uncompressedBytes: number;
+    /** The `name` declared by the SKILL.md nearest the archive root, if any. */
+    readonly declaredName: string | undefined;
+    /**
+     * Entry names carrying a {@link NEVER_UPLOADED_DIR_NAMES} path segment —
+     * `evals/` above all. The directory lane REFUSES these; this is what lets the
+     * ZIP lane reach the same verdict about the same content.
+     */
+    readonly neverUploaded: readonly string[];
+    /**
+     * Every markdown member, inflated, shaped as the parts the directory lane
+     * hands {@link warnUnportableReferences} — so the ZIP lane runs the SAME
+     * checks over the same content rather than a second implementation of them.
+     *
+     * Markdown only, and only within {@link MAX_INSPECTED_DOCUMENT_BYTES} an
+     * entry: these detectors read prose, and inflating an archive's binaries to
+     * hand them to a reader that skips them is work spent to produce nothing.
+     */
+    readonly documents: readonly MultipartFile[];
+    /**
+     * The archive's top-level directory, when it has one — the prefix
+     * {@link bundleRelativeName} strips so a finding is located in the same
+     * namespace a `validation.allow` glob is matched in. `undefined` for an
+     * archive whose SKILL.md sits at the root, which has no prefix to strip.
+     */
+    readonly bundleRoot: string | undefined;
+    /**
+     * Members this inspection wanted and could not inflate — a bad CRC, a
+     * compression method that is not store/deflate, an encrypted entry — each
+     * with the reader's reason. Skipped, never fatal (an archive VAT cannot read
+     * is not an archive VAT should block), but NAMED: a document that was not
+     * checked is a promise `install --help` makes that this run did not keep,
+     * and the operator is owed the list.
+     */
+    readonly unreadable: readonly ZipEntryFailure[];
+}
+/** One archive member the reader refused, and why. */
+export interface ZipEntryFailure {
+    readonly entry: string;
+    readonly reason: string;
+}
+/** An archive the reader could not open at all, and why. */
+export interface ZipUnreadable {
+    readonly archiveUnreadable: string;
+}
+/**
+ * What a ZIP will weigh AFTER the API expands it, read from the archive's own
+ * central directory — plus the name its inner SKILL.md declares, any answer key
+ * it carries, and the markdown members the portability checks read.
+ *
+ * 🔑 **The API expands a ZIP and applies the ceiling to the UNCOMPRESSED total,
+ * not to the archive.** Measured against the live API by an adopter: a
+ * 10,707,463-byte archive of a 47.85 MiB tree — comfortably inside the request
+ * ceiling as bytes on the wire — came back
+ * `400: Zip file uncompressed size exceeds 30MB`. So the body check every other
+ * shape passes through is structurally blind here: compression is exactly the
+ * thing that makes the measured quantity stop predicting the enforced one. A
+ * ZIP is therefore the one input that could pass every local gate and still be
+ * refused remotely, which is the same defect class as the ZIP path once
+ * skipping the size check altogether.
+ *
+ * ⚠️ **The boundary itself is UNMEASURED on this lane.** One refusal at 47.85
+ * MiB is all the evidence there is; nobody has bracketed where the uncompressed
+ * rule actually cuts, or confirmed it is the same constant as the request lane.
+ * So this refuses only on `>` — strictly the looser choice — and a bundle near
+ * the line is still sent for the API to judge. Do not tighten this to `>=`, or
+ * quote it as a measured ceiling, without bracketing it the way
+ * {@link API_SKILL_MAX_UPLOAD_BYTES} was bracketed.
+ *
+ * ⛔ Sizes come from entry HEADERS, which an archive can lie about. That is
+ * fine: a lie can only change whether VAT refuses early, never whether the API
+ * does.
+ *
+ * ⚠️ **Reading an entry is not free, and the docstring here used to claim it
+ * was** — "no zip-slip or zip-bomb surface is opened — the entries are read, not
+ * written" was true of the enumeration half and FALSE of the one `getData()`
+ * call, which inflates `header.size` bytes into memory. Worse, it ran BEFORE the
+ * caller's uncompressed-total gate, so the ceiling this function exists to
+ * enforce could not protect the inflation this function performed. Nothing is
+ * written to disk — that part stands — but the decompression is now ordered
+ * after the total is known and bounded by {@link MAX_INSPECTED_DOCUMENT_BYTES},
+ * so an archive declaring a 4 GiB SKILL.md is enumerated and never inflated.
+ */
+export declare function inspectZipArchive(zipPath: string): Promise<ZipInspection | ZipUnreadable>;
 interface CollectedUploadFiles {
     files: Array<{
         relativePath: string;
@@ -19,6 +391,161 @@ interface CollectedUploadFiles {
  * no caller can obtain an upload set with the exclusion skipped.
  */
 export declare function collectSkillUploadFiles(skillDir: string): Promise<CollectedUploadFiles>;
+/**
+ * Warn about references in the bundle that cannot resolve once it is published.
+ *
+ * 🚨 **Until this existed, `install` validated NOTHING.** It weighed the request
+ * and sent it; every check VAT owns — the non-portable reference family, the
+ * unqualified MCP tool names, the non-portable command family — ran in
+ * `vat audit` and `vat skills build` and never on the one path where content
+ * leaves the machine. An adopter found the consequence directly: of 54 built
+ * skills, 10 referenced paths outside their own directory, one of them exec'ing
+ * a script under a SIBLING skill. Under the Skills API each skill is its own
+ * top-level tree with no siblings, so those uploaded with a green tick and could
+ * not possibly run. "It uploaded" is not "it works", and the publish command was
+ * the only lane in a position to say so before the bytes left.
+ *
+ * ⚠️ **Warns, never refuses.** These are `warning`-severity codes and the
+ * operator may have reasons VAT cannot see; turning a publish into an exit 2 on
+ * a heuristic is a worse failure than the one being reported. Blocking belongs
+ * to `vat skills build` and `vat audit`, which run before this and can gate CI.
+ *
+ * Costs nothing extra: it reads the buffers already collected for the upload, so
+ * no file is opened twice and nothing is walked again.
+ *
+ * 🚨 **The three collectors are RAW issue producers, and raw issues are not what
+ * an adopter agreed to see.** Everywhere else in VAT they pass through
+ * {@link runValidationFramework}, which applies `validation.allow` waivers and
+ * `validation.severity` overrides. Printed unfiltered, this lane contradicted
+ * VAT's own documented remedy: `MCP_TOOL_NAME_UNQUALIFIED` tells authors to
+ * "waive that one identifier with a `validation.allow` entry", and an author who
+ * did exactly that got a green `vat skills build` and then the same warning on
+ * every publish with nothing left to silence it with.
+ *
+ * ⚠️ The `location` is the BUNDLE-relative path, not the API-keyed
+ * `<declared-name>/<path>` spelling. An allow glob matches `ValidationIssue.location`,
+ * which is contractually project/bundle-relative, so the keyed spelling could not
+ * have matched an entry even once allows were applied — the same divergence
+ * {@link bundleRelativeName} exists to strip out of the oversize message.
+ *
+ * ⛔ The run-level ALLOW_UNUSED sweep is deliberately NOT drained here. This lane
+ * runs three validator families out of the whole registry, so every allow entry
+ * for any other code would be reported as dead — advising the author to delete
+ * the entry that makes their build green.
+ */
+export declare function warnUnportableReferences(files: readonly MultipartFile[], bundleRoot: string | undefined, validation: ValidationConfig | undefined, logger: UploadLogger): void;
+/**
+ * List candidate package directories in node_modules (scoped + unscoped).
+ *
+ * Exported for testing: this and {@link findSkillsDir} decide WHICH tree
+ * `--from-npm` publishes to an org, and the whole `--from-npm` path was
+ * untested — `packages/cli/src/commands/**` is coverage-excluded, so nothing in
+ * any report said so.
+ */
+export declare function listNodeModulePackages(nodeModulesDir: string): string[];
+/**
+ * Find the dist/skills/ directory in a package. Checks the package itself
+ * first, then scans node_modules for sub-packages that contain built skills.
+ */
+export declare function findSkillsDir(packageDir: string): string | undefined;
+/** One skill the batch could not publish, and why. */
+export interface SkillUploadFailure {
+    readonly skill: string;
+    readonly error: string;
+}
+/** The document `install --from-npm` publishes. */
+export interface NpmInstallSummary {
+    source: string;
+    skillsUploaded: number;
+    skillsFailed?: number;
+    errors?: readonly SkillUploadFailure[];
+    skills: readonly SkillUploadResult[];
+}
+/**
+ * The batch's report, tagged as a failure when ANY skill did not publish.
+ *
+ * 🔑 Partial success is a failure. The old code returned this document plainly,
+ * so `executeOrgCommand` stamped `status: success` on it and exited 0 — a run in
+ * which all three skills were rejected printed `skillsUploaded: 0 /
+ * skillsFailed: 3` under `status: success`, and a CI wrapper written as
+ * `vat claude org skills install --from-npm … || fail` published nothing and
+ * reported green.
+ *
+ * Some-succeeded is tagged the same way as none-succeeded, deliberately: the
+ * workspace is now in a MIXED state that nobody asked for, which is exactly the
+ * case a human has to look at. Calling it green because two of three landed is
+ * the same lie, only smaller. What did land stays in the document, so the reader
+ * can see how far the run got.
+ */
+export declare function summarizeNpmInstall(source: string, results: readonly SkillUploadResult[], errors: readonly SkillUploadFailure[]): NpmInstallSummary | OrgCommandFailure;
+/**
+ * Upload a local skill directory or ZIP file. Exported for testing.
+ */
+export declare function installFromLocal(source: string, titleOverride: string | undefined, client: OrgApiClient, logger: UploadLogger): Promise<object>;
+/** One version the sweep could not delete, and the reason it gave. */
+export interface VersionDeleteFailure {
+    readonly version: string;
+    readonly reason: string;
+}
+/** What a `--all` sweep did to the versions it was handed. */
+export interface VersionSweep {
+    /** Versions this run destroyed. Irreversible, and the record of it. */
+    readonly deleted: readonly string[];
+    /** Versions still there, each with why. Empty means the sweep is complete. */
+    readonly failures: readonly VersionDeleteFailure[];
+}
+/**
+ * Delete every version handed in, and keep going when one refuses.
+ *
+ * 🚨 **One refusal is a fact about ONE version.** This loop used to return on the
+ * first one, so every version after it was never ATTEMPTED — not failed, not
+ * reported, unexamined. Deleting a workspace skill requires deleting every
+ * version first, so the operator was left with a skill that could not be deleted,
+ * a report that named one problem out of an unknown number, and no way to tell
+ * from the output which versions were still there. A transient refusal on version
+ * 2 of 30 hid the state of the other 28.
+ *
+ * The sweep therefore ATTEMPTS all of them and reports both lists. The caller
+ * decides what the outcome means: some deleted plus some failed is a run that
+ * happened and went wrong (exit 1, with the record); nothing deleted at all is
+ * the ending the command's help documents as exit 2.
+ *
+ * ⛔ It deliberately does NOT stop early on a repeated failure. A "the API is
+ * clearly down, give up" heuristic is how the abandoned-versions defect reads
+ * from inside: the whole value here is that every version's state is KNOWN when
+ * the command ends.
+ */
+export declare function deleteEveryVersion(client: Pick<OrgApiClient, 'deleteSkillVersion'>, skillId: string, versions: readonly string[], logger: UploadLogger): Promise<VersionSweep>;
+/**
+ * Every version the sweep could not delete, and why — the one sentence both the
+ * published report and the exit-2 throw are built from, so the two endings never
+ * describe the same run differently.
+ */
+export declare function describeVersionSweepFailures(failures: readonly VersionDeleteFailure[]): string;
+/** What {@link reportHalfDeleted} needs to describe a run that destroyed some of what it was asked to. */
+export interface HalfDeletedReport {
+    readonly skillId: string;
+    readonly deletedVersions: readonly string[];
+    /** Versions still present. Empty when the sweep completed and the SKILL delete is what failed. */
+    readonly failedVersions: readonly string[];
+    readonly error: string;
+}
+/**
+ * The document a `--all` run publishes when it destroyed something and then did
+ * not finish.
+ *
+ * 🔑 The deleted list is a RECORD, not a progress counter. Version deletion is
+ * irreversible, so a failure part-way through leaves a workspace nobody can
+ * reconstruct — and throwing here would end on `handleCommandError`'s exit 2
+ * ("the run could not happen") and DISCARD the document. It happened, and it
+ * destroyed things the operator now has no other list of. So the lists travel
+ * with the failure and the run ends 1: it happened, and its outcome is wrong.
+ *
+ * `failedVersions` is the other half, and the half a re-run needs: what is still
+ * there. Without it the operator knows what they lost and not what they still
+ * have to deal with.
+ */
+export declare function reportHalfDeleted(report: HalfDeletedReport): OrgCommandFailure;
 export declare function createOrgSkillsCommand(): Command;
 export {};
 //# sourceMappingURL=skills.d.ts.map

package/dist/commands/claude/org/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../../src/commands/claude/org/skills.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwFpC,UAAU,oBAAoB;IAC7B,KAAK,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AA8DD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAI7F;AAsMD,wBAAgB,sBAAsB,IAAI,OAAO,CAoKhD"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../../src/commands/claude/org/skills.ts"],"names":[],"mappings":"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"}