commandmate 0.11.3 → 0.12.0

package/.next/types/validator.ts

@@ -119,6 +119,24 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/skills/[skillId]/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/skills/[skillId]">> = Specific
+  const handler = {} as typeof import("../../src/app/skills/[skillId]/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/skills/page.tsx
+{
+  type __IsExpected<Specific extends AppPageConfig<"/skills">> = Specific
+  const handler = {} as typeof import("../../src/app/skills/page.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/worktrees/[id]/files/[...path]/page.tsx
 {
   type __IsExpected<Specific extends AppPageConfig<"/worktrees/[id]/files/[...path]">> = Specific
@@ -434,6 +452,24 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/api/skills/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/skills/[id]">> = Specific
+  const handler = {} as typeof import("../../src/app/api/skills/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/skills/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/skills">> = Specific
+  const handler = {} as typeof import("../../src/app/api/skills/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/api/slash-commands/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/slash-commands">> = Specific
@@ -893,6 +929,51 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/api/worktrees/[id]/skills/[skillId]/install/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/skills/[skillId]/install">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/skills/[skillId]/install/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/worktrees/[id]/skills/[skillId]/plan/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/skills/[skillId]/plan">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/skills/[skillId]/plan/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/worktrees/[id]/skills/[skillId]/uninstall-plan/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/skills/[skillId]/uninstall-plan">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/skills/[skillId]/uninstall-plan/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/worktrees/[id]/skills/[skillId]/uninstall/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/skills/[skillId]/uninstall">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/skills/[skillId]/uninstall/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/worktrees/[id]/skills/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/skills">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/skills/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/api/worktrees/[id]/slash-commands/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/slash-commands">> = Specific

package/dist/cli/commands/skill-format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * skill command output formatting
+ * Issue #1237: renders Catalog entries and plans in the same vocabulary the UI
+ * uses (capability, effect, provenance, risk, target, diff, next action) so a
+ * user reading `--help` and one reading the browser see the same thing.
+ *
+ * Nothing here prints an absolute path, a token or an artifact URL: the API does
+ * not serve them, and these functions must not reconstruct them either.
+ */
+import type { SkillCatalogMeta, SkillCatalogSummary, SkillInstallPlan, SkillUninstallPlan } from '../types/api-responses';
+/**
+ * Freshness notice for a Catalog response, or null when it was confirmed current.
+ * Belongs on stderr: it qualifies the listing rather than being part of it.
+ */
+export declare function formatCatalogFreshness(catalog: SkillCatalogMeta): string | null;
+export declare function formatSkillTable(skills: SkillCatalogSummary[]): string;
+export declare function formatSkillDetail(skill: SkillCatalogSummary, version?: string): string;
+/**
+ * Render the install root(s). A dual-root install (#1460) lists every root so
+ * the user sees the package lands for both Codex and Claude; a single-root plan
+ * reads exactly as before.
+ */
+export declare function formatInstallRoots(roots: readonly string[] | undefined, primary: string): string;
+/** The install preview: what lands, where, at what risk, and what stands in the way. */
+export declare function formatInstallPlan(plan: SkillInstallPlan): string;
+/** The uninstall preview: what would be deleted, what would stay, and why. */
+export declare function formatUninstallPlan(plan: SkillUninstallPlan): string;
+//# sourceMappingURL=skill-format.d.ts.map

package/dist/cli/commands/skill-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-format.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/skill-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAgBhC;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAI/E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAatE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA2CtF;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CA8ChE;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CA2BpE"}

package/dist/cli/commands/skill-format.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * skill command output formatting
+ * Issue #1237: renders Catalog entries and plans in the same vocabulary the UI
+ * uses (capability, effect, provenance, risk, target, diff, next action) so a
+ * user reading `--help` and one reading the browser see the same thing.
+ *
+ * Nothing here prints an absolute path, a token or an artifact URL: the API does
+ * not serve them, and these functions must not reconstruct them either.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCatalogFreshness = formatCatalogFreshness;
+exports.formatSkillTable = formatSkillTable;
+exports.formatSkillDetail = formatSkillDetail;
+exports.formatInstallRoots = formatInstallRoots;
+exports.formatInstallPlan = formatInstallPlan;
+exports.formatUninstallPlan = formatUninstallPlan;
+/** [DR1-08 consistency] Mirrors ls.ts / instances.ts table rendering. */
+function formatTable(headers, rows) {
+    const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i].length)));
+    const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ');
+    return [
+        line(headers),
+        widths.map((w) => '-'.repeat(w)).join('  '),
+        ...rows.map(line),
+    ].join('\n');
+}
+/**
+ * Freshness notice for a Catalog response, or null when it was confirmed current.
+ * Belongs on stderr: it qualifies the listing rather than being part of it.
+ */
+function formatCatalogFreshness(catalog) {
+    if (!catalog.stale)
+        return null;
+    const reason = catalog.staleReason ?? catalog.state;
+    return `Warning: showing the last known good Catalog (${reason}); it could not be confirmed current.`;
+}
+function formatSkillTable(skills) {
+    if (skills.length === 0)
+        return 'No Skills are published in the official Catalog.';
+    return formatTable(['SKILL_ID', 'NAME', 'LATEST', 'RECOMMENDED', 'COMPATIBILITY'], skills.map((skill) => [
+        skill.id,
+        skill.name,
+        skill.latest,
+        skill.recommendedVersion ?? '-',
+        skill.compatibility?.status ?? 'unknown',
+    ]));
+}
+function formatSkillDetail(skill, version) {
+    const lines = [
+        `${skill.name} (${skill.id})`,
+        skill.summary,
+        '',
+        `Provider:     ${skill.provider.name}`,
+        `License:      ${skill.license}`,
+        `Latest:       ${skill.latest}`,
+        `Recommended:  ${skill.recommendedVersion ?? '-'} (${skill.recommendedReason})`,
+    ];
+    if (skill.homepage)
+        lines.push(`Homepage:     ${skill.homepage}`);
+    if (skill.compatibility) {
+        lines.push(`Compatibility: ${skill.compatibility.status} — ${skill.compatibility.message}`);
+    }
+    const versions = version
+        ? skill.versions.filter((entry) => entry.version === version)
+        : skill.versions;
+    lines.push('', 'Versions:');
+    if (versions.length === 0) {
+        lines.push(version
+            ? `  (no published version ${version}; pass --prerelease if it is a prerelease)`
+            : '  (none listed; pass --prerelease to include prereleases)');
+    }
+    else {
+        lines.push(formatTable(['VERSION', 'RISK', 'PRERELEASE', 'COMPATIBILITY', 'PUBLISHED'], versions.map((entry) => [
+            entry.version,
+            entry.declaredRisk,
+            entry.prerelease ? 'yes' : 'no',
+            entry.compatibility.commandmate.status,
+            entry.publishedAt,
+        ]))
+            .split('\n')
+            .map((row) => `  ${row}`)
+            .join('\n'));
+    }
+    return lines.join('\n');
+}
+function formatList(label, values) {
+    return `${label}${values.length > 0 ? values.join(', ') : '(none)'}`;
+}
+/**
+ * Render the install root(s). A dual-root install (#1460) lists every root so
+ * the user sees the package lands for both Codex and Claude; a single-root plan
+ * reads exactly as before.
+ */
+function formatInstallRoots(roots, primary) {
+    return roots && roots.length > 1 ? roots.join(', ') : primary;
+}
+/** The install preview: what lands, where, at what risk, and what stands in the way. */
+function formatInstallPlan(plan) {
+    const { skill, target, stats } = plan;
+    const lines = [
+        `Install plan: ${skill.name} ${skill.version} (${skill.id})`,
+        skill.summary,
+        '',
+        `Target:       ${target.repositoryName} / ${target.worktreeName} (${target.worktreeId})`,
+        `Branch:       ${target.branch ?? `(${target.headState})`}${target.workingTreeDirty ? ' [working tree dirty]' : ''}`,
+        `Install root: ${formatInstallRoots(target.installRoots, target.installRoot)}`,
+        `Risk:         ${skill.effectiveRisk} — ${skill.riskRationale}`,
+        `Compatibility: ${skill.compatibility.commandmate.status} — ${skill.compatibility.commandmate.message}`,
+        formatList('Permissions:  ', skill.declaredPermissions),
+        formatList('Scripts:      ', skill.scriptPaths),
+        formatList('Requires:     ', skill.requirements.commands.map((command) => command.versionRange ? `${command.name} ${command.versionRange}` : command.name)),
+        formatList('Network:      ', skill.requirements.networkHosts),
+        `Changes:      +${stats.added} added, ~${stats.modified} modified, =${stats.unchanged} unchanged, !${stats.conflicted} conflicting, ?${stats.unmanaged} unmanaged`,
+    ];
+    if (target.existingInstall) {
+        lines.push(`Already installed: ${target.existingInstall.version}`);
+    }
+    if (plan.warnings.length > 0) {
+        lines.push(`Warnings:     ${plan.warnings.join(', ')}`);
+    }
+    if (plan.blockers.length > 0) {
+        lines.push('Blockers:');
+        for (const blocker of plan.blockers) {
+            lines.push(`  - ${blocker.code}${blocker.path ? `: ${blocker.path}` : ''}`);
+        }
+    }
+    lines.push(plan.installable
+        ? 'Installable:  yes'
+        : 'Installable:  no — nothing would be written');
+    if (plan.requiresRiskAcknowledgement) {
+        lines.push(`High risk:    installing requires --ack-risk ${skill.id}@${skill.version} in addition to --yes`);
+    }
+    return lines.join('\n');
+}
+/** The uninstall preview: what would be deleted, what would stay, and why. */
+function formatUninstallPlan(plan) {
+    const { skill, target, stats } = plan;
+    const lines = [
+        `Uninstall plan: ${skill.id} ${skill.version}`,
+        '',
+        `Target:       ${target.repositoryName} / ${target.worktreeName} (${target.worktreeId})`,
+        `Branch:       ${target.branch ?? '(detached)'}${target.workingTreeDirty ? ' [working tree dirty]' : ''}`,
+        `Install root: ${target.installRoot}`,
+        `Risk:         ${skill.effectiveRisk}`,
+        `Files:        ${stats.removable} removable, ${stats.modified} locally modified, ${stats.missing} missing, ${stats.unknown} unmanaged, ${stats.irregular} irregular`,
+        `Removable:    ${plan.removable ? 'yes' : 'no — nothing would be deleted'}`,
+    ];
+    if (plan.retained.length > 0) {
+        lines.push('Retained:');
+        for (const entry of plan.retained) {
+            lines.push(`  - ${entry.path} (${entry.reason})`);
+        }
+    }
+    if (plan.blockers.length > 0) {
+        lines.push('Blockers:');
+        for (const blocker of plan.blockers) {
+            lines.push(`  - ${blocker.code}${blocker.path ? `: ${blocker.path}` : ''}`);
+        }
+    }
+    lines.push(`Next action:  ${plan.nextActionKey}`);
+    return lines.join('\n');
+}

package/dist/cli/commands/skill-guards.d.ts

@@ -0,0 +1,53 @@
+/**
+ * skill command guards — confirmation contract and typed error mapping
+ * Issue #1237: `commandmate skill` is a thin client over the Skill APIs, so the
+ * only safety logic that belongs here is the part the server cannot enforce:
+ * whether *this invocation* is allowed to ask for a write at all.
+ */
+import { ApiError } from '../utils/api-client';
+/**
+ * Validate a Skill ID before it is interpolated into a request path.
+ * The server validates it again; this only turns a typo into exit 2 instead of
+ * a request carrying an arbitrary path segment.
+ */
+export declare function isValidSkillId(id: string): boolean;
+/**
+ * Print a refusal on stderr and set the process exit code.
+ *
+ * Callers must `return` immediately afterwards: process.exit is stubbed in
+ * tests, so anything written after this line would still run — and, for a write
+ * command, would still reach the API.
+ */
+export declare function refuse(message: string, exitCode: number): void;
+/** Exit code for a failed Skill API call. */
+export declare function skillExitCode(error: ApiError): number;
+/**
+ * Report a failed skill subcommand.
+ *
+ * Everything goes to stderr, including the typed code and any blocker paths, so
+ * a `--json` run that fails emits nothing at all on stdout rather than a
+ * half-written or error-shaped document.
+ */
+export declare function handleSkillCommandError(error: unknown): void;
+/** How the confirmation requirement was settled. Only `confirmed` may write. */
+export type ConfirmationOutcome = 'confirmed' | 'declined' | 'non_interactive';
+/**
+ * Decide whether this invocation may proceed to a write.
+ *
+ * A non-TTY without `--yes` is refused rather than assumed: an environment that
+ * cannot show a prompt is exactly the one where an implicit yes would install
+ * something nobody watched.
+ */
+export declare function resolveWriteConfirmation(question: string, options: {
+    yes?: boolean;
+}): Promise<ConfirmationOutcome>;
+/**
+ * Whether `--ack-risk` names exactly this Skill and version.
+ *
+ * Deliberately an exact value rather than a flag: `--yes` is a blanket "don't
+ * prompt me" that a wrapper script sets once and forgets, so it must not be
+ * able to carry a high-risk install with it. Typing the id and version is the
+ * acknowledgement.
+ */
+export declare function riskAcknowledgementMatches(ackRisk: string | undefined, skillId: string, version: string): boolean;
+//# sourceMappingURL=skill-guards.d.ts.map

package/dist/cli/commands/skill-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-guards.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/skill-guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAO/C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG9D;AA8CD,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAOrD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAY5D;AAsBD,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,UAAU,GAAG,iBAAiB,CAAC;AAE/E;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAI9B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAET"}

package/dist/cli/commands/skill-guards.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * skill command guards — confirmation contract and typed error mapping
+ * Issue #1237: `commandmate skill` is a thin client over the Skill APIs, so the
+ * only safety logic that belongs here is the part the server cannot enforce:
+ * whether *this invocation* is allowed to ask for a write at all.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSkillId = isValidSkillId;
+exports.refuse = refuse;
+exports.skillExitCode = skillExitCode;
+exports.handleSkillCommandError = handleSkillCommandError;
+exports.resolveWriteConfirmation = resolveWriteConfirmation;
+exports.riskAcknowledgementMatches = riskAcknowledgementMatches;
+const readline = __importStar(require("readline"));
+const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
+const prompt_1 = require("../utils/prompt");
+/** Mirrors: src/lib/skills/constants.ts SKILL_ID_PATTERN / SKILL_ID_MAX_LENGTH. */
+const SKILL_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SKILL_ID_MAX_LENGTH = 64;
+/**
+ * Validate a Skill ID before it is interpolated into a request path.
+ * The server validates it again; this only turns a typo into exit 2 instead of
+ * a request carrying an arbitrary path segment.
+ */
+function isValidSkillId(id) {
+    return id.length > 0 && id.length <= SKILL_ID_MAX_LENGTH && SKILL_ID_PATTERN.test(id);
+}
+/**
+ * Print a refusal on stderr and set the process exit code.
+ *
+ * Callers must `return` immediately afterwards: process.exit is stubbed in
+ * tests, so anything written after this line would still run — and, for a write
+ * command, would still reach the API.
+ */
+function refuse(message, exitCode) {
+    console.error(`Error: ${message}`);
+    process.exit(exitCode);
+}
+/**
+ * Exit code for each typed Skill API error.
+ *
+ * The point of the table is the split the Issue asks for: a bad request or a
+ * missing Skill (fix the argv) must not look like a worktree that refused the
+ * write (fix the files, then re-plan), and neither may look like the Catalog
+ * being unreachable (retry later).
+ */
+const SKILL_ERROR_EXIT_CODES = {
+    // The request was wrong. Nothing about the worktree needs to change.
+    SKILL_PLAN_INPUT_REJECTED: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_PLAN_INVALID_BODY: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_INSTALL_INVALID_BODY: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_UNINSTALL_INVALID_BODY: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_PLAN_TARGET_UNSAFE: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_NOT_FOUND: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_VERSION_NOT_FOUND: types_1.ExitCode.CONFIG_ERROR,
+    SKILL_UNINSTALL_NOT_INSTALLED: types_1.ExitCode.CONFIG_ERROR,
+    // The target refused. Resolve the named path, or re-plan, then retry.
+    SKILL_PLAN_STALE: types_1.SkillExitCode.BLOCKED,
+    SKILL_PLAN_EXPIRED: types_1.SkillExitCode.BLOCKED,
+    SKILL_PLAN_CONSUMED: types_1.SkillExitCode.BLOCKED,
+    SKILL_PLAN_BINDING_MISMATCH: types_1.SkillExitCode.BLOCKED,
+    SKILL_PLAN_NOT_INSTALLABLE: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_DESTINATION_EXISTS: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_DESTINATION_UNMANAGED: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_TARGET_UNSAFE: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_LOCKED: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_IDEMPOTENCY_CONFLICT: types_1.SkillExitCode.BLOCKED,
+    SKILL_INSTALL_IN_PROGRESS: types_1.SkillExitCode.BLOCKED,
+    SKILL_UNINSTALL_BLOCKED: types_1.SkillExitCode.BLOCKED,
+    SKILL_UNINSTALL_TARGET_UNSAFE: types_1.SkillExitCode.BLOCKED,
+    SKILL_UNINSTALL_LOCKED: types_1.SkillExitCode.BLOCKED,
+    SKILL_UNINSTALL_IDEMPOTENCY_CONFLICT: types_1.SkillExitCode.BLOCKED,
+    SKILL_UNINSTALL_IN_PROGRESS: types_1.SkillExitCode.BLOCKED,
+    // An acknowledgement was missing, not a file.
+    SKILL_PLAN_RISK_NOT_ACKNOWLEDGED: types_1.SkillExitCode.CONFIRMATION_REQUIRED,
+};
+/** Statuses that mean "the dependency is unavailable", not "your request was wrong". */
+const AVAILABILITY_STATUSES = [502, 503, 504];
+/** Exit code for a failed Skill API call. */
+function skillExitCode(error) {
+    const mapped = error.apiCode ? SKILL_ERROR_EXIT_CODES[error.apiCode] : undefined;
+    if (mapped !== undefined)
+        return mapped;
+    if (error.statusCode !== undefined && AVAILABILITY_STATUSES.includes(error.statusCode)) {
+        return types_1.ExitCode.DEPENDENCY_ERROR;
+    }
+    return error.exitCode;
+}
+/**
+ * Report a failed skill subcommand.
+ *
+ * Everything goes to stderr, including the typed code and any blocker paths, so
+ * a `--json` run that fails emits nothing at all on stdout rather than a
+ * half-written or error-shaped document.
+ */
+function handleSkillCommandError(error) {
+    if (error instanceof api_client_1.ApiError) {
+        const detail = error.payload?.error ?? error.message;
+        console.error(error.apiCode ? `Error: ${detail} [${error.apiCode}]` : `Error: ${detail}`);
+        for (const blocker of error.payload?.blockers ?? []) {
+            console.error(`  - ${blocker.code}${blocker.path ? `: ${blocker.path}` : ''}`);
+        }
+        process.exit(skillExitCode(error));
+        return;
+    }
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+}
+/**
+ * Ask a yes/no question on stderr.
+ *
+ * The shared confirm() in utils/prompt.ts writes to stdout, which would land
+ * inside the document a `--json` run is expected to emit. Skill writes own their
+ * prompt so stdout carries the result and nothing else, in every mode.
+ */
+async function confirmOnStderr(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolvePromise) => {
+            rl.question(`${question} (y/N): `, resolvePromise);
+        });
+        const normalized = answer.trim().toLowerCase();
+        return normalized === 'y' || normalized === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Decide whether this invocation may proceed to a write.
+ *
+ * A non-TTY without `--yes` is refused rather than assumed: an environment that
+ * cannot show a prompt is exactly the one where an implicit yes would install
+ * something nobody watched.
+ */
+async function resolveWriteConfirmation(question, options) {
+    if (options.yes)
+        return 'confirmed';
+    if (!(0, prompt_1.isInteractive)())
+        return 'non_interactive';
+    return (await confirmOnStderr(question)) ? 'confirmed' : 'declined';
+}
+/**
+ * Whether `--ack-risk` names exactly this Skill and version.
+ *
+ * Deliberately an exact value rather than a flag: `--yes` is a blanket "don't
+ * prompt me" that a wrapper script sets once and forgets, so it must not be
+ * able to carry a high-risk install with it. Typing the id and version is the
+ * acknowledgement.
+ */
+function riskAcknowledgementMatches(ackRisk, skillId, version) {
+    return ackRisk !== undefined && ackRisk.trim() === `${skillId}@${version}`;
+}

package/dist/cli/commands/skill.d.ts

@@ -0,0 +1,24 @@
+/**
+ * skill Command - manage official Agent Skills from the CLI
+ * Issue #1237: a thin client over the Skill APIs (#1231/#1233/#1235/#1236)
+ *
+ *   commandmate skill list [--json]
+ *   commandmate skill info <skill-id> [--version <v>] [--json]
+ *   commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]
+ *   commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>]
+ *   commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]
+ *   commandmate skill status <skill-id> --worktree <id> [--json]
+ *
+ * The CLI never downloads, extracts, writes or deletes anything: it asks the
+ * server for a plan, shows it, and presents the token the server issued back to
+ * the server unchanged. It reconstructs no file list, no checksum and no path —
+ * those inputs are rejected by the API by design (#1233), and reproducing them
+ * here would create exactly the UI/CLI security drift the design forbids.
+ *
+ * `--json` prints the API response body verbatim, so the JSON contract is the
+ * API's. Every diagnostic, prompt and error goes to stderr, so a failed `--json`
+ * run leaves stdout empty rather than half-written.
+ */
+import { Command } from 'commander';
+export declare function createSkillCommand(): Command;
+//# sourceMappingURL=skill.d.ts.map

package/dist/cli/commands/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiWpC,wBAAgB,kBAAkB,IAAI,OAAO,CA+H5C"}