@brydio/manifest 0.1.0-alpha.3 → 0.1.0-alpha.32

package/src/schema.js

@@ -18,11 +18,81 @@ export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structure
  * 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 placementSettingSchema = z.object({
+    type: z.enum(['string', 'url']),
+    label: z.string().min(1).max(60),
+    required: z.boolean().optional(),
+    placeholder: z.string().max(200).optional(),
+});
+/**
+ * How deep a folder's rows may nest, counting its own rows as the first
+ * level (ADR-A21): Issues → sprints → issues is two. Each level is listed
+ * only when a person opens its parent, so depth costs nothing while closed;
+ * the limit is for the sidebar's width and a person's patience.
+ */
+export const MAX_FOLDER_DEPTH = 4;
+/**
+ * "New sprint" on a folder's level (ADR-A21): one of the app's tools, run
+ * through the screen's door with the name the person typed in `titleField`
+ * and, below the first level, the row it is created under in `parentField`.
+ */
+const folderCreateSchema = z.object({
+    tool: z.string().min(1).max(64),
+    /** "sprint", in "New sprint". */
+    noun: z.string().min(1).max(40).optional(),
+    titleField: z.string().regex(FIELD_NAME, 'A field name is letters, digits and _, starting with a lower-case letter.').optional(),
+    parentField: z.string().regex(FIELD_NAME, 'A field name is letters, digits and _, starting with a lower-case letter.').optional(),
+});
+/** A level below a folder's own rows: what they are called, and how one is made. */
+const folderLevelSchema = z.object({
+    noun: z.string().min(1).max(60).optional(),
+    create: folderCreateSchema.optional(),
+});
+/** The sizes a Home card or a project widget can be drawn at (CC11-F10). */
+export const HOME_CARD_SIZES = ['small', 'medium', 'large'];
+/** The kinds drawn as a card, which say the sizes they draw well at. */
+export const SIZED_PLACEMENT_KINDS = ['home', 'project-widget'];
+/** A stable identity for one independently addable placement offering. */
+export const PLACEMENT_KEY = /^[a-z][a-z0-9-]{0,39}$/;
+export function effectivePlacementKey(one) {
+    return one.key ?? `${one.kind}:${one.screen}`;
+}
 const placementSchema = z.object({
-    kind: z.enum(['project-tab', 'project-sidebar', 'workspace-sidebar']),
+    key: z.string().regex(PLACEMENT_KEY).optional(),
+    /**
+     * `home`: a card on a person's Home, drawn by `screen` at one of `sizes`.
+     * `project-widget`: a card on a project's page, drawn at one of `sizes`.
+     * `project-tab` is retired (30 Sep 2026): still read from a published
+     * manifest, refused in a new one (`placement_tab_retired`).
+     */
+    kind: z.enum(['project-tab', 'project-widget', 'project-sidebar', 'workspace-sidebar', 'home']),
     screen: z.string().min(1).max(FIELD_LIMITS.nameChars),
+    /** For `home` and `project-widget` only, and required there: the sizes the screen draws well at. */
+    sizes: z.array(z.enum(HOME_CARD_SIZES)).max(3).optional(),
     label: z.string().min(1).max(60).optional(),
     icon: z.string().max(60).optional(),
+    settings: z.record(z.string().regex(FIELD_NAME), placementSettingSchema).optional(),
+    /**
+     * A folder (A2-F02-S02): a sidebar item whose rows one of the app's read
+     * tools lists live, only while it is open. It can nest, and offer "New …"
+     * at each level, when the app opts in (ADR-A21).
+     */
+    children: z
+        .object({
+        tool: z.string().min(1).max(64),
+        refreshSeconds: z.number().int().min(15).max(3600).optional(),
+        cap: z.number().int().min(1).max(50).optional(),
+        noun: z.string().min(1).max(60).optional(),
+        /** A "New …" row at the folder's first level (ADR-A21). */
+        create: folderCreateSchema.optional(),
+        /**
+         * The levels under the first, in order (ADR-A21). A row the tool marks
+         * `hasChildren` opens only when a level is declared for it; without
+         * `nested` the folder stays one flat list.
+         */
+        nested: z.array(folderLevelSchema).max(8).optional(),
+    })
+        .optional(),
 });
 const collectionSchema = z.object({
     /** Field name to type, in the manifest's spelling (`"member?"`, `["todo","done"]`). */
@@ -73,6 +143,28 @@ const toolsSchema = z.object({
     generated: z.boolean().optional(),
     custom: z.array(customToolSchema).max(MAX_CUSTOM_TOOLS).optional(),
 });
+/** Most secrets one app may declare (ADR-A24). */
+export const MAX_APP_SECRETS = 20;
+/** The longest value one secret may hold, in characters. */
+export const MAX_SECRET_CHARS = 8 * 1024;
+/** A secret's name, as a handler asks for it: `api_key`. */
+export const SECRET_NAME = /^[a-z][a-z0-9_]{0,59}$/;
+/**
+ * A secret the app needs (ADR-A24): named here, never valued here. The value
+ * is entered in the app's settings by an administrator, or stored by the
+ * app's own handler with `secrets.set`, and only that app's handlers can read
+ * it, with `secrets.get`. A screen never can.
+ *
+ * `install` (the default) is one value for the whole install; `instance` is
+ * one per instance.
+ */
+const secretSchema = z.object({
+    name: z.string().regex(SECRET_NAME, 'A secret name is lower case letters, digits and underscores, starting with a letter.'),
+    label: z.string().min(1).max(60),
+    description: z.string().max(300).optional(),
+    required: z.boolean().optional(),
+    scope: z.enum(['install', 'instance']).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(),
@@ -84,6 +176,8 @@ const extensionShape = {
     tools: toolsSchema.optional(),
     screens: z.record(z.string(), screenSchema).optional(),
     grants: grantsSchema.optional(),
+    /** The secrets its handlers read (ADR-A24): names only, never values. */
+    secrets: z.array(secretSchema).max(MAX_APP_SECRETS).optional(),
     /**
      * How records move when the schema changes between versions (A3-F07).
      * Checked against the previous version when a version is published, and
@@ -97,13 +191,6 @@ const extensionShape = {
      */
     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 ?? {});
@@ -234,14 +321,106 @@ export function dataProblems(additions, options = {}) {
         }
     }
     problems.push(...customToolProblems(additions, options));
+    problems.push(...secretProblems(additions, options));
     const screens = new Set(Object.keys(additions.screens ?? {}));
+    const placementKeys = new Set();
     for (const placement of additions.placements ?? []) {
+        const key = effectivePlacementKey(placement);
+        if (placementKeys.has(key)) {
+            problems.push({
+                code: 'placement_key_taken',
+                message: `Two placements use the key "${key}"; each independently addable placement needs its own key.`,
+            });
+        }
+        else {
+            placementKeys.add(key);
+        }
         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.`,
             });
         }
+        // A card must say how big it can be drawn (CC11-F10-S01).
+        if (placement.kind === 'home' && !placement.sizes?.length) {
+            problems.push({
+                code: 'placement_home_sizes',
+                message: `The Home card "${placement.screen}" must say which sizes it draws at: small, medium or large.`,
+            });
+        }
+        if (placement.kind === 'project-widget' && !placement.sizes?.length) {
+            problems.push({
+                code: 'placement_widget_sizes',
+                message: `The project widget "${placement.screen}" must say which sizes it draws at: small, medium or large.`,
+            });
+        }
+        if (!SIZED_PLACEMENT_KINDS.includes(placement.kind) && placement.sizes?.length) {
+            problems.push({
+                code: 'placement_sizes_not_home',
+                message: `Only a Home card or a project widget has sizes; the ${placement.kind} placement "${placement.screen}" cannot.`,
+            });
+        }
+        if (options.retired && placement.kind === 'project-tab') {
+            problems.push({
+                code: 'placement_tab_retired',
+                message: 'Project tabs are retired; declare a project-widget with sizes instead.',
+            });
+        }
+    }
+    problems.push(...folderProblems(additions));
+    return problems;
+}
+/**
+ * A folder that nests or creates (ADR-A21) must stay within
+ * `MAX_FOLDER_DEPTH`, and each "New …" must name a tool the app has that
+ * changes records. Only the new keys are checked: a published manifest's
+ * existing folder still reads as it did.
+ */
+function folderProblems(additions) {
+    const problems = [];
+    const custom = new Map((additions.tools?.custom ?? []).map(tool => [tool.name, tool]));
+    const generatedWrites = additions.tools?.generated === false
+        ? new Set()
+        : new Set(Object.entries(additions.data ?? {}).flatMap(([name, declared]) => {
+            const label = labelOf(name, declared.label);
+            return [`create_${label}`, `update_${label}`, `delete_${label}`, `batch_${label}s`];
+        }));
+    const generatedReads = additions.tools?.generated === false
+        ? new Set()
+        : new Set(Object.entries(additions.data ?? {}).flatMap(([name, declared]) => {
+            const label = labelOf(name, declared.label);
+            return [`get_${label}`, `list_${label}s`, `search_${label}s`];
+        }));
+    for (const placement of additions.placements ?? []) {
+        const children = placement.children;
+        if (!children)
+            continue;
+        const depth = 1 + (children.nested?.length ?? 0);
+        if (depth > MAX_FOLDER_DEPTH) {
+            problems.push({
+                code: 'placement_children_too_deep',
+                message: `The "${placement.screen}" folder nests ${depth} levels deep; a sidebar folder may nest at most ${MAX_FOLDER_DEPTH}.`,
+            });
+        }
+        const creates = [children.create, ...(children.nested ?? []).map(level => level.create)];
+        for (const create of creates) {
+            if (!create)
+                continue;
+            const own = custom.get(create.tool);
+            const reads = own ? own.write !== true : generatedReads.has(create.tool);
+            if (!own && !reads && !generatedWrites.has(create.tool)) {
+                problems.push({
+                    code: 'placement_create_tool_unknown',
+                    message: `The "${placement.screen}" folder creates with ${create.tool}, which is not one of the app's tools.`,
+                });
+            }
+            else if (reads) {
+                problems.push({
+                    code: 'placement_create_not_write',
+                    message: `The "${placement.screen}" folder creates with ${create.tool}, which only reads: name a tool that makes records, or mark a custom one write: true.`,
+                });
+            }
+        }
     }
     return problems;
 }
@@ -309,6 +488,33 @@ function customToolProblems(additions, options) {
     }
     return problems;
 }
+/**
+ * Each secret declared once, and asked for (ADR-A24): an app that declares
+ * secrets without the `secrets` host grant could never read one.
+ */
+function secretProblems(additions, options) {
+    const problems = [];
+    const secrets = additions.secrets ?? [];
+    const seen = new Set();
+    for (const secret of secrets) {
+        if (seen.has(secret.name)) {
+            problems.push({
+                code: 'secret_name_taken',
+                field: secret.name,
+                message: `The secret ${secret.name} is declared twice; keep one.`,
+            });
+        }
+        seen.add(secret.name);
+    }
+    const host = additions.grants?.host ?? [];
+    if (options.grants !== false && secrets.length && !host.includes('secrets') && !host.includes('*')) {
+        problems.push({
+            code: 'grant_secrets_missing',
+            message: 'The app declares secrets but does not ask to read them: add "secrets" to grants.host.',
+        });
+    }
+    return problems;
+}
 const refuse = (additions, ctx, options = {}) => {
     for (const problem of dataProblems(additions, options)) {
         ctx.addIssue({
@@ -316,13 +522,17 @@ const refuse = (additions, ctx, options = {}) => {
             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] : [])]
-                            : [],
+                : problem.code === 'grant_secrets_missing'
+                    ? ['grants', 'host']
+                    : problem.code === 'secret_name_taken'
+                        ? ['secrets']
+                        : 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 },
         });
     }
@@ -337,6 +547,14 @@ export const manifestExtensionsSchema = z.object(extensionShape).superRefine((ad
 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));
+/**
+ * A manifest being written now, as `brydio validate`, `build` and `dev` read
+ * it: the same, and nothing retired (`placement_tab_retired`) — which a
+ * published version may still hold.
+ */
+export const newAppManifestSchema = manifestSchema
+    .extend(extensionShape)
+    .superRefine((additions, ctx) => refuse(additions, ctx, { retired: true }));
 /**
  * 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`).

package/src/secrets.d.ts

@@ -30,3 +30,17 @@ export interface SecretFound {
 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[];
+/**
+ * The server's sentence for `developer_key_in_bundle` (ADR-A22), word for
+ * word: `DEVELOPER_KEY_IN_BUNDLE` in Brydio's `app-publish.service.ts`.
+ */
+export declare const DEVELOPER_KEY_MESSAGE = "That package contains a Brydio developer API key. A key belongs on your own server, never in an app: revoke it in Settings \u203A Developer, and call Brydio\u2019s model from a handler with the model grant instead.";
+/** Whether a text holds a Brydio developer API key. */
+export declare const holdsDeveloperKey: (text: string) => boolean;
+/**
+ * The first file holding a developer API key, by path, as Brydio's publish
+ * route finds it (`developerKeyIn`). Unlike the declaration scan, every file
+ * is read, scripts included: the key's shape is exact enough that a match is
+ * a key, not a guess, and no part of an app may hold one (ADR-A24).
+ */
+export declare function developerKeyIn(files: ReadonlyMap<string, Uint8Array>): string | null;

package/src/secrets.js

@@ -35,21 +35,21 @@ const isRealValue = (value) => {
         return false;
     return true;
 };
-function walk(node, at, found) {
+function walk(node, at, found, publicValue = () => false) {
     if (Array.isArray(node)) {
-        node.forEach((one, index) => walk(one, `${at}[${index}]`, found));
+        node.forEach((one, index) => walk(one, `${at}[${index}]`, found, publicValue));
         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)) {
+        if (VALUE_KEYS.has(key) && isRealValue(value) && !publicValue(path)) {
             // 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);
+        walk(value, path, found, publicValue);
     }
 }
 /**
@@ -59,7 +59,7 @@ function walk(node, at, found) {
  */
 export function secretsInJson(document, at) {
     const found = [];
-    walk(document, at, found);
+    walk(document, at, found, path => /(?:^|\.)placements\[\d+\]\.key$/.test(path));
     return found;
 }
 /** Every secret declared in a bundle's files, as the server finds them. */
@@ -79,3 +79,25 @@ export function findSecrets(files, root = '') {
     }
     return found;
 }
+/**
+ * The server's sentence for `developer_key_in_bundle` (ADR-A22), word for
+ * word: `DEVELOPER_KEY_IN_BUNDLE` in Brydio's `app-publish.service.ts`.
+ */
+export const DEVELOPER_KEY_MESSAGE = 'That package contains a Brydio developer API key. A key belongs on your own server, never in an app: revoke it in Settings › Developer, and call Brydio’s model from a handler with the model grant instead.';
+/** A developer API key's exact shape, anywhere in a text. */
+const DEVELOPER_KEY = /bry_live_[0-9a-f]{12}_[A-Za-z0-9_-]{43}/;
+/** Whether a text holds a Brydio developer API key. */
+export const holdsDeveloperKey = (text) => DEVELOPER_KEY.test(text);
+/**
+ * The first file holding a developer API key, by path, as Brydio's publish
+ * route finds it (`developerKeyIn`). Unlike the declaration scan, every file
+ * is read, scripts included: the key's shape is exact enough that a match is
+ * a key, not a guess, and no part of an app may hold one (ADR-A24).
+ */
+export function developerKeyIn(files) {
+    for (const [path, bytes] of files) {
+        if (holdsDeveloperKey(new TextDecoder('latin1').decode(bytes)))
+            return path;
+    }
+    return null;
+}

package/src/validate.d.ts

@@ -22,6 +22,12 @@ export interface ManifestValidation {
     manifest?: AppManifestWithData;
     problems: ManifestProblem[];
 }
-export declare function validateManifest(source: unknown): ManifestValidation;
+export declare function validateManifest(source: unknown, 
+/** `retired`: a manifest being written now, which may not use a retired kind such as `project-tab`. */
+options?: {
+    retired?: boolean;
+}): ManifestValidation;
 /** Parses the text of `.brydio/app.json` and validates it. */
-export declare function validateManifestText(text: string): ManifestValidation;
+export declare function validateManifestText(text: string, options?: {
+    retired?: boolean;
+}): ManifestValidation;

package/src/validate.js

@@ -1,6 +1,8 @@
-import { appManifestSchema } from "./schema.js";
-export function validateManifest(source) {
-    const parsed = appManifestSchema.safeParse(source);
+import { appManifestSchema, newAppManifestSchema } from "./schema.js";
+export function validateManifest(source, 
+/** `retired`: a manifest being written now, which may not use a retired kind such as `project-tab`. */
+options = {}) {
+    const parsed = (options.retired ? newAppManifestSchema : appManifestSchema).safeParse(source);
     if (parsed.success)
         return { ok: true, manifest: parsed.data, problems: [] };
     return {
@@ -14,7 +16,7 @@ export function validateManifest(source) {
     };
 }
 /** Parses the text of `.brydio/app.json` and validates it. */
-export function validateManifestText(text) {
+export function validateManifestText(text, options = {}) {
     let json;
     try {
         json = JSON.parse(text);
@@ -25,5 +27,5 @@ export function validateManifestText(text) {
             problems: [{ code: 'manifest_not_json', message: `The manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}` }],
         };
     }
-    return validateManifest(json);
+    return validateManifest(json, options);
 }