@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/commands/new.js

@@ -0,0 +1,292 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { closeVersioned, inspect, openVersioned } from "../versioned/index.js";
+import { buildSchema } from "../chant/build.js";
+import { checksProblem, createMigration, describeExpect, parseCheckArg, migrationId, MIGRATIONS_DIR, newestMigration, readMigrations, refusedSteps, verifyChecksum, writeMigration, } from "../migrations/index.js";
+import { asBackfill, BACKFILL_FILE, backfillTemplate, loadBackfill, TEMPLATE_MARK } from "../steps/index.js";
+const usage = "usage: yodel new <name> [--backfill <file>] [--check <sql>]... [--replace [--env <env>]...] [--json] [--dir <project>]";
+const help = `${usage}
+
+Writes the next migration, migrations/<YYYYMMDDTHHMM>-<name>/, by diffing
+the newest migration's recorded schema (an empty schema for the first)
+against the current build of the declared schema. Offline: no database,
+dev or otherwise, is read. The name is lowercase letters and digits, words
+joined by - or _. The timestamp is UTC.
+
+The migration holds migration.sql (each statement after a comment naming its
+object, rule and class) and migration.json (id, parent, checksum, the
+recorded schema, the steps). A change no statement makes in place, such as a
+ClickHouse sort-key change or a Postgres column rename, is an Op step:
+written to migration.json with its declaration, and to migration.sql as a
+comment only.
+
+A data backfill is a step too. --backfill <file> ends the migration with a
+backfill step: <file> (relative to the project directory) is a module
+exporting a chant Op whose every step is an effect() batch with its own
+receipt, running SQL with activity("yodelSql", { sql }). It is copied into
+the migration's directory as ${BACKFILL_FILE} and counts in its checksum.
+yodel apply runs it after the statements before it, and a run that fails or
+is stopped part way resumes at the first batch without a receipt. When
+<file> does not exist yet, a template is written there and no migration:
+write the batches, then run the same command again. With --backfill a
+migration is written even when the declared schema has not changed.
+
+--check <sql> adds a pre-migration check to migration.json: a read-only
+query that must return no rows. yodel apply runs it against the environment
+before the gate and again under the lock just before the migration's first
+statement; a check that fails refuses the run (exit 4) and names it.
+Written "<name>: <sql>" it is named <name>, else check-1, check-2 and so on.
+For "returns true" or a count within bounds, edit its "expect" in
+migration.json (docs/migrations.md); the checks count in the checksum and
+the plan digest.
+
+--replace redoes the newest migration when it is named <name>: it is written
+again from its parent's recorded schema and the current build, under a new
+id, and the old one is removed. It is for a migration you just wrote and
+have not applied: refused when the migration is applied in an environment
+--env names (each one is read), and it says so when git already tracks it.
+
+Options:
+  --backfill <file>  end the migration with a backfill step running <file>
+  --check <sql>      a pre-migration check that must return no rows
+                     (repeatable; "<name>: <sql>" names it)
+  --replace          redo the newest migration, named <name>
+  --env <env>        with --replace: refuse if it is applied in <env>
+                     (repeatable)
+  --json             print what was written as JSON
+  -C, --dir <dir>    the project directory (default: the working directory)
+
+Exit codes:
+  0  a migration was written, or the declared schema has no change from the
+     newest recorded schema (then nothing is written)
+  1  no migration could be made: a bad config, a declaration chant cannot
+     build, a migrations directory that is not one chain (a fork, a missing
+     parent), a migration of that id already there
+  4  --replace refused, nothing written: the newest migration is not named
+     <name>, or it is applied in an environment --env names
+`;
+function parseNewArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: { json: { type: "boolean" }, dir: { type: "string", short: "C" }, backfill: { type: "string" }, replace: { type: "boolean" }, env: { type: "string", multiple: true }, check: { type: "string", multiple: true } },
+        });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+    }
+    const [name, ...rest] = parsed.positionals;
+    if (name === undefined || rest.length > 0)
+        throw new YodelError(usage);
+    if (parsed.values.env !== undefined && parsed.values.replace !== true)
+        throw new YodelError(`--env goes with --replace\n${usage}`);
+    migrationId(name, new Date()); // a bad name fails before anything is built
+    return {
+        name,
+        json: parsed.values.json === true,
+        dir: typeof parsed.values.dir === "string" ? parsed.values.dir : process.cwd(),
+        backfill: typeof parsed.values.backfill === "string" ? parsed.values.backfill : undefined,
+        replace: parsed.values.replace === true,
+        envs: Array.isArray(parsed.values.env) ? parsed.values.env.filter((e) => typeof e === "string") : [],
+        checks: parseChecks(parsed.values.check),
+    };
+}
+function parseChecks(value) {
+    const args = Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+    const checks = args.map((a, i) => parseCheckArg(a, i + 1));
+    const problem = checksProblem(checks);
+    if (problem)
+        throw new YodelError(`--check: ${problem}\n${usage}`);
+    return checks;
+}
+function report(io, json, made, path, projectDir) {
+    const steps = made.statements.steps;
+    const refused = refusedSteps(steps);
+    const statementCount = steps.length - refused.length;
+    if (json) {
+        io.out(`${JSON.stringify({
+            written: true,
+            id: made.id,
+            path,
+            parent: made.document.parent,
+            checksum: made.document.checksum,
+            dialect: made.document.dialect,
+            statements: statementCount,
+            ops: refused.filter((s) => s.kind === "op").map((s) => ({ op: s.op, object: s.object, name: s.name, rules: s.changes.map((c) => c.rule) })),
+            manual: refused.filter((s) => s.kind === "manual").map((s) => ({ object: s.object, name: s.name, rules: s.changes.map((c) => c.rule), detail: s.detail })),
+            hints: made.document.hints,
+            checks: made.document.checks ?? [],
+        }, null, 2)}\n`);
+        return;
+    }
+    const where = relative(projectDir, path) || path;
+    const parent = made.document.parent ? `follows ${made.document.parent}` : "the first migration";
+    const lines = [`Wrote ${where}/ (${String(statementCount)} statement${statementCount === 1 ? "" : "s"}; ${parent})`];
+    for (const s of refused) {
+        const rules = s.changes.map((c) => c.rule).join(", ");
+        const backfill = asBackfill(s);
+        if (backfill) {
+            lines.push(`  This migration ends with a backfill step: the Op ${backfill.options.file} exports, copied into the migration's directory.`);
+            lines.push(`    yodel apply runs its effect() batches after the statements before it, resuming from their receipts after a failure.`);
+        }
+        else if (s.kind === "op") {
+            lines.push(`  This migration contains an Op step: ${s.op} for ${s.object} (${s.name}), ${rules}.`);
+            lines.push(`    It is not SQL. migration.json holds the Op's declaration:`);
+            lines.push(`    ${s.declaration}`);
+        }
+        else {
+            lines.push(`  This migration contains a manual step: ${s.object} (${s.name}), ${rules}. No statement and no Op makes it:`);
+            lines.push(`    ${s.detail}`);
+        }
+    }
+    for (const c of made.document.checks ?? [])
+        lines.push(`  check ${c.name}: ${c.sql} (${describeExpect(c)}, before the first statement)`);
+    for (const h of made.document.hints)
+        lines.push(`  hint: ${h}`);
+    io.out(`${lines.join("\n")}\n`);
+}
+/** `yodel new <name>`; the exit codes are in `help`. */
+export const newCommand = {
+    name: "new",
+    summary: "write the next migration from the declared schema",
+    implemented: true,
+    run: (args, io) => guarded("new", io, args, help, async () => {
+        const { name, json, dir, backfill: backfillArg, replace, envs, checks } = parseNewArgs(args);
+        const project = await loadProject(dir);
+        let backfill;
+        if (backfillArg !== undefined) {
+            const path = resolve(project.dir, backfillArg);
+            if (!existsSync(path)) {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, backfillTemplate(name, project.dialect));
+                const where = relative(project.dir, path) || path;
+                if (json)
+                    io.out(`${JSON.stringify({ written: false, template: path }, null, 2)}\n`);
+                else
+                    io.out(`Wrote a backfill template at ${where}. Write its batches, then run yodel new ${name} --backfill ${backfillArg} again. No migration written.\n`);
+                return 0;
+            }
+            const text = readFileSync(path, "utf8");
+            if (text.includes(TEMPLATE_MARK))
+                throw new YodelError(`${path} is still the template; write its batches' SQL first`);
+            await loadBackfill(path, text);
+            backfill = { text };
+        }
+        const migrationsDir = join(project.dir, MIGRATIONS_DIR);
+        const ordered = readMigrations(migrationsDir);
+        const replaced = replace ? await replaceable(project, ordered, name, envs, io) : undefined;
+        const previous = replaced ? ordered[ordered.length - 2] : newestMigration(ordered);
+        if (previous && !verifyChecksum(previous).ok) {
+            io.err(`yodel new: warning: ${previous.id}'s files no longer match its recorded checksum; the new migration follows it as recorded\n`);
+        }
+        const build = await buildSchema(project);
+        let made;
+        try {
+            made = createMigration({ name, build: build.output, previous, ...(backfill ? { backfill } : {}), ...(checks.length > 0 ? { checks } : {}) });
+        }
+        finally {
+            build.dispose();
+        }
+        if (made.id === undefined) {
+            if (replaced) {
+                const msg = `No changes from ${previous ? `${previous.id}'s recorded schema` : "an empty schema"}: the declared schema is what ${replaced.id} started from. Nothing written; ${replaced.id} is kept (delete it to drop it).`;
+                if (json)
+                    io.out(`${JSON.stringify({ written: false, replaced: null, kept: replaced.id }, null, 2)}\n`);
+                else
+                    io.out(`${msg}\n`);
+                return 0;
+            }
+            const from = previous ? `the newest migration's recorded schema (${previous.id})` : "an empty schema (the declared schema declares nothing)";
+            if (json)
+                io.out(`${JSON.stringify({ written: false, parent: previous?.id ?? null, dialect: project.dialect, hints: made.statements.hints }, null, 2)}\n`);
+            else
+                io.out(`No changes: the declared schema matches ${from}. Nothing written.\n`);
+            return 0;
+        }
+        if (replaced) {
+            // Moved aside first and removed only once the new one is written, so a failure leaves the old one in place.
+            const aside = join(migrationsDir, `.replaced-${replaced.id}`);
+            renameSync(replaced.dir, aside);
+            let path;
+            try {
+                path = writeMigration(migrationsDir, made);
+            }
+            catch (e) {
+                renameSync(aside, replaced.dir);
+                throw e;
+            }
+            rmSync(aside, { recursive: true, force: true });
+            if (!json)
+                io.out(`Replaced ${replaced.id}.\n`);
+            report(io, json, made, path, project.dir);
+            return 0;
+        }
+        const path = writeMigration(migrationsDir, made);
+        report(io, json, made, path, project.dir);
+        return 0;
+    }),
+};
+/** Exit code: --replace refused; nothing written. */
+export const REPLACE_REFUSED = 4;
+/** The newest migration, when --replace may redo it: named `name`, and applied in none of `envs`. */
+async function replaceable(project, ordered, name, envs, io) {
+    const newest = newestMigration(ordered);
+    if (!newest)
+        throw new YodelError(`--check <sql> adds a pre-migration check to migration.json: a read-only
+query that must return no rows. yodel apply runs it against the environment
+before the gate and again under the lock just before the migration's first
+statement; a check that fails refuses the run (exit 4) and names it.
+Written "<name>: <sql>" it is named <name>, else check-1, check-2 and so on.
+For "returns true" or a count within bounds, edit its "expect" in
+migration.json (docs/migrations.md); the checks count in the checksum and
+the plan digest.
+
+--replace redoes the newest migration, and there is none yet; run yodel new ${name}`, REPLACE_REFUSED);
+    if (newest.id.slice(newest.id.indexOf("-") + 1) !== name) {
+        throw new YodelError(`--check <sql> adds a pre-migration check to migration.json: a read-only
+query that must return no rows. yodel apply runs it against the environment
+before the gate and again under the lock just before the migration's first
+statement; a check that fails refuses the run (exit 4) and names it.
+Written "<name>: <sql>" it is named <name>, else check-1, check-2 and so on.
+For "returns true" or a count within bounds, edit its "expect" in
+migration.json (docs/migrations.md); the checks count in the checksum and
+the plan digest.
+
+--replace redoes the newest migration, ${newest.id}, which is not named ${name}; nothing written`, REPLACE_REFUSED);
+    }
+    for (const envName of envs) {
+        const env = resolveEnvironment(project, envName);
+        const venv = await openVersioned(project, env);
+        try {
+            const { status } = await inspect(venv, ordered, { sync: false });
+            if (status.applied.some((a) => a.id === newest.id)) {
+                throw new YodelError(`refused: ${newest.id} is applied in ${env.name}, so it is not redone; write the change as a new migration (yodel new <name>). Nothing written.`, REPLACE_REFUSED);
+            }
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    }
+    if (envs.length === 0)
+        io.err(`yodel new: --replace checked no environment; with --env <env>, it refuses a migration applied there\n`);
+    if (tracked(project.dir, newest.dir))
+        io.err(`yodel new: warning: git already tracks ${newest.id}; anyone who has that commit has the old one\n`);
+    return newest;
+}
+/** Whether git tracks anything under `path`. */
+function tracked(cwd, path) {
+    try {
+        return execFileSync("git", ["ls-files", "--", path], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() !== "";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=new.js.map

package/dist/commands/new.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new.js","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,YAAY,EACZ,cAAc,EACd,cAAc,GAGf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7G,MAAM,KAAK,GAAG,wHAAwH,CAAC;AAEvI,MAAM,IAAI,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;+BAmBU,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC3C,CAAC;AAYF,SAAS,YAAY,CAAC,IAAc;IAClC,IAAI,MAAoC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC;YACjB,IAAI;YACJ,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;SAC5N,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC;IAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACvE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,MAAM,IAAI,UAAU,CAAC,8BAA8B,KAAK,EAAE,CAAC,CAAC;IACnI,WAAW,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,4CAA4C;IAC3E,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI;QACjC,GAAG,EAAE,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;QAC9E,QAAQ,EAAE,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QACzF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI;QACvC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;QACjH,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,OAAO;QAAE,MAAM,IAAI,UAAU,CAAC,YAAY,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,EAAM,EAAE,IAAa,EAAE,IAAsB,EAAE,IAAY,EAAE,UAAkB;IAC7F,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;IACpC,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACrD,IAAI,IAAI,EAAE,CAAC;QACT,EAAE,CAAC,GAAG,CACJ,GAAG,IAAI,CAAC,SAAS,CACf;YACE,OAAO,EAAE,IAAI;YACb,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI;YACJ,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;YAChC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YAC9B,UAAU,EAAE,cAAc;YAC1B,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3I,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1J,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK;YAC1B,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE;SACnC,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC;IAChG,MAAM,KAAK,GAAG,CAAC,SAAS,KAAK,MAAM,MAAM,CAAC,cAAc,CAAC,aAAa,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,GAAG,CAAC,CAAC;IACrH,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,CAAC,sDAAsD,QAAQ,CAAC,OAAO,CAAC,IAAI,kDAAkD,CAAC,CAAC;YAC1I,KAAK,CAAC,IAAI,CAAC,yHAAyH,CAAC,CAAC;QACxI,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,GAAG,CAAC,CAAC;YACnG,KAAK,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;YAC5E,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,KAAK,oCAAoC,CAAC,CAAC;YAC3H,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,KAAK,cAAc,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC;IACzI,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAChE,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,MAAM,UAAU,GAAY;IACjC,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,mDAAmD;IAC5D,WAAW,EAAE,IAAI;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAChB,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE;QACxC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC7F,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAsC,CAAC;QAC3C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9C,aAAa,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;gBAClD,IAAI,IAAI;oBAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;;oBAChF,EAAE,CAAC,GAAG,CAAC,gCAAgC,KAAK,2CAA2C,IAAI,eAAe,WAAW,iCAAiC,CAAC,CAAC;gBAC7J,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,sDAAsD,CAAC,CAAC;YACtH,MAAM,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC/B,QAAQ,GAAG,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;QACD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3F,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACnF,IAAI,QAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC;YAC7C,EAAE,CAAC,GAAG,CAAC,uBAAuB,QAAQ,CAAC,EAAE,4FAA4F,CAAC,CAAC;QACzI,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,IAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,GAAG,eAAe,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/I,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,mBAAmB,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,iBAAiB,iCAAiC,QAAQ,CAAC,EAAE,mCAAmC,QAAQ,CAAC,EAAE,kCAAkC,CAAC;gBAC7N,IAAI,IAAI;oBAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;;oBACnG,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;gBACxB,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,2CAA2C,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,wDAAwD,CAAC;YAC7I,IAAI,IAAI;gBAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,IAAI,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;;gBACtJ,EAAE,CAAC,GAAG,CAAC,2CAA2C,IAAI,sBAAsB,CAAC,CAAC;YACnF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,4GAA4G;YAC5G,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9D,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAChC,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM,CAAC,CAAC;YACV,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,IAAI,CAAC,IAAI;gBAAE,EAAE,CAAC,GAAG,CAAC,YAAY,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;YAChD,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1C,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,IAAI,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACjD,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;CACL,CAAC;AAEF,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,qGAAqG;AACrG,KAAK,UAAU,WAAW,CAAC,OAAgB,EAAE,OAA6B,EAAE,IAAY,EAAE,IAAuB,EAAE,EAAM;IACvH,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,UAAU,CAAC;;;;;;;;;8EAS0C,IAAI,EAAE,EAAE,eAAe,CAAC,CAAC;IACrG,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,UAAU,CAAC;;;;;;;;;yCASgB,MAAM,CAAC,EAAE,wBAAwB,IAAI,mBAAmB,EAAE,eAAe,CAAC,CAAC;IAClH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACjE,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnD,MAAM,IAAI,UAAU,CAAC,YAAY,MAAM,CAAC,EAAE,kBAAkB,GAAG,CAAC,IAAI,iGAAiG,EAAE,eAAe,CAAC,CAAC;YAC1L,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,EAAE,CAAC,GAAG,CAAC,uGAAuG,CAAC,CAAC;IACvI,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,GAAG,CAAC,0CAA0C,MAAM,CAAC,EAAE,gDAAgD,CAAC,CAAC;IAClJ,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gDAAgD;AAChD,SAAS,OAAO,CAAC,GAAW,EAAE,IAAY;IACxC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IACrI,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/commands/override.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../command.js";
+/** `yodel override <env> --rule <id> --reason <text>`; the exit codes are in `help`. */
+export declare const override: Command;

package/dist/commands/override.js

@@ -0,0 +1,118 @@
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { EXIT_REFUSED } from "../exit.js";
+import { runChant } from "../chant/process.js";
+import { runnable } from "../chant/runnable.js";
+import { closeVersioned, findMigrateOp, hasMigrations, judgePlan, openVersioned, overrideGate, readChain, statusReport, ALLOW_OUT_OF_ORDER_ENV } from "../versioned/index.js";
+const usage = "usage: yodel override <env> --rule <id> --reason <text> [--by <name>] [--dir <project>] [--op <name>] [--allow-out-of-order]";
+const help = `${usage}
+
+Records an override of a policy rule (yodel.config.ts policy.rules) for the
+plan yodel apply <env> would run now: a person's decision, with a reason, to
+apply a plan the rule denies. It is written to chant's gate ledger (the
+chant/lifecycle branch) with chant approve <op> override-<rule> --plan
+<digest> --note <reason>, bound to the environment's migrations Op and the
+plan digest. It counts only for exactly that digest: once the plan moves
+(a migration added or edited, the live schema changed), the rule denies
+again and needs a new override. It counts only when policy.overriders
+lists the name it is recorded under (--by, else chant's: the CI actor or
+your user). yodel apply records the overrides it relied on in the history.
+
+Refused when the rule does not deny the current plan: an override answers
+one denial, it is not a standing exception.
+
+Options:
+  --rule <id>           the rule to override (repeatable)
+  --reason <text>       why; required
+  --by <name>           who is overriding (chant approve --approver)
+  --op <name>           the migrations Op, when more than one applies <env>
+  --allow-out-of-order  the plan yodel apply --allow-out-of-order runs
+  -C, --dir <dir>       the project directory (default: the working directory)
+
+Exit codes:
+  0  recorded
+  4  nothing recorded: the plan has nothing to apply or apply would refuse
+     it, a rule that does not deny it, a name policy.overriders does not list
+  1  anything else: a bad config, a server that does not answer, chant
+     approve failed
+`;
+/** `yodel override <env> --rule <id> --reason <text>`; the exit codes are in `help`. */
+export const override = {
+    name: "override",
+    summary: "override a policy rule for the current plan, with a reason",
+    implemented: true,
+    run: (args, io) => guarded("override", io, args, help, async () => {
+        let parsed;
+        try {
+            parsed = parseArgs({
+                args,
+                allowPositionals: true,
+                strict: true,
+                options: {
+                    rule: { type: "string", multiple: true },
+                    reason: { type: "string" },
+                    by: { type: "string" },
+                    dir: { type: "string", short: "C" },
+                    op: { type: "string" },
+                    "allow-out-of-order": { type: "boolean" },
+                },
+            });
+        }
+        catch (e) {
+            throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+        }
+        const { values, positionals } = parsed;
+        const [name, ...rest] = positionals;
+        if (name === undefined || rest.length > 0)
+            throw new YodelError(usage);
+        const rules = Array.isArray(values.rule) ? values.rule.filter((r) => typeof r === "string") : [];
+        const reason = typeof values.reason === "string" ? values.reason.trim() : "";
+        const by = typeof values.by === "string" ? values.by : undefined;
+        const allowOutOfOrder = values["allow-out-of-order"] === true || process.env[ALLOW_OUT_OF_ORDER_ENV] === "1";
+        const project = await loadProject(typeof values.dir === "string" ? values.dir : process.cwd());
+        const env = resolveEnvironment(project, name);
+        if (rules.length === 0 || reason === "")
+            throw new YodelError(`--rule and --reason are required: an override names the rule and says why\n${usage}`);
+        if (!hasMigrations(project))
+            throw new YodelError(`${project.dir} has no migrations/ directory with a migration; policy is for versioned migrations`);
+        const policy = project.yodel?.config.policy;
+        if (!policy)
+            throw new YodelError(`yodel.config.ts declares no policy, so there is nothing to override`, EXIT_REFUSED);
+        const unknown = rules.filter((r) => !policy.rules.some((x) => x.id === r));
+        if (unknown.length > 0)
+            throw new YodelError(`no policy rule ${unknown.join(", ")} (policy.rules: ${policy.rules.map((r) => r.id).join(", ")}); nothing recorded`, EXIT_REFUSED);
+        if (by !== undefined && !(policy.overriders ?? []).includes(by)) {
+            throw new YodelError(`${by} is not in policy.overriders (${(policy.overriders ?? []).join(", ") || "none"}), so an override by them would not count; nothing recorded`, EXIT_REFUSED);
+        }
+        const ordered = readChain(project);
+        const venv = await openVersioned(project, env);
+        try {
+            const report = await statusReport(venv, ordered, { allowOutOfOrder });
+            if (report.refusal)
+                throw new YodelError(`yodel apply would refuse this plan before any policy: ${report.refusal.message}\nNothing recorded.`, EXIT_REFUSED);
+            if (!report.digest)
+                throw new YodelError(`${env.name} has nothing pending: there is no plan to override; nothing recorded`, EXIT_REFUSED);
+            const results = await judgePlan({ policy, environment: env.name, dialect: project.dialect, toApply: report.status.pending, digest: undefined, ledger: () => Promise.resolve(undefined) });
+            const notDenying = rules.filter((r) => results.find((x) => x.id === r)?.outcome !== "denied");
+            if (notDenying.length > 0) {
+                throw new YodelError(`${notDenying.join(", ")} ${notDenying.length === 1 ? "does" : "do"} not deny the plan for ${env.name} (${report.digest}); an override answers a denial. Nothing recorded.`, EXIT_REFUSED);
+            }
+            const op = await findMigrateOp(project, env, typeof values.op === "string" ? values.op : undefined);
+            for (const rule of rules) {
+                const denial = results.find((x) => x.id === rule);
+                io.out(`${rule} denies ${report.digest}:\n${(denial?.reasons ?? []).map((x) => `  ${x}`).join("\n")}\n`);
+                const ran = await runChant(["approve", op.name, overrideGate(rule), "--plan", report.digest, "--note", reason, ...(by ? ["--approver", by] : [])], { cwd: project.dir, onStdout: io.err, onStderr: io.err });
+                if (ran.code !== 0)
+                    throw new YodelError(`chant approve ${op.name} ${overrideGate(rule)} failed (exit ${String(ran.code)}); the override of ${rule} was not recorded`);
+                io.out(`Recorded an override of ${rule} for ${report.digest}${by ? ` by ${by}` : ""}: ${reason}\n`);
+            }
+            io.out(`It counts for this plan only. Apply it with:\n  ${runnable(`yodel apply ${env.name}`, project.dir)}\n`);
+            return 0;
+        }
+        finally {
+            await closeVersioned(venv);
+        }
+    }),
+};
+//# sourceMappingURL=override.js.map

package/dist/commands/override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.js","sourceRoot":"","sources":["../../src/commands/override.ts"],"names":[],"mappings":"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"}

package/dist/commands/plan.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../command.js";
+/** `yodel plan <env>`; the exit codes are in `help`. */
+export declare const plan: Command;

package/dist/commands/plan.js

@@ -0,0 +1,183 @@
+import { parseArgs } from "node:util";
+import { guarded } from "../env-args.js";
+import { loadProject, resolveEnvironment, YodelError } from "../project.js";
+import { declarativeTopologyRefusal, describeSettingsTopology, environmentSettings } from "../config/settings.js";
+import { buildSchema } from "../chant/build.js";
+import { planEnvironment, planExitCode, planJson, renderPlan } from "../chant/plan.js";
+import { hasMigrations } from "../versioned/index.js";
+import { describeServer, probeServer } from "../server.js";
+import { runnable } from "../chant/runnable.js";
+import { decodeSubject } from "../versioned/explain.js";
+import { collectVersionedPlan } from "../pr/model.js";
+import { commentMarker, planJsonVersioned, renderPlanMarkdown, renderPlanText, subjectIn } from "../pr/render.js";
+import { resolveForgeTarget } from "../pr/forge.js";
+import { commentClient, findComment, upsertComment } from "../pr/comment.js";
+const usage = "usage: yodel plan <env> [--json] [--dir <project>] [--format text|markdown|json]\n" +
+    "                        [--allow-out-of-order] [--op <name>]\n" +
+    "                        [--comment [--forge github|gitlab|forgejo]\n" +
+    "                         [--repo <repo>] [--pr <n>] [--api-url <url>] [--token-env <VAR>]]";
+const help = `${usage}
+
+Declarative project (no migrations/ directory): shows the classified change
+from the environment's live database (sql.profiles.<env>) to the declared
+schema, as chant sql plan reports it.
+
+Versioned project (a migrations/ directory): shows the pending migrations,
+each step with its rule and class (an Op step with the Op that makes it, a
+manual step with what it needs), integrity problems (directory problems,
+checksum mismatches, out-of-order migrations), and the plan digest yodel
+apply asks approval for, with the chant approve command that approves it.
+When chant's gate ledger holds an approval of the migrations Op's gate for
+another digest, it says what moved since. Reads only.
+
+Options:
+  --json                print the plan as JSON (the same as --format json)
+  --format <f>          text (default), markdown (the pull request comment),
+                        json
+  --allow-out-of-order  versioned: the plan yodel apply --allow-out-of-order
+                        would run
+  --op <name>           versioned: the migrations Op, when more than one
+                        applies <env>
+  --comment             versioned: post the markdown as one comment on the
+                        pull (merge) request, updating the one posted before;
+                        prints the text plan. The forge, repository, request
+                        and API come from the CI job's environment
+                        (GitHub Actions, GitLab CI, Forgejo Actions) unless
+                        given:
+    --forge <f>         github, gitlab or forgejo
+    --repo <repo>       owner/name (GitHub, Forgejo) or the project id (GitLab)
+    --pr <n>            the pull request number or merge request iid
+    --api-url <url>     the REST API base (https://api.github.com,
+                        https://gitlab.example/api/v4,
+                        https://forgejo.example/api/v1)
+    --token-env <VAR>   the variable holding the token (default GITHUB_TOKEN;
+                        GITLAB_TOKEN; FORGEJO_TOKEN, else GITHUB_TOKEN)
+  -C, --dir <dir>       the project directory (default: the working directory)
+
+Exit codes:
+  0  every change can be made in place, or there is none; versioned: apply
+     would run (or has nothing to do). Pending migrations still exit 0: plan
+     reports, and a CI job that posts it should not fail because a pull
+     request adds a migration; yodel status exits 3 for them
+  2  a change needs its own Op: a ClickHouse rebuild, a Postgres expand and
+     contract (declarative); versioned: a pending migration has an Op or
+     manual step apply does not run yet
+  4  versioned: apply would refuse: a checksum mismatch, an applied migration
+     gone from the directory, an out-of-order migration, a fork or another
+     problem in the migrations directory
+  1  no plan could be made: a bad config, an unknown environment, a declaration
+     chant cannot build, a server it cannot read, a comment the forge refused
+`;
+function parsePlanArgs(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                json: { type: "boolean" },
+                dir: { type: "string", short: "C" },
+                format: { type: "string" },
+                comment: { type: "boolean" },
+                "allow-out-of-order": { type: "boolean" },
+                op: { type: "string" },
+                forge: { type: "string" },
+                repo: { type: "string" },
+                pr: { type: "string" },
+                "api-url": { type: "string" },
+                "token-env": { type: "string" },
+            },
+        });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage}`);
+    }
+    const { values: v, positionals } = parsed;
+    const [env, ...rest] = positionals;
+    if (env === undefined || rest.length > 0)
+        throw new YodelError(usage);
+    const str = (k) => (typeof v[k] === "string" ? v[k] : undefined);
+    const format = str("format") ?? (v.json === true ? "json" : "text");
+    if (format !== "text" && format !== "markdown" && format !== "json")
+        throw new YodelError(`--format must be text, markdown or json, got ${JSON.stringify(format)}\n${usage}`);
+    if (v.json === true && format !== "json")
+        throw new YodelError(`--json and --format ${format} cannot be combined\n${usage}`);
+    const forgeFlags = ["forge", "repo", "pr", "api-url", "token-env"].filter((k) => str(k) !== undefined);
+    if (forgeFlags.length > 0 && v.comment !== true)
+        throw new YodelError(`--${forgeFlags.join(", --")} ${forgeFlags.length === 1 ? "goes" : "go"} with --comment\n${usage}`);
+    const forge = { forge: str("forge"), repo: str("repo"), pr: str("pr"), apiUrl: str("api-url"), tokenEnv: str("token-env") };
+    return {
+        env,
+        dir: str("dir") ?? process.cwd(),
+        format,
+        comment: v.comment === true,
+        allowOutOfOrder: v["allow-out-of-order"] === true,
+        op: str("op"),
+        forge,
+        versionedOnly: [
+            ...(format === "markdown" ? ["--format markdown"] : []),
+            ...(v.comment === true ? ["--comment"] : []),
+            ...(v["allow-out-of-order"] === true ? ["--allow-out-of-order"] : []),
+            ...(str("op") !== undefined ? ["--op"] : []),
+        ],
+    };
+}
+/** `yodel plan <env>`; the exit codes are in `help`. */
+export const plan = {
+    name: "plan",
+    summary: "show what apply would change in an environment",
+    implemented: true,
+    run: (args, io) => guarded("plan", io, args, help, async () => {
+        const a = parsePlanArgs(args);
+        const project = await loadProject(a.dir);
+        const env = resolveEnvironment(project, a.env);
+        if (hasMigrations(project))
+            return versionedPlan(project, env, a, io);
+        if (a.versionedOnly.length > 0)
+            throw new YodelError(`${a.versionedOnly.join(", ")} ${a.versionedOnly.length === 1 ? "is" : "are"} for versioned migrations, and ${project.dir} has no migrations/ directory with a migration`);
+        return declarativePlan(project, env, a.format === "json", io);
+    }),
+};
+async function declarativePlan(project, env, json, io) {
+    const refusal = project.dialect === "clickhouse" ? declarativeTopologyRefusal(project, env.name) : undefined;
+    if (refusal)
+        throw refusal;
+    const topology = project.dialect === "clickhouse" ? `, topology ${describeSettingsTopology(environmentSettings(project, env.name))}` : "";
+    const build = await buildSchema(project);
+    try {
+        const result = await planEnvironment(project, env, build);
+        const server = await probeServer(project, env);
+        if (json)
+            io.out(`${JSON.stringify({ ...planJson(result), ...(server ? { server } : {}) }, null, 2)}\n`);
+        else
+            io.out(`${await renderPlan(result, `Plan for ${env.name} (${server ? describeServer(server) : project.dialect}, sql.profiles.${env.name}${topology})`)}\n`);
+        return planExitCode(result);
+    }
+    finally {
+        build.dispose();
+    }
+}
+async function versionedPlan(project, env, a, io) {
+    const marker = commentMarker(env.name);
+    // Resolve the forge first: a job missing its token fails before it reads the server.
+    const target = a.comment ? resolveForgeTarget(a.forge, process.env) : undefined;
+    const client = target ? commentClient(target) : undefined;
+    const existing = client ? await findComment(client, marker) : undefined;
+    const carried = existing ? subjectIn(existing.body) : undefined;
+    const previous = carried ? decodeSubject(carried) : undefined;
+    const result = await collectVersionedPlan(project, env, { allowOutOfOrder: a.allowOutOfOrder, opName: a.op, previous });
+    const code = result.refusal?.exitCode ?? 0;
+    if (client && target) {
+        const posted = await upsertComment(client, marker, renderPlanMarkdown(result), existing);
+        io.err(`yodel plan: ${posted.action} the plan comment on ${target.forge} ${target.repo}#${String(target.pr)}${posted.comment.url ? ` (${posted.comment.url})` : ` (comment ${String(posted.comment.id)})`}\n`);
+    }
+    if (a.format === "json")
+        io.out(`${JSON.stringify(planJsonVersioned(result), null, 2)}\n`);
+    else if (a.format === "markdown")
+        io.out(renderPlanMarkdown(result));
+    else
+        io.out(renderPlanText(result, { runnable: (c) => runnable(c, project.dir) }));
+    return code;
+}
+//# sourceMappingURL=plan.js.map