@ekka-ai/shelves 0.2.2

package/dist/shelf.js

@@ -0,0 +1,71 @@
+/**
+ * A SHELF, AS A BUSINESS API WRITES IT (E1 spec, section 6 P1).
+ *
+ * `npx @ekka-ai/shelves add hr.salary` writes a class that extends `Shelf` with empty typed methods. The
+ * company fills the method bodies with its own code: that code IS the mapping from its data to the
+ * shelf, and EKKA keeps no mapping table (owner rule 3).
+ *
+ *   - A PREDEFINED shelf takes its keys, fields, verbs and page cap from EKKA's registry.
+ *     `predefined('hr.salary')` refuses an id the registry does not define.
+ *   - A PRIVATE shelf declares its shape in the file. `privateShelf(...)` refuses an id the registry
+ *     DOES define (owner rule 2): a company may not publish its own `hr.salary`.
+ *   - `roles` is read from ONE policy file, `src/ekka/policy.ts`: a provider role is written in
+ *     exactly one place (spec v3.2, section 12).
+ */
+import { assertShape, loadRegistry, SEGMENT } from './registry.js';
+export const predefined = (id) => {
+    const reg = loadRegistry();
+    const shelf = reg.shelves.get(id);
+    if (!shelf) {
+        throw new Error(`"${id}" is not a predefined EKKA shelf (registry ${reg.version}: ${[...reg.shelves.keys()].join(', ')}). ` +
+            'A shelf of your own is declared with privateShelf(id, shape).');
+    }
+    return { id, interfaceMajor: shelf.interfaceMajor, isPrivate: false, shape: shelf };
+};
+export const privateShelf = (id, shape) => {
+    const reg = loadRegistry();
+    // ⛔ OWNER RULE 2: a private shelf may never reuse a predefined id. A plan naming hr.salary must
+    // mean EKKA's hr.salary everywhere, or third-party plans mean nothing.
+    if (reg.shelves.has(id)) {
+        throw new Error(`"${id}" is a predefined EKKA shelf; a private shelf may not reuse its id. Use predefined('${id}').`);
+    }
+    const full = { keys: shape.keys, fields: shape.fields, verbs: shape.verbs, pageCap: shape.pageCap ?? 100 };
+    assertShape(id, full);
+    return { id, interfaceMajor: null, isPrivate: true, shape: full };
+};
+export class ShelfRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ShelfRefusal';
+    }
+}
+export const notImplemented = (id, verb) => new ShelfRefusal('not_implemented', `${id} ${verb} has no method body yet`);
+/**
+ * `By` is the unique key set `read` takes; `Filter` is the equality filter `list` takes (any subset
+ * of the declared keys, unique or not); `R` is one record, exactly the shelf's fields.
+ */
+export class Shelf {
+}
+/** What a verb needs before it may be served: a method, a role, and a fixture to probe it with. */
+export const verbProblems = (s) => {
+    const out = [];
+    const { id, shape } = s.descriptor;
+    for (const v of shape.verbs) {
+        if (typeof s[v] !== 'function')
+            out.push(`${id} serves "${v}" but the class has no ${v}() method`);
+        const role = s.roles[v];
+        if (!role)
+            out.push(`${id} "${v}" has no provider role in src/ekka/policy.ts`);
+        else if (!SEGMENT.test(role))
+            out.push(`${id} "${v}" role "${role}" must be one lowercase word (letters, digits, _)`);
+        if (!s.fixtures[v])
+            out.push(`${id} "${v}" has no synthetic fixture, so it cannot be probed`);
+    }
+    for (const v of ['read', 'list']) {
+        if (!shape.verbs.includes(v) && typeof s[v] === 'function')
+            out.push(`${id} has a ${v}() method but does not serve "${v}"`);
+    }
+    return out;
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ekka-ai/shelves",
+  "version": "0.2.2",
+  "description": "EKKA shelves for a Business API: scaffold a typed shelf class, check it, mount the shelf protocol v1 (E1, ekka-ai/.github#674)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ekka-shelves": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekka-ai/ekka-shelves.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.20.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle-contracts.mjs && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "prepublishOnly": "node scripts/publish-guard.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "fastify": "5.12.5",
+    "typebox": "1.3.34",
+    "ajv": "8.20.0",
+    "tsx": "4.23.15",
+    "@ekka-ai/contracts": "0.42.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0",
+    "typebox": "^1.3.0",
+    "tsx": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "tsx": {
+      "optional": true
+    }
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}