@facilis.dev/db 0.0.0-stage → 0.1.1

package/dist/views.js

@@ -0,0 +1,186 @@
+// Declarative SQL views (D-097/D-098, SPEC §11.2).
+//
+// A view is code: db/views/*.ts declares it with defineView(), and the framework emits
+// CREATE OR REPLACE VIEW at boot (dev); production provisioning is the deploy step's job.
+// Two modes (D-098):
+// - no permission: security_invoker = true, so the base tables' RLS applies as facilis_app;
+// - with a permission: security_invoker = false (definer), and that permission is the only
+//   gate — the view is a table-like resource whose access is its declared permission.
+// The permission predicate is inlined in the DDL, so its name is validated first.
+import { sql } from "drizzle-orm";
+import { PgDialect, pgView, } from "drizzle-orm/pg-core";
+import { APP_ROLE } from "./policy.js";
+import { isReadOnlySql, stripTrailingSemicolon } from "./read-only-sql.js";
+/** Brand carrier for a view object, so a declaration is recognisable from its export. */
+export const VIEW_BRAND = Symbol.for("facilis.db.view");
+/** SQL view names are unquoted identifiers; generated code always satisfies this. */
+export const VIEW_NAME_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+/** A view's own permission, when declared. Same identifier shape the config uses. */
+export const VIEW_PERMISSION_PATTERN = /^[a-z][a-z0-9:_-]{0,63}$/;
+/** A declaration that cannot become a database view; the code reaches the dev endpoint. */
+export class ViewDefinitionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ViewDefinitionError";
+        this.code = code;
+    }
+}
+const dialect = new PgDialect();
+/**
+ * Declare a SQL view. Never throws: an invalid declaration is reported when the framework
+ * tries to create it, so a typo in db/views cannot take the dev server down at import time.
+ */
+export function defineView(options) {
+    const view = pgView(options.name, options.columns).existing();
+    const permission = options.permission ?? null;
+    const metadata = {
+        name: options.name,
+        query: options.query,
+        tables: options.tables ?? [],
+        permission,
+        access: permission === null ? "invoker" : "definer",
+    };
+    Object.defineProperty(view, VIEW_BRAND, { value: metadata, enumerable: false });
+    return view;
+}
+/** The declaration carried by a view object, when `value` is one. */
+export function viewMetadata(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const metadata = Reflect.get(value, VIEW_BRAND);
+    if (typeof metadata !== "object" || metadata === null)
+        return null;
+    const record = metadata;
+    if (typeof record["name"] !== "string")
+        return null;
+    if (!isSql(record["query"]))
+        return null;
+    const tables = record["tables"];
+    const permission = record["permission"];
+    const declaredPermission = typeof permission === "string" ? permission : null;
+    return {
+        name: record["name"],
+        query: record["query"],
+        tables: Array.isArray(tables)
+            ? tables.filter((entry) => typeof entry === "string")
+            : [],
+        permission: declaredPermission,
+        access: declaredPermission === null ? "invoker" : "definer",
+    };
+}
+export function isFacilisView(value) {
+    return viewMetadata(value) !== null;
+}
+/**
+ * Declarations in one or more module namespaces, deduplicated by name (first wins).
+ * A module namespace can export anything, so non-view exports are skipped.
+ */
+export function collectViewMetadata(modules) {
+    const namespaces = Array.isArray(modules) ? modules : [modules];
+    const byName = new Map();
+    for (const namespace of namespaces) {
+        for (const value of Object.values(namespace)) {
+            const metadata = viewMetadata(value);
+            if (metadata !== null && !byName.has(metadata.name))
+                byName.set(metadata.name, metadata);
+        }
+    }
+    return [...byName.values()];
+}
+/**
+ * CREATE OR REPLACE VIEW for a declaration. Rejects a non-identifier name and a query
+ * that is not a single static read-only statement: the SQL is inlined into the DDL, so
+ * this check is the boundary, not a style rule.
+ */
+export function viewCreateStatement(metadata) {
+    return viewDefinitionStatement(metadata.name, metadata.query, metadata.permission ?? undefined);
+}
+/**
+ * CREATE OR REPLACE VIEW for a raw SQL text (the query console's create-view flow).
+ *
+ * With a permission the view is a definer view whose only gate is that permission: the
+ * outer wrapper applies it to any query shape, and the permission name is validated before
+ * it is inlined (the DDL has no bind parameters, by construction).
+ */
+export function viewDefinitionStatement(name, query, permission) {
+    if (!VIEW_NAME_PATTERN.test(name)) {
+        throw new ViewDefinitionError("invalid_name", "A view name must match ^[a-z][a-z0-9_]{0,62}$ (lowercase letters, digits, underscore).");
+    }
+    if (permission !== undefined && !VIEW_PERMISSION_PATTERN.test(permission)) {
+        throw new ViewDefinitionError("invalid_permission", "A view permission must match ^[a-z][a-z0-9:_-]{0,63}$ (lowercase letters, digits, :, _, -).");
+    }
+    const text = typeof query === "string" ? stripTrailingSemicolon(query) : compileStaticQuery(query);
+    if (!isReadOnlySql(text)) {
+        throw new ViewDefinitionError("invalid_sql", "A view query must be one static read-only statement (SELECT, WITH, VALUES or TABLE).");
+    }
+    if (permission === undefined) {
+        return sql `create or replace view ${sql.identifier(name)} with (security_invoker = true) as ${sql.raw(text)}`;
+    }
+    return sql `create or replace view ${sql.identifier(name)} with (security_invoker = false) as select * from (${sql.raw(text)}) as "q" where nullif(current_setting('app.permissions', true), '')::jsonb ? ${sql.raw(`'${permission}'`)}`;
+}
+/** Grants SELECT on a view to the policy-scoped app role. Idempotent. */
+export async function grantViewSelect(db, name) {
+    await db.db.execute(sql `grant select on ${sql.identifier(name)} to ${sql.identifier(APP_ROLE)}`);
+}
+/**
+ * Creates every declared view, then retries the failures once: a view may select from
+ * another view declared later in the same module. A failure is data, never a throw, so a
+ * broken view degrades to a manifest warning like every other boot step.
+ */
+export async function applyViews(db, modules, options = {}) {
+    const definitions = collectViewMetadata(modules);
+    const declared = options.permissions === undefined ? null : new Set(options.permissions);
+    const created = [];
+    const failures = new Map();
+    // An undeclared permission is a boot warning (view_failed), never a silent grant.
+    const allowed = definitions.filter((definition) => {
+        if (definition.permission === null || declared === null)
+            return true;
+        if (declared.has(definition.permission))
+            return true;
+        failures.set(definition.name, `permission "${definition.permission}" is not declared in facilis.config.ts auth.permissions`);
+        return false;
+    });
+    let pending = allowed;
+    for (let pass = 0; pass < 2 && pending.length > 0; pass += 1) {
+        const retry = [];
+        for (const definition of pending) {
+            try {
+                // oxlint-disable-next-line no-await-in-loop -- view creation is ordered: a view may select from one created earlier in this pass.
+                await db.db.execute(viewCreateStatement(definition));
+                // oxlint-disable-next-line no-await-in-loop -- the grant needs the view to exist; keep it right after its create.
+                await grantViewSelect(db, definition.name);
+                failures.delete(definition.name);
+                created.push(definition.name);
+            }
+            catch (error) {
+                retry.push(definition);
+                failures.set(definition.name, messageOf(error));
+            }
+        }
+        pending = pass === 0 ? retry : [];
+    }
+    return {
+        created,
+        failed: [...failures].map(([name, error]) => ({ name, error })),
+    };
+}
+/** Compile a literal SQL object and reject interpolated values (DDL has no parameters). */
+function compileStaticQuery(query) {
+    const compiled = dialect.sqlToQuery(query);
+    if (compiled.params.length > 0) {
+        throw new ViewDefinitionError("invalid_sql", "A view query must be static: values cannot be interpolated into it.");
+    }
+    return stripTrailingSemicolon(compiled.sql);
+}
+function isSql(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Array.isArray(value.queryChunks));
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/workflows.d.ts

@@ -0,0 +1,289 @@
+/** Every facilis_workflows.status value, in lifecycle order. */
+export declare const FACILIS_WORKFLOW_STATUSES: readonly ["running", "waiting", "succeeded", "failed", "cancelled"];
+export type FacilisWorkflowStatus = (typeof FACILIS_WORKFLOW_STATUSES)[number];
+/**
+ * One workflow instance. Statuses stay text (a new state is a code change, not a migration),
+ * progress holds completed-step entries, plan the step identities captured at start so a
+ * resume after a definition edit fails with workflow_definition_changed instead of guessing.
+ */
+export declare const facilisWorkflows: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "facilis_workflows";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        input: import("drizzle-orm/pg-core").PgColumn<{
+            name: "input";
+            tableName: "facilis_workflows";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        progress: import("drizzle-orm/pg-core").PgColumn<{
+            name: "progress";
+            tableName: "facilis_workflows";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        plan: import("drizzle-orm/pg-core").PgColumn<{
+            name: "plan";
+            tableName: "facilis_workflows";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        currentStep: import("drizzle-orm/pg-core").PgColumn<{
+            name: "current_step";
+            tableName: "facilis_workflows";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        currentJobId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "current_job_id";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        waitingTaskId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "waiting_task_id";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempts";
+            tableName: "facilis_workflows";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        output: import("drizzle-orm/pg-core").PgColumn<{
+            name: "output";
+            tableName: "facilis_workflows";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        error: import("drizzle-orm/pg-core").PgColumn<{
+            name: "error";
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        startedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "started_at";
+            tableName: "facilis_workflows";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        finishedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "finished_at";
+            tableName: "facilis_workflows";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "facilis_workflows";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "facilis_workflows";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type FacilisWorkflowRow = typeof facilisWorkflows.$inferSelect;
+export type NewFacilisWorkflowRow = typeof facilisWorkflows.$inferInsert;

package/dist/workflows.js

@@ -0,0 +1,55 @@
+// The workflow table (D-135, docs/WORKFLOWS.md §5).
+//
+// A workflow is framework state, not application data: tenant-scoped so the structural
+// invariant holds (pgPolicy + ENABLE ROW LEVEL SECURITY), re-exported by the project's
+// db/schema.ts, and DDL-owned by a Drizzle migration like the job queue (D-107).
+//
+// The chain itself is data: the runner advances rows with short compare-and-set writes and a
+// manual step waits on a facilis_tasks row, so no job body ever holds a transaction open.
+import { sql } from "drizzle-orm";
+import { index, integer, jsonb, pgPolicy, pgTable, text, timestamp, uuid, } from "drizzle-orm/pg-core";
+import { tenantIsolationPolicy } from "./rls.js";
+import { tenantColumn } from "./tenant-column.js";
+/** Every facilis_workflows.status value, in lifecycle order. */
+export const FACILIS_WORKFLOW_STATUSES = [
+    "running",
+    "waiting",
+    "succeeded",
+    "failed",
+    "cancelled",
+];
+/**
+ * One workflow instance. Statuses stay text (a new state is a code change, not a migration),
+ * progress holds completed-step entries, plan the step identities captured at start so a
+ * resume after a definition edit fails with workflow_definition_changed instead of guessing.
+ */
+export const facilisWorkflows = pgTable("facilis_workflows", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: text("name").notNull(),
+    status: text("status").notNull(),
+    input: jsonb("input").notNull(),
+    progress: jsonb("progress").notNull().default([]),
+    plan: jsonb("plan").notNull().default([]),
+    currentStep: integer("current_step").notNull().default(0),
+    currentJobId: uuid("current_job_id"),
+    waitingTaskId: uuid("waiting_task_id"),
+    attempts: integer("attempts").notNull().default(0),
+    output: jsonb("output"),
+    error: text("error"),
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    tenantId: tenantColumn(),
+}, (table) => [
+    tenantIsolationPolicy(),
+    // A RESTRICTIVE policy only narrows what a permissive policy already allows; with no
+    // permissive policy Postgres denies every row (D-008). The runner's writes run as
+    // facilis_app, so the scoped tenant needs this gate - exactly like facilis_jobs.
+    pgPolicy("facilis_workflows_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+    index("facilis_workflows_status_created_idx").on(table.status, table.createdAt),
+    index("facilis_workflows_name_idx").on(table.name),
+]).enableRLS();

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@facilis.dev/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Facilis database layer: Drizzle + PGlite client, RLS policy helpers and release diffing.",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "0.5.11",
+    "drizzle-orm": "0.45.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facilis-dev/facilis.git",
+    "directory": "packages/db"
+  },
+  "homepage": "https://github.com/facilis-dev/facilis/tree/main/packages/db#readme",
+  "bugs": {
+    "url": "https://github.com/facilis-dev/facilis/issues"
+  },
+  "keywords": [
+    "facilis",
+    "framework",
+    "vite",
+    "nitro",
+    "low-code"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}