@hyperfixation/cli 0.1.6 → 0.1.7

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
-export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up", "deploy", "doctor", "restore-check"];
+export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up", "deploy", "doctor", "restore-check", "version"];
 export type Command = (typeof COMMANDS)[number];
-export declare const USAGE = "hf \u2014 the hyperfixation CLI\n\n  hf new <name>             provision the app in the cloud: fetch the template, push a private\n                            repo, register a backup, Sentry, Langfuse and DNS, create the\n                            database and its roles, create the Coolify application and its\n                            environment, deploy, and print what is left to do by hand.\n                            Resumable \u2014 a rerun repeats only what did not finish\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <specifier>      template to fetch (default: gh:grahamlutz/hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n\n  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and\n                            prompt for the bootstrap admin's email\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n      --email <address>       the bootstrap admin's address; skips the prompt\n\n  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev \u2014\n                            the whole local loop after hf new, safe to rerun; seeds a $10\n                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env\n\n  hf migrate                create the application role, then run the app's migrate.ts\n      --skip-roles            the cloud path, where the roles already exist\n\n  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state\n      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL\n      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD\n\n  hf status-token           provision /api/status's read and write tokens\n      --read                   only the read token; refuses if it is already set\n      --write                  only the write token; refuses if it is already set\n      --rotate                 replace a token that is already set\n                               (no flags: fills in whichever of the two is unset)\n\n  hf check                  declared env, pending migrations, and E001-E006\n\n  hf deploy <name>          set SOURCE_COMMIT to a commit, deploy it, and wait until /api/status\n                            reports it. Coolify's push auto-deploy is off, so this is what\n                            publishes a merge to main\n      --sha <sha>             the commit to deploy (default: main's, via git ls-remote)\n\n  hf doctor [name]          every deployed app in the state cache, or one: /api/status under its\n                            read token, the deployed version against main, E006 as the app role,\n                            the last restore check, and open core-bump PRs. Exits 1 on any finding\n\n  hf gen [generator]        the app's turbo generators\n\n  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>\n      --no-compose            leave the dev infrastructure alone\n      --compose-only          bring the infrastructure up and stop\n\n  hf restore-check <name>   restore the newest hf_<name> dump beside the live database and\n                            compare row counts; exits 1 on any mismatch\n      --backup-dir <dir>      where the dumps are (default: Coolify's on the box)\n      --from-s3               read the dump from object storage (not implemented)\n\nEvery command but `new`, `deploy`, `doctor` and `restore-check` runs against the app at or above the working directory, or --dir.\n";
+export declare const USAGE = "hf \u2014 the hyperfixation CLI\n\n  hf new <name>             provision the app in the cloud: fetch the template, push a private\n                            repo, register a backup, Sentry, Langfuse and DNS, create the\n                            database and its roles, create the Coolify application and its\n                            environment, deploy, and print what is left to do by hand.\n                            Resumable \u2014 a rerun repeats only what did not finish\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <specifier>      template to fetch (default: gh:grahamlutz/hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n\n  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and\n                            write both bootstrap answers into its .env\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n\n  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev \u2014\n                            the whole local loop after hf new, safe to rerun; seeds a $10\n                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env\n\n  hf migrate                create the application role, then run the app's migrate.ts\n      --skip-roles            the cloud path, where the roles already exist\n\n  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state\n      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL\n      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD\n\n  hf status-token           provision /api/status's read and write tokens\n      --read                   only the read token; refuses if it is already set\n      --write                  only the write token; refuses if it is already set\n      --rotate                 replace a token that is already set\n                               (no flags: fills in whichever of the two is unset)\n\n  hf check                  declared env, pending migrations, and E001-E006\n\n  hf deploy <name>          set SOURCE_COMMIT to a commit, deploy it, and wait until /api/status\n                            reports it. Coolify's push auto-deploy is off, so this is what\n                            publishes a merge to main\n      --sha <sha>             the commit to deploy (default: main's, via git ls-remote)\n\n  hf doctor [name]          every deployed app in the state cache, or one: /api/status under its\n                            read token, the deployed version against main, E006 as the app role,\n                            the box's connection slots, the worker's advisory lock, the last\n                            restore check, and open core-bump PRs. Exits 1 on any finding\n\n  hf gen [generator]        the app's turbo generators\n\n  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>\n      --no-compose            leave the dev infrastructure alone\n      --compose-only          bring the infrastructure up and stop\n\n  hf restore-check <name>   restore the newest hf_<name> dump beside the live database and\n                            compare row counts. An append-only table the live side has moved\n                            on from reads ok (drift +N); exits 1 on any mismatch, and on a\n                            dump older than 24 h\n      --backup-dir <dir>      where the dumps are (default: Coolify's on the box)\n      --from-s3               read the dump from object storage (not implemented)\n      --strict                compare every table exactly; no table may drift\n\n  hf version                the @hyperfixation/cli version behind this hf, also as --version, -v\n\nEvery command but `new`, `deploy`, `doctor` and `restore-check` runs against the app at or above the working directory, or --dir.\n";
 export interface Io {
     out(line: string): void;
     err(line: string): void;

package/dist/cli.js

@@ -12,6 +12,7 @@ import { formatRestoreCheck, restoreCheckApp } from "./restore-check.js";
 import { statusTokenApp } from "./status-token.js";
 import { requireTemplateSource } from "./template-source.js";
 import { DEV_BUDGET_USD, upApp } from "./up.js";
+import { cliVersion } from "./version.js";
 export const COMMANDS = [
     "new",
     "migrate",
@@ -24,6 +25,7 @@ export const COMMANDS = [
     "deploy",
     "doctor",
     "restore-check",
+    "version",
 ];
 export const USAGE = `hf — the hyperfixation CLI
 
@@ -38,10 +40,11 @@ export const USAGE = `hf — the hyperfixation CLI
       --into <dir>            where to create <name> (default: the working directory)
 
   hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and
-                            prompt for the bootstrap admin's email
+                            write both bootstrap answers into its .env
+      --budget-usd <amount>   the app's monthly LLM budget (required; no default)
+      --email <address>       the bootstrap admin's address (required)
       --from <dir>            template checkout (default: the sibling hyperfixation-template)
       --into <dir>            where to create <name> (default: the working directory)
-      --email <address>       the bootstrap admin's address; skips the prompt
 
   hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev —
                             the whole local loop after hf new, safe to rerun; seeds a $10
@@ -69,7 +72,8 @@ export const USAGE = `hf — the hyperfixation CLI
 
   hf doctor [name]          every deployed app in the state cache, or one: /api/status under its
                             read token, the deployed version against main, E006 as the app role,
-                            the last restore check, and open core-bump PRs. Exits 1 on any finding
+                            the box's connection slots, the worker's advisory lock, the last
+                            restore check, and open core-bump PRs. Exits 1 on any finding
 
   hf gen [generator]        the app's turbo generators
 
@@ -78,9 +82,14 @@ export const USAGE = `hf — the hyperfixation CLI
       --compose-only          bring the infrastructure up and stop
 
   hf restore-check <name>   restore the newest hf_<name> dump beside the live database and
-                            compare row counts; exits 1 on any mismatch
+                            compare row counts. An append-only table the live side has moved
+                            on from reads ok (drift +N); exits 1 on any mismatch, and on a
+                            dump older than 24 h
       --backup-dir <dir>      where the dumps are (default: Coolify's on the box)
       --from-s3               read the dump from object storage (not implemented)
+      --strict                compare every table exactly; no table may drift
+
+  hf version                the @hyperfixation/cli version behind this hf, also as --version, -v
 
 Every command but \`new\`, \`deploy\`, \`doctor\` and \`restore-check\` runs against the app at or above the working directory, or --dir.
 `;
@@ -101,6 +110,10 @@ export async function main(argv, io = consoleIo) {
         io.out(USAGE);
         return command === undefined ? 1 : 0;
     }
+    if (command === "--version" || command === "-v") {
+        io.out(await cliVersion());
+        return 0;
+    }
     if (!COMMANDS.includes(command)) {
         io.err(`unknown command ${JSON.stringify(command)}`);
         io.err(USAGE);
@@ -138,6 +151,9 @@ async function dispatch(command, argv, io) {
             return await commandDoctor(argv, io);
         case "restore-check":
             return await commandRestoreCheck(argv, io);
+        case "version":
+            io.out(await cliVersion());
+            return 0;
     }
 }
 async function commandNew(argv, io) {
@@ -160,6 +176,15 @@ async function commandNew(argv, io) {
     if (!values.local) {
         return await commandNewCloud(name, values, io);
     }
+    // Refused here rather than prompted for: `hf up` reads both out of the app's `.env`, so a
+    // local app started without them is the same half-answered app the cloud path has refused
+    // since Phase 3 — one that either cannot spend or cannot stop.
+    const missing = missingBootstrapFlags(values);
+    if (missing.length > 0) {
+        io.err(`hf new ${name} --local needs ${missing.join(" and ")}: hf up reads both from the app's ` +
+            ".env and neither has a default.");
+        return 1;
+    }
     const from = values.from ?? (await requireTemplateSource());
     const result = await newApp({
         name,
@@ -167,29 +192,35 @@ async function commandNew(argv, io) {
         into: values.into,
         local: values.local,
         email: values.email,
+        budgetUsd: values["budget-usd"],
     });
     io.out(`created ${result.dir} from ${from}`);
     io.out(`  app ${result.appName}, database ${result.databaseName}`);
     io.out(`  ${result.substituted.length} file(s) substituted` +
         (result.wroteEnv ? ", .env written from .env.example" : "") +
-        (result.wroteBootstrapEmail ? ", HF_BOOTSTRAP_EMAIL set" : ""));
+        (result.wroteBootstrapEmail ? ", HF_BOOTSTRAP_EMAIL set" : "") +
+        (result.wroteBootstrapBudget ? ", HF_BOOTSTRAP_BUDGET_USD set" : ""));
     io.out("");
     io.out(`next: cd ${result.given} && hf up`);
     return 0;
 }
 /**
- * The cloud half: both inputs it cannot invent are refused up front.
+ * The two answers `hf new` cannot invent, named in the order the usage lists them.
  *
- * Neither has a default. `--email` designates the one admin an app is ever granted without an
- * admin behind it, and a budget nobody chose is a deployed app that either cannot spend or
- * cannot stop — `hf bootstrap` has refused an unset one since Phase 1, and this is the same rule
- * one command earlier, where the answer costs nothing yet.
+ * `--email` designates the one admin an app is ever granted without an admin behind it, and a
+ * budget nobody chose is an app that either cannot spend or cannot stop — `hf bootstrap` has
+ * refused an unset one since Phase 1, and this is the same rule one command earlier, where the
+ * answer costs nothing yet.
  */
-async function commandNewCloud(name, values, io) {
-    const missing = [
+function missingBootstrapFlags(values) {
+    return [
         ...(values["budget-usd"] === undefined ? ["--budget-usd <amount>"] : []),
         ...(values.email === undefined ? ["--email <address>"] : []),
     ];
+}
+/** The cloud half: both inputs are refused up front, with nowhere else to carry them. */
+async function commandNewCloud(name, values, io) {
+    const missing = missingBootstrapFlags(values);
     if (missing.length > 0) {
         io.err(`hf new ${name} needs ${missing.join(" and ")}: a cloud app has no prompt and no .env to ` +
             "carry either. Pass --local for Phase 1's local copy.");
@@ -342,6 +373,7 @@ async function commandRestoreCheck(argv, io) {
         options: {
             "backup-dir": { type: "string" },
             "from-s3": { type: "boolean", default: false },
+            strict: { type: "boolean", default: false },
         },
         allowPositionals: true,
     });
@@ -354,6 +386,7 @@ async function commandRestoreCheck(argv, io) {
         app: name,
         backupDir: values["backup-dir"],
         fromS3: values["from-s3"],
+        strict: values.strict,
     });
     for (const line of formatRestoreCheck(result))
         io.out(line);

package/dist/cloud-steps/template.d.ts

@@ -1,12 +1,7 @@
 import type { Step } from "../new-cloud.js";
+import { templateTempDir } from "../new.js";
 import { type CloudStepContext } from "./context.js";
-/**
- * Where the fetch lands before it becomes the app.
- *
- * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
- * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
- */
-export declare function templateTempDir(dir: string): string;
+export { templateTempDir };
 /**
  * The app's files: giget's fetch of the template, substituted, renamed into place.
  *

package/dist/cloud-steps/template.js

@@ -1,16 +1,8 @@
 import { readFile, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import { substituteTree, TEMPLATE_MARKER, TemplateError } from "../new.js";
+import { scratchInTheWay, substituteTree, targetInTheWay, templateTempDir, TEMPLATE_MARKER, TemplateError, } from "../new.js";
 import { exists } from "./context.js";
-/**
- * Where the fetch lands before it becomes the app.
- *
- * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
- * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
- */
-export function templateTempDir(dir) {
-    return path.join(path.dirname(dir), `.${path.basename(dir)}.hf-new`);
-}
+export { templateTempDir };
 /**
  * The app's files: giget's fetch of the template, substituted, renamed into place.
  *
@@ -32,7 +24,15 @@ export const templateStep = {
             return;
         }
         const temp = templateTempDir(dir);
-        await rm(temp, { recursive: true, force: true });
+        if (await exists(temp)) {
+            // Cleared only on a resume, by the same rule the target directory gets: `fetchStartedAt`
+            // says a run of *this* app fetched into that path, and without it the directory is someone
+            // else's however much its name looks like ours.
+            if (context.state.state.templateFetchStartedAt === undefined)
+                throw scratchInTheWay(temp);
+            await rm(temp, { recursive: true, force: true });
+        }
+        await context.state.patch({ templateFetchStartedAt: new Date(context.now()).toISOString() });
         const fetched = await context.fetchTemplate(context.from, temp);
         await substituteTree(fetched, names);
         // The marker is what `assertTemplateSource` looks for: an app is never a template twice.
@@ -66,7 +66,7 @@ async function adoptOrRefuse(context) {
     }
     const substituted = !(await exists(path.join(dir, TEMPLATE_MARKER))) && (await packageName(dir)) === names.appName;
     if (!substituted) {
-        throw new TemplateError(`${dir} already exists; hf new will not write into it`);
+        throw targetInTheWay(dir);
     }
     context.io.out(`${names.given}: adopting the app directory already at ${dir}`);
 }

package/dist/doctor.d.ts

@@ -1,15 +1,23 @@
 import { type OperatorConfig } from "./config.js";
+import { type Database } from "./database.js";
 import type { FetchLike } from "./providers/http.js";
 import { type Runner } from "./runner.js";
 /** A restore check older than this is a warning: E5 is meant to run weekly, not once. */
 export declare const RESTORE_CHECK_MAX_AGE_DAYS = 7;
+/** The `CONNECTION LIMIT` every application role is created with, in `provisionRoles`. */
+export declare const APPLICATION_ROLE_CONNECTION_LIMIT = 25;
+/** Past this share of `max_connections`, the next app to deploy is the one that cannot connect. */
+export declare const CONNECTIONS_WARN_FRACTION = 0.8;
 /** The branch prefix Phase 4's core bumps open their pull requests on. */
 export declare const CORE_BUMP_BRANCH_PREFIX = "core-bump/";
 export type Severity = "ok" | "warn" | "fail";
 export interface DoctorFinding {
     /** The app as the state cache names it. */
     app: string;
-    /** `state`, `status`, `runs`, `version`, `budget`, `E006`, `restore-check`, `core-bump`. */
+    /**
+     * `state`, `status`, `runs`, `version`, `budget`, `E006`, `connections`, `lock`,
+     * `restore-check`, `core-bump`.
+     */
     check: string;
     severity: Severity;
     message: string;
@@ -39,6 +47,11 @@ export interface DoctorOptions {
     now?: () => Date;
     /** How E006 is read. Defaults to the tunnel to `HF_SSH_HOST` as `postgres`. */
     privileges?: PrivilegeCheck;
+    /**
+     * Where the connection counts and the worker locks are read: the whole cluster, as the admin
+     * E006 already goes in as. Defaults to the same tunnel to `HF_SSH_HOST`.
+     */
+    database?: () => Promise<Database>;
     env?: NodeJS.ProcessEnv;
 }
 /**
@@ -70,3 +83,11 @@ export declare function tunnelPrivilegeCheck(runner: Runner, options?: {
  * privilege query is a second thing to keep in step with the grants the migrator makes.
  */
 export declare function checkAppRolePrivileges(adminUrl: string, role: string): Promise<void>;
+/**
+ * The worker's advisory lock in one app's database: exactly one, under the key the worker takes.
+ *
+ * `pg_try_advisory_lock(bigint)` splits its key across `classid` and `objid`, so the key is
+ * reassembled rather than compared whole — and masked rather than only shifted, because
+ * `hashtext` answers `int4` and a negative hash widens to a bigint of sign bits.
+ */
+export declare function workerLockSql(appName: string): string;

package/dist/doctor.js

@@ -6,10 +6,15 @@ import { DEFAULT_PG_ADMIN_USER, loadOperatorConfig, pgAdminUser, postgresContain
 import { openDatabase } from "./database.js";
 import { deriveNames } from "./names.js";
 import { GithubClient } from "./providers/github.js";
+import { quoteLiteral } from "./roles.js";
 import { createSshRunner } from "./runner.js";
 import { openAppState, stateDir } from "./state.js";
 /** A restore check older than this is a warning: E5 is meant to run weekly, not once. */
 export const RESTORE_CHECK_MAX_AGE_DAYS = 7;
+/** The `CONNECTION LIMIT` every application role is created with, in `provisionRoles`. */
+export const APPLICATION_ROLE_CONNECTION_LIMIT = 25;
+/** Past this share of `max_connections`, the next app to deploy is the one that cannot connect. */
+export const CONNECTIONS_WARN_FRACTION = 0.8;
 /** The branch prefix Phase 4's core bumps open their pull requests on. */
 export const CORE_BUMP_BRANCH_PREFIX = "core-bump/";
 /**
@@ -27,6 +32,7 @@ export async function doctor(options = {}) {
     const config = options.config ?? (await loadOperatorConfig({ env }));
     const required = requireOperatorConfig(config, ["HF_BASE_DOMAIN", "HF_GITHUB_TOKEN"], { env });
     const dir = options.stateDir ?? stateDir(env);
+    const cluster = lazyDatabase(options.database ?? defaultDatabase(config, env));
     const context = {
         dir,
         env,
@@ -35,11 +41,20 @@ export async function doctor(options = {}) {
         fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
         now: options.now ?? (() => new Date()),
         privileges: options.privileges ?? defaultPrivilegeCheck(config, env),
+        database: cluster.get,
+        // One snapshot for the whole run: the counts are the box's, not any one app's, and an app
+        // whose line is read a second later has not moved the cluster.
+        backends: once(async () => await readBackends(await cluster.get())),
     };
     const names = options.name === undefined ? await stateNames(dir) : [options.name];
     const findings = [];
-    for (const name of names)
-        findings.push(...(await doctorApp(context, name)));
+    try {
+        for (const name of names)
+            findings.push(...(await doctorApp(context, name)));
+    }
+    finally {
+        await cluster.close();
+    }
     return { findings, ok: findings.every((finding) => finding.severity === "ok") };
 }
 const MARKER = { ok: "OK  ", warn: "WARN", fail: "FAIL" };
@@ -109,6 +124,30 @@ function defaultPrivilegeCheck(config, env) {
         adminUser: pgAdminUser(config),
     });
 }
+function defaultDatabase(config, env) {
+    const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
+    const runner = createSshRunner({ host: HF_SSH_HOST });
+    return async () => await openDatabase(runner, {
+        admin: { user: pgAdminUser(config) },
+        containers: postgresContainers(config),
+    });
+}
+/** One cluster connection for the whole run: opened when a check first needs it, closed once. */
+function lazyDatabase(open) {
+    let pending;
+    return {
+        get: () => (pending ??= open()),
+        close: async () => {
+            // A run whose every app failed before the first query never opened one, and an open that
+            // failed is already a finding.
+            await pending?.then(async (db) => await db.close(), () => undefined);
+        },
+    };
+}
+function once(read) {
+    let pending;
+    return () => (pending ??= read());
+}
 async function doctorApp(context, name) {
     const findings = [];
     const add = (check, severity, message) => {
@@ -148,6 +187,13 @@ async function doctorApp(context, name) {
         budgetFinding(report.budget.previous, "previous", add);
     }
     await privilegeFindings(context, name, add);
+    // A name `deriveNames` refuses has already failed E006 on that same message; the cluster checks
+    // have no names to run under and say nothing more.
+    const names = tryNames(name);
+    if (names !== undefined) {
+        await connectionFindings(context, names.applicationRole, add);
+        await lockFindings(context, names, add);
+    }
     restoreCheckFindings(context, state, add);
     if (repo !== undefined)
         await bumpFindings(context, repo, add);
@@ -294,6 +340,99 @@ async function privilegeFindings(context, name, add) {
         add("E006", "fail", flatten(error.message));
     }
 }
+/** Every backend belonging to an app role — `hf_<app>` and its `_migrator` and `_ro`. */
+const BACKENDS_SQL = "SELECT usename, count(*) FROM pg_stat_activity WHERE usename LIKE 'hf\\_%' GROUP BY usename";
+async function readBackends(db) {
+    const setting = (await db.query("SHOW max_connections")).rows[0]?.[0];
+    const byRole = new Map();
+    for (const row of (await db.query(BACKENDS_SQL)).rows) {
+        if (row[0] !== undefined)
+            byRole.set(row[0], Number(row[1]));
+    }
+    let total = 0;
+    for (const count of byRole.values())
+        total += count;
+    return { max: setting === undefined ? undefined : numeric(Number(setting)), total, byRole };
+}
+/**
+ * What the box's connection slots are spent on, and what this app has of them.
+ *
+ * Box-wide rather than per-app because that is where it runs out: every app on the box draws on
+ * one `max_connections`, and the app that then cannot connect is whichever one deploys next.
+ */
+async function connectionFindings(context, role, add) {
+    let backends;
+    try {
+        backends = await context.backends();
+    }
+    catch (error) {
+        add("connections", "fail", flatten(error.message));
+        return;
+    }
+    const limit = String(APPLICATION_ROLE_CONNECTION_LIMIT);
+    const line = `${role} ${String(backends.byRole.get(role) ?? 0)}/${limit}, box ` +
+        `${String(backends.total)}/${backends.max === undefined ? UNKNOWN : String(backends.max)} ` +
+        "on hf_ roles";
+    const crowded = backends.max !== undefined && backends.total > backends.max * CONNECTIONS_WARN_FRACTION;
+    add("connections", crowded ? "warn" : "ok", crowded
+        ? `${line} — over ${String(CONNECTIONS_WARN_FRACTION * 100)}% of max_connections`
+        : line);
+}
+/**
+ * The worker's advisory lock in one app's database: exactly one, under the key the worker takes.
+ *
+ * `pg_try_advisory_lock(bigint)` splits its key across `classid` and `objid`, so the key is
+ * reassembled rather than compared whole — and masked rather than only shifted, because
+ * `hashtext` answers `int4` and a negative hash widens to a bigint of sign bits.
+ */
+export function workerLockSql(appName) {
+    return (`WITH k AS (SELECT hashtext('hf-worker:' || ${quoteLiteral(appName)})::bigint AS value) ` +
+        "SELECT count(l.pid), count(l.pid) FILTER (WHERE " +
+        "l.classid = ((k.value >> 32) & 4294967295)::oid AND " +
+        "l.objid = (k.value & 4294967295)::oid) " +
+        "FROM k LEFT JOIN pg_locks AS l ON l.locktype = 'advisory' AND " +
+        "l.database = (SELECT oid FROM pg_database WHERE datname = current_database())");
+}
+async function lockFindings(context, names, add) {
+    let row;
+    try {
+        const db = await context.database();
+        row = (await db.query(workerLockSql(names.appName), { database: names.databaseName })).rows[0];
+    }
+    catch (error) {
+        add("lock", "fail", flatten(error.message));
+        return;
+    }
+    const key = `hf-worker:${names.appName}`;
+    const held = Number(row?.[0]);
+    const matching = Number(row?.[1]);
+    if (!Number.isFinite(held)) {
+        add("lock", "fail", `pg_locks in ${names.databaseName} answered no count`);
+        return;
+    }
+    if (held === 0) {
+        add("lock", "fail", `no advisory lock in ${names.databaseName}: no worker holds ${key}`);
+        return;
+    }
+    if (held !== 1) {
+        add("lock", "fail", `${String(held)} advisory locks in ${names.databaseName}; one worker per app holds one`);
+        return;
+    }
+    if (matching !== 1) {
+        add("lock", "fail", `the one advisory lock in ${names.databaseName} is not hashtext('${key}'): ` +
+            "something other than the worker holds it");
+        return;
+    }
+    add("lock", "ok", `one worker holds ${key} in ${names.databaseName}`);
+}
+function tryNames(name) {
+    try {
+        return deriveNames(name);
+    }
+    catch {
+        return undefined;
+    }
+}
 function restoreCheckFindings(context, state, add) {
     const last = state.lastRestoreCheckAt;
     if (last === undefined) {

package/dist/index.d.ts

@@ -17,5 +17,5 @@ export { run, CommandFailed, type RunOptions } from "./spawn.js";
 export { createLocalRunner, createSshRunner, shellQuote, sshExecArgv, sshTunnelArgv, RunnerError, DEFAULT_TUNNEL_READY_TIMEOUT_MS, type ExecOptions, type ExecResult, type LocalRunner, type LocalRunnerOptions, type Runner, type SshRunnerOptions, type Tunnel, } from "./runner.js";
 export { findPostgresContainer, openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, type AdminCredentials, type Database, type DatabaseTransport, type OpenDatabaseOptions, type QueryOptions, type QueryResult, } from "./database.js";
 export { createLocalDirectoryBackupSource, createS3BackupSource, BackupSourceError, COOLIFY_BACKUP_DIR, type BackupDump, type BackupSource, type BackupSourceKind, type LocalDirectoryBackupSourceOptions, } from "./backup-source.js";
-export { formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, type RestoreCheckAppOptions, type RestoreCheckOptions, type RestoreCheckResult, type RestoreCheckRow, type RestoreVerdict, } from "./restore-check.js";
+export { APPEND_ONLY_TABLES, formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, type RestoreCheckAppOptions, type RestoreCheckOptions, type RestoreCheckResult, type RestoreCheckRow, type RestoreVerdict, } from "./restore-check.js";
 export { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, type ProvisionDatabaseOptions, type ProvisionDatabaseResult, } from "./provision-database.js";

package/dist/index.js

@@ -17,5 +17,5 @@ export { run, CommandFailed } from "./spawn.js";
 export { createLocalRunner, createSshRunner, shellQuote, sshExecArgv, sshTunnelArgv, RunnerError, DEFAULT_TUNNEL_READY_TIMEOUT_MS, } from "./runner.js";
 export { findPostgresContainer, openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, } from "./database.js";
 export { createLocalDirectoryBackupSource, createS3BackupSource, BackupSourceError, COOLIFY_BACKUP_DIR, } from "./backup-source.js";
-export { formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, } from "./restore-check.js";
+export { APPEND_ONLY_TABLES, formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, } from "./restore-check.js";
 export { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, } from "./provision-database.js";

package/dist/new.d.ts

@@ -14,6 +14,23 @@ export declare const EXCLUDED_ENTRIES: readonly string[];
 export declare class TemplateError extends Error {
     constructor(message: string);
 }
+/**
+ * Where a cloud `hf new` fetches the template before it becomes the app.
+ *
+ * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
+ * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
+ */
+export declare function templateTempDir(dir: string): string;
+/**
+ * The two refusals a directory in the way earns, worded once because both halves of `hf new`
+ * raise them.
+ *
+ * Each names the absolute path and the single move that clears it: "already exists" alone leaves
+ * the operator to work out which of the app directory and the dot-prefixed scratch beside it is
+ * meant, and they are one keystroke apart.
+ */
+export declare function targetInTheWay(dir: string): TemplateError;
+export declare function scratchInTheWay(scratch: string): TemplateError;
 export interface NewAppOptions {
     /** The name as typed; becomes the directory and, underscored, both placeholders. */
     name: string;
@@ -29,6 +46,11 @@ export interface NewAppOptions {
     local: boolean;
     /** The bootstrap admin's address, written to `.env` as `HF_BOOTSTRAP_EMAIL`. Skips the prompt. */
     email?: string;
+    /**
+     * The app's monthly LLM budget, written to `.env` as `HF_BOOTSTRAP_BUDGET_USD`. `hf up` seeds
+     * the app state from there instead of falling back to its dev default.
+     */
+    budgetUsd?: string;
     /** Overrides the real interactive prompt; for tests and other callers with their own stdin. */
     promptEmail?: () => Promise<string>;
 }
@@ -41,6 +63,8 @@ export interface NewAppResult extends AppNames {
     wroteEnv: boolean;
     /** True when `HF_BOOTSTRAP_EMAIL` was written to `.env`, from `--email` or the prompt. */
     wroteBootstrapEmail: boolean;
+    /** True when `HF_BOOTSTRAP_BUDGET_USD` was written to `.env`, from `--budget-usd`. */
+    wroteBootstrapBudget: boolean;
 }
 /**
  * Copies the template checkout and substitutes the two placeholders across it.

package/dist/new.js

@@ -46,6 +46,31 @@ export class TemplateError extends Error {
         this.name = "TemplateError";
     }
 }
+/**
+ * Where a cloud `hf new` fetches the template before it becomes the app.
+ *
+ * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
+ * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
+ */
+export function templateTempDir(dir) {
+    return path.join(path.dirname(dir), `.${path.basename(dir)}.hf-new`);
+}
+/**
+ * The two refusals a directory in the way earns, worded once because both halves of `hf new`
+ * raise them.
+ *
+ * Each names the absolute path and the single move that clears it: "already exists" alone leaves
+ * the operator to work out which of the app directory and the dot-prefixed scratch beside it is
+ * meant, and they are one keystroke apart.
+ */
+export function targetInTheWay(dir) {
+    return new TemplateError(`${dir} already exists; hf new will not write into it. Move it away (or delete it) and rerun — ` +
+        "the template is fetched into a directory of its own.");
+}
+export function scratchInTheWay(scratch) {
+    return new TemplateError(`${scratch} is a leftover hf new scratch directory and hf has no record of creating it. ` +
+        "Remove it and rerun; the template is fetched into it fresh.");
+}
 /**
  * Copies the template checkout and substitutes the two placeholders across it.
  *
@@ -64,7 +89,13 @@ export async function newApp(options) {
     await assertTemplateSource(source);
     const dir = path.resolve(options.into ?? process.cwd(), names.given);
     if (await exists(dir)) {
-        throw new TemplateError(`${dir} already exists; hf new will not write into it`);
+        throw targetInTheWay(dir);
+    }
+    // A scratch directory here is an interrupted cloud run for this same name: copying an app over
+    // the top of it would leave that run's rerun to judge a directory neither flow made.
+    const scratch = templateTempDir(dir);
+    if (await exists(scratch)) {
+        throw scratchInTheWay(scratch);
     }
     await cp(source, dir, {
         recursive: true,
@@ -75,6 +106,7 @@ export async function newApp(options) {
     const example = path.join(dir, ".env.example");
     const wroteEnv = await exists(example);
     let wroteBootstrapEmail = false;
+    let wroteBootstrapBudget = false;
     if (wroteEnv) {
         let contents = await readFile(example, "utf8");
         const email = options.email ?? (await (options.promptEmail ?? promptForBootstrapEmail)());
@@ -82,9 +114,13 @@ export async function newApp(options) {
             contents = `${contents.trimEnd()}\nHF_BOOTSTRAP_EMAIL=${email}\n`;
             wroteBootstrapEmail = true;
         }
+        if (options.budgetUsd !== undefined && options.budgetUsd !== "") {
+            contents = `${contents.trimEnd()}\nHF_BOOTSTRAP_BUDGET_USD=${options.budgetUsd}\n`;
+            wroteBootstrapBudget = true;
+        }
         await writeFile(path.join(dir, ".env"), contents);
     }
-    return { ...names, dir, substituted, wroteEnv, wroteBootstrapEmail };
+    return { ...names, dir, substituted, wroteEnv, wroteBootstrapEmail, wroteBootstrapBudget };
 }
 /** The one-time prompt: the address `hf up` later hands `hf bootstrap` via `.env`. */
 async function promptForBootstrapEmail() {

package/dist/restore-check.d.ts

@@ -4,8 +4,21 @@ import { type Runner } from "./runner.js";
 import { type AppStateStore } from "./state.js";
 /** Appended to `hf_<app>` for the database the dump is restored into and then dropped. */
 export declare const SCRATCH_SUFFIX = "_restore_check";
-/** Older than this and the dump gets a warning line; it never changes the exit code. */
-export declare const STALE_DUMP_HOURS = 36;
+/** Older than this and the dump gets a WARN line, which — as in `hf doctor` — exits 1. */
+export declare const STALE_DUMP_HOURS = 24;
+/**
+ * Tables a live row is only ever added to, so a live count above the dump's is the app working,
+ * not lost data.
+ *
+ * X1 found this the hard way: against a 1.3-hour-old dump of a running app, 9 of 24 tables
+ * "mismatched" purely from churn since the dump, and the same check against a fresh dump matched
+ * all 24. A table earns a place here only when no code path deletes from it and none updates it
+ * in a way that lowers its count — checked against `packages/db/src/schema` and every statement
+ * in `core`, `workflows`, `auth` and `admin`. Anything else, including a table whose rows merely
+ * look permanent, stays exact: a false `ok` here hides exactly the data loss this command exists
+ * to catch.
+ */
+export declare const APPEND_ONLY_TABLES: readonly string[];
 export type RestoreVerdict = "ok" | "mismatch" | "live only" | "restored only";
 export interface RestoreCheckRow {
     table: string;
@@ -13,6 +26,14 @@ export interface RestoreCheckRow {
     live?: number;
     /** Absent when the table is not in the restored dump. */
     restored?: number;
+    /**
+     * Rows the live side gained since the dump, on an `APPEND_ONLY_TABLES` table.
+     *
+     * Drift is not its own verdict because it is not its own outcome: the restore held everything
+     * the dump had, which is `ok`. The column prints it as `ok (drift +N)` so the operator can see
+     * why two counts differ without having to decide whether it mattered.
+     */
+    drift?: number;
     verdict: RestoreVerdict;
 }
 export interface RestoreCheckResult {
@@ -21,11 +42,15 @@ export interface RestoreCheckResult {
     scratchDatabase: string;
     dump: BackupDump;
     dumpAgeHours: number;
-    /** The dump is older than `STALE_DUMP_HOURS`. Informational. */
+    /** The dump is older than `STALE_DUMP_HOURS`; on its own enough to exit 1. */
     dumpStale: boolean;
+    /** Exact matching was asked for, so no table was allowed to drift. */
+    strict: boolean;
     /** One row per table, `hf_*` or carrying `normalized_name`, sorted by name. */
     rows: readonly RestoreCheckRow[];
-    /** Every row's verdict is `ok`. The command's exit code is `ok ? 0 : 1`. */
+    /** Every row's verdict is `ok`, drift included. What `lastRestoreCheckAt` is written on. */
+    matched: boolean;
+    /** `matched` and the dump is not stale. The command's exit code is `ok ? 0 : 1`. */
     ok: boolean;
 }
 export declare class RestoreCheckError extends Error {
@@ -57,6 +82,8 @@ export interface RestoreCheckOptions {
     restoreAdminUrl?: string;
     /** The `pg_restore` binary inside the container. */
     pgRestorePath?: string;
+    /** Compare every table exactly, `APPEND_ONLY_TABLES` included. */
+    strict?: boolean;
     now?: Date;
 }
 /**
@@ -104,6 +131,8 @@ export interface RestoreCheckAppOptions {
     backupDir?: string;
     /** Read the dump from Hetzner object storage instead. Not implemented; see `backup-source`. */
     fromS3?: boolean;
+    /** Compare every table exactly, `APPEND_ONLY_TABLES` included. */
+    strict?: boolean;
     env?: NodeJS.ProcessEnv;
 }
 /**

package/dist/restore-check.js

@@ -10,8 +10,40 @@ import { openAppState } from "./state.js";
 export const SCRATCH_SUFFIX = "_restore_check";
 /** Postgres truncates an identifier past this, which would collide with the live database. */
 const MAX_IDENTIFIER_BYTES = 63;
-/** Older than this and the dump gets a warning line; it never changes the exit code. */
-export const STALE_DUMP_HOURS = 36;
+/** Older than this and the dump gets a WARN line, which — as in `hf doctor` — exits 1. */
+export const STALE_DUMP_HOURS = 24;
+/**
+ * Tables a live row is only ever added to, so a live count above the dump's is the app working,
+ * not lost data.
+ *
+ * X1 found this the hard way: against a 1.3-hour-old dump of a running app, 9 of 24 tables
+ * "mismatched" purely from churn since the dump, and the same check against a fresh dump matched
+ * all 24. A table earns a place here only when no code path deletes from it and none updates it
+ * in a way that lowers its count — checked against `packages/db/src/schema` and every statement
+ * in `core`, `workflows`, `auth` and `admin`. Anything else, including a table whose rows merely
+ * look permanent, stays exact: a false `ok` here hides exactly the data loss this command exists
+ * to catch.
+ */
+export const APPEND_ONLY_TABLES = [
+    // Insert-only ledgers: nothing but `INSERT` touches either.
+    "hf_audit",
+    "hf_activity",
+    // Ledger rows are inserted `started` and then `UPDATE`d to a terminal status — including
+    // `reconcile()`'s sweep to `abandoned`/`uncertain`, which is still an update.
+    "hf_llm_call",
+    "hf_action_log",
+    // Inserted pending and decided by `UPDATE`; `reconcile()` step (5) expires a stale one the
+    // same way. The delete guard exists precisely so an approval outlives the record it names.
+    "hf_approval",
+    // Inserted, or upserted on `(run_id, key, spec_name)` by a replayed step; never deleted.
+    "hf_score",
+    // `INSERT` at the start of a source run, `UPDATE` at its end.
+    "hf_source_run",
+    // `INSERT` at `runs.start`; every later write is an `UPDATE` of status, attempt or the
+    // fencing token. Runs are never purged — there is no retention sweep.
+    "hf_run",
+];
+const APPEND_ONLY = new Set(APPEND_ONLY_TABLES);
 export class RestoreCheckError extends Error {
     constructor(message) {
         super(message);
@@ -72,22 +104,27 @@ export async function restoreCheck(options) {
                     `TO ${quoteIdent(names.migratorRole)}`);
                 await scratch.query(`GRANT CREATE, USAGE ON SCHEMA public TO ${quoteIdent(names.migratorRole)}`);
                 await runRestore(options, scratchDatabase, names.migratorRole, dump.path);
-                rows = compare(await countTables(db, names.databaseName), await countTables(scratch));
+                rows = compare(await countTables(db, names.databaseName), await countTables(scratch), options.strict ?? false);
             }
             finally {
                 await scratch.close();
             }
-            const ok = rows.every((row) => row.verdict === "ok");
-            if (ok)
+            const dumpStale = dumpAgeHours > STALE_DUMP_HOURS;
+            const matched = rows.every((row) => row.verdict === "ok");
+            // A stale dump keeps the exit code but not the timestamp: the restore itself was proved,
+            // and it is `hf doctor` that decides how long a proof stays good.
+            if (matched)
                 await options.state.patch({ lastRestoreCheckAt: now.toISOString() });
             return {
                 databaseName: names.databaseName,
                 scratchDatabase,
                 dump,
                 dumpAgeHours,
-                dumpStale: dumpAgeHours > STALE_DUMP_HOURS,
+                dumpStale,
+                strict: options.strict ?? false,
                 rows,
-                ok,
+                matched,
+                ok: matched && !dumpStale,
             };
         }
         finally {
@@ -203,23 +240,35 @@ async function countTables(db, database) {
  * A table on one side only is its own verdict rather than a crash or a zero: an app migration
  * between the backup and the check is the ordinary reason for it, and reading it as a count of
  * zero would make an added table look like lost data.
+ *
+ * An `APPEND_ONLY_TABLES` table the live side is *ahead* on is `ok` with a `drift`, unless
+ * `strict`. A restored count above the live one is still a `mismatch` there: the dump cannot
+ * hold rows an append-only live table has since lost unless something did lose them.
  */
-function compare(live, restored) {
+function compare(live, restored, strict) {
     const tables = [...new Set([...live.keys(), ...restored.keys()])].sort();
     return tables.map((table) => {
         const liveCount = live.get(table);
         const restoredCount = restored.get(table);
+        const drifted = !strict &&
+            APPEND_ONLY.has(table) &&
+            liveCount !== undefined &&
+            restoredCount !== undefined &&
+            restoredCount < liveCount;
         const verdict = liveCount === undefined
             ? "restored only"
             : restoredCount === undefined
                 ? "live only"
-                : liveCount === restoredCount
+                : liveCount === restoredCount || drifted
                     ? "ok"
                     : "mismatch";
         return {
             table,
             ...(liveCount === undefined ? {} : { live: liveCount }),
             ...(restoredCount === undefined ? {} : { restored: restoredCount }),
+            ...(drifted && liveCount !== undefined && restoredCount !== undefined
+                ? { drift: liveCount - restoredCount }
+                : {}),
             verdict,
         };
     });
@@ -227,24 +276,29 @@ function compare(live, restored) {
 /** The table `hf restore-check` prints, and the two lines around it. */
 export function formatRestoreCheck(result) {
     const age = `${result.dumpAgeHours.toFixed(1)} h old`;
-    const lines = [`${result.databaseName}: ${result.dump.path}, ${age}`];
+    const lines = [
+        `${result.databaseName}: ${result.dump.path}, ${age}${result.strict ? ", strict" : ""}`,
+    ];
     if (result.dumpStale) {
-        lines.push(`WARNING: the dump is ${age} — over ${String(STALE_DUMP_HOURS)} h`);
+        lines.push(`WARN: the dump is ${age} — over ${String(STALE_DUMP_HOURS)} h; ` +
+            "this compares against stale data");
     }
     const header = ["table", "live", "restored", "verdict"];
     const cells = result.rows.map((row) => [
         row.table,
         row.live === undefined ? "—" : String(row.live),
         row.restored === undefined ? "—" : String(row.restored),
-        row.verdict,
+        row.drift === undefined ? row.verdict : `${row.verdict} (drift +${String(row.drift)})`,
     ]);
     const widths = header.map((name, column) => Math.max(name.length, ...cells.map((row) => row[column]?.length ?? 0)));
     const line = (row) => row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd();
     lines.push(line(header), ...cells.map(line));
-    const mismatched = result.rows.filter((row) => row.verdict !== "ok").length;
-    lines.push(result.ok
-        ? `${String(result.rows.length)} table(s) matched`
-        : `${String(mismatched)} of ${String(result.rows.length)} table(s) did not match`);
+    const drifted = result.rows.filter((row) => row.drift !== undefined).length;
+    const failed = result.rows.filter((row) => row.verdict !== "ok").length;
+    const drift = drifted === 0 ? "" : `, ${String(drifted)} with drift since the dump`;
+    lines.push(result.matched
+        ? `${String(result.rows.length)} table(s) matched${drift}`
+        : `${String(failed)} of ${String(result.rows.length)} table(s) did not match${drift}`);
     return lines;
 }
 /**
@@ -273,6 +327,7 @@ export async function restoreCheckApp(options) {
             database: db,
             container: await restoreContainer(runner, db, containers),
             adminUser: admin.user,
+            strict: options.strict,
         });
     }
     finally {

package/dist/roles.d.ts

@@ -32,3 +32,4 @@ export declare function credentialsOf(connectionString: string): {
     user: string;
     password: string;
 };
+export declare function quoteLiteral(value: string): string;

package/dist/roles.js

@@ -46,6 +46,6 @@ export function credentialsOf(connectionString) {
     const url = new URL(connectionString);
     return { user: decodeURIComponent(url.username), password: decodeURIComponent(url.password) };
 }
-function quoteLiteral(value) {
+export function quoteLiteral(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }

package/dist/state.d.ts

@@ -59,6 +59,14 @@ export interface AppState {
      * earlier `hf new --local` looks exactly like a lost run.
      */
     templateStartedAt?: string;
+    /**
+     * ISO 8601, written just before the `template` step fetches into the scratch directory beside
+     * the app's path.
+     *
+     * The same proof one step earlier: a scratch directory the state does not vouch for is refused
+     * rather than deleted, and a fetch that died half way is this run's own to clear and redo.
+     */
+    templateFetchStartedAt?: string;
     /** `owner/name` of the app's GitHub repository. */
     repo?: string;
     coolify?: CoolifyState;

package/dist/state.js

@@ -150,6 +150,7 @@ function parseAppState(contents, file) {
                 break;
             case "repo":
             case "templateStartedAt":
+            case "templateFetchStartedAt":
             case "sentryDsn":
             case "betterAuthSecret":
             case "lastRestoreCheckAt":

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This package's own version, read from its `package.json` at runtime.
+ *
+ * Not a constant the build stamps in: the nine packages are one fixed version group, and a
+ * release rewrites `package.json` alone — a baked-in string would be a second copy that is wrong
+ * from the next release onwards. `../package.json` resolves the same from `src/` and from `dist/`.
+ */
+export declare function cliVersion(): Promise<string>;

package/dist/version.js

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+/**
+ * This package's own version, read from its `package.json` at runtime.
+ *
+ * Not a constant the build stamps in: the nine packages are one fixed version group, and a
+ * release rewrites `package.json` alone — a baked-in string would be a second copy that is wrong
+ * from the next release onwards. `../package.json` resolves the same from `src/` and from `dist/`.
+ */
+export async function cliVersion() {
+    const manifest = JSON.parse(await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+    return typeof manifest.version === "string" ? manifest.version : "unknown";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixation/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "license": "MIT",
   "description": "The hf binary and its Turborepo generator templates",
   "repository": {
@@ -29,15 +29,15 @@
     "!dist/test-support/**"
   ],
   "dependencies": {
-    "@hyperfixation/auth": "0.1.6",
-    "@hyperfixation/core": "0.1.6",
-    "@hyperfixation/db": "0.1.6",
+    "@hyperfixation/auth": "0.1.7",
+    "@hyperfixation/core": "0.1.7",
+    "@hyperfixation/db": "0.1.7",
     "giget": "3.3.1",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@hyperfixation/eslint-config": "0.1.6",
-    "@hyperfixation/testing": "0.1.6",
+    "@hyperfixation/eslint-config": "0.1.7",
+    "@hyperfixation/testing": "0.1.7",
     "@microsoft/api-extractor": "^7.59.1",
     "@types/pg": "^8.23.1",
     "eslint": "^10.10.0",