@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/modules/index.js

@@ -0,0 +1,774 @@
+import { SECRET_LIKE_NAME, WORKER_APP_ENV_NAME, WORKER_APP_RESERVED_NAMES, } from '../entry-rules.js';
+import { ai } from './ai.js';
+import { assistants } from './assistants.js';
+import { audit } from './audit.js';
+import { database } from './database.js';
+import { email } from './email.js';
+import { clone, isProblem } from './entry-parts.js';
+import { files } from './files.js';
+import { jobs } from './jobs.js';
+import { organisations } from './organisations.js';
+import { SECRET_OUTPUTS, referenceProblem } from './outputs.js';
+import { signIn } from './sign-in.js';
+import { signedRecords } from './signed-records.js';
+import { workspaces } from './workspaces.js';
+export { 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 const MODULES = [
+    signIn,
+    assistants,
+    workspaces,
+    database,
+    signedRecords,
+    files,
+    email,
+    jobs,
+    ai,
+    organisations,
+    audit,
+];
+const byId = new Map(MODULES.map((module) => [module.view.id, module]));
+/** The views of every module, JSON-safe, for Boule to render. */
+export function modulesCatalogue() {
+    return MODULES.map((module) => clone(module.view));
+}
+const RUNTIME_WORDS = { server: 'an app that runs on a server', worker: 'a Worker app' };
+/** The values with every absent field's default filled in. */
+function withDefaults(view, values) {
+    const filled = { ...values };
+    for (const field of view.fields) {
+        if (filled[field.key] === undefined && field.default !== undefined) {
+            filled[field.key] = clone(field.default);
+        }
+    }
+    return filled;
+}
+const isEmpty = (value) => value === undefined || value === '' || (Array.isArray(value) && value.length === 0);
+/** A plain sentence when one field's value does not fit the field, else null. */
+function fieldProblem(field, value) {
+    const name = `"${field.label}"`;
+    if (isEmpty(value))
+        return field.required && field.kind !== 'secret' ? `${name} is needed.` : null;
+    const pattern = field.pattern === undefined ? null : new RegExp(field.pattern, 'u');
+    switch (field.kind) {
+        case 'switch':
+            return typeof value === 'boolean' ? null : `${name} must be on or off.`;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                return `${name} must be a number.`;
+            return field.max !== undefined && value > field.max
+                ? `${name} may be at most ${field.max}.`
+                : null;
+        case 'list': {
+            if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+                return `${name} must be a list of words.`;
+            }
+            if (field.max !== undefined && value.length > field.max) {
+                return `${name} may hold at most ${field.max}.`;
+            }
+            if (new Set(value).size !== value.length)
+                return `${name} names something twice.`;
+            for (const item of value) {
+                if (field.choices && !field.choices.some((choice) => choice.value === item)) {
+                    return `${name} cannot hold "${item}".`;
+                }
+                if (pattern && !pattern.test(item))
+                    return `${name}: "${item}" is not written the way it must be.`;
+            }
+            return null;
+        }
+        case 'choice': {
+            const choice = field.choices?.find((c) => c.value === value);
+            if (!choice)
+                return `${name} must be one of the choices shown.`;
+            return choice.soon ? `"${choice.label}" is coming soon. Pick another choice for now.` : null;
+        }
+        default:
+            if (typeof value !== 'string')
+                return `${name} must be text.`;
+            if (field.max !== undefined && value.length > field.max) {
+                return `${name} may be at most ${field.max} characters.`;
+            }
+            return pattern && !pattern.test(value) ? `${name} is not written the way it must be.` : null;
+    }
+}
+/** The modules with their defaults filled, for the modules' own checks and `toEntry`. */
+function filledModules(modules) {
+    const filled = {};
+    for (const [id, values] of Object.entries(modules)) {
+        const module = byId.get(id);
+        filled[id] = module ? withDefaults(module.view, values) : values;
+    }
+    return filled;
+}
+/**
+ * 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 function checkModules(modules, ctx) {
+    if (typeof modules !== 'object' || modules === null || Array.isArray(modules)) {
+        return { module: '', field: null, message: 'The app’s modules must be a list of named parts.' };
+    }
+    for (const id of Object.keys(modules)) {
+        if (!byId.has(id)) {
+            return { module: id, field: null, message: `There is no module called "${id}".` };
+        }
+    }
+    const filled = filledModules(modules);
+    for (const module of MODULES) {
+        const id = module.view.id;
+        const raw = modules[id];
+        if (raw === undefined)
+            continue;
+        const refuse = (field, message) => ({
+            module: id,
+            field,
+            message,
+        });
+        const { view } = module;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return refuse(null, `The settings of ${view.name} must be a list of named values.`);
+        }
+        if (view.availability === 'soon') {
+            return refuse(null, `${view.name} is coming soon. It cannot be turned on yet.`);
+        }
+        if (!view.runtimes.includes(ctx.runtime)) {
+            return refuse(null, `${view.name} works only in ${view.runtimes.map((r) => RUNTIME_WORDS[r]).join(' or ')}. This app is ${RUNTIME_WORDS[ctx.runtime]}.`);
+        }
+        for (const needed of view.requires) {
+            if (modules[needed] === undefined) {
+                const other = byId.get(needed)?.view.name ?? needed;
+                return refuse(null, `${view.name} needs ${other}. Turn on ${other} first.`);
+            }
+        }
+        const values = filled[id];
+        for (const key of Object.keys(values)) {
+            if (!view.fields.some((field) => field.key === key)) {
+                return refuse(key, `${view.name} has no setting called "${key}".`);
+            }
+        }
+        for (const field of view.fields) {
+            if (field.runtimes && !field.runtimes.includes(ctx.runtime)) {
+                if (isEmpty(values[field.key]))
+                    continue;
+                return refuse(field.key, `"${field.label}" can only be set for ${field.runtimes.map((r) => RUNTIME_WORDS[r]).join(' or ')}. This app is ${RUNTIME_WORDS[ctx.runtime]}.`);
+            }
+            const message = fieldProblem(field, values[field.key]);
+            if (message)
+                return refuse(field.key, message);
+        }
+        const ruled = module.check?.(values, filled, ctx);
+        if (ruled)
+            return refuse(ruled.field, ruled.message);
+    }
+    return null;
+}
+/**
+ * `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 function applyModules(entry, modules, ctx) {
+    const refused = checkModules(modules, ctx);
+    if (refused)
+        return { ok: false, ...refused };
+    if (ctx.runtime === 'worker' && !entry.workerApp) {
+        return {
+            ok: false,
+            module: '',
+            field: null,
+            message: 'This app runs as a Worker app, but its build has not been read yet. Read the build first.',
+        };
+    }
+    if (ctx.runtime === 'server' && entry.workerApp) {
+        return {
+            ok: false,
+            module: '',
+            field: null,
+            message: 'This app runs as a Worker app, not on a server.',
+        };
+    }
+    const filled = filledModules(modules);
+    let next = clone(entry);
+    for (const module of MODULES) {
+        const id = module.view.id;
+        const result = module.toEntry(next, filled[id] ?? null, ctx);
+        if (isProblem(result))
+            return { ok: false, module: id, ...result };
+        next = result;
+    }
+    return { ok: true, entry: next };
+}
+/** The modules `entry` has, with their values: the inverse of {@link applyModules}. */
+export function modulesOf(entry) {
+    const out = {};
+    for (const module of MODULES) {
+        if (module.view.availability !== 'ready')
+            continue;
+        const values = module.fromEntry(entry);
+        if (values !== null)
+            out[module.view.id] = values;
+    }
+    return out;
+}
+const MANIFEST_V1_KEYS = ['v', 'runtime', 'modules', 'secrets', 'settings'];
+const SECRET_KINDS = ['generated', 'held'];
+const SETTING_KEYS = ['label', 'help', 'default'];
+const SETTING_LABEL_MAX = 80;
+const SETTING_HELP_MAX = 200;
+const SETTING_DEFAULT_MAX = 1000;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A plain sentence when `name` cannot be a secret's or setting's name, else null. */
+function nameProblem(kind, name) {
+    if (!WORKER_APP_ENV_NAME.test(name)) {
+        return `the ${kind} "${name}" must be named in capital letters, digits and "_", such as POOL_CEILING`;
+    }
+    if (WORKER_APP_RESERVED_NAMES.test(name)) {
+        return `the ${kind} "${name}" uses a name the platform sets itself (AUTH_, KEYS_, MCP_, HYPERDRIVE)`;
+    }
+    return null;
+}
+/** A v1 `company-app.json` read and checked. */
+function parseManifestV1(json) {
+    const refuse = (message) => ({
+        ok: false,
+        message: `company-app.json: ${message}`,
+    });
+    const unknown = Object.keys(json).find((key) => !MANIFEST_V1_KEYS.includes(key));
+    if (unknown !== undefined)
+        return refuse(`"${unknown}" is not something the file can say.`);
+    if (json.v !== 1)
+        return refuse('"v" must be 1, the only version there is.');
+    const runtime = json.runtime;
+    if (runtime !== 'server' && runtime !== 'worker') {
+        return refuse('"runtime" must be "worker" (a Worker app) or "server" (an app that runs on a server).');
+    }
+    const modules = json.modules ?? {};
+    if (!isRecord(modules))
+        return refuse('"modules" must be an object of module names.');
+    const refused = checkModules(modules, { runtime });
+    if (refused)
+        return refuse(refused.message);
+    for (const [id, values] of Object.entries(modules)) {
+        const view = byId.get(id)?.view;
+        const secret = view?.fields.find((f) => f.kind === 'secret' && !isEmpty(values[f.key]));
+        if (view && secret) {
+            return refuse(`"${secret.label}" (${view.name}) is a secret. Your company types it in when it sets up the app; it never goes in this file.`);
+        }
+    }
+    const secrets = {};
+    const rawSecrets = json.secrets ?? {};
+    if (!isRecord(rawSecrets))
+        return refuse('"secrets" must be an object of secret names.');
+    for (const [name, kind] of Object.entries(rawSecrets)) {
+        const bad = nameProblem('secret', name);
+        if (bad)
+            return refuse(`${bad}.`);
+        if (!SECRET_KINDS.includes(kind)) {
+            return refuse(`the secret "${name}" must be "generated" (made for you) or "held" (your company types it in).`);
+        }
+        secrets[name] = kind;
+    }
+    const settings = {};
+    const rawSettings = json.settings ?? {};
+    if (!isRecord(rawSettings))
+        return refuse('"settings" must be an object of setting names.');
+    for (const [name, raw] of Object.entries(rawSettings)) {
+        const bad = nameProblem('setting', name);
+        if (bad)
+            return refuse(`${bad}.`);
+        if (name in secrets)
+            return refuse(`"${name}" is both a secret and a setting.`);
+        if (SECRET_LIKE_NAME.test(name)) {
+            return refuse(`the setting "${name}" looks like a secret. Put it under "secrets".`);
+        }
+        if (!isRecord(raw))
+            return refuse(`the setting "${name}" must have a label.`);
+        const extra = Object.keys(raw).find((key) => !SETTING_KEYS.includes(key));
+        if (extra !== undefined)
+            return refuse(`the setting "${name}" cannot say "${extra}".`);
+        const { label, help, default: value } = raw;
+        if (typeof label !== 'string' || label.trim() === '' || label.length > SETTING_LABEL_MAX) {
+            return refuse(`the setting "${name}" needs a label of 1 to ${SETTING_LABEL_MAX} characters.`);
+        }
+        if (help !== undefined && (typeof help !== 'string' || help.length > SETTING_HELP_MAX)) {
+            return refuse(`the help of the setting "${name}" must be at most ${SETTING_HELP_MAX} characters.`);
+        }
+        if (value !== undefined && (typeof value !== 'string' || value.length > SETTING_DEFAULT_MAX)) {
+            return refuse(`the default of the setting "${name}" must be text of at most ${SETTING_DEFAULT_MAX} characters.`);
+        }
+        settings[name] = {
+            label,
+            ...(help !== undefined ? { help } : {}),
+            ...(value !== undefined ? { default: value } : {}),
+        };
+    }
+    return {
+        ok: true,
+        manifest: { v: 1, runtime, modules: clone(modules), secrets, settings },
+    };
+}
+/** A v1 manifest read as v2: a generated secret is `generate`, a held one an `ask`, a setting a `default` or an `ask`. */
+function manifestV1AsV2(v1) {
+    const values = {};
+    for (const [name, kind] of Object.entries(v1.secrets)) {
+        const label = `${name.charAt(0)}${name.slice(1).toLowerCase().replaceAll('_', ' ')}`;
+        values[name] =
+            kind === 'generated'
+                ? { source: 'generate', kind: 'token' }
+                : {
+                    source: 'ask',
+                    label,
+                    help: `Your company types in ${label}.`,
+                    secret: true,
+                    required: true,
+                };
+    }
+    for (const [name, setting] of Object.entries(v1.settings)) {
+        values[name] =
+            setting.default !== undefined
+                ? {
+                    source: 'default',
+                    value: setting.default,
+                    description: setting.help ?? setting.label,
+                    label: setting.label,
+                }
+                : { source: 'ask', label: setting.label, help: setting.help ?? setting.label };
+    }
+    return { v: 2, runtime: v1.runtime, modules: v1.modules, values };
+}
+const MANIFEST_V2_KEYS = ['v', 'runtime', 'modules', 'values', 'access'];
+const VALUE_KEYS = {
+    generate: ['source', 'kind'],
+    reference: ['source', 'to', 'secret'],
+    default: ['source', 'value', 'description', 'label', 'labelKey'],
+    ask: [
+        'source',
+        'label',
+        'help',
+        'labelKey',
+        'helpKey',
+        'required',
+        'secret',
+        'default',
+        'choices',
+        'multiple',
+        'pattern',
+        'max',
+        'into',
+    ],
+};
+const GENERATE_KINDS = ['token', 'hex', 'uuid'];
+const OPTION_KEYS = ['value', 'label', 'help', 'labelKey'];
+const ASK_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const COPY_KEY = /^[a-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$/;
+const REFERENCE = /^[a-z][a-z0-9-]*\.[A-Za-z][A-Za-z0-9-]*$/;
+const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const HOST_MAX = 20;
+const WHY_MAX = 200;
+const CHOICES_MAX = 50;
+const ASKABLE_KINDS = ['text', 'longtext', 'path', 'choice', 'list'];
+const isText = (value, max) => typeof value === 'string' && value.trim() !== '' && value.length <= max;
+/** A plain sentence when `copy` is not a good label, help or copy key, else null. */
+function copyProblem(name, raw, labelRequired) {
+    const { label, help, labelKey, helpKey } = raw;
+    if (labelRequired
+        ? !isText(label, SETTING_LABEL_MAX)
+        : label !== undefined && !isText(label, SETTING_LABEL_MAX)) {
+        return `"${name}" needs a label of 1 to ${SETTING_LABEL_MAX} characters`;
+    }
+    if (help !== undefined && !isText(help, SETTING_HELP_MAX)) {
+        return `the help of "${name}" must be 1 to ${SETTING_HELP_MAX} characters`;
+    }
+    for (const [what, key] of [
+        ['labelKey', labelKey],
+        ['helpKey', helpKey],
+    ]) {
+        if (key !== undefined && (typeof key !== 'string' || !COPY_KEY.test(key))) {
+            return `"${name}": ${what} must be a copy key such as "apps.candor.registration.label"`;
+        }
+    }
+    return null;
+}
+/** A pattern longer than this is refused. */
+const PATTERN_MAX = 200;
+/** A group that has a repeat inside it and is repeated itself, such as `(a+)+`, `(a*)*` or `(a|b+){2,}`. */
+const NESTED_QUANTIFIER = /\((?:[^()\\]|\\.)*(?:[+*]|\{\d*,\d*\})(?:[^()\\]|\\.)*\)(?:[+*]|\{\d*,\d*\})/;
+/** A plain sentence when the `ask` `name` is wrong, else null. Fills `ask` with the checked value. */
+function askProblem(name, raw) {
+    const at = `the question "${name}"`;
+    const bad = copyProblem(name, raw, true);
+    if (bad)
+        return bad;
+    if (typeof raw.help !== 'string')
+        return `${at} needs a help line in plain words`;
+    for (const key of ['required', 'secret', 'multiple']) {
+        if (raw[key] !== undefined && typeof raw[key] !== 'boolean')
+            return `${at}: "${key}" must be true or false`;
+    }
+    if (raw.pattern !== undefined) {
+        const text = String(raw.pattern);
+        if (text.length > PATTERN_MAX) {
+            return `${at}: "pattern" is longer than ${PATTERN_MAX} characters; write a shorter one`;
+        }
+        if (NESTED_QUANTIFIER.test(text)) {
+            return `${at}: "pattern" repeats a group that already repeats (like "(a+)+"), which can hang the page; write it without the nested repeat`;
+        }
+        try {
+            new RegExp(text, 'u');
+        }
+        catch {
+            return `${at}: "pattern" is not a valid pattern`;
+        }
+    }
+    if (raw.max !== undefined && (!Number.isInteger(raw.max) || raw.max < 1)) {
+        return `${at}: "max" must be a whole number of 1 or more`;
+    }
+    const choices = raw.choices;
+    if (choices !== undefined) {
+        if (!Array.isArray(choices) || choices.length === 0 || choices.length > CHOICES_MAX) {
+            return `${at}: "choices" must list 1 to ${CHOICES_MAX} options`;
+        }
+        const seen = new Set();
+        for (const option of choices) {
+            if (!isRecord(option))
+                return `${at}: each choice needs a value and a label`;
+            const extra = Object.keys(option).find((k) => !OPTION_KEYS.includes(k));
+            if (extra !== undefined)
+                return `${at}: a choice cannot say "${extra}"`;
+            if (!isText(option.value, 200) || seen.has(option.value)) {
+                return `${at}: every choice needs its own value`;
+            }
+            seen.add(option.value);
+            const optionBad = copyProblem(option.value, option, true);
+            if (optionBad)
+                return `${at}: ${optionBad}`;
+        }
+    }
+    if (raw.multiple === true && choices === undefined)
+        return `${at}: a list needs "choices"`;
+    if (raw.secret === true) {
+        if (raw.default !== undefined || choices !== undefined || raw.into !== undefined) {
+            return `${at} is a secret: it cannot have a default, choices, or go into a module, because the file is not private`;
+        }
+        return null;
+    }
+    const value = raw.default;
+    if (value !== undefined) {
+        const items = raw.multiple === true ? value : [value];
+        if ((raw.multiple === true && !Array.isArray(value)) ||
+            !Array.isArray(items) ||
+            !items.every((item) => typeof item === 'string' && item.length <= SETTING_DEFAULT_MAX)) {
+            return `${at}: the default must be ${raw.multiple === true ? 'a list of text' : 'text'}`;
+        }
+        if (raw.required === true && items.every((item) => item === '')) {
+            return `${at} is required, so its default cannot be empty`;
+        }
+        const allowed = choices?.map((c) => c.value);
+        for (const item of items) {
+            if (allowed && !allowed.includes(item))
+                return `${at}: the default "${item}" is not one of its choices`;
+            if (typeof raw.pattern === 'string' &&
+                item !== '' &&
+                !new RegExp(raw.pattern, 'u').test(item)) {
+                return `${at}: the default "${item}" is not written the way it must be`;
+            }
+        }
+    }
+    return null;
+}
+/** A plain sentence when an `into` binding is wrong, else null. */
+function intoProblem(name, raw, modules) {
+    const into = raw.into;
+    if (!isRecord(into) || typeof into.module !== 'string' || typeof into.field !== 'string') {
+        return `the question "${name}": "into" must name a module and a field`;
+    }
+    const extra = Object.keys(into).find((k) => k !== 'module' && k !== 'field');
+    if (extra !== undefined)
+        return `the question "${name}": "into" cannot say "${extra}"`;
+    if (!Object.hasOwn(modules, into.module)) {
+        return `the question "${name}" fills the module "${into.module}", which this app has not turned on`;
+    }
+    const field = byId.get(into.module)?.view.fields.find((f) => f.key === into.field);
+    if (!field)
+        return `the question "${name}": the module "${into.module}" has no field "${into.field}"`;
+    if (!ASKABLE_KINDS.includes(field.kind)) {
+        return `the question "${name}": "${field.label}" cannot be asked as a question`;
+    }
+    if ((field.kind === 'list') !== (raw.multiple === true)) {
+        return `the question "${name}": "multiple" must be ${field.kind === 'list' ? 'true' : 'left out'} for "${field.label}"`;
+    }
+    const options = raw.choices;
+    if (field.choices && options) {
+        const stray = options.find((o) => !field.choices?.some((c) => c.value === o.value));
+        if (stray)
+            return `the question "${name}": "${stray.value}" is not something "${field.label}" accepts`;
+    }
+    return null;
+}
+function parseManifestV2(json) {
+    const refuse = (message) => ({
+        ok: false,
+        message: `company-app.json: ${message}`,
+    });
+    const unknown = Object.keys(json).find((key) => !MANIFEST_V2_KEYS.includes(key));
+    if (unknown !== undefined)
+        return refuse(`"${unknown}" is not something the file can say.`);
+    const runtime = json.runtime;
+    if (runtime !== 'server' && runtime !== 'worker') {
+        return refuse('"runtime" must be "worker" (a Worker app) or "server" (an app that runs on a server).');
+    }
+    const modules = json.modules ?? {};
+    if (!isRecord(modules))
+        return refuse('"modules" must be an object of module names.');
+    const rawValues = json.values ?? {};
+    if (!isRecord(rawValues))
+        return refuse('"values" must be an object of value names.');
+    const asked = new Set();
+    const values = {};
+    const probe = clone(modules);
+    for (const [name, raw] of Object.entries(rawValues)) {
+        if (!isRecord(raw))
+            return refuse(`"${name}" must say where its value comes from ("source").`);
+        const source = raw.source;
+        if (typeof source !== 'string' || !(source in VALUE_KEYS)) {
+            return refuse(`"${name}": "source" must be "generate", "reference", "default" or "ask".`);
+        }
+        const extra = Object.keys(raw).find((k) => !VALUE_KEYS[source]?.includes(k));
+        if (extra !== undefined)
+            return refuse(`"${name}" (${source}) cannot say "${extra}".`);
+        const into = source === 'ask' && raw.into !== undefined;
+        if (into) {
+            if (!ASK_ID.test(name)) {
+                return refuse(`the question "${name}" must be named in lowercase letters, digits and "-".`);
+            }
+        }
+        else {
+            const bad = nameProblem('value', name);
+            if (bad)
+                return refuse(`${bad}.`);
+        }
+        const secretLike = !into && SECRET_LIKE_NAME.test(name);
+        let value;
+        if (source === 'generate') {
+            if (!GENERATE_KINDS.includes(raw.kind)) {
+                return refuse(`"${name}": "kind" must be "token", "hex" or "uuid".`);
+            }
+            value = { source, kind: raw.kind };
+        }
+        else if (source === 'reference') {
+            if (typeof raw.to !== 'string' || !REFERENCE.test(raw.to)) {
+                return refuse(`"${name}": "to" must name an output, such as "database.address".`);
+            }
+            const owner = raw.to.slice(0, raw.to.indexOf('.'));
+            if (!Object.hasOwn(modules, owner) && owner !== 'app' && owner !== 'company') {
+                return refuse(`"${name}" reads from "${owner}", which this app has not turned on.`);
+            }
+            const unknownOutput = referenceProblem(raw.to);
+            if (unknownOutput)
+                return refuse(`"${name}" reads "${raw.to}": ${unknownOutput}`);
+            if (raw.secret !== undefined && typeof raw.secret !== 'boolean') {
+                return refuse(`"${name}": "secret" must be true or false.`);
+            }
+            if (secretLike && raw.secret !== true) {
+                return refuse(`the value "${name}" looks like a secret. Say "secret": true.`);
+            }
+            if (SECRET_OUTPUTS.has(raw.to) && raw.secret !== true) {
+                return refuse(`"${name}" reads "${raw.to}", which is a secret. Say "secret": true.`);
+            }
+            value = { source, to: raw.to, ...(raw.secret === true ? { secret: true } : {}) };
+        }
+        else if (source === 'default') {
+            if (secretLike) {
+                return refuse(`the value "${name}" looks like a secret, so it cannot have a default in this file.`);
+            }
+            if (typeof raw.value !== 'string' || raw.value.length > SETTING_DEFAULT_MAX) {
+                return refuse(`the default of "${name}" must be text of at most ${SETTING_DEFAULT_MAX} characters.`);
+            }
+            if (!isText(raw.description, SETTING_HELP_MAX)) {
+                return refuse(`"${name}" needs a description of 1 to ${SETTING_HELP_MAX} characters, in plain words.`);
+            }
+            const bad = copyProblem(name, raw, false);
+            if (bad)
+                return refuse(`${bad}.`);
+            value = {
+                source,
+                value: raw.value,
+                description: raw.description,
+                ...(raw.label !== undefined ? { label: raw.label } : {}),
+                ...(raw.labelKey !== undefined ? { labelKey: raw.labelKey } : {}),
+            };
+        }
+        else {
+            const bad = askProblem(name, raw);
+            if (bad)
+                return refuse(`${bad}.`);
+            if (secretLike && raw.secret !== true) {
+                return refuse(`the value "${name}" looks like a secret. Say "secret": true.`);
+            }
+            if (into) {
+                const badInto = intoProblem(name, raw, modules);
+                if (badInto)
+                    return refuse(`${badInto}.`);
+                const target = raw.into;
+                const slot = `${target.module}.${target.field}`;
+                if (asked.has(slot))
+                    return refuse(`two questions fill "${slot}".`);
+                asked.add(slot);
+                const sample = (raw.default ??
+                    raw.choices?.[0]?.value);
+                const mod = probe[target.module];
+                if (mod && mod[target.field] === undefined && sample !== undefined) {
+                    mod[target.field] =
+                        raw.multiple === true ? (Array.isArray(sample) ? sample : [sample]) : sample;
+                }
+            }
+            value = clone(raw);
+        }
+        values[name] = value;
+    }
+    const refused = checkModules(probe, { runtime });
+    if (refused)
+        return refuse(refused.message);
+    for (const [id, fields] of Object.entries(modules)) {
+        const view = byId.get(id)?.view;
+        const secret = view?.fields.find((f) => f.kind === 'secret' && !isEmpty(fields[f.key]));
+        if (view && secret) {
+            return refuse(`"${secret.label}" (${view.name}) is a secret. Your company types it in when it sets up the app; it never goes in this file.`);
+        }
+    }
+    // `access` is optional and advisory: absent means the app may connect anywhere, and the hosts listed
+    // are a recommendation shown to the company, never enforced.
+    const rawAccess = json.access ?? {};
+    if (!isRecord(rawAccess))
+        return refuse('"access" must be an object.');
+    const extraAccess = Object.keys(rawAccess).find((k) => k !== 'hosts');
+    if (extraAccess !== undefined)
+        return refuse(`"access" cannot say "${extraAccess}".`);
+    const rawHosts = rawAccess.hosts ?? [];
+    if (!Array.isArray(rawHosts) || rawHosts.length > HOST_MAX) {
+        return refuse(`"access.hosts" must list at most ${HOST_MAX} places the app recommends reaching.`);
+    }
+    const seen = new Set();
+    const hosts = [];
+    for (const entry of rawHosts) {
+        if (!isRecord(entry) || Object.keys(entry).some((k) => k !== 'host' && k !== 'why')) {
+            return refuse('every place in "access.hosts" needs a "host" and a "why" and nothing else.');
+        }
+        const { host, why } = entry;
+        if (typeof host !== 'string' || !HOST.test(host)) {
+            return refuse(`"${String(host)}" is not a host name. Write it like "api.example.com" or "*.example.com", with no "https://", port or path.`);
+        }
+        if (seen.has(host))
+            return refuse(`"${host}" is listed twice.`);
+        seen.add(host);
+        if (!isText(why, WHY_MAX)) {
+            return refuse(`say in plain words why the app reaches "${host}" (1 to ${WHY_MAX} characters).`);
+        }
+        hosts.push({ host, why });
+    }
+    const manifest = { v: 2, runtime, modules: clone(modules), values };
+    if (json.access !== undefined)
+        manifest.access = { hosts };
+    return { ok: true, manifest };
+}
+/** `company-app.json` (v1 or v2) read and checked: what the app's code asks for. */
+export function parseAppManifest(json) {
+    if (!isRecord(json))
+        return { ok: false, message: 'company-app.json: the file must hold one JSON object.' };
+    if (json.v === 1) {
+        const read = parseManifestV1(json);
+        return read.ok ? { ok: true, manifest: manifestV1AsV2(read.manifest), from: 1 } : read;
+    }
+    if (json.v === 2) {
+        const read = parseManifestV2(json);
+        return read.ok ? { ok: true, manifest: read.manifest, from: 2 } : read;
+    }
+    return { ok: false, message: 'company-app.json: "v" must be 1 or 2.' };
+}
+/**
+ * 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 function checkManifestAnswers(manifest, answers) {
+    const problems = [];
+    for (const key of Object.keys(answers)) {
+        if (manifest.values[key]?.source !== 'ask') {
+            problems.push({ key, message: `"${key}" is not something this app asks.` });
+        }
+    }
+    const out = {
+        modules: clone(manifest.modules),
+        plain: {},
+        secrets: {},
+        generate: {},
+        references: {},
+    };
+    for (const [key, value] of Object.entries(manifest.values)) {
+        if (value.source === 'generate')
+            out.generate[key] = value.kind;
+        else if (value.source === 'reference') {
+            out.references[key] = { to: value.to, secret: value.secret === true };
+        }
+        else if (value.source === 'default')
+            out.plain[key] = value.value;
+        else {
+            const given = answers[key] ?? value.default;
+            const name = `"${value.label}"`;
+            const list = Array.isArray(given)
+                ? given
+                : given === undefined || given === ''
+                    ? []
+                    : [given];
+            const bad = (() => {
+                if (list.length === 0 || list.every((item) => item === '')) {
+                    return value.required ? `${name} is needed to install.` : null;
+                }
+                if (value.multiple ? !Array.isArray(given) : typeof given !== 'string') {
+                    return `${name} must be ${value.multiple ? 'a list' : 'one answer'}.`;
+                }
+                const longest = value.max;
+                if (longest !== undefined && list.some((item) => item.length > longest)) {
+                    return `${name} may be at most ${longest} characters.`;
+                }
+                const pattern = value.pattern === undefined ? null : new RegExp(value.pattern, 'u');
+                for (const item of list) {
+                    if (typeof item !== 'string')
+                        return `${name} must be text.`;
+                    if (value.choices && !value.choices.some((c) => c.value === item)) {
+                        return `${name} cannot be "${item}". Pick from the choices shown.`;
+                    }
+                    if (pattern && !pattern.test(item))
+                        return `${name} is not written the way it must be.`;
+                }
+                if (new Set(list).size !== list.length)
+                    return `${name} names something twice.`;
+                return null;
+            })();
+            if (bad) {
+                problems.push({ key, message: bad });
+                continue;
+            }
+            if (list.length === 0)
+                continue;
+            if (value.into) {
+                const target = out.modules[value.into.module];
+                if (target)
+                    target[value.into.field] = value.multiple ? list : list[0];
+            }
+            else if (value.secret)
+                out.secrets[key] = list.join(',');
+            else
+                out.plain[key] = list.join(',');
+        }
+    }
+    if (problems.length === 0) {
+        const refused = checkModules(out.modules, { runtime: manifest.runtime });
+        if (refused)
+            problems.push({ key: null, message: refused.message });
+    }
+    return problems.length > 0 ? { ok: false, problems } : { ok: true, ...out };
+}