opencode-rules-md 0.8.3 → 0.8.5

package/src/cli/config.ts

@@ -0,0 +1,461 @@
+/**
+ * src/cli/config.ts
+ *
+ * Config helpers for the omd CLI installer.
+ * Exports: parseJsonc, resolveConfigPath, normalizePlugin, matchesPlugin,
+ * dedupePlugins, buildSpecifier, backupIfWritable, rotateBackups,
+ * writeAtomically, loadGlobalConfig.
+ *
+ * Constants:
+ *   PLUGIN_NAME            = "opencode-rules-md"
+ *   BACKUP_LIMIT           = 3
+ *   OPENCODE_CONFIG_SUBDIR = "opencode"
+ */
+
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const PLUGIN_NAME = 'opencode-rules-md' as const;
+export const BACKUP_LIMIT = 3;
+export const OPENCODE_CONFIG_SUBDIR = 'opencode';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CliFs interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CliFs {
+  readFileSync(path: string): string;
+  writeFileSync(path: string, content: string): void;
+  renameSync(from: string, to: string): void;
+  copyFileSync(from: string, to: string): void;
+  unlinkSync(path: string): void;
+  mkdirSync(path: string, opts?: { recursive?: boolean }): void;
+  readdirSync(path: string): string[];
+  existsSync(path: string): boolean;
+  rmdirSync(path: string): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// parseJsonc
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse JSONC (JSON with Comments) content.
+ * Strips single-line and multi-line comments and trailing commas.
+ * Returns an empty object for empty/whitespace-only input.
+ * Throws if the stripped content is not valid JSON.
+ */
+export function parseJsonc(content: string): Record<string, unknown> {
+  if (content.trim() === '') {
+    return {};
+  }
+
+  // String-aware comment stripping with bracket-depth tracking.
+  let out = '';
+  let i = 0;
+  // Bracket depth outside strings: +1 for {, -1 for }, +1 for [, -1 for ].
+  let depth = 0;
+
+  while (i < content.length) {
+    const ch = content[i]!;
+
+    // Start of // comment — strip until newline or end-of-string.
+    if (ch === '/' && content[i + 1] === '/' && !isInsideString(out)) {
+      let j = i + 2;
+      while (j < content.length && content[j] !== '\n') {
+        j++;
+      }
+      out += ' '; // replace the comment with a single space
+      // If we stopped at a newline (not EOF): skip the newline — it is the
+      // comment terminator, not JSON content. Set i to j so the outer loop
+      // increments past the newline without adding it.
+      if (j < content.length && content[j] === '\n') {
+        i = j; // outer i++ lands on j (the newline), then increments to j+1
+        continue;
+      }
+      // EOF (j >= content.length): the comment runs to end of file.
+      // Preserve a trailing } or ] at EOF as it is likely the JSON closer.
+      if (j >= content.length) {
+        const last = content[content.length - 1]!;
+        if (last === '}' || last === ']') {
+          out += last;
+        }
+        i = j;
+      } else {
+        i = j - 1; // outer i++ will land on j (EOF terminator position)
+      }
+      continue;
+    }
+
+    // Start of /* */ comment — strip the whole span
+    if (ch === '/' && content[i + 1] === '*' && !isInsideString(out)) {
+      let j = i + 2;
+      while (j < content.length - 1) {
+        if (content[j] === '*' && content[j + 1] === '/') {
+          j += 2;
+          break;
+        }
+        j++;
+      }
+      out += ' ';
+      i = j;
+      continue;
+    }
+
+    // Track bracket depth (outside strings)
+    if (!isInsideString(out)) {
+      if (ch === '{') depth++;
+      else if (ch === '}') depth = Math.max(0, depth - 1);
+      else if (ch === '[') depth++;
+      else if (ch === ']') depth = Math.max(0, depth - 1);
+    }
+
+    out += ch;
+    i++;
+  }
+
+  // Phase 2a: strip trailing commas before ] or }
+  let s = out.replace(/,(\s*[}\]])/g, '$1');
+
+  // Phase 2b: if at root level (depth > 0 means a } was consumed as comment text
+  // at EOF) and s has no closing } or ], add it and strip any trailing comma.
+  if (depth > 0 && !/[}\]]/.test(s)) {
+    s = s.replace(/,(\s*$)/, '') + '}';
+    depth = 0; // we repaired it
+  }
+
+  if (s.trim() === '') {
+    return {};
+  }
+
+  try {
+    return JSON.parse(s) as Record<string, unknown>;
+  } catch (err) {
+    const msg = (err as Error).message;
+    throw new Error('parseJsonc: invalid JSON after stripping comments - ' + msg);
+  }
+}
+
+/** True if the number of unescaped double or single quotes in `s` is odd. */
+function isInsideString(s: string): boolean {
+  let inStr = false;
+  let strChar = '';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]!;
+    if (!inStr && (ch === '"' || ch === "'")) {
+      inStr = true;
+      strChar = ch;
+    } else if (inStr && ch === '\\') {
+      i++; // skip escaped char
+    } else if (inStr && ch === strChar) {
+      inStr = false;
+      strChar = '';
+    }
+  }
+  return inStr;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// resolveConfigDir / resolveConfigPath
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolveConfigDir(env: NodeJS.ProcessEnv): string {
+  const custom = env.OPENCODE_CONFIG_DIR;
+  if (custom && custom.trim() !== '') {
+    return custom;
+  }
+
+  // Honor the XDG Base Directory Specification when it is set.
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg && xdg.trim() !== '') {
+    return join(xdg, OPENCODE_CONFIG_SUBDIR);
+  }
+
+  // Fall back to $HOME/.config/opencode before using os.homedir().
+  // This keeps tests that control HOME deterministic and avoids loading the
+  // wrong global config when the process environment is customized.
+  const home = env.HOME;
+  if (home && home.trim() !== '') {
+    return join(home, '.config', OPENCODE_CONFIG_SUBDIR);
+  }
+
+  return join(homedir(), '.config', OPENCODE_CONFIG_SUBDIR);
+}
+
+/**
+ * Resolve the config path for a given basename.
+ * Prefers .json over .jsonc; returns { path, exists }.
+ * The path does NOT need to exist — absent configs are valid for first install.
+ */
+export function resolveConfigPath(
+  fs: CliFs,
+  env: NodeJS.ProcessEnv,
+  basename: string = 'opencode',
+): { path: string; exists: boolean } {
+  const dir = resolveConfigDir(env);
+  const jsonPath = join(dir, basename + '.json');
+  const jsoncPath = join(dir, basename + '.jsonc');
+
+  if (fs.existsSync(jsonPath)) {
+    return { path: jsonPath, exists: true };
+  }
+  if (fs.existsSync(jsoncPath)) {
+    return { path: jsoncPath, exists: true };
+  }
+
+  return { path: jsonPath, exists: false };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// normalizePlugin
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a plugin value (undefined, null, string[], or legacy object)
+ * to a flat string[].
+ */
+export function normalizePlugin(raw: unknown): string[] {
+  if (raw == null) {
+    return [];
+  }
+
+  if (Array.isArray(raw)) {
+    return raw.filter((v): v is string => typeof v === 'string');
+  }
+
+  if (typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>;
+    return Object.keys(obj).filter(k => obj[k] != null && obj[k] !== false);
+  }
+
+  if (typeof raw === 'string') {
+    return [raw];
+  }
+
+  return [];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// matchesPlugin
+// ─────────────────────────────────────────────────────────────────────────────
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Returns true if entry is the plugin named name (with optional @version).
+ */
+export function matchesPlugin(entry: string, name: string = PLUGIN_NAME): boolean {
+  if (!entry || typeof entry !== 'string') return false;
+  if (entry === name) return true;
+  const pattern = new RegExp('^' + escapeRegex(name) + '@');
+  return pattern.test(entry);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// dedupePlugins
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Deduplicate plugin list: remove all entries matching PLUGIN_NAME,
+ * then re-append the freshest entry (last occurrence). Other plugins preserved.
+ */
+export function dedupePlugins(
+  plugins: string[],
+  name: string = PLUGIN_NAME,
+): string[] {
+  const others: string[] = [];
+  let lastFresh: string | undefined;
+
+  for (const p of plugins) {
+    if (matchesPlugin(p, name)) {
+      lastFresh = p;
+    } else {
+      others.push(p);
+    }
+  }
+
+  const result = [...others];
+  if (lastFresh !== undefined) {
+    result.push(lastFresh);
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// buildSpecifier
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an npm version specifier.
+ * '' | undefined -> '@latest'; explicit -> '@<version>'
+ */
+export function buildSpecifier(version?: string): string {
+  if (!version || version.trim() === '') {
+    return '@latest';
+  }
+  return '@' + version;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// loadGlobalConfig
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GlobalConfig {
+  path: string;
+  exists: boolean;
+  data: Record<string, unknown>;
+}
+
+/**
+ * Load and parse a global config file.
+ * Returns { path, exists, data }. data is {} when file absent or empty.
+ * Throws if the file exists but contains malformed JSON.
+ */
+export function loadGlobalConfig(
+  fs: CliFs,
+  env: NodeJS.ProcessEnv,
+  basename: string = 'opencode',
+): GlobalConfig {
+  const resolved = resolveConfigPath(fs, env, basename);
+
+  if (!resolved.exists) {
+    return { path: resolved.path, exists: false, data: {} };
+  }
+
+  const raw = fs.readFileSync(resolved.path);
+  try {
+    const data = parseJsonc(raw);
+    return { path: resolved.path, exists: true, data };
+  } catch (err) {
+    throw new Error(
+      `config file at ${resolved.path} is malformed JSON\n` +
+      `Fix the JSON error, or delete the file and re-run.\n` +
+      `  error: ${(err as Error).message}`,
+    );
+  }}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Backup helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function timestamp(): string {
+  const now = new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(now.getUTCDate()).padStart(2, '0');
+  const hh = String(now.getUTCHours()).padStart(2, '0');
+  const mm = String(now.getUTCMinutes()).padStart(2, '0');
+  const ss = String(now.getUTCSeconds()).padStart(2, '0');
+  return '' + y + m + d + 'T' + hh + mm + ss;
+}
+
+/**
+ * Create a timestamped backup of path if it exists.
+ * Returns the backup path, or undefined if no backup was created.
+ */
+export function backupIfWritable(fs: CliFs, path: string): string | undefined {
+  if (!fs.existsSync(path)) {
+    return undefined;
+  }
+
+  try {
+    const content = fs.readFileSync(path);
+    const dir = dirname(path);
+    const segs = path.replace(/\\/g, '/').split('/');
+    const base = segs[segs.length - 1] ?? path;
+    const dot = base.lastIndexOf('.');
+    const name = dot >= 0 ? base.slice(0, dot) : base;
+    const backupPath = join(dir, name + '.bak.' + timestamp());
+    fs.writeFileSync(backupPath, content);
+    return backupPath;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Rotate backups: keep at most `limit` backups matching `basename.bak.*`,
+ * deleting the oldest (by timestamp sort) when over limit.
+ */
+export function rotateBackups(
+  fs: CliFs,
+  dir: string,
+  basename: string,
+  limit: number = BACKUP_LIMIT,
+): void {
+  let entries: string[] = [];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+
+  const prefix = basename + '.bak.';
+  const backups = entries
+    .filter(e => e.startsWith(prefix))
+    .map(e => ({ name: e, path: join(dir, e) }))
+    .filter(({ path }) => fs.existsSync(path))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  if (backups.length <= limit) {
+    return;
+  }
+
+  const toDelete = backups.slice(0, backups.length - limit);
+  for (const { path } of toDelete) {
+    try {
+      fs.unlinkSync(path);
+    } catch {
+      // best-effort
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// writeAtomically
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Write content to path atomically:
+ * 1. Write to a sibling .tmp.<name> file
+ * 2. renameSync over the target
+ * 3. Clean up temp file on error
+ */
+export function writeAtomically(fs: CliFs, path: string, content: string): void {
+  const dir = dirname(path);
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    // may already exist
+  }
+
+  const segs = path.replace(/\\/g, '/').split('/');
+  const base = segs[segs.length - 1] ?? path;
+  const dot = base.lastIndexOf('.');
+  const name = dot >= 0 ? base.slice(0, dot) : base;
+  const ext = dot >= 0 ? base.slice(dot) : '';
+  const tmpPath = join(dir, '.tmp.' + name + ext);
+
+  let tempCreated = false;
+  try {
+    fs.writeFileSync(tmpPath, content);
+    tempCreated = true;
+    fs.renameSync(tmpPath, path);
+  } catch (err) {
+    if (tempCreated) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // ignore cleanup failure
+      }
+    }
+    throw err;
+  }
+}

package/src/cli/install.ts

@@ -0,0 +1,211 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+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';
+
+export const CONFIG_BASENAMES = ['opencode', 'tui'] as const;
+
+export interface InstallOptions {
+  version?: string;
+  dryRun?: boolean;
+  yes?: boolean;
+  /**
+   * 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.
+   */
+  latestVersion?: string | undefined;
+}
+
+export interface InstallResultPerFile {
+  path: string;
+  status: 'wrote' | 'skipped' | 'error';
+  backup: string | null;
+}
+
+export interface InstallResult {
+  status: 'wrote' | 'skipped';
+  results: InstallResultPerFile[];
+  /** True when a stale local cache directory was purged after writing. */
+  purged?: boolean;
+}
+
+/**
+ * Resolve the concrete version to write.
+ *
+ * - 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.
+ */
+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;
+  }
+}
+
+/**
+ * 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.
+ *
+ * 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
+ */
+export const runInstall = async (
+  opts: InstallOptions = {},
+  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']);
+
+    // 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,
+    });
+  }
+
+  // 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);
+  }
+
+  return {
+    status: anyProcessed ? 'wrote' : 'skipped',
+    results,
+    purged,
+  };
+};