@brydio/manifest 0.1.0-alpha.6 → 0.1.0-alpha.9

package/src/schema.d.ts

@@ -26,6 +26,20 @@ declare const placementSettingSchema: z.ZodObject<{
     placeholder: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PlacementSettingSpec = z.infer<typeof placementSettingSchema>;
+/**
+ * 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 declare const MAX_FOLDER_DEPTH = 4;
+/** A stable identity for one independently addable placement offering. */
+export declare const PLACEMENT_KEY: RegExp;
+export declare function effectivePlacementKey(one: {
+    key?: string;
+    kind: string;
+    screen: string;
+}): string;
 /** Most custom tools one app may declare (A3-F08). */
 export declare const MAX_CUSTOM_TOOLS = 20;
 /** A tool name the model and a policy row can both use as it is. */
@@ -43,12 +57,40 @@ declare const customToolSchema: z.ZodObject<{
     collection: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CustomToolSpec = z.infer<typeof customToolSchema>;
+/** Most secrets one app may declare (ADR-A24). */
+export declare const MAX_APP_SECRETS = 20;
+/** The longest value one secret may hold, in characters. */
+export declare const MAX_SECRET_CHARS: number;
+/** A secret's name, as a handler asks for it: `api_key`. */
+export declare const SECRET_NAME: RegExp;
+/**
+ * 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.
+ */
+declare const secretSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        instance: "instance";
+        install: "install";
+    }>>;
+}, z.core.$strip>;
+export type SecretSpec = z.infer<typeof secretSchema>;
 declare const extensionShape: {
     placements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             "project-tab": "project-tab";
             "project-sidebar": "project-sidebar";
             "workspace-sidebar": "workspace-sidebar";
+            home: "home";
         }>;
         screen: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
@@ -62,6 +104,27 @@ declare const extensionShape: {
             required: z.ZodOptional<z.ZodBoolean>;
             placeholder: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        children: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            refreshSeconds: z.ZodOptional<z.ZodNumber>;
+            cap: z.ZodOptional<z.ZodNumber>;
+            noun: z.ZodOptional<z.ZodString>;
+            create: z.ZodOptional<z.ZodObject<{
+                tool: z.ZodString;
+                noun: z.ZodOptional<z.ZodString>;
+                titleField: z.ZodOptional<z.ZodString>;
+                parentField: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            nested: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                noun: z.ZodOptional<z.ZodString>;
+                create: z.ZodOptional<z.ZodObject<{
+                    tool: z.ZodString;
+                    noun: z.ZodOptional<z.ZodString>;
+                    titleField: z.ZodOptional<z.ZodString>;
+                    parentField: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -87,6 +150,17 @@ declare const extensionShape: {
         collections: z.ZodOptional<z.ZodArray<z.ZodString>>;
         host: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    /** The secrets its handlers read (ADR-A24): names only, never values. */
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            install: "install";
+        }>>;
+    }, z.core.$strip>>>;
     /**
      * How records move when the schema changes between versions (A3-F07).
      * Checked against the previous version when a version is published, and
@@ -133,7 +207,7 @@ export interface DataProblem {
     field?: string;
     message: string;
 }
-export type DataProblemCode = FieldTypeInvalid['code'] | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_screen_unknown';
+export type DataProblemCode = FieldTypeInvalid['code'] | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_key_taken' | 'placement_screen_unknown' | 'placement_children_too_deep' | 'placement_create_tool_unknown' | 'placement_create_not_write' | 'secret_name_taken' | 'grant_secrets_missing';
 type Additions = z.infer<z.ZodObject<typeof extensionShape>>;
 /**
  * Everything wrong with an app's additions that a type cannot say.
@@ -148,10 +222,12 @@ export declare function dataProblems(additions: Additions, options?: {
 /** The additions alone, for code that has the rest of the manifest already. */
 export declare const manifestExtensionsSchema: z.ZodObject<{
     placements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             "project-tab": "project-tab";
             "project-sidebar": "project-sidebar";
             "workspace-sidebar": "workspace-sidebar";
+            home: "home";
         }>;
         screen: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
@@ -165,6 +241,27 @@ export declare const manifestExtensionsSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
             placeholder: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        children: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            refreshSeconds: z.ZodOptional<z.ZodNumber>;
+            cap: z.ZodOptional<z.ZodNumber>;
+            noun: z.ZodOptional<z.ZodString>;
+            create: z.ZodOptional<z.ZodObject<{
+                tool: z.ZodString;
+                noun: z.ZodOptional<z.ZodString>;
+                titleField: z.ZodOptional<z.ZodString>;
+                parentField: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            nested: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                noun: z.ZodOptional<z.ZodString>;
+                create: z.ZodOptional<z.ZodObject<{
+                    tool: z.ZodString;
+                    noun: z.ZodOptional<z.ZodString>;
+                    titleField: z.ZodOptional<z.ZodString>;
+                    parentField: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -190,6 +287,16 @@ export declare const manifestExtensionsSchema: z.ZodObject<{
         collections: z.ZodOptional<z.ZodArray<z.ZodString>>;
         host: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            install: "install";
+        }>>;
+    }, z.core.$strip>>>;
     migrations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         version: z.ZodString;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -226,10 +333,12 @@ export declare const manifestExtensionsSchema: z.ZodObject<{
  */
 export declare const storedExtensionsSchema: z.ZodObject<{
     placements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             "project-tab": "project-tab";
             "project-sidebar": "project-sidebar";
             "workspace-sidebar": "workspace-sidebar";
+            home: "home";
         }>;
         screen: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
@@ -243,6 +352,27 @@ export declare const storedExtensionsSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
             placeholder: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        children: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            refreshSeconds: z.ZodOptional<z.ZodNumber>;
+            cap: z.ZodOptional<z.ZodNumber>;
+            noun: z.ZodOptional<z.ZodString>;
+            create: z.ZodOptional<z.ZodObject<{
+                tool: z.ZodString;
+                noun: z.ZodOptional<z.ZodString>;
+                titleField: z.ZodOptional<z.ZodString>;
+                parentField: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            nested: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                noun: z.ZodOptional<z.ZodString>;
+                create: z.ZodOptional<z.ZodObject<{
+                    tool: z.ZodString;
+                    noun: z.ZodOptional<z.ZodString>;
+                    titleField: z.ZodOptional<z.ZodString>;
+                    parentField: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -268,6 +398,16 @@ export declare const storedExtensionsSchema: z.ZodObject<{
         collections: z.ZodOptional<z.ZodArray<z.ZodString>>;
         host: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            install: "install";
+        }>>;
+    }, z.core.$strip>>>;
     migrations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         version: z.ZodString;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -318,7 +458,14 @@ export declare const appManifestSchema: z.ZodObject<{
         terms: z.ZodOptional<z.ZodString>;
         support: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-    icon: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodObject<{
+        color: z.ZodString;
+        mono: z.ZodString;
+    }, z.core.$strip>>;
+    icon: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        color: z.ZodString;
+        mono: z.ZodString;
+    }, z.core.$strip>]>>;
     brandColor: z.ZodOptional<z.ZodString>;
     brandColorDark: z.ZodOptional<z.ZodString>;
     defaultPrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -332,10 +479,12 @@ export declare const appManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     placements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             "project-tab": "project-tab";
             "project-sidebar": "project-sidebar";
             "workspace-sidebar": "workspace-sidebar";
+            home: "home";
         }>;
         screen: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
@@ -349,6 +498,27 @@ export declare const appManifestSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
             placeholder: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        children: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            refreshSeconds: z.ZodOptional<z.ZodNumber>;
+            cap: z.ZodOptional<z.ZodNumber>;
+            noun: z.ZodOptional<z.ZodString>;
+            create: z.ZodOptional<z.ZodObject<{
+                tool: z.ZodString;
+                noun: z.ZodOptional<z.ZodString>;
+                titleField: z.ZodOptional<z.ZodString>;
+                parentField: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            nested: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                noun: z.ZodOptional<z.ZodString>;
+                create: z.ZodOptional<z.ZodObject<{
+                    tool: z.ZodString;
+                    noun: z.ZodOptional<z.ZodString>;
+                    titleField: z.ZodOptional<z.ZodString>;
+                    parentField: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -374,6 +544,16 @@ export declare const appManifestSchema: z.ZodObject<{
         collections: z.ZodOptional<z.ZodArray<z.ZodString>>;
         host: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            install: "install";
+        }>>;
+    }, z.core.$strip>>>;
     migrations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         version: z.ZodString;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/src/schema.js

@@ -24,12 +24,63 @@ const placementSettingSchema = z.object({
     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(),
+});
+/** 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(),
+    kind: z.enum(['project-tab', 'project-sidebar', 'workspace-sidebar', 'home']),
     screen: z.string().min(1).max(FIELD_LIMITS.nameChars),
     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"]`). */
@@ -80,6 +131,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(),
@@ -91,6 +164,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
@@ -241,8 +316,20 @@ 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',
@@ -250,6 +337,61 @@ export function dataProblems(additions, options = {}) {
             });
         }
     }
+    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;
 }
 /**
@@ -316,6 +458,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({
@@ -323,13 +492,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 },
         });
     }

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;
+}