@antelopejs/tooling-configs 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +38 -26
  2. package/dist/bin/api-diff.mjs +235 -37
  3. package/dist/bin/body-check.mjs +14 -11
  4. package/dist/bin/capture.mjs +173 -54
  5. package/dist/bin/check-size.mjs +1 -1
  6. package/dist/bin/checks.mjs +141 -14
  7. package/dist/bin/comment-proof.mjs +29 -7
  8. package/dist/bin/garden.mjs +2 -57
  9. package/dist/bin/ratchet.mjs +48 -14
  10. package/dist/bin/suppressions.mjs +3 -3
  11. package/dist/bin/sync.mjs +74 -41
  12. package/dist/bin/verify.mjs +898 -366
  13. package/dist/capture/index.d.mts +6 -1
  14. package/dist/capture/index.mjs +1 -1
  15. package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
  16. package/dist/eslint.d.mts +16 -3
  17. package/dist/eslint.mjs +21 -6
  18. package/dist/formal/index.d.mts +20 -4
  19. package/dist/formal/index.mjs +71 -19
  20. package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
  21. package/dist/oxc/anti-slop/index.mjs +50 -55
  22. package/dist/oxc/guardrails/index.d.mts +1 -1
  23. package/dist/oxc/guardrails/index.mjs +520 -103
  24. package/dist/oxc/lint.d.mts +7 -15
  25. package/dist/oxc/lint.mjs +16 -28
  26. package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
  27. package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
  28. package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-BTiPMqam.mjs} +17 -15
  29. package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
  30. package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
  31. package/dist/semver-BDxeEcP_.mjs +57 -0
  32. package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
  33. package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
  34. package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
  35. package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
  36. package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
  37. package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
  38. package/dist/verify/index.d.mts +60 -15
  39. package/package.json +3 -1
  40. package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
@@ -4,17 +4,18 @@ import { a as isString, c as object, f as parseJson, i as isObject, n as childre
4
4
  import { a as exitIs, c as interrupted, i as exists, r as equal, u as refused } from "../checks-CxkSu2E6.mjs";
5
5
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
6
6
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
7
- import { _ as removeTree, a as readFeatures, b as writeWhole, c as allocateRun, d as isolatedEnv, f as loadRun, g as recordProcesses, h as operatorTmpdir, i as planFor, l as commandRecords, m as operatorEnv, n as SMOKE_FEATURE, o as CACHE_DIR, p as openWorkspace, r as checkMap, s as RUNS_DIR, u as git, v as saveRun, x as matchesPath, y as withLocalBins } from "../map-B23_WMGE.mjs";
8
- import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
7
+ import { S as matchesPath, _ as recordProcesses, a as readFeatures, b as withLocalBins, c as allocateRun, d as isolatedEnv, f as loadRun, g as ownRun, h as operatorTmpdir, i as planFor, l as commandRecords, m as operatorEnv, n as SMOKE_FEATURE, o as CACHE_DIR, p as openWorkspace, r as checkMap, s as RUNS_DIR, u as git, v as removeTree, x as writeWhole, y as saveRun } from "../map-DRyYz_Fw.mjs";
8
+ import { accessSync, appendFileSync, chmodSync, closeSync, constants, copyFileSync, cpSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
9
9
  import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
10
10
  import { execFileSync, spawn, spawnSync } from "node:child_process";
11
11
  import { pathToFileURL } from "node:url";
12
12
  import ts from "typescript";
13
13
  import { createHash, randomBytes } from "node:crypto";
14
14
  import { availableParallelism, constants as constants$1 } from "node:os";
15
- import { parseArgs } from "node:util";
16
- import { createServer } from "node:net";
15
+ import { parseArgs, stripVTControlCharacters } from "node:util";
16
+ import { connect, createServer } from "node:net";
17
17
  import { setTimeout as setTimeout$1 } from "node:timers/promises";
18
+ import { lookup } from "node:dns";
18
19
  //#region src/verify/doors.ts
19
20
  const RELEASE_FILES = [
20
21
  "package.json",
@@ -875,6 +876,7 @@ function startRecorded(folder, spec) {
875
876
  });
876
877
  closeSync(stdout);
877
878
  closeSync(stderr);
879
+ child.on("error", (error) => appendFileSync(join(folder, "stderr.txt"), `${error.message}\n`));
878
880
  const exited = new Promise((resolve) => {
879
881
  child.on("exit", (exitCode, signal) => {
880
882
  writeFileSync(join(folder, "exit-code.txt"), `${exitCode ?? `signal ${signal}`}\n`);
@@ -926,13 +928,16 @@ const PORT_RANGE = {
926
928
  high: 2e4
927
929
  };
928
930
  const PORT_ATTEMPTS = 50;
931
+ function isAddressInfo(address) {
932
+ return address instanceof Object;
933
+ }
929
934
  function bindable(port) {
930
935
  return new Promise((resolve) => {
931
936
  const server = createServer();
932
937
  server.once("error", () => resolve(null));
933
938
  server.listen(port, "127.0.0.1", () => {
934
939
  const address = server.address();
935
- const bound = address !== null && address instanceof Object ? address.port : null;
940
+ const bound = isAddressInfo(address) ? address.port : null;
936
941
  server.close(() => resolve(bound));
937
942
  });
938
943
  });
@@ -955,15 +960,35 @@ async function freePort() {
955
960
  function reason(error) {
956
961
  return error.cause instanceof Error ? error.cause.message : error.message;
957
962
  }
958
- /** Sends one request and writes http.json with the status and body. */
963
+ /** Header names whose values http.json replaces with `<redacted>`, since `publish` pushes the evidence to the repository. */
964
+ const CREDENTIAL_HEADERS = /* @__PURE__ */ new Set([
965
+ "authorization",
966
+ "proxy-authorization",
967
+ "cookie",
968
+ "set-cookie"
969
+ ]);
970
+ function redacted(headers) {
971
+ return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, CREDENTIAL_HEADERS.has(name) ? "<redacted>" : value]));
972
+ }
973
+ /** The headers a request sends: `content-type: application/json` when it has a body, then the journey's headers over it, names lower-cased. */
974
+ function requestHeaders(init) {
975
+ const headers = new Headers(init.body ? { "content-type": "application/json" } : {});
976
+ for (const [name, value] of Object.entries(init.headers ?? {})) headers.set(name, value);
977
+ return headers;
978
+ }
979
+ /** Sends one request and writes http.json with the request it sent, and the status, headers and body of the answer, credential headers redacted. */
959
980
  async function httpRecorded(folder, url, init = {}) {
960
981
  mkdirSync(folder, { recursive: true });
982
+ const method = init.method ?? "GET";
983
+ let sent = {};
961
984
  let result;
962
985
  try {
986
+ const headers = requestHeaders(init);
987
+ sent = Object.fromEntries(headers);
963
988
  const response = await fetch(url, {
964
- method: init.method ?? "GET",
989
+ method,
965
990
  body: init.body,
966
- headers: init.body ? { "content-type": "application/json" } : void 0,
991
+ headers,
967
992
  signal: AbortSignal.timeout(init.timeoutMs ?? 5e3)
968
993
  });
969
994
  const body = await response.text();
@@ -977,6 +1002,7 @@ async function httpRecorded(folder, url, init = {}) {
977
1002
  folder,
978
1003
  url,
979
1004
  status: response.status,
1005
+ headers: Object.fromEntries(response.headers),
980
1006
  body,
981
1007
  json,
982
1008
  error: null
@@ -986,17 +1012,25 @@ async function httpRecorded(folder, url, init = {}) {
986
1012
  folder,
987
1013
  url,
988
1014
  status: null,
1015
+ headers: {},
989
1016
  body: "",
990
1017
  json: void 0,
991
1018
  error: error instanceof Error ? reason(error) : String(error)
992
1019
  };
993
1020
  }
1021
+ const request = {
1022
+ url,
1023
+ ...init,
1024
+ method,
1025
+ headers: redacted(sent)
1026
+ };
1027
+ const response = {
1028
+ ...result,
1029
+ headers: redacted(result.headers)
1030
+ };
994
1031
  writeFileSync(join(folder, "http.json"), `${JSON.stringify({
995
- request: {
996
- url,
997
- ...init
998
- },
999
- response: result
1032
+ request,
1033
+ response
1000
1034
  }, null, 2)}\n`);
1001
1035
  return result;
1002
1036
  }
@@ -1284,7 +1318,7 @@ function publishedPort(container, port) {
1284
1318
  if (!match) throw new Error(`${container} does not publish ${port}: ${mapping}`);
1285
1319
  return Number(match[1]);
1286
1320
  }
1287
- function waitReady(container, ready, folder) {
1321
+ function waitReady$1(container, ready, folder) {
1288
1322
  const deadline = Date.now() + READY_TIMEOUT_MS$1;
1289
1323
  let last = docker([
1290
1324
  "exec",
@@ -1347,7 +1381,7 @@ function startServices(workspace, state, prefix) {
1347
1381
  saveRun(state);
1348
1382
  container.port = publishedPort(name, definition.port);
1349
1383
  saveRun(state);
1350
- waitReady(name, definition.ready, join(folder, "02-ready"));
1384
+ waitReady$1(name, definition.ready, join(folder, "02-ready"));
1351
1385
  failed = false;
1352
1386
  } finally {
1353
1387
  state.timings.push({
@@ -1461,7 +1495,8 @@ function serializable(value) {
1461
1495
  function target(body) {
1462
1496
  const name = body.interface || interfaces[0];
1463
1497
  let owner;
1464
- let value = load(name, body.entry || ".");
1498
+ const list = entries[name] || ["."];
1499
+ let value = load(name, body.entry || (list.length === 1 ? list[0] : "."));
1465
1500
  for (const key of body.path) {
1466
1501
  owner = value;
1467
1502
  value = value[key];
@@ -1633,6 +1668,11 @@ function interfaceLinks(workspace, state) {
1633
1668
  const links = /* @__PURE__ */ new Map([["@antelopejs/interface-core", core]]);
1634
1669
  const entries = {};
1635
1670
  for (const name of implementedInterfaces(workspace.manifest)) {
1671
+ if (name === workspace.manifest.name) {
1672
+ links.set(name, realpathSync(workspace.root));
1673
+ entries[name] = runtimeEntries(workspace.manifest).filter((entry) => entry !== ".");
1674
+ continue;
1675
+ }
1636
1676
  const folder = installedPackage(workspace.root, name);
1637
1677
  links.set(name, folder);
1638
1678
  entries[name] = runtimeEntries(readPackage(folder));
@@ -1647,12 +1687,15 @@ function interfaceLinks(workspace, state) {
1647
1687
  * the driver module and, for the interface kind, the stub provider, or, for
1648
1688
  * the module kind, the module under verification as a `local` source. Every
1649
1689
  * interface the driver calls is linked to the copy the repository resolves,
1650
- * so the project shares one copy per interface as core requires.
1690
+ * so the project shares one copy per interface as core requires. An
1691
+ * interface of the module's own package links the repository root, whose
1692
+ * non-`.` runtime subpaths are its entries. Each of `companions` is loaded
1693
+ * too, but never in place of the module or the driver.
1651
1694
  */
1652
- function writeFixture(workspace, state, folder, moduleConfig) {
1695
+ function writeFixture(workspace, state, folder, configs) {
1653
1696
  const project = join(folder, "project");
1654
1697
  const { links, entries } = interfaceLinks(workspace, state);
1655
- const modules = {};
1698
+ const modules = { ...configs.companions };
1656
1699
  if (workspace.kind === "interface") {
1657
1700
  writeModule(join(project, "stub"), {
1658
1701
  name: "verify-stub",
@@ -1669,7 +1712,7 @@ function writeFixture(workspace, state, folder, moduleConfig) {
1669
1712
  type: "local",
1670
1713
  path: workspace.root
1671
1714
  },
1672
- config: moduleConfig
1715
+ config: configs.module
1673
1716
  };
1674
1717
  writeModule(join(project, "driver"), {
1675
1718
  name: "verify-driver",
@@ -2520,6 +2563,10 @@ function copyWorkingTree(root, target) {
2520
2563
  function templateName(workspace) {
2521
2564
  return workspace.config.template?.name ?? `Verify ${workspace.name}`;
2522
2565
  }
2566
+ /** The `ajs` command group that creates from the template: `module` for a module template, `project` otherwise. */
2567
+ function templateInit(workspace) {
2568
+ return workspace.config.template?.module === true ? "module" : "project";
2569
+ }
2523
2570
  /**
2524
2571
  * Builds the offline template source of a run: the template's working tree,
2525
2572
  * uncommitted changes included, as a local git repository, and an interfaces
@@ -2837,11 +2884,32 @@ const moduleDev = {
2837
2884
  context.expect(after.folder, [refused(after)]);
2838
2885
  }
2839
2886
  };
2840
- /** Scaffolds a project from the template with `ajs project init` and installs it; returns its folder. */
2841
- async function scaffoldProject(context) {
2842
- const project = join(context.work, "app");
2843
- const init = await context.scaffold("ajs project init", project);
2844
- context.expect(init.folder, [exitIs(init, 0), exists(join(project, "antelope.config.ts"))], { critical: true });
2887
+ /**
2888
+ * What `ajs <group> init` creates, by group: the file it writes at the root,
2889
+ * whether `pnpm run build` must run before `ajs project dev`, and the flags
2890
+ * of `ajs project dev`. A module builds first and runs in its `playground`
2891
+ * project, which loads the module's build output.
2892
+ */
2893
+ const CREATED = {
2894
+ project: {
2895
+ file: "antelope.config.ts",
2896
+ build: false,
2897
+ dev: ["--watch"]
2898
+ },
2899
+ module: {
2900
+ file: "package.json",
2901
+ build: true,
2902
+ dev: [
2903
+ "--watch",
2904
+ "--project",
2905
+ "playground"
2906
+ ]
2907
+ }
2908
+ };
2909
+ /** Scaffolds a project, or a module for a module template, from the template into `project` with `ajs project init` or `ajs module init` and installs it. */
2910
+ async function scaffoldInto(context, project) {
2911
+ const init = await context.scaffold(`ajs ${templateInit(context.workspace)} init`, project);
2912
+ context.expect(init.folder, [exitIs(init, 0)], { critical: true });
2845
2913
  context.tree("scaffolded tree", project);
2846
2914
  const install = await context.command("pnpm install", "pnpm", [
2847
2915
  "install",
@@ -2849,6 +2917,21 @@ async function scaffoldProject(context) {
2849
2917
  "--prefer-offline"
2850
2918
  ], { cwd: project });
2851
2919
  context.expect(install.folder, [exitIs(install, 0)], { critical: true });
2920
+ }
2921
+ /**
2922
+ * The journey's copy of the project scaffolded from the template and
2923
+ * installed, built once per run under the key `scaffolded`, which a repo
2924
+ * journey shares by preparing it with the same init and install. The copy is
2925
+ * checked for the file its init writes whichever journey built it, and the
2926
+ * journey's own HOME is pointed at the offline manifest again, since the
2927
+ * build's HOME is gone.
2928
+ */
2929
+ async function scaffoldProject(context) {
2930
+ const project = await context.prepared("scaffolded", (folder) => scaffoldInto(context, folder));
2931
+ const tree = context.tree("scaffolded project", project);
2932
+ const created = CREATED[templateInit(context.workspace)];
2933
+ context.expect(tree.folder, [exists(join(project, created.file))], { critical: true });
2934
+ await context.configureGit();
2852
2935
  return project;
2853
2936
  }
2854
2937
  /** The journeys each kind ships, by id; a feature file names them next to its repo-owned journeys. */
@@ -2857,17 +2940,23 @@ const BUILTIN_JOURNEYS = {
2857
2940
  module: { "module-dev": moduleDev },
2858
2941
  template: {
2859
2942
  "scaffold-dev": {
2860
- title: "a project scaffolded from the template installs, starts and answers",
2861
- entryPoint: "`ajs project init --template` from the interfaces manifest, then `ajs project dev --watch`, as the template's `pnpm dev` runs it",
2943
+ title: "a project, or a module, scaffolded from the template installs, starts and answers",
2944
+ entryPoint: "`ajs project init --template` from the interfaces manifest, then `ajs project dev --watch`, as the template's `pnpm dev` runs it; for a module template `ajs module init --template`, `pnpm run build`, then `ajs project dev --watch --project playground`",
2862
2945
  async run(context) {
2863
- const app = await context.dev("ajs project dev --watch", await scaffoldProject(context), { args: ["--watch"] });
2946
+ const created = CREATED[templateInit(context.workspace)];
2947
+ const project = await scaffoldProject(context);
2948
+ if (created.build) {
2949
+ const build = await context.command("pnpm run build", "pnpm", ["run", "build"], { cwd: project });
2950
+ context.expect(build.folder, [exitIs(build, 0)], { critical: true });
2951
+ }
2952
+ const app = await context.dev(`ajs project dev ${created.dev.join(" ")}`, project, { args: [...created.dev] });
2864
2953
  const stopped = await context.stop("SIGINT", app);
2865
2954
  context.expect(stopped.folder, [interrupted(stopped)]);
2866
2955
  }
2867
2956
  },
2868
2957
  "scaffold-checks": {
2869
- title: "a project scaffolded from the template passes its own checks",
2870
- entryPoint: "`ajs project init --template` from the interfaces manifest, then `pnpm run checks`",
2958
+ title: "a project, or a module, scaffolded from the template passes its own checks",
2959
+ entryPoint: "`ajs project init --template`, or `ajs module init --template` for a module template, from the interfaces manifest, then `pnpm run checks`",
2871
2960
  async run(context) {
2872
2961
  const project = await scaffoldProject(context);
2873
2962
  const checks = await context.command("pnpm run checks", "pnpm", ["run", "checks"], { cwd: project });
@@ -2902,77 +2991,338 @@ function appFault(started) {
2902
2991
  return null;
2903
2992
  }
2904
2993
  //#endregion
2905
- //#region src/verify/caches.ts
2906
- /** Where `ajs` installs the modules of a project that names no other `cacheFolder`. */
2907
- const PROJECT_CACHE = join(".antelope", "cache");
2908
- const MANIFEST = "manifest.json";
2909
- /** Where `ajs` keeps a project's lock records, one folder per `<package>@<version>`. */
2910
- const LOCK_FOLDER = "antelope-lock";
2911
- /** How many milliseconds the harness waits at most for the file system clock to pass an install. */
2912
- const CLOCK_ATTEMPTS = 100;
2913
- /** A start time later than every command's, for a module the harness first sees outside a command: any lock record it has counts as one `ajs` installed it from. */
2914
- const UNKNOWN_START = 2n ** 63n;
2915
- /** A version `ajs` records for a registry package; a git module records `git:<branch>:<commit>`. */
2916
- const REGISTRY_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?$/;
2917
- /** When the folder at `path` was created, which tells apart the folders created one after another there even when the file system reuses the inode; `0n` when the file system does not record it. */
2918
- function bornAt(path) {
2994
+ //#region src/verify/prepared.ts
2995
+ const KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
2996
+ /** The path of `path` inside `root`, or `null` when it lies outside. */
2997
+ function inside(root, path) {
2998
+ const rest = relative(root, path);
2999
+ if (rest === ".." || rest.startsWith(`..${sep}`) || isAbsolute(rest)) return null;
3000
+ return rest;
3001
+ }
3002
+ /** Surveys `folder` in one walk that descends only into real directories, so it never follows a symlink; a target may name the folder by its real path. */
3003
+ function survey(folder) {
3004
+ const real = realpathSync(folder);
3005
+ const found = {
3006
+ links: [],
3007
+ special: null
3008
+ };
3009
+ const walk = (at) => {
3010
+ for (const entry of readdirSync(join(folder, at), { withFileTypes: true })) {
3011
+ const path = join(at, entry.name);
3012
+ if (entry.isDirectory()) walk(path);
3013
+ else if (entry.isSymbolicLink()) {
3014
+ const pointed = readlinkSync(join(folder, path));
3015
+ const target = isAbsolute(pointed) ? inside(folder, pointed) ?? inside(real, pointed) : null;
3016
+ if (target !== null) found.links.push({
3017
+ path,
3018
+ target
3019
+ });
3020
+ } else if (!entry.isFile()) found.special ??= path;
3021
+ }
3022
+ };
3023
+ walk("");
3024
+ return found;
3025
+ }
3026
+ /** The files under `source` with a hard link outside it, such as package files pnpm links from its store; a file linked only within `source` is not one. */
3027
+ function sharedOutside(source) {
3028
+ const inodes = /* @__PURE__ */ new Map();
3029
+ const walk = (folder) => {
3030
+ for (const entry of readdirSync(folder, { withFileTypes: true })) {
3031
+ const path = join(folder, entry.name);
3032
+ if (entry.isDirectory()) walk(path);
3033
+ else if (entry.isFile()) {
3034
+ const { dev, ino, nlink } = lstatSync(path, { bigint: true });
3035
+ if (nlink < 2n) continue;
3036
+ const key = `${dev}:${ino}`;
3037
+ const inode = inodes.get(key) ?? {
3038
+ nlink,
3039
+ paths: []
3040
+ };
3041
+ inode.paths.push(path);
3042
+ inodes.set(key, inode);
3043
+ }
3044
+ }
3045
+ };
3046
+ walk(source);
3047
+ return new Set([...inodes.values()].filter((inode) => inode.nlink > BigInt(inode.paths.length)).flatMap((inode) => inode.paths));
3048
+ }
3049
+ /** Hard-links `from` at `to` unless the filesystem allows `from` no more links; returns whether it did. */
3050
+ function linked(from, to) {
2919
3051
  try {
2920
- return lstatSync(path, { bigint: true }).birthtimeNs;
2921
- } catch {
2922
- return 0n;
3052
+ linkSync(from, to);
3053
+ return true;
3054
+ } catch (error) {
3055
+ if (error instanceof Error && "code" in error && error.code === "EMLINK") return false;
3056
+ throw error;
2923
3057
  }
2924
3058
  }
2925
- /** Whether `project` held the lock record of `name@version` when a command that started at `start` began; `ajs` writes a record only after an install that used none. */
2926
- function pinned(project, name, version, start) {
3059
+ /** Copies the tree at `source` to the new path `target` without following a symlink, linking each of `shared`; any other file is cloned where the filesystem can, else copied, with its timestamps. */
3060
+ function cloneTree(source, target, shared) {
3061
+ mkdirSync(target);
3062
+ for (const entry of readdirSync(source, { withFileTypes: true })) {
3063
+ const from = join(source, entry.name);
3064
+ const to = join(target, entry.name);
3065
+ if (entry.isDirectory()) cloneTree(from, to, shared);
3066
+ else if (entry.isSymbolicLink()) symlinkSync(readlinkSync(from), to);
3067
+ else if (!shared.has(from) || !linked(from, to)) {
3068
+ copyFileSync(from, to, constants.COPYFILE_FICLONE);
3069
+ const { atimeMs, mtimeMs } = statSync(from);
3070
+ utimesSync(to, atimeMs / 1e3, mtimeMs / 1e3);
3071
+ }
3072
+ }
3073
+ chmodSync(target, statSync(source).mode);
3074
+ }
3075
+ /**
3076
+ * Copies `source` to `target`, which ends up at `root`. Each of `links`
3077
+ * points to its target inside `root`, so no copy reaches another journey's
3078
+ * folder. Every other symlink keeps its target, so pnpm's relative links in a
3079
+ * copy never point back into the source. A file with a hard link outside
3080
+ * `source` is linked, not copied.
3081
+ */
3082
+ function copyTree(source, target, links = [], root = target) {
3083
+ cloneTree(source, target, sharedOutside(source));
3084
+ for (const link of links) {
3085
+ unlinkSync(join(target, link.path));
3086
+ symlinkSync(join(root, link.target), join(target, link.path));
3087
+ }
3088
+ }
3089
+ /** Writes `content` to `file`, through a new inode renamed over it when the file has other hard links, so the write reaches no other path, such as a copy `prepared` linked or pnpm's store, and a failed write leaves the file as it was. */
3090
+ function writeOwn(file, content) {
3091
+ const before = existsSync(file) ? statSync(file) : null;
3092
+ if (before === null || before.nlink < 2) {
3093
+ writeFileSync(file, content);
3094
+ return;
3095
+ }
3096
+ const real = realpathSync(file);
3097
+ accessSync(real, constants.W_OK);
3098
+ const scratch = mkdtempSync(join(dirname(real), ".edit-"));
2927
3099
  try {
2928
- const record = join(project, LOCK_FOLDER, `${name}@${version}`);
2929
- return lstatSync(record, { bigint: true }).mtimeNs <= start;
2930
- } catch {
3100
+ const fresh = join(scratch, "file");
3101
+ writeFileSync(fresh, content, { mode: before.mode });
3102
+ chmodSync(fresh, before.mode);
3103
+ renameSync(fresh, real);
3104
+ } finally {
3105
+ removeTree(scratch);
3106
+ }
3107
+ }
3108
+ /** Judges the build of `folder` by the steps it recorded. */
3109
+ function judge$1(steps, folder) {
3110
+ const checks = steps.flatMap((step) => step.checks);
3111
+ if (checks.length === 0) return {
3112
+ kept: false,
3113
+ reason: "the build recorded no check"
3114
+ };
3115
+ if (!checks.every((check) => check.pass)) return {
3116
+ kept: false,
3117
+ reason: "a check of the build failed"
3118
+ };
3119
+ const found = survey(folder);
3120
+ return found.special === null ? {
3121
+ kept: true,
3122
+ links: found.links
3123
+ } : {
3124
+ kept: false,
3125
+ reason: `${found.special} is not a file, directory or symlink, which a copy would drop`
3126
+ };
3127
+ }
3128
+ /** The links `keep` recorded, each a path then its target, joined by NUL, the one character no path holds. */
3129
+ function readLinks(kept) {
3130
+ const fields = readFileSync(join(kept, "links"), "utf8").split("\0");
3131
+ const links = [];
3132
+ for (let at = 0; at + 1 < fields.length; at += 2) links.push({
3133
+ path: fields[at],
3134
+ target: fields[at + 1]
3135
+ });
3136
+ return links;
3137
+ }
3138
+ /** The projects `keep` recorded; a build kept without the list holds none. */
3139
+ function readProjects(kept) {
3140
+ const file = join(kept, "projects.json");
3141
+ if (!existsSync(file)) return [];
3142
+ const listed = parseJson(readFileSync(file, "utf8"));
3143
+ return Array.isArray(listed) ? listed.filter(isObject).flatMap(({ path, cache }) => isString(path) ? [{
3144
+ path,
3145
+ cache: Array.isArray(cache) ? cache.filter(isString) : null
3146
+ }] : []) : [];
3147
+ }
3148
+ /** The journey that built what the run kept, as its path under the evidence. */
3149
+ function builder(kept) {
3150
+ return readFileSync(join(kept, "from.txt"), "utf8").trim();
3151
+ }
3152
+ /**
3153
+ * Copies what the run kept into the journey, with the evidence of that build
3154
+ * under the step `marker`, seeds each project the build seeded as
3155
+ * `scaffold` does, and returns `null`. When the copy fails, or what the run
3156
+ * kept is gone or replaced once it ends, as when the journey that built
3157
+ * reruns meanwhile, the partial copy is removed and this returns why.
3158
+ */
3159
+ function reuse$1(context, { marker, key, kept, folder }) {
3160
+ const evidence = join(marker, "build");
3161
+ try {
3162
+ const memo = statSync(kept).ino;
3163
+ copyTree(join(kept, "evidence"), evidence);
3164
+ copyTree(join(kept, "folder"), folder, readLinks(kept));
3165
+ const from = builder(kept);
3166
+ const projects = readProjects(kept);
3167
+ if (statSync(kept).ino !== memo) throw new Error(`${kept} was replaced while it was copied`);
3168
+ writeFileSync(join(marker, "prepared.txt"), `${key}: ${folder} is a copy of what ${from} prepared; build/ holds the evidence of that build\n`);
3169
+ for (const project of projects) context.caches.seed(join(folder, project.path), project.cache);
3170
+ return null;
3171
+ } catch (error) {
3172
+ removeTree(evidence);
3173
+ removeTree(folder);
3174
+ return error instanceof Error ? error.message : String(error);
3175
+ }
3176
+ }
3177
+ /** Removes what the run kept by first renaming it away, so a journey copying it meanwhile fails instead of copying a half-deleted tree. */
3178
+ function drop(kept) {
3179
+ const trash = mkdtempSync(`${kept}.`);
3180
+ renameSync(kept, join(trash, "dropped"));
3181
+ removeTree(trash);
3182
+ }
3183
+ /** Keeps the built folder and the build's step evidence for the rest of the run, published by one rename; when another journey kept the key first, its copy stays and this returns `false`. */
3184
+ function keep(context, kept, folder, built) {
3185
+ mkdirSync(dirname(kept), { recursive: true });
3186
+ const staging = mkdtempSync(`${kept}.`);
3187
+ try {
3188
+ mkdirSync(join(staging, "evidence"));
3189
+ for (const step of built.steps) copyTree(join(context.folder, step), join(staging, "evidence", step));
3190
+ copyTree(folder, join(staging, "folder"), built.links, join(kept, "folder"));
3191
+ writeFileSync(join(staging, "links"), built.links.flatMap((link) => [link.path, link.target]).join("\0"));
3192
+ writeFileSync(join(staging, "projects.json"), JSON.stringify(built.projects));
3193
+ writeFileSync(join(staging, "from.txt"), `${relative(context.state.evidence, context.folder)}\n`);
3194
+ renameSync(staging, kept);
3195
+ return true;
3196
+ } catch (error) {
3197
+ if (!existsSync(kept)) throw error;
2931
3198
  return false;
3199
+ } finally {
3200
+ removeTree(staging);
2932
3201
  }
2933
3202
  }
2934
- function names(folder) {
3203
+ /** Runs `build` with a HOME of its own for its commands, deleted when it ends. */
3204
+ async function buildAlone(context, key, folder, build) {
3205
+ const outer = context.buildHome;
3206
+ const home = join(context.home, `.prepared-${key}`);
3207
+ mkdirSync(home, { recursive: true });
3208
+ context.buildHome = home;
2935
3209
  try {
2936
- return readdirSync(folder).filter((name) => !name.startsWith("."));
2937
- } catch {
2938
- return [];
3210
+ await build(folder);
3211
+ } finally {
3212
+ context.buildHome = outer;
3213
+ removeTree(home);
3214
+ }
3215
+ }
3216
+ /** Builds `key` in this journey after the step `marker`, which marks the steps after it as the build and says, after `before`, whether the run kept it. */
3217
+ async function buildHere(context, where, build, before = "") {
3218
+ const { marker, key, kept, folder } = where;
3219
+ const note = (outcome) => writeFileSync(join(marker, "prepared.txt"), `${key}: ${before}${folder} was built here by the steps after this one; ${outcome}\n`);
3220
+ const earlier = new Set(readdirSync(context.folder));
3221
+ const checked = context.steps.length;
3222
+ mkdirSync(folder, { recursive: true });
3223
+ try {
3224
+ await buildAlone(context, key, folder, build);
3225
+ } catch (error) {
3226
+ note("not kept: the build threw, so the next journey builds again");
3227
+ throw error;
3228
+ }
3229
+ const verdict = judge$1(context.steps.slice(checked), folder);
3230
+ if (!verdict.kept) {
3231
+ note(`not kept: ${verdict.reason}, so the next journey builds again`);
3232
+ return;
3233
+ }
3234
+ const steps = readdirSync(context.folder).filter((entry) => !earlier.has(entry));
3235
+ const projects = context.caches.seeded().flatMap((project) => {
3236
+ const path = inside(folder, project);
3237
+ return path === null || !existsSync(project) ? [] : [{
3238
+ path,
3239
+ cache: context.caches.clean(project)
3240
+ }];
3241
+ });
3242
+ note(keep(context, kept, folder, {
3243
+ steps,
3244
+ links: verdict.links,
3245
+ projects
3246
+ }) ? "kept, so later journeys of the run copy it" : `not kept: ${builder(kept)} kept ${key} first, so later journeys copy that build`);
3247
+ }
3248
+ /** `JourneyContext.prepared` for one journey of the run. */
3249
+ async function prepare(context, key, build) {
3250
+ if (!KEY.test(key)) throw new Error(`prepared key ${JSON.stringify(key)} must be lowercase letters and digits joined by dashes`);
3251
+ const folder = join(context.work, key);
3252
+ if (existsSync(folder)) throw new Error(`${folder} already exists: a journey prepares ${key} once`);
3253
+ const kept = join(context.state.dir, "prepared", key);
3254
+ if (existsSync(kept) && builder(kept) === relative(context.state.evidence, context.folder)) drop(kept);
3255
+ const where = {
3256
+ marker: context.step(`prepared ${key}`),
3257
+ key,
3258
+ kept,
3259
+ folder
3260
+ };
3261
+ if (!existsSync(kept)) await buildHere(context, where, build);
3262
+ else {
3263
+ const failed = reuse$1(context, where);
3264
+ if (failed !== null) await buildHere(context, where, build, `copying what the run kept failed (${failed}), so `);
2939
3265
  }
3266
+ return folder;
2940
3267
  }
2941
- /** Every entry under `root`, by its path relative to `root`, with its modification time; symbolic links are listed, not followed. */
2942
- function* entries(root, prefix = "") {
3268
+ //#endregion
3269
+ //#region src/verify/cache-copy.ts
3270
+ /** The file `ajs` lists a project cache's modules in, each name with its version. */
3271
+ const MANIFEST = "manifest.json";
3272
+ /** Stands in a kept cache for the path of the project cache it was kept from, which pnpm 10 and 11 write into the `NODE_PATH` of each `.bin` shim. */
3273
+ const KEPT_CACHE = `${sep}@antelopejs-verify-kept-cache@${sep}`;
3274
+ /** Whether `path` is `folder` or lies under it. */
3275
+ function within(folder, path) {
3276
+ return path === folder || path.startsWith(`${folder}${sep}`);
3277
+ }
3278
+ /** Every entry under `root` but those `skip` names and what they hold, by its path relative to `root`, with its modification time; symbolic links are listed, not followed. */
3279
+ function* entries(root, skip = () => false, prefix = "") {
2943
3280
  for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
2944
3281
  const path = join(prefix, entry.name);
3282
+ if (skip(path)) continue;
2945
3283
  const directory = entry.isDirectory();
2946
3284
  yield {
2947
3285
  path,
2948
3286
  mtime: lstatSync(join(root, path), { bigint: true }).mtimeNs,
2949
3287
  directory
2950
3288
  };
2951
- if (directory) yield* entries(root, path);
3289
+ if (directory) yield* entries(root, skip, path);
2952
3290
  }
2953
3291
  }
2954
- /** Whether a project's antelope config (antelope.json or antelope.config.*) mentions `cacheFolder`, so `ajs` may install somewhere other than `.antelope/cache`. */
2955
- function namesCacheFolder(project) {
2956
- try {
2957
- return readdirSync(project).filter((name) => /^antelope(\.config)?\.[cm]?[jt]s(on)?$/.test(name)).some((name) => /\bcacheFolder\b/.test(readFileSync(join(project, name), "utf8")));
2958
- } catch {
2959
- return false;
3292
+ /** The path a module installed into `cache` finds it at, with its symbolic links resolved as the working directory of `pnpm` resolves them, ending with a separator. */
3293
+ function cachePath(cache) {
3294
+ return join(realpathSync(dirname(cache)), basename(cache)) + sep;
3295
+ }
3296
+ /** Replaces each of `from`, in order, by `to` in every `.bin` shim under `folder`, never through a hard link another path shares. */
3297
+ function retarget(folder, from, to) {
3298
+ for (const { path, directory } of entries(folder)) {
3299
+ if (directory || basename(dirname(path)) !== ".bin") continue;
3300
+ const file = join(folder, path);
3301
+ if (!lstatSync(file).isFile()) continue;
3302
+ const text = readFileSync(file, "utf8");
3303
+ const shim = from.reduce((current, old) => current.replaceAll(old, () => to), text);
3304
+ if (shim !== text) writeOwn(file, shim);
2960
3305
  }
2961
3306
  }
2962
3307
  /**
2963
- * Copies `source` into a staging entry next to `target` and renames it onto
2964
- * `target`, so a reader sees all of the copy or none of it. A failed copy, a
2965
- * deleted source or a `target` another writer filled first leaves `target`
2966
- * as it was.
3308
+ * Copies `source` into a staging entry next to `target`, replaces each of
3309
+ * `from` by `to` in its `.bin` shims, and renames it onto `target`, so a
3310
+ * reader sees all of the copy or none of it. A failed copy, a deleted source
3311
+ * or a `target` another writer filled first leaves `target` as it was. With
3312
+ * `only`, the copy leaves out every other module's folder and its manifest
3313
+ * lists those modules alone.
2967
3314
  */
2968
- function publish(source, target) {
3315
+ function publish(source, target, from, to, only) {
2969
3316
  const staging = join(dirname(target), `.staging-${randomBytes(6).toString("hex")}`);
2970
3317
  try {
2971
3318
  cpSync(source, staging, {
2972
3319
  recursive: true,
2973
3320
  verbatimSymlinks: true,
2974
- preserveTimestamps: true
3321
+ preserveTimestamps: true,
3322
+ filter: (path) => only === void 0 || !only.left.some((name) => within(join(source, name), path))
2975
3323
  });
3324
+ if (only !== void 0) writeFileSync(join(staging, MANIFEST), JSON.stringify(Object.fromEntries(only.modules)));
3325
+ retarget(staging, from, to);
2976
3326
  renameSync(staging, target);
2977
3327
  } catch {
2978
3328
  return;
@@ -2980,15 +3330,76 @@ function publish(source, target) {
2980
3330
  removeTree(staging);
2981
3331
  }
2982
3332
  }
2983
- /** The manifest `ajs` writes each time it finishes installing a module: its modification time and each module's version, sorted by module. */
2984
- function manifestOf(cache) {
2985
- try {
2986
- const file = join(cache, MANIFEST);
2987
- const manifest = parseJson(readFileSync(file, "utf8"));
2988
- if (!isObject(manifest)) return void 0;
2989
- const modules = Object.entries(manifest).map(([name, version]) => [name, String(version)]).sort(([left], [right]) => left < right ? -1 : 1);
2990
- return {
2991
- mtime: lstatSync(file, { bigint: true }).mtimeNs,
3333
+ //#endregion
3334
+ //#region src/verify/caches.ts
3335
+ /** Where `ajs` installs the modules of a project that names no other `cacheFolder`. */
3336
+ const PROJECT_CACHE = join(".antelope", "cache");
3337
+ /** Where `ajs` keeps a project's lock records, one folder per `<package>@<version>`. */
3338
+ const LOCK_FOLDER = "antelope-lock";
3339
+ /** How many milliseconds the harness waits at most for the file system clock to pass an install. */
3340
+ const CLOCK_ATTEMPTS = 100;
3341
+ /** A start time later than every command's, for a module the harness first sees outside a command: any lock record it has counts as one `ajs` installed it from. */
3342
+ const UNKNOWN_START = 2n ** 63n;
3343
+ /** A version `ajs` records for a registry package; a git module records `git:<branch>:<commit>`. */
3344
+ const REGISTRY_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?$/;
3345
+ /** When the folder at `path` was created, which tells apart the folders created one after another there even when the file system reuses the inode; `0n` when the file system does not record it. */
3346
+ function bornAt(path) {
3347
+ try {
3348
+ return lstatSync(path, { bigint: true }).birthtimeNs;
3349
+ } catch {
3350
+ return 0n;
3351
+ }
3352
+ }
3353
+ /** Whether `project` held the lock record of `name@version` when a command that started at `start` began; `ajs` writes a record only after an install that used none. */
3354
+ function pinned(project, name, version, start) {
3355
+ try {
3356
+ const record = join(project, LOCK_FOLDER, `${name}@${version}`);
3357
+ return lstatSync(record, { bigint: true }).mtimeNs <= start;
3358
+ } catch {
3359
+ return false;
3360
+ }
3361
+ }
3362
+ function names(folder) {
3363
+ try {
3364
+ return readdirSync(folder).filter((name) => !name.startsWith("."));
3365
+ } catch {
3366
+ return [];
3367
+ }
3368
+ }
3369
+ /** Why a module the harness recorded as `known` is no longer that install, now that the manifest lists `version` in a folder created at `born`. */
3370
+ function reinstalled(name, known, version, born) {
3371
+ if (known.version !== version) return `${name} changed from ${known.version} to ${version} after ajs installed it`;
3372
+ if (born !== known.born) return `${name} was created again after ajs installed ${name}@${version}`;
3373
+ }
3374
+ /** Whether a project's antelope config (antelope.json or antelope.config.*) mentions `cacheFolder`, so `ajs` may install somewhere other than `.antelope/cache`. */
3375
+ function namesCacheFolder(project) {
3376
+ try {
3377
+ return readdirSync(project).filter((name) => /^antelope(\.config)?\.[cm]?[jt]s(on)?$/.test(name)).some((name) => /\bcacheFolder\b/.test(readFileSync(join(project, name), "utf8")));
3378
+ } catch {
3379
+ return false;
3380
+ }
3381
+ }
3382
+ /** Why a registry module the project followed is no longer among `modules`, or `undefined` when each still is. */
3383
+ function departure(state, modules) {
3384
+ const listed = new Set(modules.map(([name]) => name));
3385
+ for (const [name, known] of state.installed) if (!listed.has(name)) return `${name} left ${MANIFEST} after ajs installed ${name}@${known.version}`;
3386
+ }
3387
+ /** Whether `name`, listed at `version`, is a git module `state` does not follow; one seen for the first time joins `added`. */
3388
+ function recordGit(state, name, version, added) {
3389
+ if (state.installed.has(name) || REGISTRY_VERSION.test(version)) return false;
3390
+ if (!state.git.has(name)) added.push(`${name}@${version}`);
3391
+ state.git.add(name);
3392
+ return true;
3393
+ }
3394
+ /** The manifest `ajs` writes each time it finishes installing a module: its modification time and each module's version, sorted by module. */
3395
+ function manifestOf(cache) {
3396
+ try {
3397
+ const file = join(cache, MANIFEST);
3398
+ const manifest = parseJson(readFileSync(file, "utf8"));
3399
+ if (!isObject(manifest)) return void 0;
3400
+ const modules = Object.entries(manifest).map(([name, version]) => [name, String(version)]).sort(([left], [right]) => left < right ? -1 : 1);
3401
+ return {
3402
+ mtime: lstatSync(file, { bigint: true }).mtimeNs,
2992
3403
  modules
2993
3404
  };
2994
3405
  } catch {
@@ -2999,27 +3410,36 @@ function manifestOf(cache) {
2999
3410
  * Why `cache` is not exactly what `ajs` installed, or `undefined` when it is.
3000
3411
  * Each file of a module must be no newer than the module's bound. Outside the
3001
3412
  * modules, `ajs` writes only the manifest and the folders that hold the
3002
- * modules, which must be no newer than the manifest.
3413
+ * modules, which must be no newer than `folders`: the manifest's time, or the
3414
+ * bound of a cache copied in whole when that is later, since a copy gives its
3415
+ * folders the time of the copy. Entries under the folders in `left`, which the
3416
+ * kept copy leaves out, are not checked.
3003
3417
  */
3004
- function changeIn(cache, installed, manifest) {
3418
+ function changeIn(cache, installed, folders, left) {
3005
3419
  const modules = [...installed].map(([name, module]) => ({
3006
3420
  folder: join(name),
3007
3421
  label: `${name}@${module.version}`,
3008
3422
  bound: module.bound
3009
3423
  }));
3010
3424
  try {
3011
- for (const { path, mtime, directory } of entries(cache)) {
3012
- if (path === MANIFEST) continue;
3013
- const owner = modules.find(({ folder }) => path === folder || path.startsWith(`${folder}${sep}`));
3425
+ for (const { path, mtime, directory } of entries(cache, (path) => left.includes(path))) {
3426
+ if (path === "manifest.json") continue;
3427
+ const owner = modules.find(({ folder }) => within(folder, path));
3014
3428
  if (owner === void 0) {
3015
3429
  if (!directory) return `${path} belongs to no installed module`;
3016
- if (mtime > manifest) return `${path} changed after ajs wrote ${MANIFEST}`;
3430
+ if (mtime > folders) return `${path} changed after ajs wrote ${MANIFEST}`;
3017
3431
  } else if (mtime > owner.bound) return `${path} changed after ajs installed ${owner.label}`;
3018
3432
  }
3019
3433
  } catch (error) {
3020
3434
  return `it could not be read: ${error instanceof Error ? error.message : String(error)}`;
3021
3435
  }
3022
3436
  }
3437
+ /** Why the cache of a followed project is not exactly what a fresh `ajs` install gives, or `undefined` when it is. */
3438
+ function refusal(cache, state, manifest) {
3439
+ const left = manifest.modules.filter(([, version]) => !REGISTRY_VERSION.test(version)).map(([name]) => name);
3440
+ const folders = state.copied !== void 0 && state.copied > manifest.mtime ? state.copied : manifest.mtime;
3441
+ return state.refused ?? (left.length === manifest.modules.length ? `${manifest.modules[0]?.join("@")} is not a registry version, and ajs updates a git module in place` : changeIn(cache, state.installed, folders, left));
3442
+ }
3023
3443
  /**
3024
3444
  * The module caches of the projects one journey creates, and the run's kept
3025
3445
  * copies of them in `store`. Kept copies are never written, so journeys of
@@ -3030,9 +3450,12 @@ function changeIn(cache, installed, manifest) {
3030
3450
  * `manifest.json`, so the manifest's modification time when the harness first
3031
3451
  * sees the module bounds every file of it. A file modified later, a module
3032
3452
  * whose version or folder changes after that, a module `ajs` installed from a
3033
- * lock record the project held before the command, and a git module, which
3034
- * `ajs` updates in place and builds with the project's own install command,
3035
- * each keep the cache out of the store.
3453
+ * lock record the project held before the command, and two modules that
3454
+ * first appear after one command that is not `ajs`, which may have edited the
3455
+ * first before installing the second, each keep the cache out of the store. A
3456
+ * git module, which `ajs` updates in place and builds with the project's own
3457
+ * install command, is never followed nor kept: the copy holds the cache's
3458
+ * registry modules alone.
3036
3459
  */
3037
3460
  var ProjectCaches = class {
3038
3461
  store;
@@ -3040,14 +3463,24 @@ var ProjectCaches = class {
3040
3463
  constructor(store) {
3041
3464
  this.store = store;
3042
3465
  }
3043
- /** Gives a project that has installed no module yet a copy of the largest kept cache, so `ajs` reuses the packages an earlier journey installed instead of packing and installing them again. A project whose antelope config names its own `cacheFolder` gets no copy, since `ajs` would not read `.antelope/cache`. */
3044
- seed(project) {
3045
- const state = { installed: /* @__PURE__ */ new Map() };
3466
+ /**
3467
+ * Gives a project that has installed no module yet a copy of the largest kept cache, so `ajs` reuses the packages an earlier journey installed instead of packing and installing them again. A project whose antelope config names its own `cacheFolder` gets no copy, since `ajs` would not read `.antelope/cache`.
3468
+ * A project that already holds modules is followed from what it holds. When `copiedFrom` is given, that cache is a copy of the cache `clean` accepted and named by those paths: its `.bin` shims are pointed at this project's cache and it is followed as a copy from the store is.
3469
+ */
3470
+ seed(project, copiedFrom = null) {
3471
+ const state = {
3472
+ installed: /* @__PURE__ */ new Map(),
3473
+ git: /* @__PURE__ */ new Set()
3474
+ };
3046
3475
  this.projects.set(project, state);
3047
3476
  if (namesCacheFolder(project)) return;
3048
3477
  const cache = join(project, PROJECT_CACHE);
3049
3478
  if ((manifestOf(cache)?.modules.length ?? 0) > 0) {
3050
- this.observe();
3479
+ if (copiedFrom === null) this.observe();
3480
+ else {
3481
+ retarget(cache, copiedFrom, cachePath(cache));
3482
+ this.adopt(state, cache);
3483
+ }
3051
3484
  return;
3052
3485
  }
3053
3486
  let largest;
@@ -3061,7 +3494,11 @@ var ProjectCaches = class {
3061
3494
  }
3062
3495
  if (largest === void 0) return;
3063
3496
  mkdirSync(dirname(cache), { recursive: true });
3064
- publish(largest.folder, cache);
3497
+ publish(largest.folder, cache, [KEPT_CACHE], cachePath(cache));
3498
+ this.adopt(state, cache);
3499
+ }
3500
+ /** Follows each module of a cache copied whole from one exactly as `ajs` installed it, bounded by the newest entry of the copy, since a copy gives its folders the time of the copy. */
3501
+ adopt(state, cache) {
3065
3502
  const copied = manifestOf(cache);
3066
3503
  if (copied === void 0) return;
3067
3504
  let bound = copied.mtime;
@@ -3075,27 +3512,45 @@ var ProjectCaches = class {
3075
3512
  born: bornAt(join(cache, name)),
3076
3513
  bound
3077
3514
  });
3515
+ state.copied = bound;
3078
3516
  this.passClock(bound);
3079
3517
  }
3518
+ /** Every project seeded so far, so a copy of a folder that holds some can seed its own. */
3519
+ seeded() {
3520
+ return [...this.projects.keys()];
3521
+ }
3522
+ /** When the cache of a seeded `project` holds no module, or only registry modules exactly as `ajs` installed them, the paths its `.bin` shims may name, resolved and as given, which `seed` takes as `copiedFrom` for a copy of it; `null` otherwise. */
3523
+ clean(project) {
3524
+ this.observe();
3525
+ const state = this.projects.get(project);
3526
+ const cache = join(project, PROJECT_CACHE);
3527
+ const manifest = manifestOf(cache);
3528
+ return (manifest === void 0 || manifest.modules.length === 0 || state !== void 0 && manifest.modules.every(([, version]) => REGISTRY_VERSION.test(version)) && refusal(cache, state, manifest) === void 0) && existsSync(cache) ? [cachePath(cache), cache + sep] : null;
3529
+ }
3080
3530
  /**
3081
- * Records the bound of each module that appeared in a project's manifest
3531
+ * Records the bound of each registry module that appeared in a project's manifest
3082
3532
  * since the last call, and refuses the cache of a project whose recorded
3083
3533
  * module left the manifest, changed version or sits in a new folder. A
3084
3534
  * module that appeared with a lock record no newer than `start`, the start
3085
- * of the command that just ended, was installed from that record.
3535
+ * of the command that just ended, was installed from that record. After a
3536
+ * command that is not `ajs`, `ajs` may not be alone between two installs, so a
3537
+ * project whose manifest gained more than one module is refused.
3086
3538
  */
3087
- observe(start = UNKNOWN_START) {
3539
+ observe(start = UNKNOWN_START, ajs = true) {
3088
3540
  let latest = -1n;
3089
3541
  for (const [project, state] of this.projects) {
3090
3542
  const cache = join(project, PROJECT_CACHE);
3091
3543
  const manifest = manifestOf(cache);
3092
3544
  if (manifest === void 0) continue;
3093
- const listed = new Map(manifest.modules);
3094
- for (const [name, known] of state.installed) if (!listed.has(name)) state.refused ??= `${name} left ${MANIFEST} after ajs installed ${name}@${known.version}`;
3545
+ const added = [];
3546
+ state.refused ??= departure(state, manifest.modules);
3095
3547
  for (const [name, version] of manifest.modules) {
3096
3548
  const born = bornAt(join(cache, name));
3097
3549
  const known = state.installed.get(name);
3550
+ if (recordGit(state, name, version, added)) continue;
3098
3551
  if (known === void 0) {
3552
+ added.push(`${name}@${version}`);
3553
+ if (state.git.has(name)) state.refused ??= `${name} changed from a git module to ${version} after ajs installed it`;
3099
3554
  state.installed.set(name, {
3100
3555
  version,
3101
3556
  born,
@@ -3103,15 +3558,15 @@ var ProjectCaches = class {
3103
3558
  });
3104
3559
  if (manifest.mtime > latest) latest = manifest.mtime;
3105
3560
  if (pinned(project, name, version, start)) state.refused ??= `ajs installed ${name}@${version} from the project's lock record`;
3106
- } else if (known.version !== version) state.refused ??= `${name} changed from ${known.version} to ${version} after ajs installed it`;
3107
- else if (born !== known.born) state.refused ??= `${name} was created again after ajs installed ${name}@${version}`;
3561
+ } else state.refused ??= reinstalled(name, known, version, born);
3108
3562
  }
3563
+ if (!ajs && added.length > 1) state.refused ??= `${added.join(" and ")} appeared in one command that is not ajs, which may have changed one of them before ajs installed the next`;
3109
3564
  }
3110
3565
  if (latest >= 0n) this.passClock(latest);
3111
3566
  }
3112
- /** Observes the project caches once a command or an app start has ended, and returns its result. Its `folder` is the step folder the harness created as it began, so a lock record no newer than that folder was there before the command. */
3113
- observed(result) {
3114
- this.observe(bornAt(result.folder) || UNKNOWN_START);
3567
+ /** Observes the project caches once a command or an app start has ended, and returns its result. Its `folder` is the step folder the harness created as it began, so a lock record no newer than that folder was there before the command. `ajs` tells whether only `ajs` ran, as in `ajs` commands and app starts, or a command that may also run other programs. */
3568
+ observed(result, ajs) {
3569
+ this.observe(bornAt(result.folder) || UNKNOWN_START, ajs);
3115
3570
  return result;
3116
3571
  }
3117
3572
  /**
@@ -3147,220 +3602,321 @@ var ProjectCaches = class {
3147
3602
  const cache = join(project, PROJECT_CACHE);
3148
3603
  const manifest = manifestOf(cache);
3149
3604
  if (manifest === void 0 || manifest.modules.length === 0) continue;
3150
- const target = join(this.store, createHash("sha256").update(manifest.modules.map((entry) => entry.join("@")).join("\n")).digest("hex").slice(0, 16));
3151
- if (existsSync(target)) continue;
3152
- const unregistered = manifest.modules.find(([, version]) => !REGISTRY_VERSION.test(version));
3153
- const change = state.refused ?? (unregistered === void 0 ? changeIn(cache, state.installed, manifest.mtime) : `${unregistered.join("@")} is not a registry version, and ajs updates a git module in place`);
3605
+ const modules = manifest.modules.filter(([, version]) => REGISTRY_VERSION.test(version));
3606
+ const left = manifest.modules.filter(([, version]) => !REGISTRY_VERSION.test(version)).map(([name]) => name);
3607
+ const target = join(this.store, createHash("sha256").update(modules.map((entry) => entry.join("@")).join("\n")).digest("hex").slice(0, 16));
3608
+ if (modules.length > 0 && existsSync(target)) continue;
3609
+ const change = refusal(cache, state, manifest);
3154
3610
  if (change !== void 0) {
3155
3611
  skipped.push(`${cache}: ${change}`);
3156
3612
  continue;
3157
3613
  }
3158
3614
  mkdirSync(this.store, { recursive: true });
3159
- publish(cache, target);
3615
+ publish(cache, target, [cachePath(cache), cache + sep], KEPT_CACHE, left.length > 0 ? {
3616
+ modules,
3617
+ left
3618
+ } : void 0);
3160
3619
  }
3161
3620
  return skipped;
3162
3621
  }
3163
3622
  };
3164
3623
  //#endregion
3165
- //#region src/verify/prepared.ts
3166
- const KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
3167
- /** The path of `path` inside `root`, or `null` when it lies outside. */
3168
- function inside(root, path) {
3169
- const rest = relative(root, path);
3170
- if (rest === ".." || rest.startsWith(`..${sep}`) || isAbsolute(rest)) return null;
3171
- return rest;
3172
- }
3173
- /** Surveys `folder` in one walk that descends only into real directories, so it never follows a symlink; a target may name the folder by its real path. */
3174
- function survey(folder) {
3175
- const real = realpathSync(folder);
3176
- const found = {
3177
- links: [],
3178
- special: null
3624
+ //#region src/verify/readiness.ts
3625
+ const READY_TIMEOUT_MS = 12e4;
3626
+ /** The longest wait between readiness probes. */
3627
+ const POLL_MS = 250;
3628
+ /** The wait between readiness probes in the first `FAST_POLL_WINDOW_MS`, where most apps come up: an app ready in 300 ms is seen within 25 ms of it instead of at the 500 ms tick. */
3629
+ const FAST_POLL_MS = 25;
3630
+ /** How long readiness is probed every `FAST_POLL_MS` before falling back to `POLL_MS`. */
3631
+ const FAST_POLL_WINDOW_MS = 3e3;
3632
+ const SETTLE_MS = 3e3;
3633
+ async function probe(context, app, fixture, folder) {
3634
+ const probe = context.workspace.config.template?.probe;
3635
+ if (!fixture && probe?.log) {
3636
+ const output = readOutput(app.folder);
3637
+ return {
3638
+ name: `dev output matches ${probe.log}`,
3639
+ pass: probe.log.test(`${output.stdout}${output.stderr}`),
3640
+ detail: output.stderr.slice(-300)
3641
+ };
3642
+ }
3643
+ const path = fixture ? "/health" : probe?.path ?? "/";
3644
+ const answer = await httpRecorded(folder, `http://127.0.0.1:${app.port}${path}`);
3645
+ const status = fixture ? 200 : probe?.status ?? 200;
3646
+ const body = !fixture && probe?.body ? probe.body : /./s;
3647
+ return {
3648
+ name: `GET ${path} answers ${status} with ${body}`,
3649
+ pass: answer.status === status && body.test(answer.body),
3650
+ detail: answer.error ?? `status ${answer.status}, body ${answer.body.slice(0, 300)}`
3179
3651
  };
3180
- const walk = (at) => {
3181
- for (const entry of readdirSync(join(folder, at), { withFileTypes: true })) {
3182
- const path = join(at, entry.name);
3183
- if (entry.isDirectory()) walk(path);
3184
- else if (entry.isSymbolicLink()) {
3185
- const pointed = readlinkSync(join(folder, path));
3186
- const target = isAbsolute(pointed) ? inside(folder, pointed) ?? inside(real, pointed) : null;
3187
- if (target !== null) found.links.push({
3188
- path,
3189
- target
3190
- });
3191
- } else if (!entry.isFile()) found.special ??= path;
3192
- }
3652
+ }
3653
+ /** Probes a started app in a new `ready` step until it answers, exits or times out, and aborts the journey unless it came up and stayed up. */
3654
+ async function waitReady(context, app, handle, fixture) {
3655
+ const folder = context.step("ready");
3656
+ const deadline = Date.now() + READY_TIMEOUT_MS;
3657
+ let exited = false;
3658
+ handle.exited.then(() => {
3659
+ exited = true;
3660
+ });
3661
+ const fastUntil = Date.now() + FAST_POLL_WINDOW_MS;
3662
+ let check = await probe(context, app, fixture, folder);
3663
+ while (!check.pass && !exited && Date.now() < deadline) {
3664
+ await setTimeout$1(Date.now() < fastUntil ? FAST_POLL_MS : POLL_MS);
3665
+ check = await probe(context, app, fixture, folder);
3666
+ }
3667
+ const settle = context.workspace.config.template?.probe.log ? context.workspace.config.template.probe.settleMs ?? SETTLE_MS : 0;
3668
+ if (check.pass && settle > 0) await setTimeout$1(settle);
3669
+ const alive = {
3670
+ name: "still running after readiness",
3671
+ pass: !exited,
3672
+ detail: `waited ${settle} ms`
3193
3673
  };
3194
- walk("");
3195
- return found;
3674
+ writeFileSync(join(folder, "ready.txt"), `${check.pass && !exited ? "ready" : exited ? "exited before ready" : "timed out"}\n`);
3675
+ context.expect(folder, check.pass ? [check, alive] : [check], { critical: true });
3196
3676
  }
3677
+ //#endregion
3678
+ //#region src/verify/registry.ts
3679
+ /** A longer line, counted in bytes, is not read for a failing request. */
3680
+ const MAX_LINE_BYTES = 8192;
3681
+ /** How long each half of the probe, the DNS lookup and the TCP connect, may take before it counts as failed. */
3682
+ const PROBE_TIMEOUT_MS = 3e3;
3683
+ /** The command words, after the program, that fetch packages or images. */
3684
+ const FETCHING = /* @__PURE__ */ new Map([
3685
+ ["docker", [
3686
+ ["pull"],
3687
+ ["build"],
3688
+ ["buildx", "build"],
3689
+ ["compose", "pull"],
3690
+ ["compose", "build"]
3691
+ ]],
3692
+ ["npm", [
3693
+ ["install"],
3694
+ ["ci"],
3695
+ ["i"],
3696
+ ["pack"],
3697
+ ["view"]
3698
+ ]],
3699
+ ["pnpm", [
3700
+ ["install"],
3701
+ ["i"],
3702
+ ["add"],
3703
+ ["fetch"],
3704
+ ["update"]
3705
+ ]],
3706
+ ["ajs", [["module", "install"], ["project", "init"]]]
3707
+ ]);
3708
+ /** One shell word of a recorded command, quotes included. */
3709
+ const SHELL_WORD = /(?:'[^']*'|"(?:\\.|[^"\\])*"|\\.|[^\s'"\\])+/g;
3710
+ const SHELL_PIECE = /'([^']*)'|"((?:\\.|[^"\\])*)"|\\(.)/g;
3711
+ /** A path inside the `@antelopejs/core` package, which `node` runs as `ajs`. */
3712
+ const AJS_ENTRY = /(?:^|\/)@antelopejs\/core\//;
3713
+ function shellWords(command) {
3714
+ return (command.slice(0, 4096).match(SHELL_WORD) ?? []).slice(0, 16).map((word) => word.replace(SHELL_PIECE, (_whole, single, double, escaped) => single ?? double?.replace(/\\(.)/g, "$1") ?? escaped ?? ""));
3715
+ }
3716
+ /** Whether a step's `command.txt` runs a program and subcommand that fetch dependencies or images. */
3717
+ function fetchesDependencies(folder) {
3718
+ const file = join(folder, "command.txt");
3719
+ if (!existsSync(file)) return false;
3720
+ const text = readFileSync(file, "utf8");
3721
+ const words = shellWords((text.startsWith("cd ") ? text.slice(text.indexOf("\n") + 1) : text).split("\n")[0] ?? "");
3722
+ while (words.length > 0 && /^[A-Za-z_]\w*=/.test(words[0] ?? "")) words.shift();
3723
+ const first = words.shift();
3724
+ if (first === void 0) return false;
3725
+ let program = basename(first);
3726
+ if (program === "node" && AJS_ENTRY.test(words[0] ?? "")) {
3727
+ program = "ajs";
3728
+ words.shift();
3729
+ }
3730
+ return (FETCHING.get(program) ?? []).some((prefix) => prefix.every((word, index) => words[index] === word));
3731
+ }
3732
+ /** How a connection to a host fails before any answer, in any letter case. */
3733
+ const NETWORK_CAUSE = /\b(?:ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH|ERR_SOCKET_TIMEOUT|socket hang up|no such host|server misbehaving|i\/o timeout|TLS handshake timeout|context deadline exceeded|Temporary failure in name resolution|Client\.Timeout exceeded while awaiting headers|connection refused|network is unreachable)\b/i;
3734
+ /** The public npm, Docker Hub and container registries a fetch may name: fixed names only, since a name the product picks can fail DNS for the product's own reasons. */
3735
+ const REGISTRY_HOSTS = /* @__PURE__ */ new Set([
3736
+ "registry.npmjs.org",
3737
+ "registry.yarnpkg.com",
3738
+ "registry.npmmirror.com",
3739
+ "registry-1.docker.io",
3740
+ "auth.docker.io",
3741
+ "index.docker.io",
3742
+ "docker.io",
3743
+ "production.cloudflare.docker.com",
3744
+ "docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com",
3745
+ "ghcr.io",
3746
+ "quay.io",
3747
+ "gcr.io",
3748
+ "mirror.gcr.io",
3749
+ "public.ecr.aws"
3750
+ ]);
3751
+ /** The npm summary lines that repeat the error code with no request, such as `npm error code ENOTFOUND`, also behind a BuildKit `#8 12.31` prefix or indentation. */
3752
+ const NPM_SUMMARY = /^\s*(?:#\d+ [\d.]+ +)?npm (?:error|ERR!) (?:code|errno|syscall) [\w-]+\s*$/;
3753
+ /** A host with its optional port, in a URL or after a network cause. */
3754
+ const URL_HOST = String.raw`(\[[^\]\s]+\]|[^\s"/:?#\[\]]+)(?::(\d+))?`;
3755
+ /** The address after a network error code; with no port, it is dropped when a URL, `dial tcp` or `lookup` target on the line names the same host. */
3756
+ const BARE_TARGET = /\b(?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\s+(\[[^\]\s]+\]|[\w-]+(?:\.[\w-]+)+)(?::(\d+))?/gi;
3197
3757
  /**
3198
- * Copies `source` to `target`, which ends up at `root`. Each of `links`
3199
- * points to its target inside `root`, so no copy reaches another journey's
3200
- * folder. Every other symlink keeps its target, so pnpm's relative links in a
3201
- * copy never point back into the source.
3758
+ * The places where a line names the target of a request: the URL after
3759
+ * `GET`, `HEAD`, `POST`, `PUT`, `DELETE` or `request to`, the `lookup <host>`
3760
+ * and `dial tcp <host>:<port>` of the Docker client, and the address after a
3761
+ * network error code.
3202
3762
  */
3203
- function copyTree(source, target, links = [], root = target) {
3204
- cpSync(source, target, {
3205
- recursive: true,
3206
- verbatimSymlinks: true,
3207
- preserveTimestamps: true
3208
- });
3209
- for (const link of links) {
3210
- unlinkSync(join(target, link.path));
3211
- symlinkSync(join(root, link.target), join(target, link.path));
3763
+ const TARGETS = [
3764
+ new RegExp(String.raw`(?:\b(?:get|head|post|put|delete)\b(?: request)?(?: to)?|\brequest to)[ ]+"?https?://${URL_HOST}`, "gi"),
3765
+ /\bdial tcp (\[[^\]\s]+\]|[\w.-]+):(\d+)/gi,
3766
+ /\blookup ([\w.-]+)/gi,
3767
+ BARE_TARGET
3768
+ ];
3769
+ /** The targets of a line, or `null` when one of them is not a public registry on port 80 or 443. */
3770
+ function registryTargets(line) {
3771
+ const targets = [];
3772
+ for (const pattern of TARGETS) for (const match of line.matchAll(pattern)) {
3773
+ const host = (match[1] ?? "").toLowerCase().replace(/\.$/, "");
3774
+ const defaultPort = /http:\/\//i.test(match[0]) ? 80 : 443;
3775
+ const port = match[2] === void 0 ? defaultPort : Number(match[2]);
3776
+ if (!REGISTRY_HOSTS.has(host) || port !== 80 && port !== 443) return null;
3777
+ const named = targets.some((target) => target.host === host);
3778
+ if (pattern !== BARE_TARGET || match[2] !== void 0 || !named) targets.push({
3779
+ host,
3780
+ port
3781
+ });
3212
3782
  }
3783
+ return targets;
3784
+ }
3785
+ /** The registry targets of every line with a network cause, or `null` when a failing request went anywhere else or a line names no target. */
3786
+ function failingTargets(texts) {
3787
+ const found = /* @__PURE__ */ new Map();
3788
+ for (const text of texts) for (const raw of text.split(/\r\n|\r|\n/)) {
3789
+ if (Buffer.byteLength(raw) > MAX_LINE_BYTES) continue;
3790
+ const line = stripVTControlCharacters(raw);
3791
+ if (!NETWORK_CAUSE.test(line)) continue;
3792
+ if (NPM_SUMMARY.test(line)) continue;
3793
+ const targets = registryTargets(line);
3794
+ if (targets === null || targets.length === 0) return null;
3795
+ for (const target of targets) found.set(`${target.host}:${target.port}`, target);
3796
+ }
3797
+ return [...found.values()];
3798
+ }
3799
+ function exitedNonZero(folder) {
3800
+ const file = join(folder, "exit-code.txt");
3801
+ return existsSync(file) && readFileSync(file, "utf8").trim() !== "0";
3802
+ }
3803
+ function streamsOf(folder) {
3804
+ return ["stdout.txt", "stderr.txt"].map((name) => join(folder, name)).filter((file) => existsSync(file)).map((file) => readFileSync(file, "utf8"));
3805
+ }
3806
+ /** The addresses a host resolves to now, or why it did not resolve within the timeout. */
3807
+ function resolve$1(host) {
3808
+ return new Promise((settle) => {
3809
+ const timer = setTimeout(() => settle({
3810
+ ok: false,
3811
+ failure: `no DNS answer within ${PROBE_TIMEOUT_MS} ms`
3812
+ }), PROBE_TIMEOUT_MS);
3813
+ lookup(host, { all: true }, (error, found) => {
3814
+ clearTimeout(timer);
3815
+ settle(error === null ? {
3816
+ ok: true,
3817
+ addresses: found.map((entry) => entry.address)
3818
+ } : {
3819
+ ok: false,
3820
+ failure: error.code ?? error.message
3821
+ });
3822
+ });
3823
+ });
3213
3824
  }
3214
- /** Judges the build of `folder` by the steps it recorded. */
3215
- function judge$1(steps, folder) {
3216
- const checks = steps.flatMap((step) => step.checks);
3217
- if (checks.length === 0) return {
3218
- kept: false,
3219
- reason: "the build recorded no check"
3220
- };
3221
- if (!checks.every((check) => check.pass)) return {
3222
- kept: false,
3223
- reason: "a check of the build failed"
3224
- };
3225
- const found = survey(folder);
3226
- return found.special === null ? {
3227
- kept: true,
3228
- links: found.links
3229
- } : {
3230
- kept: false,
3231
- reason: `${found.special} is not a file, directory or symlink, which a copy would drop`
3232
- };
3233
- }
3234
- /** The links `keep` recorded, each a path then its target, joined by NUL, the one character no path holds. */
3235
- function readLinks(kept) {
3236
- const fields = readFileSync(join(kept, "links"), "utf8").split("\0");
3237
- const links = [];
3238
- for (let at = 0; at + 1 < fields.length; at += 2) links.push({
3239
- path: fields[at],
3240
- target: fields[at + 1]
3825
+ /** `null` once a TCP connection to the address opens, or why it did not within the timeout. */
3826
+ function tcpConnect(address, port) {
3827
+ return new Promise((settle) => {
3828
+ const socket = connect({
3829
+ host: address,
3830
+ port
3831
+ });
3832
+ socket.setTimeout(PROBE_TIMEOUT_MS, () => {
3833
+ socket.destroy();
3834
+ settle(`no TCP connect within ${PROBE_TIMEOUT_MS} ms`);
3835
+ });
3836
+ socket.once("connect", () => {
3837
+ socket.destroy();
3838
+ settle(null);
3839
+ });
3840
+ socket.once("error", (error) => {
3841
+ socket.destroy();
3842
+ settle(error.code ?? error.message);
3843
+ });
3241
3844
  });
3242
- return links;
3243
3845
  }
3244
- /** The journey that built what the run kept, as its path under the evidence. */
3245
- function builder(kept) {
3246
- return readFileSync(join(kept, "from.txt"), "utf8").trim();
3846
+ /** Resolves the target's host now and opens a TCP connection to its port on every address it resolves to; one connect is enough to answer. */
3847
+ async function probeTarget({ host, port }) {
3848
+ const resolution = await resolve$1(host);
3849
+ if (!resolution.ok) return `DNS lookup of ${host} failed: ${resolution.failure}`;
3850
+ const failures = await Promise.all(resolution.addresses.map((address) => tcpConnect(address, port)));
3851
+ if (failures.some((failure) => failure === null)) return null;
3852
+ const causes = [...new Set(failures)].join(", ");
3853
+ return `TCP connect to ${host} port ${port} failed on all ${failures.length} addresses: ${causes}`;
3247
3854
  }
3248
3855
  /**
3249
- * Copies what the run kept into the journey, with the evidence of that build
3250
- * under the step `marker`, and returns `null`. When the copy fails, or what
3251
- * the run kept is gone or replaced once it ends, as when the journey that
3252
- * built reruns meanwhile, the partial copy is removed and this returns why.
3856
+ * Why a failed journey ended because a container or package registry could
3857
+ * not be reached, or `null` when the product, not the network, explains it.
3858
+ *
3859
+ * The output decides only which registry to ask; a live probe decides the
3860
+ * outage. A missed outage stays FAIL, and when the registry answers the
3861
+ * probe the failure is the product's, whatever the output says.
3862
+ *
3863
+ * It reads only the first step with a failing check, and only when that
3864
+ * step's command exited non-zero or was signalled. The step's `command.txt`
3865
+ * must run a program and subcommand that fetch dependencies or images, after
3866
+ * any `NAME=value` prefix and whatever the program's path: `docker pull`,
3867
+ * `docker build`, `docker buildx build`, `docker compose pull` or `build`,
3868
+ * `npm install`, `ci`, `i`, `pack` or `view`, `pnpm install`, `i`, `add`,
3869
+ * `fetch` or `update`, and `ajs module install` or `ajs project init` (also
3870
+ * run as `node` on a script inside `@antelopejs/core`). The subcommand words
3871
+ * must follow the program directly, so `pnpm test`, `pnpm run`, `sh -c`,
3872
+ * `node`, `docker run` and `docker exec` stay FAIL.
3873
+ *
3874
+ * The failing requests are the lines of both streams, ANSI escapes stripped
3875
+ * and lines over 8 KiB skipped, that carry a network cause such as
3876
+ * `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `ETIMEDOUT`, `no such host`, `i/o
3877
+ * timeout` or `Temporary failure in name resolution`. Their targets are the
3878
+ * URL after `GET`, `HEAD`, `POST`, `PUT`, `DELETE` or `request to`, the host
3879
+ * after `lookup`, the host before the port after `dial tcp`, and the address
3880
+ * after a network error code, on port 443, or 80 for an `http://` URL, when
3881
+ * no port is named. Every line with a network cause must name a target, npm's
3882
+ * `code`, `errno` and `syscall` summary lines aside (also indented or behind a
3883
+ * BuildKit `#8 12.31` prefix), and every target must be
3884
+ * one of these public registries on port 80 or 443: `registry.npmjs.org`,
3885
+ * `registry.yarnpkg.com`, `registry.npmmirror.com`, `registry-1.docker.io`,
3886
+ * `auth.docker.io`, `index.docker.io`, `docker.io`,
3887
+ * `production.cloudflare.docker.com`, Docker Hub's one blob host
3888
+ * `docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com`, `ghcr.io`, `quay.io`, `gcr.io`, `mirror.gcr.io`
3889
+ * and `public.ecr.aws`. Only fixed names count: a name the product picks, such as
3890
+ * an ECR account registry or a regional `pkg.dev` host, can fail DNS for the
3891
+ * product's own reasons, so it stays FAIL, and so do an address, a private
3892
+ * mirror and `localhost`.
3893
+ *
3894
+ * Each target then gets a fresh probe: a DNS lookup and a TCP connect to
3895
+ * every address it resolves to, each bounded to 3 s, and one connect that
3896
+ * succeeds is an answer. The journey is NOT VERIFIED only when every target fails
3897
+ * it, and the reason names the step and each probe's failure. A registry
3898
+ * that answered with a 5xx or 429 passes the probe, so it stays FAIL.
3253
3899
  */
3254
- function reuse$1({ marker, key, kept, folder }) {
3255
- const evidence = join(marker, "build");
3900
+ async function registryFault(evidence, steps, probe = probeTarget) {
3256
3901
  try {
3257
- const memo = statSync(kept).ino;
3258
- copyTree(join(kept, "evidence"), evidence);
3259
- copyTree(join(kept, "folder"), folder, readLinks(kept));
3260
- const from = builder(kept);
3261
- if (statSync(kept).ino !== memo) throw new Error(`${kept} was replaced while it was copied`);
3262
- writeFileSync(join(marker, "prepared.txt"), `${key}: ${folder} is a copy of what ${from} prepared; build/ holds the evidence of that build\n`);
3902
+ const step = steps.find((entry) => entry.checks.some((check) => !check.pass));
3903
+ if (step === void 0) return null;
3904
+ const folder = join(evidence, step.folder);
3905
+ if (!exitedNonZero(folder) || !fetchesDependencies(folder)) return null;
3906
+ const targets = failingTargets(streamsOf(folder));
3907
+ if (targets === null || targets.length === 0) return null;
3908
+ const failures = await Promise.all(targets.map(probe));
3909
+ if (failures.some((failure) => failure === null)) return null;
3910
+ return `step ${step.name} could not reach a container or package registry, which also fails a fresh probe now, an outage outside the code under test: ${failures.join("; ")}`;
3911
+ } catch {
3263
3912
  return null;
3264
- } catch (error) {
3265
- removeTree(evidence);
3266
- removeTree(folder);
3267
- return error instanceof Error ? error.message : String(error);
3268
- }
3269
- }
3270
- /** Removes what the run kept by first renaming it away, so a journey copying it meanwhile fails instead of copying a half-deleted tree. */
3271
- function drop(kept) {
3272
- const trash = mkdtempSync(`${kept}.`);
3273
- renameSync(kept, join(trash, "dropped"));
3274
- removeTree(trash);
3275
- }
3276
- /** Keeps the built folder and the build's step evidence for the rest of the run, published by one rename; when another journey kept the key first, its copy stays and this returns `false`. */
3277
- function keep(context, kept, folder, built) {
3278
- mkdirSync(dirname(kept), { recursive: true });
3279
- const staging = mkdtempSync(`${kept}.`);
3280
- try {
3281
- mkdirSync(join(staging, "evidence"));
3282
- for (const step of built.steps) copyTree(join(context.folder, step), join(staging, "evidence", step));
3283
- copyTree(folder, join(staging, "folder"), built.links, join(kept, "folder"));
3284
- writeFileSync(join(staging, "links"), built.links.flatMap((link) => [link.path, link.target]).join("\0"));
3285
- writeFileSync(join(staging, "from.txt"), `${relative(context.state.evidence, context.folder)}\n`);
3286
- renameSync(staging, kept);
3287
- return true;
3288
- } catch (error) {
3289
- if (!existsSync(kept)) throw error;
3290
- return false;
3291
- } finally {
3292
- removeTree(staging);
3293
- }
3294
- }
3295
- /** Runs `build` with a HOME of its own for its commands, deleted when it ends. */
3296
- async function buildAlone(context, key, folder, build) {
3297
- const outer = context.buildHome;
3298
- const home = join(context.home, `.prepared-${key}`);
3299
- mkdirSync(home, { recursive: true });
3300
- context.buildHome = home;
3301
- try {
3302
- await build(folder);
3303
- } finally {
3304
- context.buildHome = outer;
3305
- removeTree(home);
3306
- }
3307
- }
3308
- /** Builds `key` in this journey after the step `marker`, which marks the steps after it as the build and says, after `before`, whether the run kept it. */
3309
- async function buildHere(context, where, build, before = "") {
3310
- const { marker, key, kept, folder } = where;
3311
- const note = (outcome) => writeFileSync(join(marker, "prepared.txt"), `${key}: ${before}${folder} was built here by the steps after this one; ${outcome}\n`);
3312
- const earlier = new Set(readdirSync(context.folder));
3313
- const checked = context.steps.length;
3314
- mkdirSync(folder, { recursive: true });
3315
- try {
3316
- await buildAlone(context, key, folder, build);
3317
- } catch (error) {
3318
- note("not kept: the build threw, so the next journey builds again");
3319
- throw error;
3320
- }
3321
- const verdict = judge$1(context.steps.slice(checked), folder);
3322
- if (!verdict.kept) {
3323
- note(`not kept: ${verdict.reason}, so the next journey builds again`);
3324
- return;
3325
3913
  }
3326
- note(keep(context, kept, folder, {
3327
- steps: readdirSync(context.folder).filter((entry) => !earlier.has(entry)),
3328
- links: verdict.links
3329
- }) ? "kept, so later journeys of the run copy it" : `not kept: ${builder(kept)} kept ${key} first, so later journeys copy that build`);
3330
- }
3331
- /** `JourneyContext.prepared` for one journey of the run. */
3332
- async function prepare(context, key, build) {
3333
- if (!KEY.test(key)) throw new Error(`prepared key ${JSON.stringify(key)} must be lowercase letters and digits joined by dashes`);
3334
- const folder = join(context.work, key);
3335
- if (existsSync(folder)) throw new Error(`${folder} already exists: a journey prepares ${key} once`);
3336
- const kept = join(context.state.dir, "prepared", key);
3337
- if (existsSync(kept) && builder(kept) === relative(context.state.evidence, context.folder)) drop(kept);
3338
- const where = {
3339
- marker: context.step(`prepared ${key}`),
3340
- key,
3341
- kept,
3342
- folder
3343
- };
3344
- if (!existsSync(kept)) await buildHere(context, where, build);
3345
- else {
3346
- const failed = reuse$1(where);
3347
- if (failed !== null) await buildHere(context, where, build, `copying what the run kept failed (${failed}), so `);
3348
- }
3349
- return folder;
3350
3914
  }
3351
3915
  //#endregion
3352
3916
  //#region src/verify/context.ts
3353
3917
  var JourneyAbort = class extends Error {};
3354
3918
  var NotVerified = class extends Error {};
3355
- const READY_TIMEOUT_MS = 12e4;
3356
3919
  const STOP_TIMEOUT_MS = 3e4;
3357
- /** The longest wait between readiness probes. */
3358
- const POLL_MS = 250;
3359
- /** The wait between readiness probes in the first `FAST_POLL_WINDOW_MS`, where most apps come up: an app ready in 300 ms is seen within 25 ms of it instead of at the 500 ms tick. */
3360
- const FAST_POLL_MS = 25;
3361
- /** How long readiness is probed every `FAST_POLL_MS` before falling back to `POLL_MS`. */
3362
- const FAST_POLL_WINDOW_MS = 3e3;
3363
- const SETTLE_MS = 3e3;
3364
3920
  /** The waits between the readiness reruns after a failed journey: one miss under load does not hide a catch. */
3365
3921
  const READINESS_RETRY_MS = [
3366
3922
  500,
@@ -3370,6 +3926,15 @@ const READINESS_RETRY_MS = [
3370
3926
  function slug(text) {
3371
3927
  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
3372
3928
  }
3929
+ /** Sends `name` to `pid`, returning whether the signal was delivered. */
3930
+ function signal(pid, name) {
3931
+ try {
3932
+ process.kill(pid, name);
3933
+ return true;
3934
+ } catch {
3935
+ return false;
3936
+ }
3937
+ }
3373
3938
  /** The harness side of a journey: every driving call writes its evidence into a new numbered step folder. */
3374
3939
  var VerifyContext = class {
3375
3940
  repo;
@@ -3421,22 +3986,25 @@ var VerifyContext = class {
3421
3986
  }
3422
3987
  prepared = (key, build) => prepare(this, key, build);
3423
3988
  command(name, program, args, options = {}) {
3989
+ return this.run(name, program, args, options, false);
3990
+ }
3991
+ /** Runs `ajs <args>` of the repository's `@antelopejs/core`. */
3992
+ ajs(name, args, options = {}) {
3993
+ return this.run(name, process.execPath, [ajsEntry(this.repo), ...args], options, true);
3994
+ }
3995
+ run(name, program, args, options, ajs) {
3424
3996
  return runRecorded(this.step(name), {
3425
3997
  program,
3426
3998
  args,
3427
3999
  cwd: options.cwd ?? this.work,
3428
4000
  env: this.env(options.env),
3429
4001
  timeoutMs: options.timeoutMs
3430
- }).then((result) => this.caches.observed(result));
3431
- }
3432
- /** Runs `ajs <args>` of the repository's `@antelopejs/core`. */
3433
- ajs(name, args, options = {}) {
3434
- return this.command(name, process.execPath, [ajsEntry(this.repo), ...args], options);
4002
+ }).then((result) => this.caches.observed(result, ajs));
3435
4003
  }
3436
4004
  edit(name, file, content) {
3437
4005
  const folder = this.step(name);
3438
4006
  mkdirSync(join(file, ".."), { recursive: true });
3439
- writeFileSync(file, content);
4007
+ writeOwn(file, content);
3440
4008
  writeFileSync(join(folder, "edit.txt"), `${file}\n---\n${content}`);
3441
4009
  return folder;
3442
4010
  }
@@ -3488,7 +4056,10 @@ var VerifyContext = class {
3488
4056
  fixture(options = {}) {
3489
4057
  const config = options.moduleConfig ?? this.workspace.config.moduleConfig?.(this.services()) ?? {};
3490
4058
  const folder = this.fixtures.size === 0 ? this.work : join(this.work, `fixture-${this.fixtures.size + 1}`);
3491
- const fixture = writeFixture(this.workspace, this.state, folder, config);
4059
+ const fixture = writeFixture(this.workspace, this.state, folder, {
4060
+ module: config,
4061
+ companions: this.workspace.config.companions?.(this.services()) ?? {}
4062
+ });
3492
4063
  this.fixtures.set(fixture.project, fixture);
3493
4064
  this.tree("fixture project", fixture.project);
3494
4065
  this.caches.seed(fixture.project);
@@ -3519,14 +4090,15 @@ var VerifyContext = class {
3519
4090
  ...options.env
3520
4091
  };
3521
4092
  const folder = this.step(name);
4093
+ const [program, ...args] = options.command ?? [
4094
+ process.execPath,
4095
+ ajsEntry(this.repo),
4096
+ "project",
4097
+ "dev"
4098
+ ];
3522
4099
  const handle = startRecorded(folder, {
3523
- program: process.execPath,
3524
- args: [
3525
- ajsEntry(this.repo),
3526
- "project",
3527
- "dev",
3528
- ...options.args ?? []
3529
- ],
4100
+ program,
4101
+ args: [...args, ...options.args ?? []],
3530
4102
  cwd: project,
3531
4103
  env: this.env(env)
3532
4104
  });
@@ -3553,51 +4125,8 @@ var VerifyContext = class {
3553
4125
  name: `${name} (${project})`,
3554
4126
  pid: handle.pid
3555
4127
  }] });
3556
- await this.waitReady(app, handle, fixture !== void 0);
3557
- return this.caches.observed(app);
3558
- }
3559
- async probe(app, fixture, folder) {
3560
- const probe = this.workspace.config.template?.probe;
3561
- if (!fixture && probe?.log) {
3562
- const output = readOutput(app.folder);
3563
- return {
3564
- name: `dev output matches ${probe.log}`,
3565
- pass: probe.log.test(`${output.stdout}${output.stderr}`),
3566
- detail: output.stderr.slice(-300)
3567
- };
3568
- }
3569
- const path = fixture ? "/health" : probe?.path ?? "/";
3570
- const answer = await httpRecorded(folder, `http://127.0.0.1:${app.port}${path}`);
3571
- const status = fixture ? 200 : probe?.status ?? 200;
3572
- const body = !fixture && probe?.body ? probe.body : /./s;
3573
- return {
3574
- name: `GET ${path} answers ${status} with ${body}`,
3575
- pass: answer.status === status && body.test(answer.body),
3576
- detail: answer.error ?? `status ${answer.status}, body ${answer.body.slice(0, 300)}`
3577
- };
3578
- }
3579
- async waitReady(app, handle, fixture) {
3580
- const folder = this.step("ready");
3581
- const deadline = Date.now() + READY_TIMEOUT_MS;
3582
- let exited = false;
3583
- handle.exited.then(() => {
3584
- exited = true;
3585
- });
3586
- const fastUntil = Date.now() + FAST_POLL_WINDOW_MS;
3587
- let check = await this.probe(app, fixture, folder);
3588
- while (!check.pass && !exited && Date.now() < deadline) {
3589
- await setTimeout$1(Date.now() < fastUntil ? FAST_POLL_MS : POLL_MS);
3590
- check = await this.probe(app, fixture, folder);
3591
- }
3592
- const settle = this.workspace.config.template?.probe.log ? this.workspace.config.template.probe.settleMs ?? SETTLE_MS : 0;
3593
- if (check.pass && settle > 0) await setTimeout$1(settle);
3594
- const alive = {
3595
- name: "still running after readiness",
3596
- pass: !exited,
3597
- detail: `waited ${settle} ms`
3598
- };
3599
- writeFileSync(join(folder, "ready.txt"), `${check.pass && !exited ? "ready" : exited ? "exited before ready" : "timed out"}\n`);
3600
- this.expect(folder, check.pass ? [check, alive] : [check], { critical: true });
4128
+ await waitReady(this, app, handle, fixture !== void 0);
4129
+ return this.caches.observed(app, true);
3601
4130
  }
3602
4131
  /** Posts a JSON body to a route of the driver module. */
3603
4132
  async driver(name, app, route, body) {
@@ -3617,9 +4146,9 @@ var VerifyContext = class {
3617
4146
  const body = {
3618
4147
  path: request.path,
3619
4148
  args: request.args ?? [],
3620
- chain: request.chain ?? [],
3621
- entry: request.entry ?? "."
4149
+ chain: request.chain ?? []
3622
4150
  };
4151
+ if (request.entry) body.entry = request.entry;
3623
4152
  if (request.interface) body.interface = request.interface;
3624
4153
  return this.driver(name, app, "/call", body);
3625
4154
  }
@@ -3627,12 +4156,8 @@ var VerifyContext = class {
3627
4156
  const folder = this.step(name);
3628
4157
  writeFileSync(join(folder, "command.txt"), `kill -INT ${app.pid}\n`);
3629
4158
  const running = this.running.find((entry) => entry.app.pid === app.pid);
3630
- running?.sent.push("SIGINT");
3631
- try {
3632
- process.kill(app.pid, "SIGINT");
3633
- } catch {
3634
- writeFileSync(join(folder, "note.txt"), "process was already gone\n");
3635
- }
4159
+ if (!running?.exit && signal(app.pid, "SIGINT")) running?.sent.push("SIGINT");
4160
+ else writeFileSync(join(folder, "note.txt"), "process was already gone\n");
3636
4161
  let timer;
3637
4162
  const timeout = new Promise((resolve) => {
3638
4163
  timer = setTimeout(() => resolve(void 0), STOP_TIMEOUT_MS);
@@ -3664,11 +4189,8 @@ var VerifyContext = class {
3664
4189
  if (index !== -1) this.running.splice(index, 1);
3665
4190
  recordProcesses(this.state, { drop: [pid] });
3666
4191
  }
3667
- async scaffold(name, project, flags = [
3668
- "--pm",
3669
- "pnpm",
3670
- "--git-init"
3671
- ]) {
4192
+ /** Points `ajs` at the run's offline manifest in the HOME the next commands get. */
4193
+ async configureGit() {
3672
4194
  const set = await this.ajs("config set git", [
3673
4195
  "config",
3674
4196
  "set",
@@ -3680,15 +4202,23 @@ var VerifyContext = class {
3680
4202
  pass: set.exitCode === 0,
3681
4203
  detail: set.stderr.slice(-300)
3682
4204
  }], { critical: true });
4205
+ }
4206
+ async scaffold(name, project, flags = [
4207
+ "--pm",
4208
+ "pnpm",
4209
+ "--git-init"
4210
+ ]) {
4211
+ await this.configureGit();
4212
+ const group = templateInit(this.workspace);
3683
4213
  const init = await this.ajs(name, [
3684
- "project",
4214
+ group,
3685
4215
  "init",
3686
4216
  relative(this.work, project),
3687
4217
  "--template",
3688
4218
  this.state.templateName,
3689
4219
  ...flags
3690
4220
  ]);
3691
- if (init.exitCode === 0) this.caches.seed(project);
4221
+ if (init.exitCode === 0 && group === "project") this.caches.seed(project);
3692
4222
  return init;
3693
4223
  }
3694
4224
  /** Stops every app the journey left running. */
@@ -3700,16 +4230,18 @@ var VerifyContext = class {
3700
4230
  * or `null` when nothing points away from the product: a service that
3701
4231
  * still fails its readiness command after a few reruns, an app killed by
3702
4232
  * SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the
3703
- * app the harness started failing to bind the driver's port. A break that
3704
- * takes its own service down reads as an outage. Call it after `cleanup`,
3705
- * when every app has exited.
4233
+ * app the harness started failing to bind the driver's port, or a failed
4234
+ * dependency or image fetch whose public registry also fails a fresh DNS
4235
+ * and TCP probe (see `registryFault`). A break that takes its own service
4236
+ * down reads as an outage. Call it after `cleanup`, when every app has
4237
+ * exited.
3706
4238
  */
3707
4239
  async environmentFault() {
3708
4240
  for (const [name, service] of Object.entries(this.workspace.config.services ?? {})) {
3709
4241
  const failure = await this.unready(name, service.ready);
3710
4242
  if (failure !== null) return `the service ${name} no longer passes its readiness command: ${failure}`;
3711
4243
  }
3712
- return appFault(this.started);
4244
+ return appFault(this.started) ?? await registryFault(this.state.evidence, this.steps);
3713
4245
  }
3714
4246
  /** The last readiness failure of a service after the reruns, or `null` once one rerun passes. */
3715
4247
  async unready(name, ready) {
@@ -4490,7 +5022,7 @@ async function main(argv) {
4490
5022
  ]);
4491
5023
  } else if (command === "formal") return runFormal(workspace, rest[0], values.all === true);
4492
5024
  else if (command === "doors") return printDoors(workspace, rest[0] ? patchFiles(rest[0]) : planFor(workspace, values.base).changed);
4493
- else if (command === "clean") for (const line of clean(loadRun(rest[0]))) print(line);
5025
+ else if (command === "clean") for (const line of clean(ownRun(workspace, rest[0]))) print(line);
4494
5026
  else if (command === "verdict") return judge(workspace, rest[0], Number(values.pr));
4495
5027
  else {
4496
5028
  print(USAGE);