@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/modules/database.js

@@ -0,0 +1,189 @@
+import { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_FUNCTION_SIGNATURE, WORKER_APP_GRANTS_MAX, WORKER_APP_TABLE_NAME, } from '../entry-rules.js';
+import { clone, list, omit, problem, withWorkerApp } from './entry-parts.js';
+const ADDRESS_HELP = 'From your Postgres provider. The owner can change tables; the app address is a separate user with less access. Use a different database for the workspace than for live.';
+const ADDRESS_MAX = 2000;
+const COPY_WORDS = { workspace: 'the workspace', live: 'live' };
+const ADDRESS_KEYS = {
+    workspace: { owner: 'workspaceOwnerUrl', app: 'workspaceAppUrl' },
+    live: { owner: 'liveOwnerUrl', app: 'liveAppUrl' },
+};
+const addressLabel = (copy, role) => `Database address for ${COPY_WORDS[copy]} (${role})`;
+const addressField = (copy, role) => ({
+    key: ADDRESS_KEYS[copy][role],
+    label: addressLabel(copy, role),
+    help: ADDRESS_HELP,
+    kind: 'secret',
+    required: true,
+    max: ADDRESS_MAX,
+    runtimes: ['worker'],
+});
+/** The user and the database (host, port, name) of a Postgres address, or null when it is not one. */
+function parseAddress(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'postgres:' && url.protocol !== 'postgresql:')
+        return null;
+    const name = url.pathname.replace(/^\//, '');
+    if (url.username === '' || url.hostname === '' || name === '' || name.includes('/'))
+        return null;
+    let user;
+    try {
+        user = decodeURIComponent(url.username);
+    }
+    catch {
+        return null;
+    }
+    return { user, place: `${url.hostname.toLowerCase()}:${url.port || '5432'}/${name}` };
+}
+/** One copy's addresses read and checked, with the database they reach; null when neither is given. */
+function readCopy(values, copy) {
+    const keys = ADDRESS_KEYS[copy];
+    const owner = values[keys.owner];
+    const app = values[keys.app];
+    const given = (value) => typeof value === 'string' && value !== '';
+    if (!given(owner) && !given(app))
+        return null;
+    if (!given(owner)) {
+        return problem(keys.owner, `"${addressLabel(copy, 'owner')}" is needed with the app address.`);
+    }
+    if (!given(app)) {
+        return problem(keys.app, `"${addressLabel(copy, 'app')}" is needed with the owner address.`);
+    }
+    const shape = (role) => `"${addressLabel(copy, role)}" is not a Postgres address. It starts with postgres:// or postgresql:// and names a user, a server and a database. Copy it again from your Postgres provider.`;
+    const ownerParts = parseAddress(owner);
+    if (!ownerParts)
+        return problem(keys.owner, shape('owner'));
+    const appParts = parseAddress(app);
+    if (!appParts)
+        return problem(keys.app, shape('app'));
+    if (ownerParts.user === appParts.user) {
+        return problem(keys.app, `The owner and app addresses for ${COPY_WORDS[copy]} use the same user. The app needs a separate user with less access.`);
+    }
+    if (ownerParts.place !== appParts.place) {
+        return problem(keys.app, `The app address for ${COPY_WORDS[copy]} reaches another database than the owner address. Both must reach the same database.`);
+    }
+    return { addresses: { ownerUrl: owner, runtimeUrl: app }, place: ownerParts.place };
+}
+/**
+ * The owner and runtime addresses of one copy's Postgres, for `applyWorkerAppMigrations` and `deployWorkerApp`
+ * (`database.url = runtimeUrl`). Null when the values give neither address of that copy; a problem, in plain
+ * words that never repeat an address, when one is missing, is not a Postgres address, uses the owner's user,
+ * or reaches another database than the owner.
+ */
+export function databaseAddressesOf(values, copy) {
+    const read = readCopy(values, copy);
+    if (read === null || 'message' in read)
+        return read;
+    return read.addresses;
+}
+/**
+ * A Postgres database for the app. A server app: `entry.database`. A Worker app: `workerApp.database`, reached
+ * through Hyperdrive, with its append-only tables and function grants. `migrationsSha256` is not a field: it
+ * comes from the build (`build.json`) and is kept as the entry holds it. A Worker app uses the company's own
+ * Postgres: an owner and an app address per copy, `secret` fields the caller holds and delivers itself. They
+ * never go into the entry, so `fromEntry` (and `modulesOf`) never gives them back.
+ */
+export const database = {
+    view: {
+        id: 'database',
+        name: 'Database',
+        line: "A database for the app's own records, kept safe with daily backups.",
+        category: 'Data',
+        icon: 'database',
+        runtimes: ['server', 'worker'],
+        requires: [],
+        availability: 'ready',
+        fields: [
+            addressField('workspace', 'owner'),
+            addressField('workspace', 'app'),
+            addressField('live', 'owner'),
+            addressField('live', 'app'),
+            {
+                key: 'appendOnly',
+                label: 'Tables that keep every row',
+                help: 'The app can add and read rows in these tables but never change or delete them, as for an audit trail. Only for apps that run as a Worker app.',
+                kind: 'list',
+                advanced: true,
+                pattern: WORKER_APP_TABLE_NAME.source,
+                max: WORKER_APP_APPEND_ONLY_MAX,
+            },
+            {
+                key: 'grants',
+                label: 'Database functions the app may run',
+                help: 'Functions your database setup locks down, written as name(type, ...), such as audit_chain_tail(). Only for apps that run as a Worker app.',
+                kind: 'list',
+                advanced: true,
+                pattern: WORKER_APP_FUNCTION_SIGNATURE.source,
+                max: WORKER_APP_GRANTS_MAX,
+            },
+        ],
+        adds: [
+            {
+                name: 'A Postgres database',
+                hint: 'Only this app reaches it. The app gets its address itself.',
+            },
+            { name: 'Backups', hint: 'A copy is made every day.' },
+        ],
+    },
+    check(values, _modules, ctx) {
+        if (ctx.runtime === 'server') {
+            for (const key of ['appendOnly', 'grants']) {
+                if (list(values, key) !== undefined) {
+                    return problem(key, 'Tables that keep every row and database functions can only be set for an app that runs as a Worker app.');
+                }
+            }
+            return null;
+        }
+        const workspace = readCopy(values, 'workspace');
+        if (workspace && 'message' in workspace)
+            return workspace;
+        const live = readCopy(values, 'live');
+        if (live && 'message' in live)
+            return live;
+        if (workspace && live && workspace.place === live.place) {
+            return problem(ADDRESS_KEYS.workspace.owner, 'The workspace and live use the same database. Use a different database for the workspace than for live.');
+        }
+        return null;
+    },
+    toEntry(entry, values, ctx) {
+        if (ctx.runtime === 'server') {
+            const next = clone(entry);
+            next.database = values !== null;
+            return next;
+        }
+        return withWorkerApp(entry, (app) => {
+            if (values === null)
+                return omit(app, 'database');
+            const next = {};
+            const appendOnly = list(values, 'appendOnly');
+            const grants = list(values, 'grants');
+            if (appendOnly)
+                next.appendOnly = appendOnly;
+            if (grants)
+                next.grants = grants;
+            const pinned = app.database?.migrationsSha256;
+            if (pinned !== undefined)
+                next.migrationsSha256 = pinned;
+            return { ...app, database: next };
+        });
+    },
+    fromEntry(entry) {
+        if (entry.workerApp) {
+            const db = entry.workerApp.database;
+            if (!db)
+                return null;
+            const values = {};
+            if (db.appendOnly?.length)
+                values.appendOnly = [...db.appendOnly];
+            if (db.grants?.length)
+                values.grants = [...db.grants];
+            return values;
+        }
+        return entry.database ? {} : null;
+    },
+};

package/dist/modules/email.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.mail`: the app sends mail from the company's mail domain. */
+export declare const email: AppModule;

package/dist/modules/email.js

@@ -0,0 +1,18 @@
+import { setUse } from './entry-parts.js';
+/** `uses.mail`: the app sends mail from the company's mail domain. */
+export const email = {
+    view: {
+        id: 'email',
+        name: 'Email',
+        line: "The app sends email from your company's address, such as receipts and notices.",
+        category: 'Messages',
+        icon: 'mail',
+        runtimes: ['server'],
+        requires: [],
+        availability: 'ready',
+        fields: [],
+        adds: [{ name: 'Sending email', hint: "From your company's own mail address." }],
+    },
+    toEntry: (entry, values) => setUse(entry, 'mail', values === null ? undefined : true),
+    fromEntry: (entry) => (entry.uses?.mail === true ? {} : null),
+};

package/dist/modules/entry-parts.d.ts

@@ -0,0 +1,23 @@
+import type { EntryAuth, HostingEntry, HostingEntryUses } from '../org.js';
+import type { WorkerAppConfig } from '../worker-app-config.js';
+import type { ModuleProblem, ModuleValue, ModuleValues } from './types.js';
+/** Helpers the modules share to change one part of an entry without touching the caller's copy. */
+export declare const clone: <T>(value: T) => T;
+/** A copy of `value` without `keys`. */
+export declare function omit<T extends object, K extends keyof T>(value: T, ...keys: K[]): Omit<T, K>;
+export declare const isProblem: (value: HostingEntry | ModuleProblem) => value is ModuleProblem;
+/** The entry with `uses` replaced; an empty `uses` is left out. */
+export declare function withUses(entry: HostingEntry, uses: HostingEntryUses): HostingEntry;
+/** The entry with `uses[key]` set, or removed when `value` is undefined. */
+export declare function setUse<K extends keyof HostingEntryUses>(entry: HostingEntry, key: K, value: HostingEntryUses[K] | undefined): HostingEntry;
+/** The entry with `uses.auth[key]` changed. Without `uses.auth` the entry comes back unchanged. */
+export declare function setAuthPart<K extends keyof EntryAuth>(entry: HostingEntry, key: K, value: EntryAuth[K] | undefined): HostingEntry;
+/** The entry with its `workerApp` replaced by `change`'s result. Without a `workerApp` the entry comes back unchanged. */
+export declare function withWorkerApp(entry: HostingEntry, change: (app: WorkerAppConfig) => WorkerAppConfig): HostingEntry;
+/** A text value, or undefined for an absent or empty one. */
+export declare function text(values: ModuleValues, key: string): string | undefined;
+/** A list value, or undefined for an absent or empty one. */
+export declare function list(values: ModuleValues, key: string): string[] | undefined;
+/** `values` without the keys whose value is undefined. */
+export declare function defined(values: Record<string, ModuleValue | undefined>): ModuleValues;
+export declare const problem: (field: string | null, message: string) => ModuleProblem;

package/dist/modules/entry-parts.js

@@ -0,0 +1,63 @@
+/** Helpers the modules share to change one part of an entry without touching the caller's copy. */
+export const clone = (value) => structuredClone(value);
+/** A copy of `value` without `keys`. */
+export function omit(value, ...keys) {
+    const drop = new Set(keys);
+    return Object.fromEntries(Object.entries(clone(value)).filter(([key]) => !drop.has(key)));
+}
+export const isProblem = (value) => 'message' in value && typeof value.message === 'string';
+/** The entry with `uses` replaced; an empty `uses` is left out. */
+export function withUses(entry, uses) {
+    if (Object.keys(uses).length === 0)
+        return omit(entry, 'uses');
+    return { ...clone(entry), uses };
+}
+/** The entry with `uses[key]` set, or removed when `value` is undefined. */
+export function setUse(entry, key, value) {
+    const uses = clone(entry.uses ?? {});
+    if (value === undefined)
+        delete uses[key];
+    else
+        uses[key] = value;
+    return withUses(entry, uses);
+}
+/** The entry with `uses.auth[key]` changed. Without `uses.auth` the entry comes back unchanged. */
+export function setAuthPart(entry, key, value) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return clone(entry);
+    const next = clone(auth);
+    if (value === undefined)
+        delete next[key];
+    else
+        next[key] = value;
+    return setUse(entry, 'auth', next);
+}
+/** The entry with its `workerApp` replaced by `change`'s result. Without a `workerApp` the entry comes back unchanged. */
+export function withWorkerApp(entry, change) {
+    if (!entry.workerApp)
+        return clone(entry);
+    return { ...clone(entry), workerApp: change(clone(entry.workerApp)) };
+}
+/** A text value, or undefined for an absent or empty one. */
+export function text(values, key) {
+    const value = values[key];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** A list value, or undefined for an absent or empty one. */
+export function list(values, key) {
+    const value = values[key];
+    return Array.isArray(value) && value.length > 0 ? [...value] : undefined;
+}
+/** `values` without the keys whose value is undefined. */
+export function defined(values) {
+    const out = {};
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+export const problem = (field, message) => ({
+    field,
+    message,
+});

package/dist/modules/files.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.files`: the app keeps files (uploads, documents) in folders of its own. */
+export declare const files: AppModule;

package/dist/modules/files.js

@@ -0,0 +1,64 @@
+import { FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS } from '../entry-rules.js';
+import { list, setUse } from './entry-parts.js';
+/** `uses.files`: the app keeps files (uploads, documents) in folders of its own. */
+export const files = {
+    view: {
+        id: 'files',
+        name: 'Files',
+        line: 'The app keeps files people upload, such as documents and pictures.',
+        category: 'Data',
+        icon: 'folder',
+        runtimes: ['server'],
+        requires: [],
+        availability: 'ready',
+        fields: [
+            {
+                key: 'collections',
+                label: 'Folders',
+                help: 'A name for each kind of file the app keeps, in capital letters, such as INVOICES or PHOTOS.',
+                kind: 'list',
+                required: true,
+                pattern: FILES_COLLECTION_NAME.source,
+            },
+            {
+                key: 'shareHost',
+                label: 'Share links on your own address',
+                help: 'Links to shared files start with share. and your domain. Needs your own domain.',
+                kind: 'switch',
+                advanced: true,
+                default: false,
+            },
+            {
+                key: 'permissions',
+                label: 'What the app may do with files',
+                help: 'Leave it empty to allow all of them.',
+                kind: 'list',
+                advanced: true,
+                choices: FILES_ENTRY_PERMISSIONS.map((value) => ({ value, label: value })),
+            },
+        ],
+        adds: [{ name: 'File storage', hint: 'Only this app reaches its folders.' }],
+    },
+    toEntry(entry, values) {
+        if (values === null)
+            return setUse(entry, 'files', undefined);
+        const next = { collections: list(values, 'collections') ?? [] };
+        const permissions = list(values, 'permissions');
+        if (permissions)
+            next.permissions = permissions;
+        if (values.shareHost === true)
+            next.shareHost = true;
+        return setUse(entry, 'files', next);
+    },
+    fromEntry(entry) {
+        const used = entry.uses?.files;
+        if (!used)
+            return null;
+        const values = { collections: [...used.collections] };
+        if (used.permissions?.length)
+            values.permissions = [...used.permissions];
+        if (used.shareHost !== undefined)
+            values.shareHost = used.shareHost;
+        return values;
+    },
+};

package/dist/modules/index.d.ts

@@ -0,0 +1,74 @@
+import type { HostingEntry } from '../org.js';
+import type { AppManifest, AppModule, AppModules, ManifestAnswer, ModuleContext, ModuleRefusal, ModuleView } from './types.js';
+export type * from './types.js';
+export { type DatabaseAddresses, type DatabaseCopy, databaseAddressesOf } from './database.js';
+/**
+ * Every module, in the order they are applied: a module comes after the ones it needs, so sign-in sets
+ * `uses.auth` before help for AI assistants and workspaces add to it.
+ */
+export declare const MODULES: readonly AppModule[];
+/** The views of every module, JSON-safe, for Boule to render. */
+export declare function modulesCatalogue(): ModuleView[];
+/**
+ * Null when the modules can be turned on together for an app on `ctx.runtime`; else the first problem, in
+ * words a company person can act on.
+ */
+export declare function checkModules(modules: AppModules, ctx: ModuleContext): ModuleRefusal | null;
+export type ApplyModulesResult = {
+    ok: true;
+    entry: HostingEntry;
+} | ({
+    ok: false;
+} & ModuleRefusal);
+/**
+ * `entry` with each module in `modules` set and every part an absent module owns removed. The rest of the
+ * entry (its build, address, env) is kept as it is. The caller still validates the whole company
+ * (`validateHosting`).
+ */
+export declare function applyModules(entry: HostingEntry, modules: AppModules, ctx: ModuleContext): ApplyModulesResult;
+/** The modules `entry` has, with their values: the inverse of {@link applyModules}. */
+export declare function modulesOf(entry: HostingEntry): AppModules;
+export type ParseAppManifestResult = {
+    ok: true;
+    /** Always v2: a v1 file is read as v2 with its fields mapped. */
+    manifest: AppManifest;
+    /** The version the file itself was written in. */
+    from: 1 | 2;
+} | {
+    ok: false;
+    message: string;
+};
+/** `company-app.json` (v1 or v2) read and checked: what the app's code asks for. */
+export declare function parseAppManifest(json: unknown): ParseAppManifestResult;
+export interface ManifestProblem {
+    /** The value's key, or null for a problem between them. */
+    key: string | null;
+    message: string;
+}
+/** What an install of the app is made from. Asked secrets are in `secrets`; hold them, never log them. */
+export interface ManifestInstall {
+    /** The modules with the answers that fill module fields applied. */
+    modules: AppModules;
+    /** Environment name -> plain text for the app: defaults and answers. A list is its items joined by ",". */
+    plain: Record<string, string>;
+    /** Environment name -> a secret the company typed. */
+    secrets: Record<string, string>;
+    /** Environment name -> how the platform makes it. */
+    generate: Record<string, 'token' | 'hex' | 'uuid'>;
+    /** Environment name -> the output it is read from. */
+    references: Record<string, {
+        to: string;
+        secret: boolean;
+    }>;
+}
+export type CheckManifestAnswersResult = ({
+    ok: true;
+} & ManifestInstall) | {
+    ok: false;
+    problems: ManifestProblem[];
+};
+/**
+ * The company's answers checked against the manifest: a required question left empty blocks the install,
+ * and every answer must fit its question. Questions with a default may be left out of `answers`.
+ */
+export declare function checkManifestAnswers(manifest: AppManifest, answers: Record<string, ManifestAnswer>): CheckManifestAnswersResult;