@antelopejs/dms 0.15.1 → 0.16.1

package/bin/control/commands-stack.mjs

@@ -9,6 +9,8 @@ import { apiRequest, isOk, onboard } from "./session.mjs";
 import { down, freshDatabase, resolutionFolders, up } from "./stack.mjs";
 import { loadSkill, runPrepare } from "./verify/skill.mjs";
 
+/** @typedef {import("./options.mjs").Values} Values */
+
 const BROWSER_ACTIONS = [...ACTION_NAMES, "login"];
 
 /**
@@ -20,13 +22,32 @@ export function print(text) {
   process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
 }
 
-async function defaultPlayground(values) {
-  if (values.playground) return values.playground;
-  const skill = await loadSkill(values.skill, process.cwd()).catch(() => null);
-  if (skill) return join(skill.repo, skill.config.playground);
-  return "playground";
+/**
+ * The playground and the renderer checkout `up` starts: the options, then
+ * the skill's `verify.config.ts`.
+ *
+ * @param {Pick<Values, "playground" | "renderer" | "skill">} values
+ * @param {string} cwd Where the command runs, which finds the skill
+ * @returns {Promise<{ playground: string, renderer: string | undefined }>}
+ */
+export async function targetOf(values, cwd) {
+  const skill =
+    values.playground && values.renderer
+      ? null
+      : await loadSkill(values.skill, cwd).catch(() => null);
+  const fromSkill = (/** @type {string | undefined} */ folder) =>
+    skill && folder ? resolve(skill.repo, folder) : undefined;
+  return {
+    playground:
+      values.playground ?? fromSkill(skill?.config.playground) ?? "playground",
+    renderer: values.renderer ?? fromSkill(skill?.config.renderer),
+  };
 }
 
+/**
+ * @param {Values} values
+ * @returns {Promise<number>}
+ */
 async function commandUp(values) {
   const skill = values.skill ? resolve(values.skill) : undefined;
   if (values.prepare) {
@@ -34,7 +55,7 @@ async function commandUp(values) {
     runPrepare(loaded, loaded.repo);
   }
   const state = await up({
-    playground: await defaultPlayground(values),
+    ...(await targetOf(values, process.cwd())),
     runs: values.runs,
     mongoUrl: values["mongo-url"],
     env: values.env,
@@ -45,6 +66,11 @@ async function commandUp(values) {
   return 0;
 }
 
+/**
+ * @param {string} dir
+ * @param {Values} values
+ * @returns {Promise<number>}
+ */
 async function commandDoctor(dir, values) {
   const state = loadRun(dir);
   const lines = await doctor(state);
@@ -58,6 +84,11 @@ async function commandDoctor(dir, values) {
   return lines.every((line) => line.ok) ? 0 : 1;
 }
 
+/**
+ * @param {string} dir
+ * @param {Values} values
+ * @returns {Promise<number>}
+ */
 async function commandOnboard(dir, values) {
   const state = loadRun(dir);
   const answer = await onboard(state, {
@@ -73,6 +104,7 @@ async function commandOnboard(dir, values) {
   return 0;
 }
 
+/** @param {Values} values */
 function browserTarget(values) {
   if (!values.role) return undefined;
   const within = values["within-role"]
@@ -87,6 +119,12 @@ function browserTarget(values) {
   };
 }
 
+/**
+ * @param {string} dir
+ * @param {string} action
+ * @param {Values} values
+ * @returns {Promise<number>}
+ */
 async function commandBrowser(dir, action, values) {
   if (!BROWSER_ACTIONS.includes(action)) {
     print(
@@ -118,8 +156,16 @@ async function commandBrowser(dir, action, values) {
   return 0;
 }
 
+/**
+ * @param {string} dir
+ * @param {string} method
+ * @param {string} path
+ * @param {Values} values
+ * @returns {Promise<number>}
+ */
 async function commandApi(dir, method, path, values) {
   const state = loadRun(dir);
+  /** @type {unknown} */
   const body = values.body === undefined ? undefined : JSON.parse(values.body);
   const answer = await apiRequest(state, {
     method: method.toUpperCase(),
@@ -132,6 +178,10 @@ async function commandApi(dir, method, path, values) {
   return isOk(answer) ? 0 : 1;
 }
 
+/**
+ * @param {string} dir
+ * @returns {Promise<number>}
+ */
 async function commandDown(dir) {
   const state = loadRun(dir);
   const lines = await down(state);
@@ -145,9 +195,9 @@ async function commandDown(dir) {
  * Runs a command that drives the product: `up`, `doctor`, `onboard`,
  * `browser`, `api`, `mail`, `down`, and the two services `up` starts.
  *
- * @param {string} command The command
+ * @param {string | undefined} command The command
  * @param {string[]} rest Its positional arguments
- * @param {Record<string, any>} values Its options
+ * @param {Values} values Its options
  * @returns {Promise<number | undefined>} The exit code, or undefined for a command it does not own; the two services keep the process alive
  */
 export async function runStackCommand(command, rest, values) {

package/bin/control/commands-verify.mjs

@@ -20,6 +20,16 @@ import { runSeededBreaks } from "./verify/seeded.mjs";
 import { journeysFile, loadSkill } from "./verify/skill.mjs";
 import { renderVerdict } from "./verify/verdict.mjs";
 
+/**
+ * @typedef {import("./options.mjs").Values} Values
+ * @typedef {import("./run-state.mjs").RunState} RunState
+ */
+
+/**
+ * @param {Values} values The options of the command line
+ * @param {RunState} [state] The run, whose skill and checkout are the defaults
+ * @returns {ReturnType<typeof loadSkill>} The skill
+ */
 function skillOf(values, state) {
   return loadSkill(
     values.skill ?? state?.skill ?? undefined,
@@ -27,18 +37,33 @@ function skillOf(values, state) {
   );
 }
 
+/**
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandMap(values) {
   const problems = await checkMap(await skillOf(values));
   for (const problem of problems) print(problem);
   return problems.length === 0 ? 0 : 1;
 }
 
+/**
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandPlan(values) {
   const plan = planFor(await skillOf(values), values.base);
   print(JSON.stringify(plan, null, 2));
   return plan.unmapped.length === 0 ? 0 : 1;
 }
 
+/**
+ * @param {string} dir The run root
+ * @param {string} feature The feature whose journeys run
+ * @param {string[]} ids The journeys to run, or none for all
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandJourney(dir, feature, ids, values) {
   const state = loadRun(dir);
   const skill = await skillOf(values, state);
@@ -61,6 +86,11 @@ async function commandJourney(dir, feature, ids, values) {
   return results.every((result) => result.status === "PASS") ? 0 : 1;
 }
 
+/**
+ * @param {string[]} features The features whose seeded breaks run
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandSeeded(features, values) {
   const skill = await skillOf(values);
   const outcomes = runSeededBreaks(skill, features);
@@ -81,6 +111,11 @@ async function commandSeeded(features, values) {
   return outcomes.every((outcome) => outcome.caught) ? 0 : 1;
 }
 
+/**
+ * @param {string | undefined} patch A patch file, or none for the diff
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandDoors(patch, values) {
   const skill = await skillOf(values);
   const doors = flaggedDoors(
@@ -93,6 +128,11 @@ async function commandDoors(patch, values) {
   return 0;
 }
 
+/**
+ * @param {string} dir The run root
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandFormal(dir, values) {
   const state = loadRun(dir);
   const skill = await skillOf(values, state);
@@ -125,6 +165,12 @@ async function commandFormal(dir, values) {
   return 0;
 }
 
+/**
+ * @param {string} command `verdict` or `publish`
+ * @param {string} dir The run root
+ * @param {Values} values The options of the command line
+ * @returns {Promise<number>} The exit code
+ */
 async function commandJudge(command, dir, values) {
   const pr = Number(values.pr);
   if (!Number.isInteger(pr) || pr <= 0) {
@@ -159,7 +205,7 @@ async function commandJudge(command, dir, values) {
  *
  * @param {string} command The command
  * @param {string[]} rest Its positional arguments
- * @param {Record<string, any>} values Its options
+ * @param {Values} values Its options
  * @returns {Promise<number | undefined>} The exit code, or undefined for a command it does not own
  */
 export function runVerifyCommand(command, rest, values) {

package/bin/control/doctor.mjs

@@ -3,9 +3,12 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { descendantsOf, isAlive, listenersOf, probe } from "./processes.mjs";
 import { checkoutOf } from "./git.mjs";
+import { stringField } from "./json.mjs";
 import { apiRequest } from "./session.mjs";
 import { packageVersion } from "./stack.mjs";
 
+/** @typedef {import("./run-state.mjs").RunState} RunState */
+
 const SKIPPED = new Set([
   "node_modules",
   ".antelope",
@@ -16,6 +19,10 @@ const SKIPPED = new Set([
   ".output",
 ]);
 
+/**
+ * @param {string} folder
+ * @returns {number}
+ */
 function newestMtime(folder) {
   if (!existsSync(folder)) return 0;
   let newest = 0;
@@ -30,14 +37,25 @@ function newestMtime(folder) {
   return newest;
 }
 
+/**
+ * @param {string} file
+ * @returns {number}
+ */
 function mtime(file) {
   return existsSync(file) ? statSync(file).mtimeMs : 0;
 }
 
+/**
+ * @param {string} check
+ * @param {boolean} ok
+ * @param {string} detail
+ * @returns {{ check: string, ok: boolean, detail: string }}
+ */
 function line(check, ok, detail) {
   return { check, ok, detail };
 }
 
+/** @param {RunState} state */
 function processLines(state) {
   const family = new Set([
     ...state.processes.map((record) => record.pid),
@@ -71,6 +89,10 @@ function processLines(state) {
   });
 }
 
+/**
+ * @param {RunState} state
+ * @returns {string}
+ */
 function frontendBackendUrl(state) {
   const frontend = state.processes.find((record) => record.name === "frontend");
   if (!frontend) return "no frontend recorded";
@@ -88,8 +110,13 @@ function frontendBackendUrl(state) {
   return args[args.indexOf("-b") + 1] ?? "no -b";
 }
 
+/** @param {RunState} state */
 function versions(state) {
   const require = createRequire(join(state.playground, "package.json"));
+  /**
+   * @param {string} name
+   * @returns {string}
+   */
   const version = (name) => {
     try {
       return packageVersion(require.resolve(`${name}/package.json`));
@@ -100,10 +127,13 @@ function versions(state) {
   return {
     module: `${packageVersion(join(state.moduleRoot, "package.json"))} (${state.moduleRoot})`,
     core: version("@antelopejs/core"),
-    dmsFrontend: version("@antelopejs/dms-frontend"),
+    dmsFrontend: state.renderer
+      ? packageVersion(join(state.renderer, "package.json"))
+      : version("@antelopejs/dms-frontend"),
   };
 }
 
+/** @param {RunState} state */
 function freshnessLines(state) {
   const moduleDist = join(state.moduleRoot, "dist");
   const playgroundDist = join(state.playground, "dist");
@@ -116,7 +146,18 @@ function freshnessLines(state) {
     newestMtime(join(state.moduleRoot, "frontend-vue")),
     newestMtime(join(state.playground, "frontend-vue")),
   );
+  const renderer = state.renderer
+    ? [
+        line(
+          "renderer build newer than src",
+          newestMtime(join(state.renderer, "dist")) >=
+            newestMtime(join(state.renderer, "src")),
+          state.renderer,
+        ),
+      ]
+    : [];
   return [
+    ...renderer,
     line(
       "module dist newer than src",
       !existsSync(join(state.moduleRoot, "src")) ||
@@ -138,8 +179,10 @@ function freshnessLines(state) {
   ];
 }
 
+/** @param {RunState} state */
 function headLine(state) {
-  const now = state.repo ? checkoutOf(state.repo).head : null;
+  const verified = state.renderer ?? state.repo;
+  const now = verified ? checkoutOf(verified).head : null;
   return line(
     "checkout HEAD unchanged since up",
     now === state.headSha,
@@ -147,6 +190,7 @@ function headLine(state) {
   );
 }
 
+/** @param {RunState} state */
 async function sessionLine(state) {
   if (!state.accounts?.admin)
     return line("admin session", true, "not onboarded yet");
@@ -158,7 +202,8 @@ async function sessionLine(state) {
   });
   return line(
     "admin session valid",
-    me.status === 200 && me.body?.email === state.accounts.admin.email,
+    me.status === 200 &&
+      stringField(me.body, "email") === state.accounts.admin.email,
     `GET /api/auth/me ${me.status}`,
   );
 }
@@ -169,7 +214,7 @@ async function sessionLine(state) {
  * backend, the builds are newer than their sources, the database is the
  * run's own, and the admin session (once onboarded) is valid.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @returns {Promise<{ check: string, ok: boolean, detail: string }[]>} One line per check
  */
 export async function doctor(state) {

package/bin/control/failure.mjs

@@ -0,0 +1,9 @@
+/**
+ * What a caught value says: the message of an `Error`, else the value as text.
+ *
+ * @param {unknown} failure What was thrown or rejected
+ * @returns {string} The text
+ */
+export function describeFailure(failure) {
+  return failure instanceof Error ? failure.message : String(failure);
+}