@intentius/sql-yodeler 0.1.0 → 0.2.0

package/README.md

@@ -1,38 +1,36 @@
 # SQL Yodeler
 
-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.
+Schema management and migrations for ClickHouse and Postgres, on chant's `sql` lexicon.
 
-## 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).
+SQL Yodeler is built on [chant](https://www.npmjs.com/package/@intentius/chant), a declarative infrastructure-as-code toolkit in TypeScript. You need chant's CLI (`@intentius/chant` on npm) for three things only: `chant init` to make a project from a template, `chant approve` to approve a plan, and `chant emulator up` for a local database. Run it as `npx @intentius/chant@latest` before the project exists, and as `npx chant` inside it, where `npm install` put it.
 
-[`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.
+## Getting started
 
-## Starting a project
-
-`templates/clickhouse` and `templates/postgres` are starter projects for `chant init --from`:
+[Your first migration](docs/getting-started.md) goes from an empty directory to two applied migrations on a local ClickHouse, with every command and its output. In short:
 
 ```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
+npx @intentius/chant@latest init --from INTENTIUS/sql-yodeler@main#templates/clickhouse --param name=events-schema --param database=events my-schema
+cd my-schema && npm install && git init -b main && git add -A && git commit -m "chore: a new yodel project"
+npx chant emulator up --lexicon sql            # ClickHouse and Postgres in Docker
+export DEV_CLICKHOUSE_READER_USER=default DEV_CLICKHOUSE_READER_PASSWORD= DEV_CLICKHOUSE_WRITER_USER=default DEV_CLICKHOUSE_WRITER_PASSWORD=
+npx yodel new init && npx yodel lint
+git add -A && git commit -m "feat: the first migration"
+npx yodel apply dev                            # stops at the approval
+npx chant approve migrate-dev approve-migrate-dev --plan "$(npx yodel apply dev --digest)"
+npx yodel apply dev
 ```
 
-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.
+For Postgres, use `templates/postgres` with `--param name=app-schema --param schema=app`.
 
-## Development
+Each template 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.
 
-Node 22 (`.nvmrc`).
+## Documentation
 
-```sh
-npm ci
-npm run build
-npx yodel --help
-npm run check   # typecheck, lint and test
-```
+The documentation is at [intentius.io/sql-yodeler](https://intentius.io/sql-yodeler/), built from [`docs/`](docs/README.md): [installing](docs/configuration.md#installing) (`npm install @intentius/sql-yodeler`), [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).
 
-Working rules are in `AGENTS.md`.
+[`examples/clickhouse`](examples/clickhouse/README.md) and [`examples/postgres`](examples/postgres/README.md) are finished example projects, each with a transcript of a run against chant's emulator.
 
-## Versioned migrations (ClickHouse)
+## Versioned migrations
 
 `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).
 
@@ -63,7 +61,7 @@ export default defineConfig({
 
 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.
+The declarative path (no `migrations/`) plans and applies through chant, which reads `sql.profiles.<env>.topology` only, so a topology other than `single` 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).
 
@@ -87,7 +85,7 @@ export const op = Op({
 });
 ```
 
-`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 apply prod` stops at the gate and prints `chant approve migrate-prod approve-migrate-prod --plan <digest>`; approve (inside the project, `npx chant 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
 
@@ -108,4 +106,8 @@ The reason is required. `yodel apply` records each silence (step, rule, reason)
 
 `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.
+`yodel lint --replay <env>` also replays every migration, in order, into `<env>`'s server (a throwaway emulator, `npx 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.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers building SQL Yodeler from a clone, the checks, and the scenario claims.

package/dist/bin.js

@@ -6,9 +6,24 @@
 import { register } from "tsx/esm/api";
 register();
 const { main } = await import("./cli.js");
+const terminal = process.stdin.isTTY && process.stderr.isTTY;
 const code = await main(process.argv.slice(2), {
     out: (text) => process.stdout.write(text),
     err: (text) => process.stderr.write(text),
+    ...(terminal
+        ? {
+            ask: async (question) => {
+                const { createInterface } = await import("node:readline/promises");
+                const rl = createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    return await rl.question(question);
+                }
+                finally {
+                    rl.close();
+                }
+            },
+        }
+        : {}),
 });
 process.exitCode = code;
 //# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +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"}
+{"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,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;AAC7D,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;IACzC,GAAG,CAAC,QAAQ;QACV,CAAC,CAAC;YACE,GAAG,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;gBAC9B,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;gBACnE,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC7E,IAAI,CAAC;oBACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACrC,CAAC;wBAAS,CAAC;oBACT,EAAE,CAAC,KAAK,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;SACF;QACH,CAAC,CAAC,EAAE,CAAC;CACR,CAAC,CAAC;AACH,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/dist/chant/apply.d.ts

@@ -8,7 +8,7 @@
  * through it.
  */
 import type { OpConfig } from "@intentius/chant/op/types";
-import { type Environment, type Project, type SqlDialect } from "../project.js";
+import { YodelError, type Environment, type Project, type SqlDialect } from "../project.js";
 /** The ApplyOp yodel runs for an environment. */
 export interface ApplyOpRef {
     name: string;
@@ -28,6 +28,12 @@ export declare function selectApplyOp(ops: ReadonlyMap<string, {
     config: OpConfig;
     filePath: string;
 }>, project: Project, env: Environment, name?: string): ApplyOpRef;
+/**
+ * Why the project's Ops could not be found. chant discovers Ops through git
+ * (the files git knows), so a project that is not in a git repository has
+ * none; say so, and what to run (#19).
+ */
+export declare function discoveryError(dir: string, e: unknown): YodelError;
 /** 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. */
@@ -41,6 +47,8 @@ export interface ApplyRun {
     /** The plan digest the gate is waiting on. */
     planDigest?: string;
     output: string;
+    /** The exit code of the Op's Apply step (`yodel apply --execute`), when it ran. */
+    stepExit?: number;
 }
 /** What a `chant run` of an ApplyOp says about its outcome. */
 export declare function readApplyRun(code: number, output: string): ApplyRun;

package/dist/chant/apply.js

@@ -68,6 +68,18 @@ export function selectApplyOp(ops, project, env, name) {
     }
     return { name: op.config.name, filePath: op.filePath, target, gate };
 }
+/**
+ * Why the project's Ops could not be found. chant discovers Ops through git
+ * (the files git knows), so a project that is not in a git repository has
+ * none; say so, and what to run (#19).
+ */
+export function discoveryError(dir, e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (/not in a git repository|not a git repository/i.test(message)) {
+        return new YodelError(`yodel apply finds the project's Ops through git, and ${dir} is not in a git repository: run git init, then commit the project (git add -A && git commit -m init)`);
+    }
+    return new YodelError(`could not discover Ops in ${dir}: ${message}`);
+}
 /** 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");
@@ -76,7 +88,7 @@ export async function findApplyOp(project, env, name) {
         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)}`);
+        throw discoveryError(project.dir, 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")}`);

package/dist/chant/apply.js.map

@@ -1 +1 @@
-{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/chant/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAmD,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAWxC,MAAM,KAAK,GAAG,CAAC,MAAgB,EAAoB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE5F,oFAAoF;AACpF,SAAS,aAAa,CAAC,MAAgB;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,EAAE,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC9E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,6FAA6F;AAC7F,SAAS,aAAa,CAAC,MAAgB;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,OAAmB;IAC7D,OAAO;QACL,gBAAgB,GAAG,QAAQ;QAC3B,gDAAgD;QAChD,EAAE;QACF,gDAAgD,GAAG,YAAY,GAAG,eAAe,OAAO,iBAAiB;KAC1G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAgE,EAChE,OAAgB,EAChB,GAAgB,EAChB,IAAa;IAEb,MAAM,UAAU,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAChD,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,YAAY,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IACnG,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IACpF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,IAAI,IAAI,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,OAAO,IAAI,uCAAuC,GAAG,CAAC,IAAI,qCAAqC,CAAC,CAAC;QACjJ,MAAM,IAAI,UAAU,CAClB,IAAI;YACF,CAAC,CAAC,gBAAgB,IAAI,QAAQ,OAAO,CAAC,GAAG,EAAE;YAC3C,CAAC,CAAC,kCAAkC,GAAG,CAAC,IAAI,OAAO,OAAO,CAAC,GAAG,kCAAkC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAC9I,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,0BAA0B,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IACjK,CAAC;IACD,MAAM,CAAC,EAAE,CAAC,GAAG,MAAmC,CAAC;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,MAAoB,CAAC;IAC9D,IAAI,MAAM,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,oBAAoB,MAAM,kCAAkC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3H,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,UAAU,CAClB,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC,QAAQ,+EAA+E;YACnH,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAgB,EAAE,GAAgB,EAAE,IAAa;IACjF,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC;IACrE,IAAI,KAA8C,CAAC;IACnD,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,WAAW,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,6BAA6B,OAAO,CAAC,GAAG,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,UAAU,CAAC,6BAA6B,OAAO,CAAC,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC;AAcvB,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,MAAc;IACvD,MAAM,MAAM,GAAmB,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5F,MAAM,OAAO,GAAG,4CAA4C,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,UAAU,GAAG,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAC1G,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAgB,EAAE,EAAc,EAAE,UAA0E,EAAE;IAC7I,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE;QAC7E,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxF,CAAC,CAAC;IACH,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AACzE,CAAC"}
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/chant/apply.ts"],"names":[],"mappings":"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"}

package/dist/chant/drift.d.ts

@@ -16,6 +16,8 @@
 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";
+import { type ServerInfo } from "../server.js";
+import type { BuildOutput } from "./build.js";
 /** The `lexicons.sql` section of `chant lifecycle diff --live --json`. */
 export interface SqlLiveDiff {
     resources?: LiveDiffResult;
@@ -29,7 +31,44 @@ export interface Drift {
     missing: string[];
     /** Declared objects chant could not read. */
     unobserved: UnobservedResource[];
+    /** Postgres: a read gave up at the lock timeout, and what it waited on (#18). */
+    lockWait?: string | undefined;
+    /** Each changed table's declared column names, by position, so `columns[3]` reads as the column's name (#19). */
+    columns?: Record<string, string[]>;
+    /** What the server was compared with (#49): `src/`, or the schema the newest applied migration records. */
+    against?: DriftAgainst;
 }
+/**
+ * The declaration drift compares the server with: the project's `src/`,
+ * or the recorded schema of the newest migration the environment's history
+ * records as applied (`migration` null when none is applied yet).
+ */
+export type DriftAgainst = {
+    source: "src";
+} | {
+    source: "history";
+    migration: string | null;
+};
+/**
+ * A stable fingerprint of the drift: the environment and what drifted
+ * (each changed object's changes, declared and live, and the objects gone),
+ * order-free, so two reads of the same drift give the same one and a
+ * tracking issue updated with it changes only when the drift does. Objects
+ * that could not be read are not drift and are left out.
+ */
+export declare function driftFingerprint(drift: Drift): string;
+/**
+ * The recorded schema as declarations chant can build: one file, written
+ * by the sql lexicon's import generator from each object's DDL, each named
+ * by its export as the build named it. Written under the project directory,
+ * so the generated imports resolve from the project's node_modules, in a
+ * directory {@link RecordedSource.dispose} removes.
+ */
+export interface RecordedSource {
+    dir: string;
+    dispose: () => void;
+}
+export declare function writeRecordedSource(projectDir: string, schema: BuildOutput): Promise<RecordedSource>;
 /** 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. */
@@ -39,6 +78,35 @@ export declare function driftFromLifecycle(environment: string, doc: unknown): D
 /** 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;
+    src?: string;
 }): Promise<Drift>;
+/**
+ * The declared column names of each changed object whose drift is named by
+ * column position (chant's ClickHouse tables keep columns as a list, so a
+ * change reads `columns[3].default.expr`). Read from the project's build,
+ * with the dialect's own tag, the way chant reads the declaration.
+ */
+export declare function declaredColumns(project: Project, drift: Drift, build: () => Promise<{
+    output: {
+        objects: Array<{
+            export: string;
+            ddl: string;
+        }>;
+    };
+    dispose: () => void;
+}>): Promise<Record<string, string[]>>;
+/** `columns[3].default.expr` as `column country: default.expr`, when the declaration names column 3. */
+export declare function describePath(path: string, columns: readonly string[] | undefined): string;
+/** What the server was compared with, in words. */
+export declare function describeAgainst(against: DriftAgainst | undefined): string | undefined;
 /** The drift as text. */
-export declare function renderDrift(drift: Drift): string;
+export declare function renderDrift(drift: Drift, server?: ServerInfo): string;
+/**
+ * The drift as markdown, for the tracking issue: the environment and
+ * server, what it was compared with, each changed object with its changes,
+ * the objects gone, the run that found it, and the fingerprint.
+ */
+export declare function renderDriftMarkdown(drift: Drift, server: ServerInfo | undefined, extra: {
+    fingerprint: string;
+    run?: string;
+}): string;

package/dist/chant/drift.js

@@ -13,8 +13,54 @@
  * 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 { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { YodelError } from "../project.js";
 import { lastJsonLine, runChant } from "./process.js";
+import { describeServer } from "../server.js";
+/**
+ * A stable fingerprint of the drift: the environment and what drifted
+ * (each changed object's changes, declared and live, and the objects gone),
+ * order-free, so two reads of the same drift give the same one and a
+ * tracking issue updated with it changes only when the drift does. Objects
+ * that could not be read are not drift and are left out.
+ */
+export function driftFingerprint(drift) {
+    const changed = drift.changed
+        .map((e) => ({
+        name: e.name,
+        type: e.type,
+        changes: e.changes.map((c) => ({ path: c.path, kind: c.kind, declared: c.declared ?? null, live: c.live ?? null })).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const subject = JSON.stringify({ environment: drift.environment, changed, missing: [...drift.missing].sort() });
+    return `sha256:${createHash("sha256").update(subject, "utf8").digest("hex")}`;
+}
+export async function writeRecordedSource(projectDir, schema) {
+    const { sqlTemplateGenerator } = await import("@intentius/chant-lexicon-sql/import-generator");
+    const resources = schema.objects.map((o) => {
+        const own = o;
+        const where = typeof own.database === "string" ? { database: own.database } : typeof own.schema === "string" ? { schema: own.schema } : {};
+        return { type: o.type ?? "", logicalId: o.export, properties: { ...where, name: typeof own.name === "string" ? own.name : o.export, ddl: o.ddl } };
+    });
+    const dir = mkdtempSync(join(projectDir, ".yodel-recorded-"));
+    const dispose = () => {
+        rmSync(dir, { recursive: true, force: true });
+    };
+    try {
+        for (const f of resources.length === 0 ? [] : sqlTemplateGenerator.generate({ resources, parameters: [] })) {
+            const path = join(dir, f.path);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, f.content);
+        }
+    }
+    catch (e) {
+        dispose();
+        throw new YodelError(`the recorded schema could not be written as declarations: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { dir, dispose };
+}
 /** Exit code: an owned object changed or is gone. */
 export const DRIFTED = 2;
 /** `2` on drift; `1` when there is none but part of the environment could not be read; `0` when clean. */
@@ -47,7 +93,7 @@ export function driftFromLifecycle(environment, doc) {
 }
 /** Runs `chant lifecycle diff <env> --live --json` in the project and reads the drift from it. */
 export async function readDrift(project, env, options = {}) {
-    const result = await runChant(["lifecycle", "diff", env.name, "--live", "--json"], {
+    const result = await runChant(["lifecycle", "diff", env.name, "--live", "--json", ...(options.src ? ["--src", options.src] : [])], {
         cwd: project.dir,
         ...(options.env ? { env: options.env } : {}),
     });
@@ -58,19 +104,78 @@ export async function readDrift(project, env, options = {}) {
     }
     return driftFromLifecycle(env.name, doc);
 }
+const COLUMN_PATH = /^columns\[(\d+)\]/;
+/**
+ * The declared column names of each changed object whose drift is named by
+ * column position (chant's ClickHouse tables keep columns as a list, so a
+ * change reads `columns[3].default.expr`). Read from the project's build,
+ * with the dialect's own tag, the way chant reads the declaration.
+ */
+export async function declaredColumns(project, drift, build) {
+    const wanted = new Set(drift.changed.filter((e) => e.changes.some((c) => COLUMN_PATH.test(c.path))).map((e) => e.name));
+    if (wanted.size === 0)
+        return {};
+    const b = await build();
+    try {
+        const tag = project.dialect === "postgres"
+            ? (await import("@intentius/chant-lexicon-sql/postgres/entities")).table
+            : (await import("@intentius/chant-lexicon-sql/clickhouse/entities")).table;
+        const out = {};
+        for (const o of b.output.objects) {
+            if (!wanted.has(o.export))
+                continue;
+            try {
+                const strings = Object.assign([o.ddl], { raw: [o.ddl] });
+                const columns = tag(strings).props.columns;
+                if (Array.isArray(columns))
+                    out[o.export] = columns.map((c) => { const n = c.name; return typeof n === "string" ? n : ""; });
+            }
+            catch {
+                // Not a table this tag reads: its paths stay as chant gives them.
+            }
+        }
+        return out;
+    }
+    finally {
+        b.dispose();
+    }
+}
+/** `columns[3].default.expr` as `column country: default.expr`, when the declaration names column 3. */
+export function describePath(path, columns) {
+    const m = COLUMN_PATH.exec(path);
+    const name = m && columns ? columns[Number(m[1])] : undefined;
+    if (!m || !name)
+        return path;
+    const rest = path.slice(m[0].length).replace(/^\./, "");
+    return `column ${name}${rest ? ` ${rest}` : ""}`;
+}
 const show = (v) => (v === undefined ? "(none)" : typeof v === "string" ? v : JSON.stringify(v));
+/** What the server was compared with, in words. */
+export function describeAgainst(against) {
+    if (!against)
+        return undefined;
+    if (against.source === "src")
+        return "Compared with the declared schema in src/.";
+    return against.migration
+        ? `Compared with the schema ${against.migration} records, the newest migration the history records as applied.`
+        : "No migration is applied yet, so the history records no schema to compare with.";
+}
 /** The drift as text. */
-export function renderDrift(drift) {
-    const lines = [`Drift in ${drift.environment}`, ""];
+export function renderDrift(drift, server) {
+    const lines = [`Drift in ${drift.environment}${server ? ` (${describeServer(server)})` : ""}`, ""];
+    const against = describeAgainst(drift.against);
+    if (against)
+        lines.push(against, "");
     if (drift.changed.length === 0 && drift.missing.length === 0) {
-        lines.push("No drift: every declared object matches the server.");
+        lines.push(drift.unobserved.length > 0 ? "No drift in the declared objects that could be read." : "No drift: every declared object matches the server.");
     }
     if (drift.changed.length > 0) {
         lines.push("Changed out of band:");
         for (const e of drift.changed) {
             lines.push(`  ${e.name} (${e.type})`);
             for (const c of e.changes) {
-                lines.push(c.kind === "absent" ? `    ${c.path}: declared ${show(c.declared)}, absent live` : `    ${c.path}: declared ${show(c.declared)}, live ${show(c.live)}`);
+                const path = describePath(c.path, drift.columns?.[e.name]);
+                lines.push(c.kind === "absent" ? `    ${path}: declared ${show(c.declared)}, absent live` : `    ${path}: declared ${show(c.declared)}, live ${show(c.live)}`);
             }
         }
     }
@@ -85,7 +190,49 @@ export function renderDrift(drift) {
         lines.push("", "Could not be read, so their state is unknown:");
         for (const u of drift.unobserved)
             lines.push(`  ${u.name}: ${u.reason}${u.detail ? ` (${u.detail})` : ""}`);
+        if (drift.lockWait)
+            lines.push("", `The read ${drift.lockWait}.`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+const code = (v) => `\`${show(v).replace(/`/g, "'")}\``;
+/**
+ * The drift as markdown, for the tracking issue: the environment and
+ * server, what it was compared with, each changed object with its changes,
+ * the objects gone, the run that found it, and the fingerprint.
+ */
+export function renderDriftMarkdown(drift, server, extra) {
+    const lines = [`**${drift.environment}**${server ? ` (${describeServer(server)})` : ""} has drifted: declared objects were changed out of band, or are gone.`, ""];
+    const against = describeAgainst(drift.against);
+    if (against)
+        lines.push(against, "");
+    if (drift.changed.length > 0) {
+        lines.push("Changed out of band:", "");
+        for (const e of drift.changed) {
+            lines.push(`- \`${e.name}\` (${e.type})`);
+            for (const c of e.changes) {
+                const path = describePath(c.path, drift.columns?.[e.name]);
+                lines.push(c.kind === "absent" ? `  - ${path}: declared ${code(c.declared)}, absent live` : `  - ${path}: declared ${code(c.declared)}, live ${code(c.live)}`);
+            }
+        }
+        lines.push("");
+    }
+    if (drift.missing.length > 0) {
+        lines.push("Gone (declared, not on the server):", "");
+        for (const name of drift.missing)
+            lines.push(`- \`${name}\``);
+        lines.push("");
+    }
+    if (drift.unobserved.length > 0) {
+        lines.push("Could not be read, so their state is unknown:", "");
+        for (const u of drift.unobserved)
+            lines.push(`- \`${u.name}\`: ${u.reason}`);
+        lines.push("");
     }
+    lines.push(`Run \`yodel drift ${drift.environment}\` to see it again. yodel closes this issue when the drift is gone.`);
+    if (extra.run)
+        lines.push("", `Found by ${extra.run}`);
+    lines.push("", `<sub>drift fingerprint ${extra.fingerprint}</sub>`);
     return `${lines.join("\n")}\n`;
 }
 //# sourceMappingURL=drift.js.map

package/dist/chant/drift.js.map

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

package/dist/chant/runnable.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Commands yodel prints for a person to run (#14): `chant approve ...`,
+ * `yodel apply ...`. In a project that installs chant and yodel locally,
+ * neither is on PATH, only in node_modules/.bin, so a printed `chant approve`
+ * fails with "command not found". Such a command is printed as `npx chant
+ * ...` instead, which runs the project's own copy. When the tool is on PATH,
+ * or the project does not install it (where `npx` would fetch an unrelated
+ * package of that name), the command is printed as it is.
+ */
+/**
+ * Whether `name` is an executable on `PATH`, not counting `node_modules/.bin`
+ * directories: `npx yodel` puts the project's on yodel's PATH, but the
+ * person's shell does not have it.
+ */
+export declare function onPath(name: string, env?: NodeJS.ProcessEnv): boolean;
+/** Whether `dir` or a directory above it has `node_modules/.bin/<name>`. */
+export declare function installedLocally(name: string, dir: string): boolean;
+/** `command` as a person can run it in `projectDir`: prefixed with `npx ` when its tool is installed there but not on PATH. */
+export declare function runnable(command: string, projectDir: string, env?: NodeJS.ProcessEnv): string;

package/dist/chant/runnable.js

@@ -0,0 +1,47 @@
+/**
+ * Commands yodel prints for a person to run (#14): `chant approve ...`,
+ * `yodel apply ...`. In a project that installs chant and yodel locally,
+ * neither is on PATH, only in node_modules/.bin, so a printed `chant approve`
+ * fails with "command not found". Such a command is printed as `npx chant
+ * ...` instead, which runs the project's own copy. When the tool is on PATH,
+ * or the project does not install it (where `npx` would fetch an unrelated
+ * package of that name), the command is printed as it is.
+ */
+import { accessSync, constants } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+const executable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether `name` is an executable on `PATH`, not counting `node_modules/.bin`
+ * directories: `npx yodel` puts the project's on yodel's PATH, but the
+ * person's shell does not have it.
+ */
+export function onPath(name, env = process.env) {
+    return (env.PATH ?? "")
+        .split(delimiter)
+        .some((d) => d !== "" && !/[\\/]node_modules[\\/]\.bin[\\/]?$/.test(d) && executable(join(d, name)));
+}
+/** Whether `dir` or a directory above it has `node_modules/.bin/<name>`. */
+export function installedLocally(name, dir) {
+    for (let d = dir;; d = dirname(d)) {
+        if (executable(join(d, "node_modules", ".bin", name)))
+            return true;
+        if (dirname(d) === d)
+            return false;
+    }
+}
+/** `command` as a person can run it in `projectDir`: prefixed with `npx ` when its tool is installed there but not on PATH. */
+export function runnable(command, projectDir, env = process.env) {
+    const tool = command.split(" ", 1)[0] ?? "";
+    if (tool === "" || tool === "npx" || onPath(tool, env) || !installedLocally(tool, projectDir))
+        return command;
+    return `npx ${command}`;
+}
+//# sourceMappingURL=runnable.js.map

package/dist/chant/runnable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.js","sourceRoot":"","sources":["../../src/chant/runnable.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,UAAU,GAAG,CAAC,IAAY,EAAW,EAAE;IAC3C,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IACvE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;SACpB,KAAK,CAAC,SAAS,CAAC;SAChB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,oCAAoC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACzG,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAW;IACxD,KAAK,IAAI,CAAC,GAAG,GAAG,GAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACnE,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IACrC,CAAC;AACH,CAAC;AAED,+HAA+H;AAC/H,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,UAAkB,EAAE,MAAyB,OAAO,CAAC,GAAG;IAChG,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC;QAAE,OAAO,OAAO,CAAC;IAC9G,OAAO,OAAO,OAAO,EAAE,CAAC;AAC1B,CAAC"}

package/dist/cli.d.ts

@@ -1,4 +1,8 @@
 import type { Command, Io } from "./command.js";
+/** Where the docs are published from docs/. */
+export declare const DOCS_URL = "https://intentius.io/sql-yodeler/";
 export declare function help(list?: readonly Command[]): string;
+/** Wraps `line` at 80 columns, continuing with `indent`. */
+export declare function wrap(line: string, indent: string, width?: number): string;
 /** Parses argv (without the node and script paths) and runs a verb; resolves to the exit code. */
 export declare function main(argv: string[], io: Io, list?: readonly Command[]): Promise<number>;