@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# SQL Yodeler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Schema management and migrations for ClickHouse and Postgres, on chant's `sql` lexicon. `design/README.md` is the design, and `research/` holds the reports it is based on.
+
+## Documentation
+
+[`docs/`](docs/README.md) covers installing (the package is not on npm; it installs from git, which needs read access to this private repository, or from a clone or a packed tarball), [starting a project](docs/adoption.md) from a template or with `yodel init --from`, [the declarative and versioned workflows](docs/workflows.md), [migrations](docs/migrations.md), [steps](docs/steps.md), [lint](docs/lint.md), [approval](docs/approval.md), [drift](docs/drift.md) and [topology](docs/topology.md).
+
+[`examples/clickhouse`](examples/clickhouse/README.md) and [`examples/postgres`](examples/postgres/README.md) are example projects, each with a transcript of a run against chant's emulator.
+
+## Starting a project
+
+`templates/clickhouse` and `templates/postgres` are starter projects for `chant init --from`:
+
+```sh
+chant init --from INTENTIUS/sql-yodeler@main#templates/clickhouse --param name=events-schema --param database=events my-schema
+chant init --from INTENTIUS/sql-yodeler@main#templates/postgres --param name=app-schema --param schema=app my-schema
+```
+
+Each gives `chant.config.ts` with a profile per environment (`dev`, `prod`), `yodel.config.ts`, a migrate Op per environment (`yodel apply` behind a gate bound to the plan digest), a `WatchOp` per environment for drift on a schedule, and pipelines for GitHub Actions, GitLab CI and Forgejo Actions: `yodel lint` and the plan comment on pull requests with read-only credentials, `yodel apply` on a push to main with the writer, and the drift watch on its cron with the reader. `scripts/ci.ts` in the project renders the pipelines again after an environment is added (`npm run ci`). The parameters are in each template's `chant.template.json`; the template's README covers the credentials and each forge's setup.
+
+## Development
+
+Node 22 (`.nvmrc`).
+
+```sh
+npm ci
+npm run build
+npx yodel --help
+npm run check   # typecheck, lint and test
+```
+
+Working rules are in `AGENTS.md`.
+
+## Versioned migrations (ClickHouse)
+
+`yodel apply <env>` takes the versioned path when the project has a `migrations/` directory holding at least one migration (`yodel new` writes them); otherwise it is the declarative path, unchanged. `yodel status <env>` lists applied, pending, out-of-order and part-way migrations and checksum mismatches (`--json`; exit 0 up to date, 3 pending, 4 mismatch or out of order, 2 an Op step, 1 error).
+
+`yodel init --from <env>` adopts an existing database: it reads it with chant's import (`chant import --from`), writes the declarations to `src/`, checks they plan clean, writes the baseline migration (the first one, creating everything) and records it applied in the history without running it (a succeeded migration row whose `note` starts `baseline:`). It needs a `chant.config.ts` with `sql.profiles.<env>` already, and for ClickHouse the profile's `databases`; `yodel init --help` has the rest. On Postgres it does the same, recording the baseline in `<history schema>.history`.
+
+The history is an append-only table, `<db>.history`, one row per migration and per statement event, never updated or deleted.
+
+### yodel.config.ts
+
+An optional `yodel.config.ts` next to `chant.config.ts` sets what chant's config does not, per environment (by its `sql.profiles` name):
+
+```ts
+// yodel.config.ts
+import { defineConfig } from "@intentius/sql-yodeler";
+
+export default defineConfig({
+  environments: {
+    dev: { topology: "single" },
+    staging: { topology: "replicated" },
+    prod: { topology: "cluster:main", history: { database: "yodeler" }, lockTtl: 1800 },
+  },
+});
+```
+
+- `topology`: `single` (a single node), `cluster:<name>` (`ON CLUSTER <name>`, `Replicated*MergeTree` with a Keeper path), `replicated` or `replicated:<cluster>` (a `Replicated` database: no `ON CLUSTER`, `Replicated*MergeTree` with no arguments), or `cloud` (no `ON CLUSTER`, plain MergeTree, which Cloud makes `SharedMergeTree`). The object form, `{ kind: "cluster", cluster: "main", replicaPath, replicaName }`, sets the Keeper path and replica name of the tables the migrations create. Order: `yodel.config.ts`, then `sql.profiles.<env>.topology` in chant.config.ts, then `YODEL_TOPOLOGY`, then `single`.
+- `history.database`: the database for the history and the lock. Then `YODEL_HISTORY_DATABASE`, then `yodeler`.
+- `lockTtl`: the apply lock's TTL in seconds. Then `YODEL_LOCK_TTL`, then 900.
+
+One migrations directory serves every topology. `yodel new` writes each statement for a single node and records nothing about where it runs; `yodel apply` renders each statement for the environment's topology as it sends it (chant's `renderStatement`). The history records a statement by the hash of the statement as written, so a migration that failed part way resumes the same way on any topology, and the statement row's `note` says the topology it was sent for (`topology=cluster:main`). The plan digest covers the topology, so an approval given for one topology does not apply on another. The history table's own engine follows the topology too: MergeTree on a single node and on Cloud, `ReplicatedMergeTree` `ON CLUSTER` on a cluster (one copy for the whole cluster), `ReplicatedMergeTree` inside a `Replicated` database. `yodel status` and `yodel plan` print the topology and where it came from.
+
+The declarative path (no `migrations/`) plans and applies through chant, which reads `sql.profiles.<env>.topology` only, so a topology set in `yodel.config.ts` alone is refused there; set it in chant.config.ts as well. A rebuild step (`ClickHouseRebuildOp`) runs through chant too, but yodel hands its activities the environment's topology, so it renders for the same topology as the statements around it.
+
+One apply runs at a time: the lock is a row in a KeeperMap table, `<db>.lock`, which needs Keeper and `keeper_map_path_prefix` on the server. A single node without them gets a lock file on the runner's machine, and the run says cross-runner locking needs Keeper. A lock left by a dead runner expires; to clear it sooner, once you know nothing is applying: `ALTER TABLE <db>.lock DELETE WHERE name = 'apply'` (or remove the lock file the refusal names).
+
+The apply runs as a chant Op behind a gate bound to the plan digest (the pending migrations' checksums, the history and the live schema). `yodel apply <env>` prints the declaration to add when there is none:
+
+```ts
+// ops/migrate-prod.op.ts
+import { Op, phase, gate, shell, stepOutput } from "@intentius/chant/op";
+
+const plan = shell("yodel apply prod --digest", { id: "plan" });
+const digest = stepOutput(plan, "stdout");
+
+export const op = Op({
+  name: "migrate-prod",
+  overview: "Apply the pending migrations to prod, behind an approval bound to their plan digest",
+  phases: [
+    phase("Plan", [plan]),
+    phase("Approve", [gate("approve-migrate-prod", { plan: digest })]),
+    phase("Apply", [shell("yodel apply prod --execute", { env: { YODEL_APPROVED_PLAN: digest }, timeout: "2h" })]),
+  ],
+});
+```
+
+`yodel apply prod` stops at the gate and prints `chant approve migrate-prod approve-migrate-prod --plan <digest>`; approve, then run it again. `yodel apply prod --plan` prints the pending migrations and the digest without applying. Running `chant run migrate-prod` directly needs `yodel` on PATH.
+
+## yodel lint
+
+`yodel lint` checks the migrations directory offline, with no server, so it runs in CI on every pull request. Every rule is free. Exit 0 when there is no error (warnings and silenced findings do not fail), 3 when there is at least one, 1 when lint cannot run; `--json` prints the findings.
+
+- Integrity, always errors: `fork` (two migrations follow the same parent; `yodel rebase`), `directory` (a bad name or file, a missing parent, a cycle, another dialect), `checksum` (a migration's files changed since it was written), `unreadable-object` (an object in a recorded schema, or a step, the sql lexicon cannot read or classify; never skipped).
+- From the classifier's classes: `destructive` (a drop), `pg-rewrite` (a rewrite or full scan under ACCESS EXCLUSIVE), `pg-lock` (writes blocked for a whole index build or scan: no `CONCURRENTLY`, a constraint validated in place), `ch-mutation` (a mutation rewriting parts), `ch-rebuild` (a `ClickHouseRebuildOp` step).
+- `refused-step` (a step `yodel apply` will not run), `migration-sql` (migration.sql does not hold a statement migration.json records), `silence` (a bad or unused `yodel:allow` line).
+
+A line above a statement in its `migration.sql` silences one of the classifier rules for that statement:
+
+```sql
+-- yodel:allow destructive the column was never read; checked in prod 2026-10-08
+ALTER TABLE `db`.`events` DROP COLUMN `legacy`;
+```
+
+The reason is required. `yodel apply` records each silence (step, rule, reason) in every history row the migration writes, in the `silences` column. The line changes the migration's checksum, so record the new one with `yodel lint --update-checksum <id>` while it is applied nowhere.
+
+`yodel lint --env <env>` also reads the environment's history: an applied migration whose files changed since it ran is a `checksum` error, a pending migration's edit a warning. `yodel.config.ts` sets rule levels: `lint: { rules: { "ch-mutation": "warning", "pg-lock": "off" } }`; the integrity rules cannot be lowered. `yodel lint --rules` lists the rules and their levels.
+
+`yodel lint --replay <env>` also replays every migration, in order, into `<env>`'s server (a throwaway emulator, `chant emulator up --lexicon sql`) and compares each with its recorded schema; the first that differs fails the run (rule `replay`, exit 3), named. The databases or schemas the history names must not exist there yet: otherwise it exits 4 and runs nothing, unless `--reset`, which drops them first (never point it at a server whose data matters). `--keep` leaves the replayed database in place to look at.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Published chant and its sql lexicon ship TypeScript source (their exports'
+// "default" condition is ./src/*.ts), and chant evaluates the project's
+// chant.config.ts and *.op.ts in this process. Register tsx's loader before
+// anything imports them, the way chant's own bin runs under tsx.
+import { register } from "tsx/esm/api";
+register();
+const { main } = await import("./cli.js");
+const code = await main(process.argv.slice(2), {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+});
+process.exitCode = code;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,6EAA6E;AAC7E,wEAAwE;AACxE,4EAA4E;AAC5E,iEAAiE;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,QAAQ,EAAE,CAAC;AACX,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAE1C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC7C,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IACzC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;CAC1C,CAAC,CAAC;AACH,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/dist/chant/apply.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Applying through the project's own `ApplyOp`: yodel finds the Op that
+ * applies the environment's build (`nativeApply` with `target: "clickhouse"`
+ * or `"postgres"` and that `env`), and runs it with `chant run`. The Op's
+ * gate is bound to its Plan phase's digest, so an approval given for one
+ * change set never applies another; yodel never resolves the gate itself.
+ * `chant approve <op> <gate> --plan <digest>` does, and the next run walks
+ * through it.
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import { type Environment, type Project, type SqlDialect } from "../project.js";
+/** The ApplyOp yodel runs for an environment. */
+export interface ApplyOpRef {
+    name: string;
+    filePath: string;
+    target: SqlDialect;
+    /** The gate step's name. */
+    gate: string;
+}
+/** How to declare the ApplyOp yodel looks for. */
+export declare function applyOpExample(env: string, dialect: SqlDialect): string;
+/**
+ * Picks the ApplyOp for `env` from discovered Ops. Pure: takes the Ops as
+ * `chant run` would discover them. `name` picks one when several apply the
+ * same environment. An Op without a plan-bound gate is refused.
+ */
+export declare function selectApplyOp(ops: ReadonlyMap<string, {
+    config: OpConfig;
+    filePath: string;
+}>, project: Project, env: Environment, name?: string): ApplyOpRef;
+/** Discovers the project's Ops the way `chant run` does and picks the ApplyOp for `env`. */
+export declare function findApplyOp(project: Project, env: Environment, name?: string): Promise<ApplyOpRef>;
+/** `chant run`'s exit code for a run that stopped at its gate. */
+export declare const GATED = 3;
+export type ApplyRunStatus = "applied" | "gated" | "failed";
+export interface ApplyRun {
+    status: ApplyRunStatus;
+    code: number;
+    /** The `chant approve ...` command chant printed for a gated run. */
+    approve?: string;
+    /** The plan digest the gate is waiting on. */
+    planDigest?: string;
+    output: string;
+}
+/** What a `chant run` of an ApplyOp says about its outcome. */
+export declare function readApplyRun(code: number, output: string): ApplyRun;
+/** Runs the ApplyOp with `chant run <op>`, its output passed to `onOutput` as it arrives. */
+export declare function runApplyOp(project: Project, op: ApplyOpRef, options?: {
+    env?: NodeJS.ProcessEnv;
+    onOutput?: (text: string) => void;
+}): Promise<ApplyRun>;

package/dist/chant/apply.js

@@ -0,0 +1,104 @@
+/**
+ * Applying through the project's own `ApplyOp`: yodel finds the Op that
+ * applies the environment's build (`nativeApply` with `target: "clickhouse"`
+ * or `"postgres"` and that `env`), and runs it with `chant run`. The Op's
+ * gate is bound to its Plan phase's digest, so an approval given for one
+ * change set never applies another; yodel never resolves the gate itself.
+ * `chant approve <op> <gate> --plan <digest>` does, and the next run walks
+ * through it.
+ */
+import { YodelError } from "../project.js";
+import { runChant } from "./process.js";
+const steps = (config) => config.phases.flatMap((p) => p.steps);
+/** The environment and target a `nativeApply` step applies, when the Op has one. */
+function nativeApplyOf(config) {
+    for (const step of steps(config)) {
+        if (step.kind === "activity" && step.fn === "nativeApply")
+            return step.args;
+    }
+    return undefined;
+}
+/** The gate the Op stops at, when it is bound to a plan (`plan` set, as ApplyOp sets it). */
+function planBoundGate(config) {
+    for (const step of steps(config)) {
+        if (step.kind === "gate" && step.plan !== undefined)
+            return step.gate;
+    }
+    return undefined;
+}
+/** How to declare the ApplyOp yodel looks for. */
+export function applyOpExample(env, dialect) {
+    return [
+        `// ops/apply-${env}.op.ts`,
+        `import { ApplyOp } from "@intentius/chant/op";`,
+        ``,
+        `export const { op } = ApplyOp({ name: "apply-${env}", env: "${env}", target: "${dialect}", gate: {} });`,
+    ].join("\n");
+}
+/**
+ * Picks the ApplyOp for `env` from discovered Ops. Pure: takes the Ops as
+ * `chant run` would discover them. `name` picks one when several apply the
+ * same environment. An Op without a plan-bound gate is refused.
+ */
+export function selectApplyOp(ops, project, env, name) {
+    const candidates = [...ops.values()].filter((o) => {
+        const apply = nativeApplyOf(o.config);
+        return apply?.env === env.name && (apply.target === "clickhouse" || apply.target === "postgres");
+    });
+    const chosen = name ? candidates.filter((o) => o.config.name === name) : candidates;
+    if (chosen.length === 0) {
+        if (name && ops.has(name))
+            throw new YodelError(`Op "${name}" is not an ApplyOp for environment ${env.name} with target clickhouse or postgres`);
+        throw new YodelError(name
+            ? `no Op named "${name}" in ${project.dir}`
+            : `no ApplyOp applies environment ${env.name} in ${project.dir}; declare one, for example:\n\n${applyOpExample(env.name, project.dialect)}`);
+    }
+    if (chosen.length > 1) {
+        throw new YodelError(`${String(chosen.length)} Ops apply environment ${env.name} (${chosen.map((o) => o.config.name).join(", ")}); pick one with --op <name>`);
+    }
+    const [op] = chosen;
+    const target = nativeApplyOf(op.config)?.target;
+    if (target !== project.dialect) {
+        throw new YodelError(`Op "${op.config.name}" applies target ${target}, but the project's dialect is ${project.dialect}`);
+    }
+    const gate = planBoundGate(op.config);
+    if (!gate) {
+        throw new YodelError(`Op "${op.config.name}" (${op.filePath}) has no approval gate bound to its plan, and yodel only applies behind one; ` +
+            `give the ApplyOp a gate (gate: {}) or delete: "gated"`);
+    }
+    return { name: op.config.name, filePath: op.filePath, target, gate };
+}
+/** Discovers the project's Ops the way `chant run` does and picks the ApplyOp for `env`. */
+export async function findApplyOp(project, env, name) {
+    const { discoverOps } = await import("@intentius/chant/op/discover");
+    let found;
+    try {
+        found = await discoverOps({ cwd: project.dir });
+    }
+    catch (e) {
+        throw new YodelError(`could not discover Ops in ${project.dir}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (found.errors.length > 0 && found.ops.size === 0) {
+        throw new YodelError(`could not discover Ops in ${project.dir}:\n${found.errors.join("\n")}`);
+    }
+    return selectApplyOp(found.ops, project, env, name);
+}
+/** `chant run`'s exit code for a run that stopped at its gate. */
+export const GATED = 3;
+/** What a `chant run` of an ApplyOp says about its outcome. */
+export function readApplyRun(code, output) {
+    const status = code === 0 ? "applied" : code === GATED ? "gated" : "failed";
+    const approve = /^\s*approve\s*:\s*(chant approve .+?)\s*$/m.exec(output)?.[1];
+    const planDigest = /^\s*plan\s*:\s*(\S+)\s*$/m.exec(output)?.[1];
+    return { status, code, ...(approve ? { approve } : {}), ...(planDigest ? { planDigest } : {}), output };
+}
+/** Runs the ApplyOp with `chant run <op>`, its output passed to `onOutput` as it arrives. */
+export async function runApplyOp(project, op, options = {}) {
+    const result = await runChant(["run", op.name, "--gated-exit", String(GATED)], {
+        cwd: project.dir,
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.onOutput ? { onStdout: options.onOutput, onStderr: options.onOutput } : {}),
+    });
+    return readApplyRun(result.code, `${result.stdout}\n${result.stderr}`);
+}
+//# sourceMappingURL=apply.js.map

package/dist/chant/apply.js.map

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

package/dist/chant/build.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Building the declared schema: `chant build <sourceDir> --lexicon sql`, the
+ * same build the project's ApplyOp runs, written to a file the planner reads.
+ */
+import { type Project, type SqlDialect } from "../project.js";
+/** One declared object as the sql lexicon's build output holds it. */
+export interface BuiltObject {
+    export: string;
+    type?: string;
+    ddl: string;
+    dependsOn?: string[];
+}
+/** The sql lexicon's build output (`dist/schema.json`). */
+export interface BuildOutput {
+    dialect: SqlDialect;
+    objects: BuiltObject[];
+    [key: string]: unknown;
+}
+export interface Build {
+    /** The build output file. */
+    path: string;
+    output: BuildOutput;
+    /** Removes the file and its directory, when yodel made them. */
+    dispose: () => void;
+}
+/**
+ * Builds the project's declared schema. Writes to `out` when given, else to
+ * a temporary directory that {@link Build.dispose} removes. A build that
+ * fails, or that holds another dialect than the project's, is an error.
+ */
+export declare function buildSchema(project: Project, options?: {
+    out?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<Build>;

package/dist/chant/build.js

@@ -0,0 +1,48 @@
+/**
+ * Building the declared schema: `chant build <sourceDir> --lexicon sql`, the
+ * same build the project's ApplyOp runs, written to a file the planner reads.
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { YodelError } from "../project.js";
+import { runChant } from "./process.js";
+/**
+ * Builds the project's declared schema. Writes to `out` when given, else to
+ * a temporary directory that {@link Build.dispose} removes. A build that
+ * fails, or that holds another dialect than the project's, is an error.
+ */
+export async function buildSchema(project, options = {}) {
+    const tmp = options.out ? undefined : mkdtempSync(join(tmpdir(), "yodel-build-"));
+    const path = options.out ?? join(tmp ?? ".", "schema.json");
+    const dispose = () => {
+        if (tmp)
+            rmSync(tmp, { recursive: true, force: true });
+    };
+    try {
+        const result = await runChant(["build", project.sourceDir, "--lexicon", "sql", "-o", path], {
+            cwd: project.dir,
+            ...(options.env ? { env: options.env } : {}),
+        });
+        if (result.code !== 0) {
+            const detail = (result.stderr || result.stdout).trim();
+            throw new YodelError(`chant build failed in ${project.dir}${detail ? `:\n${detail}` : ""}`);
+        }
+        let output;
+        try {
+            output = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            throw new YodelError(`chant build wrote no readable output at ${path}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (output.dialect !== project.dialect) {
+            throw new YodelError(`the build holds ${output.dialect} objects, but the project's dialect is ${project.dialect}`);
+        }
+        return { path, output, dispose };
+    }
+    catch (e) {
+        dispose();
+        throw e;
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/chant/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/chant/build.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAiC,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAyBxC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAgB,EAAE,UAAqD,EAAE;IACzG,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,GAAG,EAAE,aAAa,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,GAAG;YAAE,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE;YAC1F,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACvD,MAAM,IAAI,UAAU,CAAC,yBAAyB,OAAO,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,MAAmB,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACjE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAAC,2CAA2C,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzH,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;YACvC,MAAM,IAAI,UAAU,CAAC,mBAAmB,MAAM,CAAC,OAAO,0CAA0C,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACrH,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/chant/drift.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Drift: the declared objects whose live definition changed out of band, or
+ * that are gone from the server. Read from `chant lifecycle diff <env> --live
+ * --json`, the sql lexicon's section of it:
+ *
+ * - `deep.drifted[].changes[]`: a declared object whose live definition
+ *   differs, property by property, declared against live;
+ * - `resources.missing`: a declared object the server does not have;
+ * - `resources.unobserved` and `deep.unobserved`: a declared object chant
+ *   could not read (no credentials, a kind it cannot observe). Not drift, and
+ *   not clean either: that part of the environment is unknown.
+ *
+ * An object the project does not declare is never reported: chant only reads
+ * what the project declares, and only touches what carries its marker.
+ */
+import type { LiveDiffResult, UnobservedResource } from "@intentius/chant/lifecycle/live-diff";
+import type { DeepDiffResult, DeepEntityDrift } from "@intentius/chant/lifecycle/deep-diff";
+import { type Environment, type Project } from "../project.js";
+/** The `lexicons.sql` section of `chant lifecycle diff --live --json`. */
+export interface SqlLiveDiff {
+    resources?: LiveDiffResult;
+    deep?: DeepDiffResult;
+}
+export interface Drift {
+    environment: string;
+    /** Declared objects whose live definition differs from the declaration. */
+    changed: DeepEntityDrift[];
+    /** Declared objects the server does not have. */
+    missing: string[];
+    /** Declared objects chant could not read. */
+    unobserved: UnobservedResource[];
+}
+/** Exit code: an owned object changed or is gone. */
+export declare const DRIFTED = 2;
+/** `2` on drift; `1` when there is none but part of the environment could not be read; `0` when clean. */
+export declare function driftExitCode(drift: Drift): number;
+/** The drift in a parsed `chant lifecycle diff --live --json` document. */
+export declare function driftFromLifecycle(environment: string, doc: unknown): Drift;
+/** Runs `chant lifecycle diff <env> --live --json` in the project and reads the drift from it. */
+export declare function readDrift(project: Project, env: Environment, options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<Drift>;
+/** The drift as text. */
+export declare function renderDrift(drift: Drift): string;