@north-light/api 0.3.491 → 0.3.492

package/dist/api/command-manifest/index.d.ts

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './manifest.js';
 export * from './result.js';
+export * from './object-kinds.js';

package/dist/api/command-manifest/index.js

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './manifest.js';
 export * from './result.js';
+export * from './object-kinds.js';

package/dist/api/command-manifest/object-kinds.d.ts

@@ -0,0 +1,20 @@
+export declare const KIND: RegExp;
+export declare const LOCAL: RegExp;
+/** A kind's first segment may not be one of the built-in object types. */
+export declare const RESERVED_KIND_ROOTS: readonly string[];
+export declare const MAX_KIND_EVENTS = 64;
+export declare const MIN_EVENT_LEVEL = 1;
+export declare const MAX_EVENT_LEVEL = 10;
+/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
+export declare function eventCatalogReasons(events: unknown, where: string): string[];
+/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
+export declare function objectBlocksShapeReasons(record: Record<string, unknown>): string[];
+/**
+ * Reasons a kind's `read.command` does not name a non-streaming leaf of plugin `name`. `leafPaths` holds the space-joined path of
+ * every leaf below the plugin's root command; `streamingLeafPaths` holds those declared streaming.
+ */
+export declare function objectKindReadReasons(kind: string, decl: {
+    read?: {
+        command: readonly string[];
+    };
+}, name: string, leafPaths: ReadonlySet<string>, streamingLeafPaths: ReadonlySet<string>): string[];

package/dist/api/command-manifest/object-kinds.js

@@ -0,0 +1,98 @@
+// The shape rules for a plugin's `object_kinds` block, shared by crouter's install paths and the plugin kit
+// (`definePlugin({objectKinds})`) so both refuse exactly the same declarations. Zero dependencies.
+export const KIND = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/;
+export const LOCAL = /^[a-z][a-z0-9-]*$/;
+/** A kind's first segment may not be one of the built-in object types. */
+export const RESERVED_KIND_ROOTS = ['report', 'notice', 'node', 'job', 'document', 'person', 'app', 'repo', 'profile', 'action'];
+export const MAX_KIND_EVENTS = 64;
+export const MIN_EVENT_LEVEL = 1;
+export const MAX_EVENT_LEVEL = 10;
+const KIND_KEYS = new Set(['description', 'events', 'read']);
+const EVENT_KEYS = new Set(['level', 'supersedes']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
+export function eventCatalogReasons(events, where) {
+    if (!isRecord(events))
+        return [`${where} events must be an object`];
+    const reasons = [];
+    const entries = Object.entries(events);
+    if (entries.length > MAX_KIND_EVENTS)
+        reasons.push(`${where} declares more than ${MAX_KIND_EVENTS} events`);
+    for (const [local, spec] of entries) {
+        const at = `${where} event ${JSON.stringify(local)}`;
+        if (!LOCAL.test(local))
+            reasons.push(`${at} is not a valid event name`);
+        if (!isRecord(spec)) {
+            reasons.push(`${at} must be an object { level, supersedes? }`);
+            continue;
+        }
+        for (const key of Object.keys(spec))
+            if (!EVENT_KEYS.has(key))
+                reasons.push(`${at} has unknown key ${JSON.stringify(key)}`);
+        const level = spec['level'];
+        if (typeof level !== 'number' || !Number.isInteger(level) || level < MIN_EVENT_LEVEL || level > MAX_EVENT_LEVEL)
+            reasons.push(`${at} level must be an integer ${MIN_EVENT_LEVEL}-${MAX_EVENT_LEVEL}`);
+        if (spec['supersedes'] !== undefined && typeof spec['supersedes'] !== 'boolean')
+            reasons.push(`${at} supersedes must be a boolean`);
+    }
+    return reasons;
+}
+/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
+export function objectBlocksShapeReasons(record) {
+    const reasons = [];
+    const kinds = record['object_kinds'];
+    if (kinds !== undefined) {
+        if (!isRecord(kinds))
+            reasons.push('object_kinds must be an object keyed by kind name');
+        else {
+            for (const [kind, decl] of Object.entries(kinds)) {
+                const where = `object_kinds ${JSON.stringify(kind)}`;
+                if (!KIND.test(kind))
+                    reasons.push(`${where} is not a valid kind name (<plugin>.<name>, lowercase)`);
+                else if (RESERVED_KIND_ROOTS.includes(kind.split('.')[0]))
+                    reasons.push(`${where} uses a reserved first segment`);
+                if (!isRecord(decl)) {
+                    reasons.push(`${where} must be an object { description, events, read? }`);
+                    continue;
+                }
+                for (const key of Object.keys(decl))
+                    if (!KIND_KEYS.has(key))
+                        reasons.push(`${where} has unknown key ${JSON.stringify(key)}`);
+                if (typeof decl['description'] !== 'string' || decl['description'].trim() === '')
+                    reasons.push(`${where} description must be non-empty text`);
+                reasons.push(...eventCatalogReasons(decl['events'], where));
+                const read = decl['read'];
+                if (read !== undefined) {
+                    const command = isRecord(read) ? read['command'] : undefined;
+                    if (!isRecord(read) || Object.keys(read).some((key) => key !== 'command'))
+                        reasons.push(`${where} read must be { command: [leaf path] }`);
+                    else if (!Array.isArray(command) || command.length === 0 || command.some((part) => typeof part !== 'string' || part === ''))
+                        reasons.push(`${where} read.command must be a non-empty array of command names`);
+                }
+            }
+        }
+    }
+    const scopes = record['scopes'];
+    if (scopes !== undefined) {
+        if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== 'string'))
+            reasons.push('scopes must be an array of scope strings');
+    }
+    return reasons;
+}
+/**
+ * Reasons a kind's `read.command` does not name a non-streaming leaf of plugin `name`. `leafPaths` holds the space-joined path of
+ * every leaf below the plugin's root command; `streamingLeafPaths` holds those declared streaming.
+ */
+export function objectKindReadReasons(kind, decl, name, leafPaths, streamingLeafPaths) {
+    const command = decl.read?.command;
+    if (command === undefined)
+        return [];
+    const path = command.join(' ');
+    if (!leafPaths.has(path))
+        return [`object_kinds ${JSON.stringify(kind)} read.command "${path}" is not a leaf of plugin "${name}"`];
+    if (streamingLeafPaths.has(path))
+        return [`object_kinds ${JSON.stringify(kind)} read.command "${path}" streams; a read is one {markdown} answer`];
+    return [];
+}

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.12";
+export declare const CONTRACT_LEVEL = "1.13";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.12';
+export const CONTRACT_LEVEL = '1.13';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/core/plugin-objects-manifest.d.ts

@@ -1,21 +1,7 @@
 import type { DeclLeaf, DeclNode } from '../api/command-manifest/schema.js';
+import { KIND, LOCAL, RESERVED_KIND_ROOTS, MAX_KIND_EVENTS, MIN_EVENT_LEVEL, MAX_EVENT_LEVEL, eventCatalogReasons, objectBlocksShapeReasons, objectKindReadReasons } from '../api/command-manifest/object-kinds.js';
 import type { PluginManifest } from '../types.js';
-/**
- * The `object_kinds` and `scopes` blocks of a plugin manifest (`plugin.json`, `bundle.json`) and the one
- * validator every install, update, enable, provider-bundle and reconcile path shares. Canvas-free by
- * design: the CLI and the bundle parser import it, so it must not reach `node:sqlite` or the canvas.
- */
-export declare const KIND: RegExp;
-export declare const LOCAL: RegExp;
-/** A kind's first segment may not be one of the built-in object types. */
-export declare const RESERVED_KIND_ROOTS: readonly string[];
-export declare const MAX_KIND_EVENTS = 64;
-export declare const MIN_EVENT_LEVEL = 1;
-export declare const MAX_EVENT_LEVEL = 10;
-/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
-export declare function eventCatalogReasons(events: unknown, where: string): string[];
-/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
-export declare function objectBlocksShapeReasons(record: Record<string, unknown>): string[];
+export { KIND, LOCAL, RESERVED_KIND_ROOTS, MAX_KIND_EVENTS, MIN_EVENT_LEVEL, MAX_EVENT_LEVEL, eventCatalogReasons, objectBlocksShapeReasons, objectKindReadReasons };
 /**
  * The full check. `leafPaths` holds the space-joined path of every leaf below the plugin's root command
  * (`page read` for plugin `search`'s leaf `search page read`); `streamingLeafPaths` holds those declared `rest.streaming: true`.

package/dist/core/plugin-objects-manifest.js

@@ -1,91 +1,12 @@
 import { parseScope } from '@north-light/identity';
+import { KIND, LOCAL, RESERVED_KIND_ROOTS, MAX_KIND_EVENTS, MIN_EVENT_LEVEL, MAX_EVENT_LEVEL, eventCatalogReasons, objectBlocksShapeReasons, objectKindReadReasons, } from '../api/command-manifest/object-kinds.js';
+export { KIND, LOCAL, RESERVED_KIND_ROOTS, MAX_KIND_EVENTS, MIN_EVENT_LEVEL, MAX_EVENT_LEVEL, eventCatalogReasons, objectBlocksShapeReasons, objectKindReadReasons };
 /**
  * The `object_kinds` and `scopes` blocks of a plugin manifest (`plugin.json`, `bundle.json`) and the one
  * validator every install, update, enable, provider-bundle and reconcile path shares. Canvas-free by
  * design: the CLI and the bundle parser import it, so it must not reach `node:sqlite` or the canvas.
  */
-export const KIND = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/;
-export const LOCAL = /^[a-z][a-z0-9-]*$/;
-/** A kind's first segment may not be one of the built-in object types. */
-export const RESERVED_KIND_ROOTS = ['report', 'notice', 'node', 'job', 'document', 'person', 'app', 'repo', 'profile', 'action'];
-export const MAX_KIND_EVENTS = 64;
-export const MIN_EVENT_LEVEL = 1;
-export const MAX_EVENT_LEVEL = 10;
-const KIND_KEYS = new Set(['description', 'events', 'read']);
-const EVENT_KEYS = new Set(['level', 'supersedes']);
 const SCOPE_VERBS = /^crtr:objects:(?:read|watch|link|write):/;
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/** Reasons a catalog (`events` map) is invalid; shared with `registerCustomObject`. */
-export function eventCatalogReasons(events, where) {
-    if (!isRecord(events))
-        return [`${where} events must be an object`];
-    const reasons = [];
-    const entries = Object.entries(events);
-    if (entries.length > MAX_KIND_EVENTS)
-        reasons.push(`${where} declares more than ${MAX_KIND_EVENTS} events`);
-    for (const [local, spec] of entries) {
-        const at = `${where} event ${JSON.stringify(local)}`;
-        if (!LOCAL.test(local))
-            reasons.push(`${at} is not a valid event name`);
-        if (!isRecord(spec)) {
-            reasons.push(`${at} must be an object { level, supersedes? }`);
-            continue;
-        }
-        for (const key of Object.keys(spec))
-            if (!EVENT_KEYS.has(key))
-                reasons.push(`${at} has unknown key ${JSON.stringify(key)}`);
-        const level = spec['level'];
-        if (typeof level !== 'number' || !Number.isInteger(level) || level < MIN_EVENT_LEVEL || level > MAX_EVENT_LEVEL)
-            reasons.push(`${at} level must be an integer ${MIN_EVENT_LEVEL}-${MAX_EVENT_LEVEL}`);
-        if (spec['supersedes'] !== undefined && typeof spec['supersedes'] !== 'boolean')
-            reasons.push(`${at} supersedes must be a boolean`);
-    }
-    return reasons;
-}
-/** The JSON shape of both blocks of a raw manifest record, independent of the plugin's name and commands. */
-export function objectBlocksShapeReasons(record) {
-    const reasons = [];
-    const kinds = record['object_kinds'];
-    if (kinds !== undefined) {
-        if (!isRecord(kinds))
-            reasons.push('object_kinds must be an object keyed by kind name');
-        else {
-            for (const [kind, decl] of Object.entries(kinds)) {
-                const where = `object_kinds ${JSON.stringify(kind)}`;
-                if (!KIND.test(kind))
-                    reasons.push(`${where} is not a valid kind name (<plugin>.<name>, lowercase)`);
-                else if (RESERVED_KIND_ROOTS.includes(kind.split('.')[0]))
-                    reasons.push(`${where} uses a reserved first segment`);
-                if (!isRecord(decl)) {
-                    reasons.push(`${where} must be an object { description, events, read? }`);
-                    continue;
-                }
-                for (const key of Object.keys(decl))
-                    if (!KIND_KEYS.has(key))
-                        reasons.push(`${where} has unknown key ${JSON.stringify(key)}`);
-                if (typeof decl['description'] !== 'string' || decl['description'].trim() === '')
-                    reasons.push(`${where} description must be non-empty text`);
-                reasons.push(...eventCatalogReasons(decl['events'], where));
-                const read = decl['read'];
-                if (read !== undefined) {
-                    const command = isRecord(read) ? read['command'] : undefined;
-                    if (!isRecord(read) || Object.keys(read).some((key) => key !== 'command'))
-                        reasons.push(`${where} read must be { command: [leaf path] }`);
-                    else if (!Array.isArray(command) || command.length === 0 || command.some((part) => typeof part !== 'string' || part === ''))
-                        reasons.push(`${where} read.command must be a non-empty array of command names`);
-                }
-            }
-        }
-    }
-    const scopes = record['scopes'];
-    if (scopes !== undefined) {
-        if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== 'string'))
-            reasons.push('scopes must be an array of scope strings');
-    }
-    return reasons;
-}
 /**
  * The full check. `leafPaths` holds the space-joined path of every leaf below the plugin's root command
  * (`page read` for plugin `search`'s leaf `search page read`); `streamingLeafPaths` holds those declared `rest.streaming: true`.
@@ -98,11 +19,7 @@ export function objectBlocksReasons(manifest, context) {
     for (const [kind, decl] of Object.entries(manifest.object_kinds ?? {})) {
         if (kind.split('.')[0] !== name)
             reasons.push(`object_kinds ${JSON.stringify(kind)} must start with the plugin name "${name}."`);
-        const command = decl.read?.command;
-        if (command !== undefined && !leafPaths.has(command.join(' ')))
-            reasons.push(`object_kinds ${JSON.stringify(kind)} read.command "${command.join(' ')}" is not a leaf of plugin "${name}"`);
-        else if (command !== undefined && streamingLeafPaths.has(command.join(' ')))
-            reasons.push(`object_kinds ${JSON.stringify(kind)} read.command "${command.join(' ')}" streams; a read is one {markdown} answer`);
+        reasons.push(...objectKindReadReasons(kind, decl, name, leafPaths, streamingLeafPaths));
     }
     const scopes = manifest.scopes ?? [];
     if (manifest.scopes !== undefined && manifest.provider !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.491",
+  "version": "0.3.492",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",