@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/modules/jobs.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.jobs`: the app is a project of its own in the jobs scheduler. */
+export declare const jobs: AppModule;

package/dist/modules/jobs.js

@@ -0,0 +1,23 @@
+import { setUse } from './entry-parts.js';
+/** `uses.jobs`: the app is a project of its own in the jobs scheduler. */
+export const jobs = {
+    view: {
+        id: 'jobs',
+        name: 'Jobs in the background',
+        line: 'The app runs tasks on a timer or later, such as a nightly report or a reminder.',
+        category: 'In the background',
+        icon: 'clock',
+        runtimes: ['server'],
+        requires: [],
+        availability: 'ready',
+        fields: [],
+        adds: [
+            {
+                name: 'A scheduler',
+                hint: 'Calls the app when a task is due, and tries again if it fails.',
+            },
+        ],
+    },
+    toEntry: (entry, values) => setUse(entry, 'jobs', values === null ? undefined : true),
+    fromEntry: (entry) => (entry.uses?.jobs === true ? {} : null),
+};

package/dist/modules/organisations.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** Coming soon: businesses sign in with their own company accounts. No fields, nothing in the entry yet. */
+export declare const organisations: AppModule;

package/dist/modules/organisations.js

@@ -0,0 +1,20 @@
+import { clone, problem } from './entry-parts.js';
+/** Coming soon: businesses sign in with their own company accounts. No fields, nothing in the entry yet. */
+export const organisations = {
+    view: {
+        id: 'organisations',
+        name: 'Sign-in for organisations',
+        line: 'Businesses that use the app sign in with their own company accounts and manage their own people.',
+        category: 'People',
+        icon: 'building',
+        runtimes: ['server', 'worker'],
+        requires: ['sign-in'],
+        availability: 'soon',
+        fields: [],
+        adds: [],
+    },
+    toEntry: (entry, values) => values === null
+        ? clone(entry)
+        : problem(null, 'Sign-in for organisations is coming soon. It cannot be turned on yet.'),
+    fromEntry: () => null,
+};

package/dist/modules/outputs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The outputs a manifest `reference` may name. Kept apart from the integration list so manifest parsing can
+ * check references without importing the modules back (the integration list reads the modules).
+ */
+export declare const OUTPUTS: Record<string, readonly string[]>;
+/** Secret outputs: a reference to one must say `secret: true`. */
+export declare const SECRET_OUTPUTS: ReadonlySet<string>;
+/** Why a reference `<owner>.<output>` is refused, or null when the owner has that output. */
+export declare function referenceProblem(to: string): string | null;

package/dist/modules/outputs.js

@@ -0,0 +1,38 @@
+/**
+ * The outputs a manifest `reference` may name. Kept apart from the integration list so manifest parsing can
+ * check references without importing the modules back (the integration list reads the modules).
+ */
+export const OUTPUTS = {
+    'sign-in': ['issuer', 'client-id'],
+    assistants: ['mcp-url'],
+    workspaces: [],
+    database: ['address', 'owner-address'],
+    'signed-records': ['registrar-url'],
+    files: ['address'],
+    email: ['from'],
+    jobs: ['url'],
+    ai: ['address'],
+    organisations: [],
+    audit: [],
+    app: ['url', 'host', 'name'],
+    company: ['id', 'name', 'slug'],
+};
+/** Secret outputs: a reference to one must say `secret: true`. */
+export const SECRET_OUTPUTS = new Set([
+    'database.address',
+    'database.owner-address',
+]);
+/** Why a reference `<owner>.<output>` is refused, or null when the owner has that output. */
+export function referenceProblem(to) {
+    const dot = to.indexOf('.');
+    const owner = to.slice(0, dot);
+    const output = to.slice(dot + 1);
+    const known = Object.hasOwn(OUTPUTS, owner) ? OUTPUTS[owner] : undefined;
+    if (!known)
+        return null; // an owner that is not in the catalogue is the caller's to refuse
+    if (known.includes(output))
+        return null;
+    return known.length === 0
+        ? `"${owner}" gives the app nothing to read.`
+        : `"${owner}" has no "${output}". It gives: ${known.join(', ')}.`;
+}

package/dist/modules/sign-in.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.auth`: who signs in, whether they sign themselves up, how, and the words of the sign-in page. */
+export declare const signIn: AppModule;

package/dist/modules/sign-in.js

@@ -0,0 +1,197 @@
+import { ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, ROOM_UNSAFE_TEXT } from '../entry-rules.js';
+import { defined, omit, problem, setUse, text, withUses, withWorkerApp } from './entry-parts.js';
+/** The sign-in window's text fields: module key -> `uses.auth.room` key. */
+const ROOM_TEXT_KEYS = {
+    roomName: 'name',
+    roomHeadline: 'headline',
+    roomLine: 'line',
+    roomTitle: 'title',
+    roomDescription: 'description',
+};
+const ROOM_NEEDED = ['roomName', 'roomHeadline', 'roomLine'];
+const forCustomers = { key: 'users', equals: 'customers' };
+const roomField = (key, label, help, kind = 'text') => ({
+    key,
+    label,
+    help,
+    kind,
+    advanced: true,
+    max: ROOM_TEXT_MAX[ROOM_TEXT_KEYS[key]],
+    showWhen: forCustomers,
+});
+/** `uses.auth`: who signs in, whether they sign themselves up, how, and the words of the sign-in page. */
+export const signIn = {
+    view: {
+        id: 'sign-in',
+        name: 'Sign-in',
+        line: 'People sign in to the app with their own account.',
+        category: 'People',
+        icon: 'key',
+        runtimes: ['server', 'worker'],
+        requires: [],
+        availability: 'ready',
+        fields: [
+            {
+                key: 'users',
+                label: 'Who signs in',
+                kind: 'choice',
+                required: true,
+                default: 'customers',
+                choices: [
+                    {
+                        value: 'customers',
+                        label: 'Your customers',
+                        help: 'People outside your company who use the app.',
+                    },
+                    {
+                        value: 'staff',
+                        label: 'Your team',
+                        help: 'Only the people in your company.',
+                    },
+                ],
+            },
+            {
+                key: 'registration',
+                label: 'Who can make an account',
+                kind: 'choice',
+                required: true,
+                default: 'open',
+                choices: [
+                    {
+                        value: 'open',
+                        label: 'Anyone',
+                        help: 'People make their own account on the sign-in page.',
+                    },
+                    {
+                        value: 'closed',
+                        label: 'Only people you invite',
+                    },
+                ],
+            },
+            {
+                key: 'method',
+                label: 'How people sign in',
+                kind: 'choice',
+                required: true,
+                default: 'password',
+                choices: [
+                    { value: 'email-code', label: 'A code sent by email', help: 'No password to remember.' },
+                    { value: 'password', label: 'A password' },
+                    { value: 'passkey', label: 'A passkey', soon: true },
+                ],
+            },
+            roomField('roomName', 'Name on the sign-in page', 'The name of your app or company, as people know it.'),
+            roomField('roomHeadline', 'Headline', 'One short sentence on what the app does for people.'),
+            roomField('roomLine', 'Text under the headline', 'A sentence or two that tells people what happens next.', 'longtext'),
+            roomField('roomTitle', 'Title above the form', 'For example "Sign in to your account".'),
+            roomField('roomDescription', 'Text above the form', 'For example "Enter your email. We send you a code."', 'longtext'),
+            {
+                key: 'roomSteps',
+                label: 'Steps shown on the sign-in page',
+                help: `How many steps the page shows, from ${ROOM_STEPS_MIN} to ${ROOM_STEPS_MAX}.`,
+                kind: 'number',
+                advanced: true,
+                max: ROOM_STEPS_MAX,
+                showWhen: forCustomers,
+            },
+        ],
+        adds: [
+            {
+                name: 'A sign-in page',
+                hint: 'People sign in and sign up there, then come back to the app.',
+            },
+        ],
+    },
+    check(values) {
+        const customers = values.users === 'customers';
+        if (!customers && values.registration === 'open') {
+            return problem('registration', 'Only customers can make their own account. For your team, choose "Only people you invite".');
+        }
+        if (!customers && values.method === 'email-code') {
+            return problem('method', 'A code by email is for customers. Your team signs in with a password.');
+        }
+        const roomSet = [...Object.keys(ROOM_TEXT_KEYS), 'roomSteps'].some((key) => values[key] !== undefined && values[key] !== '');
+        if (!roomSet)
+            return null;
+        if (!customers) {
+            return problem('roomName', 'The words of the sign-in page are only shown to customers.');
+        }
+        for (const key of ROOM_NEEDED) {
+            if (text(values, key) === undefined) {
+                const label = signIn.view.fields.find((f) => f.key === key)?.label ?? key;
+                return problem(key, `${label} is needed when you change the words of the sign-in page.`);
+            }
+        }
+        for (const key of Object.keys(ROOM_TEXT_KEYS)) {
+            const value = text(values, key);
+            if (value !== undefined && (value.trim() === '' || ROOM_UNSAFE_TEXT.test(value))) {
+                return problem(key, 'Use plain text: no line breaks, "<" or ">".');
+            }
+        }
+        const steps = values.roomSteps;
+        if (steps !== undefined &&
+            (typeof steps !== 'number' || !Number.isInteger(steps) || steps < ROOM_STEPS_MIN)) {
+            return problem('roomSteps', `The steps must be a whole number from ${ROOM_STEPS_MIN} to ${ROOM_STEPS_MAX}.`);
+        }
+        return null;
+    },
+    toEntry(entry, values) {
+        if (values === null) {
+            const next = withUses(entry, omit(entry.uses ?? {}, 'auth'));
+            return withWorkerApp(next, (app) => omit(app, 'authEnv'));
+        }
+        // The parts other modules own (mcp, workspaces) and the operator's replacesBrokerEntry stay.
+        const kept = omit(entry.uses?.auth ?? {}, 'signIn', 'room');
+        const auth = {
+            ...kept,
+            users: values.users,
+            registration: values.registration,
+        };
+        if (values.method === 'email-code')
+            auth.signIn = 'email-code';
+        const room = roomOf(values);
+        if (room)
+            auth.room = room;
+        const next = setUse(entry, 'auth', auth);
+        return withWorkerApp(next, (app) => ({ ...app, authEnv: true }));
+    },
+    fromEntry(entry) {
+        const auth = entry.uses?.auth;
+        if (!auth)
+            return null;
+        const values = {
+            users: auth.users,
+            registration: auth.registration,
+            method: auth.signIn ?? 'password',
+        };
+        const room = auth.room;
+        if (room) {
+            Object.assign(values, defined({
+                roomName: room.name,
+                roomHeadline: room.headline,
+                roomLine: room.line,
+                roomTitle: room.title,
+                roomDescription: room.description,
+                roomSteps: room.steps,
+            }));
+        }
+        return values;
+    },
+};
+function roomOf(values) {
+    const name = text(values, 'roomName');
+    const headline = text(values, 'roomHeadline');
+    const line = text(values, 'roomLine');
+    if (name === undefined || headline === undefined || line === undefined)
+        return null;
+    const room = { name, headline, line };
+    const title = text(values, 'roomTitle');
+    const description = text(values, 'roomDescription');
+    if (title !== undefined)
+        room.title = title;
+    if (description !== undefined)
+        room.description = description;
+    if (typeof values.roomSteps === 'number')
+        room.steps = values.roomSteps;
+    return room;
+}

package/dist/modules/signed-records.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `workerApp.secrets.KEYS_CREDENTIAL = { from: 'keysCustody' }`: the app signs its records with a held key. */
+export declare const signedRecords: AppModule;

package/dist/modules/signed-records.js

@@ -0,0 +1,32 @@
+import { WORKER_APP_KEYS_SECRET } from '../entry-rules.js';
+import { omit, withWorkerApp } from './entry-parts.js';
+/** `workerApp.secrets.KEYS_CREDENTIAL = { from: 'keysCustody' }`: the app signs its records with a held key. */
+export const signedRecords = {
+    view: {
+        id: 'signed-records',
+        name: 'Signed records',
+        line: 'The app signs each record it keeps with a key held for your company, so anyone can check later that nothing was changed.',
+        category: 'Data',
+        icon: 'seal',
+        runtimes: ['worker'],
+        requires: [],
+        availability: 'ready',
+        fields: [],
+        adds: [
+            {
+                name: 'A signing key',
+                hint: 'Kept in a safe place for this app. The app asks for signatures; it never holds the key.',
+            },
+        ],
+    },
+    toEntry(entry, values) {
+        return withWorkerApp(entry, (app) => {
+            const others = Object.entries(app.secrets ?? {}).filter(([name]) => name !== WORKER_APP_KEYS_SECRET);
+            const secrets = Object.fromEntries(values === null ? others : [...others, [WORKER_APP_KEYS_SECRET, { from: 'keysCustody' }]]);
+            return Object.keys(secrets).length === 0 ? omit(app, 'secrets') : { ...app, secrets };
+        });
+    },
+    fromEntry(entry) {
+        return entry.workerApp?.secrets?.[WORKER_APP_KEYS_SECRET]?.from === 'keysCustody' ? {} : null;
+    },
+};

package/dist/modules/types.d.ts

@@ -0,0 +1,194 @@
+import type { HostingEntry } from '../org.js';
+/**
+ * The app modules contract (`@wtfalch/foundry/modules`). A module is one part an app can have (sign-in, a
+ * database, help for AI assistants). Its view is JSON, so Boule renders any module's form without code of its
+ * own; its `toEntry` and `fromEntry` turn the company's answers into a hosting entry's parts and back.
+ */
+/** How Boule shows a field. */
+export type FieldKind = 'text' | 'longtext' | 'path' | 'choice' | 'switch' | 'list' | 'number' | 'secret';
+export interface ModuleChoice {
+    value: string;
+    label: string;
+    help?: string;
+    /** Shown as "Coming soon" and not selectable. */
+    soon?: boolean;
+}
+export interface ModuleField {
+    key: string;
+    label: string;
+    help?: string;
+    kind: FieldKind;
+    /** For `choice`: the one value picked. For `list`: every item must be one of them. */
+    choices?: ModuleChoice[];
+    default?: string | number | boolean | string[];
+    /** Shown under "Advanced". */
+    advanced?: boolean;
+    /**
+     * The form asks for it. A `secret` field's value is held by the caller, never by the modules or the entry,
+     * so `checkModules` does not demand one: the caller checks it is there before it deploys.
+     */
+    required?: boolean;
+    /** A regular expression's source. For a `list` every item must match it. */
+    pattern?: string;
+    /** The longest text, the most list items, or the largest number. */
+    max?: number;
+    /** Shown only while another field of the same module has this value. */
+    showWhen?: {
+        key: string;
+        equals: string | boolean;
+    };
+    /** Shown and accepted only for an app on one of these runtimes. Absent: every runtime the module has. */
+    runtimes?: ModuleRuntime[];
+}
+export type ModuleCategory = 'People' | 'Data' | 'Messages' | 'AI' | 'In the background' | 'Business';
+export type ModuleRuntime = 'server' | 'worker';
+/** JSON-safe: Boule renders it. */
+export interface ModuleView {
+    id: string;
+    name: string;
+    /** One plain sentence on what the module gives the app. */
+    line: string;
+    category: ModuleCategory;
+    icon: string;
+    /** Where the module works: an app that runs on a server, a Worker app, or both. */
+    runtimes: ModuleRuntime[];
+    /** Ids of the modules this one needs turned on. */
+    requires: string[];
+    availability: 'ready' | 'soon';
+    fields: ModuleField[];
+    /** What turning the module on gives the app, in words. */
+    adds: {
+        name: string;
+        hint: string;
+    }[];
+}
+export type ModuleValue = string | number | boolean | string[];
+export type ModuleValues = Record<string, ModuleValue>;
+/** Module id -> its values. A module that is absent is off. */
+export type AppModules = Record<string, ModuleValues>;
+export interface ModuleContext {
+    runtime: ModuleRuntime;
+}
+/** Why a module or one of its fields was refused, in plain words. */
+export interface ModuleProblem {
+    field: string | null;
+    message: string;
+}
+export interface ModuleRefusal extends ModuleProblem {
+    module: string;
+}
+/** One module: one file `modules/<id>.ts`, listed in `modules/index.ts`. */
+export interface AppModule {
+    view: ModuleView;
+    /**
+     * The entry with this module's parts set from `values` (checked, defaults filled), or with every part the
+     * module owns removed when `values` is null. Never changes `entry` itself.
+     */
+    toEntry(entry: HostingEntry, values: ModuleValues | null, ctx: ModuleContext): HostingEntry | ModuleProblem;
+    /** The module's values as the entry holds them, or null when the entry does not have the module. */
+    fromEntry(entry: HostingEntry): ModuleValues | null;
+    /** Rules between fields, or with other modules, beyond what the fields themselves say. */
+    check?(values: ModuleValues, modules: AppModules, ctx: ModuleContext): ModuleProblem | null;
+}
+/** How a manifest secret gets its value. */
+export type ManifestSecretKind = 'generated' | 'held';
+/** A setting the company may change, delivered to the app as a plain value. */
+export interface ManifestSetting {
+    label: string;
+    help?: string;
+    default?: string;
+}
+/** `company-app.json` v1: what the app's code asks for, written once by its developer. */
+export interface AppManifestV1 {
+    v: 1;
+    runtime: ModuleRuntime;
+    modules: AppModules;
+    secrets: Record<string, ManifestSecretKind>;
+    settings: Record<string, ManifestSetting>;
+}
+/** How a generated value is made. All are random, made once at install and kept across updates. */
+export type ManifestGenerateKind = 'token' | 'hex' | 'uuid';
+/**
+ * The words Boule shows for a value. `label` and `help` are plain English and always present; `labelKey` and
+ * `helpKey` are optional copy keys (`@wtfalch/i18n`) that Boule prefers when it has a catalogue for them.
+ */
+export interface ManifestCopy {
+    label: string;
+    help?: string;
+    labelKey?: string;
+    helpKey?: string;
+}
+export interface ManifestOption {
+    value: string;
+    label: string;
+    help?: string;
+    labelKey?: string;
+}
+/** Made by the platform at install. Always a secret; never shown. */
+export interface ManifestGenerate {
+    source: 'generate';
+    kind: ManifestGenerateKind;
+}
+/** Taken from what another part of the app produces, such as the database's address. Never asked. */
+export interface ManifestReference {
+    source: 'reference';
+    /** `<module id>.<output>`, such as `database.address`, or `app.<output>` / `company.<output>`. */
+    to: string;
+    secret?: boolean;
+}
+/** A value the app ships with and the company may change later. Never a secret. */
+export interface ManifestDefault {
+    source: 'default';
+    value: string;
+    /** Plain words on what the value does. */
+    description: string;
+    label?: string;
+    labelKey?: string;
+}
+/**
+ * Asked of the company at install, in plain words. `required` blocks the install until it is answered.
+ * With `into` the answer goes to a field of a module (`{ module: 'sign-in', field: 'registration' }`) and the
+ * key is a free lowercase id; without it the key is the environment name the app reads.
+ */
+export interface ManifestAsk extends ManifestCopy {
+    source: 'ask';
+    required?: boolean;
+    /** The company types a secret: it is never in this file, so no default. */
+    secret?: boolean;
+    default?: string | string[];
+    /** The answer must be one of these (a list setting when `multiple`). */
+    choices?: ManifestOption[];
+    multiple?: boolean;
+    pattern?: string;
+    max?: number;
+    into?: {
+        module: string;
+        field: string;
+    };
+}
+export type ManifestValue = ManifestGenerate | ManifestReference | ManifestDefault | ManifestAsk;
+/** A place the app says it reaches. Advice shown to the company; never enforced and never needs approval. */
+export interface ManifestHost {
+    /** A host name such as `api.example.com`, or `*.example.com` for every subdomain. */
+    host: string;
+    /** Plain words on why. */
+    why: string;
+}
+/**
+ * Advisory only. The company runs its own app on its own network and manages its own access, so the app may connect
+ * anywhere; `hosts` is a recommendation shown to the company, not a limit.
+ */
+export interface ManifestAccess {
+    hosts: ManifestHost[];
+}
+/** `company-app.json` v2, and what every manifest (v1 too) is read as. */
+export interface AppManifest {
+    v: 2;
+    runtime: ModuleRuntime;
+    modules: AppModules;
+    values: Record<string, ManifestValue>;
+    /** Optional. Absent means the app may connect anywhere. */
+    access?: ManifestAccess;
+}
+/** An answer to an `ask`: text, or a list of texts for `multiple`. */
+export type ManifestAnswer = string | string[];

package/dist/modules/types.js

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

package/dist/modules/workspaces.d.ts

@@ -0,0 +1,3 @@
+import type { AppModule } from './types.js';
+/** `uses.auth.workspaces`: the app's customers make shared workspaces and invite people into them. */
+export declare const workspaces: AppModule;

package/dist/modules/workspaces.js

@@ -0,0 +1,75 @@
+import { WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, isPagePath } from '../entry-rules.js';
+import { list, problem, setAuthPart } from './entry-parts.js';
+/** `uses.auth.workspaces`: the app's customers make shared workspaces and invite people into them. */
+export const workspaces = {
+    view: {
+        id: 'workspaces',
+        name: 'Workspaces',
+        line: 'Your customers make a shared space, invite the people they work with and give each one a role.',
+        category: 'People',
+        icon: 'users',
+        runtimes: ['server'],
+        requires: ['sign-in'],
+        availability: 'ready',
+        fields: [
+            {
+                key: 'roles',
+                label: 'Roles in a workspace',
+                help: 'The person who makes a workspace gets the first role. Lowercase letters, digits, "_" and "-".',
+                kind: 'list',
+                required: true,
+                default: ['owner', 'member'],
+                pattern: WORKSPACE_ROLE.source,
+                max: WORKSPACE_ROLES_MAX,
+            },
+            {
+                key: 'invitePath',
+                label: 'Page that opens an invitation',
+                help: 'The page on your app the invitation email links to, such as /join.',
+                kind: 'path',
+                advanced: true,
+                required: true,
+                default: '/join',
+            },
+        ],
+        adds: [
+            { name: 'Invitations by email', hint: 'Sent from your company, with a link to the app.' },
+        ],
+    },
+    check(values, modules) {
+        if (modules['sign-in']?.users !== 'customers') {
+            return problem(null, 'Workspaces are for your customers. In Sign-in, choose "Your customers" first.');
+        }
+        const roles = list(values, 'roles') ?? [];
+        const seen = new Set();
+        for (const [index, role] of roles.entries()) {
+            if (role.startsWith('c_')) {
+                return problem('roles', `The role "${role}" may not start with "c_".`);
+            }
+            if (seen.has(role))
+                return problem('roles', `The role "${role}" is named twice.`);
+            if (role === 'self_service' || (role === 'owner' && index > 0)) {
+                return problem('roles', `The role "${role}" is kept for the system: only the first role may be called "owner", and "self_service" is never allowed.`);
+            }
+            seen.add(role);
+        }
+        if (!isPagePath(values.invitePath)) {
+            return problem('invitePath', 'The page must start with "/", such as /join, with no spaces, "?", "#" or "..".');
+        }
+        return null;
+    },
+    toEntry(entry, values) {
+        if (values === null)
+            return setAuthPart(entry, 'workspaces', undefined);
+        if (!entry.uses?.auth)
+            return problem(null, 'Workspaces need Sign-in. Turn on Sign-in first.');
+        return setAuthPart(entry, 'workspaces', {
+            roles: list(values, 'roles') ?? [],
+            invitePath: values.invitePath,
+        });
+    },
+    fromEntry(entry) {
+        const used = entry.uses?.auth?.workspaces;
+        return used ? { roles: [...used.roles], invitePath: used.invitePath } : null;
+    },
+};