@kisev/skills-opencode 1.2.0 → 2.0.0

package/dist/cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { AgentProfileError, applyAgentProfileChange, availableModels, availableModelVariants, FIXED_AGENT_ROLES, listAgentProfiles, previewAgentProfileChange, validateAgentName, validateModel, validateVariant, } from "./agent-profiles.js";
-import { renderInventory, renderPlan, shellCommand, terminalSafe } from "./cli-output.js";
-import { apply, InstallerError, preview } from "./installer.js";
+import { renderDoctor, renderInventory, renderPlan, renderReconcile, shellCommand, terminalSafe } from "./cli-output.js";
+import { collectDoctorFacts, doctorExitCode } from "./doctor.js";
+import { CATALOG } from "./catalog.js";
+import { apply, defaultSelection, InstallerError, normalizeSelection, PACKAGE_COMMANDS, preview, SELECTABLE_PLUGINS, SKILL_COMMANDS } from "./installer.js";
 import { LifecycleError } from "./lifecycle.js";
+import { applyReconcile, previewReconcile } from "./reconcile.js";
 import { promptText, selectOption } from "./terminal-wizard.js";
-function parseOptions(values) {
-    const options = { dryRun: false, json: false };
+function parseOptions(values, requireScope = true) {
+    const options = { dryRun: false, json: false, selectionFlag: false };
     for (let index = 0; index < values.length; index += 1) {
         const value = values[index];
         if (!value.startsWith("--")) {
@@ -58,14 +61,78 @@ function parseOptions(values) {
                 throw new InstallerError("invalid_input", "--json may be supplied once");
             options.json = true;
         }
+        else if (["--commands", "--skill-commands", "--package-commands", "--agents", "--plugins"].includes(value)) {
+            const raw = values[++index];
+            if (!raw)
+                throw new InstallerError("invalid_input", `${value} requires a comma-separated value`);
+            const target = value === "--agents" ? "agents" : value === "--plugins" ? "plugins" : "commands";
+            const names = raw === "none" ? [] : raw.split(",").map((item) => item.trim()).filter(Boolean);
+            options.selectionFlag = true;
+            if (value === "--package-commands") {
+                options.commands = [...(options.commands ?? []), ...names];
+            }
+            else if (value === "--skill-commands") {
+                options.commands = [...(options.commands ?? []), ...names];
+            }
+            else {
+                options[target] = names;
+            }
+        }
         else {
             throw new InstallerError("invalid_input", `Unknown argument: ${value}`);
         }
     }
-    if (!options.scope)
+    if (requireScope && !options.scope)
         throw new InstallerError("invalid_input", "--scope is required");
     return options;
 }
+function help() {
+    return [
+        "Usage: skills-opencode <command> [options]",
+        "",
+        "Commands: install, uninstall, doctor, capabilities, reconcile, agent list|configure|model-set|reconcile, critic add|remove",
+        "Mutations: use --dry-run for preview, then --confirm <digest>.",
+        "Install selection: --commands, --package-commands, --agents, --plugins (comma-separated or none).",
+        "Read-only: --json is stable machine-readable output; --help and --version need no scope.",
+        "",
+    ].join("\n");
+}
+async function interactiveInstallerSelection() {
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        throw new InstallerError("terminal_required", "install requires explicit selection flags outside a terminal");
+    const group = async (label, names, initial) => {
+        const choices = ["Select all", "Select none", ...names];
+        const selected = await selectOption(label, choices, process.stdin, process.stderr, initial);
+        if (selected === null)
+            throw new InstallerError("cancelled", "Wizard cancelled");
+        if (selected === 0)
+            return [...names];
+        if (selected === 1)
+            return [];
+        return [names[selected - 2]];
+    };
+    const commands = [
+        ...(await group("Skill commands", SKILL_COMMANDS, 0)),
+        ...(await group("Package commands", PACKAGE_COMMANDS, 0)),
+    ];
+    const agents = await group("Fixed agents", defaultSelection().agents, 0);
+    const plugins = await group("Selectable plugins (none selected by default)", SELECTABLE_PLUGINS, 1);
+    return normalizeSelection({ commands, agents: agents, plugins: plugins });
+}
+function installerSelection(options) {
+    return normalizeSelection({
+        commands: options.commands,
+        agents: options.agents,
+        plugins: options.plugins,
+    });
+}
+function selectionArguments(selection) {
+    return [
+        "--commands", selection.commands.join(",") || "none",
+        "--agents", selection.agents.join(",") || "none",
+        "--plugins", selection.plugins.join(",") || "none",
+    ];
+}
 function requireConfirmationMode(options) {
     if (options.dryRun === Boolean(options.confirm))
         throw new InstallerError("invalid_input", "Use exactly one of --dry-run or --confirm <digest>");
@@ -234,7 +301,61 @@ function profileConfirmationArguments(request, scope, digest) {
     return command;
 }
 async function run(arguments_) {
+    if (arguments_.includes("--help") || arguments_.length === 0) {
+        process.stdout.write(help());
+        return;
+    }
+    if (arguments_.includes("--version")) {
+        process.stdout.write(arguments_.includes("--json")
+            ? `${JSON.stringify({ status: "ok", version: CATALOG.version })}\n`
+            : `${CATALOG.version}\n`);
+        return;
+    }
     const [domain, operation, ...rest] = arguments_;
+    if (domain === "doctor") {
+        if (operation)
+            rest.unshift(operation);
+        const options = parseOptions(rest);
+        if (options.dryRun || options.confirm || options.name || options.provider || options.model || options.variant !== undefined)
+            throw new InstallerError("invalid_input", "doctor accepts only --scope and --json");
+        const report = await collectDoctorFacts(options.scope);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        else
+            process.stdout.write(renderDoctor(report));
+        process.exitCode = doctorExitCode(report);
+        return;
+    }
+    if (domain === "capabilities") {
+        const options = parseOptions(rest, false);
+        if (options.dryRun || options.confirm || options.name || options.provider || options.model || options.variant !== undefined || options.selectionFlag)
+            throw new InstallerError("invalid_input", "capabilities accepts only --scope and --json");
+        process.stdout.write(`${JSON.stringify({ schema_version: 1, status: "ok", ...CATALOG }, null, 2)}\n`);
+        return;
+    }
+    if (domain === "reconcile") {
+        if (operation)
+            rest.unshift(operation);
+        const options = parseOptions(rest);
+        if (options.name || options.provider || options.model || options.variant !== undefined)
+            throw new InstallerError("invalid_input", "reconcile accepts only scope and confirmation options");
+        requireConfirmationMode(options);
+        if (options.dryRun) {
+            const plan = await previewReconcile(options.scope);
+            if (options.json)
+                process.stdout.write(`${JSON.stringify({ status: "ok", applied: false, plan }, null, 2)}\n`);
+            else
+                process.stdout.write(renderReconcile(plan, { applied: false, confirmationCommand: shellCommand(["reconcile", "--scope", options.scope, "--confirm", plan.digest]) }));
+        }
+        else {
+            const applied = await applyReconcile(options.scope, options.confirm);
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(applied, null, 2)}\n`);
+            else
+                process.stdout.write(renderReconcile(applied.plan, { applied: true }));
+        }
+        return;
+    }
     if (domain === "install" || domain === "uninstall") {
         if (operation?.startsWith("--") || operation === undefined)
             rest.unshift(...(operation ? [operation] : []));
@@ -243,17 +364,22 @@ async function run(arguments_) {
         const options = parseOptions(rest);
         if (options.name || options.provider || options.model || options.variant !== undefined)
             throw new InstallerError("invalid_input", "Installer accepts only scope and confirmation options");
-        requireConfirmationMode(options);
         const action = domain;
+        if (action === "install" && options.selectionFlag && (options.commands === undefined || options.agents === undefined || options.plugins === undefined))
+            throw new InstallerError("invalid_input", "Non-TTY install requires --commands, --agents, and --plugins");
+        const selection = action === "install"
+            ? options.selectionFlag ? installerSelection(options) : await interactiveInstallerSelection()
+            : undefined;
+        requireConfirmationMode(options);
         if (options.dryRun) {
-            const plan = await preview(action, options.scope);
+            const plan = await preview(action, options.scope, process.cwd(), undefined, selection);
             if (options.json)
-                process.stdout.write(`${JSON.stringify({ status: "ok", applied: false, requires_restart: false, plan }, null, 2)}\n`);
+                process.stdout.write(`${JSON.stringify({ status: "ok", applied: false, requires_restart: plan.requires_restart, plan }, null, 2)}\n`);
             else
-                process.stdout.write(renderPlan(plan, { applied: false, confirmationCommand: shellCommand([action, "--scope", options.scope, "--confirm", plan.digest]) }));
+                process.stdout.write(renderPlan(plan, { applied: false, confirmationCommand: shellCommand([action, "--scope", options.scope, ...selectionArguments(plan.selection), "--confirm", plan.digest]) }));
         }
         else {
-            const plan = await apply(action, options.scope, options.confirm);
+            const plan = await apply(action, options.scope, options.confirm, process.cwd(), undefined, {}, selection);
             if (options.json)
                 process.stdout.write(`${JSON.stringify({ status: "ok", applied: true, requires_restart: plan.requires_restart, plan }, null, 2)}\n`);
             else

package/dist/contracts.d.ts

@@ -0,0 +1,52 @@
+import { type ExecutionCard } from "./routing.js";
+export declare const CONTRACT_SCHEMA_VERSION: 1;
+export type AgentReportStatus = "COMPLETED" | "BLOCKED" | "FAILED" | "REJECTED_PLAN" | "APPROVED" | "CHANGES_REQUIRED";
+export type MapperReport = {
+    mapper_report: {
+        schema_version: 1;
+        paths: Array<Record<string, string>>;
+        callers: Array<Record<string, string>>;
+        tests: Array<Record<string, string>>;
+        patterns: Array<Record<string, string>>;
+        evidence_gaps: string[];
+    };
+};
+export type WorkerReport = {
+    worker_report: {
+        schema_version: 1;
+        status: Extract<AgentReportStatus, "COMPLETED" | "BLOCKED" | "FAILED" | "REJECTED_PLAN">;
+        card_id: string | null;
+        revision: number | null;
+        changed_files: string[];
+        checks: Array<{
+            command: string;
+            status: string;
+        }>;
+        writes_performed: boolean;
+        risks: string[];
+    };
+};
+export type ReviewReport = {
+    review_report: {
+        schema_version: 1;
+        status: "APPROVED" | "CHANGES_REQUIRED";
+        target: string;
+        findings: Array<Record<string, unknown>>;
+        evidence: string[];
+        checks: string[];
+        risks: string[];
+    };
+};
+export type CriticReport = {
+    critic_report: {
+        schema_version: 1;
+        status: "APPROVED" | "CHANGES_REQUIRED";
+        card_id: string;
+        revision: number;
+        findings: Array<Record<string, unknown>>;
+        evidence: string[];
+        unrun_checks: string[];
+        risks: string[];
+    };
+};
+export declare function validateAgentReport(agent: string, report: unknown, card?: ExecutionCard): void;

package/dist/contracts.js

@@ -0,0 +1,98 @@
+import { validateExecutionCard } from "./routing.js";
+export const CONTRACT_SCHEMA_VERSION = 1;
+function object(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+export function validateAgentReport(agent, report, card) {
+    if (!object(report))
+        throw new Error("agent report must be an object");
+    const reportKey = agent === "architect" ? "execution_card" : `${agent}_report`;
+    if (Object.keys(report).length !== 1 || !(reportKey in report))
+        throw new Error(`${agent} report has an invalid envelope`);
+    const value = report[reportKey];
+    if (!object(value))
+        throw new Error(`missing ${agent}_report`);
+    if (value.schema_version !== CONTRACT_SCHEMA_VERSION)
+        throw new Error(`${agent} report schema version is unsupported`);
+    if (agent === "mapper") {
+        for (const key of ["paths", "callers", "tests", "patterns"])
+            if (!Array.isArray(value[key]))
+                throw new Error(`mapper report field is invalid: ${key}`);
+        if (Object.keys(value).some((key) => !["schema_version", "paths", "callers", "tests", "patterns", "evidence_gaps"].includes(key)))
+            throw new Error("mapper report contains unknown fields");
+        if (!strings(value.evidence_gaps))
+            throw new Error("mapper report evidence_gaps is invalid");
+    }
+    else if (agent === "architect") {
+        if (value.status === "NEEDS_EVIDENCE")
+            return;
+        const result = validateExecutionCard(value);
+        if (!result.valid)
+            throw new Error(`architect execution card is invalid: ${result.failedField}`);
+    }
+    else if (agent === "worker") {
+        if (!strings(value.changed_files) ||
+            !Array.isArray(value.checks) ||
+            typeof value.writes_performed !== "boolean" ||
+            !strings(value.risks))
+            throw new Error("worker report is invalid");
+        if (Object.keys(value).some((key) => ![
+            "schema_version",
+            "status",
+            "card_id",
+            "revision",
+            "changed_files",
+            "checks",
+            "writes_performed",
+            "risks",
+        ].includes(key)))
+            throw new Error("worker report contains unknown fields");
+        if (value.status === "COMPLETED" &&
+            (value.writes_performed !== true ||
+                value.checks.some((check) => check.status !== "passed")))
+            throw new Error("completed worker report has incomplete checks");
+        if (card && value.changed_files.some((path) => !card.write_set.includes(path)))
+            throw new Error("worker report writes outside execution card");
+    }
+    else if (agent === "review" || agent === "critic") {
+        if (!["APPROVED", "CHANGES_REQUIRED"].includes(String(value.status)) ||
+            !Array.isArray(value.findings) ||
+            (typeof value.target !== "string" && agent === "review"))
+            throw new Error(`${agent} report is invalid`);
+        if (agent === "review" &&
+            (!Array.isArray(value.checks) ||
+                !strings(value.checks) ||
+                !strings(value.risks) ||
+                !strings(value.evidence) ||
+                !value.target))
+            throw new Error("review report fields are invalid");
+        if (agent === "critic" &&
+            (typeof value.card_id !== "string" ||
+                !Number.isInteger(value.revision) ||
+                !strings(value.unrun_checks) ||
+                !strings(value.risks) ||
+                !strings(value.evidence)))
+            throw new Error("critic report fields are invalid");
+        const allowed = agent === "review"
+            ? ["schema_version", "status", "target", "findings", "evidence", "checks", "risks"]
+            : [
+                "schema_version",
+                "status",
+                "card_id",
+                "revision",
+                "findings",
+                "evidence",
+                "unrun_checks",
+                "risks",
+            ];
+        if (Object.keys(value).some((key) => !allowed.includes(key)))
+            throw new Error(`${agent} report contains unknown fields`);
+    }
+    else
+        throw new Error(`unknown report agent: ${agent}`);
+    if (card && (value.card_id !== card.card_id || value.revision !== card.revision))
+        throw new Error("agent report does not match execution card");
+}

package/dist/doctor.d.ts

@@ -0,0 +1,44 @@
+import { type Scope } from "./lifecycle.js";
+export type DoctorCheckStatus = "pass" | "warn" | "fail" | "incomplete";
+export type DoctorCheck = {
+    id: string;
+    status: DoctorCheckStatus;
+    summary: string;
+    evidence: Record<string, string | number | boolean | string[]>;
+    remediation?: string[];
+};
+export type DoctorHost = {
+    config?: () => Promise<unknown>;
+    lsp?: () => Promise<unknown>;
+};
+export type DoctorReport = {
+    schema_version: 1;
+    status: "clean" | "problems" | "incomplete" | "error";
+    mutations: false;
+    scope: Scope;
+    roots: {
+        project: string;
+        deployment: string;
+        lifecycle: string;
+    };
+    versions: {
+        package: string | null;
+        catalog: string;
+        installed_manifest: string | null;
+        opencode: string | null;
+    };
+    checks: DoctorCheck[];
+    counts: Record<DoctorCheckStatus, number>;
+    partial: string[];
+    unavailable: string[];
+    lsp: Record<string, unknown>;
+    retired: Record<string, unknown>;
+    conflicts: Array<Record<string, unknown>>;
+    archive: {
+        path: string;
+        entries: number;
+        valid: boolean;
+    };
+};
+export declare function collectDoctorFacts(scope: Scope, cwd?: string, home?: string, host?: DoctorHost): Promise<DoctorReport>;
+export declare function doctorExitCode(report: DoctorReport): number;