@opencode-compat/cli 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @opencode-compat/cli
+
+OCP compat doctor, Plugin×Host×Tier matrix runner, Layer A `setup` / `overrides`, and `migrate-zcode` companion CLI.
+
+```text
+compat doctor [--host opencode|mimo|kilo|zcode]
+compat setup [--dir <path>] [--host <id>] [--mode auto|npm|file] [--dry-run]
+             [--deep|--no-deep] [--reify|--no-reify]
+compat overrides
+compat matrix [...]
+compat migrate-zcode --plugin <dir> [--out <dir>] [--dry-run]
+```
+
+`setup` defaults to **deep** child `package.json` patches and **auto-reify** (`npm install`) when a patched tree already has `node_modules` — required on MiMo/Kilo isolated per-plugin install dirs. Re-run after installing or upgrading consumer plugins.
+
+User-facing entry is **`ocp`** from `@opencode-compat/ocp` (defaults to `setup`). This package remains the bridge CLI implementation.
+
+`migrate-zcode` packs **plugin-packaged** skills/commands/manifests into a `.zcode-plugin` tree. It is **not** OCP ABI compatibility (ZCode stays T0) and does **not** migrate host MCP.
+
+**License:** MPL-2.0
+
+See the monorepo [README](../../README.md), [OCP 0.1](../../docs/ocp/0.1.md), and [migrator plan](../../docs/plans/zcode-asset-migrator-plan.md).

package/bin/compat.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/**
+ * Published entry uses dist/ (src/ is not in the npm tarball).
+ * From a checkout: run `bun run build` first, or `bun packages/cli/src/…` via tests.
+ */
+import { mainAsync } from "../dist/index.js"
+
+process.exit(await mainAsync())

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @opencode-compat/cli — `compat doctor` + matrix + setup + migrate-zcode companion.
+ */
+export declare const PKG: "@opencode-compat/cli";
+export declare const VERSION: "0.1.0";
+import { type MigrateMarketplaceReport, type MigrateReport } from "@opencode-compat/migrate-zcode";
+import { type DetectOptions, type HostId } from "@opencode-compat/profile";
+export { parseSetupArgs, setup, type SetupOptions, type SetupResult } from "./setup";
+export type DoctorResult = {
+    ok: boolean;
+    message: string;
+    host?: string;
+    source?: string;
+};
+/** Run OCP compat doctor against the current (or injected) environment. */
+export declare function doctor(options?: DetectOptions): DoctorResult;
+export type MatrixCliOptions = {
+    hosts?: HostId[];
+    fixtureIds?: string[];
+    /** When true, exercise mimo/kilo compatProjectDirs expectations (operator/docs path). */
+    compatScan?: boolean;
+};
+export type MatrixCell = {
+    id: string;
+    tier: string;
+    host: HostId;
+    status: "pass" | "fail" | "skip";
+    message: string;
+    detail?: string;
+};
+type FixturesApi = {
+    runMatrix: (options?: {
+        hosts?: HostId[];
+        fixtureIds?: string[];
+        compatScanEnabled?: boolean | Partial<Record<HostId, boolean>>;
+    }) => Promise<MatrixCell[]>;
+    formatMatrix: (results: MatrixCell[]) => string;
+    matrixOk: (results: MatrixCell[]) => boolean;
+};
+/** Resolve monorepo fixtures (CLI matrix is a checkout-rooted command). */
+export declare function loadFixtures(): Promise<FixturesApi>;
+/** Run Plugin×Host×Tier matrix via fixtures/ (OCP §10). */
+export declare function matrix(options?: MatrixCliOptions): Promise<MatrixCell[]>;
+export declare function runSetupCli(rest: string[]): Promise<number>;
+export type MigrateZcodeCliOptions = {
+    plugins: string[];
+    out?: string;
+    name?: string;
+    version?: string;
+    marketplaceName?: string;
+    marketplaceDescription?: string;
+    ownerName?: string;
+    ownerUrl?: string;
+    dryRun: boolean;
+    allowEmpty: boolean;
+    format: "text" | "json";
+    help: boolean;
+};
+export declare function parseMigrateZcodeArgs(rest: string[]): MigrateZcodeCliOptions;
+/** Exit: 0 ok, 1 error/collision, 2 empty without allowEmpty. */
+export declare function migrateZcodeExitCode(report: MigrateReport | MigrateMarketplaceReport): number;
+export declare function runMigrateZcodeCli(rest: string[]): Promise<number>;
+export declare function mainAsync(argv?: string[]): Promise<number>;
+/** Sync entry for doctor / overrides / setup / help (used by unit tests). */
+export declare function main(argv?: string[]): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,450 @@
+/**
+ * @opencode-compat/cli — `compat doctor` + matrix + setup + migrate-zcode companion.
+ */
+export const PKG = "@opencode-compat/cli";
+export const VERSION = "0.1.0";
+import { doctorReport } from "@opencode-compat/adapter";
+import { migrateZcode, migrateZcodeMarketplace, } from "@opencode-compat/migrate-zcode";
+import { facadeOverrideSnippet, } from "@opencode-compat/profile";
+import { resolve } from "node:path";
+import { parseSetupArgs, setup, } from "./setup";
+export { parseSetupArgs, setup } from "./setup";
+/** Run OCP compat doctor against the current (or injected) environment. */
+export function doctor(options) {
+    const report = doctorReport(options);
+    const { result } = report;
+    if (!result.supported) {
+        return {
+            ok: false,
+            message: result.message ?? report.summary,
+            host: result.id,
+            source: result.source,
+        };
+    }
+    return {
+        ok: true,
+        message: report.summary,
+        host: result.id,
+        source: result.source,
+    };
+}
+/** Resolve monorepo fixtures (CLI matrix is a checkout-rooted command). */
+export async function loadFixtures() {
+    const url = new URL("../../../fixtures/index.ts", import.meta.url);
+    return (await import(url.href));
+}
+/** Run Plugin×Host×Tier matrix via fixtures/ (OCP §10). */
+export async function matrix(options = {}) {
+    const fixtures = await loadFixtures();
+    return fixtures.runMatrix({
+        hosts: options.hosts,
+        fixtureIds: options.fixtureIds,
+        compatScanEnabled: options.compatScan ? true : undefined,
+    });
+}
+function printHelp() {
+    console.log(`opencode-compat — OCP doctor + matrix + setup + companions
+
+Usage:
+  opencode-compat doctor [--host opencode|mimo|kilo|zcode]
+  opencode-compat overrides
+  opencode-compat setup [--dir <path>] [--host <id>] [--mode auto|npm|file] [--dry-run]
+                        [--deep|--no-deep] [--reify|--no-reify] [--provider-shim|--no-provider-shim]
+  opencode-compat matrix [--host <id>]... [--fixture <id>]... [--compat-scan]
+  opencode-compat migrate-zcode --plugin <dir> [--out <dir>] [options]
+  opencode-compat migrate-zcode --plugin <dir> [--plugin <dir>...] \\
+    --marketplace-name <name> --out <dir> [options]
+
+Commands:
+  doctor           Detect host and print capability summary
+  overrides        Print suggested install-time facade override JSON
+  setup            Write Layer A overrides + Option B provider shims into host install tree
+  matrix           Run OCP §10 Plugin×Host×Tier conformance fixtures
+  migrate-zcode    Companion: pack plugin skills/commands/manifests → .zcode-plugin
+                   (not OCP ABI; ZCode stays T0; does not migrate host MCP)
+
+setup options:
+  --dir <path>                   Install tree root (default: host pluginInstallDir)
+  --host opencode|mimo|kilo|...  Force host detection
+  --mode auto|npm|file           Override spec form (auto prefers local file:)
+  --version <ver>                npm: facade version (default 0.1.0)
+  --dry-run                      Print plan only; do not write
+  --deep / --no-deep             Also patch child package.json (default: deep)
+  --reify / --no-reify           npm install after patch when node_modules exists (default: auto)
+  --provider-shim / --no-provider-shim
+                                 In-place create*/languageModel adoption shims after reify (default: on)
+
+migrate-zcode options:
+  --plugin <dir>                 Plugin package root (repeatable; required)
+  --out <dir>                    Output directory (required unless --dry-run)
+  --name <name>                  Override plugin.json name (single-plugin mode)
+  --version <ver>                Override plugin.json version (single-plugin mode)
+  --marketplace-name <name>      Wrap plugin(s) into a multi-plugin marketplace tree
+  --marketplace-description <t>  Catalog description
+  --owner-name <name>            Catalog owner.name
+  --owner-url <url>              Catalog owner.url
+  --dry-run                      Scan/report only; do not write
+  --allow-empty                  Succeed when no marketplace assets found
+  --format text|json             Report format (default: text)
+`);
+}
+const HOST_IDS = new Set(["opencode", "mimo", "kilo", "zcode", "unknown"]);
+function parseArgs(argv) {
+    const [, , command = "doctor", ...rest] = argv;
+    let host;
+    const hosts = [];
+    const fixtures = [];
+    let compatScan = false;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--host") {
+            const value = rest[++i];
+            host = value;
+            if (value && HOST_IDS.has(value))
+                hosts.push(value);
+        }
+        else if (arg?.startsWith("--host=")) {
+            const value = arg.slice("--host=".length);
+            host = value;
+            if (HOST_IDS.has(value))
+                hosts.push(value);
+        }
+        else if (arg === "--fixture") {
+            const value = rest[++i];
+            if (value)
+                fixtures.push(value);
+        }
+        else if (arg?.startsWith("--fixture=")) {
+            fixtures.push(arg.slice("--fixture=".length));
+        }
+        else if (arg === "--compat-scan") {
+            compatScan = true;
+        }
+    }
+    return {
+        command,
+        host,
+        hosts,
+        fixtures,
+        compatScan,
+        migrateRest: rest,
+        setupRest: rest,
+    };
+}
+export async function runSetupCli(rest) {
+    const opts = parseSetupArgs(rest);
+    if (opts.help) {
+        printHelp();
+        return 0;
+    }
+    try {
+        const result = setup({
+            dir: opts.dir,
+            host: opts.host,
+            version: opts.version,
+            mode: opts.mode,
+            dryRun: opts.dryRun,
+            deep: opts.deep,
+            reify: opts.reify,
+        });
+        console.log(result.message);
+        if (opts.dryRun || !result.ok) {
+            console.log(JSON.stringify(result.overrides, null, 2));
+        }
+        for (const t of result.targets.filter((x) => x.changed || x.reified || x.reifyError)) {
+            const mark = t.reifyError ? "!" : t.reified ? "*" : t.created ? "+" : "~";
+            console.log(`  ${mark} ${t.path}`);
+        }
+        return result.ok ? 0 : 1;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`setup failed: ${message}`);
+        return 1;
+    }
+}
+export function parseMigrateZcodeArgs(rest) {
+    const opts = {
+        plugins: [],
+        dryRun: false,
+        allowEmpty: false,
+        format: "text",
+        help: false,
+    };
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--help" || arg === "-h")
+            opts.help = true;
+        else if (arg === "--plugin") {
+            const value = rest[++i];
+            if (value)
+                opts.plugins.push(value);
+        }
+        else if (arg?.startsWith("--plugin=")) {
+            opts.plugins.push(arg.slice("--plugin=".length));
+        }
+        else if (arg === "--out")
+            opts.out = rest[++i];
+        else if (arg?.startsWith("--out="))
+            opts.out = arg.slice("--out=".length);
+        else if (arg === "--name")
+            opts.name = rest[++i];
+        else if (arg?.startsWith("--name="))
+            opts.name = arg.slice("--name=".length);
+        else if (arg === "--version")
+            opts.version = rest[++i];
+        else if (arg?.startsWith("--version=")) {
+            opts.version = arg.slice("--version=".length);
+        }
+        else if (arg === "--marketplace-name")
+            opts.marketplaceName = rest[++i];
+        else if (arg?.startsWith("--marketplace-name=")) {
+            opts.marketplaceName = arg.slice("--marketplace-name=".length);
+        }
+        else if (arg === "--marketplace-description") {
+            opts.marketplaceDescription = rest[++i];
+        }
+        else if (arg?.startsWith("--marketplace-description=")) {
+            opts.marketplaceDescription = arg.slice("--marketplace-description=".length);
+        }
+        else if (arg === "--owner-name")
+            opts.ownerName = rest[++i];
+        else if (arg?.startsWith("--owner-name=")) {
+            opts.ownerName = arg.slice("--owner-name=".length);
+        }
+        else if (arg === "--owner-url")
+            opts.ownerUrl = rest[++i];
+        else if (arg?.startsWith("--owner-url=")) {
+            opts.ownerUrl = arg.slice("--owner-url=".length);
+        }
+        else if (arg === "--dry-run")
+            opts.dryRun = true;
+        else if (arg === "--allow-empty")
+            opts.allowEmpty = true;
+        else if (arg === "--format") {
+            const value = rest[++i];
+            if (value === "json" || value === "text")
+                opts.format = value;
+        }
+        else if (arg?.startsWith("--format=")) {
+            const value = arg.slice("--format=".length);
+            if (value === "json" || value === "text")
+                opts.format = value;
+        }
+    }
+    return opts;
+}
+function formatMigrateText(report) {
+    const lines = [
+        `migrate-zcode: ${report.ok ? "ok" : "failed"}`,
+        `pluginDir: ${report.pluginDir}`,
+        report.outDir ? `outDir: ${report.outDir}` : undefined,
+        `skills: ${report.included.skills.length}`,
+        ...report.included.skills.map((s) => `  + ${s}`),
+        `commands: ${report.included.commands.length}`,
+        ...report.included.commands.map((c) => `  + ${c}`),
+        `manifests: ${report.included.manifests.length}`,
+        ...report.included.manifests.map((m) => `  + ${m}`),
+        `skipped: ${report.skipped.length}`,
+        ...report.skipped.map((s) => `  - ${s.reason} (${s.path})`),
+        `warnings: ${report.warnings.length}`,
+        ...report.warnings.map((w) => `  ! ${w}`),
+        "",
+        "Note: not OCP ABI. ZCode stays T0. Host MCP is not migrated.",
+    ];
+    return lines.filter((l) => l !== undefined).join("\n");
+}
+function formatMarketplaceText(report) {
+    const lines = [
+        `migrate-zcode marketplace: ${report.ok ? "ok" : "failed"}`,
+        `marketplace: ${report.marketplaceName}`,
+        report.outDir ? `outDir: ${report.outDir}` : undefined,
+        `plugins: ${report.plugins.length}`,
+        ...report.plugins.map((p) => `  + ${p.name} (${p.source})`),
+        `pluginDirs: ${report.pluginDirs.length}`,
+        ...report.pluginDirs.map((d) => `  * ${d}`),
+        `skipped: ${report.skipped.length}`,
+        ...report.skipped.map((s) => `  - ${s.reason} (${s.path})`),
+        `warnings: ${report.warnings.length}`,
+        ...report.warnings.map((w) => `  ! ${w}`),
+        "",
+        "Note: not OCP ABI. ZCode stays T0. Host MCP is not migrated.",
+    ];
+    return lines.filter((l) => l !== undefined).join("\n");
+}
+/** Exit: 0 ok, 1 error/collision, 2 empty without allowEmpty. */
+export function migrateZcodeExitCode(report) {
+    if (report.ok)
+        return 0;
+    if (report.warnings.some((w) => w.startsWith("empty-migration:") || w.startsWith("empty-marketplace:"))) {
+        return 2;
+    }
+    return 1;
+}
+export async function runMigrateZcodeCli(rest) {
+    const opts = parseMigrateZcodeArgs(rest);
+    if (opts.help) {
+        printHelp();
+        return 0;
+    }
+    if (opts.plugins.length === 0) {
+        console.error("migrate-zcode: --plugin <dir> is required");
+        printHelp();
+        return 1;
+    }
+    if (!opts.dryRun && !opts.out?.trim()) {
+        console.error("migrate-zcode: --out <dir> is required unless --dry-run");
+        return 1;
+    }
+    const marketplaceMode = Boolean(opts.marketplaceName?.trim()) || opts.plugins.length > 1;
+    if (opts.plugins.length > 1 && !opts.marketplaceName?.trim()) {
+        console.error("migrate-zcode: multiple --plugin values require --marketplace-name");
+        return 1;
+    }
+    try {
+        if (marketplaceMode) {
+            const result = await migrateZcodeMarketplace({
+                pluginDirs: opts.plugins.map((p) => resolve(p)),
+                outDir: opts.out ? resolve(opts.out) : undefined,
+                marketplaceName: opts.marketplaceName.trim(),
+                marketplaceDescription: opts.marketplaceDescription,
+                ownerName: opts.ownerName,
+                ownerUrl: opts.ownerUrl,
+                dryRun: opts.dryRun || !opts.out,
+                allowEmpty: opts.allowEmpty,
+            });
+            if (opts.format === "json") {
+                console.log(JSON.stringify(result.report, null, 2));
+            }
+            else {
+                console.log(formatMarketplaceText(result.report));
+            }
+            return migrateZcodeExitCode(result.report);
+        }
+        const result = await migrateZcode({
+            pluginDir: resolve(opts.plugins[0]),
+            outDir: opts.out ? resolve(opts.out) : undefined,
+            name: opts.name,
+            version: opts.version,
+            dryRun: opts.dryRun || !opts.out,
+            allowEmpty: opts.allowEmpty,
+        });
+        if (opts.format === "json") {
+            console.log(JSON.stringify(result.report, null, 2));
+        }
+        else {
+            console.log(formatMigrateText(result.report));
+        }
+        return migrateZcodeExitCode(result.report);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`migrate-zcode failed: ${message}`);
+        return 1;
+    }
+}
+export async function mainAsync(argv = process.argv) {
+    const { command, host, hosts, fixtures, compatScan, migrateRest, setupRest } = parseArgs(argv);
+    if (command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+    if (command === "overrides") {
+        console.log(facadeOverrideSnippet());
+        return 0;
+    }
+    if (command === "setup") {
+        return runSetupCli(setupRest);
+    }
+    if (command === "migrate-zcode") {
+        return runMigrateZcodeCli(migrateRest);
+    }
+    if (command === "matrix") {
+        try {
+            const mod = await loadFixtures();
+            const results = await mod.runMatrix({
+                hosts: hosts.length > 0 ? hosts : undefined,
+                fixtureIds: fixtures.length > 0 ? fixtures : undefined,
+                compatScanEnabled: compatScan ? true : undefined,
+            });
+            console.log(mod.formatMatrix(results));
+            return mod.matrixOk(results) ? 0 : 1;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`matrix failed: ${message}`);
+            console.error("(matrix expects a monorepo checkout with fixtures/ next to packages/)");
+            return 1;
+        }
+    }
+    if (command !== "doctor") {
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        return 1;
+    }
+    const env = host
+        ? { ...process.env, OPENCODE_COMPAT_HOST: host }
+        : process.env;
+    const result = doctor({ env });
+    console.log(result.message);
+    if (result.host) {
+        console.log(`\n(exit: ${result.ok ? "ok" : "unsupported"} host=${result.host} source=${result.source})`);
+    }
+    return result.ok ? 0 : 1;
+}
+/** Sync entry for doctor / overrides / setup / help (used by unit tests). */
+export function main(argv = process.argv) {
+    const { command, host, setupRest } = parseArgs(argv);
+    if (command === "matrix" || command === "migrate-zcode") {
+        console.error(`${command} requires async entry — use: opencode-compat ${command}`);
+        return 1;
+    }
+    if (command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+    if (command === "overrides") {
+        console.log(facadeOverrideSnippet());
+        return 0;
+    }
+    if (command === "setup") {
+        // setup is sync; expose via main for tests / thin wrappers
+        const opts = parseSetupArgs(setupRest);
+        if (opts.help) {
+            printHelp();
+            return 0;
+        }
+        try {
+            const result = setup({
+                dir: opts.dir,
+                host: opts.host,
+                version: opts.version,
+                mode: opts.mode,
+                dryRun: opts.dryRun,
+                deep: opts.deep,
+            });
+            console.log(result.message);
+            return result.ok ? 0 : 1;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`setup failed: ${message}`);
+            return 1;
+        }
+    }
+    if (command !== "doctor") {
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        return 1;
+    }
+    const env = host
+        ? { ...process.env, OPENCODE_COMPAT_HOST: host }
+        : process.env;
+    const result = doctor({ env });
+    console.log(result.message);
+    if (result.host) {
+        console.log(`\n(exit: ${result.ok ? "ok" : "unsupported"} host=${result.host} source=${result.source})`);
+    }
+    return result.ok ? 0 : 1;
+}
+//# sourceMappingURL=index.js.map

package/dist/provider-shim.d.ts

@@ -0,0 +1,39 @@
+export type ProviderShimOptions = {
+    /** Host plugin install root (e.g. ~/.cache/mimocode/packages). */
+    dir: string;
+    /** Optional host id hint recorded in meta / used for messaging. */
+    hostHint?: string;
+    dryRun?: boolean;
+};
+export type ProviderShimTarget = {
+    packageDir: string;
+    packageName?: string;
+    entry: string;
+    original: string;
+    changed: boolean;
+    skipped?: string;
+};
+export type ProviderShimResult = {
+    ok: boolean;
+    targets: ProviderShimTarget[];
+    message: string;
+};
+type PackageJson = {
+    name?: string;
+    main?: string;
+    module?: string;
+    exports?: unknown;
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    [key: string]: unknown;
+};
+/** Resolve package root entry relative path (POSIX, leading `./`). */
+export declare function resolvePackageEntryRel(pkg: PackageJson): string | undefined;
+/** Static scan for `export … create*` / named exports (sync; no module eval). */
+export declare function discoverExportNames(source: string): string[];
+/** Discover provider package directories under a host install tree. */
+export declare function discoverProviderPackageDirs(installRoot: string): string[];
+/** Apply Option B shims under a host plugin install tree. */
+export declare function setupProviderShims(options: ProviderShimOptions): ProviderShimResult;
+export {};
+//# sourceMappingURL=provider-shim.d.ts.map