@antelopejs/dms 0.15.1 → 0.16.0

package/bin/control/renderer.test.mjs

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import {
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+import { withBaseBackend } from "./base.mjs";
+import { targetOf } from "./commands-stack.mjs";
+import { git } from "./git.mjs";
+import { resolveRenderer } from "./renderer.mjs";
+import { decodeSkillConfig } from "./verify/decode.mjs";
+import { upArguments } from "./verify/seeded.mjs";
+import { cliPaths, layOutCopy } from "./stack.mjs";
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @returns {string} A real scratch folder removed when the test ends
+ */
+function scratch(t) {
+  const dir = realpathSync(
+    mkdtempSync(join(tmpdir(), "dms-control-renderer-test-")),
+  );
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/**
+ * @param {string} folder The package folder
+ * @param {string} name Its name
+ * @returns {string} The folder
+ */
+function writePackage(folder, name) {
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, "package.json"), JSON.stringify({ name }));
+  return folder;
+}
+
+/**
+ * @param {string} folder The renderer checkout
+ * @returns {string} The folder
+ */
+function builtRenderer(folder) {
+  writePackage(folder, "@antelopejs/dms-frontend");
+  mkdirSync(join(folder, "dist"), { recursive: true });
+  writeFileSync(join(folder, "dist", "index.js"), "");
+  return folder;
+}
+
+/**
+ * A checkout whose playground has installed modules: core, a published
+ * dms-frontend and one other package.
+ *
+ * @param {string} root The scratch folder
+ * @returns {{ checkout: string, playground: string, modules: string }} Its paths
+ */
+function checkoutWithPlayground(root) {
+  const checkout = join(root, "dms");
+  const playground = join(checkout, "playground");
+  const modules = join(playground, "node_modules");
+  mkdirSync(playground, { recursive: true });
+  writeFileSync(join(playground, "antelope.config.ts"), "");
+  writePackage(join(modules, "@antelopejs", "core"), "@antelopejs/core");
+  writePackage(
+    join(modules, "@antelopejs", "dms-frontend"),
+    "@antelopejs/dms-frontend",
+  );
+  writePackage(join(modules, "zod"), "zod");
+  return { checkout, playground, modules };
+}
+
+await test("--renderer takes a built dms-frontend checkout as an absolute folder", (t) => {
+  const folder = builtRenderer(join(scratch(t), "dms-frontend"));
+  assert.equal(resolveRenderer(folder), folder);
+});
+
+await test("--renderer refuses a folder without a package.json", (t) => {
+  assert.throws(() => resolveRenderer(scratch(t)), /has no package\.json/);
+});
+
+await test("--renderer refuses a package that is not dms-frontend", (t) => {
+  const folder = writePackage(join(scratch(t), "other"), "@antelopejs/dms");
+  assert.throws(
+    () => resolveRenderer(folder),
+    /is @antelopejs\/dms, not @antelopejs\/dms-frontend/,
+  );
+});
+
+await test("--renderer refuses a checkout that is not built", (t) => {
+  const folder = writePackage(
+    join(scratch(t), "dms-frontend"),
+    "@antelopejs/dms-frontend",
+  );
+  assert.throws(() => resolveRenderer(folder), /has no dist.index\.js/);
+});
+
+await test("the run's playground resolves dms-frontend to the renderer and everything else to the playground's modules", (t) => {
+  const root = scratch(t);
+  const { checkout, playground, modules } = checkoutWithPlayground(root);
+  const renderer = builtRenderer(join(root, "dms-frontend"));
+  const copy = layOutCopy(playground, checkout, join(root, "run"), renderer);
+  const linked = join(copy, "node_modules");
+  assert.equal(
+    realpathSync(join(linked, "@antelopejs", "dms-frontend")),
+    renderer,
+  );
+  assert.equal(
+    realpathSync(join(linked, "@antelopejs", "core")),
+    realpathSync(join(modules, "@antelopejs", "core")),
+  );
+  assert.equal(
+    realpathSync(join(linked, "zod")),
+    realpathSync(join(modules, "zod")),
+  );
+});
+
+await test("linking a renderer leaves the playground's own modules alone", (t) => {
+  const root = scratch(t);
+  const { checkout, playground, modules } = checkoutWithPlayground(root);
+  const published = realpathSync(join(modules, "@antelopejs", "dms-frontend"));
+  layOutCopy(
+    playground,
+    checkout,
+    join(root, "run"),
+    builtRenderer(join(root, "dms-frontend")),
+  );
+  assert.equal(
+    realpathSync(join(modules, "@antelopejs", "dms-frontend")),
+    published,
+  );
+});
+
+await test("a playground that installs no @antelopejs scope still gets the renderer", (t) => {
+  const root = scratch(t);
+  const { checkout, playground, modules } = checkoutWithPlayground(root);
+  rmSync(join(modules, "@antelopejs"), { recursive: true });
+  const renderer = builtRenderer(join(root, "dms-frontend"));
+  const copy = layOutCopy(playground, checkout, join(root, "run"), renderer);
+  assert.equal(
+    realpathSync(join(copy, "node_modules", "@antelopejs", "dms-frontend")),
+    renderer,
+  );
+});
+
+await test("without a renderer the run's node_modules is the playground's", (t) => {
+  const root = scratch(t);
+  const { checkout, playground, modules } = checkoutWithPlayground(root);
+  const copy = layOutCopy(playground, checkout, join(root, "run"));
+  const linked = join(copy, "node_modules");
+  assert.equal(lstatSync(linked).isSymbolicLink(), true);
+  assert.equal(realpathSync(linked), realpathSync(modules));
+});
+
+await test("the dashboard CLI is the renderer's build, the backend CLI stays the playground's core", (t) => {
+  const root = scratch(t);
+  const { playground } = checkoutWithPlayground(root);
+  const renderer = builtRenderer(join(root, "dms-frontend"));
+  const published = cliPaths(playground);
+  const served = cliPaths(playground, renderer);
+  assert.equal(served.dms, join(renderer, "dist", "index.js"));
+  assert.notEqual(published.dms, served.dms);
+  assert.equal(served.ajs, published.ajs);
+});
+
+/**
+ * @param {string} root The scratch folder
+ * @param {string} config The text after `export default` in `verify.config.ts`
+ * @returns {string} The checkout holding a verification skill with that config
+ */
+function checkoutWithSkill(root, config) {
+  const checkout = join(root, "dms-frontend");
+  const skill = join(checkout, ".agents", "skills", "verify-dms-frontend");
+  mkdirSync(skill, { recursive: true });
+  writeFileSync(join(skill, "verify.config.ts"), `export default ${config};\n`);
+  git(["init", "--quiet"], checkout);
+  git(["add", "."], checkout);
+  git(
+    [
+      "-c",
+      "user.name=t",
+      "-c",
+      "user.email=t@example.com",
+      "commit",
+      "--quiet",
+      "-m",
+      "skill",
+    ],
+    checkout,
+  );
+  return checkout;
+}
+
+const EMPTY_CONFIG = `prepare: [], userFacing: [], smoke: "", smokeJourney: "", doors: {}, formal: []`;
+
+await test("up takes the playground and the renderer from the skill's config, relative ones from its repository", async (t) => {
+  const root = scratch(t);
+  const checkout = checkoutWithSkill(
+    root,
+    `{ playground: "/dms/playground", renderer: ".", ${EMPTY_CONFIG} }`,
+  );
+  assert.deepEqual(await targetOf({}, checkout), {
+    playground: "/dms/playground",
+    renderer: checkout,
+  });
+});
+
+await test("--renderer and --playground win over the skill's config", async (t) => {
+  const checkout = checkoutWithSkill(
+    scratch(t),
+    `{ playground: "/dms/playground", renderer: ".", ${EMPTY_CONFIG} }`,
+  );
+  assert.deepEqual(
+    await targetOf(
+      { playground: "/other/playground", renderer: "/other/ui" },
+      checkout,
+    ),
+    { playground: "/other/playground", renderer: "/other/ui" },
+  );
+});
+
+await test("a skill without a renderer serves the published one", async (t) => {
+  const checkout = checkoutWithSkill(
+    scratch(t),
+    `{ playground: "packages/dms/playground", ${EMPTY_CONFIG} }`,
+  );
+  assert.deepEqual(await targetOf({}, checkout), {
+    playground: resolve(checkout, "packages/dms/playground"),
+    renderer: undefined,
+  });
+});
+
+const CONFIG = {
+  playground: "p",
+  prepare: [],
+  userFacing: [],
+  smoke: "",
+  smokeJourney: "",
+  doors: {},
+  formal: [],
+};
+
+await test("a skill config keeps its renderer, and refuses one that is not a path", () => {
+  assert.equal(
+    decodeSkillConfig({ ...CONFIG, renderer: "." }, "verify.config.ts")
+      .renderer,
+    ".",
+  );
+  assert.equal(
+    decodeSkillConfig(CONFIG, "verify.config.ts").renderer,
+    undefined,
+  );
+  assert.throws(
+    () => decodeSkillConfig({ ...CONFIG, renderer: 3 }, "verify.config.ts"),
+    /verify\.config\.ts/,
+  );
+});
+
+await test("a run with a renderer has no base backend", async () => {
+  await assert.rejects(
+    withBaseBackend({ renderer: "/ui" }, {}, async () => {}),
+    /no base backend/,
+  );
+});
+
+/**
+ * @param {Partial<import("./verify/skill.mjs").SkillConfig>} config What differs from a skill with a playground in its repository
+ * @returns {import("./verify/skill.mjs").Skill} The skill
+ */
+function skillWith(config) {
+  return {
+    dir: "/repo/.agents/skills/verify-x",
+    name: "verify-x",
+    repo: "/repo",
+    config: { ...decodeSkillConfig(CONFIG, "verify.config.ts"), ...config },
+    featuresDir: "",
+    journeysDir: "",
+    seededBreaksDir: "",
+    seededDoorsDir: "",
+  };
+}
+
+await test("seeded starts each run on the worktree's renderer and an external playground as it is", () => {
+  const prepared = {
+    worktree: "/work/seeded-auth-1",
+    skill: "/work/seeded-auth-1/skill",
+  };
+  assert.deepEqual(
+    upArguments(
+      skillWith({ playground: "/dms/playground", renderer: "." }),
+      prepared,
+    ),
+    [
+      "up",
+      "--playground",
+      "/dms/playground",
+      "--renderer",
+      "/work/seeded-auth-1",
+      "--skill",
+      "/work/seeded-auth-1/skill",
+    ],
+  );
+});
+
+await test("seeded without a renderer starts the worktree's own playground", () => {
+  const prepared = {
+    worktree: "/work/seeded-auth-1",
+    skill: "/work/seeded-auth-1/skill",
+  };
+  assert.deepEqual(
+    upArguments(skillWith({ playground: "packages/dms/playground" }), prepared),
+    [
+      "up",
+      "--playground",
+      "/work/seeded-auth-1/packages/dms/playground",
+      "--skill",
+      "/work/seeded-auth-1/skill",
+    ],
+  );
+});

package/bin/control/run-state.mjs

@@ -2,11 +2,29 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import {
+  arrayOf,
+  decode,
+  either,
+  isBoolean,
+  isNumber,
+  isString,
+  nullable,
+  objectOf,
+  recordOf,
+} from "./json.mjs";
 
 const RUN_FILE = "run.json";
 const ID_BYTES = 3;
 const TIMESTAMP_LENGTH = 15;
 
+/**
+ * @typedef {{ name: string, pid: number, command: string, cwd: string, log: string, startedAt: string, port?: number }} ProcessRecord
+ * @typedef {ProcessRecord & { port: number }} ServerRecord
+ * @typedef {{ email: string, password: string, userId?: string | null }} Account
+ * @typedef {{ dir: string, root: string, home: string, logs: string, mongo: string, browser?: ServerRecord, evidence: string, cache: string, id: string, createdAt: string, environment: string, playground: string, moduleRoot: string, repo: string | null, headSha: string | null, renderer?: string, baseRef: string, skill: string | null, apiPort: number, webPort: number, smtpPort: number, mail: string, apiUrl: string, webUrl: string, databasePrefix: string, database: string, mongoUrl: string, ownsMongo: boolean, secrets: Record<string, string>, adminPassword: string, extraEnv: Record<string, string>, processes: ProcessRecord[], accounts: Record<string, Account>, tokens: Record<string, string>, ready: boolean, error?: string, runPlayground?: string, baseRoot?: string, resetCount?: number, journeyCount?: number }} RunState
+ */
+
 /**
  * Where runs are created: `--runs`, else `DMS_CONTROL_RUNS`, else
  * `<tmpdir>/dms-control`. A run holds a playground copy and its frontend
@@ -39,7 +57,7 @@ export function newRunId() {
  * The folders of a run, all under its root.
  *
  * @param {string} dir The run root
- * @returns {{ dir: string, root: string, home: string, logs: string, mongo: string, browser: string, evidence: string, cache: string }} The run's folders
+ * @returns {{ dir: string, root: string, home: string, logs: string, mongo: string, evidence: string, cache: string }} The run's folders
  */
 export function runPaths(dir) {
   return {
@@ -48,7 +66,6 @@ export function runPaths(dir) {
     home: join(dir, "home"),
     logs: join(dir, "logs"),
     mongo: join(dir, "mongo"),
-    browser: join(dir, "browser"),
     evidence: join(dir, "evidence"),
     cache: join(dir, "cache"),
   };
@@ -80,10 +97,93 @@ export function createRunFolders(dir) {
 }
 
 /**
- * Reads the state `up` recorded for a run.
+ * @typedef {Omit<RunState, "browser" | "accounts"> & { browser?: string | ServerRecord, accounts: Record<string, Omit<Account, "password"> & { password?: string }> }} StoredRunState The state as a file may hold it. A run saved by an earlier release holds the browser's folder in `browser` until the browser starts, and `down` leaves an account without its `password`.
+ */
+
+const isStrings = recordOf(isString);
+
+const isProcessRecord = objectOf(
+  {
+    name: isString,
+    pid: isNumber,
+    command: isString,
+    cwd: isString,
+    log: isString,
+    startedAt: isString,
+  },
+  { port: isNumber },
+);
+
+const isServerRecord = objectOf({
+  name: isString,
+  pid: isNumber,
+  command: isString,
+  cwd: isString,
+  log: isString,
+  startedAt: isString,
+  port: isNumber,
+});
+
+const isAccount = objectOf(
+  { email: isString },
+  { password: isString, userId: nullable(isString) },
+);
+
+/** @type {import("./json.mjs").Guard<StoredRunState>} The state as `run.json` holds it. Keys it does not check are kept, so saving a loaded run writes them back. */
+const isStoredRun = objectOf(
+  {
+    dir: isString,
+    root: isString,
+    home: isString,
+    logs: isString,
+    mongo: isString,
+    evidence: isString,
+    cache: isString,
+    id: isString,
+    createdAt: isString,
+    environment: isString,
+    playground: isString,
+    moduleRoot: isString,
+    repo: nullable(isString),
+    headSha: nullable(isString),
+    baseRef: isString,
+    skill: nullable(isString),
+    apiPort: isNumber,
+    webPort: isNumber,
+    smtpPort: isNumber,
+    mail: isString,
+    apiUrl: isString,
+    webUrl: isString,
+    databasePrefix: isString,
+    database: isString,
+    mongoUrl: isString,
+    ownsMongo: isBoolean,
+    secrets: isStrings,
+    adminPassword: isString,
+    extraEnv: isStrings,
+    processes: arrayOf(isProcessRecord),
+    accounts: recordOf(isAccount),
+    tokens: isStrings,
+    ready: isBoolean,
+  },
+  {
+    browser: either(isString, isServerRecord),
+    error: isString,
+    renderer: isString,
+    runPlayground: isString,
+    baseRoot: isString,
+    resetCount: isNumber,
+    journeyCount: isNumber,
+  },
+);
+
+/**
+ * Reads the state `up` recorded for a run. A folder an earlier release stored
+ * in `browser` is dropped, since nothing creates or reads that folder. An
+ * account that `down` left without its `password` reads with an empty one.
  *
  * @param {string} dir The run root, as `up` printed it
- * @returns {Record<string, any>} The run state
+ * @returns {RunState} The run state
  * @throws When the folder holds no run.json
  */
 export function loadRun(dir) {
@@ -93,14 +193,27 @@ export function loadRun(dir) {
       `No run at ${dir}: run.json is missing. Start one with dms-control up.`,
     );
   }
-  return JSON.parse(readFileSync(file, "utf8"));
+  /** @type {unknown} */
+  const parsed = JSON.parse(readFileSync(file, "utf8"));
+  const stored = decode(isStoredRun, parsed, file, "a run state");
+  const { browser, accounts, ...rest } = stored;
+  const run = {
+    ...rest,
+    accounts: Object.fromEntries(
+      Object.entries(accounts).map(([name, account]) => [
+        name,
+        { ...account, password: account.password ?? "" },
+      ]),
+    ),
+  };
+  return browser === undefined || isString(browser) ? run : { ...run, browser };
 }
 
 /**
  * Writes the run state, readable by its owner only since it holds the run's
  * secrets and the admin password.
  *
- * @param {Record<string, any>} state The run state
+ * @param {RunState} state The run state
  */
 export function saveRun(state) {
   writeFileSync(

package/bin/control/run-state.test.mjs

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createRunFolders, loadRun, saveRun } from "./run-state.mjs";
+import { down } from "./stack.mjs";
+
+const SERVER = {
+  name: "browser",
+  pid: 4242,
+  command: "node serve",
+  cwd: "/run",
+  log: "/run/logs/browser.log",
+  startedAt: "2026-10-31T00:00:00.000Z",
+  port: 40123,
+};
+
+const RUN = {
+  root: "/run/root",
+  home: "/run/home",
+  logs: "/run/logs",
+  mongo: "/run/mongo",
+  evidence: "/run/evidence",
+  cache: "/run/cache",
+  id: "20261031T000000-abc123",
+  createdAt: "2026-10-31T00:00:00.000Z",
+  environment: "verify",
+  playground: "/repo/playground",
+  moduleRoot: "/repo",
+  repo: "/repo",
+  headSha: null,
+  baseRef: "origin/main",
+  skill: null,
+  apiPort: 5010,
+  webPort: 5011,
+  smtpPort: 5012,
+  mail: "/run/evidence/mail",
+  apiUrl: "http://127.0.0.1:5010",
+  webUrl: "http://127.0.0.1:5011",
+  databasePrefix: "verify_x",
+  database: "verify_x",
+  mongoUrl: "",
+  ownsMongo: true,
+  secrets: { JWT: "s" },
+  adminPassword: "pw",
+  extraEnv: {},
+  processes: [],
+  accounts: { admin: { email: "a@example.com", password: "pw" } },
+  tokens: {},
+  ready: false,
+};
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {Record<string, unknown>} fields What the saved file holds besides `dir` and the fields every run has
+ * @returns {string} The run folder
+ */
+function savedRun(t, fields) {
+  const dir = mkdtempSync(join(tmpdir(), "dms-control-run-state-test-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "run.json"),
+    JSON.stringify({ ...RUN, dir, ...fields }),
+  );
+  return dir;
+}
+
+await test("a run saved by an earlier release drops the browser folder it held in `browser`", (t) => {
+  const dir = savedRun(t, { browser: "/runs/old/browser" });
+  const state = loadRun(dir);
+  assert.equal("browser" in state, false);
+});
+
+await test("a run saved by an earlier release keeps its server record once the browser started", (t) => {
+  const dir = savedRun(t, { browser: SERVER });
+  assert.deepEqual(loadRun(dir).browser, SERVER);
+});
+
+await test("a run without a browser reads back without one", (t) => {
+  const dir = savedRun(t, {});
+  assert.equal("browser" in loadRun(dir), false);
+});
+
+await test("saving a loaded run again keeps its server record", (t) => {
+  const dir = savedRun(t, { browser: SERVER });
+  const state = loadRun(dir);
+  saveRun(state);
+  assert.deepEqual(loadRun(dir), state);
+});
+
+await test("a run.json that holds no run is refused", (t) => {
+  for (const text of ["null", "[]", "5", '"s"', "{}"]) {
+    const dir = mkdtempSync(join(tmpdir(), "dms-control-run-state-test-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    writeFileSync(join(dir, "run.json"), text);
+    assert.throws(
+      () => loadRun(dir),
+      /run\.json is malformed: expected a run state/,
+    );
+  }
+});
+
+await test("a run.json whose field has the wrong type is refused", (t) => {
+  const dir = savedRun(t, { ready: "yes" });
+  assert.throws(() => loadRun(dir), /malformed: expected a run state/);
+  const processes = savedRun(t, { processes: [{ name: "api", pid: "7" }] });
+  assert.throws(() => loadRun(processes), /malformed: expected a run state/);
+});
+
+await test("keys of a run.json that the schema does not name are written back", (t) => {
+  const dir = savedRun(t, { addedByANewerRelease: 1 });
+  saveRun(loadRun(dir));
+  assert.equal(
+    Object.getOwnPropertyDescriptor(loadRun(dir), "addedByANewerRelease")
+      ?.value,
+    1,
+  );
+});
+
+await test("a new run's folders hold no browser folder, and loading a fresh run has no server", (t) => {
+  const parent = mkdtempSync(join(tmpdir(), "dms-control-run-state-test-"));
+  t.after(() => rmSync(parent, { recursive: true, force: true }));
+  const dir = join(parent, "run");
+  const paths = createRunFolders(dir);
+  assert.equal("browser" in paths, false);
+  saveRun({ ...RUN, ...paths, id: "x" });
+  assert.equal("browser" in loadRun(dir), false);
+});
+
+await test("a run that down stopped loads again, its accounts without a password", async (t) => {
+  const dir = savedRun(t, {
+    accounts: {
+      admin: { email: "a@example.com", password: "pw", userId: "u1" },
+    },
+  });
+  await down(loadRun(dir));
+  const stopped = loadRun(dir);
+  assert.deepEqual(stopped.accounts, {
+    admin: { email: "a@example.com", password: "" },
+  });
+  assert.equal(stopped.ready, false);
+  await down(stopped);
+  assert.deepEqual(loadRun(dir).accounts, {
+    admin: { email: "a@example.com", password: "" },
+  });
+});
+
+await test("a run.json without its accounts, or with an account without an email, is refused", (t) => {
+  const withoutAccounts = savedRun(t, {});
+  writeFileSync(
+    join(withoutAccounts, "run.json"),
+    JSON.stringify({ ...RUN, dir: withoutAccounts, accounts: undefined }),
+  );
+  assert.throws(() => loadRun(withoutAccounts), /malformed/);
+  const noEmail = savedRun(t, { accounts: { admin: { password: "pw" } } });
+  assert.throws(() => loadRun(noEmail), /malformed/);
+});
+
+await test("a run keeps the renderer checkout it serves across a save and a load", (t) => {
+  const dir = savedRun(t, { renderer: "/work/dms-frontend" });
+  const state = loadRun(dir);
+  assert.equal(state.renderer, "/work/dms-frontend");
+  saveRun(state);
+  assert.equal(loadRun(dir).renderer, "/work/dms-frontend");
+});
+
+await test("a run whose renderer is not a path is refused", (t) => {
+  assert.throws(() => loadRun(savedRun(t, { renderer: 3 })), /malformed/);
+});