@zeyos/client 0.3.0 → 0.4.0

package/scripts/lib/spec-model.mjs

@@ -0,0 +1,325 @@
+// Shared OpenAPI / dbref parsing primitives.
+//
+// Extracted verbatim from scripts/generate-client.mjs so both the client codegen
+// and the OKF producer (scripts/generate-okf.mjs) read the specs the same way.
+// generate-client.mjs imports these unchanged; generate-okf.mjs additionally uses
+// buildEntityModel() for the richer per-entity detail OKF docs need.
+
+import { readFile } from 'node:fs/promises';
+
+export const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace']);
+
+export function unescapePointerToken(token) {
+  return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+export function pointerGet(doc, ref) {
+  if (!ref.startsWith('#/')) {
+    throw new Error(`External $ref is not supported: ${ref}`);
+  }
+
+  const parts = ref.slice(2).split('/').map(unescapePointerToken);
+  let current = doc;
+  for (const part of parts) {
+    if (current == null || !Object.prototype.hasOwnProperty.call(current, part)) {
+      throw new Error(`Unresolvable $ref: ${ref}`);
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+export function resolveRef(doc, value) {
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+  if (typeof value.$ref === 'string') {
+    return pointerGet(doc, value.$ref);
+  }
+  return value;
+}
+
+export function normalizeServer(server) {
+  const urlTemplate = server?.url || '';
+  const defaultVariables = {};
+
+  if (server?.variables && typeof server.variables === 'object') {
+    for (const [name, variable] of Object.entries(server.variables)) {
+      if (variable && typeof variable.default === 'string') {
+        defaultVariables[name] = variable.default;
+      }
+    }
+  }
+
+  const basePathTemplate = (() => {
+    const match = urlTemplate.match(/^https?:\/\/[^/]+(\/.*)$/i);
+    return match ? match[1] : '';
+  })();
+
+  return {
+    urlTemplate,
+    basePathTemplate,
+    defaultVariables
+  };
+}
+
+export function normalizeParameters(doc, pathItem, operation) {
+  const combined = [
+    ...(Array.isArray(pathItem?.parameters) ? pathItem.parameters : []),
+    ...(Array.isArray(operation?.parameters) ? operation.parameters : [])
+  ];
+
+  const indexed = new Map();
+  for (const rawParameter of combined) {
+    const parameter = resolveRef(doc, rawParameter);
+    if (!parameter || typeof parameter !== 'object') {
+      continue;
+    }
+
+    const key = `${parameter.in || 'unknown'}:${parameter.name || 'unknown'}`;
+    indexed.set(key, {
+      name: parameter.name,
+      in: parameter.in,
+      required: Boolean(parameter.required)
+    });
+  }
+
+  const normalized = Array.from(indexed.values()).filter((parameter) => parameter.name && parameter.in);
+
+  return {
+    all: normalized,
+    path: normalized.filter((parameter) => parameter.in === 'path').map((parameter) => parameter.name),
+    query: normalized.filter((parameter) => parameter.in === 'query').map((parameter) => parameter.name),
+    header: normalized.filter((parameter) => parameter.in === 'header').map((parameter) => parameter.name)
+  };
+}
+
+export function normalizeRequestBody(doc, operation) {
+  const requestBody = resolveRef(doc, operation?.requestBody);
+  if (!requestBody || typeof requestBody !== 'object') {
+    return {
+      required: false,
+      contentTypes: []
+    };
+  }
+
+  const content = requestBody.content && typeof requestBody.content === 'object' ? requestBody.content : {};
+  const contentTypes = Object.keys(content);
+
+  return {
+    required: Boolean(requestBody.required),
+    contentTypes
+  };
+}
+
+export function normalizeOperationSecurity(doc, operation) {
+  if (Array.isArray(operation?.security)) {
+    return operation.security;
+  }
+  if (Array.isArray(doc.security)) {
+    return doc.security;
+  }
+  return [];
+}
+
+export function buildOperationId({ operationId, method, route, existingIds }) {
+  if (operationId && !existingIds.has(operationId)) {
+    return operationId;
+  }
+
+  const routeToken = route
+    .replace(/[^a-zA-Z0-9{}]/g, '_')
+    .replace(/[{}]/g, '')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+
+  let candidate = operationId || `${method.toLowerCase()}_${routeToken || 'operation'}`;
+  let suffix = 1;
+
+  while (existingIds.has(candidate)) {
+    suffix += 1;
+    candidate = `${operationId || `${method.toLowerCase()}_${routeToken || 'operation'}`}_${suffix}`;
+  }
+
+  return candidate;
+}
+
+export function collectOperations(doc) {
+  const operations = [];
+  const existingIds = new Set();
+
+  for (const [route, pathItem] of Object.entries(doc.paths || {})) {
+    for (const [method, operation] of Object.entries(pathItem || {})) {
+      if (!HTTP_METHODS.has(method)) {
+        continue;
+      }
+
+      const normalizedMethod = method.toUpperCase();
+      const parameters = normalizeParameters(doc, pathItem, operation);
+      const requestBody = normalizeRequestBody(doc, operation);
+      const security = normalizeOperationSecurity(doc, operation);
+      const finalOperationId = buildOperationId({
+        operationId: operation.operationId,
+        method: normalizedMethod,
+        route,
+        existingIds
+      });
+
+      existingIds.add(finalOperationId);
+
+      operations.push({
+        operationId: finalOperationId,
+        summary: operation.summary || '',
+        deprecated: Boolean(operation.deprecated),
+        method: normalizedMethod,
+        path: route,
+        security,
+        requestBodyRequired: requestBody.required,
+        requestContentTypes: requestBody.contentTypes,
+        parameterNames: {
+          path: parameters.path,
+          query: parameters.query,
+          header: parameters.header
+        }
+      });
+    }
+  }
+
+  operations.sort((a, b) => {
+    if (a.path !== b.path) {
+      return a.path.localeCompare(b.path);
+    }
+    return a.method.localeCompare(b.method);
+  });
+
+  return operations;
+}
+
+export function buildServices(specEntries) {
+  const services = {};
+
+  for (const specEntry of specEntries) {
+    const { service, file, doc } = specEntry;
+    const firstServer = Array.isArray(doc.servers) ? doc.servers[0] : undefined;
+
+    services[service] = {
+      key: service,
+      source: file,
+      title: doc.info?.title || '',
+      version: doc.info?.version || '',
+      server: normalizeServer(firstServer),
+      globalSecurity: Array.isArray(doc.security) ? doc.security : [],
+      operations: collectOperations(doc)
+    };
+  }
+
+  return services;
+}
+
+// Enum values are documented inline in dbref descriptions as `N`=LABEL pairs,
+// e.g. "Status (`0`=NOTSTARTED, `1`=AWAITINGACCEPTANCE, ...)". Extract them so
+// the client can validate enum inputs and suggest valid values.
+export function parseEnum(description) {
+  if (typeof description !== 'string') return null;
+  const out = {};
+  let count = 0;
+  const re = /`(-?\d+)`\s*=\s*([A-Za-z0-9_]+)/g;
+  let match;
+  while ((match = re.exec(description)) !== null) {
+    out[match[1]] = match[2];
+    count += 1;
+  }
+  return count >= 2 ? out : null;
+}
+
+// Compact field/enum/foreign-key map derived from openapi/dbref.json. Much
+// smaller than the raw dbref (drops storage, collation, constraints, triggers,
+// stats, etc.) so it ships cheaply and powers runtime introspection.
+export function buildSchema(dbref) {
+  const schema = {};
+  if (!Array.isArray(dbref)) return schema;
+
+  for (const entity of dbref) {
+    if (!entity || typeof entity !== 'object' || !entity.name || !Array.isArray(entity.fields)) {
+      continue;
+    }
+
+    const fields = {};
+    for (const field of entity.fields) {
+      if (!field || typeof field !== 'object' || !field.name) continue;
+      const def = { type: field.type || 'unknown' };
+      if (field.indexed) def.indexed = true;
+      if (Array.isArray(field.fkeys) && field.fkeys.length > 0 && field.fkeys[0].table) {
+        def.fk = field.fkeys[0].table;
+      }
+      const enumValues = parseEnum(field.description);
+      if (enumValues) def.enum = enumValues;
+      fields[field.name] = def;
+    }
+
+    schema[entity.name] = { type: entity.type || 'table', fields };
+  }
+
+  return schema;
+}
+
+// Richer per-entity model for OKF docs. Unlike buildSchema (compact, for the
+// shipped client), this preserves nullability, defaults, FK target field, the
+// raw field description, and the entity's indexes — including the GIN/partial
+// definitions behind the `filters`-vs-`filter` foreign-key footgun.
+export function buildEntityModel(dbref) {
+  const model = {};
+  if (!Array.isArray(dbref)) return model;
+
+  for (const entity of dbref) {
+    if (!entity || typeof entity !== 'object' || !entity.name || !Array.isArray(entity.fields)) {
+      continue;
+    }
+
+    const fields = entity.fields
+      .filter((field) => field && typeof field === 'object' && field.name)
+      .map((field) => {
+        const fk = Array.isArray(field.fkeys) && field.fkeys.length > 0 && field.fkeys[0].table
+          ? { table: field.fkeys[0].table, field: field.fkeys[0].field || 'ID' }
+          : null;
+        return {
+          name: field.name,
+          type: field.type || 'unknown',
+          notnull: Boolean(field.notnull),
+          default: field.default ?? null,
+          indexed: Boolean(field.indexed),
+          fk,
+          enum: parseEnum(field.description),
+          description: typeof field.description === 'string' ? field.description : ''
+        };
+      });
+
+    const indexes = (Array.isArray(entity.indexes) ? entity.indexes : []).map((index) => ({
+      name: index.name,
+      method: index.method || 'btree',
+      unique: Boolean(index.unique),
+      primary: Boolean(index.primary),
+      partial: Boolean(index.partial),
+      keys: Array.isArray(index.keys) ? index.keys : [],
+      def: typeof index.def === 'string' ? index.def : ''
+    }));
+
+    model[entity.name] = { name: entity.name, type: entity.type || 'table', fields, indexes };
+  }
+
+  return model;
+}
+
+export async function loadSpec(absolutePath) {
+  const raw = await readFile(absolutePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function loadOptionalSpec(absolutePath) {
+  try {
+    return await loadSpec(absolutePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}

package/src/index.js

@@ -1,6 +1,9 @@
 import { createZeyosClient } from './runtime/client.js';
 import { ZeyosApiError, ZeyosValidationError } from './runtime/error.js';
 import { MemoryTokenStore, normalizeTokenSet, tokenResponseToTokenSet } from './runtime/token-store.js';
+import {
+  OKF_VERSION, buildOkf, loadOkfBundle, validateOkfBundle, validateOkfFiles, conceptIdForResource
+} from './runtime/okf.js';
 
 /**
  * @typedef {null|boolean|number|string|JsonValue[]|Record<string, JsonValue>} JsonValue
@@ -83,3 +86,4 @@ export function normalizeCountResult(result) {
 }
 
 export { createZeyosClient, ZeyosApiError, ZeyosValidationError, MemoryTokenStore, normalizeTokenSet, tokenResponseToTokenSet };
+export { OKF_VERSION, buildOkf, loadOkfBundle, validateOkfBundle, validateOkfFiles, conceptIdForResource };

package/src/runtime/okf.js

@@ -0,0 +1,237 @@
+// Open Knowledge Format (OKF v0.1) support for @zeyos/client.
+//
+// Two halves:
+//   • Pure (browser + Node): the OKF conformance constants, a tolerant concept
+//     parser, a bundle validator, and buildOkf() — which synthesizes a conformant
+//     OKF bundle from the client's own introspection surface (the generated
+//     SCHEMA + SERVICES). No filesystem access.
+//   • Node-only: loadOkfBundle() reads the shipped okf/ bundle (or any directory)
+//     from disk via a lazy import, so this module stays bundler/browser-safe.
+//
+// The richer build-time producer (scripts/generate-okf.mjs) emits the curated,
+// managed-block bundle under okf/. buildOkf() here is the lightweight runtime
+// projection of what the shipped client knows — handy for emitting OKF in
+// environments without the bundled files, or to diff against a live instance.
+
+import { SCHEMA } from '../generated/schema.js';
+import { SERVICES } from '../generated/operations.js';
+
+export const OKF_VERSION = '0.1';
+
+// Markers fencing producer-generated content inside a concept's body. Exported so
+// the build-time renderer (scripts/lib/okf.mjs) shares one definition.
+export const GENERATED_START = '<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->';
+export const GENERATED_END = '<!-- okf:generated:end -->';
+export const GENERATED_FRONTMATTER_KEYS = Object.freeze([
+  'type', 'title', 'description', 'resource', 'tags', 'timestamp',
+  'api_backed', 'list_operation', 'visibility_column'
+]);
+
+// Files that are not concept documents (spec §5/§6).
+const RESERVED_BASENAMES = new Set(['index.md', 'log.md']);
+
+const VERB_RE = /^(list|get|create|update|delete|exists)/;
+
+// ── Parsing / validation (pure) ────────────────────────────────────────────────
+
+/** Tolerant frontmatter + body split. Returns `{ frontmatter, body }` where
+ *  frontmatter is a flat string→string map (lists kept as their raw text). */
+export function parseConcept(content) {
+  const text = String(content || '');
+  const match = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!match) return { frontmatter: {}, body: text };
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_]+):\s*(.*)$/.exec(line);
+    if (kv) frontmatter[kv[1]] = kv[2].trim();
+  }
+  return { frontmatter, body: text.slice(match[0].length) };
+}
+
+function isReserved(relPath) {
+  const base = relPath.split('/').pop();
+  return RESERVED_BASENAMES.has(base);
+}
+
+/**
+ * Validate an OKF bundle for v0.1 conformance (spec §9): every non-reserved `.md`
+ * file must have parseable frontmatter with a non-empty `type`. Tolerant by
+ * design — unknown types/keys and broken links are NOT errors.
+ *
+ * @param {Record<string,string>} files - relativePath → file content.
+ * @returns {{ valid: boolean, errors: { path: string, message: string }[], conceptCount: number }}
+ */
+export function validateOkfFiles(files) {
+  const errors = [];
+  let conceptCount = 0;
+  for (const [relPath, content] of Object.entries(files || {})) {
+    if (!relPath.endsWith('.md') || isReserved(relPath)) continue;
+    conceptCount += 1;
+    const { frontmatter } = parseConcept(content);
+    if (!Object.keys(frontmatter).length) {
+      errors.push({ path: relPath, message: 'Missing YAML frontmatter.' });
+      continue;
+    }
+    if (!frontmatter.type) {
+      errors.push({ path: relPath, message: 'Frontmatter is missing the required `type` field.' });
+    }
+  }
+  return { valid: errors.length === 0, errors, conceptCount };
+}
+
+/** The OKF concept ID for a ZeyOS resource, e.g. `tickets` → `entities/tickets`. */
+export function conceptIdForResource(resource) {
+  return `entities/${resource}`;
+}
+
+// ── buildOkf: synthesize a bundle from the client's introspection surface ───────
+
+function groupOperations(services) {
+  const byResource = new Map();
+  for (const service of Object.values(services || {})) {
+    for (const op of service.operations || []) {
+      const resource = resourceFromPath(op.path);
+      if (!resource) continue;
+      if (!byResource.has(resource)) byResource.set(resource, {});
+      const bucket = byResource.get(resource);
+      const m = VERB_RE.exec(op.operationId);
+      const key = m ? m[1] : op.operationId;
+      if (!bucket[key]) bucket[key] = op.operationId;
+    }
+  }
+  return byResource;
+}
+
+function resourceFromPath(p) {
+  if (typeof p !== 'string') return null;
+  for (const segment of p.split('/')) {
+    if (segment && !segment.startsWith('{')) return segment;
+  }
+  return null;
+}
+
+function titleFromOps(ops, fallback) {
+  const op = ops.list || ops.get;
+  if (!op) return fallback.charAt(0).toUpperCase() + fallback.slice(1);
+  return op.replace(VERB_RE, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').trim() || fallback;
+}
+
+// Deterministic, dependency-free 32-bit hash for the bundle source snapshot.
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+function renderEntityDoc(name, entry, ops, hasDoc) {
+  const link = (target) => (hasDoc.has(target) ? `/entities/${target}.md` : null);
+  const fields = Object.entries(entry.fields || {});
+
+  const schemaRows = fields.map(([fname, def]) => {
+    const fkCell = def.fk ? (link(def.fk) ? `[${def.fk}](${link(def.fk)})` : def.fk) : '—';
+    const enumCell = def.enum ? Object.entries(def.enum).map(([k, v]) => `${k}=${v}`).join(', ') : '—';
+    return `| \`${fname}\` | ${def.type || 'unknown'} | ${def.indexed ? 'yes' : '—'} | ${fkCell} | ${enumCell} |`;
+  });
+  const schema = `# Schema\n\n| Column | Type | Indexed | FK | Enum |\n|---|---|---|---|---|\n${schemaRows.join('\n')}`;
+
+  const fks = fields.filter(([, d]) => d.fk);
+  const fkSection = fks.length
+    ? `\n\n# Foreign Keys\n\n${fks.map(([f, d]) => `- \`${f}\` → ${link(d.fk) ? `[${d.fk}](${link(d.fk)})` : d.fk}`).join('\n')}`
+    : '';
+
+  const order = ['list', 'get', 'create', 'update', 'delete', 'exists'];
+  const opLines = order.filter((k) => ops[k]).map((k) => `- ${k}: \`${ops[k]}\``);
+  const opSection = opLines.length ? `\n\n# Operations\n\n${opLines.join('\n')}` : '';
+
+  const title = titleFromOps(ops, name);
+  const fm = [
+    'type: ZeyOS Entity',
+    `title: ${title}`,
+    `resource: zeyos://api/${name}`,
+    'tags: [generated]',
+    'api_backed: true'
+  ];
+  if (ops.list) fm.push(`list_operation: ${ops.list}`);
+  fm.push(`visibility_column: ${Object.prototype.hasOwnProperty.call(entry.fields || {}, 'visibility')}`);
+
+  return `---\n${fm.join('\n')}\n---\n\n${schema}${fkSection}${opSection}\n`;
+}
+
+/**
+ * Synthesize a conformant OKF v0.1 bundle from a client schema + services. Pure:
+ * returns a `{ relativePath: content }` map; the caller decides whether to write
+ * it to disk. Defaults to the generated SCHEMA/SERVICES baked into the client.
+ *
+ * @param {{ schema?: object, services?: object }} [input]
+ * @returns {Record<string,string>}
+ */
+export function buildOkf({ schema = SCHEMA, services = SERVICES } = {}) {
+  const ops = groupOperations(services);
+  const resources = Object.keys(schema).filter((r) => ops.has(r)).sort();
+  const hasDoc = new Set(resources);
+  const files = {};
+
+  for (const name of resources) {
+    files[`entities/${name}.md`] = renderEntityDoc(name, schema[name], ops.get(name) || {}, hasDoc);
+  }
+
+  const indexItems = resources
+    .map((name) => `* [${titleFromOps(ops.get(name) || {}, name)}](${name}.md)`)
+    .join('\n');
+  files['entities/index.md'] = `# Entities\n\n${indexItems}\n`;
+
+  const signature = resources.map((r) => `${r}:${Object.keys(schema[r].fields || {}).join(',')}`).join('|');
+  files['index.md'] = `---\nokf_version: ${OKF_VERSION}\nsource_snapshot: ${fnv1a(signature)}\n---\n\n# ZeyOS Knowledge Bundle\n\n* [Entities](entities/) - ${resources.length} API-backed entity concepts.\n`;
+
+  return files;
+}
+
+// ── Node-only loaders (lazy fs so the module stays browser-safe) ────────────────
+
+/**
+ * Read an OKF bundle directory from disk. Node only.
+ * @param {string} dir - Path to a bundle root (e.g. the shipped okf/).
+ * @returns {Promise<{ version: string|null, files: Record<string,string>, concepts: Record<string,{frontmatter:object,body:string}> }>}
+ */
+export async function loadOkfBundle(dir) {
+  const { readFile, readdir } = await import('node:fs/promises');
+  const path = await import('node:path');
+
+  const files = {};
+  async function walk(current, prefix) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = path.join(current, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await walk(abs, rel);
+      else if (entry.name.endsWith('.md')) files[rel] = await readFile(abs, 'utf8');
+    }
+  }
+  await walk(dir, '');
+
+  const concepts = {};
+  for (const [rel, content] of Object.entries(files)) {
+    if (isReserved(rel)) continue;
+    concepts[rel.replace(/\.md$/, '')] = parseConcept(content);
+  }
+
+  let version = null;
+  if (files['index.md']) version = parseConcept(files['index.md']).frontmatter.okf_version || null;
+
+  return { version, files, concepts };
+}
+
+/**
+ * Validate an OKF bundle. Accepts a directory path (Node) or an in-memory
+ * `{ path: content }` map (universal). Returns the validateOkfFiles() result.
+ */
+export async function validateOkfBundle(dirOrFiles) {
+  if (typeof dirOrFiles === 'string') {
+    const { files } = await loadOkfBundle(dirOrFiles);
+    return validateOkfFiles(files);
+  }
+  return validateOkfFiles(dirOrFiles);
+}