nx 24.0.0-beta.2 → 24.0.0-beta.3

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 (137) hide show
  1. package/dist/bin/post-install.js +5 -3
  2. package/dist/src/adapter/ngcli-adapter.js +1 -2
  3. package/dist/src/command-line/add/add.d.ts +2 -0
  4. package/dist/src/command-line/add/add.js +23 -5
  5. package/dist/src/command-line/affected/affected.js +2 -2
  6. package/dist/src/command-line/init/implementation/add-nx-to-nest.js +21 -62
  7. package/dist/src/command-line/migrate/agentic/definitions.d.ts +1 -3
  8. package/dist/src/command-line/migrate/agentic/definitions.js +5 -97
  9. package/dist/src/command-line/migrate/agentic/handoff-gitignore.d.ts +7 -41
  10. package/dist/src/command-line/migrate/agentic/handoff-gitignore.js +9 -48
  11. package/dist/src/command-line/migrate/agentic/handoff.d.ts +1 -43
  12. package/dist/src/command-line/migrate/agentic/handoff.js +3 -119
  13. package/dist/src/command-line/migrate/agentic/instruction-files.d.ts +0 -21
  14. package/dist/src/command-line/migrate/agentic/instruction-files.js +6 -27
  15. package/dist/src/command-line/migrate/agentic/master/run-master-session.d.ts +19 -1
  16. package/dist/src/command-line/migrate/agentic/master/run-master-session.js +63 -36
  17. package/dist/src/command-line/migrate/agentic/master/spawn-master.d.ts +1 -0
  18. package/dist/src/command-line/migrate/agentic/master/spawn-master.js +7 -5
  19. package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.d.ts +2 -2
  20. package/dist/src/command-line/migrate/agentic/print-dropped-agent-context.js +2 -2
  21. package/dist/src/command-line/migrate/agentic/prompts/fragments.d.ts +1 -12
  22. package/dist/src/command-line/migrate/agentic/prompts/fragments.js +8 -17
  23. package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.d.ts +0 -15
  24. package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.js +3 -100
  25. package/dist/src/command-line/migrate/agentic/select.d.ts +12 -6
  26. package/dist/src/command-line/migrate/agentic/select.js +35 -5
  27. package/dist/src/command-line/migrate/agentic/types.d.ts +9 -68
  28. package/dist/src/command-line/migrate/agentic/types.js +5 -5
  29. package/dist/src/command-line/migrate/command-object.js +3 -3
  30. package/dist/src/command-line/migrate/migrate-analytics.d.ts +12 -1
  31. package/dist/src/command-line/migrate/migrate-analytics.js +26 -0
  32. package/dist/src/command-line/migrate/migrate-commits.d.ts +9 -10
  33. package/dist/src/command-line/migrate/migrate-commits.js +25 -18
  34. package/dist/src/command-line/migrate/migrate-output.d.ts +1 -6
  35. package/dist/src/command-line/migrate/migrate-output.js +1 -10
  36. package/dist/src/command-line/migrate/migrate.js +16 -27
  37. package/dist/src/command-line/migrate/run/agent-output.d.ts +1 -0
  38. package/dist/src/command-line/migrate/run/agent-output.js +4 -0
  39. package/dist/src/command-line/migrate/run/broker.js +1 -1
  40. package/dist/src/command-line/migrate/run/give-up.d.ts +4 -3
  41. package/dist/src/command-line/migrate/run/give-up.js +8 -5
  42. package/dist/src/command-line/migrate/run/index.d.ts +2 -1
  43. package/dist/src/command-line/migrate/run/index.js +5 -1
  44. package/dist/src/command-line/migrate/run/issues.js +7 -2
  45. package/dist/src/command-line/migrate/run/orchestrator.d.ts +40 -4
  46. package/dist/src/command-line/migrate/run/orchestrator.js +233 -92
  47. package/dist/src/command-line/migrate/run/run-state.d.ts +4 -1
  48. package/dist/src/command-line/migrate/run/run-state.js +20 -2
  49. package/dist/src/command-line/migrate/run/runbook.d.ts +1 -0
  50. package/dist/src/command-line/migrate/run/runbook.js +99 -21
  51. package/dist/src/command-line/migrate/run/state-lock.d.ts +29 -4
  52. package/dist/src/command-line/migrate/run/state-lock.js +102 -10
  53. package/dist/src/command-line/migrate/run/util.d.ts +4 -2
  54. package/dist/src/command-line/migrate/run/util.js +23 -2
  55. package/dist/src/command-line/migrate/run/worker.d.ts +1 -1
  56. package/dist/src/command-line/migrate/run/worker.js +252 -250
  57. package/dist/src/command-line/release/changelog.js +9 -6
  58. package/dist/src/command-line/release/config/config.d.ts +1 -0
  59. package/dist/src/command-line/release/config/config.js +48 -9
  60. package/dist/src/command-line/release/release.js +2 -2
  61. package/dist/src/command-line/release/utils/git.js +8 -7
  62. package/dist/src/command-line/release/utils/interpolate-release-config.d.ts +6 -0
  63. package/dist/src/command-line/release/utils/interpolate-release-config.js +39 -0
  64. package/dist/src/command-line/release/utils/release-graph.d.ts +5 -0
  65. package/dist/src/command-line/release/utils/release-graph.js +1 -0
  66. package/dist/src/command-line/release/utils/resolve-changelog-renderer.js +2 -2
  67. package/dist/src/command-line/release/utils/shared.js +10 -10
  68. package/dist/src/command-line/release/utils/version-plan-utils.d.ts +3 -12
  69. package/dist/src/command-line/release/utils/version-plan-utils.js +33 -55
  70. package/dist/src/command-line/release/version/version-actions.js +2 -1
  71. package/dist/src/command-line/release/version.js +5 -2
  72. package/dist/src/command-line/show/projects.js +5 -3
  73. package/dist/src/command-line/yargs-utils/shared-options.js +1 -1
  74. package/dist/src/config/nx-json.d.ts +8 -5
  75. package/dist/src/config/workspace-json-project-json.d.ts +12 -9
  76. package/dist/src/core/graph/main.js +1 -1
  77. package/dist/src/devkit-exports.d.ts +4 -0
  78. package/dist/src/devkit-exports.js +6 -1
  79. package/dist/src/devkit-internals.d.ts +1 -1
  80. package/dist/src/devkit-internals.js +4 -3
  81. package/dist/src/executors/run-commands/run-commands.impl.d.ts +2 -2
  82. package/dist/src/executors/run-commands/run-commands.impl.js +20 -10
  83. package/dist/src/executors/run-commands/running-tasks.d.ts +12 -3
  84. package/dist/src/executors/run-commands/running-tasks.js +22 -18
  85. package/dist/src/hasher/check-task-files.js +1 -4
  86. package/dist/src/migrations/update-23-2-0/set-cache-on-executor-target-defaults.d.ts +1 -2
  87. package/dist/src/migrations/update-23-2-0/set-cache-on-executor-target-defaults.js +6 -11
  88. package/dist/src/migrations/update-23-2-0/set-cache-on-executor-target-defaults.md +2 -2
  89. package/dist/src/migrations/update-24-0-0/enable-legacy-affected.d.ts +4 -0
  90. package/dist/src/migrations/update-24-0-0/enable-legacy-affected.js +15 -0
  91. package/dist/src/migrations/update-24-0-0/enable-legacy-affected.md +30 -0
  92. package/dist/src/migrations/update-24-0-0/move-custom-hashers-to-inputs.md +7 -6
  93. package/dist/src/migrations/update-24-0-0/rename-ultracache-ignore-options.d.ts +3 -0
  94. package/dist/src/migrations/update-24-0-0/rename-ultracache-ignore-options.js +130 -0
  95. package/dist/src/migrations/update-24-0-0/rename-ultracache-ignore-options.md +62 -0
  96. package/dist/src/native/index.d.ts +3 -3
  97. package/dist/src/native/nx.wasm32-wasi.debug.wasm +0 -0
  98. package/dist/src/native/nx.wasm32-wasi.wasm +0 -0
  99. package/dist/src/plugins/js/lock-file/pnpm-parser.js +1 -3
  100. package/dist/src/plugins/js/lock-file/pruned-output.d.ts +2 -2
  101. package/dist/src/plugins/js/lock-file/pruned-output.js +4 -4
  102. package/dist/src/project-graph/affected/affected-tasks.d.ts +6 -5
  103. package/dist/src/project-graph/affected/affected-tasks.js +16 -6
  104. package/dist/src/project-graph/utils/project-configuration/target-merging.js +1 -1
  105. package/dist/src/project-graph/utils/project-configuration/target-normalization.js +7 -133
  106. package/dist/src/project-graph/utils/project-configuration-utils.js +2 -2
  107. package/dist/src/tasks-runner/readiness/probes.js +30 -1
  108. package/dist/src/tasks-runner/readiness/ready-when.d.ts +31 -10
  109. package/dist/src/tasks-runner/readiness/ready-when.js +178 -41
  110. package/dist/src/tasks-runner/task-orchestrator.d.ts +4 -0
  111. package/dist/src/tasks-runner/task-orchestrator.js +113 -38
  112. package/dist/src/tasks-runner/tokens.d.ts +54 -0
  113. package/dist/src/tasks-runner/tokens.js +161 -0
  114. package/dist/src/tasks-runner/utils.d.ts +15 -1
  115. package/dist/src/tasks-runner/utils.js +79 -33
  116. package/dist/src/utils/acknowledge-build-scripts.d.ts +34 -1
  117. package/dist/src/utils/acknowledge-build-scripts.js +171 -32
  118. package/dist/src/utils/long-running-target.d.ts +1 -3
  119. package/dist/src/utils/long-running-target.js +1 -3
  120. package/migrations.json +13 -6
  121. package/package.json +11 -11
  122. package/schemas/nx-schema.json +17 -11
  123. package/schemas/project-schema.json +8 -7
  124. package/dist/src/command-line/migrate/agentic/prompts/generic-validation.d.ts +0 -56
  125. package/dist/src/command-line/migrate/agentic/prompts/generic-validation.js +0 -67
  126. package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.d.ts +0 -49
  127. package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.js +0 -53
  128. package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.d.ts +0 -26
  129. package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.js +0 -27
  130. package/dist/src/command-line/migrate/agentic/prompts/system-prompt.d.ts +0 -70
  131. package/dist/src/command-line/migrate/agentic/prompts/system-prompt.js +0 -113
  132. package/dist/src/command-line/migrate/agentic/run-step.d.ts +0 -68
  133. package/dist/src/command-line/migrate/agentic/run-step.js +0 -148
  134. package/dist/src/command-line/migrate/agentic/runner.d.ts +0 -21
  135. package/dist/src/command-line/migrate/agentic/runner.js +0 -262
  136. package/dist/src/migrations/update-23-0-0/consolidate-release-tag-config.d.ts +0 -9
  137. package/dist/src/migrations/update-23-0-0/consolidate-release-tag-config.js +0 -18
@@ -1,35 +1,17 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.FileReplacedDuringReadError = void 0;
4
- exports.runDirPath = runDirPath;
5
- exports.resolveAgenticRunId = resolveAgenticRunId;
6
4
  exports.mkdirSafely = mkdirSafely;
7
- exports.initRunDir = initRunDir;
8
5
  exports.truncateUtf8 = truncateUtf8;
9
- exports.stepHandoffPath = stepHandoffPath;
10
6
  exports.runStepHandoffPath = runStepHandoffPath;
11
- exports.stepPromptsDir = stepPromptsDir;
12
7
  exports.handoffsDirState = handoffsDirState;
13
8
  exports.ensureRunSubdir = ensureRunSubdir;
14
9
  exports.readInspectedFile = readInspectedFile;
15
10
  exports.readAtomicallyPublishedFile = readAtomicallyPublishedFile;
16
11
  exports.readHandoffWithReason = readHandoffWithReason;
17
- exports.readHandoff = readHandoff;
18
- exports.waitForValidHandoff = waitForValidHandoff;
19
- const crypto_1 = require("crypto");
20
12
  const fs_1 = require("fs");
21
13
  const path_1 = require("path");
22
- const semver_1 = require("semver");
23
- const version_utils_1 = require("../version-utils");
24
14
  const types_1 = require("./types");
25
- /** Returns the run directory for a given workspace + run id (target version). */
26
- function runDirPath(workspaceRoot, runId) {
27
- return (0, path_1.join)(workspaceRoot, types_1.MIGRATE_RUNS_RELATIVE_DIR, runId);
28
- }
29
- /** The version-derived run id: the highest target version in the plan. */
30
- function resolveAgenticRunId(migrations) {
31
- return (0, semver_1.rsort)(migrations.map((m) => (0, version_utils_1.normalizeVersion)(m.version)))[0];
32
- }
33
15
  /**
34
16
  * `mkdir -p` with a contextual error wrapper. Without this, the raw
35
17
  * ENOSPC/EACCES/EROFS surfaces with no indication of which directory the
@@ -48,35 +30,6 @@ function mkdirSafely(dir, purpose) {
48
30
  throw new Error(`Could not create ${purpose} at ${dir}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
49
31
  }
50
32
  }
51
- /**
52
- * Wipes any prior contents for this run id and recreates an empty directory.
53
- *
54
- * Scope of the wipe is intentionally narrow (only `<run-id>/`) so that handoff
55
- * artifacts from prior runs targeting different versions remain on disk for
56
- * inspection.
57
- */
58
- function initRunDir(workspaceRoot, runId) {
59
- const dir = runDirPath(workspaceRoot, runId);
60
- (0, fs_1.rmSync)(dir, { recursive: true, force: true });
61
- mkdirSafely(dir, 'nx migrate run directory');
62
- return dir;
63
- }
64
- // Windows reserved device names fail to open even with an extension —
65
- // a migration named `CON` would otherwise produce a `CON.json` that the
66
- // agent can't write to.
67
- const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
68
- function sanitizeSegment(value) {
69
- if (value === '.' || value === '..')
70
- return '_';
71
- let sanitized = value.replace(/[\x00-\x1f<>:"/\\|?*+]/g, '_');
72
- // Windows forbids trailing dots/spaces on file/directory names.
73
- sanitized = sanitized.replace(/[. ]+$/, '');
74
- if (WINDOWS_RESERVED_NAMES.test(sanitized)) {
75
- sanitized = `_${sanitized}`;
76
- }
77
- return sanitized || '_';
78
- }
79
- const STEP_NAME_PREFIX_MAX_BYTES = 64;
80
33
  // Truncates to a UTF-8 byte budget without splitting a code point.
81
34
  function truncateUtf8(value, maxBytes) {
82
35
  let out = '';
@@ -90,29 +43,9 @@ function truncateUtf8(value, maxBytes) {
90
43
  }
91
44
  return out;
92
45
  }
93
- /**
94
- * The name a step's own files are keyed by, bounded to fit one path component.
95
- * Sanitizing folds many characters to `_` and the prefix is cut to fit, so the
96
- * SHA-256 of the raw package and name is what keeps two migrations apart.
97
- */
98
- function stepStem(migration) {
99
- const prefix = truncateUtf8([...migration.package.split('/'), migration.name]
100
- .map(sanitizeSegment)
101
- .join('+'), STEP_NAME_PREFIX_MAX_BYTES);
102
- const hash = (0, crypto_1.createHash)('sha256')
103
- .update(JSON.stringify([migration.package, migration.name]))
104
- .digest('hex');
105
- return `${prefix}-${hash}`;
106
- }
107
- function stepHandoffPath(runDir, migration) {
108
- return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${stepStem(migration)}.json`);
109
- }
110
- /** Handoff path for a run step. No hash needed: step ids are unique within the run. */
46
+ // Step ids match run-state's STEP_ID (`step-<n>`), so they are safe file names.
111
47
  function runStepHandoffPath(runDir, stepId) {
112
- return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${sanitizeSegment(stepId)}.json`);
113
- }
114
- function stepPromptsDir(runDir, migration) {
115
- return (0, path_1.join)(runDir, types_1.PROMPTS_DIR_NAME, stepStem(migration));
48
+ return (0, path_1.join)(runDir, types_1.HANDOFFS_DIR_NAME, `${stepId}.json`);
116
49
  }
117
50
  /**
118
51
  * `lstat`, not `stat`: a symlink in the handoffs dir's place would send every
@@ -211,8 +144,7 @@ function readAtomicallyPublishedFile(filePath, notRegularMessage) {
211
144
  }
212
145
  /**
213
146
  * Splits "not written yet" from "written but garbage" so callers can surface a
214
- * malformed handoff instead of collapsing it into the generic
215
- * ambiguous-outcome prompt.
147
+ * malformed handoff instead of treating it as not written.
216
148
  */
217
149
  function readHandoffWithReason(filePath, handoffsDir) {
218
150
  let raw;
@@ -285,51 +217,3 @@ function readHandoffWithReason(filePath, handoffsDir) {
285
217
  }
286
218
  return { ok: true, handoff };
287
219
  }
288
- /**
289
- * Convenience wrapper preserving the original null-on-any-failure contract.
290
- * Used by the polling loop (`waitForValidHandoff`) where every failure mode
291
- * is "keep waiting" — the file may be missing, mid-write, or being rewritten.
292
- */
293
- function readHandoff(filePath, handoffsDir) {
294
- const result = readHandoffWithReason(filePath, handoffsDir);
295
- return result.ok ? result.handoff : null;
296
- }
297
- /**
298
- * Polls for a valid handoff file. Resolves once `readHandoff` accepts the
299
- * file's contents. Used to detect when the agent has finished its work so the
300
- * orchestrator can close the agent's session without depending on the agent
301
- * exiting on its own.
302
- *
303
- * Rejects with the abort reason when `options.signal` is aborted.
304
- */
305
- function waitForValidHandoff(handoffFilePath, handoffsDir, options = {}) {
306
- const intervalMs = options.intervalMs ?? 500;
307
- const { signal } = options;
308
- return new Promise((resolve, reject) => {
309
- if (signal?.aborted) {
310
- reject(signal.reason ?? new Error('aborted'));
311
- return;
312
- }
313
- let timer;
314
- const onAbort = () => {
315
- if (timer)
316
- clearTimeout(timer);
317
- signal?.removeEventListener('abort', onAbort);
318
- reject(signal.reason ?? new Error('aborted'));
319
- };
320
- const tick = () => {
321
- if (signal?.aborted) {
322
- onAbort();
323
- return;
324
- }
325
- if (readHandoff(handoffFilePath, handoffsDir) !== null) {
326
- signal?.removeEventListener('abort', onAbort);
327
- resolve();
328
- return;
329
- }
330
- timer = setTimeout(tick, intervalMs);
331
- };
332
- signal?.addEventListener('abort', onAbort);
333
- timer = setTimeout(tick, intervalMs);
334
- });
335
- }
@@ -1,23 +1,2 @@
1
- export interface StepInstructionFiles {
2
- /** Absolute path: config loaders resolve it, not the agent from its cwd. */
3
- systemPromptFilePath: string;
4
- /** Single-line command-line text pointing the agent at its instructions. */
5
- instructionsPointer: string;
6
- }
7
- export interface WriteStepInstructionFilesArgs {
8
- workspaceRoot: string;
9
- runDir: string;
10
- migration: {
11
- package: string;
12
- name: string;
13
- };
14
- systemPrompt: string;
15
- instructions: string;
16
- }
17
- /**
18
- * Writes prompts as files on every platform to keep one delivery path.
19
- * Windows npm shims cannot carry multi-line prompts within cmd.exe's limit.
20
- */
21
- export declare function writeStepInstructionFiles(args: WriteStepInstructionFilesArgs): StepInstructionFiles;
22
1
  /** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
23
2
  export declare function writeInstructionsFile(workspaceRoot: string, promptsDir: string, instructions: string): string;
@@ -1,41 +1,20 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.writeStepInstructionFiles = writeStepInstructionFiles;
4
3
  exports.writeInstructionsFile = writeInstructionsFile;
5
4
  const fs_1 = require("fs");
6
5
  const path_1 = require("path");
7
- const handoff_1 = require("./handoff");
8
- /**
9
- * Writes prompts as files on every platform to keep one delivery path.
10
- * Windows npm shims cannot carry multi-line prompts within cmd.exe's limit.
11
- */
12
- function writeStepInstructionFiles(args) {
13
- const { workspaceRoot, runDir, migration, systemPrompt, instructions } = args;
14
- const promptsDir = (0, handoff_1.stepPromptsDir)(runDir, migration);
15
- (0, handoff_1.mkdirSafely)(promptsDir, `prompt directory for ${migration.name}`);
16
- const systemPromptFilePath = (0, path_1.join)(promptsDir, 'system.md');
17
- writeStepFile(systemPromptFilePath, systemPrompt, 'system prompt');
18
- const instructionsFilePath = writeInstructionsFile(workspaceRoot, promptsDir, instructions);
19
- return {
20
- systemPromptFilePath,
21
- instructionsPointer: `Your instructions for this migration step are in the file ${instructionsFilePath} (path is relative to the workspace root). Read it in full, then follow it.`,
22
- };
23
- }
24
6
  /** Writes `instructions.md` into an existing `promptsDir`; returns its path. */
25
7
  function writeInstructionsFile(workspaceRoot, promptsDir, instructions) {
26
8
  const absolutePath = (0, path_1.join)(promptsDir, 'instructions.md');
27
- writeStepFile(absolutePath, instructions, 'instructions');
28
- // Workspace-relative: the agent resolves this one itself with its cwd pinned
29
- // to the workspace root. Forward slashes because it is read as prose out of
30
- // the agent's prompt, where a `\` is an escape.
31
- return (0, path_1.relative)(workspaceRoot, absolutePath).replace(/\\/g, '/');
32
- }
33
- function writeStepFile(filePath, contents, purpose) {
34
9
  try {
35
- (0, fs_1.writeFileSync)(filePath, contents, 'utf-8');
10
+ (0, fs_1.writeFileSync)(absolutePath, instructions, 'utf-8');
36
11
  }
37
12
  catch (err) {
38
13
  const code = err?.code;
39
- throw new Error(`Could not write the step's ${purpose} to ${filePath}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
14
+ throw new Error(`Could not write the step's instructions to ${absolutePath}${code ? ` (${code})` : ''}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
40
15
  }
16
+ // Workspace-relative: the agent resolves this one itself with its cwd pinned
17
+ // to the workspace root. Forward slashes because it is read as prose out of
18
+ // the agent's prompt, where a `\` is an escape.
19
+ return (0, path_1.relative)(workspaceRoot, absolutePath).replace(/\\/g, '/');
41
20
  }
@@ -1,4 +1,4 @@
1
- import { type RunOrchestratorInitInput } from '../../run';
1
+ import { type MigrateRunPolicy, type MigrateRunState, type OrchestratorInitResult, type RunOrchestratorInitInput } from '../../run';
2
2
  import type { DetectedInstalledAgent } from '../types';
3
3
  export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'emitAgentInstructions' | 'onExistingRun'> {
4
4
  agent: DetectedInstalledAgent;
@@ -14,3 +14,21 @@ export interface RunMasterSessionInput extends Omit<RunOrchestratorInitInput, 'e
14
14
  * session ends, not what the agent process returned.
15
15
  */
16
16
  export declare function runMasterSession(input: RunMasterSessionInput): Promise<number | undefined>;
17
+ /**
18
+ * Hands a ready run to one agent session and reads the run's state once the
19
+ * session ends. `migration` is set for a `--run-migration` run. Returns null
20
+ * once it has printed why the session could not start or why its outcome is
21
+ * unknown; `notStartedHint` tells the user what to do when it could not start.
22
+ */
23
+ export declare function driveMasterSession(input: {
24
+ agent: DetectedInstalledAgent;
25
+ ready: Extract<OrchestratorInitResult, {
26
+ kind: 'ready';
27
+ }>;
28
+ policy: MigrateRunPolicy;
29
+ migration?: {
30
+ package: string;
31
+ name: string;
32
+ };
33
+ notStartedHint: string;
34
+ }): Promise<MigrateRunState | null>;
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.runMasterSession = runMasterSession;
4
+ exports.driveMasterSession = driveMasterSession;
4
5
  const output_1 = require("../../../../utils/output");
5
6
  const migrate_analytics_1 = require("../../migrate-analytics");
6
7
  const run_1 = require("../../run");
@@ -73,48 +74,19 @@ async function runMasterSession(input) {
73
74
  (0, migrate_analytics_1.reportMigrateRunStopped)(refusal);
74
75
  return;
75
76
  }
76
- const { runId, runRoot, runbookPath, reconcileCommand } = ready;
77
+ const { runId, runRoot } = ready;
77
78
  const resumeHint = continueHint(init.root, agent.id, runId, policy);
78
79
  output_1.output.log({
79
80
  title: `Starting ${agent.displayName} to drive migrate run ${runId}.`,
80
81
  });
81
- const session = await (0, spawn_master_1.spawnMasterSession)({
82
+ const state = await driveMasterSession({
82
83
  agent,
83
- runRoot,
84
- runId,
85
- runbookPath,
86
- reconcileCommand,
84
+ ready,
87
85
  policy,
86
+ notStartedHint: `Migrate run ${runId} is still active. ${resumeHint}`,
88
87
  });
89
- if (session.kind === 'spawn-failed') {
90
- output_1.output.error({
91
- title: `Could not start ${agent.displayName}: ${session.error.message}`,
92
- bodyLines: [`Migrate run ${runId} is still active. ${resumeHint}`],
93
- });
94
- (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
95
- return 1;
96
- }
97
- if (session.kind === 'broker-failed') {
98
- // The broker itself reads run.json, so its failure can mean the state is
99
- // unreadable; the read below decides whether a resume is safe to offer.
100
- output_1.output.error({
101
- title: `Closed the ${agent.displayName} session: a step's request could not be answered (${session.error.message}).`,
102
- });
103
- (0, migrate_analytics_1.reportMigrateRunError)({ code: 'agentic', error: session.error });
104
- }
105
- let state;
106
- try {
107
- state = (0, run_1.readRunState)((0, run_1.runDir)(runRoot, runId));
108
- }
109
- catch (error) {
110
- // No resume hint: run discovery skips a directory whose run.json is
111
- // missing, so a rerun could start a second run over the same plan.
112
- output_1.output.error({
113
- title: `Nx could not determine whether migrate run ${runId} completed.`,
114
- bodyLines: [error instanceof Error ? error.message : String(error)],
115
- });
88
+ if (!state)
116
89
  return 1;
117
- }
118
90
  switch (state.status) {
119
91
  case 'active':
120
92
  (0, migrate_analytics_1.reportMigrateOrchestratorAbandoned)({
@@ -156,6 +128,62 @@ async function runMasterSession(input) {
156
128
  }
157
129
  }
158
130
  }
131
+ /**
132
+ * Hands a ready run to one agent session and reads the run's state once the
133
+ * session ends. `migration` is set for a `--run-migration` run. Returns null
134
+ * once it has printed why the session could not start or why its outcome is
135
+ * unknown; `notStartedHint` tells the user what to do when it could not start.
136
+ */
137
+ async function driveMasterSession(input) {
138
+ const { agent, ready, policy, migration, notStartedHint } = input;
139
+ const { runId, runRoot, runbookPath, reconcileCommand } = ready;
140
+ const reportAgentError = (error) => (0, migrate_analytics_1.reportMigrateRunError)({
141
+ code: 'agentic',
142
+ migrationPackage: migration?.package,
143
+ migrationName: migration?.name,
144
+ error,
145
+ });
146
+ const session = await (0, spawn_master_1.spawnMasterSession)({
147
+ agent,
148
+ runRoot,
149
+ runId,
150
+ runbookPath,
151
+ reconcileCommand,
152
+ policy,
153
+ singleMigration: migration !== undefined,
154
+ });
155
+ if (session.kind === 'spawn-failed') {
156
+ output_1.output.error({
157
+ title: `Could not start ${agent.displayName}: ${session.error.message}`,
158
+ bodyLines: [notStartedHint],
159
+ });
160
+ reportAgentError(session.error);
161
+ return null;
162
+ }
163
+ if (session.kind === 'broker-failed') {
164
+ // The broker itself reads run.json, so its failure can mean the state is
165
+ // unreadable; the read below decides what the caller can offer.
166
+ output_1.output.error({
167
+ title: `Closed the ${agent.displayName} session: a step's request could not be answered (${session.error.message}).`,
168
+ });
169
+ reportAgentError(session.error);
170
+ }
171
+ try {
172
+ return (0, run_1.readRunState)((0, run_1.runDir)(runRoot, runId));
173
+ }
174
+ catch (error) {
175
+ // No resume hint for a `--run-migrations` run: run discovery skips a
176
+ // directory whose run.json is missing, so a rerun could start a second run
177
+ // over the same plan.
178
+ output_1.output.error({
179
+ title: `Nx could not determine whether ${migration
180
+ ? `migration ${migration.package}:${migration.name}`
181
+ : `migrate run ${runId}`} completed.`,
182
+ bodyLines: [error instanceof Error ? error.message : String(error)],
183
+ });
184
+ return null;
185
+ }
186
+ }
159
187
  function continueHint(root, agentId, runId, policy) {
160
188
  return `Run ${(0, run_1.renderContinueCommand)(root, runId, policy, agentId)} to continue it.`;
161
189
  }
@@ -164,8 +192,7 @@ async function decideExistingRun(found, root) {
164
192
  // A held run leaves nothing to ask: continue would open a second session
165
193
  // over the live one, and start fresh refuses. The continue's own gate
166
194
  // throws the refusal; a holder gone since the report lets the prompt run.
167
- if (found.facts.otherHolders === 'unknown' ||
168
- found.facts.otherHolders.length > 0) {
195
+ if ((0, run_1.isHeld)(found.facts.otherHolders)) {
169
196
  (0, run_1.holdRunToContinue)(root, found.runId);
170
197
  }
171
198
  return (0, safe_prompt_1.migrateChoice)({
@@ -7,6 +7,7 @@ export interface SpawnMasterSessionInput {
7
7
  runbookPath: string;
8
8
  reconcileCommand: string;
9
9
  policy: MigrateRunPolicy;
10
+ singleMigration?: boolean;
10
11
  sentinelPollIntervalMs?: number;
11
12
  gracefulExitMs?: number;
12
13
  forceKillWaitMs?: number;
@@ -49,7 +49,7 @@ function sessionCompleteSentinel(runRoot, runId, nonce) {
49
49
  * did is read from run state by the caller, never from the exit code.
50
50
  */
51
51
  async function spawnMasterSession(input) {
52
- const { agent, runRoot, runId, runbookPath, reconcileCommand, policy, sentinelPollIntervalMs = 500, gracefulExitMs = close_agent_session_1.AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = close_agent_session_1.FORCE_KILL_WAIT_MS, } = input;
52
+ const { agent, runRoot, runId, runbookPath, reconcileCommand, policy, singleMigration = false, sentinelPollIntervalMs = 500, gracefulExitMs = close_agent_session_1.AGENT_GRACEFUL_EXIT_MS, forceKillWaitMs = close_agent_session_1.FORCE_KILL_WAIT_MS, } = input;
53
53
  let sentinelPath;
54
54
  let child;
55
55
  let broker;
@@ -163,7 +163,7 @@ async function spawnMasterSession(input) {
163
163
  let stoppedWaiting = false;
164
164
  if (started && exited) {
165
165
  restoreTerminal();
166
- const inFlight = warnOperationInFlight(broker);
166
+ const inFlight = warnOperationInFlight(broker, singleMigration);
167
167
  if (inFlight && (await interruptedTwice(brokerDone, ctrlC))) {
168
168
  (0, spawn_without_terminal_1.signalCommandsWithoutTerminal)('SIGKILL');
169
169
  if (!(await (0, close_agent_session_1.raceWithTimeout)(brokerDone, OPERATION_KILL_WAIT_MS))) {
@@ -171,7 +171,7 @@ async function spawnMasterSession(input) {
171
171
  output_1.output.warn({
172
172
  title: `Stopped waiting for ${(0, run_1.treeOperationLabel)(inFlight.request, inFlight.stepName)}.`,
173
173
  bodyLines: [
174
- 'A process it started may still be running. Resume the run once it has exited.',
174
+ `A process it started may still be running. ${singleMigration ? 'Re-run the same command' : 'Resume the run'} once it has exited.`,
175
175
  ],
176
176
  });
177
177
  }
@@ -197,12 +197,14 @@ function restoreTerminal() {
197
197
  (0, migrate_output_1.resetSgrAfterAgent)();
198
198
  }
199
199
  // With the agent gone nothing else tells the user an operation still runs.
200
- function warnOperationInFlight(broker) {
200
+ function warnOperationInFlight(broker, singleMigration) {
201
201
  const inFlight = broker.requestInFlight;
202
202
  if (!inFlight)
203
203
  return null;
204
204
  output_1.output.warn({
205
- title: `Still running ${(0, run_1.treeOperationLabel)(inFlight.request, inFlight.stepName)} for this migrate run (${(0, run_1.formatElapsed)(Date.now() - inFlight.startedAt)} so far).${(0, run_1.commitsStep)(inFlight.request.kind) ? ` ${run_1.COMMIT_INSTALLS_FIRST}` : ''} Press Ctrl+C to end it, and again to stop everything it started. The run can be resumed afterwards.`,
205
+ title: `Still running ${(0, run_1.treeOperationLabel)(inFlight.request, inFlight.stepName)}${singleMigration ? '' : ' for this migrate run'} (${(0, run_1.formatElapsed)(Date.now() - inFlight.startedAt)} so far).${(0, run_1.commitsStep)(inFlight.request.kind) ? ` ${run_1.COMMIT_INSTALLS_FIRST}` : ''} Press Ctrl+C to end it, and again to stop everything it started. ${singleMigration
206
+ ? 'Re-run the same command afterwards to run the migration again.'
207
+ : 'The run can be resumed afterwards.'}`,
206
208
  });
207
209
  return inFlight;
208
210
  }
@@ -10,8 +10,8 @@ export declare function formatDroppedAgentContextForOuterAgent(input: DroppedAge
10
10
  export declare function escapeXmlAttr(value: string): string;
11
11
  /**
12
12
  * Both the classic loop and the single-migration worker call this only under
13
- * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
14
- * consumes `agentContext` through the prompt builders; under `disabled` the
13
+ * `agentic.kind === 'inside-agent'`. Under `enabled` a step that gives the
14
+ * agent work carries `agentContext` in its prompt block; under `disabled` the
15
15
  * run is human-driven and agent-targeted context is only noise.
16
16
  */
17
17
  export declare function printDroppedAgentContextForOuterAgent(input: DroppedAgentContextInput): void;
@@ -43,8 +43,8 @@ function escapeXmlAttr(value) {
43
43
  }
44
44
  /**
45
45
  * Both the classic loop and the single-migration worker call this only under
46
- * `agentic.kind === 'inside-agent'`. Under `enabled` the inner agent step
47
- * consumes `agentContext` through the prompt builders; under `disabled` the
46
+ * `agentic.kind === 'inside-agent'`. Under `enabled` a step that gives the
47
+ * agent work carries `agentContext` in its prompt block; under `disabled` the
48
48
  * run is human-driven and agent-targeted context is only noise.
49
49
  */
50
50
  function printDroppedAgentContextForOuterAgent(input) {
@@ -1,17 +1,6 @@
1
1
  export declare function renderNxInvocationNote(packageManager: string, nxInvocation: string): string;
2
2
  export declare function renderHandoffShapeInline(summaryHint: string): string;
3
3
  export declare function renderHandoffShapeLines(): string[];
4
- /**
5
- * Where the formatter command comes from. A prompt built right before the
6
- * agent runs carries the resolved command; the runbook outlives many steps,
7
- * so it points at the `Format command:` line each dispensed step resolves.
8
- */
9
- export type FormatInstruction = {
10
- source: 'command';
11
- command: string | null;
12
- } | {
13
- source: 'dispensed-step';
14
- };
15
- export declare function renderAuthorScopeRuleLines(pmExec: string, format: FormatInstruction): string[];
4
+ export declare function renderAuthorScopeRuleLines(pmExec: string): string[];
16
5
  export declare function renderValidationScopeRuleLines(): string[];
17
6
  export declare function renderFinalValidationScopeRuleLines(): string[];
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
- // Wording the agent system prompt (system-prompt.ts) and the orchestrated
3
- // run's runbook (run/runbook.ts) must state identically.
2
+ // The runbook's (run/runbook.ts) contract wording. The dispensed step blocks
3
+ // and the final validation instructions reuse parts of it word for word.
4
4
  Object.defineProperty(exports, "__esModule", { value: true });
5
5
  exports.renderNxInvocationNote = renderNxInvocationNote;
6
6
  exports.renderHandoffShapeInline = renderHandoffShapeInline;
@@ -25,11 +25,11 @@ function renderHandoffShapeLines() {
25
25
  `}`,
26
26
  ];
27
27
  }
28
- function renderAuthorScopeRuleLines(pmExec, format) {
28
+ function renderAuthorScopeRuleLines(pmExec) {
29
29
  return [
30
30
  `- Apply only the changes the migration prompt asks for.`,
31
31
  `- Do not refactor or update dependencies beyond what the migration prompt directs, and do not reformat files you did not change.`,
32
- renderFormatRule(pmExec, format),
32
+ renderFormatRule(pmExec),
33
33
  `- Do not modify files outside the workspace root.`,
34
34
  `- Do not edit anything under \`${types_1.MIGRATE_RUNS_RELATIVE_DIR}\` except the handoff file you are asked to write.`,
35
35
  `- Do not run \`nx\` commands that mutate workspace state (\`nx migrate\`, \`nx reset\`, \`nx format:write\`, \`nx run-many\`, generators, etc.). Read-only inspection (\`nx show\`, \`nx graph --file\`, reading files) is fine.`,
@@ -41,23 +41,14 @@ const FORMAT_SCOPE = `over exactly the files you created or modified`;
41
41
  // with or without the flag), so the no-files case must be said explicitly.
42
42
  const NO_FILES = `If you created or modified no files, do not run it.`;
43
43
  const NO_NX_FORMAT = `Do not use \`nx format:write\` for this: it also selects files changed earlier on the branch and always reformats the root config files.`;
44
- function renderFormatRule(pmExec, format) {
44
+ // The runbook outlives many steps, so it points at the `Format command:` line
45
+ // each dispensed step resolves.
46
+ function renderFormatRule(pmExec) {
45
47
  // The command is resolved before the step runs, so the step that adds or
46
48
  // replaces the formatter is the one case it cannot cover; name the exact
47
49
  // replacements so the agent does not have to guess flags.
48
50
  const replacement = `If this migration itself added or replaced the workspace formatter, run the new one ${FORMAT_SCOPE} instead: \`${(0, format_command_1.formatCommandFor)('prettier', pmExec)}\` for Prettier, \`${(0, format_command_1.formatCommandFor)('oxfmt', pmExec)}\` for oxfmt, but only if it is installed under node_modules; if it is not, do not install or run it. ${NO_FILES}`;
49
- switch (format.source) {
50
- case 'command':
51
- return format.command === null
52
- ? `- No configured formatter is installed in this workspace; do not install or run one over your changes. ${replacement}`
53
- : `- After applying your changes and before writing the handoff, run \`${format.command}\` ${FORMAT_SCOPE} (the flag keeps the command from failing when some or all of those paths are files the formatter does not handle). ${replacement} ${NO_NX_FORMAT}`;
54
- case 'dispensed-step':
55
- return `- After applying your changes and before writing the handoff, run the command on the dispensed step's \`Format command:\` line ${FORMAT_SCOPE}; when that line says none, do not run a formatter. ${replacement} ${NO_NX_FORMAT}`;
56
- default: {
57
- const unhandled = format;
58
- throw new Error(`Unhandled format instruction: ${JSON.stringify(unhandled)}`);
59
- }
60
- }
51
+ return `- After applying your changes and before writing the handoff, run the command on the dispensed step's \`Format command:\` line ${FORMAT_SCOPE}; when that line says none, do not run a formatter. ${replacement} ${NO_NX_FORMAT}`;
61
52
  }
62
53
  function renderValidationScopeRuleLines() {
63
54
  return [
@@ -1,19 +1,4 @@
1
- import type { FileChange } from '../../../../generators/tree';
2
- export declare function renderFileEntry(change: FileChange): string;
3
1
  export declare function renderListItem(entry: string): string;
4
- export declare function renderKeyMultilineValue(key: string, value: string): string[];
5
- export declare function stripAnsi(text: string): string;
6
2
  export declare function filterNonEmptyStrings(entries: unknown[]): string[];
7
3
  export declare function escapeXmlBody(value: string): string;
8
- export declare function renderGitInspectInstruction(): string;
9
- export declare function renderGeneratorOutputBlock(logs: string): string[];
10
- export interface MigrationBlockContext {
11
- package: string;
12
- name: string;
13
- version: string;
14
- description?: string;
15
- }
16
- export declare function renderMigrationBlock(ctx: MigrationBlockContext): string[];
17
4
  export declare function renderHandoffPathFooter(handoffFileAbsolutePath: string): string[];
18
- export declare function renderAdvisoryContext(note: string, entries: string[]): string[];
19
- export declare function renderMigrationDocumentationBlock(documentationPath: string | undefined): string[];