plugnz 0.0.0 → 0.0.4

package/src/mcp-write.ts

@@ -0,0 +1,81 @@
+/**
+ * The write side of the shared MCP reader (src/mcp.ts).
+ *
+ * `pinPluginMcpFiles` lives here, not in mcp.ts, because every host reader
+ * imports mcp.ts's read helpers — and a module is evaluated whole, so the
+ * `writeFileSync` would load with them and reach doctor through the registry.
+ * Only the host writers (src/hosts/<host>-writer.ts) import this module;
+ * test/doctor-imports.test.ts keeps it out of doctor's import graph.
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PinChange, PinOptions, PinOutcome, PinRefusal } from './host';
+import { normalizeTransport, readJson, type PluginMcpCandidate, type RawServerDef } from './mcp';
+import { which } from './exec';
+
+/** The file a candidate names, relative to the plugin root. */
+function candidateFile(pluginDir: string, candidate: PluginMcpCandidate): string {
+  return candidate.kind === 'spec' ? join(pluginDir, candidate.file) : join(pluginDir, candidate.manifest);
+}
+
+/**
+ * Rewrite bare stdio `command`s in one plugin copy to the absolute path they
+ * resolve to on this process's PATH — the write side of `pin`, shared by every
+ * host so the files it rewrites are exactly the `candidates` it reads.
+ *
+ * Per spec §7.2.1 a `command` is a single executable token, either bare or a
+ * plugin-relative path starting with `./`; only the bare form is rewritten
+ * here (a `./`-relative or absolute command is already unambiguous). A bare
+ * command that does not resolve is never invented: it is returned as a refusal
+ * and the file is left as-is.
+ *
+ * A codex-style pointer manifest (`"mcpServers": "./.mcp.json"`) is not an
+ * object, so it is skipped here — the file it points at is a spec candidate of
+ * its own and gets pinned directly.
+ */
+export function pinPluginMcpFiles(
+  pluginDir: string,
+  candidates: readonly PluginMcpCandidate[],
+  opts: PinOptions = {},
+): PinOutcome {
+  const changes: PinChange[] = [];
+  const refusals: PinRefusal[] = [];
+  // One server is usually restated across 2–3 files; report each name once
+  // (the twins are still rewritten below) so findings and recorded pins don't
+  // repeat per file.
+  const reported = new Set<string>();
+  for (const candidate of candidates) {
+    const file = candidateFile(pluginDir, candidate);
+    const root = readJson(file);
+    if (root === null) continue;
+    const servers = root['mcpServers'];
+    if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) continue;
+    let rewritten = false;
+    for (const [name, value] of Object.entries(servers as Record<string, unknown>)) {
+      if (opts.only !== undefined && !opts.only.includes(name)) continue;
+      if (typeof value !== 'object' || value === null) continue;
+      const def = value as RawServerDef;
+      if (normalizeTransport(def) !== 'stdio') continue;
+      const command = def['command'];
+      if (typeof command !== 'string' || command.length === 0 || command.includes('/')) continue;
+      const resolved = which(command);
+      if (resolved === null) {
+        if (!reported.has(name)) {
+          reported.add(name);
+          refusals.push({ server: name, command, file });
+        }
+        continue;
+      }
+      if (!reported.has(name)) {
+        reported.add(name);
+        changes.push({ server: name, from: command, to: resolved, file });
+      }
+      if (command !== resolved) {
+        def['command'] = resolved;
+        rewritten = true;
+      }
+    }
+    if (rewritten && opts.dryRun !== true) writeFileSync(file, JSON.stringify(root, null, 2));
+  }
+  return { changes, refusals };
+}

package/src/mcp.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared reader for MCP server declarations — read-only.
+ *
+ * Two shapes occur on disk:
+ *  - the spec's `mcp.json` / the plugins CLI's `.mcp.json` at the plugin root:
+ *    `{ $schema, mcpServers: { <name>: { type, command, args, … } } }`
+ *    (spec §7.2.1: `mcpServers` member values are server configs; stdio
+ *    servers carry a single-token `command`)
+ *  - host-native manifests with an `mcpServers` member, measured in two
+ *    variants: kimi `.kimi-plugin/plugin.json` carries the servers inline
+ *    (spec-style entries); codex `.codex-plugin/plugin.json` carries a
+ *    pointer string — `"mcpServers": "./.mcp.json"` — resolved against the
+ *    plugin root (13 manifests measured: 6 pointers, 7 absent, 0 inline)
+ *
+ * Measured on this machine, `npx plugins add` dereferences one source into
+ * *all* of these per install dir, so the same server usually appears 2–3×;
+ * identical restatements are deduped, keeping the highest-priority occurrence.
+ *
+ * The write side (`pinPluginMcpFiles`, the per-host `pin` implementations'
+ * shared rewriter) lives in src/mcp-write.ts so this module stays safe for
+ * doctor to load transitively through the host readers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { McpServerEntry } from './host';
+
+export type RawServerDef = Record<string, unknown>;
+
+/**
+ * One place a plugin may declare MCP servers, in the host's own priority
+ * order: a spec `mcp.json`/`.mcp.json` at the plugin root, or a host-native
+ * manifest whose `mcpServers` member is either inline servers or (codex-style)
+ * a pointer string at a spec file.
+ */
+export type PluginMcpCandidate = { kind: 'spec'; file: string } | { kind: 'inline'; manifest: string };
+
+export function readJson(file: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** `mcpServers` object from a spec `mcp.json`/`.mcp.json` file, or null. */
+export function specMcpServers(file: string): Record<string, RawServerDef> | null {
+  const root = readJson(file);
+  if (root === null) return null;
+  const servers = root['mcpServers'];
+  if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) return null;
+  return servers as Record<string, RawServerDef>;
+}
+
+/** Inline `mcpServers` object from a host-native plugin manifest, or null. */
+export function inlineMcpServers(manifestFile: string): Record<string, RawServerDef> | null {
+  const root = readJson(manifestFile);
+  if (root === null) return null;
+  const servers = root['mcpServers'];
+  if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) return null;
+  return servers as Record<string, RawServerDef>;
+}
+
+/**
+ * The file a host-native manifest's `mcpServers` points at, when it is a
+ * codex-style pointer string (`"./.mcp.json"`, resolved against the plugin
+ * root), or null when it is not a pointer / points nowhere.
+ */
+export function pointerMcpFile(manifestFile: string, pluginDir: string): string | null {
+  const root = readJson(manifestFile);
+  if (root === null) return null;
+  const pointer = root['mcpServers'];
+  if (typeof pointer !== 'string') return null;
+  const pointed = join(pluginDir, pointer);
+  return existsSync(pointed) ? pointed : null;
+}
+
+export function normalizeTransport(def: RawServerDef): 'stdio' | 'http' | null {
+  const type = typeof def['type'] === 'string' ? def['type'] : undefined;
+  if (type === 'http' || type === 'sse' || typeof def['url'] === 'string') return 'http';
+  if (type === 'stdio' || typeof def['command'] === 'string') return 'stdio';
+  return null;
+}
+
+/**
+ * Collect deduped MCP entries for one plugin directory.
+ * `candidates` is in priority order — the file the host actually launches
+ * from comes first (see docs/hosts/<host>.md for per-host evidence).
+ */
+export function collectPluginServers(
+  pluginId: string,
+  pluginDir: string,
+  candidates: readonly PluginMcpCandidate[],
+): McpServerEntry[] {
+  const entries: McpServerEntry[] = [];
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    // A native manifest resolves to itself (inline servers) or, codex-style,
+    // to the spec file its `mcpServers` pointer names.
+    let file: string;
+    let servers: Record<string, RawServerDef> | null;
+    if (candidate.kind === 'spec') {
+      file = join(pluginDir, candidate.file);
+      servers = specMcpServers(file);
+    } else {
+      file = join(pluginDir, candidate.manifest);
+      const pointed = pointerMcpFile(file, pluginDir);
+      if (pointed !== null) {
+        file = pointed;
+        servers = specMcpServers(pointed);
+      } else {
+        servers = inlineMcpServers(file);
+      }
+    }
+    if (servers === null) continue;
+    for (const [name, def] of Object.entries(servers)) {
+      const transport = normalizeTransport(def);
+      if (transport === null) continue;
+      const command = typeof def['command'] === 'string' ? def['command'] : undefined;
+      const rawArgs = def['args'];
+      const args = Array.isArray(rawArgs) ? rawArgs.filter((a): a is string => typeof a === 'string') : undefined;
+      // Dedupe identical restatements across the candidate files.
+      const key = `${name}\0${transport}\0${command ?? ''}\0${JSON.stringify(args ?? [])}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const entry: McpServerEntry = {
+        name,
+        transport,
+        origin: 'plugin',
+        pluginId,
+        file,
+        baseDir: pluginDir,
+      };
+      if (command !== undefined) entry.command = command;
+      if (args !== undefined) entry.args = args;
+      if (def['enabled'] === false) entry.enabled = false;
+      entries.push(entry);
+    }
+  }
+  return entries;
+}
+
+/** Collect entries from a host-level config file (`mcpServers` object shape). */
+export function collectUserServers(file: string, baseDir: string): McpServerEntry[] {
+  const servers = specMcpServers(file);
+  if (servers === null) return [];
+  const entries: McpServerEntry[] = [];
+  for (const [name, def] of Object.entries(servers)) {
+    const transport = normalizeTransport(def);
+    if (transport === null) continue;
+    const command = typeof def['command'] === 'string' ? def['command'] : undefined;
+    const rawArgs = def['args'];
+    const args = Array.isArray(rawArgs) ? rawArgs.filter((a): a is string => typeof a === 'string') : undefined;
+    const entry: McpServerEntry = { name, transport, origin: 'user', file, baseDir };
+    if (command !== undefined) entry.command = command;
+    if (args !== undefined) entry.args = args;
+    if (def['enabled'] === false) entry.enabled = false;
+    entries.push(entry);
+  }
+  return entries;
+}

package/src/paths.ts

@@ -0,0 +1,101 @@
+/**
+ * Path resolution for open-plugin.
+ *
+ * Every filesystem path the tool touches goes through this module so tests can
+ * redirect the whole world into a temp directory via `OPEN_PLUGIN_HOME`
+ * (AGENTS.md: tests never touch the real home).
+ *
+ * Resolution order for each host root: a host-specific override env var wins,
+ * then `OPEN_PLUGIN_HOME` (a stand-in for `$HOME`), then the real `$HOME`.
+ */
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/** The home stand-in: `OPEN_PLUGIN_HOME` when set, else the real `$HOME`. */
+export function homeRoot(): string {
+  const override = process.env['OPEN_PLUGIN_HOME'];
+  if (override && override.length > 0) return override;
+  return process.env['HOME'] ?? '.';
+}
+
+/** `~/.claude` — claude-code config root (`installed_plugins.json` lives under `plugins/`). */
+export function claudeCodeRoot(): string {
+  return process.env['OPEN_PLUGIN_CLAUDE_CODE_ROOT'] ?? join(homeRoot(), '.claude');
+}
+
+/** `~/.codex` — codex home: `config.toml` + `plugins/cache/`. */
+export function codexHome(): string {
+  return process.env['OPEN_PLUGIN_CODEX_HOME'] ?? join(homeRoot(), '.codex');
+}
+
+/** `~/.kimi-code` — kimi root: `config.toml` + `plugins/managed/`. */
+export function kimiRoot(): string {
+  return process.env['OPEN_PLUGIN_KIMI_ROOT'] ?? join(homeRoot(), '.kimi-code');
+}
+
+/** `~/.cursor` — cursor root: `mcp.json` + `plugins/local/`. */
+export function cursorRoot(): string {
+  return process.env['OPEN_PLUGIN_CURSOR_ROOT'] ?? join(homeRoot(), '.cursor');
+}
+
+/** `~/.omp` — omp home: its own plugin store under `plugins/` (AGENTS.md hosts list). */
+export function ompRoot(): string {
+  return process.env['OPEN_PLUGIN_OMP_ROOT'] ?? join(homeRoot(), '.omp');
+}
+
+/** `~/.grok` — Grok Build's native configuration and installed-plugin store. */
+export function grokRoot(): string {
+  return process.env['OPEN_PLUGIN_GROK_ROOT'] ?? join(homeRoot(), '.grok');
+}
+
+/** Hermes's native plugin home. Portable packages live under `plugins/`. */
+export function hermesRoot(): string {
+  return process.env['OPEN_PLUGIN_HERMES_ROOT'] ?? join(homeRoot(), '.hermes');
+}
+
+/** Requested config path; writer verifies native HERMES_HOME/config.yaml resolves to it. */
+export function hermesConfigPath(): string {
+  return process.env['OPEN_PLUGIN_HERMES_CONFIG_PATH'] ?? join(hermesRoot(), 'config.yaml');
+}
+
+/** Official ZCode CLI config and plugin root (`~/.zcode/cli`). */
+export function zcodeCliRoot(): string {
+  return join(zcodeStorageRoot(), 'cli');
+}
+
+/** Official ZCode keeps config under HOME while allowing its plugin store to move. */
+export function zcodeCliConfigRoot(): string {
+  return join(homeRoot(), '.zcode', 'cli');
+}
+
+export function zcodeStorageRoot(): string {
+  return process.env['ZCODE_STORAGE_DIR'] ?? dirname(zcodeCliConfigRoot());
+}
+
+/**
+ * open-plugin's own install ledger, written by `add`.
+ * When `OPEN_PLUGIN_HOME` is set the ledger is `<home>/state.json`; in real use
+ * it lives under `~/.open-plugin/state.json` so we never drop a file in `$HOME`.
+ */
+export function stateFile(): string {
+  const override = process.env['OPEN_PLUGIN_HOME'];
+  if (override && override.length > 0) return join(override, 'state.json');
+  return join(process.env['HOME'] ?? '.', '.open-plugin', 'state.json');
+}
+
+/**
+ * open-plugin's git-source clone cache, written when `add` resolves a git URL
+ * (src/source.ts). Same rule as `stateFile()`: `<home>/cache` under
+ * `OPEN_PLUGIN_HOME`, `~/.open-plugin/cache` in real use — never a generic
+ * `cache/` directory dropped straight into `$HOME`.
+ */
+export function cacheRoot(): string {
+  const override = process.env['OPEN_PLUGIN_HOME'];
+  if (override && override.length > 0) return join(override, 'cache');
+  return join(process.env['HOME'] ?? '.', '.open-plugin', 'cache');
+}
+
+/** Test/debug helper: does a path exist? */
+export function pathExists(p: string): boolean {
+  return existsSync(p);
+}

package/src/pin.ts

@@ -0,0 +1,135 @@
+/**
+ * `plgnz pin` — make plugin-provided MCP servers launchable from a GUI
+ * host.
+ *
+ * A GUI-launched host (cursor) has no shell PATH, so a bare `command` in a
+ * plugin's `mcp.json` may resolve to nothing at launch even though it resolves
+ * fine in this shell. Spec §7.2.1 leaves PATH participation client-defined and
+ * tells plugins not to depend on it; `pin` is the repair: resolve every *bare*
+ * stdio command on this process's PATH right now and write the absolute path
+ * into the host's copy of the plugin.
+ *
+ *   - Default targets are the GUI hosts (`HostReader.gui`); `--all` covers
+ *     every host, `--target <host>` picks explicitly.
+ *   - Only plugin-provided servers are touched. A host's *user-level* MCP
+ *     config is hand-written and stays hand-written — `pin` never edits it.
+ *   - A bare command that does not resolve is refused (✗, exit 1) and left
+ *     bare: a wrong absolute path would be worse than a bare one.
+ *   - What was pinned is recorded in the install ledger (`state.json`), so
+ *     `update` can re-apply it after re-adding a copy that restores the
+ *     source's bare command. Plugins plgnz did not install have no
+ *     record to write to; that is reported (`!`), not invented.
+ *
+ * The absolute-path form is not one of the two spec §7.2.1 allows in a
+ * `command` (a bare name or a `./`-relative path); it is a host-native repair
+ * for a client with no shell PATH, and it keeps the field a single executable
+ * token, which is what §7.2.1 is protecting.
+ */
+import type { HostWriter } from './host';
+import type { Mark } from './doctor';
+import { writers as allWriters } from './hosts/writers';
+import { findRecord, readState, type InstallRecord } from './state';
+import { writeState } from './state-write';
+import { fingerprintTree } from './fingerprint';
+
+export interface PinFinding {
+  host: string;
+  mark: Mark;
+  message: string;
+}
+
+export interface PinRunResult {
+  findings: PinFinding[];
+  exitCode: number;
+}
+
+export interface PinRunOptions {
+  /** Host ids to pin; empty/absent falls back to the GUI hosts (or all with `all`). */
+  targets?: readonly string[];
+  /** Every host, not just the GUI ones. */
+  all?: boolean;
+  /** Report changes without writing them (and without touching the ledger). */
+  dryRun?: boolean;
+  /** Ledger to read/update; defaults to the real `state.json`. */
+  state?: InstallRecord[];
+  /** Hosts to consider; defaults to the registry. */
+  writers?: readonly HostWriter[];
+}
+
+/** The hosts `pin` targets when nothing was asked for: the GUI ones. */
+export function defaultPinTargets(all: readonly HostWriter[] = allWriters): HostWriter[] {
+  return all.filter((w) => w.gui);
+}
+
+export async function runPin(options: PinRunOptions = {}): Promise<PinRunResult> {
+  const candidates = options.writers ?? allWriters;
+  const state = options.state ?? readState();
+  const selected = selectTargets(candidates, options);
+  const findings: PinFinding[] = [];
+  let ledgerChanged = false;
+
+  for (const host of selected) {
+    if (!host.detect()) continue;
+    for (const plugin of host.listInstalled()) {
+      if (plugin.path === undefined) continue;
+      const outcome = await host.pin(plugin, { dryRun: options.dryRun });
+      const prefix = options.dryRun === true ? '[dry-run] ' : '';
+      for (const change of outcome.changes) {
+        findings.push({
+          host: host.id,
+          mark: '✓',
+          message: `${prefix}server '${change.server}': pinned '${change.from}' → ${change.to} (plugin ${plugin.id})`,
+        });
+      }
+      for (const refusal of outcome.refusals) {
+        findings.push({
+          host: host.id,
+          mark: '✗',
+          message:
+            `${prefix}server '${refusal.server}': bare command '${refusal.command}' not found on PATH — not pinned ` +
+            `(plugin ${plugin.id})`,
+        });
+      }
+      if (outcome.changes.length === 0) continue;
+
+      const record = findRecord(state, host.id, plugin.id);
+      if (record === undefined) {
+        findings.push({
+          host: host.id,
+          mark: '!',
+          message:
+            `plugin '${plugin.id}' has no record in state.json — pinned, but plgnz did not install it, ` +
+            `so update will not restore the pin`,
+        });
+        continue;
+      }
+      if (options.dryRun === true) continue;
+      const pins = new Set(record.pins ?? []);
+      for (const change of outcome.changes) pins.add(change.server);
+      const next = [...pins].sort();
+      if (next.length !== (record.pins ?? []).length) {
+        record.pins = next;
+        ledgerChanged = true;
+      }
+      try {
+        record.installedFingerprint = fingerprintTree(plugin.path);
+        ledgerChanged = true;
+      } catch (error) {
+        findings.push({ host: host.id, mark: '✗', message: `plugin '${plugin.id}' was pinned but its installed bytes could not be recorded — ${(error as Error).message}` });
+      }
+    }
+  }
+
+  if (ledgerChanged) writeState(state);
+  return { findings, exitCode: findings.some((f) => f.mark === '✗') ? 1 : 0 };
+}
+
+function selectTargets(all: readonly HostWriter[], options: PinRunOptions): HostWriter[] {
+  const targets = options.targets;
+  if (targets !== undefined && targets.length > 0) {
+    const wanted = new Set(targets);
+    return all.filter((w) => wanted.has(w.id));
+  }
+  if (options.all === true) return [...all];
+  return defaultPinTargets(all);
+}