Adopt oclif command-plugins; rename plugin→module; preinstall sync

bin/quoin.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 
-import { main } from "../dist/cli.js";
+import { execute } from "@agent-ix/ix-cli-core";
 
-main(process.argv.slice(2)).catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exitCode = 1;
-});
+import { isVersionRequest, packageVersion } from "../dist/cli.js";
+
+const argv = process.argv.slice(2);
+
+// Preserve quoin's bare build-time version output ahead of the oclif runner.
+if (isVersionRequest(argv)) {
+  console.log(packageVersion());
+} else {
+  await execute({ dir: import.meta.url });
+}

package.json

@@ -21,6 +21,26 @@
   "bin": {
     "quoin": "bin/quoin.js"
   },
+  "oclif": {
+    "bin": "quoin",
+    "dirname": "quoin",
+    "commands": "./dist/commands",
+    "plugins": [
+      "@agent-ix/filament-plan-sync"
+    ],
+    "topicSeparator": " ",
+    "topics": {
+      "catalog": {
+        "description": "Inspect the active artifact/object catalog (list, show, validate)."
+      },
+      "module": {
+        "description": "Install and manage user/community spec modules (list, install, remove, ensure-defaults)."
+      },
+      "plugin": {
+        "description": "[DEPRECATED] Renamed to `module`; retained as a forwarding alias."
+      }
+    }
+  },
   "packageManager": "pnpm@10.33.4",
   "scripts": {
     "help": "node scripts/help.js",
@@ -57,8 +77,10 @@
     "test-results:warnings": "./node_modules/.bin/jest-results warnings"
   },
   "dependencies": {
+    "@agent-ix/filament-plan-sync": "file:../filament-plan-sync",
     "@agent-ix/ix-cli-core": ">=0.11.0",
     "@agent-ix/ts-plugin-kit": ">=0.1.3",
+    "@oclif/core": ">=4.11.4",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

src/base.ts

@@ -0,0 +1,57 @@
+import { BaseCommand, maybeOfferUpdate } from "@agent-ix/ix-cli-core";
+
+import { ixHome } from "./catalog.js";
+import { packageVersion } from "./version.js";
+
+/**
+ * Shared base for every quoin command.
+ *
+ * Extends ix-cli-core's {@link BaseCommand} (which owns the `--config-root` /
+ * `--no-project-config` global flags and the capability lifecycle) and adds the
+ * two cross-cutting concerns the legacy hand-rolled dispatcher used to apply to
+ * every invocation:
+ *
+ *  1. Resolve the quoin home (`--config-root` flag, else `IX_HOME`) and export
+ *     it as `process.env.IX_HOME` so the catalog / module modules — which read
+ *     `ixHome()` — observe the per-invocation override exactly as before.
+ *  2. Nudge toward a newer published quoin (throttled, interactive-only, silent
+ *     in CI / under `--json` / for `update` itself). Never blocks or throws.
+ */
+export abstract class QuoinCommand extends BaseCommand {
+  /** Commands that must not trigger the update nudge (e.g. `update`). */
+  protected skipUpdateNudge = false;
+
+  /** Resolved quoin home for this invocation. */
+  protected home = "";
+
+  public override async init(): Promise<void> {
+    await super.init();
+
+    const configRoot =
+      configRootFromArgv(this.argv) ?? process.env.IX_CONFIG_ROOT;
+    this.home =
+      typeof configRoot === "string" && configRoot.length > 0
+        ? configRoot
+        : ixHome();
+    process.env.IX_HOME = this.home;
+
+    if (!this.skipUpdateNudge && !this.argv.includes("--json")) {
+      await maybeOfferUpdate({
+        packageName: "@agent-ix/quoin",
+        currentVersion: packageVersion(),
+      });
+    }
+  }
+}
+
+/** Read the `--config-root <dir>` / `--config-root=<dir>` value from argv. */
+function configRootFromArgv(argv: readonly string[]): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--config-root") return argv[i + 1];
+    if (arg.startsWith("--config-root=")) {
+      return arg.slice("--config-root=".length);
+    }
+  }
+  return undefined;
+}