@fonderie/admin 0.8.3 → 0.9.0

package/dist/index.d.cts

@@ -1,11 +1,23 @@
 import { IAdminCheck, IAdminCheckReport, IReadinessReport, IRouteEntry, IFonderieModule, IFonderieApp, IReadinessProblem, Middleware } from '@fonderie/core';
-import { IStoreAdapter } from '@fonderie/store';
+import { IStoreAdapter, MigrationImpact } from '@fonderie/store';
+import { IRequestSchema } from '@fonderie/core/middlewares';
 
 interface IAdminOptions {
     adminToken?: string;
     path?: string;
     checks?: IAdminCheck[];
     checkTimeoutMs?: number;
+    /**
+     * The ordered migration sets this deployment applies, exactly as its own
+     * applier runs them — brick directories and the app's own, interleaved.
+     * Unset ⇒ the migrations routes are not registered at all.
+     *
+     * Pass the SAME constant the applier reads. The order is the app's to
+     * declare and this surface must never infer it: bricks and app migrations
+     * depend on each other across the list, and a panel guessing that order
+     * would eventually guess wrong in a way that only shows on a fresh database.
+     */
+    migrations?: ReadonlyArray<IMigrationSet>;
     ui?: boolean;
     /**
      * Answer only for requests addressed to this hostname (or one of these);
@@ -131,6 +143,22 @@ interface IAdminTokensReport {
     legacy: IAdminTokenEntry[];
     issued: IAdminTokenRecord[] | null;
 }
+type IMigrationSet = readonly [name: string, dir: string];
+interface IAdminPendingMigration {
+    file: string;
+    impact: MigrationImpact;
+    destructive: string[];
+}
+interface IAdminMigrationModule {
+    name: string;
+    pending: IAdminPendingMigration[];
+    blockedBy: string | null;
+    appliable: boolean;
+}
+interface IAdminMigrationsReport {
+    everApplied: boolean;
+    modules: IAdminMigrationModule[];
+}
 
 declare const DEFAULT_ADMIN_PATH = "/_admin";
 declare const DEFAULT_CHECK_TIMEOUT_MS = 10000;
@@ -171,6 +199,62 @@ declare function configReport(app: IFonderieApp, env: string[]): IAdminConfigRep
 declare function routesReport(app: IFonderieApp, adminModule: string): IAdminRoutesReport;
 declare function tokensReport(app: IFonderieApp, adminModule: string, issued: IAdminTokenRecord[] | null): IAdminTokensReport;
 
+/**
+ * `expect` is the exact pending list the operator was shown, in order.
+ *
+ * It is not ceremony. Between rendering the page and clicking the button a
+ * deploy can change what is pending — and the thing that changed is precisely
+ * the thing nobody reviewed. Sending it back makes the server refuse rather
+ * than apply a set the operator never saw. Same shape as versionedWrite's
+ * if_version, and it also gives this POST the body schema audit:validation
+ * requires.
+ */
+declare const applyMigrationsSchema: IRequestSchema;
+/**
+ * What every module is waiting on, with each pending file's impact.
+ *
+ * `blockedBy` names the first EARLIER module that is behind. Order is
+ * load-bearing and declared by the app, so a module cannot be applied while
+ * something it may depend on is unapplied — the panel offers one button at a
+ * time and the operator walks the list in the declared order.
+ */
+declare function migrationsReport(store: IStoreAdapter, sets: ReadonlyArray<IMigrationSet>): Promise<IAdminMigrationsReport>;
+type ApplyOutcome = {
+    ok: true;
+    reason: 'MIGRATIONS_APPLIED' | 'MIGRATIONS_UP_TO_DATE';
+    module: IAdminMigrationModule;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND';
+} | {
+    ok: false;
+    reason: 'MIGRATIONS_OUT_OF_ORDER';
+    blockedBy: string;
+} | {
+    ok: false;
+    reason: 'MIGRATIONS_CHANGED';
+    expected: string[];
+    actual: string[];
+} | {
+    ok: false;
+    reason: 'MIGRATION_DESTRUCTIVE';
+    files: IAdminMigrationModule['pending'];
+};
+/**
+ * Apply one module's pending migrations — all of them, or none.
+ *
+ * There is no partial apply, deliberately: files run in lexicographic order, so
+ * an additive migration sorting AFTER a destructive one may depend on it.
+ * Cherry-picking around a DROP would apply 901 against a schema that never saw
+ * 900. Refusing the whole module at the first destructive file is the only safe
+ * reading, and happens to be the only one MigrationRunner.run() supports.
+ *
+ * `expect` is the file list the operator was looking at. Between the render and
+ * the click a deploy can change what is pending; without this the button would
+ * apply something nobody reviewed.
+ */
+declare function applyModuleMigrations(store: IStoreAdapter, sets: ReadonlyArray<IMigrationSet>, module: string, expect: readonly string[]): Promise<ApplyOutcome>;
+
 declare const SCOPES: readonly AdminScope[];
 declare function scopeFor(method: string, path: string): AdminScope;
 declare function grants(held: readonly AdminScope[], needed: AdminScope): boolean;
@@ -188,4 +272,4 @@ declare function issueToken(store: IStoreAdapter, input: {
 declare function revokeToken(store: IStoreAdapter, id: string): Promise<boolean>;
 declare function requireAdminScope(bootstrap: string, store: IStoreAdapter | undefined, needed: AdminScope | 'root'): Middleware;
 
-export { ADMIN_VERSION, AdminModule, type AdminRouteGuard, type AdminScope, DEFAULT_ACTOR, DEFAULT_ADMIN_PATH, DEFAULT_CHECK_TIMEOUT_MS, type IAdminAttention, type IAdminAttentionItem, type IAdminCheckResult, type IAdminConfigReport, type IAdminDoctorReport, type IAdminEnvEntry, type IAdminLogEntry, type IAdminLogPage, type IAdminManifest, type IAdminModuleEntry, type IAdminOptions, type IAdminRouteEntry, type IAdminRoutesReport, type IAdminTokenEntry, type IAdminTokenRecord, type IAdminTokensReport, MAX_PAGE, SCOPES, adminLog, attention, buildManifest, collectChecks, configReport, grants, hashToken, issueToken, listTokens, readAdminLog, requireAdminScope, revokeToken, routesReport, runDoctor, scopeFor, tokensReport };
+export { ADMIN_VERSION, AdminModule, type AdminRouteGuard, type AdminScope, DEFAULT_ACTOR, DEFAULT_ADMIN_PATH, DEFAULT_CHECK_TIMEOUT_MS, type IAdminAttention, type IAdminAttentionItem, type IAdminCheckResult, type IAdminConfigReport, type IAdminDoctorReport, type IAdminEnvEntry, type IAdminLogEntry, type IAdminLogPage, type IAdminManifest, type IAdminMigrationModule, type IAdminMigrationsReport, type IAdminModuleEntry, type IAdminOptions, type IAdminPendingMigration, type IAdminRouteEntry, type IAdminRoutesReport, type IAdminTokenEntry, type IAdminTokenRecord, type IAdminTokensReport, type IMigrationSet, MAX_PAGE, SCOPES, adminLog, applyMigrationsSchema, applyModuleMigrations, attention, buildManifest, collectChecks, configReport, grants, hashToken, issueToken, listTokens, migrationsReport, readAdminLog, requireAdminScope, revokeToken, routesReport, runDoctor, scopeFor, tokensReport };

package/dist/index.d.ts

@@ -1,11 +1,23 @@
 import { IAdminCheck, IAdminCheckReport, IReadinessReport, IRouteEntry, IFonderieModule, IFonderieApp, IReadinessProblem, Middleware } from '@fonderie/core';
-import { IStoreAdapter } from '@fonderie/store';
+import { IStoreAdapter, MigrationImpact } from '@fonderie/store';
+import { IRequestSchema } from '@fonderie/core/middlewares';
 
 interface IAdminOptions {
     adminToken?: string;
     path?: string;
     checks?: IAdminCheck[];
     checkTimeoutMs?: number;
+    /**
+     * The ordered migration sets this deployment applies, exactly as its own
+     * applier runs them — brick directories and the app's own, interleaved.
+     * Unset ⇒ the migrations routes are not registered at all.
+     *
+     * Pass the SAME constant the applier reads. The order is the app's to
+     * declare and this surface must never infer it: bricks and app migrations
+     * depend on each other across the list, and a panel guessing that order
+     * would eventually guess wrong in a way that only shows on a fresh database.
+     */
+    migrations?: ReadonlyArray<IMigrationSet>;
     ui?: boolean;
     /**
      * Answer only for requests addressed to this hostname (or one of these);
@@ -131,6 +143,22 @@ interface IAdminTokensReport {
     legacy: IAdminTokenEntry[];
     issued: IAdminTokenRecord[] | null;
 }
+type IMigrationSet = readonly [name: string, dir: string];
+interface IAdminPendingMigration {
+    file: string;
+    impact: MigrationImpact;
+    destructive: string[];
+}
+interface IAdminMigrationModule {
+    name: string;
+    pending: IAdminPendingMigration[];
+    blockedBy: string | null;
+    appliable: boolean;
+}
+interface IAdminMigrationsReport {
+    everApplied: boolean;
+    modules: IAdminMigrationModule[];
+}
 
 declare const DEFAULT_ADMIN_PATH = "/_admin";
 declare const DEFAULT_CHECK_TIMEOUT_MS = 10000;
@@ -171,6 +199,62 @@ declare function configReport(app: IFonderieApp, env: string[]): IAdminConfigRep
 declare function routesReport(app: IFonderieApp, adminModule: string): IAdminRoutesReport;
 declare function tokensReport(app: IFonderieApp, adminModule: string, issued: IAdminTokenRecord[] | null): IAdminTokensReport;
 
+/**
+ * `expect` is the exact pending list the operator was shown, in order.
+ *
+ * It is not ceremony. Between rendering the page and clicking the button a
+ * deploy can change what is pending — and the thing that changed is precisely
+ * the thing nobody reviewed. Sending it back makes the server refuse rather
+ * than apply a set the operator never saw. Same shape as versionedWrite's
+ * if_version, and it also gives this POST the body schema audit:validation
+ * requires.
+ */
+declare const applyMigrationsSchema: IRequestSchema;
+/**
+ * What every module is waiting on, with each pending file's impact.
+ *
+ * `blockedBy` names the first EARLIER module that is behind. Order is
+ * load-bearing and declared by the app, so a module cannot be applied while
+ * something it may depend on is unapplied — the panel offers one button at a
+ * time and the operator walks the list in the declared order.
+ */
+declare function migrationsReport(store: IStoreAdapter, sets: ReadonlyArray<IMigrationSet>): Promise<IAdminMigrationsReport>;
+type ApplyOutcome = {
+    ok: true;
+    reason: 'MIGRATIONS_APPLIED' | 'MIGRATIONS_UP_TO_DATE';
+    module: IAdminMigrationModule;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND';
+} | {
+    ok: false;
+    reason: 'MIGRATIONS_OUT_OF_ORDER';
+    blockedBy: string;
+} | {
+    ok: false;
+    reason: 'MIGRATIONS_CHANGED';
+    expected: string[];
+    actual: string[];
+} | {
+    ok: false;
+    reason: 'MIGRATION_DESTRUCTIVE';
+    files: IAdminMigrationModule['pending'];
+};
+/**
+ * Apply one module's pending migrations — all of them, or none.
+ *
+ * There is no partial apply, deliberately: files run in lexicographic order, so
+ * an additive migration sorting AFTER a destructive one may depend on it.
+ * Cherry-picking around a DROP would apply 901 against a schema that never saw
+ * 900. Refusing the whole module at the first destructive file is the only safe
+ * reading, and happens to be the only one MigrationRunner.run() supports.
+ *
+ * `expect` is the file list the operator was looking at. Between the render and
+ * the click a deploy can change what is pending; without this the button would
+ * apply something nobody reviewed.
+ */
+declare function applyModuleMigrations(store: IStoreAdapter, sets: ReadonlyArray<IMigrationSet>, module: string, expect: readonly string[]): Promise<ApplyOutcome>;
+
 declare const SCOPES: readonly AdminScope[];
 declare function scopeFor(method: string, path: string): AdminScope;
 declare function grants(held: readonly AdminScope[], needed: AdminScope): boolean;
@@ -188,4 +272,4 @@ declare function issueToken(store: IStoreAdapter, input: {
 declare function revokeToken(store: IStoreAdapter, id: string): Promise<boolean>;
 declare function requireAdminScope(bootstrap: string, store: IStoreAdapter | undefined, needed: AdminScope | 'root'): Middleware;
 
-export { ADMIN_VERSION, AdminModule, type AdminRouteGuard, type AdminScope, DEFAULT_ACTOR, DEFAULT_ADMIN_PATH, DEFAULT_CHECK_TIMEOUT_MS, type IAdminAttention, type IAdminAttentionItem, type IAdminCheckResult, type IAdminConfigReport, type IAdminDoctorReport, type IAdminEnvEntry, type IAdminLogEntry, type IAdminLogPage, type IAdminManifest, type IAdminModuleEntry, type IAdminOptions, type IAdminRouteEntry, type IAdminRoutesReport, type IAdminTokenEntry, type IAdminTokenRecord, type IAdminTokensReport, MAX_PAGE, SCOPES, adminLog, attention, buildManifest, collectChecks, configReport, grants, hashToken, issueToken, listTokens, readAdminLog, requireAdminScope, revokeToken, routesReport, runDoctor, scopeFor, tokensReport };
+export { ADMIN_VERSION, AdminModule, type AdminRouteGuard, type AdminScope, DEFAULT_ACTOR, DEFAULT_ADMIN_PATH, DEFAULT_CHECK_TIMEOUT_MS, type IAdminAttention, type IAdminAttentionItem, type IAdminCheckResult, type IAdminConfigReport, type IAdminDoctorReport, type IAdminEnvEntry, type IAdminLogEntry, type IAdminLogPage, type IAdminManifest, type IAdminMigrationModule, type IAdminMigrationsReport, type IAdminModuleEntry, type IAdminOptions, type IAdminPendingMigration, type IAdminRouteEntry, type IAdminRoutesReport, type IAdminTokenEntry, type IAdminTokenRecord, type IAdminTokensReport, type IMigrationSet, MAX_PAGE, SCOPES, adminLog, applyMigrationsSchema, applyModuleMigrations, attention, buildManifest, collectChecks, configReport, grants, hashToken, issueToken, listTokens, migrationsReport, readAdminLog, requireAdminScope, revokeToken, routesReport, runDoctor, scopeFor, tokensReport };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/module.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { HTTP as HTTP2, normalizeMountPath, normalizeRequestPath as normalizeRequestPath2, setApiResponse as setApiResponse2 } from "@fonderie/core";
 import { validate, validateAdminToken } from "@fonderie/core/middlewares";
 
@@ -142,6 +142,91 @@ function decodeCursor(c) {
   return at && id ? { at, id } : null;
 }
 
+// src/migrate.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+import { classifyMigration, InternalMigrationRunner } from "@fonderie/store";
+var applyMigrationsSchema = {
+  safeParse(input) {
+    const fail = (path, message) => ({
+      success: false,
+      error: { issues: [{ path: [path], message }] }
+    });
+    const b = input ?? {};
+    const expect = b["expect"];
+    if (!Array.isArray(expect) || !expect.every((f) => typeof f === "string"))
+      return fail("expect", "expect must be the list of pending filenames you were shown");
+    return { success: true, data: { expect } };
+  }
+};
+async function hasMigrationHistory(store) {
+  try {
+    const rows = await store.query(
+      "SELECT count(*)::int AS n FROM fonderie_migrations"
+    );
+    return (rows[0]?.n ?? 0) > 0;
+  } catch {
+    return false;
+  }
+}
+function classifyPending(dir, files) {
+  return files.map((file) => {
+    const { impact, destructive } = classifyMigration(readFileSync(join(dir, file), "utf8"));
+    return { file, impact, destructive };
+  });
+}
+async function migrationsReport(store, sets) {
+  const everApplied = await hasMigrationHistory(store);
+  const modules = [];
+  let firstBehind = null;
+  for (const [name, dir] of sets) {
+    const pending = await new InternalMigrationRunner(store, dir).pending();
+    const files = classifyPending(dir, pending);
+    modules.push({
+      name,
+      pending: files,
+      // Only a module BEFORE this one blocks it. The first module with
+      // pending work blocks every module after it, and nothing blocks it.
+      blockedBy: firstBehind,
+      // A file that deletes data on a database with nothing in it yet is not
+      // destroying anything. Same rule the CLI's --check applies.
+      appliable: files.length > 0 && firstBehind === null && (!everApplied || files.every((f) => f.impact === "additive"))
+    });
+    if (files.length > 0 && firstBehind === null) firstBehind = name;
+  }
+  return { everApplied, modules };
+}
+async function applyModuleMigrations(store, sets, module, expect) {
+  const set = sets.find(([name]) => name === module);
+  if (!set) return { ok: false, reason: "NOT_FOUND" };
+  const before = await migrationsReport(store, sets);
+  const target = before.modules.find((m) => m.name === module);
+  if (!target) return { ok: false, reason: "NOT_FOUND" };
+  if (target.blockedBy) {
+    return { ok: false, reason: "MIGRATIONS_OUT_OF_ORDER", blockedBy: target.blockedBy };
+  }
+  const actual = target.pending.map((p) => p.file);
+  const same = actual.length === expect.length && actual.every((f, i) => f === expect[i]);
+  if (!same) {
+    return { ok: false, reason: "MIGRATIONS_CHANGED", expected: [...expect], actual };
+  }
+  if (actual.length === 0) {
+    return { ok: true, reason: "MIGRATIONS_UP_TO_DATE", module: target };
+  }
+  const destructive = target.pending.filter((p) => p.impact === "destructive");
+  if (destructive.length > 0 && before.everApplied) {
+    return { ok: false, reason: "MIGRATION_DESTRUCTIVE", files: destructive };
+  }
+  await new InternalMigrationRunner(store, set[1]).run();
+  const after = await migrationsReport(store, sets);
+  const now = after.modules.find((m) => m.name === module);
+  return {
+    ok: true,
+    reason: "MIGRATIONS_APPLIED",
+    module: now ?? { name: module, pending: [], blockedBy: null, appliable: false }
+  };
+}
+
 // src/manifest.ts
 function buildManifest(app, admin) {
   const report = app.securityReport();
@@ -332,7 +417,7 @@ var uiHtml = (scriptPath) => `<!doctype html>
 // src/module.ts
 var DEFAULT_ADMIN_PATH = "/_admin";
 var DEFAULT_CHECK_TIMEOUT_MS = 1e4;
-var ADMIN_VERSION = "0.8.3";
+var ADMIN_VERSION = "0.9.0";
 function normalizeHostPattern(host) {
   return host.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/\/.*$/, "").toLowerCase();
 }
@@ -465,6 +550,70 @@ var AdminModule = class {
         ]
       ]
     ] : [];
+    const migrationSets = this.options.migrations;
+    const scoped = store && migrationSets ? [
+      [
+        "GET",
+        "/_admin/migrations",
+        [
+          async () => setApiResponse2(
+            HTTP2.OK,
+            "MIGRATIONS",
+            "Pending migrations by module",
+            await migrationsReport(store, migrationSets)
+          )
+        ]
+      ],
+      [
+        "POST",
+        "/_admin/migrations/:module/apply",
+        [
+          validate(applyMigrationsSchema),
+          async (ctx) => {
+            const { expect } = ctx.meta["body"];
+            const name = ctx.meta.params?.["module"] ?? "";
+            const out = await applyModuleMigrations(store, migrationSets, name, expect);
+            if (out.ok) {
+              return setApiResponse2(
+                HTTP2.OK,
+                out.reason,
+                out.reason === "MIGRATIONS_APPLIED" ? `Applied. ${out.module.pending.length} still pending in ${name}.` : `${name} is already up to date`,
+                out.module
+              );
+            }
+            switch (out.reason) {
+              case "NOT_FOUND":
+                return setApiResponse2(
+                  HTTP2.NOT_FOUND,
+                  "NOT_FOUND",
+                  `No migration set named "${name}"`
+                );
+              case "MIGRATIONS_OUT_OF_ORDER":
+                return setApiResponse2(
+                  HTTP2.CONFLICT,
+                  out.reason,
+                  `Apply "${out.blockedBy}" first \u2014 it runs before "${name}" and is behind.`,
+                  { blockedBy: out.blockedBy }
+                );
+              case "MIGRATIONS_CHANGED":
+                return setApiResponse2(
+                  HTTP2.CONFLICT,
+                  out.reason,
+                  "What is pending changed since you looked. Refresh and read it again.",
+                  { expected: out.expected, actual: out.actual }
+                );
+              default:
+                return setApiResponse2(
+                  HTTP2.UNPROCESSABLE,
+                  out.reason,
+                  "A pending migration deletes data. No down-migration brings it back \u2014 apply it through CI or `npm run migrate`, not from here.",
+                  { files: out.files }
+                );
+            }
+          }
+        ]
+      ]
+    ] : [];
     const mounted = /* @__PURE__ */ new Map();
     const mount = (module, method, path, handlers, needed) => {
       const key = `${method.toUpperCase()} ${path}`;
@@ -492,7 +641,7 @@ var AdminModule = class {
       const loadJs = () => {
         if (js === null) {
           try {
-            js = readFileSync(new URL("./ui/app.global.js", import.meta.url), "utf8");
+            js = readFileSync2(new URL("./ui/app.global.js", import.meta.url), "utf8");
           } catch {
             js = "";
           }
@@ -531,6 +680,7 @@ var AdminModule = class {
     for (const [method, path, handler] of own) mount(this.name, method, at(path), [handler]);
     for (const [method, path, handlers] of rootOnly)
       mount(this.name, method, at(path), handlers, "root");
+    for (const [method, path, handlers] of scoped) mount(this.name, method, at(path), handlers);
     for (const { module, description } of app.adminDescriptions()) {
       for (const r of description.routes ?? [])
         mount(module, r.method, this.path + r.path, r.handlers);
@@ -549,6 +699,8 @@ export {
   MAX_PAGE,
   SCOPES,
   adminLog,
+  applyMigrationsSchema,
+  applyModuleMigrations,
   attention,
   buildManifest,
   collectChecks,
@@ -557,6 +709,7 @@ export {
   hashToken,
   issueToken,
   listTokens,
+  migrationsReport,
   readAdminLog,
   requireAdminScope,
   revokeToken,