@intentius/sql-yodeler 0.6.0 → 0.8.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 (92) hide show
  1. package/README.md +7 -7
  2. package/dist/apply-steps/index.d.ts +73 -21
  3. package/dist/apply-steps/index.js +171 -49
  4. package/dist/apply-steps/index.js.map +1 -1
  5. package/dist/approval-mode/index.d.ts +7 -0
  6. package/dist/approval-mode/index.js +10 -3
  7. package/dist/approval-mode/index.js.map +1 -1
  8. package/dist/chant/apply.d.ts +15 -3
  9. package/dist/chant/apply.js +22 -3
  10. package/dist/chant/apply.js.map +1 -1
  11. package/dist/ci/render.d.ts +7 -2
  12. package/dist/ci/render.js +13 -3
  13. package/dist/ci/render.js.map +1 -1
  14. package/dist/commands/apply.d.ts +2 -0
  15. package/dist/commands/apply.js +196 -87
  16. package/dist/commands/apply.js.map +1 -1
  17. package/dist/commands/approve.d.ts +51 -1
  18. package/dist/commands/approve.js +177 -14
  19. package/dist/commands/approve.js.map +1 -1
  20. package/dist/commands/cleanup.d.ts +1 -0
  21. package/dist/commands/cleanup.js +11 -7
  22. package/dist/commands/cleanup.js.map +1 -1
  23. package/dist/commands/create.d.ts +31 -0
  24. package/dist/commands/create.js +171 -0
  25. package/dist/commands/create.js.map +1 -0
  26. package/dist/commands/drift.js +8 -8
  27. package/dist/commands/drift.js.map +1 -1
  28. package/dist/commands/emulator.d.ts +17 -0
  29. package/dist/commands/emulator.js +78 -0
  30. package/dist/commands/emulator.js.map +1 -0
  31. package/dist/commands/index.js +4 -0
  32. package/dist/commands/index.js.map +1 -1
  33. package/dist/commands/init.js +7 -5
  34. package/dist/commands/init.js.map +1 -1
  35. package/dist/commands/override.js +46 -22
  36. package/dist/commands/override.js.map +1 -1
  37. package/dist/commands/plan.js +20 -20
  38. package/dist/commands/plan.js.map +1 -1
  39. package/dist/commands/revert.js +10 -7
  40. package/dist/commands/revert.js.map +1 -1
  41. package/dist/config/define.d.ts +5 -5
  42. package/dist/mcp/tools.d.ts +2 -2
  43. package/dist/mcp/tools.js +7 -5
  44. package/dist/mcp/tools.js.map +1 -1
  45. package/dist/notify/index.d.ts +30 -95
  46. package/dist/notify/index.js +50 -153
  47. package/dist/notify/index.js.map +1 -1
  48. package/dist/notify/verify.d.ts +17 -31
  49. package/dist/notify/verify.js +16 -47
  50. package/dist/notify/verify.js.map +1 -1
  51. package/dist/pr/forge.d.ts +33 -38
  52. package/dist/pr/forge.js +74 -97
  53. package/dist/pr/forge.js.map +1 -1
  54. package/dist/pr/issue.d.ts +16 -33
  55. package/dist/pr/issue.js +17 -88
  56. package/dist/pr/issue.js.map +1 -1
  57. package/dist/pr/model.d.ts +5 -3
  58. package/dist/pr/model.js +12 -6
  59. package/dist/pr/model.js.map +1 -1
  60. package/dist/pr/render.js +7 -6
  61. package/dist/pr/render.js.map +1 -1
  62. package/dist/pr/tenants.js +2 -2
  63. package/dist/pr/tenants.js.map +1 -1
  64. package/dist/release/index.d.ts +63 -0
  65. package/dist/release/index.js +122 -0
  66. package/dist/release/index.js.map +1 -0
  67. package/dist/report/audit.d.ts +18 -19
  68. package/dist/report/audit.js +57 -27
  69. package/dist/report/audit.js.map +1 -1
  70. package/dist/report/model.js +18 -5
  71. package/dist/report/model.js.map +1 -1
  72. package/dist/tenants/wave.d.ts +9 -3
  73. package/dist/tenants/wave.js +4 -5
  74. package/dist/tenants/wave.js.map +1 -1
  75. package/dist/versioned/approval.js +1 -1
  76. package/dist/versioned/approval.js.map +1 -1
  77. package/dist/versioned/policy.d.ts +44 -24
  78. package/dist/versioned/policy.js +70 -37
  79. package/dist/versioned/policy.js.map +1 -1
  80. package/dist/waves/index.d.ts +9 -13
  81. package/dist/waves/index.js +12 -36
  82. package/dist/waves/index.js.map +1 -1
  83. package/package.json +7 -7
  84. package/schemas/apply.schema.json +2 -0
  85. package/schemas/cleanup.schema.json +1 -0
  86. package/schemas/event.schema.json +218 -25
  87. package/schemas/init.schema.json +1 -0
  88. package/schemas/plan.schema.json +3 -1
  89. package/schemas/revert.schema.json +2 -1
  90. package/dist/pr/comment.d.ts +0 -32
  91. package/dist/pr/comment.js +0 -99
  92. package/dist/pr/comment.js.map +0 -1
@@ -4,7 +4,7 @@ import { guarded } from "../env-args.js";
4
4
  import { loadProject, resolveEnvironment, YodelError } from "../project.js";
5
5
  import { buildSchema } from "../chant/build.js";
6
6
  import { declaredChanges, planEnvironment, planExitCode, planJson, renderPlan, unreadableOf, PLAN_NEEDS_OP } from "../chant/plan.js";
7
- import { findApplyOp, GATED, runApplyOp } from "../chant/apply.js";
7
+ import { findApplyOp, GATED, gatedCommands, runApplyOp } from "../chant/apply.js";
8
8
  import { runnable, runnableAsWriter } from "../chant/runnable.js";
9
9
  import { permissionRefusal, readerRefusal } from "../credentials.js";
10
10
  import { migrationSilences } from "../lint/index.js";
@@ -15,13 +15,15 @@ import { newerCommit, STAND_DOWN_ENV, standDownFromEnv, standDownLine } from "..
15
15
  import { describeServer, probeServer } from "../server.js";
16
16
  import { eventFromRun, sendEvent } from "../notify/index.js";
17
17
  import { EXIT_OUTSTANDING, EXIT_REFUSED } from "../exit.js";
18
- import { describeStep, heldSteps, runApplySteps, stepsAtBase, stepsRefusal } from "../apply-steps/index.js";
19
- import { migrationsApprovalAtBase, portFor } from "../approval-mode/index.js";
18
+ import { describeStep, heldSteps, runSqlStep, runStepHooks, sqlStepOfArgv, STEP_SQL_FLAG, stepsAtBase, stepsHooksFile, stepsRefusal } from "../apply-steps/index.js";
19
+ import { approveCommand, migrationsApprovalAtBase, portFor } from "../approval-mode/index.js";
20
+ import { baseEnvironment, tenantTarget } from "../tenants/target.js";
20
21
  import { enforcePromotion, forecastWave, planWave, RECORD_PLANS_ENV, readWavePlan, verifyWaveDecision, WavePlanMoved, WAVES_SPEC_FILE, writeWavePlan } from "../waves/index.js";
21
- import { applySlot, splitSlot, writeSlotPlan } from "../tenants/wave.js";
22
- import { ALLOW_OUT_OF_ORDER_ENV, APPROVED_PLAN_ENV, checksDue, checksRefusal, describeResults, judgePlan, judgeRevert, policyRefusal, runChecks, currentDigest, currentRevert, executeApply, executeRevert, revertFromEnv, findMigrateOp, gitLedger, verifyApproval, hasMigrations, inspect, readChain, recordStepExit, closeVersioned, openVersioned, renderStatus, runMigrateOp, selectToApply, statusJson, statusReport, } from "../versioned/index.js";
22
+ import { applySlot, slotTenants, splitSlot, writeSlotPlan } from "../tenants/wave.js";
23
+ import { ALLOW_OUT_OF_ORDER_ENV, APPROVED_PLAN_ENV, checksDue, checksRefusal, describeResults, judgePlan, judgeRevert, overrideSourceAt, overrideSubject, policyRefusal, spendOverride, runChecks, currentDigest, currentRevert, executeApply, executeRevert, revertFromEnv, findMigrateOp, gitLedger, verifyApproval, hasMigrations, inspect, readChain, recordStepExit, closeVersioned, openVersioned, renderStatus, runMigrateOp, selectToApply, statusJson, statusReport, } from "../versioned/index.js";
23
24
  import { BASELINE_ENV } from "../versioned/op.js";
24
25
  import { baselineFromEnv, executeBaseline, planBaseline, projectBaseline } from "../init/second.js";
26
+ import { appliedHead, recordReleaseLines } from "../release/index.js";
25
27
  /** When the gate's newest approval does not hold: what moved since (or that approval was asked for again), in one line. */
26
28
  async function movedSinceApproval(project, venv, ordered, op, digest) {
27
29
  try {
@@ -55,7 +57,7 @@ export function applyJson(doc) {
55
57
  return { environment: doc.environment, dialect: doc.dialect, ...(doc.server ? { server: doc.server } : {}), op: doc.op, ...doc.outcome };
56
58
  }
57
59
  const usage = "usage: yodel apply <env> [--json] [--dir <project>] [--op <name>] [--allow-out-of-order] [--plan] [--lock-wait <duration>] [--stand-down]";
58
- const waveModes = ["wave-plan", "wave-apply"];
60
+ const waveModes = ["wave-plan", "wave-apply", "step-sql"];
59
61
  const help = `${usage}
60
62
 
61
63
  Two paths, chosen by the project:
@@ -69,10 +71,10 @@ Two paths, chosen by the project:
69
71
  single) as it is sent. Runs the project's migrations Op for the
70
72
  environment (chant run <op>), whose gate is bound to the plan digest: the
71
73
  pending migrations' checksums, the topology, the history and the live
72
- schema. A run that stops at the gate prints the chant approve command;
73
- approve, then run yodel apply again. At a terminal, yodel approve <env>
74
- approves the same plan without the digest to copy: yodel approve <env>,
75
- then yodel apply <env>. If anything the digest covers changes after
74
+ schema. A run that stops at the gate prints the command that approves
75
+ its plan, yodel approve <env> --plan <digest>; a person runs it at a
76
+ terminal, then runs yodel apply again (--json also gives chant's own
77
+ approve command, chantApprove, for scripts). If anything the digest covers changes after
76
78
  approval, the gate asks again.
77
79
 
78
80
  A migration that failed part way resumes at the statement that failed; a
@@ -89,7 +91,8 @@ Two paths, chosen by the project:
89
91
  before the gate and again under the lock: a rule that denies it refuses
90
92
  (exit 4) naming the rule, unless someone policy.overriders lists recorded
91
93
  an override for exactly this plan digest (yodel override <env> --rule <id>
92
- --reason <text>). The history records the overrides a run relied on.
94
+ --reason <text>). An override counts once: the Apply step spends it, and
95
+ the history records the overrides a run relied on.
93
96
 
94
97
  A migration's pre-migration checks (checks in its migration.json, read-only
95
98
  queries) run against the environment: the first pending migration's before
@@ -140,7 +143,7 @@ The migrations Op runs two steps of its own, not for direct use:
140
143
  ${APPROVED_PLAN_ENV} and chant's gate ledger holds an approval
141
144
  of the Op's gate for it (the Op's Apply step)
142
145
 
143
- The apply pipeline's wave jobs (chant run wave, ${WAVES_SPEC_FILE}) run two more:
146
+ The apply pipeline's wave jobs (chant run wave, ${WAVES_SPEC_FILE}) run three more:
144
147
  --wave-plan <file> write the environment's wave plan to <file>: the
145
148
  plan digest, the gate policy at the base commit, and
146
149
  whether a pending step is destructive
@@ -149,6 +152,11 @@ The apply pipeline's wave jobs (chant run wave, ${WAVES_SPEC_FILE}) run two more
149
152
  wave lets it through (an approval of the wave's
150
153
  digest, or a policy at the base commit that needs none)
151
154
  --spec <file> the waves spec (default ${WAVES_SPEC_FILE})
155
+ ${STEP_SQL_FLAG} <sql> run one SQL step (yodel.config.ts environments.<env>.steps)
156
+ against the environment, as the wave's stage hook
157
+ does: with --step <name>, --step-when before|after,
158
+ --step-expect <json> and --step-on-failure approve as
159
+ the step has them. Exit 0 when it passes, 1 when not
152
160
 
153
161
  Exit codes:
154
162
  0 applied, or nothing to apply, or (--stand-down) stood down for a newer
@@ -192,6 +200,11 @@ function parseApplyArgs(args) {
192
200
  "wave-plan": { type: "string" },
193
201
  "wave-apply": { type: "string" },
194
202
  spec: { type: "string" },
203
+ "step-sql": { type: "string" },
204
+ step: { type: "string" },
205
+ "step-when": { type: "string" },
206
+ "step-expect": { type: "string" },
207
+ "step-on-failure": { type: "string" },
195
208
  },
196
209
  });
197
210
  }
@@ -220,6 +233,7 @@ function parseApplyArgs(args) {
220
233
  standDown: flag("stand-down") || standDownFromEnv(process.env),
221
234
  wavePlan: str("wave-plan"),
222
235
  waveApply: str("wave-apply"),
236
+ stepArgv: str("step-sql") !== undefined ? ["yodel", "apply", ...args] : undefined,
223
237
  spec: str("spec") ?? WAVES_SPEC_FILE,
224
238
  };
225
239
  }
@@ -236,7 +250,7 @@ export const apply = {
236
250
  const profile = resolveEnvironment(project, slot?.env ?? a.env).profile;
237
251
  // The reader cannot write (#159): a run that writes refuses before the gate, naming the variable that picks the writer.
238
252
  const command = `yodel apply ${a.env}`;
239
- const writes = !a.plan && !a.digest && a.wavePlan === undefined;
253
+ const writes = !a.plan && !a.digest && a.wavePlan === undefined && a.stepArgv === undefined;
240
254
  const asReader = writes ? readerRefusal(profile, runnable(command, project.dir)) : undefined;
241
255
  if (asReader)
242
256
  throw new YodelError(asReader, EXIT_REFUSED);
@@ -257,6 +271,8 @@ export const apply = {
257
271
  };
258
272
  /** `yodel apply` once the project is loaded and its credentials can write. */
259
273
  async function applyIn(project, a, args, io) {
274
+ if (a.stepArgv !== undefined)
275
+ return stepCheck(project, a.env, a.stepArgv, io);
260
276
  if (splitSlot(a.env))
261
277
  return slotWave(project, a, io);
262
278
  const env = resolveEnvironment(project, a.env);
@@ -273,6 +289,32 @@ async function applyIn(project, a, args, io) {
273
289
  throw refusal;
274
290
  return declarativeApply(project, env, a, io);
275
291
  }
292
+ /**
293
+ * `--step-sql` (#206): one SQL step, as the wave's stage hook runs it, on
294
+ * `target`, or on every tenant of a slot read now. Prints one line per
295
+ * target; exits 0 when it passes everywhere, 1 when not.
296
+ */
297
+ async function stepCheck(project, target, argv, io) {
298
+ const step = sqlStepOfArgv(argv);
299
+ if (!step)
300
+ throw new YodelError(`${STEP_SQL_FLAG} needs --step <name>, the step's name\n${usage}`);
301
+ const slot = splitSlot(target);
302
+ const targets = slot ? (await slotTenants(project, slot)).map((t) => tenantTarget(slot.env, t)) : [target];
303
+ let passed = true;
304
+ for (const t of targets) {
305
+ const venv = await openVersioned(project, resolveEnvironment(project, t));
306
+ try {
307
+ const got = await runSqlStep(venv.driver, step);
308
+ passed &&= got.passed;
309
+ const o = { name: step.name, when: step.when, kind: "sql", passed: got.passed, detail: got.detail, onFailure: step.onFailure ?? "fail" };
310
+ io.err(`${t}: ${!o.passed && o.onFailure === "approve" ? `${o.when} step ${o.name} failed with onFailure approve (${o.detail}), so the wave waits for a person` : describeStep(o)}\n`);
311
+ }
312
+ finally {
313
+ await closeVersioned(venv);
314
+ }
315
+ }
316
+ return passed ? 0 : 1;
317
+ }
276
318
  /**
277
319
  * A slot of a tenant set's wave read at run time (#56), `<env>/@<i>of<n>`:
278
320
  * every tenant the set's query lists now that hashes to the slot, planned
@@ -289,7 +331,7 @@ async function slotWave(project, a, io) {
289
331
  const forecast = forReview ? undefined : await forecastWave(process.cwd(), a.spec, plan);
290
332
  if (forecast?.waits) {
291
333
  const set = splitSlot(a.env)?.env ?? a.env;
292
- log(`${set}: wave ${String(forecast.wave)} waits for an approval of ${forecast.digest} (gate ${forecast.policy} at ${forecast.base.slice(0, 12)}${forecast.approval === "ledger" ? "" : `, approval ${forecast.approval}`}) for every tenant. Approve it with yodel approve ${set}${forecast.approval === "sealed" ? " --sign" : ""}, or: ${forecast.approve}`);
334
+ log(`${set}: wave ${String(forecast.wave)} waits for an approval of ${forecast.digest} (gate ${forecast.policy} at ${forecast.base.slice(0, 12)}${forecast.approval === "ledger" ? "" : `, approval ${forecast.approval}`}) for every tenant. Approve it with ${approveCommand(set, forecast.digest, forecast.approval)}`);
293
335
  }
294
336
  if (a.json)
295
337
  io.out(`${JSON.stringify(plan, null, 2)}\n`);
@@ -345,14 +387,17 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
345
387
  throw new YodelError(`--execute records a baseline only under the plan its Op's gate approved, and ${APPROVED_PLAN_ENV} is not set; run yodel init --baseline ${env.name}`);
346
388
  const op = await findMigrateOp(project, env, a.op);
347
389
  const ledger = await migrationsLedger(project, env.name, io);
390
+ let approver;
348
391
  await executeBaseline(project, env, venv, baseline, {
349
392
  approvedDigest: approved,
350
393
  approve: async (digest) => {
351
394
  const by = await verifyApproval(ledger, op, digest);
395
+ approver = by.resolvedBy;
352
396
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
353
397
  },
354
398
  log: (l) => { io.err(`${l}\n`); },
355
399
  });
400
+ await recordApplied(project, env, venv, ordered, io, approver);
356
401
  io.out(`Recorded: ${baseline.id}, as ${env.name}'s baseline\n`);
357
402
  return 0;
358
403
  }
@@ -368,6 +413,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
368
413
  throw new YodelError(`--execute reverts only the plan its Op's gate approved, and ${APPROVED_PLAN_ENV} is not set; run yodel revert ${env.name} ${revert.id}`);
369
414
  const op = await findMigrateOp(project, env, a.op);
370
415
  const ledger = await migrationsLedger(project, env.name, io);
416
+ let approver;
371
417
  // The policy over the revert (#97), as the base commit has it (#73), as yodel revert judged it before the gate.
372
418
  const { policy: basePolicy, note: policyNote } = await policyAtBase(project);
373
419
  if (policyNote)
@@ -379,12 +425,21 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
379
425
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
380
426
  approve: async (digest) => {
381
427
  const by = await verifyApproval(ledger, op, digest);
428
+ approver = by.resolvedBy;
382
429
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
383
430
  },
384
431
  ...(basePolicy
385
432
  ? {
386
433
  policy: async (digest, planned) => {
387
- const results = await judgeRevert({ policy: basePolicy, environment: env.name, dialect: project.dialect, plan: planned, digest, ledger: () => Promise.resolve({ port: ledger, op }) });
434
+ const results = await judgeRevert({
435
+ policy: basePolicy,
436
+ environment: env.name,
437
+ dialect: project.dialect,
438
+ plan: planned,
439
+ digest,
440
+ ledger: async () => overrideSourceAt(project.dir, overrideSubject(op.name, revert.id), await migrationsApprovalAtBase(project, env.name)),
441
+ spend: (o) => spendOverride(project.dir, o, (l) => { io.err(`${l}\n`); }),
442
+ });
388
443
  const refusal = policyRefusal(results, env.name, digest, "under the lock", { id: revert.id, step: revert.step?.file });
389
444
  if (refusal)
390
445
  throw refusal;
@@ -396,6 +451,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
396
451
  : {}),
397
452
  log: (l) => { io.err(`${l}\n`); },
398
453
  });
454
+ await recordApplied(project, env, venv, ordered, io, approver);
399
455
  io.out(`Reverted: ${plan.migration.id}, back to ${plan.to ?? "an empty schema"}\n`);
400
456
  return 0;
401
457
  }
@@ -411,21 +467,25 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
411
467
  const plan = await writeWavePlan(project, venv, ordered, a.wavePlan, { allowOutOfOrder: a.allowOutOfOrder, forReview });
412
468
  io.err(`${env.name}: ${plan.empty ? "nothing to apply" : `${String(plan.pending.length)} pending (${plan.pending.join(", ")})`}; gate ${plan.gate} at ${plan.base.slice(0, 12)}` +
413
469
  `${plan.destructive ? `; destructive: ${plan.destructiveSteps.map((d) => `${d.migration} step ${String(d.step)} (${d.why})`).join(", ")}` : ""}; plan ${plan.planDigest}\n`);
414
- // The before steps (#64): the SQL checks as they ran, and each command as one that will run under the lock (#107).
415
- for (const o of plan.steps ?? [])
416
- io.err(`${describeStep(o)}\n`);
470
+ // The before steps (#64): chant ran the SQL checks as the wave's before-plan hooks (#206); each command runs under the lock only (#107).
471
+ if (!plan.empty && !forReview) {
472
+ for (const s of (await stepsAtBase(project, env.name)).steps?.before ?? []) {
473
+ if (s.command !== undefined)
474
+ io.err(`${describeStep({ name: s.name, when: "before", kind: "command", passed: true, detail: "a command: it runs under the lock, not when the wave is planned", onFailure: s.onFailure ?? "fail", deferred: true })}\n`);
475
+ }
476
+ }
417
477
  // chant decides the wave right after this; tell the webhook now when it will wait (#87), since chant sends nothing.
418
478
  // Recorded for a review (#48), nothing waits now: the wave is decided after the merge.
419
479
  const forecast = forReview ? undefined : await forecastWave(process.cwd(), a.spec, plan);
420
480
  if (forecast?.waits) {
421
481
  // A tenant set's wave (#56) is approved once for every tenant.
422
- const sign = forecast.approval === "sealed" ? " --sign" : "";
423
- const how = env.tenant ? `for every tenant of ${env.tenant.env}. Approve it with yodel approve ${env.tenant.env}${sign}, or: ` : `. Approve it with yodel approve ${env.name}${sign}, or: `;
482
+ const approve = approveCommand(baseEnvironment(env.name), forecast.digest, forecast.approval);
483
+ const how = env.tenant ? `for every tenant of ${env.tenant.env}. Approve it with ` : `. Approve it with `;
424
484
  const mode = forecast.approval === "ledger" ? "" : `, approval ${forecast.approval}`;
425
- io.err(`${env.name}: wave ${String(forecast.wave)} waits for an approval of ${forecast.digest} (gate ${forecast.policy} at ${forecast.base.slice(0, 12)}${mode})${how}${forecast.approve}\n`);
485
+ io.err(`${env.name}: wave ${String(forecast.wave)} waits for an approval of ${forecast.digest} (gate ${forecast.policy} at ${forecast.base.slice(0, 12)}${mode})${how}${approve}\n`);
426
486
  if (forecast.approval === "pr-review")
427
487
  io.err(`${env.name}: under pr-review, an approving review of the merged pull request's head by a writer other than its author approves it too, when that head's pipeline recorded this plan (chant run wave --record-plans).\n`);
428
- outcome.doc = { environment: env.name, status: "gated", pending: plan.pending.map((id) => ({ id })), gatePlanDigest: forecast.digest, approve: forecast.approve };
488
+ outcome.doc = { environment: env.name, status: "gated", pending: plan.pending.map((id) => ({ id })), gatePlanDigest: forecast.digest, approve, chantApprove: forecast.chantApprove };
429
489
  }
430
490
  if (a.json)
431
491
  io.out(`${JSON.stringify(applyJson({ mode: "wave-plan", plan }), null, 2)}\n`);
@@ -441,12 +501,17 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
441
501
  const cwd = process.cwd();
442
502
  let wave;
443
503
  let before = [];
444
- const steps = await stepsAtBase(project, env.name);
445
- if (steps.note)
504
+ // The steps (#64) are the wave's stage hooks, which chant hands this run in CHANT_HOOKS (#206); run by hand, they are the steps at base.
505
+ const { readOpWaveHooksFile } = await import("@intentius/chant/op");
506
+ const handed = readOpWaveHooksFile(undefined, cwd);
507
+ const steps = handed ? undefined : await stepsAtBase(project, env.name);
508
+ if (steps?.note)
446
509
  io.err(`${steps.note}\n`);
510
+ let hooksFile = handed ?? undefined;
511
+ const hooks = applyHooks(project, venv, env, () => (hooksFile ??= stepsHooksFile(steps?.steps, env.name, { approved: wave?.status === "approved", ...(steps?.sha ? { base: steps.sha } : {}) })), io);
447
512
  const result = await executeApply(venv, ordered, {
448
513
  runNote: () => (wave || before.length > 0 ? { ...(wave ? { wave } : {}), ...(before.length > 0 ? { steps: before } : {}) } : undefined),
449
- ...afterSteps(project, venv, env, steps.steps?.after, io),
514
+ ...hooks.after,
450
515
  approvedDigest: planned.migrations,
451
516
  allowOutOfOrder: a.allowOutOfOrder,
452
517
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
@@ -456,13 +521,15 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
456
521
  policy: async (digest, toApply) => {
457
522
  const ledger = async () => {
458
523
  try {
459
- return { port: await gitLedger(project.dir), op: await findMigrateOp(project, env, a.op) };
524
+ const op = await findMigrateOp(project, env, a.op);
525
+ return await overrideSourceAt(project.dir, overrideSubject(op.name), await migrationsApprovalAtBase(project, env.name));
460
526
  }
461
527
  catch {
462
528
  return undefined;
463
529
  }
464
530
  };
465
- const results = await judgePlan({ policy: basePolicy, environment: env.name, dialect: project.dialect, toApply, digest, ledger });
531
+ const spend = (o) => spendOverride(project.dir, o, (l) => { io.err(`${l}\n`); });
532
+ const results = await judgePlan({ policy: basePolicy, environment: env.name, dialect: project.dialect, toApply, digest, ledger, spend });
466
533
  const refusal = policyRefusal(results, env.name, digest, "under the lock");
467
534
  if (refusal)
468
535
  throw refusal;
@@ -478,22 +545,20 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
478
545
  if (now.planDigest !== planned.planDigest) {
479
546
  throw new WavePlanMoved(`refused: ${env.name}'s wave plan moved since the wave was decided (decided ${planned.planDigest}, now ${now.planDigest}); nothing was applied. Run the wave again.`);
480
547
  }
481
- // The before steps' SQL checks (#64) ran again in that plan, under the lock; a held one needs a person's approval whatever the gate.
482
- const checked = (now.steps ?? []).filter((o) => !o.deferred);
483
- for (const o of checked)
484
- io.err(`${describeStep(o)}\n`);
485
- let verified = await verifyWaveDecision(cwd, a.spec, a.decidedAs?.target ?? env.name, a.decidedAs?.planDigest ?? planned.planDigest, now.held ?? []);
486
- // The commands (#107) run once, here, once the wave may apply: one that fails refuses; a held one needs the approval too.
487
- const commands = await runBeforeSteps(project, venv, env, steps.steps?.before?.filter((s) => s.sql === undefined), "under the lock", io);
488
- before = [...checked, ...commands];
489
- if (heldSteps(commands).length > 0 && verified.wave.status !== "approved")
490
- verified = await verifyWaveDecision(cwd, a.spec, a.decidedAs?.target ?? env.name, a.decidedAs?.planDigest ?? planned.planDigest, [...(now.held ?? []), ...heldSteps(commands)]);
548
+ const verified = await verifyWaveDecision(cwd, a.spec, a.decidedAs?.target ?? env.name, a.decidedAs?.planDigest ?? planned.planDigest);
491
549
  wave = verified.wave;
492
550
  io.err(`${verified.line}\n`);
551
+ // The before steps (#64), under the lock, through chant's runner: one that fails refuses (exit 4); a held one with no approval standing stops here (exit 3), and chant waits for, or finds, the approval and runs this again.
552
+ // A command (#107) runs here only, once per apply.
553
+ before = await hooks.before();
493
554
  },
494
555
  log: (l) => { io.err(`${l}\n`); },
495
556
  silences: migrationSilences,
496
557
  });
558
+ // An apply that changed nothing ran no step, and tells chant so: a step command runs once per apply that changes the schema, not once per push (#206).
559
+ await hooks.skipped(result.stoodDown ?? "nothing to apply");
560
+ if (result.applied.length > 0)
561
+ await recordApplied(project, env, venv, ordered, io, wave?.review?.approvers.join(", "));
497
562
  if (a.json)
498
563
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: planned.migrations, wavePlanDigest: planned.planDigest, result }), null, 2)}\n`);
499
564
  else
@@ -514,9 +579,13 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
514
579
  if (steps.note)
515
580
  io.err(`${steps.note}\n`);
516
581
  let before = [];
582
+ let approver;
583
+ // The steps (#64) as stage hooks (#206), read at base; the Op's approval, checked under the lock before they run, lets a held one through.
584
+ const hooksFile = stepsHooksFile(steps.steps, env.name, { approved: true, ...(steps.sha ? { base: steps.sha } : {}) });
585
+ const hooks = applyHooks(project, venv, env, () => hooksFile, io);
517
586
  const result = await executeApply(venv, ordered, {
518
587
  runNote: () => (before.length > 0 ? { steps: before } : undefined),
519
- ...afterSteps(project, venv, env, steps.steps?.after, io),
588
+ ...hooks.after,
520
589
  approvedDigest: approved,
521
590
  allowOutOfOrder: a.allowOutOfOrder,
522
591
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
@@ -525,16 +594,25 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
525
594
  // Under the lock: every pending migration ran first where this environment requires (exit 4 otherwise).
526
595
  await enforcePromotion(project, env.name, ordered, (await inspect(venv, ordered)).status.pending);
527
596
  const by = await verifyApproval(ledger, op, digest);
597
+ approver = by.resolvedBy;
528
598
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}${by.signer !== undefined ? `, sealed by ${by.signer}` : ""}\n`);
529
599
  // The before steps (#64), under the lock: one that fails refuses; a held one is let through by the Op's approval, which every run of it asks for.
530
- before = await runBeforeSteps(project, venv, env, steps.steps?.before, "under the lock", io);
600
+ before = await hooks.before();
531
601
  },
532
602
  log: (l) => { io.err(`${l}\n`); },
533
603
  silences: migrationSilences,
534
604
  ...(basePolicy
535
605
  ? {
536
606
  policy: async (digest, toApply) => {
537
- const results = await judgePlan({ policy: basePolicy, environment: env.name, dialect: project.dialect, toApply, digest, ledger: () => Promise.resolve({ port: ledger, op }) });
607
+ const results = await judgePlan({
608
+ policy: basePolicy,
609
+ environment: env.name,
610
+ dialect: project.dialect,
611
+ toApply,
612
+ digest,
613
+ ledger: async () => overrideSourceAt(project.dir, overrideSubject(op.name), await migrationsApprovalAtBase(project, env.name)),
614
+ spend: (o) => spendOverride(project.dir, o, (l) => { io.err(`${l}\n`); }),
615
+ });
538
616
  const refusal = policyRefusal(results, env.name, digest, "under the lock");
539
617
  if (refusal)
540
618
  throw refusal;
@@ -545,6 +623,8 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
545
623
  }
546
624
  : {}),
547
625
  });
626
+ if (result.applied.length > 0)
627
+ await recordApplied(project, env, venv, ordered, io, approver);
548
628
  if (a.json)
549
629
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: approved, result }), null, 2)}\n`);
550
630
  else
@@ -609,17 +689,25 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
609
689
  const steps = await stepsAtBase(project, env.name);
610
690
  if (steps.note && !a.json)
611
691
  io.err(`${steps.note}\n`);
612
- try {
613
- const outcomes = await runBeforeSteps(project, venv, env, steps.steps?.before, "before the gate", a.json ? undefined : io, "plan");
614
- if (!a.json && heldSteps(outcomes).length > 0)
615
- io.out(`before step ${heldSteps(outcomes).join(", ")} failed with onFailure approve: approving this plan lets it through\n`);
616
- }
617
- catch (e) {
618
- if (!(e instanceof YodelError) || e.exitCode !== EXIT_REFUSED)
619
- throw e;
620
- if (!a.json)
621
- io.err(`yodel apply: ${e.message}\n`);
622
- return emit({ status: "refused", refusal: { exitCode: EXIT_REFUSED, message: e.message } }, EXIT_REFUSED);
692
+ {
693
+ // The SQL checks are the before-plan hooks (#206). The gate asks for an approval on every run, so a held one goes on to it.
694
+ const planned = await runStepHooks(stepsHooksFile(steps.steps, env.name, { approved: true }), "before-plan", { driver: venv.driver, dir: project.dir, env: env.name });
695
+ if (!a.json) {
696
+ for (const o of planned.outcomes)
697
+ io.err(`${describeStep(o)}\n`);
698
+ for (const s of steps.steps?.before ?? []) {
699
+ if (s.command !== undefined)
700
+ io.err(`${describeStep({ name: s.name, when: "before", kind: "command", passed: true, detail: "a command: it runs under the lock, not when the run is planned", onFailure: s.onFailure ?? "fail", deferred: true })}\n`);
701
+ }
702
+ }
703
+ const refusal = stepsRefusal(env.name, planned, "before the gate");
704
+ if (refusal) {
705
+ if (!a.json)
706
+ io.err(`yodel apply: ${refusal.message}\n`);
707
+ return emit({ status: "refused", refusal: { exitCode: refusal.exitCode, message: refusal.message } }, refusal.exitCode);
708
+ }
709
+ if (!a.json && heldSteps(planned.outcomes).length > 0)
710
+ io.out(`before step ${heldSteps(planned.outcomes).join(", ")} failed with onFailure approve: approving this plan lets it through\n`);
623
711
  }
624
712
  const op = await findMigrateOp(project, env, a.op);
625
713
  // The policy (#53), as the base commit has it (#73): a rule that denies this plan, with no override recorded for its digest, refuses before the gate.
@@ -632,7 +720,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
632
720
  dialect: project.dialect,
633
721
  toApply: report.status.pending,
634
722
  digest: report.digest,
635
- ledger: async () => ({ port: await gitLedger(project.dir), op }),
723
+ ledger: async () => overrideSourceAt(project.dir, overrideSubject(op.name), await migrationsApprovalAtBase(project, env.name)),
636
724
  });
637
725
  const denied = policyRefusal(policy, env.name, report.digest, "before the gate");
638
726
  if (denied) {
@@ -663,16 +751,14 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
663
751
  io.out(`\n${stale.line}\n`);
664
752
  if (!a.json) {
665
753
  io.out(`\n${op.name} is waiting at gate "${op.gate}" for approval of this plan${run.planDigest ? ` (${run.planDigest})` : ""}.\n`);
666
- if (run.approve) {
667
- // A sealed gate (#48) counts only a sealed approval, which --execute checks.
668
- const sealed = (await migrationsApprovalAtBase(project, env.name)).mode === "sealed";
669
- const approve = sealed && !/ --sign\b/.test(run.approve) ? `${run.approve} --sign` : run.approve;
670
- io.out(`Approve it with:\n ${runnable(approve, project.dir)}\n` +
671
- `or, at a terminal, with ${runnable(`yodel approve ${env.name}${sealed ? " --sign" : ""}`, project.dir)}, which shows the plan and asks you first;\n` +
672
- `then run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
673
- }
674
754
  }
675
- return emit({ status: "gated", op: op.name, gate: op.gate, ...(stale ? { moved: stale.moved } : {}), ...(run.approve ? { approve: run.approve } : {}), ...(run.planDigest ? { gatePlanDigest: run.planDigest } : {}) }, GATED);
755
+ // A sealed gate (#48) counts only a sealed approval, which --execute checks.
756
+ const commands = gatedCommands(run, env.name, (await migrationsApprovalAtBase(project, env.name)).mode);
757
+ if (!a.json && commands.approve) {
758
+ io.out(`Approve it at a terminal with:\n ${runnable(commands.approve, project.dir)}\n` +
759
+ `which shows the plan and asks you first; then run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
760
+ }
761
+ return emit({ status: "gated", op: op.name, gate: op.gate, ...(stale ? { moved: stale.moved } : {}), ...commands, ...(run.planDigest ? { gatePlanDigest: run.planDigest } : {}) }, GATED);
676
762
  }
677
763
  const after = await statusReport(venv, ordered, { allowOutOfOrder: a.allowOutOfOrder });
678
764
  if (run.status === "failed") {
@@ -745,12 +831,13 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
745
831
  io.out(`\nRunning ${op.name} (${op.filePath})\n`);
746
832
  const run = await runApplyOp(project, op, { onOutput: (t) => { io.err(t); } });
747
833
  if (run.status === "gated") {
834
+ const commands = gatedCommands(run, env.name);
748
835
  if (!json) {
749
- io.out(`\n${op.name} is waiting at gate "${op.gate}" for approval of this plan.\n`);
750
- if (run.approve)
751
- io.out(`Approve it with:\n ${runnable(run.approve, project.dir)}\nthen run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
836
+ io.out(`\n${op.name} is waiting at gate "${op.gate}" for approval of this plan${run.planDigest ? ` (${run.planDigest})` : ""}.\n`);
837
+ if (commands.approve)
838
+ io.out(`Approve it at a terminal with:\n ${runnable(commands.approve, project.dir)}\nwhich shows the plan and asks you first; then run ${runnableAsWriter(`yodel apply ${env.name}`, project.dir, env.profile)} again.\n`);
752
839
  }
753
- return report({ status: "gated", gate: op.gate, ...(run.approve ? { approve: run.approve } : {}), ...(run.planDigest ? { planDigest: run.planDigest } : {}), plan: planJson(before) }, GATED);
840
+ return report({ status: "gated", gate: op.gate, ...commands, ...(run.planDigest ? { planDigest: run.planDigest } : {}), plan: planJson(before) }, GATED);
754
841
  }
755
842
  if (run.status === "failed") {
756
843
  if (!json)
@@ -765,6 +852,8 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
765
852
  io.err(`yodel apply: ${op.name} completed but ${String(remaining.length)} change(s) to declared objects are still planned (a drop the Op's delete mode withholds, or a change it did not attempt):\n${await renderPlan(after, `Plan for ${env.name} after apply`)}\n`);
766
853
  return report({ status: "incomplete", plan: planJson(before), remaining: planJson(after) }, 1);
767
854
  }
855
+ for (const line of await recordReleaseLines(project, env, build.output))
856
+ io.err(`${line}\n`);
768
857
  if (!json)
769
858
  io.out(`\nApplied: ${env.name} matches the declared schema.\n`);
770
859
  return report({ status: "applied", plan: planJson(before) }, 0);
@@ -773,6 +862,13 @@ async function declarativeRun(project, env, a, io, op, report, setServer) {
773
862
  build.dispose();
774
863
  }
775
864
  }
865
+ /** Records the schema `env` holds now on chant's release ledger (#208), told on stderr. */
866
+ async function recordApplied(project, env, venv, ordered, io, approver) {
867
+ const { status } = await inspect(venv, ordered);
868
+ const lines = await recordReleaseLines(project, env, appliedHead(ordered, status)?.document.schema, approver ? { approver } : {});
869
+ for (const line of lines)
870
+ io.err(`${line}\n`);
871
+ }
776
872
  /** `--stand-down`'s question: the line to stand down with, when a newer commit on the run's branch will apply `env`. */
777
873
  function standingDown(project, env) {
778
874
  return async () => {
@@ -780,29 +876,42 @@ function standingDown(project, env) {
780
876
  return n ? standDownLine(env.name, n) : undefined;
781
877
  };
782
878
  }
783
- /** Runs `env`'s before steps (#64); throws the refusal for one that fails with onFailure fail. */
784
- async function runBeforeSteps(project, venv, env, list, when, io, commands = "run") {
785
- if (!list || list.length === 0)
786
- return [];
787
- const outcomes = await runApplySteps(venv.driver, list, "before", { dir: project.dir, env: env.name, commands });
788
- for (const o of outcomes)
789
- io?.err(`${describeStep(o)}\n`);
790
- const refusal = stepsRefusal(env.name, outcomes, when);
791
- if (refusal)
792
- throw refusal;
793
- return outcomes;
794
- }
795
- /** executeApply's `after` (#64), when `env` has after steps. */
796
- function afterSteps(project, venv, env, list, io) {
797
- if (!list || list.length === 0)
798
- return {};
879
+ /**
880
+ * The steps around one apply (#64) as chant's apply-stage hooks (#206):
881
+ * `before` runs the before-apply hooks under the lock and throws the
882
+ * refusal when they do not let the apply go on; `after` is executeApply's
883
+ * `after`; `skipped` tells chant, for an apply that changed nothing, that
884
+ * the hooks it handed did not run, and why.
885
+ */
886
+ function applyHooks(project, venv, env, file, io) {
887
+ const ran = new Set();
888
+ const ctx = { driver: venv.driver, dir: project.dir, env: env.name, log: (l) => { io.err(`${l}\n`); } };
889
+ const run = async (moment) => {
890
+ ran.add(moment);
891
+ const got = await runStepHooks(file(), moment, ctx);
892
+ for (const o of got.outcomes)
893
+ io.err(`${describeStep(o)}\n`);
894
+ return { got, refusal: stepsRefusal(env.name, got, "under the lock") };
895
+ };
799
896
  return {
800
- after: async () => {
801
- const outcomes = await runApplySteps(venv.driver, list, "after", { dir: project.dir, env: env.name });
802
- for (const o of outcomes)
803
- io.err(`${describeStep(o)}\n`);
804
- const error = stepsRefusal(env.name, outcomes, "under the lock");
805
- return { note: { steps: outcomes }, ...(error ? { error } : {}) };
897
+ before: async () => {
898
+ const { got, refusal } = await run("before-apply");
899
+ if (refusal)
900
+ throw refusal;
901
+ return got.outcomes;
902
+ },
903
+ after: {
904
+ after: async () => {
905
+ const { got, refusal } = await run("after-apply");
906
+ return { note: { steps: got.outcomes }, ...(refusal ? { error: refusal } : {}) };
907
+ },
908
+ },
909
+ skipped: async (why) => {
910
+ const f = file();
911
+ for (const moment of ["before-apply", "after-apply"]) {
912
+ if (!ran.has(moment) && f.result && (f.hooks[moment]?.length ?? 0) > 0)
913
+ await runStepHooks(f, moment, { ...ctx, skip: why });
914
+ }
806
915
  },
807
916
  };
808
917
  }