opencode-rules-md 0.8.5 → 0.9.0

package/src/cli/install.ts

@@ -1,211 +1,103 @@
 // ---------------------------------------------------------------------------
 // src/cli/install.ts — `omd install` command implementation.
 //
-// Dual-config install loop: iterates over ["opencode", "tui"], loads each
-// config, normalizes + deduplicates the plugin list, appends the fresh
-// specifier, and writes atomically with a timestamped backup. When the version
-// is omitted or "latest", the latest published npm version is resolved so the
-// written specifier matches the concrete version (important for accurate
-// update checks) and any stale local cache can be purged.
+// `omd install` is a thin convenience wrapper around OpenCode's own
+// `opencode plugin <specifier> --global` command. OpenCode handles the
+// correct config field name (`plugin`, singular), manifest reading, and
+// cache placement under ~/.cache/opencode/packages/. We no longer edit
+// opencode.json or tui.json directly — duplicating that logic was the
+// source of the original bug (we wrote `plugins` plural, which OpenCode
+// silently ignored).
+//
+// The bare specifier `opencode-rules-md` (no `@latest`) is intentional:
+// it lets OpenCode resolve and refresh the package on every invocation
+// without us pinning to a stale version literal.
 // ---------------------------------------------------------------------------
 
-import { dirname, join } from 'path';
-import {
-  PLUGIN_NAME,
-  loadGlobalConfig,
-  matchesPlugin,
-  normalizePlugin,
-  backupIfWritable,
-  rotateBackups,
-  writeAtomically,
-  type CliFs,
-} from './config.js';
-import { fetchLatestVersion } from './registry.js';
-import { purgeDirectory, resolveCachePath } from './update.js';
+import { spawnOpencodePlugin } from './spawn.js';
+import type { CliFs } from './config.js';
+import { PLUGIN_NAME } from './config.js';
 
-export const CONFIG_BASENAMES = ['opencode', 'tui'] as const;
+/** Default base specifier used when the caller does not pin a version. */
+export const DEFAULT_SPECIFIER = PLUGIN_NAME;
 
 export interface InstallOptions {
+  /** Pin to a specific version, e.g. `"2.0.0"`. Falsy means "use the bare specifier". */
   version?: string;
+  /** Run the full pipeline without spawning the child process. */
   dryRun?: boolean;
+  /** Reserved for future prompts — currently a no-op. */
   yes?: boolean;
+  /** Test hook for resolving the latest version (kept for API compatibility). */
+  latestVersion?: string | undefined;
   /**
-   * Optional injection point for tests: pretend the npm registry returned this
-   * version when the requested version is "latest" or unset. When omitted,
-   * `fetchLatestVersion()` is called against the real npm registry.
+   * Test seam: replaces spawnOpencodePlugin. Defaults to the real CLI wrapper.
+   * Pass an object with a compatible signature to assert on calls.
    */
-  latestVersion?: string | undefined;
-}
-
-export interface InstallResultPerFile {
-  path: string;
-  status: 'wrote' | 'skipped' | 'error';
-  backup: string | null;
+  spawn?: typeof spawnOpencodePlugin;
 }
 
 export interface InstallResult {
+  /** Whether we actually invoked the opencode CLI. */
   status: 'wrote' | 'skipped';
-  results: InstallResultPerFile[];
-  /** True when a stale local cache directory was purged after writing. */
-  purged?: boolean;
+  /** The specifier passed to `opencode plugin`. Useful for logging. */
+  specifier: string;
 }
 
 /**
- * Resolve the concrete version to write.
+ * Build the specifier to pass to `opencode plugin`.
  *
- * - If the user supplied an explicit version (not "latest" and not empty), use
- *   it unchanged.
- * - Otherwise, ask the npm registry for the latest published version.
- * - If the registry is unreachable, fall back to the literal "@latest" tag so
- *   the install command never hard-fails due to network issues. This preserves
- *   the previous behavior while still allowing the cache check to compare when
- *   a concrete version is known.
- */
-async function resolveVersion(opts: InstallOptions): Promise<string> {
-  const raw = opts.version?.trim() ?? '';
-  const wantsLatest = raw === '' || raw === 'latest';
-
-  if (!wantsLatest) {
-    return raw;
-  }
-
-  // Tests can short-circuit the network call via latestVersion.
-  if (opts.latestVersion !== undefined) {
-    return opts.latestVersion;
-  }
-
-  const latest = await fetchLatestVersion();
-  return latest ?? 'latest';
-}
-
-/**
- * Read the version field from a cached package.json, if present.
- * Returns null when the file is missing or unreadable.
+ * Rules:
+ *   - Empty / unset version  → bare `opencode-rules-md` (lets OpenCode refresh).
+ *   - Any other value        → `opencode-rules-md@<version>` (pins the install).
  */
-function readCacheVersion(fs: CliFs, cachePath: string): string | null {
-  const pkgPath = join(cachePath, 'package.json');
-  try {
-    if (!fs.existsSync(pkgPath)) {
-      return null;
-    }
-    const pkg = JSON.parse(fs.readFileSync(pkgPath)) as { version?: unknown };
-    return typeof pkg.version === 'string' ? pkg.version : null;
-  } catch {
-    // A broken cache is treated as "version unknown" so it gets purged.
-    return null;
+export function buildSpecifier(version: string | undefined): string {
+  const trimmed = version?.trim() ?? '';
+  if (!trimmed || trimmed === 'latest') {
+    return DEFAULT_SPECIFIER;
   }
+  return `${PLUGIN_NAME}@${trimmed}`;
 }
 
 /**
- * Purge the local cache directory when it is stale relative to the version we
- * just installed. If the cache version cannot be determined, we err on the
- * side of purging so the next npx invocation fetches a fresh copy.
- */
-function purgeCacheIfStale(
-  fs: CliFs,
-  env: NodeJS.ProcessEnv,
-  resolvedVersion: string,
-): boolean {
-  // The literal "latest" tag is not a comparable version; we only purge when
-  // we have a concrete resolved version to compare against.
-  if (resolvedVersion === 'latest') {
-    return false;
-  }
-
-  const cachePath = resolveCachePath(env);
-  if (!fs.existsSync(cachePath)) {
-    return false;
-  }
-
-  const cacheVersion = readCacheVersion(fs, cachePath);
-  if (cacheVersion === null || cacheVersion !== resolvedVersion) {
-    purgeDirectory(fs, cachePath);
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Install opencode-rules-md into both opencode.json and tui.json configs.
+ * Install opencode-rules-md via OpenCode's own plugin command.
  *
  * Options:
- *   version    — npm version specifier (default: latest from registry)
- *   dryRun     — run full pipeline without writing to disk
- *   yes        — accepted for future prompts, no-op here
- *   latestVersion — test hook for the resolved latest version
+ *   version    — optional npm version pin
+ *   dryRun     — print the would-be command and skip the spawn
+ *   yes        — reserved
+ *
+ * Returns:
+ *   { status: 'skipped', specifier } when dryRun is true
+ *   { status: 'wrote',   specifier } on a clean exit
+ *
+ * Throws on non-zero exit, so the caller (main.ts) can map it to a CLI
+ * failure without us swallowing the error.
  */
 export const runInstall = async (
   opts: InstallOptions = {},
-  fs: CliFs,
-  env: NodeJS.ProcessEnv,
+  // The next two parameters are kept for API compatibility with main.ts.
+  // `omd install` no longer reads or writes the user's config files directly,
+  // so fs/env are no longer consulted here.
+  _fs?: CliFs,
+  env?: NodeJS.ProcessEnv,
 ): Promise<InstallResult> => {
-  const resolvedVersion = await resolveVersion(opts);
-  const freshEntry = `${PLUGIN_NAME}@${resolvedVersion}`;
-  const results: InstallResultPerFile[] = [];
-  let anyProcessed = false;
-
-  for (const basename of CONFIG_BASENAMES) {
-    const loaded = loadGlobalConfig(fs, env, basename);
-    const plugins = normalizePlugin(loaded.data['plugins']);
+  const specifier = buildSpecifier(opts.version);
+  const spawnFn = opts.spawn ?? spawnOpencodePlugin;
+  const targetEnv = env ?? process.env;
 
-    // Find existing entry for this plugin
-    const existingEntry = plugins.find(p => matchesPlugin(p));
-
-    // No-op if the same specifier is already installed
-    if (existingEntry === freshEntry) {
-      results.push({ path: loaded.path, status: 'skipped', backup: null });
-      continue;
-    }
-
-    anyProcessed = true;
-
-    // Build the new plugin list: remove all matching entries, append fresh specifier.
-    // Existing non-matching plugins are preserved in their original order.
-    const withoutStale = plugins.filter(p => !matchesPlugin(p));
-    const newPlugins = [...withoutStale, freshEntry];
-
-    const newData = { ...loaded.data, plugins: newPlugins };
-    const newContent = JSON.stringify(newData, null, 2) + '\n';
-
-    if (opts.dryRun) {
-      results.push({ path: loaded.path, status: 'wrote', backup: null });
-      continue;
-    }
-
-    // Backup the existing file if it exists
-    let backup: string | undefined;
-    if (loaded.exists) {
-      backup = backupIfWritable(fs, loaded.path);
-      if (backup !== undefined) {
-        const dir = dirname(loaded.path);
-        const segs = loaded.path.replace(/\\/g, '/').split('/');
-        const base = segs[segs.length - 1] ?? loaded.path;
-        const dot = base.lastIndexOf('.');
-        const name = dot >= 0 ? base.slice(0, dot) : base;
-        rotateBackups(fs, dir, name, 3);
-      }
-    }
-
-    writeAtomically(fs, loaded.path, newContent);
-    results.push({
-      path: loaded.path,
-      status: 'wrote',
-      backup: backup ?? null,
-    });
+  if (opts.dryRun) {
+    console.log(`omd: would run: opencode plugin ${specifier} --global`);
+    return { status: 'skipped', specifier };
   }
 
-  // After writing the configs, purge a stale local cache so the next run of the
-  // plugin starts from the version we just registered. In dry-run mode we
-  // never touch the filesystem.
-  let purged = false;
-  if (!opts.dryRun) {
-    purged = purgeCacheIfStale(fs, env, resolvedVersion);
+  const result = await spawnFn([specifier, '--global'], { env: targetEnv, stdio: 'inherit' });
+
+  if ((result.status ?? 0) !== 0) {
+    throw new Error(
+      `opencode plugin ${specifier} --global exited with status ${String(result.status)}`,
+    );
   }
 
-  return {
-    status: anyProcessed ? 'wrote' : 'skipped',
-    results,
-    purged,
-  };
-};
+  return { status: 'wrote', specifier };
+};

package/src/cli/main.ts

@@ -22,17 +22,17 @@ Usage:
   omd [command] [options]
 
 Commands:
-  install   Register opencode-rules-md in both opencode.json and tui.json
-  uninstall Remove opencode-rules-md from both configs
-  status    Show installed plugin state for each config
-  doctor    Run health checks for the plugin environment
-  update    Check for new versions and purge stale cache
+  install    Register opencode-rules-md via OpenCode's plugin command
+  uninstall  Remove opencode-rules-md from both configs and cache
+  status     Show installed plugin state for each config
+  doctor     Run health checks for the plugin environment
+  update     Check for new versions and refresh the install via OpenCode
 
 Options:
   --dry-run    Show what would be changed without writing
   --version    Pin to a specific version (install only)
   --latest     Use the latest version (install only)
-  --purge      Also remove ~/.cache/opencode/node_modules/opencode-rules-md (uninstall only)
+  --purge      Also remove ~/.cache/opencode/packages/opencode-rules-md* (uninstall only)
   --yes        Accept all prompts automatically
 
 Examples:
@@ -141,6 +141,11 @@ export interface MainOptions {
    * version when "latest" is requested by install or update.
    */
   latestVersion?: string;
+  /**
+   * Test seam: replace the `spawnOpencodePlugin` function. Lets tests verify
+   * which CLI args the installer would have invoked without touching disk.
+   */
+  spawn?: typeof import('./spawn.js').spawnOpencodePlugin;
 }
 
 export const runMain = async (
@@ -180,12 +185,12 @@ export const runMain = async (
         argv.indexOf('install') + 1 || argv.indexOf(resolvedCommand) + 1,
       );
       const { values } = parseArgs({
-        argv: remaining,
+        args: remaining,
         allowPositionals: true,
         strict: false,
         options: {
           'dry-run': { type: 'boolean', default: false },
-          version: { type: 'string', default: undefined },
+          version: { type: 'string', default: '' },
           latest: { type: 'boolean', default: false },
           yes: { type: 'boolean', default: false },
         },
@@ -195,29 +200,21 @@ export const runMain = async (
         dryRun: Boolean(values['dry-run']),
         yes: Boolean(values['yes']),
         latestVersion: opts.latestVersion,
+        ...(opts.spawn ? { spawn: opts.spawn } : {}),
       };
       const result = await runInstall(installOpts, fs, env);
       if (result.status === 'skipped') {
-        stdout('omd: already installed (no changes needed)');
+        stdout(`omd: install skipped (dry-run) — would run: opencode plugin ${result.specifier} --global`);
         return 0;
       }
-      for (const r of result.results) {
-        if (r.status === 'wrote') {
-          stdout(`omd: registered in ${r.path}`);
-        } else if (r.status === 'skipped') {
-          stdout(`omd: ${r.path} — already up to date`);
-        }
-      }
-      if (result.purged) {
-        stdout('omd: cache purged');
-      }
+      stdout(`omd: installed via opencode plugin ${result.specifier} --global`);
       return 0;
     }
 
     case 'uninstall': {
       const remaining = argv.slice(argv.indexOf(resolvedCommand) + 1);
       const { values } = parseArgs({
-        argv: remaining,
+        args: remaining,
         allowPositionals: true,
         strict: false,
         options: {
@@ -250,7 +247,7 @@ export const runMain = async (
     }
 
     case 'status': {
-      await runStatus(fs, env, stdout);
+      await runStatus(fs, env, stdout, opts.latestVersion !== undefined ? { latestVersion: opts.latestVersion } : {});
       return 0;
     }
 
@@ -262,7 +259,7 @@ export const runMain = async (
     case 'update': {
       const remaining = argv.slice(argv.indexOf(resolvedCommand) + 1);
       const { values } = parseArgs({
-        argv: remaining,
+        args: remaining,
         allowPositionals: true,
         strict: false,
         options: {
@@ -270,9 +267,21 @@ export const runMain = async (
         },
       });
       const dryRun = Boolean(values['dry-run']);
-      const updateResult = await runUpdate(fs, env, stdout, stderr, { dryRun, latestVersion: opts.latestVersion });
-      if (updateResult.status === 'current') {
-        stdout('omd: already at latest version');
+      const updateResult = await runUpdate(fs, env, stdout, stderr, {
+        dryRun,
+        latestVersion: opts.latestVersion,
+        ...(opts.spawn ? { spawn: opts.spawn } : {}),
+      });
+      switch (updateResult.status) {
+        case 'current':
+          stdout('omd: already at latest version');
+          break;
+        case 'unreachable':
+          stderr('omd: could not reach npm registry — try again later');
+          return 1;
+        case 'stale':
+          // runUpdate already logged the purge / reinstall outcome.
+          break;
       }
       return 0;
     }

package/src/cli/spawn.ts

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// src/cli/spawn.ts — thin wrapper around `opencode plugin`.
+//
+// Why a wrapper? Two reasons:
+//   1. OpenCode owns the schema for `data['plugin']` (singular) and the cache
+//      layout under ~/.cache/opencode/packages/. Re-implementing that logic
+//      drift-prone (the bug we are fixing). Delegating to OpenCode's own CLI
+//      keeps us correct by construction.
+//   2. Tests need a deterministic, non-blocking seam. Defaulting to
+//      spawnSync with `stdio: 'inherit'` lets the real CLI talk directly to
+//      the user's terminal; tests inject a stub that returns canned output.
+// ---------------------------------------------------------------------------
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export interface SpawnResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SpawnOptions {
+  env: NodeJS.ProcessEnv;
+  stdio?: 'pipe' | 'inherit';
+}
+
+export type SpawnFn = (command: string, args: string[], options: SpawnOptions) => SpawnResult;
+
+export interface SpawnOpencodePluginOptions {
+  /** Injected spawn function for tests. Defaults to node:child_process.spawnSync. */
+  spawn?: SpawnFn;
+  /** Environment variables passed to the child process. Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
+  /** stdio mode for the child process. 'inherit' forwards output to the parent. */
+  stdio?: 'pipe' | 'inherit';
+}
+
+/**
+ * Run `opencode plugin <args...>` and return the exit status plus captured
+ * stdout/stderr (only populated when `stdio: 'pipe'`).
+ *
+ * The default implementation uses spawnSync so the call blocks until the
+ * child process exits. This keeps `omd install` simple — the user's shell
+ * stays put until registration completes, then returns control with a
+ * non-zero status on failure.
+ */
+export async function spawnOpencodePlugin(
+  args: string[],
+  opts: SpawnOpencodePluginOptions = {},
+): Promise<SpawnResult> {
+  const env = opts.env ?? process.env;
+  const stdio = opts.stdio ?? 'inherit';
+  const spawnFn = opts.spawn ?? defaultSpawn;
+  return spawnFn('opencode', ['plugin', ...args], { env, stdio });
+}
+
+/**
+ * Default spawn implementation backed by node:child_process.spawnSync.
+ *
+ * The require is loaded lazily so test doubles can replace the spawn
+ * function entirely without ever touching node:child_process.
+ */
+function defaultSpawn(command: string, args: string[], options: SpawnOptions): SpawnResult {
+  const cp = require('node:child_process') as typeof import('node:child_process');
+  const result = cp.spawnSync(command, args, {
+    env: options.env,
+    stdio: options.stdio,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout?.toString() ?? '',
+    stderr: result.stderr?.toString() ?? '',
+  };
+}