@evandam93/dev-env 0.0.0-stage → 0.1.1

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 (48) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +282 -2
  3. package/bin/dev-env.js +3 -0
  4. package/dist/abandoned.d.ts +2 -0
  5. package/dist/abandoned.js +66 -0
  6. package/dist/affected/graph.d.ts +43 -0
  7. package/dist/affected/graph.js +222 -0
  8. package/dist/affected/index.d.ts +5 -0
  9. package/dist/affected/index.js +3 -0
  10. package/dist/affected/layout.d.ts +11 -0
  11. package/dist/affected/layout.js +34 -0
  12. package/dist/affected/run.d.ts +10 -0
  13. package/dist/affected/run.js +96 -0
  14. package/dist/affected/select.d.ts +27 -0
  15. package/dist/affected/select.js +79 -0
  16. package/dist/checkout.d.ts +13 -0
  17. package/dist/checkout.js +40 -0
  18. package/dist/cli.d.ts +1 -0
  19. package/dist/cli.js +98 -0
  20. package/dist/compose.d.ts +18 -0
  21. package/dist/compose.js +119 -0
  22. package/dist/environment.d.ts +33 -0
  23. package/dist/environment.js +387 -0
  24. package/dist/errors.d.ts +4 -0
  25. package/dist/errors.js +4 -0
  26. package/dist/index.d.ts +4 -0
  27. package/dist/index.js +2 -0
  28. package/dist/machine.d.ts +3 -0
  29. package/dist/machine.js +17 -0
  30. package/dist/manifest.d.ts +95 -0
  31. package/dist/manifest.js +91 -0
  32. package/dist/ports.d.ts +6 -0
  33. package/dist/ports.js +92 -0
  34. package/dist/processes.d.ts +13 -0
  35. package/dist/processes.js +116 -0
  36. package/dist/readiness.d.ts +6 -0
  37. package/dist/readiness.js +31 -0
  38. package/dist/shared.d.ts +9 -0
  39. package/dist/shared.js +81 -0
  40. package/dist/slots.d.ts +21 -0
  41. package/dist/slots.js +165 -0
  42. package/dist/state.d.ts +21 -0
  43. package/dist/state.js +36 -0
  44. package/dist/test-environment.d.ts +36 -0
  45. package/dist/test-environment.js +67 -0
  46. package/dist/workspace.d.ts +31 -0
  47. package/dist/workspace.js +140 -0
  48. package/package.json +75 -4
@@ -0,0 +1,387 @@
1
+ import { existsSync, mkdirSync, rmSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { removeAbandonedProjects } from './abandoned.js';
4
+ import { checkoutRootsOf, composeProjectOf, environmentIdOf, environmentKeyOf, isTestMode, resolveCheckout, } from './checkout.js';
5
+ import { assertDockerAvailable, assertServicesAreSafe, composeDownWithVolumes, composeFileOf, composeRemoveWithVolumes, composeStop, composeUp, isDockerAvailable, runningServicesOf, testOverrideOf, } from './compose.js';
6
+ import { DevEnvError } from './errors.js';
7
+ import { availableTargets, loadTarget, portVariablesOf, testSettingsOf, } from './manifest.js';
8
+ import { choosePort, isPortInUse, LOOPBACK, preferredPortOf, withAllocationLock, } from './ports.js';
9
+ import { isLeaderLive, isRecordedProcessLive, startProcess, stopProcess, tailOf, } from './processes.js';
10
+ import { waitUntilAnswering } from './readiness.js';
11
+ import { ensureSharedServices, portsSharedOnMachine, runningSharedServicesOf, sharedServicesOf, } from './shared.js';
12
+ import { dataDirectoryOf, environmentDirectoryOf, readAllStates, readState, removeState, writeState, } from './state.js';
13
+ const DEFAULT_TIMEOUT_MS = 120_000;
14
+ const LOG_LINES_ON_FAILURE = 20;
15
+ const UNALLOCATED_PORT = 0;
16
+ /** The environment's own containers, leaving out those shared on the machine. */
17
+ const composeServicesOf = (target) => Object.entries(target.manifest.services)
18
+ .filter(([, service]) => service.kind === 'compose' && !service.shared)
19
+ .map(([name]) => name);
20
+ const needsDocker = (target) => Object.values(target.manifest.services).some((service) => service.kind === 'compose');
21
+ const processServicesOf = (target) => Object.entries(target.manifest.services).flatMap(([name, service]) => service.kind === 'process' ? [[name, service]] : []);
22
+ /*
23
+ * Compose interpolates the whole file for every command, so one service added
24
+ * to the manifest since the ports were recorded would fail even a `ps`. The
25
+ * placeholder is never published, because allocation runs before any `up`.
26
+ */
27
+ const composeProjectFor = (checkout, target, mode, ports) => ({
28
+ name: composeProjectOf(checkout, target.name, mode),
29
+ directory: target.directory,
30
+ files: [
31
+ composeFileOf(target.directory),
32
+ ...(isTestMode(mode) && existsSync(testOverrideOf(target.directory))
33
+ ? [testOverrideOf(target.directory)]
34
+ : []),
35
+ ],
36
+ variables: portVariablesOf({
37
+ ...Object.fromEntries(Object.keys(target.manifest.services).map((service) => [
38
+ service,
39
+ UNALLOCATED_PORT,
40
+ ])),
41
+ ...ports,
42
+ }),
43
+ });
44
+ const composeTimeoutOf = (target, services) => Math.max(...services.map((service) => target.manifest.services[service]?.timeoutMs ?? DEFAULT_TIMEOUT_MS));
45
+ const usesCompose = (target) => composeServicesOf(target).length > 0;
46
+ const portsClaimedElsewhere = async (checkout, ownKey) => {
47
+ const roots = await checkoutRootsOf(checkout);
48
+ const others = roots.flatMap((root) => readAllStates(root).filter((state) => root !== checkout.root ||
49
+ environmentKeyOf(state.target, state.mode) !== ownKey));
50
+ return new Set(others.flatMap((state) => Object.values(state.ports)));
51
+ };
52
+ /*
53
+ * A probe only says what is listening right now, and a sibling's container
54
+ * between a remove and a create looks free. The recorded claims, read and
55
+ * written under the lock, are what keep two environments apart.
56
+ */
57
+ const allocatePorts = (checkout, target, mode, sharedPorts) => withAllocationLock(checkout.gitCommonDirectory, async () => {
58
+ const key = environmentKeyOf(target.name, mode);
59
+ const previous = readState(checkout.root, target.name, mode);
60
+ const claimed = new Set([
61
+ ...(await portsClaimedElsewhere(checkout, key)),
62
+ ...portsSharedOnMachine(),
63
+ ]);
64
+ const provisional = composeProjectFor(checkout, target, mode, {
65
+ ...previous?.ports,
66
+ });
67
+ const running = usesCompose(target) && previous !== undefined
68
+ ? await runningServicesOf(provisional)
69
+ : new Map();
70
+ const ports = { ...sharedPorts };
71
+ for (const [service, definition] of Object.entries(target.manifest.services)) {
72
+ if (service in sharedPorts)
73
+ continue;
74
+ const recorded = previous?.processes[service];
75
+ const isOurs = async (port) => {
76
+ if (previous?.ports[service] !== port)
77
+ return false;
78
+ if (definition.kind === 'compose')
79
+ return running.get(service) === port;
80
+ return recorded !== undefined && (await isRecordedProcessLive(recorded));
81
+ };
82
+ const port = await choosePort(previous?.ports[service] ??
83
+ preferredPortOf(`${checkout.id}:${key}:${service}`), async (candidate) => claimed.has(candidate) ||
84
+ ((await isPortInUse(candidate)) && !(await isOurs(candidate))));
85
+ ports[service] = port;
86
+ claimed.add(port);
87
+ }
88
+ const state = {
89
+ environmentId: checkout.id,
90
+ target: target.name,
91
+ mode,
92
+ ports,
93
+ processes: previous?.processes ?? {},
94
+ };
95
+ writeState(checkout.root, state);
96
+ return state;
97
+ });
98
+ const waitForProcessReady = async (name, service, port, isLive, logPath) => {
99
+ const url = `http://${LOOPBACK}:${port}${service.readinessPath}`;
100
+ const timeoutMs = service.timeoutMs ?? DEFAULT_TIMEOUT_MS;
101
+ const failure = (reason) => new DevEnvError(`Service "${name}" ${reason}.\n${tailOf(logPath, LOG_LINES_ON_FAILURE)}`);
102
+ const readiness = await waitUntilAnswering({ url, timeoutMs, isLive });
103
+ if (readiness === 'exited')
104
+ throw failure('exited before it was ready');
105
+ if (readiness === 'timed out')
106
+ throw failure(`did not answer ${url} within ${timeoutMs} ms`);
107
+ };
108
+ /*
109
+ * One at a time, each ready before the next starts: the processes of a target
110
+ * share one local state directory, and Wrangler runtimes that open it at the
111
+ * same moment fail with a locked database.
112
+ */
113
+ const startProcesses = async (checkout, target, initial, services = processServicesOf(target)) => {
114
+ let state = initial;
115
+ for (const [name, service] of services) {
116
+ const recorded = state.processes[name];
117
+ if (recorded !== undefined) {
118
+ if (await isLeaderLive(recorded))
119
+ continue;
120
+ // What survived its leader may no longer be serving, so it is replaced.
121
+ await stopProcess(recorded);
122
+ }
123
+ const port = state.ports[name];
124
+ if (port === undefined) {
125
+ throw new DevEnvError(`Service "${name}" has no allocated port.`);
126
+ }
127
+ const logPath = join(environmentDirectoryOf(checkout.root, target.name, state.mode), `${name}.log`);
128
+ const dataDirectory = dataDirectoryOf(checkout.root, target.name, state.mode);
129
+ mkdirSync(dataDirectory, { recursive: true });
130
+ const started = await startProcess({
131
+ command: service.command({
132
+ environmentName: composeProjectOf(checkout, target.name, state.mode),
133
+ settings: state.settings ?? {},
134
+ port,
135
+ ports: state.ports,
136
+ dataDirectory,
137
+ }),
138
+ directory: target.directory,
139
+ environment: { ...portVariablesOf(state.ports), PORT: String(port) },
140
+ logPath,
141
+ });
142
+ state = {
143
+ ...state,
144
+ processes: { ...state.processes, [name]: started },
145
+ };
146
+ writeState(checkout.root, state);
147
+ try {
148
+ await waitForProcessReady(name, service, port, () => isLeaderLive(started), logPath);
149
+ }
150
+ catch (error) {
151
+ await stopProcess(started);
152
+ throw error;
153
+ }
154
+ }
155
+ return state;
156
+ };
157
+ const startSharedServices = async (checkout, target) => sharedServicesOf(target).length === 0
158
+ ? {}
159
+ : ensureSharedServices(target, await portsClaimedElsewhere(checkout, ''));
160
+ export const startTarget = async (cwd, targetName, mode) => {
161
+ const checkout = await resolveCheckout(cwd);
162
+ const target = await loadTarget(checkout.root, targetName);
163
+ const services = composeServicesOf(target);
164
+ if (needsDocker(target)) {
165
+ await assertDockerAvailable();
166
+ await removeAbandonedProjects();
167
+ }
168
+ const state = await allocatePorts(checkout, target, mode, await startSharedServices(checkout, target));
169
+ if (services.length > 0) {
170
+ const project = composeProjectFor(checkout, target, mode, state.ports);
171
+ await assertServicesAreSafe(project, services);
172
+ await composeUp(project, services, composeTimeoutOf(target, services));
173
+ }
174
+ const { setup, afterStart } = target.manifest;
175
+ if (setup !== undefined && !isTestMode(mode)) {
176
+ try {
177
+ await setup({ ports: state.ports });
178
+ }
179
+ catch (error) {
180
+ const reason = error instanceof Error ? error.message : String(error);
181
+ throw new DevEnvError(`Setup of "${target.name}" failed: ${reason}`);
182
+ }
183
+ }
184
+ await startProcesses(checkout, target, state);
185
+ if (afterStart !== undefined && !isTestMode(mode)) {
186
+ try {
187
+ await afterStart({ ports: state.ports });
188
+ }
189
+ catch (error) {
190
+ const reason = error instanceof Error ? error.message : String(error);
191
+ throw new DevEnvError(`After starting "${target.name}" failed: ${reason}`);
192
+ }
193
+ }
194
+ return describe(checkout, target, mode);
195
+ };
196
+ /*
197
+ * What a test file finds at its start: the containers its lane already runs,
198
+ * recreated empty, those shared on the machine left running, and every process
199
+ * started again on an empty data directory. A lane that is not fully running
200
+ * is reset and started from nothing.
201
+ */
202
+ export const startTestTarget = async (cwd, targetName, mode, { without = [], settings: asked = {}, } = {}) => {
203
+ const checkout = await resolveCheckout(cwd);
204
+ const target = await loadTarget(checkout.root, targetName);
205
+ const settings = testSettingsOf(target.manifest, asked);
206
+ const services = composeServicesOf(target);
207
+ const processes = processServicesOf(target).filter(([name]) => !without.includes(name));
208
+ if (needsDocker(target))
209
+ await removeAbandonedProjects();
210
+ const sharedPorts = await startSharedServices(checkout, target);
211
+ const previous = readState(checkout.root, targetName, mode);
212
+ const running = previous !== undefined && services.length > 0
213
+ ? await runningServicesOf(composeProjectFor(checkout, target, mode, previous.ports))
214
+ : new Map();
215
+ const isWarm = previous !== undefined &&
216
+ services.every((service) => running.get(service) === previous.ports[service]);
217
+ if (!isWarm) {
218
+ await resetTarget(cwd, targetName, mode);
219
+ const state = {
220
+ ...(await allocatePorts(checkout, target, mode, sharedPorts)),
221
+ settings,
222
+ };
223
+ writeState(checkout.root, state);
224
+ if (services.length > 0) {
225
+ const project = composeProjectFor(checkout, target, mode, state.ports);
226
+ await assertServicesAreSafe(project, services);
227
+ await composeUp(project, services, composeTimeoutOf(target, services));
228
+ }
229
+ await startProcesses(checkout, target, state, processes);
230
+ return describe(checkout, target, mode);
231
+ }
232
+ await stopProcesses(checkout, previous);
233
+ rmSync(dataDirectoryOf(checkout.root, targetName, mode), {
234
+ recursive: true,
235
+ force: true,
236
+ });
237
+ const state = {
238
+ ...previous,
239
+ ports: { ...previous.ports, ...sharedPorts },
240
+ processes: {},
241
+ settings,
242
+ };
243
+ writeState(checkout.root, state);
244
+ if (services.length > 0) {
245
+ const project = composeProjectFor(checkout, target, mode, state.ports);
246
+ await composeRemoveWithVolumes(project, services);
247
+ await composeUp(project, services, composeTimeoutOf(target, services));
248
+ }
249
+ await startProcesses(checkout, target, state, processes);
250
+ return describe(checkout, target, mode);
251
+ };
252
+ const stopProcesses = async (checkout, state) => {
253
+ await Promise.all(Object.values(state.processes).map(stopProcess));
254
+ writeState(checkout.root, { ...state, processes: {} });
255
+ };
256
+ /* Keeps ports, volumes and containers so the next start resumes where this left off. */
257
+ export const stopTarget = async (cwd, targetName, mode) => {
258
+ const checkout = await resolveCheckout(cwd);
259
+ const state = readState(checkout.root, targetName, mode);
260
+ if (state === undefined)
261
+ return;
262
+ const target = await loadTarget(checkout.root, targetName);
263
+ await stopProcesses(checkout, state);
264
+ if (usesCompose(target)) {
265
+ await assertDockerAvailable();
266
+ await composeStop(composeProjectFor(checkout, target, mode, state.ports));
267
+ }
268
+ };
269
+ /* `test` stops every test lane. */
270
+ export const stopAll = async (cwd, mode) => {
271
+ const checkout = await resolveCheckout(cwd);
272
+ const states = readAllStates(checkout.root).filter((state) => mode === undefined ||
273
+ state.mode === mode ||
274
+ (mode === 'test' && isTestMode(state.mode)));
275
+ await Promise.all(states.map((state) => stopTarget(cwd, state.target, state.mode)));
276
+ };
277
+ export const resetTarget = async (cwd, targetName, mode) => {
278
+ const checkout = await resolveCheckout(cwd);
279
+ const state = readState(checkout.root, targetName, mode);
280
+ if (state === undefined)
281
+ return;
282
+ const target = await loadTarget(checkout.root, targetName);
283
+ await stopProcesses(checkout, state);
284
+ if (usesCompose(target)) {
285
+ await assertDockerAvailable();
286
+ await composeDownWithVolumes(composeProjectFor(checkout, target, mode, state.ports));
287
+ }
288
+ removeState(checkout.root, targetName, mode);
289
+ };
290
+ const startedServiceOf = async (cwd, targetName, mode, service) => {
291
+ const checkout = await resolveCheckout(cwd);
292
+ const target = await loadTarget(checkout.root, targetName);
293
+ const definition = target.manifest.services[service];
294
+ if (definition === undefined) {
295
+ throw new DevEnvError(`Target "${targetName}" has no service "${service}".`);
296
+ }
297
+ if (definition.kind === 'compose' && definition.shared) {
298
+ throw new DevEnvError(`Service "${service}" is shared by every environment on this machine, so no one environment stops or starts it.`);
299
+ }
300
+ const state = readState(checkout.root, targetName, mode);
301
+ if (state === undefined) {
302
+ throw new DevEnvError(`Target "${targetName}" has not been started.`);
303
+ }
304
+ return { checkout, target, state, definition };
305
+ };
306
+ export const stopService = async (cwd, targetName, mode, service) => {
307
+ const { checkout, target, state, definition } = await startedServiceOf(cwd, targetName, mode, service);
308
+ if (definition.kind === 'compose') {
309
+ const project = composeProjectFor(checkout, target, mode, state.ports);
310
+ await composeStop(project, [service]);
311
+ return;
312
+ }
313
+ const recorded = state.processes[service];
314
+ if (recorded !== undefined)
315
+ await stopProcess(recorded);
316
+ };
317
+ export const startService = async (cwd, targetName, mode, service) => {
318
+ const { checkout, target, state, definition } = await startedServiceOf(cwd, targetName, mode, service);
319
+ if (definition.kind === 'compose') {
320
+ const project = composeProjectFor(checkout, target, mode, state.ports);
321
+ await composeUp(project, [service], definition.timeoutMs ?? DEFAULT_TIMEOUT_MS);
322
+ return;
323
+ }
324
+ await startProcesses(checkout, target, state, [[service, definition]]);
325
+ };
326
+ const runningOrNoneWithoutDocker = async (read) => {
327
+ try {
328
+ return await read();
329
+ }
330
+ catch (error) {
331
+ if (await isDockerAvailable())
332
+ throw error;
333
+ return new Map();
334
+ }
335
+ };
336
+ const describe = async (checkout, target, mode) => {
337
+ const state = readState(checkout.root, target.name, mode);
338
+ const ports = state?.ports ?? {};
339
+ const project = composeProjectFor(checkout, target, mode, ports);
340
+ const running = new Map([
341
+ ...(usesCompose(target) && state !== undefined
342
+ ? await runningOrNoneWithoutDocker(() => runningServicesOf(project))
343
+ : []),
344
+ ...(state !== undefined
345
+ ? await runningOrNoneWithoutDocker(() => runningSharedServicesOf(target))
346
+ : []),
347
+ ]);
348
+ const services = {};
349
+ for (const [name, service] of Object.entries(target.manifest.services)) {
350
+ const port = ports[name];
351
+ if (port === undefined)
352
+ continue;
353
+ const recorded = state?.processes[name];
354
+ const isRunning = service.kind === 'compose'
355
+ ? running.has(name)
356
+ : recorded !== undefined && (await isRecordedProcessLive(recorded));
357
+ const address = `${LOOPBACK}:${port}`;
358
+ services[name] = {
359
+ kind: service.kind,
360
+ running: isRunning,
361
+ port,
362
+ address,
363
+ ...(service.kind === 'process' ? { url: `http://${address}` } : {}),
364
+ };
365
+ }
366
+ return {
367
+ target: target.name,
368
+ mode,
369
+ name: project.name,
370
+ ...(usesCompose(target) ? { composeProject: project.name } : {}),
371
+ services,
372
+ };
373
+ };
374
+ export const describeCheckout = async (cwd) => {
375
+ const checkout = await resolveCheckout(cwd);
376
+ const environments = [];
377
+ for (const state of readAllStates(checkout.root)) {
378
+ const target = await loadTarget(checkout.root, state.target);
379
+ environments.push(await describe(checkout, target, state.mode));
380
+ }
381
+ return {
382
+ environmentId: environmentIdOf(checkout.root),
383
+ checkout: checkout.root,
384
+ available: availableTargets(checkout.root),
385
+ environments,
386
+ };
387
+ };
@@ -0,0 +1,4 @@
1
+ /** A failure the person running the command can act on, printed without a stack. */
2
+ export declare class DevEnvError extends Error {
3
+ readonly name = "DevEnvError";
4
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,4 @@
1
+ /** A failure the person running the command can act on, printed without a stack. */
2
+ export class DevEnvError extends Error {
3
+ name = 'DevEnvError';
4
+ }
@@ -0,0 +1,4 @@
1
+ export type { CommandContext, ComposeService, Manifest, ProcessService, Service, SetupContext, } from './manifest.ts';
2
+ export { defineManifest } from './manifest.ts';
3
+ export type { TestEnvironment, TestEnvironmentOptions, } from './test-environment.ts';
4
+ export { resetTestEnvironments, startTestEnvironment, } from './test-environment.ts';
package/dist/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export { defineManifest } from './manifest.js';
2
+ export { resetTestEnvironments, startTestEnvironment, } from './test-environment.js';
@@ -0,0 +1,3 @@
1
+ export declare const machineDirectoryOf: (environment?: NodeJS.ProcessEnv) => string;
2
+ /** Tells apart the machine directories, so a test's shared services are never a real run's. */
3
+ export declare const machineIdOf: (directory: string) => string;
@@ -0,0 +1,17 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { mkdirSync } from 'node:fs';
3
+ import { homedir } from 'node:os';
4
+ import { join } from 'node:path';
5
+ /*
6
+ * What every checkout on this machine shares: the lane slots and the shared
7
+ * services. DEV_ENV_HOME moves it, so dev-env's own tests share nothing with
8
+ * real runs.
9
+ */
10
+ export const machineDirectoryOf = (environment = process.env) => {
11
+ const directory = environment.DEV_ENV_HOME ??
12
+ join(environment.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'dev-env');
13
+ mkdirSync(directory, { recursive: true });
14
+ return directory;
15
+ };
16
+ /** Tells apart the machine directories, so a test's shared services are never a real run's. */
17
+ export const machineIdOf = (directory) => createHash('sha256').update(directory).digest('hex').slice(0, 8);
@@ -0,0 +1,95 @@
1
+ export interface CommandContext {
2
+ /** Names this environment uniquely on the machine, to tell its data apart in a shared service. */
3
+ readonly environmentName: string;
4
+ /**
5
+ * What a test asked its environment for, such as raised limits, by names
6
+ * the manifest gives them. Empty for a dev environment, so nothing a test
7
+ * asks for reaches one, or anything deployed.
8
+ */
9
+ readonly settings: Readonly<Record<string, string>>;
10
+ readonly port: number;
11
+ readonly ports: Readonly<Record<string, number>>;
12
+ /** Where the process keeps its own data. It survives a stop and goes on reset. */
13
+ readonly dataDirectory: string;
14
+ }
15
+ export interface ProcessService {
16
+ readonly kind: 'process';
17
+ readonly command: (context: CommandContext) => readonly string[];
18
+ /** The path that answers below 400 once the service is usable. */
19
+ readonly readinessPath: string;
20
+ readonly timeoutMs?: number;
21
+ /**
22
+ * The directories, relative to the target, holding the code this process
23
+ * runs, such as a Worker's own and any it loads beside it. A change under
24
+ * one, or to a file their code imports, reaches every integration spec
25
+ * that starts this process.
26
+ */
27
+ readonly sources: readonly string[];
28
+ }
29
+ /** Named after its service in the target's compose.yaml. */
30
+ export interface ComposeService {
31
+ readonly kind: 'compose';
32
+ readonly timeoutMs?: number;
33
+ /**
34
+ * One container for every checkout, mode and lane on the machine, started
35
+ * the first time any of them needs it and kept. Only for a service whose
36
+ * data a reader can tell apart by its own environment, IDs and time, such
37
+ * as telemetry.
38
+ */
39
+ readonly shared?: boolean;
40
+ }
41
+ export type Service = ProcessService | ComposeService;
42
+ export interface SetupContext {
43
+ readonly ports: Readonly<Record<string, number>>;
44
+ }
45
+ export interface Manifest {
46
+ readonly services: Readonly<Record<string, Service>>;
47
+ /**
48
+ * Globs, relative to the target or from the repository with a leading `/`,
49
+ * for what the target's test environments are built from without importing
50
+ * it, such as migrations. A change to one runs every integration spec.
51
+ */
52
+ readonly shared?: readonly string[];
53
+ /**
54
+ * Integration specs, relative to the target, that a pull request's affected
55
+ * run always holds, such as the product's own scenarios, and those it never
56
+ * holds, which only the full suite runs before a release, such as a paced
57
+ * replay.
58
+ */
59
+ readonly specs?: {
60
+ readonly always?: readonly string[];
61
+ readonly beforeRelease?: readonly string[];
62
+ };
63
+ /**
64
+ * Runs on every dev start, once the compose services are healthy and before
65
+ * any process starts, so it must be safe to run again, as migrations are.
66
+ * Test environments skip it, because each test file sets up its own data.
67
+ */
68
+ readonly setup?: (context: SetupContext) => Promise<void>;
69
+ /**
70
+ * Runs on every dev start once every process is ready, for data only a
71
+ * running process can make, such as people a stand-in directory holds. It
72
+ * must be safe to run again, and test environments skip it as they skip
73
+ * setup.
74
+ */
75
+ readonly afterStart?: (context: SetupContext) => Promise<void>;
76
+ /**
77
+ * Settings every test environment of the target starts with, such as a
78
+ * feature flag on, under the ones a spec asks for, which win. A dev
79
+ * environment never gets them.
80
+ */
81
+ readonly testSettings?: Readonly<Record<string, string>>;
82
+ }
83
+ export interface Target {
84
+ readonly name: string;
85
+ readonly directory: string;
86
+ readonly manifest: Manifest;
87
+ }
88
+ export declare const defineManifest: (manifest: Manifest) => Manifest;
89
+ /** A test environment's settings: the target's defaults, then what the spec asked for. */
90
+ export declare const testSettingsOf: (manifest: Manifest, asked: Readonly<Record<string, string>>) => Readonly<Record<string, string>>;
91
+ export declare const portVariableOf: (service: string) => string;
92
+ export declare const portVariablesOf: (ports: Readonly<Record<string, number>>) => Readonly<Record<string, string>>;
93
+ /** The targets of the repository: its workspaces with a dev-env.ts. */
94
+ export declare const availableTargets: (root: string) => readonly string[];
95
+ export declare const loadTarget: (root: string, name: string) => Promise<Target>;
@@ -0,0 +1,91 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { basename, dirname, join, relative } from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ import { getTsconfig } from 'get-tsconfig';
5
+ import { register as registerCommonJs } from 'tsx/cjs/api';
6
+ import { register as registerModule } from 'tsx/esm/api';
7
+ import { DevEnvError } from './errors.js';
8
+ import { isModulePackage, workspaceDirectoriesOf } from './workspace.js';
9
+ const MANIFEST = 'dev-env.ts';
10
+ export const defineManifest = (manifest) => manifest;
11
+ /** A test environment's settings: the target's defaults, then what the spec asked for. */
12
+ export const testSettingsOf = (manifest, asked) => ({ ...manifest.testSettings, ...asked });
13
+ export const portVariableOf = (service) => `${service.toUpperCase().replaceAll(/[^A-Z0-9]/g, '_')}_PORT`;
14
+ export const portVariablesOf = (ports) => Object.fromEntries(Object.entries(ports).map(([service, port]) => [
15
+ portVariableOf(service),
16
+ String(port),
17
+ ]));
18
+ /*
19
+ * Each workspace directory that holds a dev-env.ts, by its directory's name,
20
+ * which is all a command gives. Two with one name would make a command
21
+ * ambiguous, so they are refused.
22
+ */
23
+ const targetDirectoriesOf = (root) => {
24
+ const targets = new Map();
25
+ for (const directory of workspaceDirectoriesOf(root)) {
26
+ if (!existsSync(join(directory, MANIFEST)))
27
+ continue;
28
+ const name = basename(directory);
29
+ const other = targets.get(name);
30
+ if (other !== undefined)
31
+ throw new DevEnvError(`${relative(root, other)} and ${relative(root, directory)} are both named "${name}". Rename one of the directories, since a target is named after its directory.`);
32
+ targets.set(name, directory);
33
+ }
34
+ return targets;
35
+ };
36
+ /** The targets of the repository: its workspaces with a dev-env.ts. */
37
+ export const availableTargets = (root) => [...targetDirectoriesOf(root).keys()].toSorted();
38
+ const moduleLoader = (namespace, tsconfig) => {
39
+ const loader = registerModule({ namespace, tsconfig: tsconfig ?? false });
40
+ return async (file) => loader.import(pathToFileURL(file).href, import.meta.url);
41
+ };
42
+ const commonJsLoader = (namespace, tsconfig) => {
43
+ const previous = process.env.TSX_TSCONFIG_PATH;
44
+ if (tsconfig !== undefined)
45
+ process.env.TSX_TSCONFIG_PATH = tsconfig;
46
+ try {
47
+ const loader = registerCommonJs({ namespace });
48
+ return async (file) => loader.require(file, import.meta.url);
49
+ }
50
+ finally {
51
+ if (previous === undefined)
52
+ delete process.env.TSX_TSCONFIG_PATH;
53
+ else
54
+ process.env.TSX_TSCONFIG_PATH = previous;
55
+ }
56
+ };
57
+ const loaders = new Map();
58
+ const loaderFor = (file) => {
59
+ const tsconfig = getTsconfig(dirname(file))?.path;
60
+ const isModule = isModulePackage(dirname(file));
61
+ const key = `${isModule ? 'module' : 'commonjs'}:${tsconfig ?? ''}`;
62
+ let loader = loaders.get(key);
63
+ if (loader === undefined) {
64
+ const namespace = `dev-env-${loaders.size}`;
65
+ loader = isModule
66
+ ? moduleLoader(namespace, tsconfig)
67
+ : commonJsLoader(namespace, tsconfig);
68
+ loaders.set(key, loader);
69
+ }
70
+ return loader;
71
+ };
72
+ const importManifest = async (file) => {
73
+ const loaded = (await loaderFor(file)(file));
74
+ const manifest = loaded.default;
75
+ if (typeof manifest !== 'object' || manifest === null)
76
+ throw new DevEnvError(`${file} has no default export. Export its manifest with \`export default defineManifest({ ... })\`.`);
77
+ return manifest;
78
+ };
79
+ export const loadTarget = async (root, name) => {
80
+ const targets = targetDirectoriesOf(root);
81
+ const directory = targets.get(name);
82
+ if (directory === undefined) {
83
+ const known = [...targets.keys()].toSorted().join(', ') || 'none';
84
+ throw new DevEnvError(`Unknown target "${name}". Available: ${known}. A target is a workspace directory with a ${MANIFEST}.`);
85
+ }
86
+ return {
87
+ name,
88
+ directory,
89
+ manifest: await importManifest(join(directory, MANIFEST)),
90
+ };
91
+ };
@@ -0,0 +1,6 @@
1
+ export declare const LOOPBACK = "127.0.0.1";
2
+ export declare const preferredPortOf: (seed: string) => number;
3
+ export declare const choosePort: (preferred: number, isTaken: (port: number) => boolean | Promise<boolean>) => Promise<number>;
4
+ export declare const isPortInUse: (port: number) => Promise<boolean>;
5
+ export declare const withLock: <T>(path: string, timeoutMs: number, work: () => Promise<T>) => Promise<T>;
6
+ export declare const withAllocationLock: <T>(gitCommonDirectory: string, work: () => Promise<T>) => Promise<T>;