opencode-agent-skills-md 1.0.0

package/packages/opencode-agent-skills-md/src/cli/main.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// src/cli/main.ts — `oas` CLI entry point.
+//
+// Parses argv with `node:util.parseArgs` and dispatches to install,
+// uninstall, status, or doctor. Exit codes follow the standard CLI
+// convention used elsewhere in this repo:
+//
+//   0 — success (including idempotent no-ops)
+//   1 — operational / health failure
+//   2 — invalid usage (unknown command, missing required arg, etc.)
+//
+// When the file is built (rolldown, PR 2), the shebang stays in place via
+// the banner plugin so `dist/cli.mjs` is directly executable as `oas`.
+// During dev, `pnpm tsx src/cli/main.ts ...` works the same way.
+// ---------------------------------------------------------------------------
+
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { runInstall } from "./install";
+import { runDoctor, runStatus } from "./status";
+import { runUninstall } from "./uninstall";
+
+const USAGE = `Usage: oas <command> [options]
+
+Commands:
+  install     Register the plugin in the global OpenCode config
+  uninstall   Remove the plugin from the global OpenCode config
+  status      Show current installation status
+  doctor      Run health checks against the global config
+
+Options (install):
+  -v, --version <v>  Install a specific version (default: latest)
+      --latest       Alias for --version latest
+      --dry-run      Print the planned change without writing
+      --yes          Skip confirmation prompts (reserved)
+
+Options (uninstall):
+      --purge        Also remove cache + ~/.config/opencode-agent-skills-md/
+      --dry-run      Print the planned change without writing
+      --yes          Skip confirmation prompts (reserved)
+
+Options (all):
+  -h, --help         Show this help and exit
+`;
+
+const printUsage = (): void => {
+  console.log(USAGE);
+};
+
+const setExit = (code: 0 | 1 | 2): void => {
+  process.exitCode = code;
+};
+
+interface ParsedArgs {
+  values: Record<string, string | boolean | undefined>;
+  positionals: string[];
+}
+
+const parseCliArgs = (argv: readonly string[]): ParsedArgs => {
+  // parseArgs with `strict: true` (the default) rejects unknown options
+  // with a clean error message — we surface that as exit code 2.
+  const parsed = parseArgs({
+    args: argv as string[],
+    allowPositionals: true,
+    strict: true,
+    options: {
+      version: { type: "string", short: "v" },
+      latest: { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
+      "dry-run": { type: "boolean" },
+      purge: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  return {
+    values: parsed.values as Record<string, string | boolean | undefined>,
+    positionals: parsed.positionals,
+  };
+};
+
+/**
+ * Strip Node + script argv entries when the entry point is invoked via
+ * the shell (shebang) or via `node ./dist/cli.mjs`. When called from a
+ * test harness with synthetic args, no stripping happens.
+ */
+const sliceProcessArgv = (argv: readonly string[]): readonly string[] => {
+  if (argv.length < 2) return argv;
+  const first = argv[0] ?? "";
+  if (first === process.argv[0] || first.endsWith("node") || first.endsWith("node.exe")) {
+    return argv.slice(2);
+  }
+  return argv;
+};
+
+export interface MainResult {
+  command: string | null;
+  exitCode: 0 | 1 | 2;
+}
+
+/**
+ * Pure(ish) dispatcher: takes argv, runs the matching command, sets
+ * `process.exitCode`, and returns a structured result so tests can assert
+ * without reading the exit code.
+ */
+export const runMain = (argv: readonly string[] = process.argv): MainResult => {
+  const args = sliceProcessArgv(argv);
+
+  // Short-circuit `--help` / `-h` before `parseArgs` so the user can ask
+  // for help without supplying a command.
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    printUsage();
+    return { command: "help", exitCode: 0 };
+  }
+
+  let parsed: ParsedArgs;
+  try {
+    parsed = parseCliArgs(args);
+  } catch (err) {
+    console.error(`oas: ${(err as Error).message}`);
+    setExit(2);
+    return { command: null, exitCode: 2 };
+  }
+
+  if (parsed.values.help) {
+    printUsage();
+    return { command: "help", exitCode: 0 };
+  }
+
+  const command = parsed.positionals[0];
+
+  if (!command) {
+    console.error("oas: missing command. Run `oas --help` for usage.");
+    setExit(2);
+    return { command: null, exitCode: 2 };
+  }
+
+  try {
+    switch (command) {
+      case "install": {
+        const versionRaw = parsed.values.version;
+        const version =
+          parsed.values.latest === true
+            ? "latest"
+            : typeof versionRaw === "string"
+              ? versionRaw
+              : undefined;
+        runInstall({
+          version,
+          dryRun: parsed.values["dry-run"] === true,
+          yes: parsed.values.yes === true,
+        });
+        return { command, exitCode: 0 };
+      }
+      case "uninstall": {
+        runUninstall({
+          purge: parsed.values.purge === true,
+          dryRun: parsed.values["dry-run"] === true,
+          yes: parsed.values.yes === true,
+        });
+        return { command, exitCode: 0 };
+      }
+      case "status": {
+        runStatus();
+        return { command, exitCode: 0 };
+      }
+      case "doctor": {
+        const result = runDoctor();
+        if (!result.ok) setExit(1);
+        return { command, exitCode: result.ok ? 0 : 1 };
+      }
+      default:
+        console.error(`oas: unknown command '${command}'. Run \`oas --help\` for usage.`);
+        setExit(2);
+        return { command: null, exitCode: 2 };
+    }
+  } catch (err) {
+    console.error(`oas: ${(err as Error).message}`);
+    setExit(1);
+    return { command, exitCode: 1 };
+  }
+};
+
+/**
+ * `true` when the file is the program's entry point (shebang / `node
+ * cli.mjs`), `false` when it was imported from a test harness. We avoid
+ * `import.meta.main` because the package floor is Node 18 and that field
+ * only landed in Node 22.
+ */
+const invokedAsMain = ((): boolean => {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedAsMain) {
+  runMain(process.argv);
+}

package/packages/opencode-agent-skills-md/src/cli/real-fs.ts

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// src/cli/real-fs.ts — Default `CliFs` adapter backed by `node:fs`.
+//
+// The CLI commands (`install`, `uninstall`, `status`, `doctor`) default to
+// the real filesystem in production. Tests inject an in-memory adapter via
+// the second argument to keep everything deterministic and fast.
+//
+// The mapping is intentionally thin: only the methods `CliFs` exposes are
+// bound, and `readFileSync` returns a UTF-8 string (the only shape the CLI
+// helpers consume). Anything that does not belong on the `CliFs` interface
+// — for example, recursive directory removal in the uninstall purge path —
+// uses `node:fs` directly at the call site instead of widening the
+// abstraction.
+// ---------------------------------------------------------------------------
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import type { CliFs } from "./config";
+
+/**
+ * Build a `CliFs` that delegates to `node:fs`. All methods are sync; the
+ * CLI is short-lived and never benefits from async I/O.
+ */
+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),
+});

package/packages/opencode-agent-skills-md/src/cli/status.ts

@@ -0,0 +1,183 @@
+// ---------------------------------------------------------------------------
+// src/cli/status.ts — `oas status` and `oas doctor` commands.
+//
+// `status` reports whether the plugin is installed (and at what version)
+// in the global OpenCode config — it's a read-only, idempotent probe
+// suitable for scripting.
+//
+// `doctor` runs a small battery of health checks: Node version, config
+// file readability, plugin-array shape, and config-directory writability.
+// Issues are reported grouped by severity; the caller (main.ts) decides
+// whether the exit code reflects health.
+//
+// `doctor`'s writability probe touches the real filesystem directly via
+// `node:fs` because `CliFs` deliberately does not expose access checks —
+// the probe is best-effort and an injected in-memory fs should not pretend
+// to model POSIX permissions.
+// ---------------------------------------------------------------------------
+
+import { accessSync, constants as fsConstants, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { type CliFs, loadGlobalConfig, matchesPlugin, normalizePlugin, PLUGIN_NAME } from "./config";
+import { createRealFs } from "./real-fs";
+
+export interface StatusResult {
+  /** Whether an `opencode-agent-skills-md` entry is present in `plugin`. */
+  installed: boolean;
+  /** Resolved config path the loader used. */
+  path: string;
+  /** Detected on-disk format. */
+  format: "json" | "jsonc";
+  /** The active specifier, or `null` when not installed. */
+  specifier: string | null;
+  /** Other plugin entries preserved alongside the oas one. */
+  extras: string[];
+}
+
+export interface DoctorResult {
+  /** True when there are zero blocking issues. */
+  ok: boolean;
+  /** Blocking problems — the install flow will not work until they are fixed. */
+  issues: string[];
+  /** Non-blocking advisories — install may still work. */
+  warnings: string[];
+  /** Informational notes about what was checked. */
+  info: string[];
+}
+
+const formatFromPath = (path: string): "json" | "jsonc" =>
+  path.endsWith(".jsonc") ? "jsonc" : "json";
+
+/**
+ * Read-only status probe. Prints a human-readable report to stdout and
+ * returns the same data as a structured result so callers (including
+ * `main.ts` and tests) can consume it without parsing the message.
+ */
+export const runStatus = (fs: CliFs = createRealFs()): StatusResult => {
+  const loaded = loadGlobalConfig(fs);
+  const plugins = normalizePlugin(loaded.config.plugin);
+  const oasEntries = plugins.filter(matchesPlugin);
+  const extras = plugins.filter((entry) => !matchesPlugin(entry));
+  const format = formatFromPath(loaded.path);
+
+  console.log(`Config path:    ${loaded.path}`);
+  console.log(`Format:         ${format}`);
+  console.log(`Exists on disk: ${loaded.existed ? "yes" : "no (will be created on install)"}`);
+
+  if (oasEntries.length === 0) {
+    console.log(`Installed:      no`);
+    return {
+      installed: false,
+      path: loaded.path,
+      format,
+      specifier: null,
+      extras,
+    };
+  }
+
+  // In practice `install` dedupes so at most one oas entry survives;
+  // reporting the first keeps the output stable for scripting.
+  const specifier = oasEntries[0] ?? null;
+  console.log(`Installed:      yes`);
+  console.log(`Specifier:      ${specifier}`);
+  if (extras.length > 0) {
+    console.log(`Other plugins:  ${extras.join(", ")}`);
+  }
+
+  return {
+    installed: true,
+    path: loaded.path,
+    format,
+    specifier,
+    extras,
+  };
+};
+
+/**
+ * Health checks. The function does not exit on its own — it returns a
+ * `DoctorResult` and `main.ts` maps `ok === false` to exit code 1.
+ */
+export const runDoctor = (
+  fs: CliFs = createRealFs(),
+  env: NodeJS.ProcessEnv = process.env,
+): DoctorResult => {
+  const issues: string[] = [];
+  const warnings: string[] = [];
+  const info: string[] = [];
+
+  // 1. Node major version — `package.json#engines.node` requires >= 18.
+  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+  if (!Number.isFinite(nodeMajor) || nodeMajor < 18) {
+    issues.push(`Node ${process.versions.node} detected — ${PLUGIN_NAME} requires Node >= 18`);
+  } else {
+    info.push(`Node ${process.versions.node} OK`);
+  }
+
+  // 2. Config file readability + format detection.
+  const loaded = loadGlobalConfig(fs, env);
+  const format = formatFromPath(loaded.path);
+  info.push(`Config path: ${loaded.path}`);
+  info.push(`Config format: ${format}`);
+  if (!loaded.existed) {
+    warnings.push(`Config file does not exist yet — install will create it`);
+  }
+
+  // 3. `plugin` shape — must be array, object (legacy), or absent.
+  const rawPlugin = loaded.config.plugin;
+  if (rawPlugin === undefined || rawPlugin === null) {
+    info.push(`Plugin entries: 0`);
+  } else {
+    const validShape = Array.isArray(rawPlugin) || typeof rawPlugin === "object";
+    if (!validShape) {
+      issues.push(`config.plugin is neither array nor object — install will reset it`);
+    } else {
+      const plugins = normalizePlugin(rawPlugin);
+      info.push(`Plugin entries: ${plugins.length}`);
+      const oasCount = plugins.filter(matchesPlugin).length;
+      if (oasCount > 1) {
+        warnings.push(`${oasCount} ${PLUGIN_NAME} entries present — install will dedupe`);
+      }
+    }
+  }
+
+  // 4. Parent dir existence + writability. We probe the real filesystem
+  // because POSIX permissions are not something the in-memory `CliFs` can
+  // meaningfully model. Failures here are warnings, not blocking issues:
+  // install will surface a real error when it tries to write.
+  try {
+    const dir = dirname(loaded.path);
+    try {
+      const stat = statSync(dir);
+      if (stat.isDirectory()) {
+        try {
+          accessSync(dir, fsConstants.W_OK);
+          info.push(`Config directory writable: ${dir}`);
+        } catch {
+          warnings.push(`Config directory ${dir} is not writable`);
+        }
+      } else {
+        issues.push(`${dir} exists but is not a directory`);
+      }
+    } catch {
+      warnings.push(
+        `Config directory ${dir} does not exist yet — will be created on first install`,
+      );
+    }
+  } catch {
+    // best-effort — never block on permission probes
+  }
+
+  // Render the report. Order: info, warnings, errors, summary.
+  for (const line of info) console.log(`  ✓ ${line}`);
+  for (const line of warnings) console.warn(`  ! ${line}`);
+  for (const line of issues) console.error(`  ✗ ${line}`);
+
+  const ok = issues.length === 0;
+  if (ok) {
+    console.log(`\n✓ Doctor: all checks passed`);
+  } else {
+    console.log(`\n✗ Doctor: ${issues.length} issue(s) found`);
+  }
+
+  return { ok, issues, warnings, info };
+};

package/packages/opencode-agent-skills-md/src/cli/uninstall.ts

@@ -0,0 +1,157 @@
+// ---------------------------------------------------------------------------
+// src/cli/uninstall.ts — `oas uninstall` command.
+//
+// Removes every `opencode-agent-skills-md` entry from the global OpenCode
+// config's `plugin` list. With `--purge`, also deletes the runtime cache
+// directory (`~/.cache/opencode/node_modules/opencode-agent-skills-md`) and
+// the plugin's own config dir (`~/.config/opencode-agent-skills-md/`).
+//
+// Like `install`, the function is side-effect-free beyond prints and disk
+// writes through `fs`. Tests inject an in-memory `CliFs` to exercise the
+// config-mutation path; the purge path uses `node:fs` directly because
+// `CliFs` deliberately does not expose recursive directory removal.
+// ---------------------------------------------------------------------------
+
+import { rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  backupIfWritable,
+  type CliFs,
+  loadGlobalConfig,
+  matchesPlugin,
+  normalizePlugin,
+  PLUGIN_NAME,
+  writeAtomically,
+} from "./config";
+import { createRealFs } from "./real-fs";
+
+export interface UninstallOptions {
+  /** Also remove the runtime cache and the plugin's own config dir. */
+  purge?: boolean;
+  /** Plan the change and print it without writing. */
+  dryRun?: boolean;
+  /** Reserved for future confirmation prompts; accepted but unused for now. */
+  yes?: boolean;
+}
+
+export interface UninstallResult {
+  status: "wrote" | "planned" | "noop";
+  path: string;
+  /** Plugin entries that were (or would be) removed from the config. */
+  removed: string[];
+  /** Cache / config dirs removed under `--purge`. Empty when `--purge` was not set. */
+  purged: string[];
+}
+
+const JSON_INDENT = 2;
+
+/** Resolve `$HOME` (or `os.homedir()` as last resort) for purge paths. */
+const homeRoot = (env: NodeJS.ProcessEnv = process.env): string => {
+  const home = env.HOME;
+  if (typeof home === "string" && home.trim().length > 0) return home;
+  return homedir();
+};
+
+/** Bun/npm-style cache path where the plugin gets installed at runtime. */
+export const cachePath = (env: NodeJS.ProcessEnv = process.env): string =>
+  join(homeRoot(env), ".cache", "opencode", "node_modules", PLUGIN_NAME);
+
+/** Plugin's own XDG config dir (separate from the OpenCode config it edits). */
+export const pluginConfigPath = (env: NodeJS.ProcessEnv = process.env): string =>
+  join(homeRoot(env), ".config", PLUGIN_NAME);
+
+/**
+ * Best-effort recursive delete. Returns the path on success or `null` when
+ * the target was missing (we don't want to fail the whole command if the
+ * user never ran `install` to create these dirs in the first place).
+ */
+const purgeDir = (path: string): string | null => {
+  try {
+    rmSync(path, { recursive: true, force: true });
+    return path;
+  } catch {
+    return null;
+  }
+};
+
+export const runUninstall = (
+  opts: UninstallOptions = {},
+  fs: CliFs = createRealFs(),
+): UninstallResult => {
+  const loaded = loadGlobalConfig(fs);
+
+  if (loaded.parseError) {
+    throw new Error(
+      `oas: config file is malformed JSON — aborting to avoid data loss.\n` +
+        `  path:  ${loaded.path}\n` +
+        `  error: ${loaded.parseError}\n` +
+        `Fix the JSON error, or delete the file and re-run.`,
+    );
+  }
+
+  const config: Record<string, unknown> = { ...loaded.config };
+  const existing = normalizePlugin(config.plugin);
+  const removed = existing.filter(matchesPlugin);
+  const remaining = existing.filter((entry) => !removed.includes(entry));
+
+  // Compute purge candidates up front so dry-run can report them too.
+  const purgeCandidates = opts.purge ? [cachePath(), pluginConfigPath()] : [];
+  const purged: string[] = [];
+  const plannedPurge: string[] = [];
+
+  if (opts.purge && opts.dryRun) {
+    plannedPurge.push(...purgeCandidates);
+  }
+
+  // Nothing to remove from the config AND nothing to purge → true no-op.
+  if (removed.length === 0 && purgeCandidates.length === 0) {
+    console.log(`✓ Not installed: ${PLUGIN_NAME} not found in ${loaded.path}`);
+    return { status: "noop", path: loaded.path, removed: [], purged: [] };
+  }
+
+  // Build the post-uninstall config object.
+  if (removed.length > 0) {
+    if (remaining.length === 0) {
+      delete config.plugin;
+    } else {
+      config.plugin = remaining;
+    }
+  }
+
+  if (opts.dryRun) {
+    if (plannedPurge.length > 0) {
+      console.log(`[dry-run] Would purge:`);
+      for (const p of plannedPurge) console.log(`  ${p}`);
+    }
+    console.log(`[dry-run] Would write to ${loaded.path}:`);
+    console.log(JSON.stringify(config, null, JSON_INDENT));
+    return {
+      status: "planned",
+      path: loaded.path,
+      removed,
+      purged: plannedPurge,
+    };
+  }
+
+  // Write the updated config before purging — this preserves the invariant
+  // that config state is committed before side-effectful purge runs.
+  let backup: string | null = null;
+  if (removed.length > 0 && loaded.existed) {
+    backup = backupIfWritable(loaded.path, fs);
+    writeAtomically(loaded.path, JSON.stringify(config, null, JSON_INDENT), fs);
+  }
+
+  // Best-effort purge after config write is committed.
+  for (const p of purgeCandidates) {
+    const result = purgeDir(p);
+    if (result) purged.push(result);
+  }
+
+  console.log(`✓ Uninstalled ${PLUGIN_NAME}`);
+  if (removed.length > 0) console.log(`  config: ${loaded.path}`);
+  if (backup) console.log(`  backup: ${backup}`);
+  for (const p of purged) console.log(`  purged: ${p}`);
+
+  return { status: "wrote", path: loaded.path, removed, purged };
+};