@fjall/util 20.0.0 → 21.1.0

package/dist/migration/clickhouseFrameworkUsers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Cross-package contract for the framework-owned ClickHouse identities —
+ * one SQL user per control-plane workload class, so no two classes ever
+ * contend for the same per-user concurrency cap.
+ *
+ * | identity             | holder(s)                              | rights                                   |
+ * | -------------------- | -------------------------------------- | ---------------------------------------- |
+ * | `schemaAdmin.name`   | migration task (XML, `ddl_admin`)      | full DDL; cap 1 = DDL single-flight      |
+ * | `fjall_schema_gate`  | materialised gate container            | `readonly=2`, SELECT on `_schema_migrations` only; NO per-user cap |
+ * | `fjall_maintenance`  | backup + optimise sidecars             | today's `ddl_admin` numbers (cap 1); OPTIMIZE / BACKUP / RESTORE / scratch DROP |
+ *
+ * Producer: `ClickHouseDatabase` mints a Secrets-Manager password per
+ * framework identity (OUTSIDE the customer `managedPasswords` set — these
+ * secrets are never injected into the ClickHouse service container, so
+ * adopting them changes no ClickHouse task definition) and
+ * `getMigrationContributions()` emits `CLICKHOUSE_FRAMEWORK_USERS` (a
+ * JSON-stringified array of the names below) plus a `USER_<NAME>_PASSWORD`
+ * import per identity on the migration task.
+ *
+ * Consumer: `@fjall/clickhouse § provisionFrameworkUsersFromEnv` runs as
+ * `schemaAdmin` from the pre-scale-up lifecycle hook — ordered ahead of every
+ * gate and sidecar — and issues the idempotent CREATE / ALTER / GRANT set for
+ * each identity, so the identities exist before anything authenticates as
+ * them. SQL-provisioned (not `users.xml`) deliberately: no ClickHouse
+ * restart, no `SYSTEM RELOAD USERS` race, zero outage on adoption.
+ *
+ * Coupled values — must move together per
+ * `.claude/rules/code-quality.md § "Coupled values: shared source at 2
+ * occurrences"`.
+ */
+import { z } from "zod";
+/** Read-only identity the materialised schema gate authenticates as. */
+export declare const FJALL_SCHEMA_GATE_USER: "fjall_schema_gate";
+/** Identity the backup + optimise maintenance sidecars authenticate as. */
+export declare const FJALL_MAINTENANCE_USER: "fjall_maintenance";
+/**
+ * Every framework-owned identity, in provisioning order. Derive from this —
+ * never re-list the names — so a new workload class lands in the manifest,
+ * the reserved-name validator, and the provisioning loop at once.
+ */
+export declare const FJALL_CLICKHOUSE_USERS: readonly ["fjall_schema_gate", "fjall_maintenance"];
+export type FjallClickHouseUser = (typeof FJALL_CLICKHOUSE_USERS)[number];
+/**
+ * Prefix reserved for framework identities. `ClickHouseDatabase` throws at
+ * synth when a customer `schemaAdmin.name` or `managedPasswords` entry
+ * starts with it, so a customer user can never collide with (or be silently
+ * re-provisioned as) a framework identity.
+ */
+export declare const FJALL_CLICKHOUSE_USER_PREFIX: "fjall_";
+export declare function isReservedClickHouseUserName(name: string): boolean;
+/**
+ * Container env var name carrying the JSON-stringified manifest of framework
+ * identities to provision. Sibling to `CLICKHOUSE_MANAGED_USERS` (customer
+ * users); kept separate because the two sets differ in ownership — the
+ * framework decides its identities' rights, customer SQL decides the managed
+ * users' profiles.
+ */
+export declare const CLICKHOUSE_FRAMEWORK_USERS_ENV: "CLICKHOUSE_FRAMEWORK_USERS";
+/**
+ * Container env var name carrying the settings-profile name the maintenance
+ * identity binds to — the construct contributes `schemaAdmin.profile` (the
+ * `ddl_admin` profile at the resolved instance's scale), so
+ * `fjall_maintenance` inherits today's memory / execution caps and tracks
+ * instance resizes without the runner knowing any numbers. The runner pins
+ * `max_concurrent_queries_for_user = 1 CONST` on top: a bare setting is a
+ * default the session can override, only `CONST` makes the cap binding.
+ */
+export declare const CLICKHOUSE_MAINTENANCE_PROFILE_ENV: "CLICKHOUSE_MAINTENANCE_PROFILE";
+export declare const FrameworkUserNameSchema: z.ZodString & z.ZodType<"fjall_schema_gate" | "fjall_maintenance", string, z.core.$ZodTypeInternals<"fjall_schema_gate" | "fjall_maintenance", string>>;
+export type FrameworkUserName = z.infer<typeof FrameworkUserNameSchema>;
+export declare const FrameworkUserNamesSchema: z.ZodArray<z.ZodString & z.ZodType<"fjall_schema_gate" | "fjall_maintenance", string, z.core.$ZodTypeInternals<"fjall_schema_gate" | "fjall_maintenance", string>>>;
+export type FrameworkUserNames = z.infer<typeof FrameworkUserNamesSchema>;
+/**
+ * Scratch database the backup sidecar restores into to verify a backup, and
+ * the only database `fjall_maintenance` may DROP. Coupled across the
+ * construct (backup script, IAM) and `@fjall/clickhouse` (the GRANT set) —
+ * a drift would grant DROP on a database the script never touches while the
+ * one it does touch fails with `ACCESS_DENIED`.
+ */
+export declare const CLICKHOUSE_BACKUP_SCRATCH_DATABASE: "fjall_backup_verify";

package/dist/migration/clickhouseFrameworkUsers.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var E=(e,o)=>r(e,"name",{value:o,configurable:!0});import{z as _}from"zod";import{MANAGED_USER_NAME_PATTERN as s}from"./clickhouseSqlUsers.js";const S="fjall_schema_gate",a="fjall_maintenance",t=[S,a],A="fjall_";function L(e){return e.startsWith(A)}E(L,"isReservedClickHouseUserName");const N="CLICKHOUSE_FRAMEWORK_USERS",m="CLICKHOUSE_MAINTENANCE_PROFILE",n=new Set(t),C=_.string().regex(s,"Must be lowercase snake_case").refine(e=>n.has(e),{message:`Must be one of ${t.join(", ")}`}),p=_.array(C),I="fjall_backup_verify";export{I as CLICKHOUSE_BACKUP_SCRATCH_DATABASE,N as CLICKHOUSE_FRAMEWORK_USERS_ENV,m as CLICKHOUSE_MAINTENANCE_PROFILE_ENV,t as FJALL_CLICKHOUSE_USERS,A as FJALL_CLICKHOUSE_USER_PREFIX,a as FJALL_MAINTENANCE_USER,S as FJALL_SCHEMA_GATE_USER,C as FrameworkUserNameSchema,p as FrameworkUserNamesSchema,L as isReservedClickHouseUserName};

package/dist/migration/clickhouseFrameworkUsers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/migration/clickhouseFrameworkUsers.test.js

@@ -0,0 +1 @@
+import{describe as a,expect as e,it as s}from"vitest";import{CLICKHOUSE_FRAMEWORK_USERS_ENV as f,FJALL_CLICKHOUSE_USER_PREFIX as C,FJALL_CLICKHOUSE_USERS as c,FJALL_MAINTENANCE_USER as l,FJALL_SCHEMA_GATE_USER as h,FrameworkUserNamesSchema as d,isReservedClickHouseUserName as n}from"./clickhouseFrameworkUsers.js";import{MANAGED_USER_NAME_PATTERN as A}from"./clickhouseSqlUsers.js";import{CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS as S,buildControlPlaneActivityQuery as r}from"./controlPlaneActivity.js";import{SCHEMA_GATE_EXIT as i,SCHEMA_GATE_EXIT_HINTS as y,schemaGateExitKind as m}from"./schemaGateExit.js";import{sleepAbortable as E}from"./sleepAbortable.js";a("framework ClickHouse identities",()=>{s("every framework identity carries the reserved prefix and is a valid SQL name",()=>{for(const t of c)e(n(t)).toBe(!0),e(t).toMatch(A);e(c).toEqual([h,l])}),s("customer names outside the prefix are not reserved",()=>{e(n("schema_admin")).toBe(!1),e(n("backup_reader")).toBe(!1),e(n(`${C}x`)).toBe(!0)}),s("the manifest schema accepts only framework identities",()=>{e(d.safeParse([...c]).success).toBe(!0),e(d.safeParse(["fjall_other"]).success).toBe(!1),e(d.safeParse(["schema_admin"]).success).toBe(!1),e(f).toBe("CLICKHOUSE_FRAMEWORK_USERS")})}),a("schema gate exit taxonomy",()=>{s("codes are distinct and every kind has a hint",()=>{const t=Object.values(i);e(new Set(t).size).toBe(t.length);for(const o of Object.keys(i))e(y[o].length).toBeGreaterThan(0),e(m(i[o])).toBe(o)}),s("pins the wire values consumers already depend on",()=>{e(i).toEqual({pass:0,refused:1,configError:2,connectionError:3,busy:4,denied:5})}),s("returns undefined for codes the gate never emits",()=>{e(m(143)).toBeUndefined(),e(m(137)).toBeUndefined()})}),a("buildControlPlaneActivityQuery",()=>{s("probes both live processes and recent query_log for the named users",()=>{const t=r({users:["schema_admin",l]});e(t).toContain("FROM system.processes WHERE user IN ('schema_admin', 'fjall_maintenance')"),e(t).toContain("FROM system.query_log WHERE user IN ('schema_admin', 'fjall_maintenance')"),e(t).toContain(`INTERVAL ${S} SECOND`),e(t).toContain("type != 'QueryStart'"),e(t).toContain("event_date >= yesterday()"),e(t.trim().endsWith("AS active")).toBe(!0)}),s("honours a recency override",()=>{e(r({users:["schema_admin"],recencySeconds:5})).toContain("INTERVAL 5 SECOND")}),s("rejects names that could smuggle quoting, empty user lists, and bad recency",()=>{e(()=>r({users:["x' OR 1=1 --"]})).toThrow(/Invalid ClickHouse user name/),e(()=>r({users:[]})).toThrow(/at least one user/),e(()=>r({users:["a"],recencySeconds:0})).toThrow(/positive integer/)})}),a("sleepAbortable",()=>{s("resolves immediately on an already-aborted signal and on abort mid-sleep",async()=>{const t=new AbortController;t.abort(),await e(E(6e4,t.signal)).resolves.toBeUndefined();const o=new AbortController,u=Date.now(),_=E(6e4,o.signal);o.abort(),await _,e(Date.now()-u).toBeLessThan(1e3)})});

package/dist/migration/constants.d.ts

@@ -36,13 +36,13 @@ export declare const EXPECTED_SCHEMA_VERSION_TOOL_ENV: "EXPECTED_SCHEMA_VERSION_
 export declare const EXPECTED_CH_SCHEMA_VERSION_ENV: "EXPECTED_CH_SCHEMA_VERSION";
 /**
  * Container env / secret names for the ClickHouse schema-admin user contributed
- * by `ClickHouseDatabase`. Both the migration task AND every connected service
- * whose `connections:` includes a migration-declaring CH database receive
- * these, so the boot-time schema gate can authenticate against
- * `_schema_migrations`. Drift between the framework injection site, the
- * migration runner, and the boot gate would mask a missing-credential failure
- * as a generic "schema version mismatch" — hoisted to one site so all three
- * always read from the same name.
+ * by `ClickHouseDatabase`. Injected ONLY into the migration task (the sole
+ * DDL principal) — never into app containers, the gate container, or the
+ * maintenance sidecars, each of which authenticates as its own workload-class
+ * identity (see `clickhouseFrameworkUsers.ts`). One XML principal shared by
+ * six holders under a `max_concurrent_queries_for_user = 1` cap was the
+ * 2026-08-25 deploy-rollback incident: a gate probe lost the slot to the
+ * scheduled OPTIMIZE and reported the server "unreachable".
  */
 export declare const SCHEMA_ADMIN_USER_ENV: "SCHEMA_ADMIN_USER";
 export declare const SCHEMA_ADMIN_PASSWORD_ENV: "SCHEMA_ADMIN_PASSWORD";
@@ -76,6 +76,28 @@ export declare const SCHEMA_GATE_DB_PASSWORD_ENV: "FJALL_SCHEMA_GATE_DB_PASSWORD
 export declare const SCHEMA_GATE_CH_URL_ENV: "CLICKHOUSE_URL";
 export declare const SCHEMA_GATE_CH_DATABASE_ENV: "CLICKHOUSE_DATABASE";
 export declare const SCHEMA_GATE_CH_CA_CERT_ENV: "CLICKHOUSE_CA_CERT";
+/**
+ * ClickHouse credential env names for the gate container's CH half. The
+ * value of `SCHEMA_GATE_CH_USER_ENV` is always `FJALL_SCHEMA_GATE_USER` (the
+ * read-only gate identity), and `SCHEMA_GATE_CH_PASSWORD_ENV` is a
+ * Secrets-Manager import of that identity's password. Named in the
+ * `FJALL_SCHEMA_GATE_*` family alongside the Postgres trio so a reader of the
+ * task definition sees one gate contract, not a gate half and a borrowed
+ * admin half.
+ */
+export declare const SCHEMA_GATE_CH_USER_ENV: "FJALL_SCHEMA_GATE_CH_USER";
+export declare const SCHEMA_GATE_CH_PASSWORD_ENV: "FJALL_SCHEMA_GATE_CH_PASSWORD";
+/**
+ * ECS `startTimeout` for the synthetic gate container — the ceiling ECS
+ * allows the gate to reach its exit before the task is stopped as a failed
+ * start. The gate runner derives its own retry budget FROM this value (it
+ * must finish, with a verdict, comfortably inside it), so the two are coupled
+ * across the construct↔runner boundary: a construct that raised the timeout
+ * without the runner widening its budget would leave headroom unused; a
+ * runner budget exceeding the timeout would be cut off mid-retry with no
+ * verdict at all. Hoisted so both read one number.
+ */
+export declare const SCHEMA_GATE_START_TIMEOUT_SECONDS: 120;
 /**
  * The synthetic gate container's reserved name. Shared between the construct
  * (container synthesis + the name-collision validator in `validateEcsProps`)

package/dist/migration/constants.js

@@ -1 +1 @@
-const E="fjall-premigrate",_="EXPECTED_SCHEMA_VERSION",A="EXPECTED_SCHEMA_VERSION_TOOL",S="EXPECTED_CH_SCHEMA_VERSION",C="SCHEMA_ADMIN_USER",t="SCHEMA_ADMIN_PASSWORD",o="FJALL_SCHEMA_GATE_DB_URL_BASE",M="FJALL_SCHEMA_GATE_DB_USER",R="FJALL_SCHEMA_GATE_DB_PASSWORD",H="CLICKHOUSE_URL",I="CLICKHOUSE_DATABASE",N="CLICKHOUSE_CA_CERT",T="fjall-schema-gate",e="fjall/schema-gate",O="public.ecr.aws/fjall/schema-gate",s=/^\d{14}_/,c=/\.dev\.sql$/,D=/\.sql$/;export{D as CLICKHOUSE_MIGRATION_FILE_RE,c as CLICKHOUSE_MIGRATION_SKIP_RE,S as EXPECTED_CH_SCHEMA_VERSION_ENV,_ as EXPECTED_SCHEMA_VERSION_ENV,A as EXPECTED_SCHEMA_VERSION_TOOL_ENV,E as MIGRATION_SNAPSHOT_NAME_PREFIX,s as PRISMA_MIGRATION_DIR_RE,t as SCHEMA_ADMIN_PASSWORD_ENV,C as SCHEMA_ADMIN_USER_ENV,N as SCHEMA_GATE_CH_CA_CERT_ENV,I as SCHEMA_GATE_CH_DATABASE_ENV,H as SCHEMA_GATE_CH_URL_ENV,T as SCHEMA_GATE_CONTAINER_NAME,R as SCHEMA_GATE_DB_PASSWORD_ENV,o as SCHEMA_GATE_DB_URL_BASE_ENV,M as SCHEMA_GATE_DB_USER_ENV,e as SCHEMA_GATE_ECR_REPO_NAME,O as SCHEMA_GATE_PUBLIC_IMAGE_REPO};
+const _="fjall-premigrate",E="EXPECTED_SCHEMA_VERSION",A="EXPECTED_SCHEMA_VERSION_TOOL",S="EXPECTED_CH_SCHEMA_VERSION",C="SCHEMA_ADMIN_USER",t="SCHEMA_ADMIN_PASSWORD",o="FJALL_SCHEMA_GATE_DB_URL_BASE",H="FJALL_SCHEMA_GATE_DB_USER",M="FJALL_SCHEMA_GATE_DB_PASSWORD",R="CLICKHOUSE_URL",T="CLICKHOUSE_DATABASE",N="CLICKHOUSE_CA_CERT",I="FJALL_SCHEMA_GATE_CH_USER",e="FJALL_SCHEMA_GATE_CH_PASSWORD",O=120,s="fjall-schema-gate",c="fjall/schema-gate",D="public.ecr.aws/fjall/schema-gate",r=/^\d{14}_/,p=/\.dev\.sql$/,L=/\.sql$/;export{L as CLICKHOUSE_MIGRATION_FILE_RE,p as CLICKHOUSE_MIGRATION_SKIP_RE,S as EXPECTED_CH_SCHEMA_VERSION_ENV,E as EXPECTED_SCHEMA_VERSION_ENV,A as EXPECTED_SCHEMA_VERSION_TOOL_ENV,_ as MIGRATION_SNAPSHOT_NAME_PREFIX,r as PRISMA_MIGRATION_DIR_RE,t as SCHEMA_ADMIN_PASSWORD_ENV,C as SCHEMA_ADMIN_USER_ENV,N as SCHEMA_GATE_CH_CA_CERT_ENV,T as SCHEMA_GATE_CH_DATABASE_ENV,e as SCHEMA_GATE_CH_PASSWORD_ENV,R as SCHEMA_GATE_CH_URL_ENV,I as SCHEMA_GATE_CH_USER_ENV,s as SCHEMA_GATE_CONTAINER_NAME,M as SCHEMA_GATE_DB_PASSWORD_ENV,o as SCHEMA_GATE_DB_URL_BASE_ENV,H as SCHEMA_GATE_DB_USER_ENV,c as SCHEMA_GATE_ECR_REPO_NAME,D as SCHEMA_GATE_PUBLIC_IMAGE_REPO,O as SCHEMA_GATE_START_TIMEOUT_SECONDS};

package/dist/migration/controlPlaneActivity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ClickHouse-native activity probe for the migrate ↔ maintenance mutex.
+ *
+ * The migration task (Compute stack) and the maintenance sidecars (Database
+ * stack) cannot see each other through ECS — the Database stack is deployed
+ * first and cannot reference the Compute stack — so the mutual exclusion is
+ * observed through the server both already talk to: `system.processes`
+ * (queries running right now) plus `system.query_log` recency (a query that
+ * finished within the last `recencySeconds`). Each side asks about the OTHER
+ * control-plane identity and defers while it is active:
+ *
+ * - the maintenance wrapper asks about `schemaAdmin.name` before OPTIMIZE /
+ *   BACKUP and exits `deferred` (exit 0, metric) when a migration is under way;
+ * - the migration runner asks about `fjall_maintenance` before its ClickHouse
+ *   phase and waits (bounded, abort-aware) for the sidecar to go idle.
+ *
+ * The recency window closes the gap between one statement of a multi-
+ * statement job finishing and the next one starting (there is no process
+ * row in between). Both sides read the same builder so the two halves of
+ * the mutex cannot drift in what "active" means.
+ *
+ * `system.query_log` is flushed on an interval (7500 ms in the constructs'
+ * server config), so the recency signal lands up to one flush late; the
+ * residual window is the sub-second gap between a process row vanishing and
+ * its finish row landing, and the two identities carry separate concurrency
+ * caps, so a probe that slips through it costs contention, never a 202. Two
+ * server-side preconditions keep the recency half honest: the table only
+ * exists after the first flush (a brand-new server answers `Code: 60` until
+ * then — the probe's own queries create it inside one interval, which is why
+ * `awaitControlPlaneIdle` keeps polling through non-denied errors), and
+ * `log_queries_min_query_duration_ms` must stay 0 (see `clickhouseTuning`),
+ * else short control-plane statements never reach the log at all.
+ *
+ * The caller's own identity is never in `users`, so no self-exclusion is
+ * needed; the probe is a plain SELECT the gate/maintenance/admin identities
+ * are all granted on `system.processes` and `system.query_log`.
+ */
+/**
+ * How long after a control-plane query completes the identity is still
+ * considered active. Long enough to bridge a sidecar's per-statement gaps
+ * (the backup script runs DROP → BACKUP → RESTORE back-to-back), short
+ * enough that a finished job releases the mutex well inside one deploy.
+ */
+export declare const CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS: 120;
+export interface ControlPlaneActivityQueryOpts {
+    /** Identities to test for activity — the OTHER side of the mutex. */
+    users: readonly string[];
+    /** Overrides `CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS`. */
+    recencySeconds?: number;
+}
+/**
+ * Builds a single-row `SELECT active` returning `1` when any of `users` has
+ * a running query or finished one within the recency window, else `0`.
+ * Names are validated against the managed-user pattern before interpolation
+ * — the only quoting the SQL needs — so a name that could carry a quote
+ * never reaches the string.
+ */
+export declare function buildControlPlaneActivityQuery(opts: ControlPlaneActivityQueryOpts): string;

package/dist/migration/controlPlaneActivity.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var o=(e,r)=>s(e,"name",{value:r,configurable:!0});import{MANAGED_USER_NAME_PATTERN as i}from"./clickhouseSqlUsers.js";const E=120;function y(e){const r=e.recencySeconds??E;if(!Number.isInteger(r)||r<=0)throw new Error(`recencySeconds must be a positive integer, got ${String(r)}`);if(e.users.length===0)throw new Error("buildControlPlaneActivityQuery needs at least one user");for(const t of e.users)if(!i.test(t))throw new Error(`Invalid ClickHouse user name for activity probe: ${t}`);const n=e.users.map(t=>`'${t}'`).join(", ");return["SELECT toUInt8(",`  (SELECT count() FROM system.processes WHERE user IN (${n})) > 0`,"  OR",`  (SELECT count() FROM system.query_log WHERE user IN (${n})`,"     AND event_date >= yesterday()","     AND type != 'QueryStart'",`     AND event_time >= now() - INTERVAL ${r} SECOND) > 0`,") AS active"].join(`
+`)}o(y,"buildControlPlaneActivityQuery");export{E as CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS,y as buildControlPlaneActivityQuery};

package/dist/migration/index.d.ts

@@ -1,6 +1,10 @@
-export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV, SCHEMA_ADMIN_USER_ENV, SCHEMA_ADMIN_PASSWORD_ENV, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_DB_USER_ENV, SCHEMA_GATE_DB_PASSWORD_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_ECR_REPO_NAME, SCHEMA_GATE_PUBLIC_IMAGE_REPO, PRISMA_MIGRATION_DIR_RE, CLICKHOUSE_MIGRATION_SKIP_RE } from "./constants.js";
+export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV, SCHEMA_ADMIN_USER_ENV, SCHEMA_ADMIN_PASSWORD_ENV, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_DB_USER_ENV, SCHEMA_GATE_DB_PASSWORD_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CH_USER_ENV, SCHEMA_GATE_CH_PASSWORD_ENV, SCHEMA_GATE_START_TIMEOUT_SECONDS, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_ECR_REPO_NAME, SCHEMA_GATE_PUBLIC_IMAGE_REPO, PRISMA_MIGRATION_DIR_RE, CLICKHOUSE_MIGRATION_SKIP_RE } from "./constants.js";
 export { pickLatestPrismaMigration } from "./pickLatestPrismaMigration.js";
 export { pickLatestClickHouseMigration } from "./pickLatestClickHouseMigration.js";
 export { isOrderableSchemaVersion, isSchemaVersionSatisfied } from "./compareSchemaVersion.js";
 export { type MigrationsSqlClient, type VerifyExpectedSchemaVersionOpts, type VerifyExpectedSchemaVersionResult, verifyExpectedSchemaVersion } from "./verifyExpectedSchemaVersion.js";
 export { CLICKHOUSE_MANAGED_USERS_ENV, MANAGED_USER_NAME_PATTERN, userPasswordEnvName, ManagedUserNameSchema, ManagedUserNamesSchema, type ManagedUserName, type ManagedUserNames } from "./clickhouseSqlUsers.js";
+export { FJALL_SCHEMA_GATE_USER, FJALL_MAINTENANCE_USER, FJALL_CLICKHOUSE_USERS, FJALL_CLICKHOUSE_USER_PREFIX, isReservedClickHouseUserName, CLICKHOUSE_FRAMEWORK_USERS_ENV, CLICKHOUSE_MAINTENANCE_PROFILE_ENV, CLICKHOUSE_BACKUP_SCRATCH_DATABASE, FrameworkUserNameSchema, FrameworkUserNamesSchema, type FjallClickHouseUser, type FrameworkUserName, type FrameworkUserNames } from "./clickhouseFrameworkUsers.js";
+export { SCHEMA_GATE_EXIT, SCHEMA_GATE_EXIT_HINTS, schemaGateExitKind, type SchemaGateExitKind, type SchemaGateExitCode } from "./schemaGateExit.js";
+export { CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS, buildControlPlaneActivityQuery, type ControlPlaneActivityQueryOpts } from "./controlPlaneActivity.js";
+export { sleepAbortable } from "./sleepAbortable.js";

package/dist/migration/index.js

@@ -1 +1 @@
-import{MIGRATION_SNAPSHOT_NAME_PREFIX as A,EXPECTED_SCHEMA_VERSION_ENV as S,EXPECTED_SCHEMA_VERSION_TOOL_ENV as N,EXPECTED_CH_SCHEMA_VERSION_ENV as e,SCHEMA_ADMIN_USER_ENV as C,SCHEMA_ADMIN_PASSWORD_ENV as M,SCHEMA_GATE_DB_URL_BASE_ENV as r,SCHEMA_GATE_DB_USER_ENV as R,SCHEMA_GATE_DB_PASSWORD_ENV as H,SCHEMA_GATE_CH_URL_ENV as T,SCHEMA_GATE_CH_DATABASE_ENV as a,SCHEMA_GATE_CH_CA_CERT_ENV as I,SCHEMA_GATE_CONTAINER_NAME as o,SCHEMA_GATE_ECR_REPO_NAME as V,SCHEMA_GATE_PUBLIC_IMAGE_REPO as O,PRISMA_MIGRATION_DIR_RE as i,CLICKHOUSE_MIGRATION_SKIP_RE as s}from"./constants.js";import{pickLatestPrismaMigration as G}from"./pickLatestPrismaMigration.js";import{pickLatestClickHouseMigration as t}from"./pickLatestClickHouseMigration.js";import{isOrderableSchemaVersion as U,isSchemaVersionSatisfied as c}from"./compareSchemaVersion.js";import{verifyExpectedSchemaVersion as f}from"./verifyExpectedSchemaVersion.js";import{CLICKHOUSE_MANAGED_USERS_ENV as L,MANAGED_USER_NAME_PATTERN as x,userPasswordEnvName as d,ManagedUserNameSchema as B,ManagedUserNamesSchema as h}from"./clickhouseSqlUsers.js";export{L as CLICKHOUSE_MANAGED_USERS_ENV,s as CLICKHOUSE_MIGRATION_SKIP_RE,e as EXPECTED_CH_SCHEMA_VERSION_ENV,S as EXPECTED_SCHEMA_VERSION_ENV,N as EXPECTED_SCHEMA_VERSION_TOOL_ENV,x as MANAGED_USER_NAME_PATTERN,A as MIGRATION_SNAPSHOT_NAME_PREFIX,B as ManagedUserNameSchema,h as ManagedUserNamesSchema,i as PRISMA_MIGRATION_DIR_RE,M as SCHEMA_ADMIN_PASSWORD_ENV,C as SCHEMA_ADMIN_USER_ENV,I as SCHEMA_GATE_CH_CA_CERT_ENV,a as SCHEMA_GATE_CH_DATABASE_ENV,T as SCHEMA_GATE_CH_URL_ENV,o as SCHEMA_GATE_CONTAINER_NAME,H as SCHEMA_GATE_DB_PASSWORD_ENV,r as SCHEMA_GATE_DB_URL_BASE_ENV,R as SCHEMA_GATE_DB_USER_ENV,V as SCHEMA_GATE_ECR_REPO_NAME,O as SCHEMA_GATE_PUBLIC_IMAGE_REPO,U as isOrderableSchemaVersion,c as isSchemaVersionSatisfied,t as pickLatestClickHouseMigration,G as pickLatestPrismaMigration,d as userPasswordEnvName,f as verifyExpectedSchemaVersion};
+import{MIGRATION_SNAPSHOT_NAME_PREFIX as A,EXPECTED_SCHEMA_VERSION_ENV as S,EXPECTED_SCHEMA_VERSION_TOOL_ENV as C,EXPECTED_CH_SCHEMA_VERSION_ENV as e,SCHEMA_ADMIN_USER_ENV as N,SCHEMA_ADMIN_PASSWORD_ENV as r,SCHEMA_GATE_DB_URL_BASE_ENV as T,SCHEMA_GATE_DB_USER_ENV as M,SCHEMA_GATE_DB_PASSWORD_ENV as R,SCHEMA_GATE_CH_URL_ENV as H,SCHEMA_GATE_CH_DATABASE_ENV as I,SCHEMA_GATE_CH_CA_CERT_ENV as o,SCHEMA_GATE_CH_USER_ENV as a,SCHEMA_GATE_CH_PASSWORD_ENV as O,SCHEMA_GATE_START_TIMEOUT_SECONDS as m,SCHEMA_GATE_CONTAINER_NAME as U,SCHEMA_GATE_ECR_REPO_NAME as s,SCHEMA_GATE_PUBLIC_IMAGE_REPO as t,PRISMA_MIGRATION_DIR_RE as L,CLICKHOUSE_MIGRATION_SKIP_RE as i}from"./constants.js";import{pickLatestPrismaMigration as G}from"./pickLatestPrismaMigration.js";import{pickLatestClickHouseMigration as D}from"./pickLatestClickHouseMigration.js";import{isOrderableSchemaVersion as p,isSchemaVersionSatisfied as f}from"./compareSchemaVersion.js";import{verifyExpectedSchemaVersion as n}from"./verifyExpectedSchemaVersion.js";import{CLICKHOUSE_MANAGED_USERS_ENV as F,MANAGED_USER_NAME_PATTERN as d,userPasswordEnvName as h,ManagedUserNameSchema as l,ManagedUserNamesSchema as B}from"./clickhouseSqlUsers.js";import{FJALL_SCHEMA_GATE_USER as k,FJALL_MAINTENANCE_USER as u,FJALL_CLICKHOUSE_USERS as b,FJALL_CLICKHOUSE_USER_PREFIX as g,isReservedClickHouseUserName as v,CLICKHOUSE_FRAMEWORK_USERS_ENV as J,CLICKHOUSE_MAINTENANCE_PROFILE_ENV as W,CLICKHOUSE_BACKUP_SCRATCH_DATABASE as w,FrameworkUserNameSchema as y,FrameworkUserNamesSchema as Y}from"./clickhouseFrameworkUsers.js";import{SCHEMA_GATE_EXIT as j,SCHEMA_GATE_EXIT_HINTS as q,schemaGateExitKind as z}from"./schemaGateExit.js";import{CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS as $,buildControlPlaneActivityQuery as EE}from"./controlPlaneActivity.js";import{sleepAbortable as AE}from"./sleepAbortable.js";export{w as CLICKHOUSE_BACKUP_SCRATCH_DATABASE,J as CLICKHOUSE_FRAMEWORK_USERS_ENV,W as CLICKHOUSE_MAINTENANCE_PROFILE_ENV,F as CLICKHOUSE_MANAGED_USERS_ENV,i as CLICKHOUSE_MIGRATION_SKIP_RE,$ as CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS,e as EXPECTED_CH_SCHEMA_VERSION_ENV,S as EXPECTED_SCHEMA_VERSION_ENV,C as EXPECTED_SCHEMA_VERSION_TOOL_ENV,b as FJALL_CLICKHOUSE_USERS,g as FJALL_CLICKHOUSE_USER_PREFIX,u as FJALL_MAINTENANCE_USER,k as FJALL_SCHEMA_GATE_USER,y as FrameworkUserNameSchema,Y as FrameworkUserNamesSchema,d as MANAGED_USER_NAME_PATTERN,A as MIGRATION_SNAPSHOT_NAME_PREFIX,l as ManagedUserNameSchema,B as ManagedUserNamesSchema,L as PRISMA_MIGRATION_DIR_RE,r as SCHEMA_ADMIN_PASSWORD_ENV,N as SCHEMA_ADMIN_USER_ENV,o as SCHEMA_GATE_CH_CA_CERT_ENV,I as SCHEMA_GATE_CH_DATABASE_ENV,O as SCHEMA_GATE_CH_PASSWORD_ENV,H as SCHEMA_GATE_CH_URL_ENV,a as SCHEMA_GATE_CH_USER_ENV,U as SCHEMA_GATE_CONTAINER_NAME,R as SCHEMA_GATE_DB_PASSWORD_ENV,T as SCHEMA_GATE_DB_URL_BASE_ENV,M as SCHEMA_GATE_DB_USER_ENV,s as SCHEMA_GATE_ECR_REPO_NAME,j as SCHEMA_GATE_EXIT,q as SCHEMA_GATE_EXIT_HINTS,t as SCHEMA_GATE_PUBLIC_IMAGE_REPO,m as SCHEMA_GATE_START_TIMEOUT_SECONDS,EE as buildControlPlaneActivityQuery,p as isOrderableSchemaVersion,v as isReservedClickHouseUserName,f as isSchemaVersionSatisfied,D as pickLatestClickHouseMigration,G as pickLatestPrismaMigration,z as schemaGateExitKind,AE as sleepAbortable,h as userPasswordEnvName,n as verifyExpectedSchemaVersion};

package/dist/migration/schemaGateExit.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Exit taxonomy for the materialised schema-gate container
+ * (`@fjall/schema-gate`). The dependent app containers declare
+ * `dependsOn: [{ container: "fjall-schema-gate", condition: "SUCCESS" }]`, so
+ * ANY non-zero exit stops the task pre-RUNNING and counts toward the
+ * deployment circuit breaker — the codes exist for the forensic log and the
+ * deploy-time ECS tail, not for ECS itself.
+ *
+ * Lives in `@fjall/util` because three packages must agree on it: the gate
+ * runner emits the codes, `@fjall/deploy-core`'s deployment tail translates
+ * them into one human line, and the constructs' docs cite them. Coupled
+ * values across package boundaries — a drift would have the tail describe
+ * an exit the runner never emits.
+ *
+ * - `pass` (0) — every configured target verified; app containers start.
+ * - `refused` (1) — a target's live schema does not satisfy the expected
+ *   version (forward skew, or a never-migrated database). The gate did its
+ *   job; the deploy must roll back or the migration must land first.
+ * - `configError` (2) — the gate could not even attempt verification:
+ *   missing/empty env, unsupported tool or engine family, or an internal
+ *   error. Points at a construct bug or an author override.
+ * - `connectionError` (3) — the server could not be reached after the
+ *   bounded retry budget (network, TLS, timeout). Indeterminate: the schema
+ *   may be fine.
+ * - `busy` (4) — the server was reachable and answered every attempt, but
+ *   refused to run the probe because a concurrency cap or quota was
+ *   exhausted (ClickHouse `TOO_MANY_SIMULTANEOUS_QUERIES` 202 /
+ *   `QUOTA_EXCEEDED` 201, Postgres `too_many_connections` 53300 /
+ *   `cannot_connect_now` 57P03) for the whole budget. Indeterminate, and
+ *   distinct from `connectionError` because the cure is different: the
+ *   server is healthy and something else holds the slot.
+ * - `denied` (5) — the server was reachable and rejected the gate's
+ *   identity or its rights (auth failure, unknown user, missing grant,
+ *   read-only violation). Definitive: no retry will change it, and the fix
+ *   is provisioning, not capacity.
+ *
+ * Precedence when targets disagree: `configError` is detected before any
+ * connection is attempted; then `refused` (definitive evidence), then
+ * `denied` (definitive), then `busy`, then `connectionError` (both
+ * indeterminate; `busy` carries the more specific cure).
+ */
+export declare const SCHEMA_GATE_EXIT: {
+    readonly pass: 0;
+    readonly refused: 1;
+    readonly configError: 2;
+    readonly connectionError: 3;
+    readonly busy: 4;
+    readonly denied: 5;
+};
+export type SchemaGateExitKind = keyof typeof SCHEMA_GATE_EXIT;
+export type SchemaGateExitCode = (typeof SCHEMA_GATE_EXIT)[SchemaGateExitKind];
+/**
+ * One human line per exit kind, for the deploy-time ECS tail and forensic
+ * logs. Keyed on the taxonomy so adding an exit kind without a hint is a
+ * compile error (`Record<SchemaGateExitKind, string>` rejects a missing key).
+ */
+export declare const SCHEMA_GATE_EXIT_HINTS: Record<SchemaGateExitKind, string>;
+/**
+ * Inverse lookup for the deployment tail: an ECS container exit code → the
+ * taxonomy kind, or `undefined` for a code the gate never emits (a signal
+ * exit such as 143, or an OOM 137).
+ */
+export declare function schemaGateExitKind(code: number): SchemaGateExitKind | undefined;

package/dist/migration/schemaGateExit.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,r)=>o(e,"name",{value:r,configurable:!0});const a={pass:0,refused:1,configError:2,connectionError:3,busy:4,denied:5},i={pass:"schema gate passed",refused:"schema gate refused: live schema does not satisfy the expected version \u2014 land the migration or roll back",configError:"schema gate could not run: missing or invalid gate configuration \u2014 check the task definition's FJALL_SCHEMA_GATE_* env",connectionError:"schema gate could not reach the database within its budget \u2014 check network reachability and database health",busy:"schema gate was refused a query slot for its whole budget \u2014 the database is healthy; another workload holds the concurrency cap or quota",denied:"schema gate identity was rejected \u2014 the gate user's credentials or grants are wrong; re-run the migration task to re-provision it"},s=new Map(Object.keys(a).map(e=>[a[e],e]));function c(e){return s.get(e)}t(c,"schemaGateExitKind");export{a as SCHEMA_GATE_EXIT,i as SCHEMA_GATE_EXIT_HINTS,c as schemaGateExitKind};

package/dist/migration/sleepAbortable.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Promise-based sleep that short-circuits when the supplied abort signal
+ * fires. Poll and retry loops that can be running when a shutdown signal
+ * arrives (SIGTERM in a worker, an ECS stop of the gate container) MUST use
+ * this for inter-attempt delays so the signal does not stall for the full
+ * sleep. Resolves (never rejects) on abort; callers check `signal.aborted`
+ * after waking. Shared by `@fjall/clickhouse`, `@fjall/schema-gate` and
+ * `@fjall/deploy-core`.
+ */
+export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/migration/sleepAbortable.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var r=(t,e)=>u(t,"name",{value:e,configurable:!0});function m(t,e){return e?.aborted===!0?Promise.resolve():new Promise(o=>{const i=setTimeout(()=>{e?.removeEventListener("abort",n),o()},t),n=r(()=>{clearTimeout(i),o()},"onAbort");e?.addEventListener("abort",n,{once:!0})})}r(m,"sleepAbortable");export{m as sleepAbortable};

package/dist/patterns/frameworkPatterns.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The framework vocabulary and its bridge to the pattern vocabulary.
+ *
+ * Detection answers "what did the author build this with?" (`Framework`).
+ * Creation asks "which shape does Fjall deploy?" (`PatternType`). Those are
+ * different questions with different membership, and until this module nothing
+ * joined them: `apps detect` reported `astro`, the agent skill told the agent to
+ * feed what detect reported straight into `--pattern`, and `--pattern astro`
+ * reached `PATTERN_REGISTRY[...]` as an unchecked index and threw a `TypeError`
+ * that surfaced to the agent as `code: UNKNOWN`. Five of the seven framework
+ * values had no pattern at all; the join existed only in the skill's prose.
+ *
+ * `FRAMEWORK_PATTERN_RECOMMENDATIONS` is the compiler's checklist for that
+ * join. It is a `Record<Framework, PatternRecommendation>`, so an eighth
+ * framework fails to compile until someone states what it means for
+ * `--pattern` — the same discipline `PATTERN_REGISTRY` applies to patterns.
+ *
+ * The three verdicts are deliberately distinct, because they are three
+ * different instructions to hand an agent mid-onboarding:
+ *
+ * - `recommended` — a deployable pattern fits; proceed with it.
+ * - `blocked`     — the pattern exists but cannot deploy yet; stop, and say why.
+ * - `unsupported` — no pattern shape fits this framework; stop, and say so.
+ *
+ * `recommended` and `blocked` are separated at the *type* level rather than by
+ * author discipline: their `pattern` fields are mapped types filtered on the
+ * registry's own `deployable` flag, in the same idiom as `OpenNextPatternType`.
+ * Flipping `nextjs` to `deployable: true` makes `UndeployablePatternType`
+ * uninhabited and breaks the `blocked` entry, forcing it to be moved rather
+ * than left behind as a lie. The reverse holds too: a pattern that loses its
+ * construct cannot stay in `recommended`.
+ */
+import { PATTERN_REGISTRY, type PatternType, type PatternCreateInput } from "./patternTypes.js";
+/**
+ * Every framework the detector can name.
+ *
+ * This vocabulary lives here rather than in `@fjall/generator` because the
+ * bridge below needs both halves in one place, and `generator` already depends
+ * on `@fjall/util` (never the reverse). `generator/src/detection` re-exports
+ * these names and builds the Zod schema over them, exactly as it already does
+ * for `STATIC_SITE_ROUTING_VALUES`.
+ *
+ * - `nextjs+payload` is a strict superset of both its parts and must be
+ *   matched before either: Payload v3 ships as a Next.js plugin, so both
+ *   dependencies appear in a Payload app.
+ * - `unknown` is a real member, not an absence — a repository with a parseable
+ *   `package.json` and no recognised signal is still a detection result.
+ */
+export declare const FRAMEWORK_VALUES: readonly ["nextjs", "payload", "nextjs+payload", "express", "remix", "astro", "unknown"];
+export type Framework = (typeof FRAMEWORK_VALUES)[number];
+export declare const FRAMEWORKS: ReadonlySet<string>;
+export declare function isFramework(value: unknown): value is Framework;
+/**
+ * The patterns that can deploy end-to-end, derived from the registry's own
+ * flag at the type level. `DEPLOYABLE_PATTERN_TYPES` is the value-level twin.
+ */
+export type DeployablePatternType = {
+    [K in PatternType]: (typeof PATTERN_REGISTRY)[K]["deployable"] extends true ? K : never;
+}[PatternType];
+/**
+ * The patterns the generator knows but cannot yet synthesise. Uninhabited once
+ * every pattern is deployable — at which point the `blocked` verdict below
+ * stops compiling, which is the intended signal, not a defect.
+ */
+export type UndeployablePatternType = {
+    [K in PatternType]: (typeof PATTERN_REGISTRY)[K]["deployable"] extends false ? K : never;
+}[PatternType];
+/**
+ * What a detected framework means for `--pattern`.
+ *
+ * Every arm carries prose because every arm is read aloud to a user by an
+ * agent. A verdict an agent cannot explain is a verdict it will second-guess,
+ * and second-guessing is what the "do not infer the pattern" instruction in the
+ * skill exists to prevent.
+ */
+export type PatternRecommendation = {
+    readonly kind: "recommended";
+    /** Constrained to deployable patterns by the registry's own flag. */
+    readonly pattern: DeployablePatternType;
+    /** Why this pattern fits, in the agent's own words to the user. */
+    readonly rationale: string;
+} | {
+    readonly kind: "blocked";
+    /** Constrained to patterns the registry marks undeployable. */
+    readonly pattern: UndeployablePatternType;
+    /** What is missing, so the agent can say more than "no". */
+    readonly reason: string;
+} | {
+    readonly kind: "unsupported";
+    /** Why no pattern fits this framework's shape. */
+    readonly reason: string;
+};
+/**
+ * The framework → pattern join.
+ *
+ * This is the *evidence-free* verdict: it knows only the framework name. A
+ * detector holding more evidence (an Astro config declaring `output: "server"`,
+ * say) returns the same union with a different arm — that is a refinement of
+ * one contract, not a second framing path.
+ */
+export declare const FRAMEWORK_PATTERN_RECOMMENDATIONS: {
+    readonly astro: {
+        readonly kind: "recommended";
+        readonly pattern: "staticsite";
+        readonly rationale: "Astro builds to a directory of static assets, which is what the static-site pattern serves from S3 behind CloudFront.";
+    };
+    readonly payload: {
+        readonly kind: "recommended";
+        readonly pattern: "payload";
+        readonly rationale: "Payload CMS runs on OpenNext with a database and migrations, which the payload pattern provisions.";
+    };
+    readonly "nextjs+payload": {
+        readonly kind: "recommended";
+        readonly pattern: "payload";
+        readonly rationale: "Payload v3 ships as a Next.js plugin, so a repository carrying both dependencies is a Payload application and deploys as one.";
+    };
+    readonly nextjs: {
+        readonly kind: "blocked";
+        readonly pattern: "nextjs";
+        readonly reason: "The Next.js pattern has no CDK construct yet — IPatternProps omits it, so a generated app fails at synthesis. Deploy a Payload application, or supply a static export with --pattern staticsite.";
+    };
+    readonly remix: {
+        readonly kind: "unsupported";
+        readonly reason: "Remix serves from a Node server at request time; Fjall has no server-rendering pattern beyond OpenNext, and no static-export path from Remix.";
+    };
+    readonly express: {
+        readonly kind: "unsupported";
+        readonly reason: "Express is a long-running HTTP server. Fjall's patterns cover OpenNext applications and pre-built static sites; neither shape fits.";
+    };
+    readonly unknown: {
+        readonly kind: "unsupported";
+        readonly reason: "No framework signal was found in package.json. If this is a pre-built static site, pass --pattern staticsite explicitly with --source, --build-command and --output-dir.";
+    };
+};
+/**
+ * The evidence-free verdict for a framework. Total by construction — there is
+ * no undefined branch to guard, which is the whole point of the record above.
+ */
+export declare function recommendPatternForFramework(framework: Framework): PatternRecommendation;
+/**
+ * The frameworks an agent can carry all the way to a deploy today, derived
+ * from the table rather than restated. Used by the skill's vocabulary block so
+ * its prose cannot drift from the join.
+ */
+export declare const CREATABLE_FRAMEWORKS: readonly Framework[];
+/**
+ * The inputs a framework's recommended pattern still needs from the caller.
+ * Empty for anything not `recommended` — there is nothing to collect for a
+ * pattern that cannot be created.
+ */
+export declare function requiredInputsForFramework(framework: Framework): readonly PatternCreateInput[];

package/dist/patterns/frameworkPatterns.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var a=(e,t)=>o(e,"name",{value:t,configurable:!0});import{PATTERN_REGISTRY as s}from"./patternTypes.js";const r=["nextjs","payload","nextjs+payload","express","remix","astro","unknown"],i=new Set(r);function c(e){return typeof e=="string"&&i.has(e)}a(c,"isFramework");const n={astro:{kind:"recommended",pattern:"staticsite",rationale:"Astro builds to a directory of static assets, which is what the static-site pattern serves from S3 behind CloudFront."},payload:{kind:"recommended",pattern:"payload",rationale:"Payload CMS runs on OpenNext with a database and migrations, which the payload pattern provisions."},"nextjs+payload":{kind:"recommended",pattern:"payload",rationale:"Payload v3 ships as a Next.js plugin, so a repository carrying both dependencies is a Payload application and deploys as one."},nextjs:{kind:"blocked",pattern:"nextjs",reason:"The Next.js pattern has no CDK construct yet \u2014 IPatternProps omits it, so a generated app fails at synthesis. Deploy a Payload application, or supply a static export with --pattern staticsite."},remix:{kind:"unsupported",reason:"Remix serves from a Node server at request time; Fjall has no server-rendering pattern beyond OpenNext, and no static-export path from Remix."},express:{kind:"unsupported",reason:"Express is a long-running HTTP server. Fjall's patterns cover OpenNext applications and pre-built static sites; neither shape fits."},unknown:{kind:"unsupported",reason:"No framework signal was found in package.json. If this is a pre-built static site, pass --pattern staticsite explicitly with --source, --build-command and --output-dir."}};function l(e){return n[e]}a(l,"recommendPatternForFramework");const m=r.filter(e=>n[e].kind==="recommended");function u(e){const t=n[e];return t.kind==="recommended"?s[t.pattern].requiredCreateInputs:[]}a(u,"requiredInputsForFramework");export{m as CREATABLE_FRAMEWORKS,i as FRAMEWORKS,n as FRAMEWORK_PATTERN_RECOMMENDATIONS,r as FRAMEWORK_VALUES,c as isFramework,l as recommendPatternForFramework,u as requiredInputsForFramework};

package/dist/patterns/index.d.ts

@@ -7,5 +7,6 @@
  * the webapp bundles) can take the vocabulary without depending on the root
  * barrel's contents staying pure.
  */
-export { PATTERN_TYPE_VALUES, type PatternType, PATTERN_TYPES, isPatternType, type PatternArtefact, type PatternStackPlacement, type PatternDescriptor, PATTERN_REGISTRY, patternConstructId, DEPLOYABLE_PATTERN_TYPES, type OpenNextPatternType, OPENNEXT_PATTERN_TYPES, isOpenNextPatternType, STATIC_SITE_ROUTING_VALUES, type StaticSiteRouting } from "./patternTypes.js";
+export { PATTERN_TYPE_VALUES, type PatternType, PATTERN_TYPES, isPatternType, type PatternArtefact, type PatternStackPlacement, type PatternDescriptor, PATTERN_REGISTRY, patternConstructId, DEPLOYABLE_PATTERN_TYPES, type OpenNextPatternType, OPENNEXT_PATTERN_TYPES, isOpenNextPatternType, STATIC_SITE_ROUTING_VALUES, type StaticSiteRouting, PATTERN_CREATE_INPUT_VALUES, type PatternCreateInput, PATTERN_CREATE_INPUT_FLAGS } from "./patternTypes.js";
+export { FRAMEWORK_VALUES, type Framework, FRAMEWORKS, isFramework, type DeployablePatternType, type UndeployablePatternType, type PatternRecommendation, FRAMEWORK_PATTERN_RECOMMENDATIONS, recommendPatternForFramework, CREATABLE_FRAMEWORKS, requiredInputsForFramework } from "./frameworkPatterns.js";
 export { DEFAULT_FORMS_FROM_LOCAL_PART, defaultFormsFromAddress, defaultFormsCorsOrigin, isAddressAtDomain } from "./staticSiteForms.js";

package/dist/patterns/index.js

@@ -1 +1 @@
-import{PATTERN_TYPE_VALUES as r,PATTERN_TYPES as A,isPatternType as _,PATTERN_REGISTRY as t,patternConstructId as P,DEPLOYABLE_PATTERN_TYPES as e,OPENNEXT_PATTERN_TYPES as s,isOpenNextPatternType as R,STATIC_SITE_ROUTING_VALUES as o}from"./patternTypes.js";import{DEFAULT_FORMS_FROM_LOCAL_PART as S,defaultFormsFromAddress as O,defaultFormsCorsOrigin as d,isAddressAtDomain as n}from"./staticSiteForms.js";export{S as DEFAULT_FORMS_FROM_LOCAL_PART,e as DEPLOYABLE_PATTERN_TYPES,s as OPENNEXT_PATTERN_TYPES,t as PATTERN_REGISTRY,A as PATTERN_TYPES,r as PATTERN_TYPE_VALUES,o as STATIC_SITE_ROUTING_VALUES,d as defaultFormsCorsOrigin,O as defaultFormsFromAddress,n as isAddressAtDomain,R as isOpenNextPatternType,_ as isPatternType,P as patternConstructId};
+import{PATTERN_TYPE_VALUES as A,PATTERN_TYPES as r,isPatternType as R,PATTERN_REGISTRY as _,patternConstructId as e,DEPLOYABLE_PATTERN_TYPES as P,OPENNEXT_PATTERN_TYPES as o,isOpenNextPatternType as t,STATIC_SITE_ROUTING_VALUES as F,PATTERN_CREATE_INPUT_VALUES as N,PATTERN_CREATE_INPUT_FLAGS as S}from"./patternTypes.js";import{FRAMEWORK_VALUES as s,FRAMEWORKS as m,isFramework as L,FRAMEWORK_PATTERN_RECOMMENDATIONS as a,recommendPatternForFramework as n,CREATABLE_FRAMEWORKS as d,requiredInputsForFramework as I}from"./frameworkPatterns.js";import{DEFAULT_FORMS_FROM_LOCAL_PART as p,defaultFormsFromAddress as C,defaultFormsCorsOrigin as M,isAddressAtDomain as U}from"./staticSiteForms.js";export{d as CREATABLE_FRAMEWORKS,p as DEFAULT_FORMS_FROM_LOCAL_PART,P as DEPLOYABLE_PATTERN_TYPES,m as FRAMEWORKS,a as FRAMEWORK_PATTERN_RECOMMENDATIONS,s as FRAMEWORK_VALUES,o as OPENNEXT_PATTERN_TYPES,S as PATTERN_CREATE_INPUT_FLAGS,N as PATTERN_CREATE_INPUT_VALUES,_ as PATTERN_REGISTRY,r as PATTERN_TYPES,A as PATTERN_TYPE_VALUES,F as STATIC_SITE_ROUTING_VALUES,M as defaultFormsCorsOrigin,C as defaultFormsFromAddress,U as isAddressAtDomain,L as isFramework,t as isOpenNextPatternType,R as isPatternType,e as patternConstructId,n as recommendPatternForFramework,I as requiredInputsForFramework};

package/dist/patterns/patternTypes.d.ts

@@ -31,6 +31,26 @@ export type PatternArtefact = "opennext-lambda" | "static-assets";
  * Lambda (and usually a database) and belong in the compute stack.
  */
 export type PatternStackPlacement = "compute" | "cdn";
+/**
+ * Create-time inputs a pattern cannot invent for itself.
+ *
+ * A static site is built from someone else's repository, so Fjall cannot guess
+ * where the sources live, how they build, or which directory to upload — get
+ * `outputDir` wrong and the deploy succeeds onto an empty bucket. Declaring the
+ * set here rather than in the create handler's control flow is what lets the
+ * CLI refuse the command with a list of missing flags instead of surfacing a
+ * raw Zod issue array, and lets `apps detect` prefill exactly the values the
+ * chosen pattern will be asked for.
+ */
+export declare const PATTERN_CREATE_INPUT_VALUES: readonly ["source", "buildCommand", "outputDir"];
+export type PatternCreateInput = (typeof PATTERN_CREATE_INPUT_VALUES)[number];
+/** The CLI flag each input arrives on. Kept beside the vocabulary so error
+ * messages name a flag the user can actually type. */
+export declare const PATTERN_CREATE_INPUT_FLAGS: {
+    readonly source: "--source";
+    readonly buildCommand: "--build-command";
+    readonly outputDir: "--output-dir";
+};
 export interface PatternDescriptor {
     /** Human-facing name, used by the CLI picker and progress output. */
     readonly label: string;
@@ -48,6 +68,12 @@ export interface PatternDescriptor {
      * adding the construct.
      */
     readonly deployable: boolean;
+    /**
+     * Inputs the caller must supply for this pattern; the create flow refuses
+     * the command when any are absent. Empty for patterns whose scaffold is
+     * generated wholesale and therefore knows its own layout.
+     */
+    readonly requiredCreateInputs: readonly PatternCreateInput[];
 }
 export declare const PATTERN_REGISTRY: {
     readonly payload: {
@@ -56,6 +82,7 @@ export declare const PATTERN_REGISTRY: {
         readonly artefact: "opennext-lambda";
         readonly stackPlacement: "compute";
         readonly deployable: true;
+        readonly requiredCreateInputs: readonly [];
     };
     readonly nextjs: {
         readonly label: "Next.js";
@@ -63,6 +90,7 @@ export declare const PATTERN_REGISTRY: {
         readonly artefact: "opennext-lambda";
         readonly stackPlacement: "compute";
         readonly deployable: false;
+        readonly requiredCreateInputs: readonly [];
     };
     readonly staticsite: {
         readonly label: "Static site";
@@ -70,6 +98,7 @@ export declare const PATTERN_REGISTRY: {
         readonly artefact: "static-assets";
         readonly stackPlacement: "cdn";
         readonly deployable: true;
+        readonly requiredCreateInputs: readonly ["source", "buildCommand", "outputDir"];
     };
 };
 /**

package/dist/patterns/patternTypes.js

@@ -1 +1 @@
-var c=Object.defineProperty;var e=(t,a)=>c(t,"name",{value:a,configurable:!0});import{toPascalCase as s}from"../naming/caseConversion.js";const n=["payload","nextjs","staticsite"],r=new Set(n);function E(t){return typeof t=="string"&&r.has(t)}e(E,"isPatternType");const o={payload:{label:"Payload CMS",constructIdSuffix:"Payload",artefact:"opennext-lambda",stackPlacement:"compute",deployable:!0},nextjs:{label:"Next.js",constructIdSuffix:"Nextjs",artefact:"opennext-lambda",stackPlacement:"compute",deployable:!1},staticsite:{label:"Static site",constructIdSuffix:"StaticSite",artefact:"static-assets",stackPlacement:"cdn",deployable:!0}};function P(t,a){return`${s(t)}${o[a].constructIdSuffix}`}e(P,"patternConstructId");const f=n.filter(t=>o[t].deployable),l=n.filter(t=>o[t].artefact==="opennext-lambda"),p=new Set(l);function x(t){return t!=null&&p.has(t)}e(x,"isOpenNextPatternType");const d=["multipage","spa"];export{f as DEPLOYABLE_PATTERN_TYPES,l as OPENNEXT_PATTERN_TYPES,o as PATTERN_REGISTRY,r as PATTERN_TYPES,n as PATTERN_TYPE_VALUES,d as STATIC_SITE_ROUTING_VALUES,x as isOpenNextPatternType,E as isPatternType,P as patternConstructId};
+var n=Object.defineProperty;var e=(t,o)=>n(t,"name",{value:o,configurable:!0});import{toPascalCase as s}from"../naming/caseConversion.js";const a=["payload","nextjs","staticsite"],c=new Set(a);function l(t){return typeof t=="string"&&c.has(t)}e(l,"isPatternType");const d=["source","buildCommand","outputDir"],E={source:"--source",buildCommand:"--build-command",outputDir:"--output-dir"},r={payload:{label:"Payload CMS",constructIdSuffix:"Payload",artefact:"opennext-lambda",stackPlacement:"compute",deployable:!0,requiredCreateInputs:[]},nextjs:{label:"Next.js",constructIdSuffix:"Nextjs",artefact:"opennext-lambda",stackPlacement:"compute",deployable:!1,requiredCreateInputs:[]},staticsite:{label:"Static site",constructIdSuffix:"StaticSite",artefact:"static-assets",stackPlacement:"cdn",deployable:!0,requiredCreateInputs:["source","buildCommand","outputDir"]}};function P(t,o){return`${s(t)}${r[o].constructIdSuffix}`}e(P,"patternConstructId");const x=a.filter(t=>r[t].deployable),u=a.filter(t=>r[t].artefact==="opennext-lambda"),p=new Set(u);function f(t){return t!=null&&p.has(t)}e(f,"isOpenNextPatternType");const S=["multipage","spa"];export{x as DEPLOYABLE_PATTERN_TYPES,u as OPENNEXT_PATTERN_TYPES,E as PATTERN_CREATE_INPUT_FLAGS,d as PATTERN_CREATE_INPUT_VALUES,r as PATTERN_REGISTRY,c as PATTERN_TYPES,a as PATTERN_TYPE_VALUES,S as STATIC_SITE_ROUTING_VALUES,f as isOpenNextPatternType,l as isPatternType,P as patternConstructId};

package/dist/scaffold/ensureGitignore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Idempotently guarantee that a `.gitignore` in `directory` carries `entries`.
+ *
+ * Absent file → written with `header` followed by the entries. Existing file →
+ * only the missing entries are appended, under `marker` so the addition is
+ * attributable. An entry already present anywhere in the file (at any
+ * indentation) is left alone, so repeat calls are no-ops.
+ *
+ * Best-effort by design: this maintains repository hygiene, never correctness.
+ * The caller's real work — writing config or recording deploy state — must not
+ * fail because a `.gitignore` could not be written (read-only checkout, no
+ * repository at all, permissions). Returns whether the file now provably
+ * carries every entry, for callers that want to assert or log.
+ */
+export declare function ensureGitignoreEntries(directory: string, entries: readonly string[], options: {
+    header?: string;
+    marker: string;
+}): boolean;

package/dist/scaffold/ensureGitignore.js

@@ -0,0 +1,9 @@
+var d=Object.defineProperty;var u=(o,e)=>d(o,"name",{value:e,configurable:!0});import i from"fs";import g from"path";function l(o,e,s){const t=g.join(o,".gitignore");try{const r=i.existsSync(t)?i.readFileSync(t,"utf8"):void 0;if(r===void 0){const n=s.header??"";return i.writeFileSync(t,`${n}${e.join(`
+`)}
+`,{encoding:"utf8"}),!0}const a=new Set(r.split(`
+`).map(n=>n.trim())),c=e.filter(n=>!a.has(n));if(c.length===0)return!0;const f=r===""||r.endsWith(`
+`)?"":`
+`;return i.appendFileSync(t,`${f}${s.marker}
+${c.join(`
+`)}
+`,"utf8"),!0}catch{return!1}}u(l,"ensureGitignoreEntries");export{l as ensureGitignoreEntries};