rovecode 0.3.2

package/src/market/manifest.ts

@@ -0,0 +1,187 @@
+/** Where an installed thing CAME FROM. The disk stays the source of truth for whether something is
+ *  installed — `installedState` looks for the folder or the config entry, so a skill deleted by hand stops
+ *  being installed the moment it is gone, which no record file could guarantee. This file carries only what
+ *  the disk cannot know: which catalog row it was, which source, which commit that resolved to, and when.
+ *
+ *  Three rules, each of which exists because the alternative reads as a bug to whoever hits it:
+ *   - A MISSING record is not an error. Anything installed before this file existed, or copied into place
+ *     by hand, has no record; `list` says its origin is unknown rather than pretending it is not installed.
+ *   - An EXTRA record is not an error either. A record whose thing is gone from disk is ignored, and the
+ *     next write drops it, so orphans cannot pile up.
+ *   - SECRETS never land here. A clone URL carrying a token (`https://user:token@host/repo.git`) is
+ *     scrubbed before it is written, and an MCP install records the PATH of its mcp.json, never the
+ *     contents — the file itself already keeps secrets out by writing `${NAME}`.
+ *
+ *  One file per scope: `~/.rovecode/installed.json` for user installs, `<cwd>/.rovecode/installed.json`
+ *  for the project's. The project one is committed with the repo, which is the other reason a token in a
+ *  URL would be a real leak rather than a tidiness problem. */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { MarketItem, MarketKind, MarketScope, MarketSource } from "./types.ts";
+
+export const MANIFEST_VERSION = 1;
+
+export interface InstallRecord {
+  kind: MarketKind;
+  id: string;
+  /** which shelf the row came from, so "curated" and "someone's git URL" are never confused */
+  source: MarketSource;
+  scope: MarketScope;
+  /** ISO-8601, UTC */
+  installedAt: string;
+  /** which surface wrote it. `mcp add` records too, but only when it installed a PACKAGE (install-once):
+   *  that record carries the integrity hash, and a plain config line still has nothing to record. */
+  installedBy: "market" | "mcp add";
+  /** where it landed: the folder, or the mcp.json that holds the entry */
+  target: string;
+  /** the catalog row's own version at the time, when it stated one */
+  catalogVersion?: string;
+  /** what landed on disk, hashed at install — see digest.ts. `--ref` pins what was ASKED for; this is
+   *  what arrived, and it is the part that can still be checked later. Absent for an MCP entry, which
+   *  is a line inside a shared file rather than a folder of its own. */
+  digest?: { algo: "sha256"; value: string; files: number };
+  /** for anything cloned: the URL as it was fetched (scrubbed) and the commit it resolved to */
+  git?: {
+    source: string; sha?: string; ref?: string;
+    /** which command produced the tree — so "was that ref a branch or a commit?" has an answer */
+    resolvedBy?: "branch" | "commit" | "default";
+  };
+  /** an MCP server installed ONCE as an npm package (mcp/local-package.ts) instead of `npx -y` at every
+   *  start: what npm put on disk. `integrity` is npm's hash for the tarball, from the lockfile; when the
+   *  lockfile could not supply it, `missing` says so in words rather than the field being silently absent.
+   *  This is the record an `npx` line never has — it runs whatever "latest" is and leaves nothing behind. */
+  package?: {
+    name: string;
+    version: string;
+    /** the shared prefix it was installed into (~/.rovecode/mcp) */
+    prefix: string;
+    /** the bin `node` launches, absolute */
+    bin: string;
+    integrity?: string;
+    resolved?: string;
+    /** what could not be recorded and why; absent when everything above is filled */
+    missing?: string[];
+  };
+}
+
+interface ManifestFile { version: number; installs: InstallRecord[] }
+
+export function manifestPath(scope: MarketScope, cwd: string, home: string): string {
+  return scope === "project" ? join(cwd, ".rovecode", "installed.json") : join(home, "installed.json");
+}
+
+/** A URL with its credentials removed. `https://someone:ghp_xxx@github.com/o/r.git` becomes
+ *  `https://github.com/o/r.git` — the record is about provenance, and a token is not provenance. */
+export function scrubUrl(url: string): string {
+  try {
+    const u = new URL(url);
+    if (u.username || u.password) { u.username = ""; u.password = ""; return u.toString(); }
+    return url;
+  } catch {
+    // not a URL (an ssh spec like git@host:owner/repo.git, or a local path): strip an inline
+    // `user:secret@` if one is there, and otherwise leave it alone
+    return url.replace(/^([a-z+]+:\/\/)?[^/@\s]*:[^/@\s]+@/i, "$1");
+  }
+}
+
+/** Read a scope's manifest. A missing, unreadable or malformed file is an EMPTY manifest, never a throw:
+ *  provenance is a nice-to-have and must not be able to stop an install. */
+export function readManifest(scope: MarketScope, cwd: string, home: string): InstallRecord[] {
+  const path = manifestPath(scope, cwd, home);
+  if (!existsSync(path)) return [];
+  try {
+    const json: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof json !== "object" || json === null) return [];
+    const installs = (json as ManifestFile).installs;
+    if (!Array.isArray(installs)) return [];
+    return installs.filter(isRecord);
+  } catch { return []; }
+}
+
+function isRecord(v: unknown): v is InstallRecord {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Partial<InstallRecord>;
+  return typeof r.id === "string" && (r.kind === "mcp" || r.kind === "skill" || r.kind === "plugin")
+    && (r.scope === "user" || r.scope === "project") && typeof r.target === "string";
+}
+
+const sameItem = (a: { kind: MarketKind; id: string }, b: { kind: MarketKind; id: string }): boolean =>
+  a.kind === b.kind && a.id === b.id;
+
+export interface WriteOptions {
+  cwd: string;
+  home: string;
+  /** which records still describe something on disk; orphans are dropped on every write */
+  stillInstalled?: (r: InstallRecord) => boolean;
+}
+
+function save(scope: MarketScope, records: InstallRecord[], opts: WriteOptions): void {
+  const path = manifestPath(scope, opts.cwd, opts.home);
+  const keep = opts.stillInstalled ? records.filter(opts.stillInstalled) : records;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ version: MANIFEST_VERSION, installs: keep }, null, 2) + "\n");
+  } catch { /* a read-only home must not fail an install that already succeeded */ }
+}
+
+/** Record one install, replacing any earlier record for the same kind+id in that scope. */
+export function recordInstall(record: InstallRecord, opts: WriteOptions): void {
+  const others = readManifest(record.scope, opts.cwd, opts.home).filter((r) => !sameItem(r, record));
+  save(record.scope, [...others, record], opts);
+}
+
+/** Drop the record for one item, if there is one. */
+export function forgetInstall(kind: MarketKind, id: string, scope: MarketScope, opts: WriteOptions): void {
+  const records = readManifest(scope, opts.cwd, opts.home);
+  const left = records.filter((r) => !sameItem(r, { kind, id }));
+  if (left.length !== records.length) save(scope, left, opts);
+}
+
+/** The record for one item, from whichever scope it is installed in. */
+export function recordFor(item: Pick<MarketItem, "kind" | "id">, scope: MarketScope, cwd: string, home: string): InstallRecord | undefined {
+  return readManifest(scope, cwd, home).find((r) => sameItem(r, item));
+}
+
+/** Build the record for an install that just happened. `sha` is filled by the caller when a clone
+ *  resolved one; nothing here invents it, because an unverified commit id is worse than no commit id. */
+export function buildRecord<T extends Pick<MarketItem, "kind" | "id" | "source" | "version">>(item: T, opts: {
+  scope: MarketScope; target: string; now?: () => Date;
+  digest?: { algo: "sha256"; value: string; files: number };
+  git?: { source: string; sha?: string; ref?: string; resolvedBy?: "branch" | "commit" | "default" };
+  package?: NonNullable<InstallRecord["package"]>;
+  installedBy?: InstallRecord["installedBy"];
+}): InstallRecord {
+  const record: InstallRecord = {
+    kind: item.kind, id: item.id, source: item.source, scope: opts.scope,
+    installedAt: (opts.now ? opts.now() : new Date()).toISOString(),
+    installedBy: opts.installedBy ?? "market", target: opts.target,
+  };
+  if (item.version !== undefined) record.catalogVersion = item.version;
+  if (opts.digest) record.digest = opts.digest;
+  if (opts.package) {
+    // `missing` is kept only when it says something: an empty list would read as "checked, nothing missing"
+    // to one reader and as noise to the next, and the absent field already means the former
+    const { missing, ...rest } = opts.package;
+    record.package = { ...rest, ...(missing !== undefined && missing.length > 0 ? { missing } : {}) };
+  }
+  if (opts.git) {
+    record.git = { source: scrubUrl(opts.git.source),
+      ...(opts.git.sha !== undefined ? { sha: opts.git.sha } : {}),
+      ...(opts.git.ref !== undefined ? { ref: opts.git.ref } : {}),
+      ...(opts.git.resolvedBy !== undefined ? { resolvedBy: opts.git.resolvedBy } : {}) };
+  }
+  return record;
+}
+
+/** One line about where something came from, for `market list`. Absent record → the honest sentence
+ *  rather than silence, because "installed, origin unknown" is a real and common state. */
+export function originLine(r: InstallRecord | undefined): string {
+  if (r === undefined) return "origin unknown — installed before rovecode kept a record, or by hand";
+  const when = r.installedAt.slice(0, 10);
+  if (r.git) {
+    const pin = r.git.ref !== undefined ? ` (${r.git.resolvedBy === "commit" ? "commit" : "branch/tag"} ${r.git.ref})` : "";
+    return `${r.git.source}${pin}${r.git.sha ? ` @ ${r.git.sha.slice(0, 12)}` : ""} · ${when}`;
+  }
+  return `${r.source} · ${when}`;
+}

package/src/market/prereq.ts

@@ -0,0 +1,145 @@
+/** Is the program this item needs actually on the machine?
+ *
+ *  The most common way an install "succeeds" and then does not work is that the launch line names a
+ *  program nobody has: `npx …` without Node, `uvx …` without uv, `docker run …` without Docker. Today the
+ *  only signal is prose in a description, which nobody reads at the moment it matters. This module turns
+ *  that into one line in the plan, BEFORE the yes.
+ *
+ *  Three rules, and each one is a decision not to do more:
+ *
+ *  - **It never runs anything.** A prerequisite check that executes the program it is checking is a
+ *    prerequisite check that can hang, prompt, or start a daemon. This looks the program up on PATH and
+ *    stops there.
+ *  - **It never compares versions.** "Needs node ≥ 20" reads well and is wrong often — a version probe
+ *    means running the thing, parsing whatever it prints, and being wrong about pre-releases and vendored
+ *    builds. A warning that lies once is a warning nobody reads again.
+ *  - **It never blocks.** The result is a line in the plan, not a gate. Plenty of people install the tool
+ *    after they install the thing that needs it, and refusing them would be worse than saying nothing.
+ *
+ *  A missing answer is `undefined`, not a false one: an item with nothing to check produces no line at all
+ *  rather than a reassuring tick that means nothing.
+ */
+
+import { existsSync } from "node:fs";
+import type { MarketItem } from "./types.ts";
+
+export interface Prereq {
+  /** the program a launch line would run: "npx", "uvx", "docker", "git" */
+  program: string;
+  found: boolean;
+  /** where it was found, when it was */
+  path?: string;
+  /** a one-line "how to get it" — only for the handful we can name honestly */
+  hint?: string;
+}
+
+/** Where to look and how, injectable so the tests do not depend on the machine running them. */
+export interface PrereqEnv {
+  PATH?: string;
+  /** Windows only: the extensions that make a name executable (`.COM;.EXE;.BAT;.CMD`) */
+  PATHEXT?: string;
+  /** defaults to the running platform; decides the PATH separator and whether PATHEXT applies */
+  windows?: boolean;
+  /** how existence is tested; the default is `existsSync` */
+  exists?: (p: string) => boolean;
+}
+
+/** Install advice only where we can give it without guessing. A program we cannot name a source for gets
+ *  no hint, and the plan says "not on PATH" and nothing more — which is honest and still useful. */
+const HINTS: Record<string, string> = {
+  npx: "comes with Node.js — nodejs.org",
+  npm: "comes with Node.js — nodejs.org",
+  node: "nodejs.org",
+  uvx: "pipx install uv — astral.sh/uv",
+  uv: "pipx install uv — astral.sh/uv",
+  docker: "docker.com/get-started",
+  git: "git-scm.com/downloads",
+  python: "python.org/downloads",
+  python3: "python.org/downloads",
+  deno: "deno.com",
+  bun: "bun.sh",
+};
+
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+/** Join with the separator the CHECKED platform uses, not the one we happen to be running on. `join()`
+ *  from node:path is bound to the host, so on Windows it turned `/usr/bin` + `docker` into
+ *  `\usr\bin\docker` — harmless in production, where the flag matches the host, but it made the injected
+ *  platform a half-truth and would have quietly broken any future cross-platform use. */
+const joinPath = (dir: string, name: string, windows: boolean): string => {
+  const sep = windows ? "\\" : "/";
+  return dir.endsWith("/") || dir.endsWith("\\") ? `${dir}${name}` : `${dir}${sep}${name}`;
+};
+
+/** Look one program up on PATH. No execution, no version, no shell. */
+export function checkPrereq(program: string, env: PrereqEnv = {}): Prereq {
+  const windows = env.windows ?? process.platform === "win32";
+  const exists = env.exists ?? existsSync;
+  const hint = HINTS[program.toLowerCase()];
+  const base: Prereq = { program, found: false, ...(hint ? { hint } : {}) };
+
+  // a launch line that names a path rather than a command is not a PATH question at all
+  if (program.includes("/") || program.includes("\\")) {
+    return exists(program) ? { ...base, found: true, path: program } : base;
+  }
+
+  const raw = env.PATH ?? process.env["PATH"] ?? "";
+  const dirs = raw.split(windows ? ";" : ":").map((d) => d.trim().replace(/^"|"$/g, "")).filter((d) => d !== "");
+  // On Windows a bare name is executable only with one of PATHEXT's extensions — `npx` on disk is
+  // `npx.cmd`, and looking for `npx` alone reports every Node install as missing.
+  const exts = windows
+    ? ["", ...(env.PATHEXT ?? process.env["PATHEXT"] ?? DEFAULT_PATHEXT).split(";").map((e) => e.trim()).filter((e) => e !== "")]
+    : [""];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = joinPath(dir, program + ext, windows);
+      if (exists(candidate)) return { ...base, found: true, path: candidate };
+    }
+  }
+  return base;
+}
+
+/** The program an item's install would run, or undefined when there is nothing to check.
+ *
+ *  MCP: a stdio entry already carries the exact command — `mcp/market.ts` resolved the registry's
+ *  `runtimeHint` (or the package type's default) into `command`, so nothing is re-derived here. An http
+ *  entry runs nothing locally and gets no line.
+ *
+ *  Skills and plugins: `git`, when and only when the source is a repository. This is NOT the case the
+ *  feature was proposed for, and it is the one that fires most: every row in both catalogs today is
+ *  git-sourced (19 of 19 skills, 3 of 3 plugins), so without git every install in the market fails after
+ *  the human has already said yes — which is exactly the failure this is here to move earlier. A skill
+ *  that ships its files in the catalog, or a plugin installed from a local folder, needs nothing.
+ */
+export function prereqOf(item: MarketItem, env?: PrereqEnv): Prereq | undefined {
+  const program = programFor(item);
+  return program === undefined ? undefined : checkPrereq(program, env);
+}
+
+function programFor(item: MarketItem): string | undefined {
+  const install = item.install;
+  switch (install.kind) {
+    case "mcp": {
+      const first = install.entry.installs?.[0];
+      // only the form that launches a process locally; a remote is a URL we connect to
+      return first !== undefined && first.kind === "stdio" ? first.command : undefined;
+    }
+    case "plugin":
+      return install.git ? "git" : undefined;
+    case "skill":
+      return install.source?.git !== undefined ? "git" : undefined;
+  }
+}
+
+/** The plan's line for a prerequisite, or undefined when there is none to draw.
+ *
+ *  Here rather than at the call site so both surfaces say the same thing, and so the wording stays with
+ *  the rules it describes: "not on PATH" is a statement about where we looked, not a claim that the
+ *  program is not installed — someone may have it somewhere PATH does not reach, and the sentence should
+ *  not tell them they are wrong. */
+export function prereqLine(p: Prereq | undefined): string | undefined {
+  if (p === undefined) return undefined;
+  if (p.found) return `${p.program} ✓`;
+  return `${p.program} — not on PATH${p.hint ? ` (install: ${p.hint})` : ""}`;
+}