@intentius/sql-yodeler 0.7.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 (58) hide show
  1. package/dist/apply-steps/index.d.ts +73 -21
  2. package/dist/apply-steps/index.js +171 -49
  3. package/dist/apply-steps/index.js.map +1 -1
  4. package/dist/ci/render.d.ts +7 -2
  5. package/dist/ci/render.js +12 -2
  6. package/dist/ci/render.js.map +1 -1
  7. package/dist/commands/apply.js +173 -64
  8. package/dist/commands/apply.js.map +1 -1
  9. package/dist/commands/drift.js +8 -8
  10. package/dist/commands/drift.js.map +1 -1
  11. package/dist/commands/override.js +46 -22
  12. package/dist/commands/override.js.map +1 -1
  13. package/dist/commands/plan.js +19 -19
  14. package/dist/commands/plan.js.map +1 -1
  15. package/dist/commands/revert.js +3 -2
  16. package/dist/commands/revert.js.map +1 -1
  17. package/dist/config/define.d.ts +5 -5
  18. package/dist/mcp/tools.d.ts +1 -1
  19. package/dist/mcp/tools.js +6 -4
  20. package/dist/mcp/tools.js.map +1 -1
  21. package/dist/notify/index.d.ts +30 -97
  22. package/dist/notify/index.js +50 -154
  23. package/dist/notify/index.js.map +1 -1
  24. package/dist/notify/verify.d.ts +17 -31
  25. package/dist/notify/verify.js +16 -47
  26. package/dist/notify/verify.js.map +1 -1
  27. package/dist/pr/forge.d.ts +33 -38
  28. package/dist/pr/forge.js +74 -97
  29. package/dist/pr/forge.js.map +1 -1
  30. package/dist/pr/issue.d.ts +16 -33
  31. package/dist/pr/issue.js +17 -88
  32. package/dist/pr/issue.js.map +1 -1
  33. package/dist/pr/model.js +7 -2
  34. package/dist/pr/model.js.map +1 -1
  35. package/dist/pr/render.js +2 -2
  36. package/dist/pr/render.js.map +1 -1
  37. package/dist/release/index.d.ts +63 -0
  38. package/dist/release/index.js +122 -0
  39. package/dist/release/index.js.map +1 -0
  40. package/dist/report/audit.d.ts +18 -19
  41. package/dist/report/audit.js +57 -27
  42. package/dist/report/audit.js.map +1 -1
  43. package/dist/report/model.js +18 -5
  44. package/dist/report/model.js.map +1 -1
  45. package/dist/tenants/wave.d.ts +6 -2
  46. package/dist/tenants/wave.js +1 -3
  47. package/dist/tenants/wave.js.map +1 -1
  48. package/dist/versioned/policy.d.ts +44 -24
  49. package/dist/versioned/policy.js +70 -37
  50. package/dist/versioned/policy.js.map +1 -1
  51. package/dist/waves/index.d.ts +4 -10
  52. package/dist/waves/index.js +8 -33
  53. package/dist/waves/index.js.map +1 -1
  54. package/package.json +7 -7
  55. package/schemas/event.schema.json +218 -26
  56. package/dist/pr/comment.d.ts +0 -32
  57. package/dist/pr/comment.js +0 -99
  58. package/dist/pr/comment.js.map +0 -1
@@ -15,14 +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";
18
+ import { describeStep, heldSteps, runSqlStep, runStepHooks, sqlStepOfArgv, STEP_SQL_FLAG, stepsAtBase, stepsHooksFile, stepsRefusal } from "../apply-steps/index.js";
19
19
  import { approveCommand, migrationsApprovalAtBase, portFor } from "../approval-mode/index.js";
20
- import { baseEnvironment } from "../tenants/target.js";
20
+ import { baseEnvironment, tenantTarget } from "../tenants/target.js";
21
21
  import { enforcePromotion, forecastWave, planWave, RECORD_PLANS_ENV, readWavePlan, verifyWaveDecision, WavePlanMoved, WAVES_SPEC_FILE, writeWavePlan } from "../waves/index.js";
22
- import { applySlot, splitSlot, writeSlotPlan } from "../tenants/wave.js";
23
- 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";
24
24
  import { BASELINE_ENV } from "../versioned/op.js";
25
25
  import { baselineFromEnv, executeBaseline, planBaseline, projectBaseline } from "../init/second.js";
26
+ import { appliedHead, recordReleaseLines } from "../release/index.js";
26
27
  /** When the gate's newest approval does not hold: what moved since (or that approval was asked for again), in one line. */
27
28
  async function movedSinceApproval(project, venv, ordered, op, digest) {
28
29
  try {
@@ -56,7 +57,7 @@ export function applyJson(doc) {
56
57
  return { environment: doc.environment, dialect: doc.dialect, ...(doc.server ? { server: doc.server } : {}), op: doc.op, ...doc.outcome };
57
58
  }
58
59
  const usage = "usage: yodel apply <env> [--json] [--dir <project>] [--op <name>] [--allow-out-of-order] [--plan] [--lock-wait <duration>] [--stand-down]";
59
- const waveModes = ["wave-plan", "wave-apply"];
60
+ const waveModes = ["wave-plan", "wave-apply", "step-sql"];
60
61
  const help = `${usage}
61
62
 
62
63
  Two paths, chosen by the project:
@@ -90,7 +91,8 @@ Two paths, chosen by the project:
90
91
  before the gate and again under the lock: a rule that denies it refuses
91
92
  (exit 4) naming the rule, unless someone policy.overriders lists recorded
92
93
  an override for exactly this plan digest (yodel override <env> --rule <id>
93
- --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.
94
96
 
95
97
  A migration's pre-migration checks (checks in its migration.json, read-only
96
98
  queries) run against the environment: the first pending migration's before
@@ -141,7 +143,7 @@ The migrations Op runs two steps of its own, not for direct use:
141
143
  ${APPROVED_PLAN_ENV} and chant's gate ledger holds an approval
142
144
  of the Op's gate for it (the Op's Apply step)
143
145
 
144
- 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:
145
147
  --wave-plan <file> write the environment's wave plan to <file>: the
146
148
  plan digest, the gate policy at the base commit, and
147
149
  whether a pending step is destructive
@@ -150,6 +152,11 @@ The apply pipeline's wave jobs (chant run wave, ${WAVES_SPEC_FILE}) run two more
150
152
  wave lets it through (an approval of the wave's
151
153
  digest, or a policy at the base commit that needs none)
152
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
153
160
 
154
161
  Exit codes:
155
162
  0 applied, or nothing to apply, or (--stand-down) stood down for a newer
@@ -193,6 +200,11 @@ function parseApplyArgs(args) {
193
200
  "wave-plan": { type: "string" },
194
201
  "wave-apply": { type: "string" },
195
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" },
196
208
  },
197
209
  });
198
210
  }
@@ -221,6 +233,7 @@ function parseApplyArgs(args) {
221
233
  standDown: flag("stand-down") || standDownFromEnv(process.env),
222
234
  wavePlan: str("wave-plan"),
223
235
  waveApply: str("wave-apply"),
236
+ stepArgv: str("step-sql") !== undefined ? ["yodel", "apply", ...args] : undefined,
224
237
  spec: str("spec") ?? WAVES_SPEC_FILE,
225
238
  };
226
239
  }
@@ -237,7 +250,7 @@ export const apply = {
237
250
  const profile = resolveEnvironment(project, slot?.env ?? a.env).profile;
238
251
  // The reader cannot write (#159): a run that writes refuses before the gate, naming the variable that picks the writer.
239
252
  const command = `yodel apply ${a.env}`;
240
- const writes = !a.plan && !a.digest && a.wavePlan === undefined;
253
+ const writes = !a.plan && !a.digest && a.wavePlan === undefined && a.stepArgv === undefined;
241
254
  const asReader = writes ? readerRefusal(profile, runnable(command, project.dir)) : undefined;
242
255
  if (asReader)
243
256
  throw new YodelError(asReader, EXIT_REFUSED);
@@ -258,6 +271,8 @@ export const apply = {
258
271
  };
259
272
  /** `yodel apply` once the project is loaded and its credentials can write. */
260
273
  async function applyIn(project, a, args, io) {
274
+ if (a.stepArgv !== undefined)
275
+ return stepCheck(project, a.env, a.stepArgv, io);
261
276
  if (splitSlot(a.env))
262
277
  return slotWave(project, a, io);
263
278
  const env = resolveEnvironment(project, a.env);
@@ -274,6 +289,32 @@ async function applyIn(project, a, args, io) {
274
289
  throw refusal;
275
290
  return declarativeApply(project, env, a, io);
276
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
+ }
277
318
  /**
278
319
  * A slot of a tenant set's wave read at run time (#56), `<env>/@<i>of<n>`:
279
320
  * every tenant the set's query lists now that hashes to the slot, planned
@@ -346,14 +387,17 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
346
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}`);
347
388
  const op = await findMigrateOp(project, env, a.op);
348
389
  const ledger = await migrationsLedger(project, env.name, io);
390
+ let approver;
349
391
  await executeBaseline(project, env, venv, baseline, {
350
392
  approvedDigest: approved,
351
393
  approve: async (digest) => {
352
394
  const by = await verifyApproval(ledger, op, digest);
395
+ approver = by.resolvedBy;
353
396
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
354
397
  },
355
398
  log: (l) => { io.err(`${l}\n`); },
356
399
  });
400
+ await recordApplied(project, env, venv, ordered, io, approver);
357
401
  io.out(`Recorded: ${baseline.id}, as ${env.name}'s baseline\n`);
358
402
  return 0;
359
403
  }
@@ -369,6 +413,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
369
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}`);
370
414
  const op = await findMigrateOp(project, env, a.op);
371
415
  const ledger = await migrationsLedger(project, env.name, io);
416
+ let approver;
372
417
  // The policy over the revert (#97), as the base commit has it (#73), as yodel revert judged it before the gate.
373
418
  const { policy: basePolicy, note: policyNote } = await policyAtBase(project);
374
419
  if (policyNote)
@@ -380,12 +425,21 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
380
425
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
381
426
  approve: async (digest) => {
382
427
  const by = await verifyApproval(ledger, op, digest);
428
+ approver = by.resolvedBy;
383
429
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}\n`);
384
430
  },
385
431
  ...(basePolicy
386
432
  ? {
387
433
  policy: async (digest, planned) => {
388
- 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
+ });
389
443
  const refusal = policyRefusal(results, env.name, digest, "under the lock", { id: revert.id, step: revert.step?.file });
390
444
  if (refusal)
391
445
  throw refusal;
@@ -397,6 +451,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
397
451
  : {}),
398
452
  log: (l) => { io.err(`${l}\n`); },
399
453
  });
454
+ await recordApplied(project, env, venv, ordered, io, approver);
400
455
  io.out(`Reverted: ${plan.migration.id}, back to ${plan.to ?? "an empty schema"}\n`);
401
456
  return 0;
402
457
  }
@@ -412,9 +467,13 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
412
467
  const plan = await writeWavePlan(project, venv, ordered, a.wavePlan, { allowOutOfOrder: a.allowOutOfOrder, forReview });
413
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)}` +
414
469
  `${plan.destructive ? `; destructive: ${plan.destructiveSteps.map((d) => `${d.migration} step ${String(d.step)} (${d.why})`).join(", ")}` : ""}; plan ${plan.planDigest}\n`);
415
- // The before steps (#64): the SQL checks as they ran, and each command as one that will run under the lock (#107).
416
- for (const o of plan.steps ?? [])
417
- 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
+ }
418
477
  // chant decides the wave right after this; tell the webhook now when it will wait (#87), since chant sends nothing.
419
478
  // Recorded for a review (#48), nothing waits now: the wave is decided after the merge.
420
479
  const forecast = forReview ? undefined : await forecastWave(process.cwd(), a.spec, plan);
@@ -442,12 +501,17 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
442
501
  const cwd = process.cwd();
443
502
  let wave;
444
503
  let before = [];
445
- const steps = await stepsAtBase(project, env.name);
446
- 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)
447
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);
448
512
  const result = await executeApply(venv, ordered, {
449
513
  runNote: () => (wave || before.length > 0 ? { ...(wave ? { wave } : {}), ...(before.length > 0 ? { steps: before } : {}) } : undefined),
450
- ...afterSteps(project, venv, env, steps.steps?.after, io),
514
+ ...hooks.after,
451
515
  approvedDigest: planned.migrations,
452
516
  allowOutOfOrder: a.allowOutOfOrder,
453
517
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
@@ -457,13 +521,15 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
457
521
  policy: async (digest, toApply) => {
458
522
  const ledger = async () => {
459
523
  try {
460
- 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));
461
526
  }
462
527
  catch {
463
528
  return undefined;
464
529
  }
465
530
  };
466
- 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 });
467
533
  const refusal = policyRefusal(results, env.name, digest, "under the lock");
468
534
  if (refusal)
469
535
  throw refusal;
@@ -479,22 +545,20 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
479
545
  if (now.planDigest !== planned.planDigest) {
480
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.`);
481
547
  }
482
- // 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.
483
- const checked = (now.steps ?? []).filter((o) => !o.deferred);
484
- for (const o of checked)
485
- io.err(`${describeStep(o)}\n`);
486
- let verified = await verifyWaveDecision(cwd, a.spec, a.decidedAs?.target ?? env.name, a.decidedAs?.planDigest ?? planned.planDigest, now.held ?? []);
487
- // The commands (#107) run once, here, once the wave may apply: one that fails refuses; a held one needs the approval too.
488
- const commands = await runBeforeSteps(project, venv, env, steps.steps?.before?.filter((s) => s.sql === undefined), "under the lock", io);
489
- before = [...checked, ...commands];
490
- if (heldSteps(commands).length > 0 && verified.wave.status !== "approved")
491
- 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);
492
549
  wave = verified.wave;
493
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();
494
554
  },
495
555
  log: (l) => { io.err(`${l}\n`); },
496
556
  silences: migrationSilences,
497
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(", "));
498
562
  if (a.json)
499
563
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: planned.migrations, wavePlanDigest: planned.planDigest, result }), null, 2)}\n`);
500
564
  else
@@ -515,9 +579,13 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
515
579
  if (steps.note)
516
580
  io.err(`${steps.note}\n`);
517
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);
518
586
  const result = await executeApply(venv, ordered, {
519
587
  runNote: () => (before.length > 0 ? { steps: before } : undefined),
520
- ...afterSteps(project, venv, env, steps.steps?.after, io),
588
+ ...hooks.after,
521
589
  approvedDigest: approved,
522
590
  allowOutOfOrder: a.allowOutOfOrder,
523
591
  ...(a.lockWaitMs !== undefined ? { lockWaitMs: a.lockWaitMs } : {}),
@@ -526,16 +594,25 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
526
594
  // Under the lock: every pending migration ran first where this environment requires (exit 4 otherwise).
527
595
  await enforcePromotion(project, env.name, ordered, (await inspect(venv, ordered)).status.pending);
528
596
  const by = await verifyApproval(ledger, op, digest);
597
+ approver = by.resolvedBy;
529
598
  io.err(`approval: ${op.name} / ${op.gate} for ${digest}, by ${by.resolvedBy} at ${by.timestamp}${by.signer !== undefined ? `, sealed by ${by.signer}` : ""}\n`);
530
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.
531
- before = await runBeforeSteps(project, venv, env, steps.steps?.before, "under the lock", io);
600
+ before = await hooks.before();
532
601
  },
533
602
  log: (l) => { io.err(`${l}\n`); },
534
603
  silences: migrationSilences,
535
604
  ...(basePolicy
536
605
  ? {
537
606
  policy: async (digest, toApply) => {
538
- 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
+ });
539
616
  const refusal = policyRefusal(results, env.name, digest, "under the lock");
540
617
  if (refusal)
541
618
  throw refusal;
@@ -546,6 +623,8 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
546
623
  }
547
624
  : {}),
548
625
  });
626
+ if (result.applied.length > 0)
627
+ await recordApplied(project, env, venv, ordered, io, approver);
549
628
  if (a.json)
550
629
  io.out(`${JSON.stringify(applyJson({ mode: "execute", environment: env.name, planDigest: approved, result }), null, 2)}\n`);
551
630
  else
@@ -610,17 +689,25 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
610
689
  const steps = await stepsAtBase(project, env.name);
611
690
  if (steps.note && !a.json)
612
691
  io.err(`${steps.note}\n`);
613
- try {
614
- const outcomes = await runBeforeSteps(project, venv, env, steps.steps?.before, "before the gate", a.json ? undefined : io, "plan");
615
- if (!a.json && heldSteps(outcomes).length > 0)
616
- io.out(`before step ${heldSteps(outcomes).join(", ")} failed with onFailure approve: approving this plan lets it through\n`);
617
- }
618
- catch (e) {
619
- if (!(e instanceof YodelError) || e.exitCode !== EXIT_REFUSED)
620
- throw e;
621
- if (!a.json)
622
- io.err(`yodel apply: ${e.message}\n`);
623
- 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`);
624
711
  }
625
712
  const op = await findMigrateOp(project, env, a.op);
626
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.
@@ -633,7 +720,7 @@ async function versionedApplyWith(project, env, a, io, ordered, venv, outcome =
633
720
  dialect: project.dialect,
634
721
  toApply: report.status.pending,
635
722
  digest: report.digest,
636
- ledger: async () => ({ port: await gitLedger(project.dir), op }),
723
+ ledger: async () => overrideSourceAt(project.dir, overrideSubject(op.name), await migrationsApprovalAtBase(project, env.name)),
637
724
  });
638
725
  const denied = policyRefusal(policy, env.name, report.digest, "before the gate");
639
726
  if (denied) {
@@ -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
  }