opencode-rules-md 0.8.4 → 0.8.6

package/src/cli/main.ts

@@ -0,0 +1,308 @@
+// ---------------------------------------------------------------------------
+// src/cli/main.ts — `omd` CLI entry point.
+//
+// Command dispatch using node:util.parseArgs.
+// Bare `omd` → install (default).
+// Exit codes: 0 success/no-op, 1 health failure, 2 usage error.
+// ---------------------------------------------------------------------------
+
+import { parseArgs } from 'node:util';
+import { runInstall, type InstallOptions } from './install.js';
+import { runUninstall, type UninstallOptions } from './uninstall.js';
+import { runStatus, runDoctor } from './status.js';
+import { runUpdate } from './update.js';
+import { createRealFs } from './real-fs.js';
+import type { CliFs } from './config.js';
+
+// ─── Usage ───────────────────────────────────────────────────────────────────
+
+const USAGE = `omd — opencode-rules-md plugin manager
+
+Usage:
+  omd [command] [options]
+
+Commands:
+  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/packages/opencode-rules-md* (uninstall only)
+  --yes        Accept all prompts automatically
+
+Examples:
+  omd               # install with defaults (latest)
+  omd install        # same as bare omd
+  omd install --dry-run
+  omd install --version 2.0.0
+  omd uninstall --purge
+`.trim();
+
+const printUsage = (stdout: (s: string) => void): void => {
+  stdout(USAGE);
+};
+
+// ─── Manual argv parsing — extract command before passing to parseArgs ────────
+
+/**
+ * Known option flags (long-form).
+ * We detect unknown flags by scanning argv for anything starting with `-` or `--`
+ * that is NOT in this set.
+ */
+const KNOWN_FLAGS = new Set([
+  '--help', '--dry-run', '--latest', '--purge', '--yes', '--version',
+  '-h', '-V',
+]);
+
+/**
+ * Known short options that take a value.
+ * e.g. `--version 2.0.0` → values.version = '2.0.0'
+ */
+const SHORT_OPTIONS_WITH_VALUE = new Set(['v']);
+
+/**
+ * Known long options that take a value.
+ */
+const LONG_OPTIONS_WITH_VALUE = new Set(['version']);
+
+/**
+ * Extract the command name (first non-option positional) from argv.
+ * Also returns unknown flags found before the command.
+ *
+ * Examples:
+ *   []           → { command: 'install', args: [], unknownFlags: [] }
+ *   ['install']  → { command: 'install', args: [], unknownFlags: [] }
+ *   ['notacommand'] → { command: 'notacommand', args: [], unknownFlags: [] }
+ *   ['install', '--dry-run'] → { command: 'install', args: ['--dry-run'], unknownFlags: [] }
+ *   ['install', '--unknown-opt'] → { command: 'install', args: ['--unknown-opt'], unknownFlags: ['--unknown-opt'] }
+ */
+function extractCommand(
+  argv: string[],
+): { command: string | null; unknownFlags: string[] } {
+  const unknownFlags: string[] = [];
+  let command: string | null = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+
+    if (arg === '--') {
+      // Argument separator — remaining args are positional
+      break;
+    }
+
+    if (!arg.startsWith('-')) {
+      // First non-option is the command
+      if (command === null) {
+        command = arg;
+      }
+      continue;
+    }
+
+    // It's an option — check if known
+    if (!KNOWN_FLAGS.has(arg)) {
+      unknownFlags.push(arg);
+    }
+
+    // Skip the value for options that take one
+    const flagName = arg.startsWith('--')
+      ? arg.slice(2)
+      : arg.startsWith('-')
+        ? arg.slice(1)
+        : '';
+
+    if (
+      LONG_OPTIONS_WITH_VALUE.has(flagName) ||
+      SHORT_OPTIONS_WITH_VALUE.has(flagName)
+    ) {
+      // Skip the next argv element if it's not an option itself
+      if (i + 1 < argv.length && !argv[i + 1]!.startsWith('-')) {
+        i++;
+      }
+    }
+  }
+
+  return { command, unknownFlags };
+}
+
+// ─── Main dispatch ───────────────────────────────────────────────────────────
+
+export interface MainOptions {
+  fs?: CliFs;
+  env?: NodeJS.ProcessEnv;
+  stdout?: (s: string) => void;
+  stderr?: (s: string) => void;
+  /**
+   * Optional injection point for tests: pretend the npm registry returned this
+   * 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 (
+  opts: MainOptions,
+  argv: string[],
+): Promise<number> => {
+  const {
+    fs = createRealFs(),
+    env = process.env,
+    stdout = (s: string) => console.log(s),
+    stderr = (s: string) => console.error(s),
+  } = opts;
+
+  // Intercept --help/-h before anything else
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printUsage(stdout);
+    return 0;
+  }
+
+  // Extract command and detect unknown flags before parseArgs
+  const { command, unknownFlags } = extractCommand(argv);
+
+  if (unknownFlags.length > 0) {
+    stderr(`omd: unknown option ${unknownFlags[0]}`);
+    stderr("Run 'omd --help' for usage.");
+    return 2;
+  }
+
+  // Default to install for bare `omd`
+  const resolvedCommand = command ?? 'install';
+
+  try {
+    switch (resolvedCommand) {
+    case 'install': {
+      // Remaining argv for parseArgs to extract options
+      const remaining = argv.slice(
+        argv.indexOf('install') + 1 || argv.indexOf(resolvedCommand) + 1,
+      );
+      const { values } = parseArgs({
+        args: remaining,
+        allowPositionals: true,
+        strict: false,
+        options: {
+          'dry-run': { type: 'boolean', default: false },
+          version: { type: 'string', default: '' },
+          latest: { type: 'boolean', default: false },
+          yes: { type: 'boolean', default: false },
+        },
+      });
+      const installOpts: InstallOptions = {
+        version: values['latest'] ? 'latest' : String(values['version'] ?? ''),
+        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: install skipped (dry-run) — would run: opencode plugin ${result.specifier} --global`);
+        return 0;
+      }
+      stdout(`omd: installed via opencode plugin ${result.specifier} --global`);
+      return 0;
+    }
+
+    case 'uninstall': {
+      const remaining = argv.slice(argv.indexOf(resolvedCommand) + 1);
+      const { values } = parseArgs({
+        args: remaining,
+        allowPositionals: true,
+        strict: false,
+        options: {
+          'dry-run': { type: 'boolean', default: false },
+          purge: { type: 'boolean', default: false },
+          yes: { type: 'boolean', default: false },
+        },
+      });
+      const uninstallOpts: UninstallOptions = {
+        purge: Boolean(values['purge']),
+        dryRun: Boolean(values['dry-run']),
+        yes: Boolean(values['yes']),
+      };
+      const result = runUninstall(uninstallOpts, fs, env);
+      if (result.status === 'skipped') {
+        stdout('omd: not installed (no changes needed)');
+        return 0;
+      }
+      for (const r of result.results) {
+        if (r.status === 'wrote') {
+          stdout(`omd: removed from ${r.path}`);
+        } else if (r.status === 'skipped') {
+          stdout(`omd: ${r.path} — not present`);
+        }
+      }
+      if (result.purged) {
+        stdout('omd: cache purged');
+      }
+      return 0;
+    }
+
+    case 'status': {
+      await runStatus(fs, env, stdout, opts.latestVersion !== undefined ? { latestVersion: opts.latestVersion } : {});
+      return 0;
+    }
+
+    case 'doctor': {
+      const docResult = await runDoctor(fs, env, stdout, stderr);
+      return docResult.ok ? 0 : 1;
+    }
+
+    case 'update': {
+      const remaining = argv.slice(argv.indexOf(resolvedCommand) + 1);
+      const { values } = parseArgs({
+        args: remaining,
+        allowPositionals: true,
+        strict: false,
+        options: {
+          'dry-run': { type: 'boolean', default: false },
+        },
+      });
+      const dryRun = Boolean(values['dry-run']);
+      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;
+    }
+
+    default:
+      stderr(`omd: unknown command '${resolvedCommand}'`);
+      stderr("Run 'omd --help' for usage.");
+      return 2;
+  }
+  } catch (err) {
+    stderr(`omd: ${(err as Error).message}`);
+    return 1;
+  }
+};
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+// Only run when executed directly (not imported as a module in tests).
+const isMainModule =
+  import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+
+if (isMainModule) {
+  const exitCode = await runMain({}, process.argv.slice(2));
+  process.exit(exitCode);
+}

package/src/cli/real-fs.ts

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// src/cli/real-fs.ts — Default `CliFs` adapter backed by `node:fs`.
+//
+// The CLI commands default to the real filesystem in production. Tests inject
+// an in-memory adapter to keep everything deterministic and fast. All methods
+// are sync — the CLI is short-lived and never benefits from async I/O.
+// ---------------------------------------------------------------------------
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import type { CliFs } from "./config";
+
+export const createRealFs = (): CliFs => ({
+  readFileSync: (path) => readFileSync(path, "utf8"),
+  writeFileSync: (path, content) => {
+    writeFileSync(path, content);
+  },
+  renameSync: (from, to) => {
+    renameSync(from, to);
+  },
+  copyFileSync: (from, to) => {
+    copyFileSync(from, to);
+  },
+  unlinkSync: (path) => {
+    unlinkSync(path);
+  },
+  mkdirSync: (path, opts) => {
+    mkdirSync(path, opts);
+  },
+  readdirSync: (path) => readdirSync(path),
+  existsSync: (path) => existsSync(path),
+  rmdirSync: (path) => {
+    rmdirSync(path);
+  },
+});

package/src/cli/registry.ts

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// src/cli/registry.ts — npm registry helpers for `omd`.
+//
+// Fetches the latest published version of `opencode-rules-md` from the npm
+// registry. Uses the native `fetch()` API (Node 20+) — no extra dependencies.
+// ---------------------------------------------------------------------------
+
+const REGISTRY_URL = "https://registry.npmjs.org/opencode-rules-md/latest";
+
+/**
+ * Fetch the latest version string from the npm registry.
+ * Returns `null` when the registry is unreachable or the response is
+ * malformed — callers treat `null` as "can't determine, don't block".
+ */
+export const fetchLatestVersion = async (): Promise<string | null> => {
+  try {
+    const res = await fetch(REGISTRY_URL);
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Return whether the installed version is older than the latest.
+ * Unknown versions (null on either side) are never treated as stale.
+ */
+export const isStale = (
+  installed: string | null,
+  latest: string | null,
+): boolean => {
+  if (!installed || !latest) return false;
+  return installed !== latest;
+};

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() ?? '',
+  };
+}