@hyperfixation/cli 0.1.5 → 0.1.7

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.5",
+  "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.5",
-    "@hyperfixation/core": "0.1.5",
-    "@hyperfixation/db": "0.1.5",
+    "@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.5",
-    "@hyperfixation/testing": "0.1.5",
+    "@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",