@antelopejs/dms 0.11.0 → 0.12.0

package/bin/control/verify/seeded.mjs

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { git } from "../git.mjs";
+import { CONTROL_BIN } from "../stack.mjs";
+import { runPrepare } from "./skill.mjs";
+
+const OUTPUT_LIMIT = 64 * 1024 * 1024;
+
+function run(cwd, program, args) {
+  return spawnSync(program, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, CI: "1" },
+    maxBuffer: OUTPUT_LIMIT,
+  });
+}
+
+function mustRun(cwd, program, args) {
+  const result = run(cwd, program, args);
+  if (result.status !== 0) {
+    throw new Error(
+      `${program} ${args.join(" ")} failed in ${cwd}:\n${result.stdout}${result.stderr}`,
+    );
+  }
+  return result.stdout.trim();
+}
+
+/**
+ * A scratch worktree of HEAD with the current skill copied in, the patch
+ * applied when there is one, and the config's `prepare` commands run.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} label What the worktree is for
+ * @param {string | null} patch The patch file, or `null` for the control
+ * @returns {{ worktree: string, skill: string }} The worktree and its skill copy
+ */
+function prepareWorktree(skill, label, patch) {
+  const worktree = mkdtempSync(
+    join(tmpdir(), `${skill.name}-seeded-${label}-`),
+  );
+  git(["worktree", "add", "--detach", "--force", worktree, "HEAD"], skill.repo);
+  const copy = join(worktree, relative(skill.repo, skill.dir));
+  rmSync(copy, { recursive: true, force: true });
+  cpSync(skill.dir, copy, { recursive: true });
+  if (patch) mustRun(worktree, "git", ["apply", patch]);
+  runPrepare(skill, worktree);
+  return { worktree, skill: copy };
+}
+
+function removeWorktree(skill, worktree) {
+  git(["worktree", "remove", "--force", worktree], skill.repo);
+}
+
+function runFeatureIn(prepared, skill, feature) {
+  const playground = join(prepared.worktree, skill.config.playground);
+  const control = (args) =>
+    run(prepared.worktree, process.execPath, [CONTROL_BIN, ...args]);
+  const started = control([
+    "up",
+    "--playground",
+    playground,
+    "--skill",
+    prepared.skill,
+  ]);
+  const dir = started.stdout.trim().split("\n").at(-1) ?? "";
+  if (started.status !== 0 || !existsSync(join(dir, "run.json"))) {
+    return {
+      run: dir,
+      results: [],
+      output: `up failed:\n${started.stdout}${started.stderr}`,
+    };
+  }
+  const journeys = control([
+    "journey",
+    dir,
+    feature,
+    "--skill",
+    prepared.skill,
+  ]);
+  control(["down", dir]);
+  const file = join(dir, "evidence", feature, "feature.json");
+  const results = existsSync(file)
+    ? JSON.parse(readFileSync(file, "utf8"))
+    : [];
+  return { run: dir, results, output: `${journeys.stdout}${journeys.stderr}` };
+}
+
+function failsACheck(result) {
+  return result.steps.some((step) => step.checks.some((check) => !check.pass));
+}
+
+function judge(feature, control, seeded) {
+  const passedInControl = new Set(
+    control.results
+      .filter((result) => result.status === "PASS")
+      .map((result) => result.journey),
+  );
+  const failed = seeded.results.filter((result) => result.status === "FAIL");
+  const caughtBy = failed
+    .filter(
+      (result) => passedInControl.has(result.journey) && failsACheck(result),
+    )
+    .map((result) => result.journey);
+  return {
+    feature,
+    caught: caughtBy.length > 0,
+    run: seeded.run,
+    controlRun: control.run,
+    caughtBy,
+    failingInControl: control.results
+      .filter((result) => result.status === "FAIL")
+      .map((result) => result.journey),
+    harnessErrors: failed
+      .filter((result) => !failsACheck(result))
+      .map((result) => result.journey),
+    output: seeded.output,
+  };
+}
+
+/**
+ * Runs each feature's journeys twice from scratch worktrees of HEAD: once
+ * unpatched as the control, once with `seeded-breaks/<feature>.patch`. A
+ * break is caught only when a journey that passes in the control fails one
+ * of its checks with the patch; a failure without a failing check is a
+ * harness error and does not count. Worktrees are removed; both runs keep
+ * their evidence, and `seeded.json` in the patched run records the outcome.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string[]} features The features
+ * @returns {Record<string, any>[]} One outcome per feature
+ */
+export function runSeededBreaks(skill, features) {
+  const control = prepareWorktree(skill, "control", null);
+  try {
+    return features.map((feature) => {
+      const unpatched = runFeatureIn(control, skill, feature);
+      const patch = join(skill.seededBreaksDir, `${feature}.patch`);
+      const seeded = prepareWorktree(skill, feature, patch);
+      try {
+        const outcome = judge(
+          feature,
+          unpatched,
+          runFeatureIn(seeded, skill, feature),
+        );
+        if (existsSync(outcome.run)) {
+          writeFileSync(
+            join(outcome.run, "evidence", "seeded.json"),
+            `${JSON.stringify(outcome, null, 2)}\n`,
+          );
+        }
+        return outcome;
+      } finally {
+        removeWorktree(skill, seeded.worktree);
+      }
+    });
+  } finally {
+    removeWorktree(skill, control.worktree);
+  }
+}

package/bin/control/verify/skill.mjs

@@ -0,0 +1,130 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { checkoutOf } from "../git.mjs";
+
+const CONFIG_FILE = "verify.config.ts";
+const OUTPUT_LIMIT = 64 * 1024 * 1024;
+
+function frontmatterLists(text) {
+  const lists = new Map();
+  const match = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  let current;
+  for (const line of (match?.[1] ?? "").split("\n")) {
+    const key = /^(\w+):\s*$/.exec(line);
+    const item = /^\s+-\s+(.+)$/.exec(line);
+    if (key) {
+      current = [];
+      lists.set(key[1], current);
+    } else if (item && current) {
+      current.push(item[1].replace(/^"|"$/g, ""));
+    }
+  }
+  return lists;
+}
+
+function discover(cwd) {
+  const { root } = checkoutOf(cwd);
+  const skills = join(root ?? cwd, ".agents", "skills");
+  const found = existsSync(skills)
+    ? readdirSync(skills)
+        .filter((name) => name.startsWith("verify-"))
+        .map((name) => join(skills, name))
+        .filter((dir) => existsSync(join(dir, CONFIG_FILE)))
+    : [];
+  if (found.length !== 1) {
+    throw new Error(
+      `Expected one .agents/skills/verify-*/${CONFIG_FILE} under ${root ?? cwd}, found ${found.length}; pass --skill <dir>.`,
+    );
+  }
+  return found[0];
+}
+
+/**
+ * Loads a verification skill: its `verify.config.ts` (imported with Node's
+ * TypeScript type stripping), its feature files and where its journeys,
+ * seeded breaks and seeded doors live. Without `--skill`, the one
+ * `.agents/skills/verify-*` folder of the checkout holding `cwd`.
+ *
+ * @param {string | undefined} option The `--skill` folder
+ * @param {string} cwd Where the command runs
+ * @returns {Promise<Record<string, any>>} The skill
+ */
+export async function loadSkill(option, cwd) {
+  const dir = resolve(option ?? discover(cwd));
+  const { root } = checkoutOf(dir);
+  if (!root) throw new Error(`${dir} is not inside a git checkout`);
+  const { default: config } = await import(
+    pathToFileURL(join(dir, CONFIG_FILE)).href
+  );
+  return {
+    dir,
+    name: basename(dir),
+    repo: root,
+    config,
+    featuresDir: join(dir, "features"),
+    journeysDir: join(dir, "journeys"),
+    seededBreaksDir: join(dir, "seeded-breaks"),
+    seededDoorsDir: join(dir, "seeded-doors"),
+  };
+}
+
+/**
+ * Every feature file under `features/`, README.md excluded, with its
+ * `covers:` globs, `docs:` pages and text.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @returns {{ name: string, file: string, covers: string[], docs: string[], body: string }[]} The features
+ */
+export function readFeatures(skill) {
+  return readdirSync(skill.featuresDir)
+    .filter((file) => file.endsWith(".md") && file !== "README.md")
+    .sort()
+    .map((file) => {
+      const text = readFileSync(join(skill.featuresDir, file), "utf8");
+      const lists = frontmatterLists(text);
+      return {
+        name: file.replace(/\.md$/, ""),
+        file: relative(skill.repo, join(skill.featuresDir, file)),
+        covers: lists.get("covers") ?? [],
+        docs: lists.get("docs") ?? [],
+        body: text,
+      };
+    });
+}
+
+/**
+ * The journeys module of a feature.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} feature The feature name
+ * @returns {string} Its path
+ */
+export function journeysFile(skill, feature) {
+  return join(skill.journeysDir, `${feature}.mjs`);
+}
+
+/**
+ * Runs the config's `prepare` commands (install and build) in a checkout of
+ * the repository, so a run starts from a fresh build.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {string} cwd The checkout
+ * @throws When a command fails, with its output
+ */
+export function runPrepare(skill, cwd) {
+  for (const [program, ...args] of skill.config.prepare) {
+    const result = spawnSync(program, args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: OUTPUT_LIMIT,
+      env: { ...process.env, CI: "1" },
+    });
+    if (result.status !== 0) {
+      throw new Error(
+        `${program} ${args.join(" ")} failed in ${cwd}:\n${result.stdout}${result.stderr}`,
+      );
+    }
+  }
+}

package/bin/control/verify/verdict.mjs

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { git } from "../git.mjs";
+import { loadJourneys } from "../journey.mjs";
+import { flaggedDoors } from "./doors.mjs";
+import {
+  formalGate,
+  readFormalResult,
+  touchedFormalChecks,
+} from "./formal.mjs";
+import { planFor } from "./map.mjs";
+import { journeysFile } from "./skill.mjs";
+
+const CONTAINED_KINDS = new Set(["data", "format"]);
+
+/**
+ * The GitHub `owner/repo` of the checkout's origin remote.
+ *
+ * @param {string} repo The checkout
+ * @returns {string} The repository
+ */
+export function originRepository(repo) {
+  const url = git(["remote", "get-url", "origin"], repo);
+  const match = /github\.com[:/](.+?)(?:\.git)?$/.exec(url);
+  if (!match) throw new Error(`origin ${url} is not a GitHub repository`);
+  return match[1];
+}
+
+function short(sha) {
+  return sha.slice(0, 7);
+}
+
+function bullets(entries, empty) {
+  return (entries.length > 0 ? entries : [empty]).map((entry) => `- ${entry}`);
+}
+
+function readResults(state, feature) {
+  const file = join(state.evidence, feature, "feature.json");
+  return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : [];
+}
+
+async function journeyRows(skill, state, plan, link) {
+  const rows = [];
+  const reasons = [];
+  const byJourney = new Map();
+  for (const feature of plan.run) {
+    const results = readResults(state, feature);
+    const file = journeysFile(skill, feature);
+    const registered = existsSync(file)
+      ? (await loadJourneys(file)).map((journey) => journey.id)
+      : [];
+    for (const id of registered.filter(
+      (journey) => !results.some((result) => result.journey === journey),
+    )) {
+      reasons.push(`${feature}/${id} was not run`);
+    }
+    for (const result of results) {
+      if (!registered.includes(result.journey))
+        reasons.push(
+          `${feature}/${result.journey} is not a registered journey`,
+        );
+      if (result.status === "FAIL")
+        reasons.push(`${feature}/${result.journey} failed`);
+      byJourney.set(`${feature}/${result.journey}`, result);
+      const outcome = result.status === "PASS" ? "pass" : "**fail**";
+      rows.push(
+        `| ${feature} | \`${result.journey}\`: ${result.entryPoint} | ${outcome}: ${result.title} | [${result.folder}](${link(result.folder)}) |`,
+      );
+    }
+  }
+  return { rows, reasons, byJourney };
+}
+
+function containmentResult(state, byJourney, id) {
+  const [feature, journey] = id.split("/");
+  return (
+    byJourney.get(id) ??
+    readResults(state, feature).find((result) => result.journey === journey)
+  );
+}
+
+function doorReasons(skill, state, judgement, byJourney, plan) {
+  const reasons = [];
+  for (const row of judgement.doors.filter((door) =>
+    CONTAINED_KINDS.has(door.kind),
+  )) {
+    const allowed = skill.config.doors[row.kind]?.containments ?? [];
+    const journey = containmentResult(state, byJourney, row.containmentJourney);
+    if (!allowed.includes(row.containmentJourney)) {
+      reasons.push(
+        `${row.kind} door at ${row.location} names ${row.containmentJourney || "no journey"}; its containment must be one of ${allowed.join(", ")}`,
+      );
+    } else if (journey?.status !== "PASS") {
+      reasons.push(
+        `${row.kind} door at ${row.location}: containment journey ${row.containmentJourney} did not pass in this run`,
+      );
+    }
+  }
+  for (const door of flaggedDoors(skill, plan.changed)) {
+    for (const file of door.files) {
+      const listed = judgement.doors.some(
+        (row) => row.kind === door.kind && row.location.includes(file),
+      );
+      const dismissed = judgement.falsePositives.some(
+        (entry) => entry.kind === door.kind && entry.location === file,
+      );
+      if (!listed && !dismissed) {
+        reasons.push(
+          `path rules flag a ${door.kind} door at ${file} that the One-way doors section neither lists nor dismisses`,
+        );
+      }
+    }
+  }
+  return reasons;
+}
+
+function doorsSection(judgement) {
+  const dismissed = judgement.falsePositives.map(
+    (entry) =>
+      `- Not a door: \`${entry.location}\` matches the ${entry.kind} path rules. ${entry.reason}`,
+  );
+  if (judgement.doors.length === 0)
+    return [`None: ${judgement.doorsNone}`, ...dismissed];
+  return [
+    ...dismissed,
+    "| Kind | Location | What cannot be undone | Containment |",
+    "|---|---|---|---|",
+    ...judgement.doors.map((door) => {
+      const journey = door.containmentJourney
+        ? ` (journey \`${door.containmentJourney}\`)`
+        : "";
+      return `| ${door.kind} | \`${door.location}\` | ${door.irreversible} | ${door.containment}${journey} |`;
+    }),
+  ];
+}
+
+function formalSection(skill, state, plan, link) {
+  const reasons = [];
+  const lines = [];
+  const touched = touchedFormalChecks(skill, plan.changed).map(
+    (check) => check.name,
+  );
+  for (const check of skill.config.formal) {
+    const result = readFormalResult(state, check.name);
+    const gate = touched.includes(check.name);
+    if (!result) {
+      if (gate)
+        reasons.push(
+          `formal check ${check.name} covers the diff but was not run`,
+        );
+      continue;
+    }
+    if (gate && !result.behaviour && result.exitCode === 0) {
+      reasons.push(
+        `formal check ${check.name} covers the diff but its run did not compare the covered behaviour with the base`,
+      );
+    }
+    const weight = formalGate(result);
+    if (gate && weight.fails)
+      reasons.push(`formal check ${check.name}: ${weight.outcome}`);
+    const summary = gate
+      ? weight.outcome
+      : result.violated.length > 0
+        ? `violated: ${result.violated.join(", ")}`
+        : `exit ${result.exitCode}, no violated rule`;
+    const role = gate
+      ? "covers the diff, gates the verdict"
+      : "does not cover the diff, informational";
+    lines.push(
+      `\`${check.name}\` (${role}): ${summary}. [evidence](${link(result.folder)})`,
+    );
+  }
+  return { reasons, lines };
+}
+
+function docsReasons(judgement, plan) {
+  return plan.docs.flatMap((page) => {
+    const docs = judgement.docs.find((entry) => entry.page === page);
+    if (!docs)
+      throw new Error(
+        `judgement.json: docs page ${page} of a touched feature has no judgement`,
+      );
+    return docs.matches ? [] : [`${page} no longer matches the behaviour`];
+  });
+}
+
+function markdown(skill, verdict, parts) {
+  const { plan, judgement, journeys, formal, reasons, attention, link } = parts;
+  const touched = plan.touched.map(
+    (entry) =>
+      `\`${entry.feature}\` (diff: ${entry.files.map((file) => `\`${file}\``).join(", ")})`,
+  );
+  const docs = judgement.docs.map(
+    (entry) =>
+      `\`${entry.page}\`: ${entry.matches ? "matches" : "**stale**"}${entry.note ? `. ${entry.note}` : ""}`,
+  );
+  return [
+    `## Verify: ${verdict.result}`,
+    "",
+    `**Head** \`${short(plan.headSha)}\` · **Skill** \`${skill.name}\` @ \`${short(verdict.skillSha)}\` (not trusted yet) · **Verifier** ${judgement.verifier}`,
+    "",
+    "### One-way doors",
+    ...doorsSection(judgement),
+    "",
+    "### Touched features",
+    ...bullets(touched, "none"),
+    `- ${skill.config.smoke}: ${skill.config.smokeJourney}`,
+    ...(plan.containments.length > 0
+      ? [
+          `- containment journeys of the Data and Format doors: ${plan.containments.map((feature) => `\`${feature}\``).join(", ")}`,
+        ]
+      : []),
+    "",
+    ...(plan.unmapped.length > 0
+      ? [
+          "### Unmapped surfaces",
+          ...plan.unmapped.map(
+            (file) =>
+              `- \`${file}\` matches no feature glob; add it to a feature file.`,
+          ),
+          "",
+        ]
+      : []),
+    ...(reasons.length > 0
+      ? ["### Why it fails", ...reasons.map((reason) => `- ${reason}`), ""]
+      : []),
+    "### Journeys",
+    "| Feature | Entry point | Result | Evidence |",
+    "|---|---|---|---|",
+    ...journeys.rows,
+    "",
+    "### Formal checks",
+    ...bullets(formal.lines, "None ran."),
+    "",
+    "### Docs",
+    ...bullets(docs, "No touched feature links a page."),
+    "",
+    "### Not verified",
+    ...bullets(judgement.notVerified, "Nothing."),
+    "",
+    "### Attention",
+    ...bullets(attention, "Nothing."),
+    "",
+    `Evidence: \`verify-evidence\` branch, [\`pr-${verdict.pr}/${plan.headSha}/\`](${link("")})`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Computes the verdict of a run from its journey results, the diff plan,
+ * the formal check results and the verifier's judgement, and writes
+ * verdict.md, verdict.json and plan.json into the evidence folder.
+ *
+ * @param {Record<string, any>} skill The skill
+ * @param {Record<string, any>} state The run
+ * @param {number} pr The pull request
+ * @param {Record<string, any>} judgement The verifier's judgement
+ * @returns {Promise<{ result: string, headSha: string, skillSha: string, pr: number, markdown: string, reasons: string[] }>} The verdict
+ */
+export async function renderVerdict(skill, state, pr, judgement) {
+  const plan = planFor(skill, state.baseRef);
+  const skillSha =
+    git(
+      ["log", "-1", "--format=%H", "--", relative(skill.repo, skill.dir)],
+      skill.repo,
+    ) || plan.headSha;
+  const repository = originRepository(skill.repo);
+  const link = (path) =>
+    `https://github.com/${repository}/tree/verify-evidence/pr-${pr}/${plan.headSha}/${path}`;
+  const reasons = [];
+  if (plan.headSha !== state.headSha) {
+    reasons.push(
+      `the run was created at ${short(state.headSha ?? "unknown")} but HEAD is ${short(plan.headSha)}`,
+    );
+  }
+  const journeys = await journeyRows(skill, state, plan, link);
+  const formal = formalSection(skill, state, plan, link);
+  reasons.push(
+    ...journeys.reasons,
+    ...plan.unmapped.map((file) => `unmapped surface ${file}`),
+    ...docsReasons(judgement, plan),
+    ...doorReasons(skill, state, judgement, journeys.byJourney, plan),
+    ...formal.reasons,
+  );
+  const attention = judgement.attention;
+  const notes = judgement.notVerified.length + attention.length > 0;
+  const result = reasons.length > 0 ? "FAIL" : notes ? "PASS+NOTES" : "PASS";
+  const verdict = { result, headSha: plan.headSha, skillSha, pr, reasons };
+  const text = markdown(skill, verdict, {
+    plan,
+    judgement,
+    journeys,
+    formal,
+    reasons,
+    attention,
+    link,
+  });
+  writeFileSync(join(state.evidence, "verdict.md"), text);
+  writeFileSync(
+    join(state.evidence, "plan.json"),
+    `${JSON.stringify(plan, null, 2)}\n`,
+  );
+  writeFileSync(
+    join(state.evidence, "verdict.json"),
+    `${JSON.stringify(verdict, null, 2)}\n`,
+  );
+  return { ...verdict, markdown: text };
+}

package/bin/dms-control.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { print, runStackCommand } from "./control/commands-stack.mjs";
+import { runVerifyCommand } from "./control/commands-verify.mjs";
+
+const USAGE = `Usage: dms-control <command>
+
+Drive an isolated DMS (run from the repository, or pass --playground):
+  up [--prepare] [--playground <dir>] [--runs <dir>] [--mongo-url <url>] [--env KEY=VALUE]... [--base <ref>] [--skill <dir>]
+                       build and start a playground copy on free ports; print the run folder
+                       (--prepare first runs the skill's install and build commands)
+  doctor <run> [--verbose]          check the run is worth driving; print the failing checks
+  onboard <run> [--platform-name <name>]
+                       create the run's administrator through POST /api/onboarding/register
+  browser <run> <action> [--as <account>] [--tab <name>] [--role <role> --name <name> [--exact] [--nth <n>]
+          [--within-role <role> --within-name <name>]] [--value <text>] [--key <key>] [--path <path>]
+                       actions: goto, reload, click, fill, select, check, uncheck, hover, press, wait,
+                       snapshot (prints the ARIA tree), screenshot (prints the file), login
+  api <run> <method> <path> [--as <account>|anon] [--body <json>]
+                       an authenticated request; prints the status and the body
+  mail <run>                        the messages the run's mail sink captured
+  reset <run>                       restart the backend on an empty database of the run
+  down <run>                        stop the run, drop its databases, keep its evidence
+
+Verify a change (the .agents/skills/verify-* folder of the checkout, or --skill <dir>):
+  map                               check the feature map covers every user-facing file
+  plan [--base <ref>]               map the diff to features; list unmapped surfaces
+  journey <run> <feature> [ids...]  run a feature's journeys and record evidence
+  seeded <feature...>               run each feature unpatched and with its seeded break
+  doors [patch] [--base <ref>]      print the One-way-door line for a patch, or for the diff
+  formal <run> [--all]              run the formal checks that cover the diff (or every one)
+  verdict <run> --pr <n>            render evidence/verdict.md from the results and evidence/judgement.json
+  publish <run> --pr <n>            push the evidence, comment the verdict, set the verify status
+`;
+
+const OPTIONS = {
+  prepare: { type: "boolean" },
+  playground: { type: "string" },
+  runs: { type: "string" },
+  "mongo-url": { type: "string" },
+  env: { type: "string", multiple: true },
+  base: { type: "string", default: "origin/main" },
+  skill: { type: "string" },
+  verbose: { type: "boolean" },
+  "platform-name": { type: "string" },
+  as: { type: "string" },
+  tab: { type: "string" },
+  role: { type: "string" },
+  name: { type: "string" },
+  exact: { type: "boolean" },
+  nth: { type: "string" },
+  "within-role": { type: "string" },
+  "within-name": { type: "string" },
+  value: { type: "string" },
+  key: { type: "string" },
+  path: { type: "string" },
+  body: { type: "string" },
+  pr: { type: "string" },
+  all: { type: "boolean" },
+};
+
+async function main(argv) {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: OPTIONS,
+  });
+  const [command, ...rest] = positionals;
+  const code =
+    (await runStackCommand(command, rest, values)) ??
+    (await runVerifyCommand(command, rest, values));
+  if (code !== undefined) return code;
+  print(USAGE);
+  return command ? 2 : 0;
+}
+
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(process.exitCode ?? 0);
+  throw error;
+});
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`dms-control: ${error?.message ?? error}\n`);
+  process.exitCode = 1;
+}

package/dist/attachments/access.d.ts

@@ -1,7 +1,7 @@
 import type { RequestContext } from "@antelopejs/interface-api";
 import type { NativeUploadFieldRegistration } from "@antelopejs/interface-dms/internal/uploads";
 import type { RequestPrincipal } from "@antelopejs/interface-dms/auth";
-import type { UploadTokenClaims } from "../utils/upload-token";
+import type { UploadTokenClaims } from "../utils";
 export declare const RegisterNativeUploadField: {
     register(registration: NativeUploadFieldRegistration): void;
     unregister(registration: NativeUploadFieldRegistration): void;