@gadicc/loom 2.2.0 → 2.3.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 (39) hide show
  1. package/.loom-source-manifest.json +6 -1
  2. package/README.md +6 -4
  3. package/db/testing.d.ts +38 -1
  4. package/db/testing.js +66 -18
  5. package/db/testingTiming.js +45 -0
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +46 -0
  8. package/esm/src/cli/mod.js.map +1 -1
  9. package/esm/src/cli/testResourceCommand.d.ts +9 -0
  10. package/esm/src/cli/testResourceCommand.d.ts.map +1 -0
  11. package/esm/src/cli/testResourceCommand.js +33 -0
  12. package/esm/src/cli/testResourceCommand.js.map +1 -0
  13. package/esm/src/cli/testResourceHost.d.ts +36 -0
  14. package/esm/src/cli/testResourceHost.d.ts.map +1 -0
  15. package/esm/src/cli/testResourceHost.js +207 -0
  16. package/esm/src/cli/testResourceHost.js.map +1 -0
  17. package/esm/src/cli/testResourceLaunch.d.ts +22 -0
  18. package/esm/src/cli/testResourceLaunch.d.ts.map +1 -0
  19. package/esm/src/cli/testResourceLaunch.js +189 -0
  20. package/esm/src/cli/testResourceLaunch.js.map +1 -0
  21. package/esm/src/cli/testResourcePolicy.d.ts +24 -0
  22. package/esm/src/cli/testResourcePolicy.d.ts.map +1 -0
  23. package/esm/src/cli/testResourcePolicy.js +103 -0
  24. package/esm/src/cli/testResourcePolicy.js.map +1 -0
  25. package/esm/src/cli/testVitestRunner.d.ts +28 -0
  26. package/esm/src/cli/testVitestRunner.d.ts.map +1 -0
  27. package/esm/src/cli/testVitestRunner.js +159 -0
  28. package/esm/src/cli/testVitestRunner.js.map +1 -0
  29. package/package.json +2 -2
  30. package/skills/loom-db/SKILL.md +5 -2
  31. package/skills/loom-db/references/test-boundaries.md +76 -0
  32. package/skills/loom-scaffold/SKILL.md +4 -0
  33. package/skills/loom-scaffold/references/greenfield-workflow.md +25 -2
  34. package/source/src/cli/mod.ts +70 -0
  35. package/source/src/cli/testResourceCommand.ts +49 -0
  36. package/source/src/cli/testResourceHost.ts +299 -0
  37. package/source/src/cli/testResourceLaunch.ts +257 -0
  38. package/source/src/cli/testResourcePolicy.ts +135 -0
  39. package/source/src/cli/testVitestRunner.ts +222 -0
@@ -0,0 +1,103 @@
1
+ import { createHash } from "node:crypto";
2
+ /** Parses Linux CPU lists strictly and returns normalized ascending indices. */
3
+ export function parseCpuList(text) {
4
+ const result = new Set();
5
+ for (const part of text.trim().split(",")) {
6
+ const match = /^(\d+)(?:-(\d+))?$/.exec(part);
7
+ if (!match)
8
+ throw new Error("Invalid CPU list");
9
+ const start = Number(match[1]);
10
+ const end = Number(match[2] ?? match[1]);
11
+ if (end < start || end > 1_000_000)
12
+ throw new Error("Invalid CPU range");
13
+ for (let cpu = start; cpu <= end; cpu++)
14
+ result.add(cpu);
15
+ }
16
+ return [...result].sort((a, b) => a - b);
17
+ }
18
+ /** Stable selection shared by projects; private masks never choose substitute cores. */
19
+ export function selectTestCpus(online, inherited, physical, reserve) {
20
+ const normalized = parseCpuList(online.join(","));
21
+ const onlineSet = new Set(normalized);
22
+ const cores = physical
23
+ ? physical.map((item) => ({
24
+ socket: item.socket,
25
+ core: item.core,
26
+ cpus: [...item.cpus].sort((a, b) => a - b),
27
+ }))
28
+ : normalized.map((cpu) => ({ socket: 0, core: cpu, cpus: [cpu] }));
29
+ cores.sort((a, b) => a.socket - b.socket || a.core - b.core || a.cpus[0] - b.cpus[0]);
30
+ const covered = cores.flatMap((item) => item.cpus);
31
+ if (cores.some((item) => !Number.isInteger(item.socket) ||
32
+ !Number.isInteger(item.core) ||
33
+ item.cpus.length === 0) ||
34
+ covered.length !== normalized.length ||
35
+ new Set(covered).size !== covered.length ||
36
+ covered.some((cpu) => !onlineSet.has(cpu))) {
37
+ throw new Error("Physical topology must partition the online CPU set");
38
+ }
39
+ const count = reserve ?? (cores.length <= 2 ? 0 : cores.length < 8 ? 1 : 2);
40
+ if (!Number.isSafeInteger(count) || count < 0 || count >= cores.length) {
41
+ throw new Error("Reservation must leave at least one online core");
42
+ }
43
+ const reservedCpus = cores
44
+ .slice(0, count)
45
+ .flatMap((item) => item.cpus)
46
+ .sort((a, b) => a - b);
47
+ const reserved = new Set(reservedCpus);
48
+ const testCpus = [...new Set(inherited)]
49
+ .filter((cpu) => onlineSet.has(cpu) && !reserved.has(cpu))
50
+ .sort((a, b) => a - b);
51
+ if (testCpus.length === 0) {
52
+ throw new Error("Inherited CPU restrictions leave no test CPUs after exclusion");
53
+ }
54
+ const spec = "loom-cpu-selection-v1";
55
+ // No inherited mask, dynamic frequency, memory, or worker choice in the epoch.
56
+ const epoch = createHash("sha256")
57
+ .update(JSON.stringify({
58
+ spec,
59
+ online: normalized,
60
+ cores,
61
+ reserve: reserve ?? null,
62
+ }))
63
+ .digest("hex");
64
+ return {
65
+ spec,
66
+ epoch,
67
+ reservedCpus,
68
+ testCpus,
69
+ reservedCores: count,
70
+ topology: physical ? "physical" : "logical-fallback",
71
+ };
72
+ }
73
+ /** A cgroup quota ceiling, or undefined when any applicable limit is unknown. */
74
+ export function testCpuQuota(texts) {
75
+ let capacity = Infinity;
76
+ for (const text of texts) {
77
+ if (text === undefined)
78
+ return undefined;
79
+ const fields = text.trim().split(/\s+/);
80
+ if (fields.length !== 2 || !/^\d+$/.test(fields[1]))
81
+ return undefined;
82
+ const period = Number(fields[1]);
83
+ if (!Number.isSafeInteger(period) || period <= 0)
84
+ return undefined;
85
+ if (fields[0] === "max")
86
+ continue;
87
+ if (!/^\d+$/.test(fields[0]))
88
+ return undefined;
89
+ const quota = Number(fields[0]);
90
+ if (!Number.isSafeInteger(quota) || quota <= 0)
91
+ return undefined;
92
+ capacity = Math.min(capacity, quota / period);
93
+ }
94
+ return texts.length ? capacity : undefined;
95
+ }
96
+ /** Local desktop reserve; CI does not use this floor. */
97
+ export function testMemoryHeadroom(capacityBytes) {
98
+ if (!Number.isFinite(capacityBytes) || capacityBytes <= 0) {
99
+ throw new Error("Memory capacity must be positive and finite");
100
+ }
101
+ return Math.min(2 * 1024 ** 3, Math.max(256 * 1024 ** 2, capacityBytes * 0.1));
102
+ }
103
+ //# sourceMappingURL=testResourcePolicy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testResourcePolicy.js","sourceRoot":"","sources":["../../../source/src/cli/testResourcePolicy.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ /** Minimal supported resolved config; Vitest stays an optional consumer dependency. */
2
+ interface ManagedConfig {
3
+ maxWorkers?: number;
4
+ pool?: unknown;
5
+ watch?: boolean;
6
+ projects?: unknown;
7
+ browser?: {
8
+ enabled?: boolean;
9
+ };
10
+ typecheck?: {
11
+ enabled?: boolean;
12
+ };
13
+ passWithNoTests?: boolean;
14
+ standalone?: boolean;
15
+ ui?: boolean;
16
+ api?: unknown;
17
+ mergeReports?: unknown;
18
+ inspect?: unknown;
19
+ inspectBrk?: unknown;
20
+ }
21
+ /** Location used by the CLI to launch the same source or emitted runner module. */
22
+ export declare const managedVitestModuleURL: string;
23
+ /** Restrict a single, already resolved config before Vitest creates its pool. */
24
+ export declare function clampResolvedTestWorkers(config: ManagedConfig, ceiling: number): number;
25
+ /** Load the installed runner once, clamp final config, then execute that same instance. */
26
+ export declare function runManagedVitest(cwd: string, args: string[], ceiling: number, report?: (workers: number, pool: string) => void): Promise<number>;
27
+ export {};
28
+ //# sourceMappingURL=testVitestRunner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testVitestRunner.d.ts","sourceRoot":"","sources":["../../../source/src/cli/testVitestRunner.ts"],"names":[],"mappings":"AAMA,uFAAuF;AACvF,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChC,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAsBD,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAEtD,iFAAiF;AACjF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,CAgDR;AAED,2FAA2F;AAC3F,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAe,GACzD,OAAO,CAAC,MAAM,CAAC,CAmHjB"}
@@ -0,0 +1,159 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
9
+ import { readFile } from "node:fs/promises";
10
+ import { createRequire } from "node:module";
11
+ import { join } from "node:path";
12
+ import process from "node:process";
13
+ import { pathToFileURL } from "node:url";
14
+ /** Location used by the CLI to launch the same source or emitted runner module. */
15
+ export const managedVitestModuleURL = import.meta.url;
16
+ /** Restrict a single, already resolved config before Vitest creates its pool. */
17
+ export function clampResolvedTestWorkers(config, ceiling) {
18
+ if (!Number.isSafeInteger(ceiling) || ceiling < 1)
19
+ throw new Error("Invalid worker ceiling");
20
+ if (config.pool !== "threads" && config.pool !== "forks")
21
+ throw new Error("Managed tests support only threads and forks pools");
22
+ const api = config.api;
23
+ // Vitest resolves its disabled API to internal middleware metadata. Only
24
+ // a listening/unknown API mode is unsupported, not that ordinary default.
25
+ const listeningApi = api !== undefined &&
26
+ api !== false &&
27
+ api !== null &&
28
+ (typeof api !== "object" ||
29
+ !("middlewareMode" in api) ||
30
+ api.middlewareMode !== true ||
31
+ ("port" in api && api.port !== undefined));
32
+ if (config.watch ||
33
+ config.standalone ||
34
+ config.ui ||
35
+ listeningApi ||
36
+ config.mergeReports ||
37
+ config.inspect ||
38
+ config.inspectBrk ||
39
+ config.projects ||
40
+ config.browser?.enabled ||
41
+ config.typecheck?.enabled) {
42
+ throw new Error("Managed tests currently require a single Node test project without watch, UI/API, standalone, merging, inspectors, browser or typecheck pools");
43
+ }
44
+ const existing = config.maxWorkers;
45
+ if (existing !== undefined &&
46
+ (!Number.isSafeInteger(existing) || existing < 1)) {
47
+ throw new Error("Unsupported resolved Vitest worker limit");
48
+ }
49
+ const selected = Math.min(ceiling, existing ?? ceiling);
50
+ // Later reporter hooks cannot raise a validated value before pool creation.
51
+ Object.defineProperty(config, "maxWorkers", {
52
+ value: selected,
53
+ enumerable: true,
54
+ writable: false,
55
+ configurable: false,
56
+ });
57
+ return selected;
58
+ }
59
+ /** Load the installed runner once, clamp final config, then execute that same instance. */
60
+ export async function runManagedVitest(cwd, args, ceiling, report = () => { }) {
61
+ let context;
62
+ let started = false;
63
+ let outcome = 120;
64
+ let api;
65
+ try {
66
+ if (args[0] !== "run")
67
+ throw new Error("Managed Vitest requires the run command; watch is not yet supported");
68
+ const require = createRequire(join(cwd, "package.json"));
69
+ const packagePath = require.resolve("vitest/package.json");
70
+ const pkg = JSON.parse(await readFile(packagePath, "utf8"));
71
+ const major = Number(pkg.version.split(".")[0]);
72
+ if (major !== 4 && major !== 5)
73
+ throw new Error(`Unsupported managed Vitest major ${major}`);
74
+ api = (await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("vitest/node")).href)));
75
+ const parsed = api.parseCLI(["vitest", ...args]);
76
+ const options = parsed.options;
77
+ if (options.watch ||
78
+ options.standalone ||
79
+ options.ui ||
80
+ options.api ||
81
+ options.mergeReports ||
82
+ options.help ||
83
+ options.version ||
84
+ options.inspect ||
85
+ options.inspectBrk) {
86
+ throw new Error("Managed Vitest supports a finite run, without watch, UI, API or report merging");
87
+ }
88
+ const requested = options.maxWorkers;
89
+ let requestedCeiling = ceiling;
90
+ if (requested !== undefined) {
91
+ if (!/^\d+$/.test(String(requested)) ||
92
+ !Number.isSafeInteger(Number(requested)) ||
93
+ Number(requested) < 1 ||
94
+ Number(requested) > ceiling) {
95
+ throw new Error("Managed --maxWorkers must be a positive integer no higher than the launcher ceiling");
96
+ }
97
+ requestedCeiling = Number(requested);
98
+ // A CLI flag must not override the app's lower computed cap. Resolve
99
+ // the app once without this override, then take the minimum below.
100
+ delete options.maxWorkers;
101
+ }
102
+ process.env.TEST = "true";
103
+ process.env.VITEST = "true";
104
+ process.env.NODE_ENV ??= "test";
105
+ Object.assign(options, {
106
+ root: options.root ?? cwd,
107
+ run: true,
108
+ watch: false,
109
+ });
110
+ context =
111
+ major === 4
112
+ ? await api.createVitest("test", options)
113
+ : await api.createVitest(options);
114
+ if (context.projects.length !== 1)
115
+ throw new Error("Managed Vitest requires exactly one resolved project");
116
+ const rootWorkers = clampResolvedTestWorkers(context.config, requestedCeiling);
117
+ for (const project of context.projects)
118
+ clampResolvedTestWorkers(project.config, rootWorkers);
119
+ // No new unchecked project may appear in an onInit reporter hook.
120
+ Object.freeze(context.projects);
121
+ Object.defineProperty(context, "projects", {
122
+ value: context.projects,
123
+ writable: false,
124
+ configurable: false,
125
+ });
126
+ report(rootWorkers, String(context.config.pool));
127
+ started = true;
128
+ const result = await context.start(parsed.filter);
129
+ outcome =
130
+ result.unhandledErrors.length ||
131
+ result.testModules.some((module) => module.state() === "failed")
132
+ ? 1
133
+ : Number(process.exitCode ?? 0);
134
+ }
135
+ catch (error) {
136
+ const Missing = api?.TestsNotFoundError ?? api?.FilesNotFoundError;
137
+ if (started &&
138
+ context?.config.passWithNoTests &&
139
+ Missing &&
140
+ error instanceof Missing)
141
+ outcome = 0;
142
+ else {
143
+ console.error(`Loom ${started ? "test runner" : "test preflight"}: ${error instanceof Error ? error.message : String(error)}`);
144
+ outcome = started ? 1 : 120;
145
+ }
146
+ }
147
+ finally {
148
+ try {
149
+ await context?.close();
150
+ }
151
+ catch (error) {
152
+ console.error("Loom test cleanup:", error);
153
+ if (outcome === 0)
154
+ outcome = 1;
155
+ }
156
+ }
157
+ return outcome;
158
+ }
159
+ //# sourceMappingURL=testVitestRunner.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testVitestRunner.js","sourceRoot":"","sources":["../../../source/src/cli/testVitestRunner.ts"],"names":[],"mappings":";;;;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAuCzC,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AAEtD,iFAAiF;AACjF,MAAM,UAAU,wBAAwB,CACtC,MAAqB,EACrB,OAAe;IAEf,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QACtD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;IACvB,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,YAAY,GAChB,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,KAAK;QACb,GAAG,KAAK,IAAI;QACZ,CAAC,OAAO,GAAG,KAAK,QAAQ;YACtB,CAAC,CAAC,gBAAgB,IAAI,GAAG,CAAC;YAC1B,GAAG,CAAC,cAAc,KAAK,IAAI;YAC3B,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC;IAC/C,IACE,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,UAAU;QACjB,MAAM,CAAC,EAAE;QACT,YAAY;QACZ,MAAM,CAAC,YAAY;QACnB,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,UAAU;QACjB,MAAM,CAAC,QAAQ;QACf,MAAM,CAAC,OAAO,EAAE,OAAO;QACvB,MAAM,CAAC,SAAS,EAAE,OAAO,EACzB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,+IAA+I,CAChJ,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC;IACnC,IACE,QAAQ,KAAK,SAAS;QACtB,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,EACjD,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,IAAI,OAAO,CAAC,CAAC;IACxD,4EAA4E;IAC5E,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE;QAC1C,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,IAAI;QAChB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,IAAc,EACd,OAAe,EACf,SAAkD,GAAG,EAAE,GAAE,CAAC;IAE1D,IAAI,OAAkC,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,OAAO,GAAG,GAAG,CAAC;IAClB,IAAI,GAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK;YACnB,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;QACJ,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;QACzD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAwB,IAAI,CAAC,KAAK,CACzC,MAAM,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,CACpC,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,EAAE,CAAC,CAAC;QAC/D,GAAG,GAAG,CAAC,MAAM,MAAM,kCACjB,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,EACnD,CAAc,CAAC;QAChB,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IACE,OAAO,CAAC,KAAK;YACb,OAAO,CAAC,UAAU;YAClB,OAAO,CAAC,EAAE;YACV,OAAO,CAAC,GAAG;YACX,OAAO,CAAC,YAAY;YACpB,OAAO,CAAC,IAAI;YACZ,OAAO,CAAC,OAAO;YACf,OAAO,CAAC,OAAO;YACf,OAAO,CAAC,UAAU,EAClB,CAAC;YACD,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,gBAAgB,GAAG,OAAO,CAAC;QAC/B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,IACE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAChC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACxC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;gBACrB,MAAM,CAAC,SAAS,CAAC,GAAG,OAAO,EAC3B,CAAC;gBACD,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;YACJ,CAAC;YACD,gBAAgB,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YACrC,qEAAqE;YACrE,mEAAmE;YACnE,OAAO,OAAO,CAAC,UAAU,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE;YACrB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG;YACzB,GAAG,EAAE,IAAI;YACT,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,OAAO;YACL,KAAK,KAAK,CAAC;gBACT,CAAC,CAAC,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC;gBACzC,CAAC,CAAC,MAAM,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,MAAM,WAAW,GAAG,wBAAwB,CAC1C,OAAO,CAAC,MAAM,EACd,gBAAgB,CACjB,CAAC;QACF,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ;YACpC,wBAAwB,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACxD,kEAAkE;QAClE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE;YACzC,KAAK,EAAE,OAAO,CAAC,QAAQ;YACvB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;QACH,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO;YACL,MAAM,CAAC,eAAe,CAAC,MAAM;gBAC7B,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,QAAQ,CAAC;gBAC9D,CAAC,CAAC,CAAC;gBACH,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,GAAG,EAAE,kBAAkB,IAAI,GAAG,EAAE,kBAAkB,CAAC;QACnE,IACE,OAAO;YACP,OAAO,EAAE,MAAM,CAAC,eAAe;YAC/B,OAAO;YACP,KAAK,YAAY,OAAO;YAExB,OAAO,GAAG,CAAC,CAAC;aACT,CAAC;YACJ,OAAO,CAAC,KAAK,CACX,QAAQ,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAC;YACF,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9B,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;YAC3C,IAAI,OAAO,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gadicc/loom",
3
- "version": "2.2.0",
3
+ "version": "2.3.0",
4
4
  "description": "Shared helpers and verification tooling for Next.js applications.",
5
5
  "homepage": "https://github.com/gadicc/loom#readme",
6
6
  "repository": {
@@ -11,7 +11,7 @@
11
11
  "url": "https://github.com/gadicc/loom/issues"
12
12
  },
13
13
  "loom": {
14
- "gitCommit": "a7beb2d659957e577c285a5be200230209a62d1f"
14
+ "gitCommit": "817997c7edff2e3adbe62c8849504e80734fd027"
15
15
  },
16
16
  "type": "module",
17
17
  "main": "./esm/mod.js",
@@ -82,13 +82,16 @@ Use this skill when working on the shared DB stack from a consuming app.
82
82
 
83
83
  ## Validation and tests
84
84
 
85
+ Read [test boundaries and local resources](references/test-boundaries.md) before
86
+ retargeting existing tests, changing test backends or adopting resource controls.
87
+
85
88
  - Use `loom db schema-gen` after schema changes that affect generated Valibot
86
89
  output.
87
90
  - Use `loom db schemas sync` to refresh active Loom-managed schema blueprints,
88
91
  then review diffs and run the normal migration generation flow deliberately.
89
92
  - Keep `src/db/valibot/generated/*` generated and committed, never hand-edited.
90
- - Prefer `tests/memory-pglite.ts` plus a mock of `@/db/neon` or `@/db/neonFull`
91
- for DB-backed unit tests.
93
+ - For SQL assertions, prefer `tests/memory-pglite.ts` plus a mock of `@/db/neon`
94
+ or `@/db/neonFull`; pure decisions should not initialize a database.
92
95
  - If fixtures are used, keep them under `tests/fixtures/db/` and serialize them
93
96
  with `superjson`.
94
97
 
@@ -0,0 +1,76 @@
1
+ # Database test boundaries and local resources
2
+
3
+ Retarget tests by what their assertions prove. Pure decisions use plain values
4
+ and a module with no runtime DB/schema import. Feature orchestration may use a
5
+ small repository fake only when the fake and real implementation share a
6
+ contract suite. SQL predicates, joins, mapping, constraints and persistence stay
7
+ on PGlite. Independent transactions, locking/isolation, RLS/roles, production
8
+ extensions and version-specific behavior need native PostgreSQL with the
9
+ relevant independent connections. Provider transport needs its own adapter gate.
10
+ PGlite remains appropriate for SQL; a JS PostgreSQL emulator is not the default.
11
+
12
+ Preserve the original business assertions when splitting a test. Add actual
13
+ production-loader coverage before removing test-local SQL setup. Seed targeted
14
+ query faults (for example a missing owner/building predicate or wrong join) and
15
+ confirm the retained SQL tests fail. Keep useful service/repository end-to-end
16
+ paths. Do not convert tests based only on filenames or a target percentage.
17
+ Required integration commands fail when their backend or expected discovery is
18
+ missing; a silently skipped native suite does not prove that coverage exists.
19
+
20
+ For investigation, the shared harness has optional synchronous `onTiming`
21
+ events with phase, duration and status only. Keep collectors short, omit them
22
+ normally, and use `harness.close()` for observed owned cleanup. Existing
23
+ `client.close()` remains valid. Do not log fixtures, SQL, paths or credentials.
24
+
25
+ On a Loom version that provides the resource commands:
26
+
27
+ ```sh
28
+ loom test resources doctor
29
+ loom test run --workers auto --cpu-mode exclude --dry-run -- vitest run
30
+ loom test run --workers auto --cpu-mode exclude -- vitest run
31
+ ```
32
+
33
+ `auto` selects the visible CPU/quota ceiling; it is not a measured optimum.
34
+ Existing lower app caps remain authoritative. An explicit numeric count may
35
+ lower demand. Local Linux exclusion reserves all SMT siblings of the same
36
+ stable machine cores across projects; it never chooses replacement cores from
37
+ an inherited private mask. One or two physical cores are reserved according to
38
+ small-device thresholds. There is no persistent machine policy or aggregate
39
+ worker/memory admission. Identical stateless v1 clients need the same visible
40
+ online topology; inspect their epochs when diagnosing differences.
41
+
42
+ CI ignores the local worker request, exclusion and desktop memory floor, while
43
+ retaining container limits and deliberate app/runner caps. `--test-profile local`
44
+ explicitly overrides CI detection; `ci` explicitly selects CI behavior. On
45
+ unknown local quota the pilot degrades to one worker. Unknown or insufficient
46
+ local memory headroom refuses the run; there is no calibrated per-worker memory
47
+ estimate or hard memory isolation.
48
+
49
+ Only finite, single-project Vitest 4/5 Node pools (`threads`/`forks`) are
50
+ supported. Existing environments such as jsdom remain app-configured. Watch, UI/API, standalone/report merging, inspectors,
51
+ browser/VM/custom pools, multi-project runs and percentage CLI worker overrides
52
+ are unavailable. Config loads once; lowering CLI counts work, while escalation
53
+ and late attempts to raise the resolved bound fail before test execution.
54
+ The CLI runs Vitest in Node, including when Loom itself starts in Bun or Deno.
55
+ Keep any explicitly Bun-executed Vitest task on its existing path until that
56
+ runner runtime has its own verified adapter.
57
+
58
+ Preserve the app's pool, config, filters, environment wrapper and prerequisites.
59
+ For example, keep an existing `loom env --` outside the resource command and
60
+ keep generated-data/i18n steps before it. Read recorded `project.tooling` before
61
+ editing a task; do not assume npm scripts or pnpm. Resource controls apply to
62
+ the runner child, after those prerequisites and normal Loom sync. Progress goes
63
+ to stderr; reporter stdout is retained. `--quiet-test-resources` suppresses
64
+ Loom's resource summary.
65
+
66
+ Normal terminal job control is retained. Nonterminal POSIX termination is
67
+ forwarded to the owned process group; no daemon, SIGKILL/orphan containment or
68
+ active-run drain guarantee is provided. Use verified disposable scopes for
69
+ unattended performance experiments. Other users and unwrapped jobs remain
70
+ outside this policy. Do not promise OS responsiveness or speed from affinity.
71
+
72
+ Keep new controls opt-in until representative comparisons justify adoption.
73
+ The initial busy-desktop pilot found two workers slower than the unchanged
74
+ three-file selection, and per-run prepared SQL was slower after preparation.
75
+ Neither result determines the best setting for another app/device. No worker
76
+ count, DB backend replacement or cross-run cache is selected fleet-wide.
@@ -57,6 +57,10 @@ changing the target repository.
57
57
  migrations, smoke-test it, and only then promote it. Keep automatic preview
58
58
  deployments, but disable automatic `main` production deployments once that
59
59
  release workflow is ready.
60
+ - For new GitHub release workflows, use short-lived GitHub OIDC through Vercel
61
+ Trusted Sources for protected HTTP checks. Read the Loom release safety and
62
+ Trusted Sources references before writing the workflow. Deployment/promotion
63
+ still needs its separate bounded Vercel API credential.
60
64
  - Keep secrets out of commits, command arguments, logs, caches, and uploaded
61
65
  artifacts. Document variable names in `.env.example`.
62
66
 
@@ -187,6 +187,14 @@ Set the chosen Vercel function region in `vercel.json`. For a DB-backed app,
187
187
  build the GitHub-to-Vercel staged release before disabling Vercel's automatic
188
188
  production deployment for `main`.
189
189
 
190
+ Before writing release steps, read
191
+ [Loom release safety](../../loom/references/release-safety.md) and
192
+ [Trusted Sources adoption](../../loom/references/release-trusted-sources.md).
193
+ For a new GitHub workflow, choose GitHub OIDC for protected HTTP checks; the
194
+ legacy create/check/revoke bypass sequence remains compatibility guidance for
195
+ existing apps. OIDC does not replace deployment/promotion API authentication,
196
+ database migration credentials, or normal application sign-in.
197
+
190
198
  Use Loom's setup commands where applicable:
191
199
 
192
200
  ```text
@@ -206,8 +214,23 @@ The app-local workflow must:
206
214
  6. build and scan the exact prebuilt artifact;
207
215
  7. upload it with `--prebuilt --prod --skip-domain`;
208
216
  8. run the backward-compatible Drizzle migration;
209
- 9. smoke-test the staged deployment through a short-lived protection bypass;
210
- 10. promote that exact deployment and revoke the bypass even on failure.
217
+ 9. verify the immutable deployment's project, owner, and source identity, then
218
+ smoke-test it using `createGithubActionsOidcFetch` from `@gadicc/loom/release`;
219
+ 10. promote that exact deployment and verify its canonical alias through OIDC.
220
+
221
+ Use `loom db release trust-plan`, review its exact repository ID/name, branch,
222
+ GitHub environment, workflow, audience, and target Vercel environment, then apply
223
+ and verify the reviewed plan within the user's authorization. Grant the HTTP
224
+ check job `id-token: write`; keep the deployment API token out of HTTP-only steps.
225
+ Prove real allowed and denied identities in read-only acceptance jobs before
226
+ claiming the OIDC setup works. Do not deploy, migrate, or promote from those jobs.
227
+
228
+ A missing GitHub link blocks identity-bound trust planning; it does not change
229
+ the recommended HTTP transport. Complete the authorized repository link or report
230
+ that prerequisite, and keep release promotion gated until OIDC acceptance passes.
231
+ Do not silently scaffold a bypass fallback just because linking is unfinished.
232
+ For an existing app that retains a bypass, preserve create/check/revoke cleanup
233
+ on every failure path until its deliberate OIDC migration passes acceptance.
211
234
 
212
235
  Keep preview deployments automatic. Pin third-party Actions to reviewed full
213
236
  commit SHAs and let Dependabot maintain them.
@@ -57,6 +57,8 @@ import {
57
57
  syncSourceDev,
58
58
  watchSourceDev,
59
59
  } from "./sourceDev.ts";
60
+ import { runTestResourceDoctor } from "./testResourceCommand.ts";
61
+ import { runManagedTestCommand } from "./testResourceLaunch.ts";
60
62
 
61
63
  import {
62
64
  type FilesR2DirectUploadPolicy,
@@ -23779,6 +23781,12 @@ function printHelp({ out }: CliOutput) {
23779
23781
  out("loom <command>");
23780
23782
  out("");
23781
23783
  out("Commands:");
23784
+ out(
23785
+ " test run --workers <count|auto> -- vitest run [args] Opt in to verified finite worker controls (--cpu-mode inherit|exclude, --dry-run).",
23786
+ );
23787
+ out(
23788
+ " test resources doctor Inspect local/CI resource limits without changing policy (--json, --test-profile local|ci).",
23789
+ );
23782
23790
  out(
23783
23791
  " init Set up package/Deno config, loom.json, managed AGENTS.md guidance, first-party links, and package skills.",
23784
23792
  );
@@ -25194,6 +25202,12 @@ function printSkillsHelp({ out }: CliOutput) {
25194
25202
  out("loom skills <command> [skill]");
25195
25203
  out("");
25196
25204
  out("Commands:");
25205
+ out(
25206
+ " test run --workers <count|auto> -- vitest run [args] Opt in to verified finite worker controls (--cpu-mode inherit|exclude, --dry-run).",
25207
+ );
25208
+ out(
25209
+ " test resources doctor Inspect local/CI resource limits without changing policy (--json, --test-profile local|ci).",
25210
+ );
25197
25211
  out(" list Show discovered, adopted, disabled, and recommended skills.");
25198
25212
  out(" add Adopt selected external or installed npm skills.");
25199
25213
  out(" sync Restore recorded skill content and links.");
@@ -26620,6 +26634,12 @@ export async function runCli(
26620
26634
  force: { type: "boolean" },
26621
26635
  help: { short: "h", type: "boolean" },
26622
26636
  jurisdiction: { type: "string" },
26637
+ json: { type: "boolean" },
26638
+ "test-profile": { type: "string" },
26639
+ "cpu-mode": { type: "string" },
26640
+ workers: { type: "string" },
26641
+ "quiet-test-resources": { type: "boolean" },
26642
+ "dry-run": { type: "boolean" },
26623
26643
  "local-bucket": { type: "string" },
26624
26644
  "local-db-host": { type: "string" },
26625
26645
  "local-db-port": { type: "string" },
@@ -26663,6 +26683,28 @@ export async function runCli(
26663
26683
  }
26664
26684
 
26665
26685
  const [command, arg1, arg2, ...rest] = parsed.positionals;
26686
+ const resourceRun = command === "test" && arg1 === "run";
26687
+ const resourceDoctor =
26688
+ command === "test" && arg1 === "resources" && arg2 === "doctor";
26689
+ // A generic dry-run flag must never be silently ignored by another command
26690
+ // that could provision resources. Refuse before automatic local-dev sync.
26691
+ if (
26692
+ (parsed.values["dry-run"] && !resourceRun) ||
26693
+ (parsed.values.json && !resourceDoctor) ||
26694
+ (!resourceRun &&
26695
+ (parsed.values.workers !== undefined ||
26696
+ parsed.values["cpu-mode"] !== undefined ||
26697
+ parsed.values["quiet-test-resources"])) ||
26698
+ (!resourceRun &&
26699
+ !resourceDoctor &&
26700
+ parsed.values["test-profile"] !== undefined)
26701
+ ) {
26702
+ io.err(
26703
+ "Test-resource flags apply only to their documented loom test command; no command ran.",
26704
+ );
26705
+ return 1;
26706
+ }
26707
+
26666
26708
  const cwd = parsed.values.cwd
26667
26709
  ? resolve(process.cwd(), parsed.values.cwd)
26668
26710
  : process.cwd();
@@ -26670,6 +26712,8 @@ export async function runCli(
26670
26712
  const productionCheck =
26671
26713
  command === "check" && (parsed.values.production ?? false);
26672
26714
  const addListOnly = command === "add" && arg1 === undefined;
26715
+ const testResourceDoctor =
26716
+ command === "test" && arg1 === "resources" && arg2 === "doctor";
26673
26717
 
26674
26718
  if (
26675
26719
  command !== undefined &&
@@ -26680,6 +26724,8 @@ export async function runCli(
26680
26724
  command !== "skills" &&
26681
26725
  command !== "status" &&
26682
26726
  !addListOnly &&
26727
+ !testResourceDoctor &&
26728
+ !(command === "test" && arg1 === "run" && parsed.values["dry-run"]) &&
26683
26729
  !productionCheck &&
26684
26730
  !parsed.values["no-sync"]
26685
26731
  ) {
@@ -26815,6 +26861,30 @@ export async function runCli(
26815
26861
  return await runSkills(cwd, arg1, [arg2, ...rest].filter(Boolean), io, {
26816
26862
  acceptUnknownLicense: parsed.values["accept-unknown-license"],
26817
26863
  });
26864
+ case "test":
26865
+ if (arg1 === "run") {
26866
+ if (!args.includes("--")) {
26867
+ io.err("Use -- before the Vitest command.");
26868
+ return 1;
26869
+ }
26870
+ return await runManagedTestCommand(
26871
+ cwd,
26872
+ args.slice(args.indexOf("--") + 1),
26873
+ {
26874
+ workers: parsed.values.workers,
26875
+ cpuMode: parsed.values["cpu-mode"],
26876
+ profile: parsed.values["test-profile"],
26877
+ quiet: parsed.values["quiet-test-resources"],
26878
+ dryRun: parsed.values["dry-run"],
26879
+ },
26880
+ io,
26881
+ );
26882
+ }
26883
+ return await runTestResourceDoctor(
26884
+ [arg1, arg2, ...rest],
26885
+ { profile: parsed.values["test-profile"], json: parsed.values.json },
26886
+ io,
26887
+ );
26818
26888
  case "env":
26819
26889
  return await runEnvCommand(
26820
26890
  cwd,