plugnz 0.0.4 → 0.0.6

package/src/doctor.ts

@@ -1,277 +0,0 @@
-/**
- * `plgnz doctor` — read-only diagnosis.
- *
- * Read-only by construction: this module imports only the readers-only host
- * registry (src/hosts/index.ts) — no writer module loads with it — and
- * touches no file except reading configs and running `git rev-parse` /
- * `git ls-remote` against recorded sources. test/doctor-imports.test.ts
- * walks this module's import graph and fails if a writer appears in it.
- *
- * Three checks (AGENTS.md contract):
- *  (1) command resolution — every stdio server in each host's native MCP
- *      config AND in each installed plugin's mcp.json/.mcp.json: a command
- *      containing `/` must exist and be executable; a bare command is
- *      resolved on this process's PATH. On GUI hosts (cursor) a bare command
- *      is additionally flagged `!` with the hint `run plgnz pin` —
- *      macOS GUI apps have no shell PATH (spec §7.2.1 makes PATH
- *      participation client-defined).
- *  (2) shadow / duplicate — the same server name in a host's user-level MCP
- *      config and in an installed plugin's mcp.json is ✗: on codex the user
- *      entry wins and silently shadows the plugin server; on cursor both
- *      load and duplicate.
- *  (3) staleness — the installed plugin's recorded source sha (state.json,
- *      written by `add`) vs the source's current head: `git rev-parse` for a
- *      local checkout, `git ls-remote` for a git URL (recorded verbatim by
- *      `add`, so it is the same query the install was resolved with).
- *      Installs made by another tool have no record: report `unknown` —
- *      never treat a missing record as fresh or as zero.
- *
- * Output: one line per finding `<host>  ✓|✗|!  <message>`; `--json` emits
- * the same as an array; exit 1 if any ✗, else 0.
- *
- * Messages never include server args or env values — args can carry
- * credentials.
- */
-import type { HostReader, McpServerEntry } from './host';
-import { hosts as allHosts } from './hosts';
-import { findRecord, readState, type InstallRecord } from './state';
-import { expandRootPlaceholders, gitHead, gitRemoteHead, isExecutableFile, isGitUrl, resolveCommandPath, which } from './exec';
-import { fingerprintInstallation, fingerprintTree } from './fingerprint';
-
-export type Mark = '✓' | '✗' | '!';
-
-export interface DoctorFinding {
-  host: string;
-  mark: Mark;
-  message: string;
-  check?: 'content';
-  pluginId?: string;
-}
-
-function contentFinding(host: string, pluginId: string, mark: Mark, message: string): DoctorFinding {
-  return { host, pluginId, check: 'content', mark, message };
-}
-
-/** Verify source bytes and the activated native tree independently of git freshness. */
-function checkContent(host: HostReader, state: InstallRecord[], out: DoctorFinding[]): void {
-  const installed = new Map(host.listInstalled().map((plugin) => [plugin.id, plugin]));
-  const records = state.filter((record) => record.host === host.id);
-  for (const record of records) {
-    if (record.pending !== undefined) {
-      out.push(contentFinding(host.id, record.id, '!', `install '${record.id}' content unverified — ${record.pending} is pending`));
-      continue;
-    }
-    const native = installed.get(record.id);
-    if (native === undefined || native.enabled === false || native.path === undefined) {
-      out.push(contentFinding(host.id, record.id, '✗', `install '${record.id}' content stale — enabled native representation is missing`));
-      continue;
-    }
-    if (record.sourceDir === undefined || record.fingerprint === undefined || record.installedFingerprint === undefined) {
-      out.push(contentFinding(host.id, record.id, '!', `install '${record.id}' content unverified — legacy record has no complete byte proof`));
-      continue;
-    }
-    let sourceFingerprint: string;
-    try { sourceFingerprint = fingerprintTree(record.sourceDir); }
-    catch (error) {
-      out.push(contentFinding(host.id, record.id, '✗', `install '${record.id}' source content cannot be verified — ${(error as Error).message}`));
-      continue;
-    }
-    if (sourceFingerprint !== record.fingerprint) {
-      out.push(contentFinding(host.id, record.id, '✗', `install '${record.id}' source content changed since activation`));
-      continue;
-    }
-    let nativeFingerprint: string;
-    try { nativeFingerprint = fingerprintInstallation(native); }
-    catch (error) {
-      out.push(contentFinding(host.id, record.id, '✗', `install '${record.id}' native content cannot be verified — ${(error as Error).message}`));
-      continue;
-    }
-    if (nativeFingerprint !== record.installedFingerprint) {
-      out.push(contentFinding(host.id, record.id, '✗', `install '${record.id}' native content changed after activation`));
-      continue;
-    }
-    out.push(contentFinding(host.id, record.id, '✓', `install '${record.id}' source and native content match their recorded byte proofs`));
-  }
-  for (const native of installed.values()) {
-    if (records.some((record) => record.id === native.id)) continue;
-    out.push(contentFinding(host.id, native.id, '!', `install '${native.id}' content unverified — no plgnz record`));
-  }
-}
-
-export interface DoctorResult {
-  findings: DoctorFinding[];
-  exitCode: number;
-}
-
-function originLabel(entry: McpServerEntry): string {
-  if (entry.origin === 'plugin' && entry.pluginId !== undefined) return `plugin ${entry.pluginId}`;
-  if (entry.origin === 'plugin') return 'plugin';
-  return 'user config';
-}
-
-function shortSha(sha: string): string {
-  return sha.slice(0, 8);
-}
-
-/** sha equality tolerant of the host recording a short sha (claude-code records 12 chars). */
-function sameSha(installed: string, head: string): boolean {
-  const a = installed.toLowerCase();
-  const b = head.toLowerCase();
-  const n = Math.min(a.length, b.length);
-  return a.slice(0, n) === b.slice(0, n);
-}
-
-/** Check (1): every stdio command resolves and is executable. */
-function checkCommands(host: HostReader, entries: McpServerEntry[], out: DoctorFinding[]): void {
-  for (const entry of entries) {
-    if (entry.transport !== 'stdio' || entry.command === undefined) continue;
-    const label = originLabel(entry);
-    const suffix = entry.enabled === false ? ' [disabled]' : '';
-    // Host-native configs expand root placeholders at launch (spec §9.2 for
-    // ${PLUGIN_ROOT}; CLAUDE_/CODEX_/CURSOR_ variants measured in real caches).
-    // A known placeholder is expanded here so the real target is checked; an
-    // unknown one makes the entry unverifiable — flagged `!`, not dead.
-    let command = entry.command;
-    if (command.includes('${')) {
-      const result = expandRootPlaceholders(command, entry.baseDir);
-      if (result.unknown !== null) {
-        out.push({
-          host: host.id,
-          mark: '!',
-          message: `server '${entry.name}': command contains placeholder ${result.unknown} that plgnz cannot expand — not verified (${label})${suffix}`,
-        });
-        continue;
-      }
-      command = result.expanded;
-    }
-    if (command.includes('/')) {
-      const resolved = resolveCommandPath(command, entry.baseDir);
-      if (isExecutableFile(resolved)) {
-        out.push({ host: host.id, mark: '✓', message: `server '${entry.name}': command ok: ${resolved} (${label})${suffix}` });
-      } else {
-        out.push({
-          host: host.id,
-          mark: '✗',
-          message: `server '${entry.name}': command not found or not executable: ${resolved} (${label})${suffix}`,
-        });
-      }
-    } else {
-      const resolved = which(entry.command);
-      if (host.gui) {
-        if (resolved === null) {
-          out.push({
-            host: host.id,
-            mark: '✗',
-            message: `server '${entry.name}': bare command '${entry.command}' not found on PATH (${label})${suffix}`,
-          });
-        } else {
-          out.push({
-            host: host.id,
-            mark: '!',
-            message:
-              `server '${entry.name}': bare command '${entry.command}' may not resolve — macOS GUI apps have no shell PATH ` +
-              `(spec §7.2.1); run plgnz pin${suffix}`,
-          });
-        }
-      } else if (resolved !== null) {
-        out.push({
-          host: host.id,
-          mark: '✓',
-          message: `server '${entry.name}': bare command '${entry.command}' resolves to ${resolved} (${label})${suffix}`,
-        });
-      } else {
-        out.push({
-          host: host.id,
-          mark: '✗',
-          message: `server '${entry.name}': bare command '${entry.command}' not found on PATH (${label})${suffix}`,
-        });
-      }
-    }
-  }
-}
-
-/** Check (2): a server name defined both user-level and by an installed plugin. */
-function checkShadows(host: HostReader, entries: McpServerEntry[], out: DoctorFinding[]): void {
-  const userNames = new Set(entries.filter((e) => e.origin === 'user').map((e) => e.name));
-  const seen = new Set<string>();
-  for (const entry of entries) {
-    if (entry.origin !== 'plugin' || entry.pluginId === undefined || !userNames.has(entry.name)) continue;
-    const key = `${entry.name}\0${entry.pluginId}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    let behavior: string;
-    if (host.id === 'codex') {
-      behavior = 'on codex the user entry wins and silently shadows the plugin server';
-    } else if (host.id === 'cursor') {
-      behavior = 'on cursor both load and duplicate';
-    } else {
-      behavior = 'they shadow or duplicate each other';
-    }
-    out.push({
-      host: host.id,
-      mark: '✗',
-      message: `server '${entry.name}' is defined both in user config and in plugin '${entry.pluginId}' — ${behavior}`,
-    });
-  }
-}
-
-/** Check (3): installed sha (state.json) vs the source's current head. */
-function checkStaleness(host: HostReader, state: InstallRecord[], out: DoctorFinding[]): void {
-  for (const install of host.listInstalled()) {
-    const record = findRecord(state, host.id, install.id);
-    if (record === undefined) {
-      out.push({
-        host: host.id,
-        mark: '!',
-        message: `install '${install.id}' staleness unknown — no record in state.json (installed by another tool?)`,
-      });
-      continue;
-    }
-    if (record.pending !== undefined) continue;
-    // A git-URL source is recorded verbatim by `add` and has no local
-    // checkout to rev-parse — its head comes from `git ls-remote`, the same
-    // query that resolved the install (src/source.ts).
-    const head = isGitUrl(record.source) ? gitRemoteHead(record.source) : gitHead(record.source);
-    if (head === null) {
-      out.push({
-        host: host.id,
-        mark: '!',
-        message: `install '${install.id}' staleness unknown — cannot determine head of ${record.source}`,
-      });
-      continue;
-    }
-    if (sameSha(record.sourceSha, head)) {
-      out.push({ host: host.id, mark: '✓', message: `install '${install.id}' is at source head ${shortSha(head)}` });
-    } else {
-      out.push({
-        host: host.id,
-        mark: '✗',
-        message: `install '${install.id}' is stale — installed ${shortSha(record.sourceSha)}, source head ${shortSha(head)}`,
-      });
-    }
-  }
-}
-
-export function runDoctor(hostList: HostReader[] = allHosts, state: InstallRecord[] = readState()): DoctorResult {
-  const findings: DoctorFinding[] = [];
-  const selected = new Set(hostList.map((host) => host.id));
-  for (const record of state) {
-    if (record.pending !== undefined && selected.has(record.host)) {
-      findings.push({ host: record.host, mark: '!', message: `install '${record.id}' has pending ${record.pending} intent — retry the ${record.pending === 'remove' ? 'remove' : 'add/update'} operation` });
-    }
-  }
-  for (const host of hostList) {
-    if (!host.detect()) continue;
-    const entries = host.mcpEntries();
-    checkCommands(host, entries, findings);
-    checkShadows(host, entries, findings);
-    checkContent(host, state, findings);
-    checkStaleness(host, state, findings);
-  }
-  const exitCode = findings.some((f) => f.mark === '✗') ? 1 : 0;
-  return { findings, exitCode };
-}
-
-export function formatFinding(f: DoctorFinding): string {
-  return `${f.host}  ${f.mark}  ${f.message}`;
-}

package/src/exec.ts

@@ -1,91 +0,0 @@
-/**
- * Command-resolution and git helpers shared by doctor.
- */
-import { accessSync, constants, statSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-
-/** A path that exists and is an executable regular file. */
-export function isExecutableFile(p: string): boolean {
-  try {
-    if (!statSync(p).isFile()) return false;
-    accessSync(p, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Resolve a bare command on *this process's* PATH; null when not found. */
-export function which(command: string): string | null {
-  const pathEnv = process.env['PATH'] ?? '';
-  for (const dir of pathEnv.split(':')) {
-    if (dir.length === 0) continue;
-    const candidate = join(dir, command);
-    if (isExecutableFile(candidate)) return candidate;
-  }
-  return null;
-}
-
-/**
- * Resolve a command containing `/` (spec §7.2.1 allows bare names or
- * plugin-relative `./` paths). Absolute paths pass through; relative paths
- * resolve against `baseDir` (the plugin root, or the config file's root).
- */
-export function resolveCommandPath(command: string, baseDir: string): string {
-  return isAbsolute(command) ? command : join(baseDir, command);
-}
-
-/**
- * Root placeholders hosts expand at launch: spec §9.2 defines `${PLUGIN_ROOT}`;
- * the CLAUDE_/CODEX_/CURSOR_ variants are host-native conventions measured in
- * real caches (e.g. `${CODEX_PLUGIN_ROOT}/scripts/air-launcher.sh`). spec
- * §7.2.1 forbids placeholder expansion in a spec `command`, so these only
- * occur in host-native config files. Unknown placeholders are reported back
- * so doctor can mark the entry unverifiable instead of dead.
- */
-const ROOT_PLACEHOLDERS = new Set(['PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT', 'CODEX_PLUGIN_ROOT', 'CURSOR_PLUGIN_ROOT']);
-
-export function expandRootPlaceholders(command: string, root: string): { expanded: string; unknown: string | null } {
-  let unknown: string | null = null;
-  const expanded = command.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (whole, name: string) => {
-    if (ROOT_PLACEHOLDERS.has(name)) return root;
-    unknown = whole;
-    return whole;
-  });
-  return { expanded, unknown };
-}
-
-/** Current HEAD sha of a local git checkout, or null when unavailable. */
-export function gitHead(dir: string): string | null {
-  try {
-    const r = spawnSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
-    if (r.status !== 0) return null;
-    const sha = r.stdout.trim();
-    return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * A remote git source — the URL prefixes `add` accepts (src/source.ts
- * `resolveSource`). One predicate shared by `add` and doctor so the source
- * kinds that get recorded and the source kinds doctor can freshness-check
- * cannot drift apart.
- */
-export function isGitUrl(source: string): boolean {
-  return source.startsWith('http://') || source.startsWith('https://') || source.startsWith('git@');
-}
-
-/** Current HEAD sha of a git remote via `git ls-remote`, or null when unreachable. */
-export function gitRemoteHead(url: string): string | null {
-  try {
-    const r = spawnSync('git', ['ls-remote', url, 'HEAD'], { encoding: 'utf8' });
-    if (r.status !== 0) return null;
-    const sha = r.stdout.split('\t')[0]?.trim() ?? '';
-    return /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
-  } catch {
-    return null;
-  }
-}

package/src/fingerprint.ts

@@ -1,77 +0,0 @@
-/** Stable raw-byte tree fingerprint shared by source capture and read-only verification. */
-import { lstatSync, readFileSync, readdirSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
-import type { InstalledPlugin } from './host';
-
-declare const Bun: {
-  CryptoHasher: new (algorithm: 'sha256') => {
-    update(input: string | Uint8Array): void;
-    digest(encoding: 'hex'): string;
-  };
-};
-
-declare const TextEncoder: {
-  new (): { encode(input?: string): Uint8Array };
-};
-
-export function fingerprintTree(root: string): string {
-  if (lstatSync(root).isSymbolicLink()) throw new Error('cannot fingerprint symlink: .');
-  const hash = new Bun.CryptoHasher('sha256');
-  const walk = (dir: string, prefix: string): void => {
-    for (const entry of readdirSync(dir).sort()) {
-      const path = join(dir, entry);
-      const relative = prefix === '' ? entry : `${prefix}/${entry}`;
-      const stat = lstatSync(path);
-      if (stat.isSymbolicLink()) throw new Error(`cannot fingerprint symlink: ${relative}`);
-      if (stat.isDirectory()) {
-        hash.update(`d\0${relative}\0`);
-        walk(path, relative);
-      } else if (stat.isFile()) {
-        hash.update(`f\0${relative}\0`);
-        const content = new Bun.CryptoHasher('sha256');
-        content.update(readBytes(path));
-        hash.update(content.digest('hex'));
-        hash.update('\0');
-      } else {
-        throw new Error(`cannot fingerprint non-file resource: ${relative}`);
-      }
-    }
-  };
-  walk(root, '');
-  return hash.digest('hex');
-}
-
-/**
- * Fingerprint the bytes that make an installation active for its host.
- * Legacy hosts expose one native tree through `path`; multi-root hosts label
- * every active root so their separate stores cannot silently escape proof.
- */
-export function fingerprintInstallation(plugin: InstalledPlugin): string {
-  if (plugin.contentRoots === undefined) {
-    if (plugin.path === undefined) throw new Error('cannot fingerprint installation without a native path');
-    return fingerprintTree(plugin.path);
-  }
-  const roots = Object.entries(plugin.contentRoots).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-  if (roots.length === 0) throw new Error('cannot fingerprint installation with no content roots');
-  const hash = new Bun.CryptoHasher('sha256');
-  for (const [label, root] of roots) {
-    if (label.length === 0) throw new Error('cannot fingerprint installation with an empty content root label');
-    if (!isAbsolute(root)) throw new Error(`content root '${label}' is not absolute: ${root}`);
-    const fingerprint = fingerprintTree(root);
-    frame(hash, label);
-    frame(hash, fingerprint);
-  }
-  return hash.digest('hex');
-}
-
-function frame(hash: InstanceType<typeof Bun.CryptoHasher>, value: string): void {
-  const bytes = new TextEncoder().encode(value);
-  const size = new Uint8Array([bytes.byteLength >>> 24, bytes.byteLength >>> 16, bytes.byteLength >>> 8, bytes.byteLength]);
-  hash.update(size);
-  hash.update(bytes);
-}
-
-function readBytes(path: string): Uint8Array {
-  const read = readFileSync as unknown as (file: string) => Uint8Array;
-  return read(path);
-}

package/src/globals.d.ts

@@ -1,97 +0,0 @@
-/**
- * Minimal ambient declarations for the node builtins and globals this project
- * uses, so `tsc --noEmit` passes under strict mode with a zero-dependency
- * typecheck (allowed deps: typescript, smol-toml, add-mcp — no @types/node).
- * Bun implements these at runtime; only the surface we consume is declared.
- */
-
-declare module 'node:fs' {
-  export function existsSync(path: string): boolean;
-  export function readFileSync(path: string, encoding: 'utf8'): string;
-  export function readdirSync(path: string): string[];
-  export function statSync(path: string): {
-    isFile(): boolean;
-    isDirectory(): boolean;
-  };
-  export function lstatSync(path: string): {
-    isSymbolicLink(): boolean;
-    isFile(): boolean;
-    isDirectory(): boolean;
-  };
-  export function accessSync(path: string, mode?: number): void;
-  export function mkdirSync(path: string, options?: { recursive?: boolean }): string | undefined;
-  export function rmSync(path: string, options?: { recursive?: boolean; force?: boolean }): void;
-  export function cpSync(src: string, dest: string, options?: { recursive?: boolean }): void;
-  export function writeFileSync(path: string, data: string): void;
-  export function chmodSync(path: string, mode: number): void;
-  export function mkdtempSync(prefix: string): string;
-  export function renameSync(oldPath: string, newPath: string): void;
-  export function realpathSync(path: string): string;
-  export function symlinkSync(target: string, path: string, type?: 'dir' | 'file' | 'junction'): void;
-  export function readlinkSync(path: string): string;
-  export const constants: { X_OK: number };
-}
-
-declare module 'node:path' {
-  export function join(...parts: string[]): string;
-  export function resolve(...parts: string[]): string;
-  export function relative(from: string, to: string): string;
-  export function dirname(p: string): string;
-  export function basename(p: string, ext?: string): string;
-  export function isAbsolute(p: string): boolean;
-}
-
-declare module 'node:child_process' {
-  export interface SpawnSyncResult {
-    status: number | null;
-    stdout: string;
-    stderr: string;
-  }
-  export function spawnSync(
-    command: string,
-    args: string[],
-    options?: { cwd?: string; encoding?: string; env?: Record<string, string | undefined> },
-  ): SpawnSyncResult;
-}
-
-declare module 'node:os' {
-  export function tmpdir(): string;
-}
-
-/** Minimal surface of Bun's test runner used by this repo's tests. */
-declare module 'bun:test' {
-  export function describe(name: string, fn: () => void): void;
-  export function it(name: string, fn: () => void | Promise<void>): void;
-  export const test: typeof it;
-  export function expect(actual: unknown): {
-    toBe(expected: unknown): void;
-    toEqual(expected: unknown): void;
-    toContain(expected: unknown): void;
-    toMatch(pattern: RegExp): void;
-    toHaveLength(expected: number): void;
-    toBeGreaterThan(expected: number): void;
-    toBeUndefined(): void;
-  };
-}
-
-declare const process: {
-  env: Record<string, string | undefined>;
-  cwd(): string;
-  chdir(dir: string): void;
-  argv: string[];
-  platform: string;
-  execPath: string;
-  exitCode?: number;
-  exit(code?: number): never;
-};
-
-declare const console: {
-  log(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-};
-
-interface ImportMeta {
-  /** Absolute directory of the current module (Bun / bundler convention). */
-  readonly dir: string;
-  readonly url: string;
-}

package/src/hermes-identity.ts

@@ -1,4 +0,0 @@
-/** Collision-resistant sibling id for a generated Hermes command companion. */
-export function hermesCommandCompanionId(pluginId: string): string {
-  return `${pluginId}.plgnz-commands`;
-}

package/src/host.ts

@@ -1,131 +0,0 @@
-/**
- * The host contract (AGENTS.md: one module per host under `src/hosts/`,
- * implementing this interface; no host-specific branches outside its module).
- *
- * Split into `HostReader` and `HostWriter` so `doctor` is read-only *by
- * construction*: it takes `HostReader[]` and must never import a writer. A
- * module is evaluated whole, so each host's writer implements `HostWriter` in
- * a sibling `<host>-writer.ts` module — loading the reader must not load the
- * writer. test/doctor-imports.test.ts pins that split.
- */
-
-/** One MCP server as configured somewhere we can read it. */
-export interface McpServerEntry {
-  /** Server name as written in the config (`mcpServers` key / `[mcp_servers.<name>]`). */
-  name: string;
-  transport: 'stdio' | 'http';
-  /** Where the entry came from: host user-level config or an installed plugin. */
-  origin: 'user' | 'plugin';
-  /** `plugin@marketplace` (or bare plugin name) when origin is `plugin`. */
-  pluginId?: string;
-  /** Absolute path of the file the entry was read from. */
-  file: string;
-  /** Directory relative paths resolve against (plugin root, or the config's root). */
-  baseDir: string;
-  /** stdio: the executable token (spec §7.2.1: a single token, bare name or `./`-relative). */
-  command?: string;
-  /** stdio args. Never printed by doctor — args can carry credentials. */
-  args?: string[];
-  /** False when the host config explicitly disables the entry. */
-  enabled?: boolean;
-}
-
-/** One installed plugin in a host's native store. */
-export interface InstalledPlugin {
-  /** Host-native id: `plugin@marketplace` where the host tracks marketplaces, else the plugin name. */
-  id: string;
-  name: string;
-  marketplace?: string;
-  /** Install directory, when it exists on disk. */
-  path?: string;
-  /** Every host-native root whose bytes participate in this active install. */
-  contentRoots?: Record<string, string>;
-  version?: string;
-  /** Source sha the host itself recorded (claude-code `gitCommitSha`), if any. */
-  sha?: string;
-  enabled?: boolean;
-}
-
-export interface HostReader {
-  readonly id: string;
-  /**
-   * True when the host is launched by a macOS GUI app and therefore has no
-   * shell PATH — bare commands are suspect there (spec §7.2.1 makes PATH
-   * participation client-defined; plugins MUST NOT depend on it).
-   */
-  readonly gui: boolean;
-  /** Is this host present on this machine? */
-  detect(): boolean;
-  /** Store directories this host owns (for `targets`/reporting). */
-  stores(): string[];
-  /** Plugins installed in the host's native store. */
-  listInstalled(): InstalledPlugin[];
-  /** Every MCP server entry the host will consider: user-level config + each installed plugin. */
-  mcpEntries(): McpServerEntry[];
-}
-
-export interface AddOptions {
-  target?: string;
-  dryRun?: boolean;
-  /** Explicitly replace one selected, proven legacy native install. */
-  adoptExisting?: boolean;
-}
-
-export type InstallStatus = 'installed' | 'unchanged' | 'unsupported' | 'unverified' | 'failed';
-
-/** Generic mutation result; readers keep their host-native data shapes. */
-export interface InstallOutcome {
-  plugin: string;
-  target: string;
-  status: InstallStatus;
-  dryRun: boolean;
-  diagnostic?: string;
-  nativeId?: string;
-  action?: 'install' | 'update' | 'remove';
-}
-
-export interface PinOptions {
-  /** Report what would change without writing. */
-  dryRun?: boolean;
-  /** Restrict the pass to these server names (`update` re-applies recorded pins). */
-  only?: readonly string[];
-}
-
-/** One bare `command` rewritten to the absolute path it resolved to. */
-export interface PinChange {
-  server: string;
-  from: string;
-  to: string;
-  /** The file the rewrite was written to. */
-  file: string;
-}
-
-/** One bare `command` that did not resolve — left untouched, reported as ✗. */
-export interface PinRefusal {
-  server: string;
-  command: string;
-  file: string;
-}
-
-export interface PinOutcome {
-  changes: PinChange[];
-  refusals: PinRefusal[];
-}
-
-import type { PluginSource, ResolvedSource } from './source';
-
-export interface HostWriter extends HostReader {
-  /** Whether this writer implements explicit legacy adoption. */
-  readonly supportsAdoption?: boolean;
-  add(plugin: PluginSource, resolved: ResolvedSource, opts?: AddOptions): Promise<void | 'unchanged'>;
-  remove(id: string): Promise<void>;
-  /**
-   * Rewrite every *bare* stdio `command` in this plugin's installed copy to the
-   * absolute path it resolves to on this process's PATH, so a GUI host with no
-   * shell PATH can still launch it (spec §7.2.1: whether a configured PATH
-   * participates in bare-name resolution is client-defined; plugins MUST NOT
-   * depend on it). A command that does not resolve is left alone and returned
-   * in `refusals` — `pin` never guesses.
-   */
-  pin(plugin: InstalledPlugin, opts?: PinOptions): Promise<PinOutcome>;
-}