@brydio/manifest 0.1.0-alpha.0

package/src/schema.js

@@ -0,0 +1,375 @@
+import { z } from 'zod';
+import { MANIFEST_LIMITS, SEMVER_FORMAT, baseManifestSchema as manifestSchema } from "./base.js";
+import { COLLECTION_NAME, FIELD_LIMITS, FIELD_NAME, FieldTypeInvalid, isSearchable, isSortable, isStructured, parseFieldType, RESERVED_FIELDS, } from "./field-types.js";
+import { migrationsSchema } from "./migrations.js";
+export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structuredFields, } from "./field-types.js";
+/**
+ * What an app adds to `.brydio/app.json` to be more than a bundle of servers
+ * and skills: where it is shown, what it keeps, the tools that come from what
+ * it keeps, its screens, and what it asks the workspace for (contracts §4).
+ *
+ * Every key is optional, so every manifest E5 already imports still parses.
+ * A copy of Brydio's `apps/api/src/apps/manifest/manifest-ext.schema.ts`, the
+ * schema the server reads an installed app's manifest with. The two change
+ * together; `test/manifest.test.ts` parses the same manifests with both.
+ *
+ * Zod says what the additions *are*. The checks that are claims about one
+ * field against another — a search list naming a date, a placement naming a
+ * screen nobody declared — are `dataProblems` below, with a code each, so an
+ * import report can say which collection and which field, not just "invalid".
+ */
+const placementSchema = z.object({
+    kind: z.enum(['project-tab', 'project-sidebar', 'workspace-sidebar']),
+    screen: z.string().min(1).max(FIELD_LIMITS.nameChars),
+    label: z.string().min(1).max(60).optional(),
+    icon: z.string().max(60).optional(),
+});
+const collectionSchema = z.object({
+    /** Field name to type, in the manifest's spelling (`"member?"`, `["todo","done"]`). */
+    schema: z.record(z.string(), z.unknown()),
+    /** Fields the assistant may one day search by their words. */
+    search: z.array(z.string()).optional(),
+    /** The singular noun the tools are named with: `issue` gives `create_issue`. */
+    label: z.string().optional(),
+});
+const screenSchema = z.object({
+    /**
+     * Relative to the bundle's root: `screens/board.js` or `screens/board.mjs`.
+     * The server's schema said `.js` only while its store and the mount took
+     * `.mjs` too; the schema gives (E1 and Hodler, 16 Sep 14:04 and 14:12).
+     */
+    entry: z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^(?!\/)(?!.*\.\.)[A-Za-z0-9_\-./]+\.m?js$/, 'An entry is a .js or .mjs path inside the bundle.'),
+});
+/** Most custom tools one app may declare (A3-F08). */
+export const MAX_CUSTOM_TOOLS = 20;
+/** A tool name the model and a policy row can both use as it is. */
+export const CUSTOM_TOOL_NAME = /^[a-z][a-z0-9_]{0,59}$/;
+/**
+ * A tool the app writes itself (A3-F08-S01): a handler file in its bundle,
+ * run on Brydio's side in a box, taking `input` in the field-type grammar.
+ */
+const customToolSchema = z.object({
+    name: z.string().regex(CUSTOM_TOOL_NAME, 'A tool name is lower case letters, digits and underscores, starting with a letter.'),
+    description: z.string().min(1).max(1024),
+    /** Relative to the bundle's root: `handlers/list_prs.js`. */
+    handler: z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^(?!\/)(?!.*\.\.)[A-Za-z0-9_\-./]+\.m?js$/, 'A handler is a .js or .mjs path inside the bundle.'),
+    /** Field name to type, as a collection's schema writes it (`"string?"`). */
+    input: z.record(z.string(), z.unknown()).optional(),
+    /** True when running it changes something: it asks first, like a generated write. */
+    write: z.boolean().optional(),
+    /** The collection it works on, when it works on one: its grant then needs that collection too. */
+    collection: z.string().optional(),
+});
+const toolsSchema = z.object({
+    /** Off only when the app supplies every tool itself (A3-F08). */
+    generated: z.boolean().optional(),
+    custom: z.array(customToolSchema).max(MAX_CUSTOM_TOOLS).optional(),
+});
+const grantsSchema = z.object({
+    tools: z.array(z.string().max(100)).max(200).optional(),
+    collections: z.array(z.string().max(100)).max(FIELD_LIMITS.collections + 1).optional(),
+    host: z.array(z.string().max(60)).max(20).optional(),
+});
+const extensionShape = {
+    placements: z.array(placementSchema).max(20).optional(),
+    data: z.record(z.string(), collectionSchema).optional(),
+    tools: toolsSchema.optional(),
+    screens: z.record(z.string(), screenSchema).optional(),
+    grants: grantsSchema.optional(),
+    /**
+     * How records move when the schema changes between versions (A3-F07).
+     * Checked against the previous version when a version is published, and
+     * again when a workspace's pin moves; here only its shape.
+     */
+    migrations: migrationsSchema.optional(),
+    /**
+     * The `@brydio/app` version the bundle was built against, written by
+     * `brydio build` and never by hand. Optional, so a bundle from before it
+     * still loads; `POST /apps/publish` requires it and checks it (A5-F04-S03).
+     */
+    sdk: z.string().max(MANIFEST_LIMITS.versionChars).regex(SEMVER_FORMAT).optional(),
+};
+/**
+ * Everything wrong with an app's additions that a type cannot say.
+ *
+ * Exported on its own so E5's validator can fold the codes into its import
+ * report; the zod schemas below run it too, so a parse never accepts what
+ * this refuses.
+ */
+export function dataProblems(additions, options = {}) {
+    const problems = [];
+    const collections = Object.entries(additions.data ?? {});
+    if (collections.length > FIELD_LIMITS.collections) {
+        problems.push({
+            code: 'data_too_many_collections',
+            message: `An app may keep at most ${FIELD_LIMITS.collections} collections.`,
+        });
+    }
+    const labels = new Map();
+    for (const [collection, declared] of collections) {
+        if (!COLLECTION_NAME.test(collection) || collection.length > FIELD_LIMITS.nameChars) {
+            problems.push({
+                code: 'data_collection_name_format',
+                collection,
+                message: `${collection} is not a collection name: lower-case letters, digits and _, starting with a letter, at most ${FIELD_LIMITS.nameChars} characters.`,
+            });
+        }
+        const label = labelOf(collection, declared.label);
+        if (!COLLECTION_NAME.test(label) || label.length > FIELD_LIMITS.nameChars) {
+            problems.push({
+                code: 'data_label_format',
+                collection,
+                message: `${collection}'s label must be one lower-case word the tools can be named with, at most ${FIELD_LIMITS.nameChars} characters.`,
+            });
+        }
+        else if (labels.has(label)) {
+            // Two collections called "issue" would give two `create_issue` tools.
+            problems.push({
+                code: 'data_label_taken',
+                collection,
+                message: `${collection} and ${labels.get(label)} would both make tools called ${label}.`,
+            });
+        }
+        else {
+            labels.set(label, collection);
+        }
+        const fields = Object.entries(declared.schema);
+        if (fields.length > FIELD_LIMITS.fields) {
+            problems.push({
+                code: 'data_too_many_fields',
+                collection,
+                message: `A collection may have at most ${FIELD_LIMITS.fields} fields.`,
+            });
+        }
+        const types = new Map();
+        let projectField = null;
+        for (const [field, raw] of fields) {
+            if (RESERVED_FIELDS.has(field)) {
+                problems.push({
+                    code: 'data_field_reserved',
+                    collection,
+                    field,
+                    message: `${collection}.${field}: Brydio keeps ${field} on every record itself.`,
+                });
+                continue;
+            }
+            if (!FIELD_NAME.test(field) || field.length > FIELD_LIMITS.nameChars) {
+                problems.push({
+                    code: 'data_field_name_format',
+                    collection,
+                    field,
+                    message: `${collection}.${field} is not a field name: letters, digits and _, starting with a lower-case letter, at most ${FIELD_LIMITS.nameChars} characters.`,
+                });
+                continue;
+            }
+            try {
+                const type = parseFieldType(raw);
+                types.set(field, type);
+                if (type.kind === 'project') {
+                    // The record's project is copied to one indexed column, so a second
+                    // `project` field would have nowhere to go.
+                    if (projectField) {
+                        problems.push({
+                            code: 'data_project_field_twice',
+                            collection,
+                            field,
+                            message: `${collection} links to a project twice (${projectField} and ${field}); keep one.`,
+                        });
+                    }
+                    projectField = field;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof FieldTypeInvalid))
+                    throw error;
+                problems.push({
+                    code: error.code,
+                    collection,
+                    field,
+                    message: `${collection}.${field}: ${error.message}`,
+                });
+            }
+        }
+        for (const field of declared.search ?? []) {
+            const type = types.get(field);
+            if (!type) {
+                problems.push({
+                    code: 'data_search_unknown_field',
+                    collection,
+                    field,
+                    message: `${collection} searches ${field}, which is not one of its fields.`,
+                });
+            }
+            else if (!isSearchable(type)) {
+                problems.push({
+                    code: 'data_search_not_text',
+                    collection,
+                    field,
+                    message: `${collection}.${field} cannot be searched: only text fields can.`,
+                });
+            }
+        }
+    }
+    // What the app keeps must be what it asks to keep (A3-F06-S01): a
+    // collection the grants leave out would be data a workspace never agreed to
+    // hold, found only when the first write is refused.
+    const granted = additions.grants?.collections ?? [];
+    if (options.grants !== false && !granted.includes('*')) {
+        for (const [collection] of collections) {
+            if (!granted.includes(collection)) {
+                problems.push({
+                    code: 'grant_collection_missing',
+                    collection,
+                    message: `${collection} is kept but not asked for: add it to grants.collections.`,
+                });
+            }
+        }
+    }
+    problems.push(...customToolProblems(additions, options));
+    const screens = new Set(Object.keys(additions.screens ?? {}));
+    for (const placement of additions.placements ?? []) {
+        if (!screens.has(placement.screen)) {
+            problems.push({
+                code: 'placement_screen_unknown',
+                message: `A ${placement.kind} placement opens "${placement.screen}", which is not one of the app's screens.`,
+            });
+        }
+    }
+    return problems;
+}
+/**
+ * A custom tool must be granted by name (or `*`), take a name no generated
+ * tool has, name a collection the app keeps, and take input in the field-type
+ * grammar (A3-F08-S01). That its handler file is in the bundle is checked
+ * where the files are: `POST /apps/publish`.
+ */
+function customToolProblems(additions, options) {
+    const problems = [];
+    const custom = additions.tools?.custom ?? [];
+    // Named from the manifest directly: `collectionsOf` validates through this
+    // very check, and would come back here.
+    const generated = additions.tools?.generated === false
+        ? new Set()
+        : new Set(Object.entries(additions.data ?? {}).flatMap(([name, declared]) => {
+            const label = labelOf(name, declared.label);
+            const plural = `${label}s`;
+            return [
+                `create_${label}`,
+                `update_${label}`,
+                `get_${label}`,
+                `delete_${label}`,
+                `list_${plural}`,
+                `search_${plural}`,
+                `batch_${plural}`,
+            ];
+        }));
+    const seen = new Set();
+    const granted = additions.grants?.tools ?? [];
+    for (const tool of custom) {
+        if (generated.has(tool.name) || seen.has(tool.name)) {
+            problems.push({
+                code: 'custom_name_taken',
+                message: `${tool.name} is already a tool this app has: give the custom tool another name, or switch generated tools off.`,
+            });
+        }
+        seen.add(tool.name);
+        if (tool.collection !== undefined && !additions.data?.[tool.collection]) {
+            problems.push({
+                code: 'custom_collection_unknown',
+                collection: tool.collection,
+                message: `${tool.name} works on ${tool.collection}, which the app does not keep.`,
+            });
+        }
+        for (const [field, raw] of Object.entries(tool.input ?? {})) {
+            try {
+                parseFieldType(raw);
+            }
+            catch (error) {
+                problems.push({
+                    code: 'custom_input_invalid',
+                    field,
+                    message: `${tool.name}'s input ${field}: ${error instanceof Error ? error.message : 'not a field type'}`,
+                });
+            }
+        }
+        if (options.grants !== false && !granted.includes('*') && !granted.includes(tool.name)) {
+            problems.push({
+                code: 'grant_tool_missing',
+                message: `${tool.name} is a custom tool but not asked for: add it to grants.tools.`,
+            });
+        }
+    }
+    return problems;
+}
+const refuse = (additions, ctx, options = {}) => {
+    for (const problem of dataProblems(additions, options)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: problem.message,
+            path: problem.code === 'grant_tool_missing'
+                ? ['grants', 'tools']
+                : problem.code.startsWith('grant_')
+                    ? ['grants', 'collections']
+                    : problem.code.startsWith('custom_')
+                        ? ['tools', 'custom']
+                        : problem.collection
+                            ? ['data', problem.collection, ...(problem.field ? ['schema', problem.field] : [])]
+                            : [],
+            params: { code: problem.code },
+        });
+    }
+};
+/** The additions alone, for code that has the rest of the manifest already. */
+export const manifestExtensionsSchema = z.object(extensionShape).superRefine((additions, ctx) => refuse(additions, ctx));
+/**
+ * The additions as code reads a manifest that was checked whole when it was
+ * published. Everything but the grants cross-check: what is granted is the
+ * install's record to answer (A3-F06), not the stored manifest's.
+ */
+export const storedExtensionsSchema = z.object(extensionShape).superRefine((additions, ctx) => refuse(additions, ctx, { grants: false }));
+/** E5's manifest with the additions: the whole `.brydio/app.json` of an app. */
+export const appManifestSchema = manifestSchema.extend(extensionShape).superRefine((additions, ctx) => refuse(additions, ctx));
+/**
+ * The singular a collection's tools are named with: the manifest's, else the
+ * collection's name with a trailing "s" taken off (`issues` → `issue`).
+ */
+export function labelOf(collection, label) {
+    if (label)
+        return label;
+    return collection.length > 1 && collection.endsWith('s') ? collection.slice(0, -1) : collection;
+}
+/**
+ * Every collection an app declares, parsed. Throws on a manifest that
+ * `dataProblems` would refuse: callers read manifests that were validated
+ * when they were stored, and a bad one here is a bug, not input.
+ */
+export function collectionsOf(manifest) {
+    const parsed = storedExtensionsSchema.parse({ data: manifest.data ?? {} });
+    return Object.entries(parsed.data ?? {}).map(([name, declared]) => {
+        const fields = Object.fromEntries(Object.entries(declared.schema).map(([field, raw]) => [field, parseFieldType(raw)]));
+        const label = labelOf(name, declared.label);
+        const names = Object.keys(fields);
+        return {
+            name,
+            label,
+            plural: `${label}s`,
+            fields,
+            structured: names.filter(field => isStructured(fields[field])),
+            sortable: names.filter(field => isSortable(fields[field])),
+            search: declared.search ?? [],
+            projectField: names.find(field => fields[field].kind === 'project') ?? null,
+        };
+    });
+}
+/** One collection by name, or null when the app keeps no such thing. */
+export function collectionOf(manifest, collection) {
+    return collectionsOf(manifest).find(one => one.name === collection) ?? null;
+}

package/src/sdk.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Which SDK built a version, and whether a Brydio runs it (A5-F04-S03).
+ *
+ * `brydio build` writes the `@brydio/app` version it built against into the
+ * bundle's `app.json` as `sdk`. Brydio says which versions it runs at
+ * `GET /api/v1/apps/sdk` as `{ oldest, before }`, and refuses a publish
+ * outside them as `sdk_unsupported` (422, `at: "sdk"`). `brydio publish` asks
+ * first and refuses with the same sentence before uploading anything.
+ *
+ * Copies of the server's `apps/api/src/apps/publishing/sdk-support.ts`
+ * (`sdkRefusal`, given the range rather than reading the host's constant) and
+ * `apps/api/src/apps/versions/compare-versions.ts`, word for word;
+ * `manifest.test.ts` compares them whenever a Brydio checkout sits beside
+ * this repository.
+ */
+/** The SDK versions a Brydio runs: from `oldest`, up to but not including `before`. */
+export interface SdkSupport {
+    oldest: string;
+    before: string;
+}
+/** Null when an app built with this SDK can run on a Brydio with this support; otherwise the sentence why not. */
+export declare function sdkRefusal(sdk: unknown, support: SdkSupport): string | null;
+/**
+ * Which of two version numbers is newer, by semver's precedence rules. Build
+ * metadata (`+abc`) is ignored, as semver says.
+ *
+ * Negative when `a` is older, positive when newer, zero when they are the
+ * same release.
+ */
+export declare function compareVersions(a: string, b: string): number;

package/src/sdk.js

@@ -0,0 +1,77 @@
+/**
+ * Which SDK built a version, and whether a Brydio runs it (A5-F04-S03).
+ *
+ * `brydio build` writes the `@brydio/app` version it built against into the
+ * bundle's `app.json` as `sdk`. Brydio says which versions it runs at
+ * `GET /api/v1/apps/sdk` as `{ oldest, before }`, and refuses a publish
+ * outside them as `sdk_unsupported` (422, `at: "sdk"`). `brydio publish` asks
+ * first and refuses with the same sentence before uploading anything.
+ *
+ * Copies of the server's `apps/api/src/apps/publishing/sdk-support.ts`
+ * (`sdkRefusal`, given the range rather than reading the host's constant) and
+ * `apps/api/src/apps/versions/compare-versions.ts`, word for word;
+ * `manifest.test.ts` compares them whenever a Brydio checkout sits beside
+ * this repository.
+ */
+/** Null when an app built with this SDK can run on a Brydio with this support; otherwise the sentence why not. */
+export function sdkRefusal(sdk, support) {
+    const range = `Brydio runs apps built with SDK ${support.oldest} or newer, before ${support.before}.`;
+    if (typeof sdk !== 'string' || sdk.length === 0) {
+        return `app.json does not say which SDK built it. Build it with brydio build. ${range}`;
+    }
+    // `before` excludes its own prereleases too: 0.2.0-beta is not a 0.1 SDK.
+    if (compareVersions(sdk, support.oldest) < 0 || compareVersions(sdk, `${support.before}-0`) >= 0) {
+        return `This app was built with SDK ${sdk}. ${range}`;
+    }
+    return null;
+}
+/**
+ * Which of two version numbers is newer, by semver's precedence rules. Build
+ * metadata (`+abc`) is ignored, as semver says.
+ *
+ * Negative when `a` is older, positive when newer, zero when they are the
+ * same release.
+ */
+export function compareVersions(a, b) {
+    const [coreA, preA] = split(a);
+    const [coreB, preB] = split(b);
+    for (let i = 0; i < 3; i++) {
+        const difference = (coreA[i] ?? 0) - (coreB[i] ?? 0);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    // A release is newer than any of its prereleases.
+    if (preA.length === 0 || preB.length === 0)
+        return Math.sign(preB.length - preA.length);
+    for (let i = 0; i < Math.max(preA.length, preB.length); i++) {
+        const x = preA[i];
+        const y = preB[i];
+        // A longer prerelease with the same start is newer: 1.0.0-beta < 1.0.0-beta.1.
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const numericX = /^\d+$/.test(x);
+        const numericY = /^\d+$/.test(y);
+        if (numericX && numericY) {
+            const difference = Number(x) - Number(y);
+            if (difference !== 0)
+                return Math.sign(difference);
+        }
+        else if (numericX !== numericY) {
+            // Numbers sort before words: 1.0.0-1 < 1.0.0-alpha.
+            return numericX ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function split(version) {
+    const withoutBuild = version.split('+')[0];
+    const dash = withoutBuild.indexOf('-');
+    const core = dash === -1 ? withoutBuild : withoutBuild.slice(0, dash);
+    const pre = dash === -1 ? '' : withoutBuild.slice(dash + 1);
+    return [core.split('.').map(Number), pre ? pre.split('.') : []];
+}

package/src/secrets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Finding a secret somebody shipped inside a bundle (A8-F04-S03).
+ *
+ * A copy of Brydio's `apps/api/src/extensions/apps/secret-scan.ts`, which
+ * `POST /apps/publish` runs over every upload and refuses as
+ * `secret_in_bundle`. The same keys, the same idea of a placeholder, the same
+ * two places looked in, and the same sentence, so `brydio validate` refuses
+ * exactly what the server would and nothing else.
+ *
+ * The scan is deliberately narrow, as the server's is. It looks only where a
+ * package *declares* credentials, `servers.json` and `integrations/*.json`,
+ * where a value is unambiguous, and in the bundle's own `app.json`
+ * (`secretsInJson`), rather than grepping scripts for things that look like
+ * keys: a pattern scan of minified code misses real keys and refuses innocent
+ * strings (Hodler, 16 Sep).
+ */
+/** The server's sentence for `brydio_secret_in_package`, which publishing sends as `secret_in_bundle`. */
+export declare const SECRET_MESSAGE = "That package contains a secret. Header values and client secrets are entered here, never shipped in a file \u2014 remove it and import again.";
+export interface SecretFound {
+    code: 'secret_in_bundle';
+    message: string;
+    /** Where: the file and the path inside it. The value itself is never carried. */
+    path: string;
+}
+/**
+ * Every secret-shaped value in one JSON document, by the same keys and the
+ * same placeholder rules: for a bundle's `app.json`, which Brydio serves to
+ * every screen that opens it and scans at publish (`secretsInJson`).
+ */
+export declare function secretsInJson(document: unknown, at: string): SecretFound[];
+/** Every secret declared in a bundle's files, as the server finds them. */
+export declare function findSecrets(files: ReadonlyMap<string, Uint8Array>, root?: string): SecretFound[];

package/src/secrets.js

@@ -0,0 +1,81 @@
+/**
+ * Finding a secret somebody shipped inside a bundle (A8-F04-S03).
+ *
+ * A copy of Brydio's `apps/api/src/extensions/apps/secret-scan.ts`, which
+ * `POST /apps/publish` runs over every upload and refuses as
+ * `secret_in_bundle`. The same keys, the same idea of a placeholder, the same
+ * two places looked in, and the same sentence, so `brydio validate` refuses
+ * exactly what the server would and nothing else.
+ *
+ * The scan is deliberately narrow, as the server's is. It looks only where a
+ * package *declares* credentials, `servers.json` and `integrations/*.json`,
+ * where a value is unambiguous, and in the bundle's own `app.json`
+ * (`secretsInJson`), rather than grepping scripts for things that look like
+ * keys: a pattern scan of minified code misses real keys and refuses innocent
+ * strings (Hodler, 16 Sep).
+ */
+/** The server's sentence for `brydio_secret_in_package`, which publishing sends as `secret_in_bundle`. */
+export const SECRET_MESSAGE = 'That package contains a secret. Header values and client secrets are entered here, never shipped in a file — remove it and import again.';
+/** The keys that hold a value rather than a name, in either declaration. */
+const VALUE_KEYS = new Set(['value', 'clientSecret', 'client_secret', 'secret', 'apiKey', 'api_key', 'key', 'token', 'password']);
+/** A value that is actually one, rather than a placeholder asking to be filled. */
+const isRealValue = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return false;
+    if (/^[<{[].*[>}\]]$/.test(trimmed))
+        return false;
+    if (/^(your|my|the)[ _-]/i.test(trimmed))
+        return false;
+    if (/^(x+|\*+|\.+|todo|tbd|changeme|redacted|placeholder)$/i.test(trimmed))
+        return false;
+    return true;
+};
+function walk(node, at, found) {
+    if (Array.isArray(node)) {
+        node.forEach((one, index) => walk(one, `${at}[${index}]`, found));
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        const path = at ? `${at}.${key}` : key;
+        if (VALUE_KEYS.has(key) && isRealValue(value)) {
+            // Never quoted back: a report that repeated the secret would copy it somewhere else.
+            found.push({ code: 'secret_in_bundle', message: SECRET_MESSAGE, path });
+            continue;
+        }
+        walk(value, path, found);
+    }
+}
+/**
+ * Every secret-shaped value in one JSON document, by the same keys and the
+ * same placeholder rules: for a bundle's `app.json`, which Brydio serves to
+ * every screen that opens it and scans at publish (`secretsInJson`).
+ */
+export function secretsInJson(document, at) {
+    const found = [];
+    walk(document, at, found);
+    return found;
+}
+/** Every secret declared in a bundle's files, as the server finds them. */
+export function findSecrets(files, root = '') {
+    const found = [];
+    for (const [path, bytes] of files) {
+        const relative = root && path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+        const declares = relative === 'servers.json' || (relative.startsWith('integrations/') && relative.endsWith('.json'));
+        if (!declares)
+            continue;
+        try {
+            walk(JSON.parse(new TextDecoder().decode(bytes)), relative, found);
+        }
+        catch {
+            // A file that will not parse is refused elsewhere.
+        }
+    }
+    return found;
+}

package/src/tools.d.ts

@@ -0,0 +1,21 @@
+import { type CollectionSpec, type ManifestExtensions } from './schema.js';
+/**
+ * The names of the tools Brydio generates for a collection (contracts §6).
+ *
+ * As `apps/api/src/apps/tools/generated-tools.ts` names them: the singular
+ * label for one record, and the label with an "s" for many, so a collection
+ * labelled `issue` gets `create_issue` and `list_issues`. The plural is the
+ * label's, not the collection's name, which is what the server does.
+ */
+export type ToolVerb = 'create' | 'update' | 'get' | 'list' | 'search' | 'delete';
+/** Whether the tool writes, and so asks the person first from a screen (§6, §7). */
+export declare const TOOL_WRITES: Readonly<Record<ToolVerb, boolean>>;
+export declare function toolNames(spec: Pick<CollectionSpec, 'label' | 'plural'>): Record<ToolVerb, string>;
+export interface GeneratedTool {
+    name: string;
+    verb: ToolVerb;
+    collection: string;
+    write: boolean;
+}
+/** Every generated tool of a manifest's collections, or none when generation is off. */
+export declare function generatedToolsOf(manifest: Pick<ManifestExtensions, 'data' | 'tools'>): GeneratedTool[];

package/src/tools.js

@@ -0,0 +1,31 @@
+import { collectionsOf } from "./schema.js";
+/** Whether the tool writes, and so asks the person first from a screen (§6, §7). */
+export const TOOL_WRITES = {
+    create: true,
+    update: true,
+    get: false,
+    list: false,
+    search: false,
+    delete: true,
+};
+export function toolNames(spec) {
+    return {
+        create: `create_${spec.label}`,
+        update: `update_${spec.label}`,
+        get: `get_${spec.label}`,
+        list: `list_${spec.plural}`,
+        search: `search_${spec.plural}`,
+        delete: `delete_${spec.label}`,
+    };
+}
+/** Every generated tool of a manifest's collections, or none when generation is off. */
+export function generatedToolsOf(manifest) {
+    if (manifest.tools?.generated === false)
+        return [];
+    return collectionsOf(manifest).flatMap(spec => Object.entries(toolNames(spec)).map(([verb, name]) => ({
+        name,
+        verb,
+        collection: spec.name,
+        write: TOOL_WRITES[verb],
+    })));
+}

package/src/validate.d.ts

@@ -0,0 +1,27 @@
+import { type AppManifestWithData, type DataProblemCode } from './schema.js';
+/**
+ * Reading a manifest and saying what is wrong with it, the way Brydio would.
+ *
+ * The answer is the schema's: a manifest is valid here exactly when
+ * `appManifestSchema` accepts it, which is the server's schema, copied. Each
+ * problem keeps the server's code where it has one (`data_label_taken`,
+ * `placement_screen_unknown`), and a field that is simply the wrong shape is
+ * `manifest_invalid` with the path to it, so an app's builder can find the
+ * line.
+ */
+export type ManifestProblemCode = DataProblemCode | 'manifest_not_json' | 'manifest_invalid';
+export interface ManifestProblem {
+    code: ManifestProblemCode;
+    message: string;
+    /** Where in the manifest, like `placements.0.screen`. */
+    path?: string;
+}
+export interface ManifestValidation {
+    ok: boolean;
+    /** Present only when `ok`: the manifest as Brydio parses it. */
+    manifest?: AppManifestWithData;
+    problems: ManifestProblem[];
+}
+export declare function validateManifest(source: unknown): ManifestValidation;
+/** Parses the text of `.brydio/app.json` and validates it. */
+export declare function validateManifestText(text: string): ManifestValidation;