@wtfalch/foundry 0.60.0 → 0.61.0

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;