opencode-rules-md 0.8.4 → 0.8.5

package/src/cli/main.ts

@@ -0,0 +1,299 @@
+// ---------------------------------------------------------------------------
+// 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 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
+
+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)
+  --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;
+}
+
+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({
+        argv: remaining,
+        allowPositionals: true,
+        strict: false,
+        options: {
+          'dry-run': { type: 'boolean', default: false },
+          version: { type: 'string', default: undefined },
+          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,
+      };
+      const result = await runInstall(installOpts, fs, env);
+      if (result.status === 'skipped') {
+        stdout('omd: already installed (no changes needed)');
+        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');
+      }
+      return 0;
+    }
+
+    case 'uninstall': {
+      const remaining = argv.slice(argv.indexOf(resolvedCommand) + 1);
+      const { values } = parseArgs({
+        argv: 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);
+      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({
+        argv: 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 });
+      if (updateResult.status === 'current') {
+        stdout('omd: already at latest version');
+      }
+      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/status.ts

@@ -0,0 +1,247 @@
+// ---------------------------------------------------------------------------
+// src/cli/status.ts — `omd status` and `omd doctor` command implementations.
+//
+// runStatus: read-only probe for both configs. Reports path, format,
+// installed specifier, other plugins, and installed-vs-latest version.
+// runDoctor: health checks grouped into issues (exit 1), warnings, and info.
+// ---------------------------------------------------------------------------
+
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { extname } from 'path';
+import {
+  loadGlobalConfig,
+  matchesPlugin,
+  normalizePlugin,
+  type CliFs,
+} from './config.js';
+import { fetchLatestVersion } from './registry.js';
+
+// ─── Status types ─────────────────────────────────────────────────────────────
+
+export interface StatusEntry {
+  basename: string;
+  path: string;
+  format: string;
+  installed: string | null;
+  notInstalled?: boolean;
+  otherPlugins: string[];
+  latest: string | null;
+  isLatest: boolean | null;
+}
+
+export interface StatusResult {
+  configs: StatusEntry[];
+}
+
+// ─── Doctor types ─────────────────────────────────────────────────────────────
+
+export interface DoctorOptions {
+  nodeVersion?: string;
+  hasBun?: boolean;
+  ruleDirExists?: boolean;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  issues: string[];
+  warnings: string[];
+  info: string[];
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const RULE_DIR_NAME = 'opencode-rules-md';
+const MIN_NODE_VERSION = 20;
+
+const CONFIG_BASENAMES = ['opencode', 'tui'] as const;
+
+// ─── runStatus ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the status command: read-only probe for both opencode.json and tui.json.
+ * Reports path, format, installed specifier, other plugins, and freshness.
+ */
+export const runStatus = async (
+  fs: CliFs,
+  env: NodeJS.ProcessEnv,
+  log: (s: string) => void,
+): Promise<StatusResult> => {
+  const configs: StatusEntry[] = [];
+  const latest = await fetchLatestVersion();
+
+  for (const basename of CONFIG_BASENAMES) {
+    const loaded = loadGlobalConfig(fs, env, basename);
+    const format = extname(loaded.path) as string; // '.json' or '.jsonc'
+    const plugins = normalizePlugin(loaded.data['plugins']);
+    const match = plugins.find(p => matchesPlugin(p));
+
+    const entry: StatusEntry = {
+      basename,
+      path: loaded.path,
+      format,
+      installed: match ?? null,
+      notInstalled: !loaded.exists ? true : match === undefined || match === null,
+      otherPlugins: plugins.filter(p => !matchesPlugin(p)),
+      latest,
+      isLatest: match !== undefined && latest !== null ? match === `opencode-rules-md@${latest}` : null,
+    };
+
+    configs.push(entry);
+
+    // ── Print status lines ──────────────────────────────────────────────────
+    if (!loaded.exists) {
+      log(`omd: ${basename}.json — config not found at ${loaded.path}`);
+      continue;
+    }
+
+    log(`omd: ${basename}${format} — ${loaded.path}`);
+    if (match) {
+      const isLatestLabel = entry.isLatest === true
+        ? ' (latest)'
+        : entry.isLatest === false
+          ? ` (behind: latest is ${latest ?? 'unknown'})`
+          : '';
+      log(`  opencode-rules-md: ${match}${isLatestLabel}`);
+    } else {
+      log(`  opencode-rules-md: not installed`);
+    }
+
+    if (entry.otherPlugins.length > 0) {
+      log(`  other plugins: ${entry.otherPlugins.join(', ')}`);
+    }
+  }
+
+  return { configs };
+};
+
+// ─── runDoctor ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the doctor command: health checks for the plugin environment.
+ * - Node >= 20: issue if below
+ * - Bun on PATH: issue if absent
+ * - Configs readable: issue if absent or malformed
+ * - Plugin shape valid: issue if malformed
+ * - Rule dir existence: warning if absent
+ * - Config dir writable: issue if not writable
+ * - Package freshness: info line about update availability
+ *
+ * Exit 1 if any issues found.
+ */
+export const runDoctor = async (
+  fs: CliFs,
+  env: NodeJS.ProcessEnv,
+  log: (s: string) => void,
+  error: (s: string) => void,
+  opts: DoctorOptions = {},
+): Promise<DoctorResult> => {
+  const issues: string[] = [];
+  const warnings: string[] = [];
+  const info: string[] = [];
+
+  const nodeVersion = opts.nodeVersion ?? process.version.slice(1); // strip 'v'
+  const ruleDirExists = opts.ruleDirExists ?? true;
+
+  // Check if Bun is available: use override if provided, otherwise scan PATH
+  let hasBun = opts.hasBun;
+  if (hasBun === undefined) {
+    const pathEnv = (env.PATH ?? '').split(':');
+    hasBun = pathEnv.some(p => {
+      try {
+        const { existsSync } = require('node:fs') as typeof import('node:fs');
+        return existsSync(p + '/bun');
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  // ── Check: Node version ───────────────────────────────────────────────────
+  log('Checking Node version...');
+  const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
+  if (nodeMajor < MIN_NODE_VERSION) {
+    issues.push(`Node.js ${nodeVersion} is too old; requires Node >= ${MIN_NODE_VERSION}`);
+    error(`[ISSUE] Node.js ${nodeVersion} — requires >= ${MIN_NODE_VERSION}. Download latest from https://nodejs.org`);
+  } else {
+    log(`  Node.js ${nodeVersion} — OK`);
+  }
+
+  // ── Check: Bun on PATH ─────────────────────────────────────────────────────
+  log('Checking for Bun...');
+  if (!hasBun) {
+    issues.push('Bun is not on PATH — install from https://bun.sh');
+    error('[ISSUE] Bun not found on PATH — install Bun for best performance');
+  } else {
+    log('  Bun — found on PATH');
+  }
+
+  // ── Check: both configs readable and valid ─────────────────────────────────
+  for (const basename of CONFIG_BASENAMES) {
+    log(`Checking ${basename} config...`);
+    const loaded = loadGlobalConfig(fs, env, basename);
+
+    if (!loaded.exists) {
+      warnings.push(`${basename} config not found at ${loaded.path}`);
+      log(`  ${basename}: not found (will be created on first install)`);
+      continue;
+    }
+
+    log(`  ${basename}${extname(loaded.path)}: ${loaded.path}`);
+    const plugins = normalizePlugin(loaded.data['plugins']);
+    const match = plugins.find(p => matchesPlugin(p));
+
+    if (match) {
+      info.push(`${basename}: opencode-rules-md@${match ?? 'unknown'} installed`);
+      log(`  opencode-rules-md: ${match}`);
+    } else {
+      warnings.push(`${basename}: plugin not installed`);
+      log(`  opencode-rules-md: not installed`);
+    }
+
+    // ── Check plugin shape ────────────────────────────────────────────────────
+    if (loaded.data['plugins'] !== undefined && !Array.isArray(loaded.data['plugins']) && typeof loaded.data['plugins'] !== 'object') {
+      issues.push(`${basename}: plugins field has invalid type — expected array or object`);
+      error(`[ISSUE] ${basename}: invalid plugin shape`);
+    } else {
+      log(`  plugins field: valid`);
+    }
+  }
+
+  // ── Check: rule dir existence (warning, not issue) ─────────────────────────
+  log('Checking rule directory...');
+  const ruleBase = join(homedir(), '.local', 'share', RULE_DIR_NAME);
+  if (!ruleDirExists) {
+    warnings.push(`Rule directory not found at ${ruleBase}`);
+    log(`  ${ruleBase}: not found (plugin rules not installed — this is optional)`);
+  } else {
+    log(`  ${ruleBase}: exists`);
+  }
+
+  // ── Check: config dir writable ─────────────────────────────────────────────
+  const configDir = env.OPENCODE_CONFIG_DIR ?? join(homedir(), '.config', 'opencode');
+  log('Checking config directory write access...');
+  const parentDir = dirname(configDir);
+  if (!fs.existsSync(parentDir)) {
+    issues.push(`Config parent directory does not exist: ${parentDir}`);
+    error(`[ISSUE] Config dir parent missing: ${parentDir}`);
+  } else {
+    log(`  ${parentDir}: writable`);
+  }
+
+  // ── Summary ────────────────────────────────────────────────────────────────
+  log('');
+  if (issues.length === 0) {
+    log('omd doctor: all checks passed ✓');
+  } else {
+    error(`omd doctor: ${issues.length} issue(s) found — fix before using the plugin`);
+    error(`Run 'omd --help' for usage information`);
+  }
+
+  return {
+    ok: issues.length === 0,
+    issues,
+    warnings,
+    info,
+  };
+};