@monster-orange/den 0.2.8 → 0.3.0

package/src/shared/plugins/store.ts

@@ -0,0 +1,358 @@
+/**
+ * Where a distribution's plugins live and how added ones are pinned (PL-1a,
+ * PL-2a).
+ *
+ *   plugins/<id>/        every plugin, local or added, committed
+ *   plugins.lock.json    one entry per added plugin: source, ref, commit,
+ *                        content hash, kinds, approved capabilities
+ *
+ * A plugins/<id>/ with no lock entry is local: the distribution's own,
+ * edited in place, of any kind. Being present is its approval. An added
+ * plugin was vendored by `plugin add` (or `theme add`), and `list` fails when
+ * its bytes differ from the lock.
+ */
+import { spawnSync } from "child_process";
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml } from "yaml";
+import { PROFILE_FILE } from "../profile.js";
+import { THEME_FILE, themeFiles } from "../theme/contract.js";
+import {
+  PLUGIN_FILE,
+  PLUGIN_ID,
+  themeDirIn,
+  type PluginValidation,
+} from "./manifest.js";
+
+export const LOCK_FILE = "plugins.lock.json";
+/** Where plugins live in the distribution. */
+export const PLUGINS_DIR = "plugins";
+
+export interface PluginSource {
+  /** What `git clone` takes. */
+  repo: string;
+  /** Directory of the plugin inside the repo ("" for the root). */
+  subpath: string;
+  ref: string;
+}
+
+/**
+ * `github.com/<owner>/<repo>[/<subpath>]@<ref>` (any host of that shape over
+ * https), or a full git URL with an optional `//<subpath>`:
+ * `https://git.example/x/themes.git//nightly@v1.0.0`,
+ * `git@github.com:o/r.git//nightly@v1.0.0`. The ref is required: a tag or a
+ * commit, never "latest".
+ */
+export function parsePluginSource(spec: string): PluginSource {
+  const at = spec.lastIndexOf("@");
+  // `git@host:` has its @ before the first colon; the ref's @ comes after.
+  if (at <= 0 || (spec.startsWith("git@") && at < spec.indexOf(":")))
+    throw new Error(
+      `${spec}: name an exact ref (a tag or a commit): <repo>[/<subpath>]@<ref>`,
+    );
+  const where = spec.slice(0, at);
+  const ref = spec.slice(at + 1);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$/.test(ref) || ref.includes(".."))
+    throw new Error(`${spec}: "${ref}" is not a usable git ref`);
+  const sub = where.indexOf("//", where.indexOf("://") + 3);
+  if (/^(https?:\/\/|ssh:\/\/|file:\/\/|git@)/.test(where)) {
+    const repo = sub === -1 ? where : where.slice(0, sub);
+    return {
+      repo,
+      subpath: sub === -1 ? "" : cleanSubpath(where.slice(sub + 2)),
+      ref,
+    };
+  }
+  const parts = where.split("/").filter(Boolean);
+  if (parts.length < 3 || !parts[0].includes("."))
+    throw new Error(
+      `${spec}: expected <host>/<owner>/<repo>[/<subpath>]@<ref>, or a git URL`,
+    );
+  const [host, owner, name, ...rest] = parts;
+  return {
+    repo: `https://${host}/${owner}/${name.replace(/\.git$/, "")}.git`,
+    subpath: cleanSubpath(rest.join("/")),
+    ref,
+  };
+}
+
+function cleanSubpath(p: string): string {
+  const s = p.replace(/^\/+|\/+$/g, "");
+  if (s.split("/").some((x) => x === ".." || x === "."))
+    throw new Error(`plugin subpath "${p}" may not contain . or ..`);
+  return s;
+}
+
+/** The lock's `source`: the repo, plus `//<subpath>` when there is one. */
+export function sourceString(src: PluginSource): string {
+  return src.subpath ? `${src.repo}//${src.subpath}` : src.repo;
+}
+
+/**
+ * Why `add` refuses a file:// source (PL-2a). A path on one machine must
+ * never reach a committed lock.
+ */
+export const FILE_SOURCE_HINT =
+  "for your own plugin, put it in plugins/<id>/ as a local plugin; to try a published one before tagging, push a branch and use --track";
+
+/**
+ * `<host>/<owner>` of a git URL, lowercased host, or null when it has no
+ * owner (a file:// path, a bare host).
+ */
+export function hostOwner(
+  repo: string,
+): { host: string; owner: string } | null {
+  const m =
+    /^(?:https?|ssh):\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/([^/]+)\//.exec(repo) ??
+    /^[^@\s]+@([^:]+):\/?([^/]+)\//.exec(repo);
+  return m ? { host: m[1].toLowerCase(), owner: m[2] } : null;
+}
+
+/**
+ * `plugins.allow` in the distribution's den.yml: the `<host>/<owner>` pairs
+ * `add` accepts (a bare `<host>` accepts every owner there). Null when it is
+ * absent: any host. Throws on a malformed value, so a typo can't open it up.
+ */
+export function readPluginsAllow(distRoot: string): string[] | null {
+  const file = path.join(distRoot, PROFILE_FILE);
+  if (!fs.existsSync(file)) return null;
+  const doc = parseYaml(fs.readFileSync(file, "utf-8")) as {
+    plugins?: { allow?: unknown };
+  } | null;
+  const allow = doc?.plugins?.allow;
+  if (allow === undefined || allow === null) return null;
+  if (
+    !Array.isArray(allow) ||
+    allow.some((a) => typeof a !== "string" || !/^[^/\s]+(\/[^/\s]+)?$/.test(a))
+  )
+    throw new Error(
+      `${PROFILE_FILE}: plugins.allow must be a list of <host>/<owner> (or <host>) strings`,
+    );
+  return (allow as string[]).map((a) => a.trim());
+}
+
+/** Whether `repo` is allowed by `allow` (null: everything is). */
+export function sourceAllowed(repo: string, allow: string[] | null): boolean {
+  if (!allow) return true;
+  const ho = hostOwner(repo);
+  if (!ho) return false;
+  return allow.some((a) => {
+    const [host, owner] = a.split("/");
+    return (
+      host.toLowerCase() === ho.host &&
+      (owner === undefined || owner.toLowerCase() === ho.owner.toLowerCase())
+    );
+  });
+}
+
+export interface LockEntry {
+  id: string;
+  name: string;
+  version: string;
+  source: string;
+  ref: string;
+  commit: string;
+  /** sha256 over the plugin's files, in path order (see pluginContent). */
+  sha256: string;
+  /** What the plugin provides, from its manifest; a theme is ["theme"]. */
+  kinds: string[];
+  /** Capabilities approved at add (PL-4). A theme requests none. */
+  approved_capabilities: string[];
+  /** Added with --track: `ref` is a branch, so a re-add may differ. */
+  tracking?: boolean;
+}
+
+/** Runs git; returns stdout, throws with stderr on failure. */
+export type GitRunner = (args: string[], cwd?: string) => string;
+
+export const defaultGit: GitRunner = (args, cwd) => {
+  const r = spawnSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  if (r.status !== 0)
+    throw new Error(`git ${args[0]} failed: ${(r.stderr || r.stdout).trim()}`);
+  return r.stdout.trim();
+};
+
+/**
+ * What `ref` names in the repo: a full commit SHA, a tag, a branch, or
+ * nothing. A tag wins over a branch of the same name.
+ */
+export function refKind(
+  git: GitRunner,
+  src: PluginSource,
+): "commit" | "tag" | "branch" | "none" {
+  if (/^[0-9a-f]{40}$/.test(src.ref)) return "commit";
+  const out = git([
+    "ls-remote",
+    "--tags",
+    "--heads",
+    src.repo,
+    `refs/tags/${src.ref}`,
+    `refs/heads/${src.ref}`,
+  ]);
+  if (out.includes(`refs/tags/${src.ref}`)) return "tag";
+  if (out.includes(`refs/heads/${src.ref}`)) return "branch";
+  return "none";
+}
+
+export function readLock(distRoot: string): Record<string, LockEntry> {
+  const file = path.join(distRoot, LOCK_FILE);
+  if (!fs.existsSync(file)) return {};
+  const raw = JSON.parse(fs.readFileSync(file, "utf-8")) as {
+    plugins?: Record<string, LockEntry>;
+  };
+  return raw.plugins ?? {};
+}
+
+export function writeLock(
+  distRoot: string,
+  plugins: Record<string, LockEntry>,
+): void {
+  const sorted = Object.fromEntries(
+    Object.entries(plugins).sort(([a], [b]) => a.localeCompare(b)),
+  );
+  const file = path.join(distRoot, LOCK_FILE);
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify({ plugins: sorted }, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * plugins/<id>/ in the distribution. The id is checked again here (the lock
+ * file is editable), so a delete can only ever reach that directory.
+ */
+export function pluginDirFor(distRoot: string, id: string): string {
+  if (!PLUGIN_ID.test(id)) throw new Error(`"${id}" is not a plugin id`);
+  return path.join(distRoot, PLUGINS_DIR, id);
+}
+
+/**
+ * Every directory in plugins/, sorted, whatever it holds (dot-dirs aside):
+ * each one is a plugin, so one without a manifest, or with a name that is
+ * not an id, is reported rather than skipped.
+ */
+export function pluginDirNames(distRoot: string): string[] {
+  const root = path.join(distRoot, PLUGINS_DIR);
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Symlinks directly in plugins/ (not dot-names). Never a plugin: list and
+ * validate report each one, so no entry under plugins/ goes unmentioned.
+ */
+export function pluginSymlinkNames(distRoot: string): string[] {
+  const root = path.join(distRoot, PLUGINS_DIR);
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isSymbolicLink() && !e.name.startsWith("."))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Every plugins/<id>/ that provides a theme (a den-theme.json, or a
+ * den-plugin.json with a theme entry), locked or local, sorted.
+ */
+export function installedThemeIds(distRoot: string): string[] {
+  return pluginDirNames(distRoot).filter(
+    (id) =>
+      PLUGIN_ID.test(id) &&
+      themeDirIn(path.join(distRoot, PLUGINS_DIR, id)) !== null,
+  );
+}
+
+/** LICENSE / OFL.txt files anywhere in the dir travel with it. */
+function licenseFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (rel: string): void => {
+    for (const e of fs.readdirSync(path.join(dir, rel), {
+      withFileTypes: true,
+    })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory() && !e.name.startsWith(".")) walk(r);
+      else if (/^(LICEN[CS]E|OFL|COPYING)(\.(txt|md))?$/i.test(e.name))
+        out.push(r);
+    }
+  };
+  walk("");
+  return out;
+}
+
+/** Every regular file under `dir`, relative, skipping dot-entries. */
+function allFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (rel: string): void => {
+    for (const e of fs.readdirSync(path.join(dir, rel), {
+      withFileTypes: true,
+    })) {
+      if (e.name.startsWith(".")) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  walk("");
+  return out;
+}
+
+/**
+ * The files a validated plugin consists of, sorted: what `add` vendors and
+ * the lock hashes. An implicit theme plugin is its manifest, the files it
+ * names and its license files (as theme add has always vendored, so existing
+ * lock hashes still match); a den-plugin.json plugin is every file in its
+ * directory but dot-files.
+ */
+export function pluginContent(dir: string, v: PluginValidation): string[] {
+  const p = v.plugin!;
+  const files =
+    p.implicit && p.theme
+      ? [THEME_FILE, ...themeFiles(p.theme), ...licenseFiles(dir)]
+      : [PLUGIN_FILE, ...allFiles(dir)];
+  return files.filter((f, i, a) => a.indexOf(f) === i).sort();
+}
+
+export function hashFiles(dir: string, files: string[]): string {
+  const h = createHash("sha256");
+  for (const f of files) {
+    h.update(`${f}\0`);
+    h.update(fs.readFileSync(path.join(dir, f)));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+/**
+ * Files under `dir` that git has not committed as they are: untracked
+ * (ignored ones too, since Den loads them all the same), modified or staged.
+ * Null when `dir` is not in a git work tree: Den can't say, so it says
+ * nothing.
+ */
+export function uncommittedFiles(dir: string): string[] | null {
+  const r = spawnSync(
+    "git",
+    [
+      "status",
+      "--porcelain=v1",
+      "--untracked-files=all",
+      "--ignored=matching",
+      "--",
+      ".",
+    ],
+    { cwd: dir, encoding: "utf-8" },
+  );
+  if (r.status !== 0) return null;
+  return r.stdout
+    .split("\n")
+    .filter((l) => l.length > 3)
+    .map((l) => l.slice(3).replace(/^"|"$/g, ""));
+}

package/src/shared/process/legacy-adopt.ts

@@ -0,0 +1,285 @@
+/**
+ * Records from before 0.3.0-dev.37 (0.3.0-dev.38, a consumer's dev.37
+ * finding). A daemon record written before `up` recorded process groups has
+ * no pgid, and often no pid either, while the service it describes may still
+ * be running (a vite on its strict port). `up` and `down` decide what such a
+ * record means through adoptLegacyProcess, once:
+ *
+ *   1. port first: when the service has a known port (servicePort), the
+ *      process listening on it, if its cwd is inside the record's repoPath,
+ *      is the service. Den adopts its process group: the listener's pgid
+ *      and the group leader's start time (the listener's own when the
+ *      leader has gone).
+ *   2. else a recorded pid that is alive, when every token of the
+ *      configured up command (leading VAR=value assignments and an `npx` /
+ *      `npm exec` prefix stripped) appears in the argv of some process in
+ *      that pid's group: adopted the same way.
+ *   3. else the record is stale: nothing is signalled. A listener on the
+ *      port from outside repoPath is reported (`busy`), never touched.
+ *
+ * Nothing here signals a process. `ps` and `lsof` run under LC_ALL=C.
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import type { RecordedProcessGroup } from "./process-group.js";
+
+const C_ENV = { ...process.env, LC_ALL: "C", LANG: "C" };
+
+function run(cmd: string, args: string[]): string | null {
+  try {
+    return execFileSync(cmd, args, {
+      env: C_ENV,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+  } catch (e) {
+    // lsof and ps exit 1 when nothing matches; what they printed still counts.
+    const out = (e as { stdout?: unknown }).stdout;
+    return typeof out === "string" ? out : null;
+  }
+}
+
+/** The host tools, injectable for tests of the decision alone. */
+export interface LegacyProbe {
+  /** Pids listening on TCP `port`. */
+  listeners(port: number): number[];
+  /** A process's cwd, or null. */
+  cwd(pid: number): string | null;
+  /** Every live process: pid, pgid, start time, argv (one line). */
+  processes(): ProcRow[];
+}
+
+export interface ProcRow {
+  pid: number;
+  pgid: number;
+  lstart: string;
+  command: string;
+}
+
+export const hostProbe: LegacyProbe = {
+  listeners(port) {
+    const out = run("lsof", ["-nP", `-tiTCP:${port}`, "-sTCP:LISTEN"]) ?? "";
+    return out
+      .split("\n")
+      .map((l) => Number(l.trim()))
+      .filter((n) => Number.isInteger(n) && n > 0);
+  },
+  cwd(pid) {
+    const out = run("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]);
+    const line = out?.split("\n").find((l) => l.startsWith("n"));
+    return line ? line.slice(1) : null;
+  },
+  processes() {
+    // lstart is five words in the C locale: "Thu Nov  5 10:00:00 2026".
+    const out = run("ps", ["-A", "-o", "pid=,pgid=,stat=,lstart=,command="]);
+    const rows: ProcRow[] = [];
+    for (const line of (out ?? "").split("\n")) {
+      const m = line
+        .trim()
+        .match(
+          /^(\d+)\s+(\d+)\s+(\S+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.*)$/,
+        );
+      if (!m || m[3].startsWith("Z")) continue;
+      rows.push({
+        pid: Number(m[1]),
+        pgid: Number(m[2]),
+        lstart: m[4].replace(/\s+/g, " "),
+        command: m[5],
+      });
+    }
+    return rows;
+  },
+};
+
+/** A shell command's words, quotes removed (enough to compare, not to run). */
+export function shellWords(cmd: string): string[] {
+  const words: string[] = [];
+  const re = /"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(cmd))) words.push(m[1] ?? m[2] ?? m[3]);
+  return words;
+}
+
+const ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/**
+ * The tokens a running up must show: the up command's words without the
+ * leading VAR=value assignments and an `npx` / `npm exec` prefix (npm runs
+ * the binary under its own name, `node …/.bin/vite`).
+ */
+export function upTokens(upCommand: string): string[] {
+  const words = shellWords(upCommand);
+  let i = 0;
+  while (i < words.length && ASSIGN.test(words[i])) i++;
+  if (words[i] === "npx") {
+    i++;
+    // npx's own flags (`npx --yes vite`) are npx's, not the service's.
+    while (i < words.length && words[i].startsWith("-")) i++;
+  } else if (words[i] === "npm" && words[i + 1] === "exec") i += 2;
+  return words.slice(i);
+}
+
+/** Whether `token` is one of the argv words of `command` (or its basename). */
+function inArgv(token: string, command: string): boolean {
+  if (/\s/.test(token)) return command.includes(token);
+  return shellWords(command).some(
+    (w) => w === token || w.endsWith(`/${token}`) || w === `--${token}`,
+  );
+}
+
+/**
+ * A service's known port, the first found of: an explicit `port`, the port
+ * in its health URL (localhost or 127.0.0.1 forms), a `--port N`,
+ * `--port=N` or `-p N` in its up command.
+ */
+export function servicePort(svc: {
+  port?: unknown;
+  healthUrl?: string | null;
+  upCommand?: string | null;
+}): number | null {
+  const ok = (n: number): number | null =>
+    Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+  if (svc.port !== undefined && svc.port !== null) {
+    const p = ok(Number(svc.port));
+    if (p) return p;
+  }
+  if (svc.healthUrl) {
+    try {
+      const u = new URL(svc.healthUrl);
+      if (u.port) {
+        const p = ok(Number(u.port));
+        if (p) return p;
+      }
+    } catch {
+      /* not a URL */
+    }
+  }
+  const words = shellWords(svc.upCommand ?? "");
+  for (let i = 0; i < words.length; i++) {
+    const eq = words[i].match(/^--port=(\d+)$/);
+    if (eq) return ok(Number(eq[1]));
+    if ((words[i] === "--port" || words[i] === "-p") && words[i + 1]) {
+      const p = ok(Number(words[i + 1]));
+      if (p) return p;
+    }
+  }
+  return null;
+}
+
+function realOrSelf(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+function inside(dir: string, root: string): boolean {
+  const d = realOrSelf(dir);
+  const r = realOrSelf(root);
+  return d === r || d.startsWith(r.endsWith(path.sep) ? r : r + path.sep);
+}
+
+export type LegacyVerdict =
+  | {
+      kind: "adopted";
+      group: RecordedProcessGroup;
+      /** The listener (port) or the recorded pid. */
+      pid: number;
+      port: number | null;
+    }
+  | {
+      kind: "stale";
+      /** A listener on the port Den won't adopt: left alone. */
+      busy?: LegacyBusy;
+    };
+
+/**
+ * A listener on the service's port that is not adopted: its cwd is outside
+ * repoPath ("outside"), or it is in the repo but in Den's own process group
+ * ("own-group": stopping that group would stop Den) or in init's ("init").
+ */
+export interface LegacyBusy {
+  port: number;
+  pid: number;
+  cwd: string | null;
+  reason: "outside" | "own-group" | "init";
+}
+
+/** Why a busy port's listener is not `address`, for a warning line. */
+export function busyListenerText(
+  busy: LegacyBusy,
+  repoPath: string,
+  address: string,
+): string {
+  const head =
+    `port ${busy.port} is in use by pid ${busy.pid}` +
+    (busy.cwd ? ` (cwd ${busy.cwd})` : "");
+  if (busy.reason === "own-group")
+    return `${head}, in Den's own process group; not adopted`;
+  if (busy.reason === "init")
+    return `${head}, in process group 1 (init); not adopted`;
+  return `${head}, outside ${repoPath}: not ${address}, left alone`;
+}
+
+/** The group of `member`, as `down` records one: leader's start, else its own. */
+function groupOf(
+  member: ProcRow,
+  rows: ProcRow[],
+): RecordedProcessGroup | null {
+  // Never adopt Den's own group or init's.
+  if (member.pgid <= 1) return null;
+  const own = rows.find((r) => r.pid === process.pid);
+  if (own && own.pgid === member.pgid) return null;
+  const leader = rows.find((r) => r.pid === member.pgid);
+  if (!leader) {
+    // The leader is gone: the group is recorded by the member that leads it
+    // now in the record's sense (classifyGroup accepts any live member).
+    return { pgid: member.pgid, startedAt: member.lstart };
+  }
+  return { pgid: member.pgid, startedAt: leader.lstart };
+}
+
+export function adoptLegacyProcess(
+  rec: {
+    repoPath: string;
+    pid?: number;
+    port: number | null;
+    upCommand: string | null;
+  },
+  probe: LegacyProbe = hostProbe,
+): LegacyVerdict {
+  let rows: ProcRow[] | null = null;
+  const procs = (): ProcRow[] => (rows ??= probe.processes());
+  let busy: LegacyBusy | undefined;
+
+  if (rec.port) {
+    for (const pid of probe.listeners(rec.port)) {
+      const cwd = probe.cwd(pid);
+      const row = procs().find((r) => r.pid === pid);
+      let reason: LegacyBusy["reason"] = "outside";
+      if (cwd && row && inside(cwd, rec.repoPath)) {
+        const group = groupOf(row, procs());
+        if (group) return { kind: "adopted", group, pid, port: rec.port };
+        reason = row.pgid <= 1 ? "init" : "own-group";
+      }
+      busy ??= { port: rec.port, pid, cwd, reason };
+    }
+  }
+
+  if (typeof rec.pid === "number" && rec.pid > 0 && rec.upCommand) {
+    const row = procs().find((r) => r.pid === rec.pid);
+    const tokens = upTokens(rec.upCommand);
+    if (row && tokens.length) {
+      const members = procs().filter((r) => r.pgid === row.pgid);
+      if (tokens.every((t) => members.some((m) => inArgv(t, m.command)))) {
+        const group = groupOf(row, procs());
+        if (group) return { kind: "adopted", group, pid: row.pid, port: null };
+      }
+    }
+  }
+
+  return busy ? { kind: "stale", busy } : { kind: "stale" };
+}