@gregiteen/ssss-cli 0.7.0 → 0.8.0

package/src/frontmatter.mjs

@@ -3,9 +3,10 @@
  *
  * SSSS files are Markdown with a leading `---`-fenced YAML frontmatter block
  * (spec §4.1). The canonical engine avoids a YAML dependency: it parses the
- * subset SSSS actually uses — top-level scalars, inline `[a, b]` arrays, block
- * `- item` arrays, and block scalars — which is sufficient to resolve a file's
- * `type` and validate field presence against the registry (§5, §9).
+ * subset SSSS actually uses — scalars, inline `[a, b]` arrays, block `- item`
+ * arrays, nested maps, and arrays of shallow maps — which is sufficient to
+ * resolve a file's `type`, validate registry fields (§5, §9), and round-trip
+ * operation patches without dropping nested frontmatter.
  */
 
 /** Split a document into its raw frontmatter block and body. */
@@ -42,43 +43,107 @@ function coerce(raw) {
   return v;
 }
 
-/**
- * Parse a frontmatter block (the inner YAML, no fences) into an object.
- * Returns top-level keys only; nested maps are returned as `{}` placeholders
- * (presence is what the registry validator needs).
- */
-export function parseFrontmatter(fm) {
+function countIndent(line) {
+  const m = line.match(/^ */);
+  return m ? m[0].length : 0;
+}
+
+function splitKeyValue(text) {
+  const m = text.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+  return m ? { key: m[1], rest: m[2] } : null;
+}
+
+function nextSignificant(lines, start) {
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].trim() && !lines[i].trim().startsWith('#')) return i;
+  }
+  return -1;
+}
+
+function parseMap(lines, start, indent) {
   const data = {};
-  if (!fm) return data;
-  const lines = fm.split('\n');
-  for (let i = 0; i < lines.length; i++) {
+  let i = start;
+  while (i < lines.length) {
     const line = lines[i];
-    if (!line.trim() || line.trim().startsWith('#')) continue;
-    if (/^\s/.test(line)) continue; // sub-entry of a block handled below
-    const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
-    if (!m) continue;
-    const key = m[1];
-    const rest = m[2];
-    if (rest === '') {
-      // Could open a block list or a nested map. Peek ahead.
-      const items = [];
-      let isList = false;
-      let j = i + 1;
-      for (; j < lines.length; j++) {
-        const sub = lines[j];
-        if (!sub.trim()) continue;
-        if (!/^\s/.test(sub)) break; // dedent → block ended
-        const li = sub.match(/^\s*-\s*(.*)$/);
-        if (li) { isList = true; items.push(coerce(li[1])); }
-        else break; // nested map; we only need presence
+    if (!line.trim() || line.trim().startsWith('#')) { i++; continue; }
+    const currentIndent = countIndent(line);
+    if (currentIndent < indent) break;
+    if (currentIndent > indent) { i++; continue; }
+    const kv = splitKeyValue(line.slice(indent));
+    if (!kv) { i++; continue; }
+    if (kv.rest !== '') {
+      data[kv.key] = coerce(kv.rest);
+      i++;
+      continue;
+    }
+
+    const next = nextSignificant(lines, i + 1);
+    if (next < 0 || countIndent(lines[next]) <= indent) {
+      data[kv.key] = {};
+      i++;
+      continue;
+    }
+    const childIndent = countIndent(lines[next]);
+    if (lines[next].slice(childIndent).startsWith('- ')) {
+      const parsed = parseList(lines, next, childIndent);
+      data[kv.key] = parsed.value;
+      i = parsed.next;
+    } else {
+      const parsed = parseMap(lines, next, childIndent);
+      data[kv.key] = parsed.value;
+      i = parsed.next;
+    }
+  }
+  return { value: data, next: i };
+}
+
+function parseList(lines, start, indent) {
+  const items = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith('#')) { i++; continue; }
+    const currentIndent = countIndent(line);
+    if (currentIndent < indent) break;
+    if (currentIndent > indent) { i++; continue; }
+    const item = line.slice(indent).match(/^-\s*(.*)$/);
+    if (!item) break;
+    const raw = item[1];
+    const kv = splitKeyValue(raw);
+    if (kv) {
+      const obj = { [kv.key]: kv.rest === '' ? {} : coerce(kv.rest) };
+      i++;
+      const next = nextSignificant(lines, i);
+      if (next >= 0 && countIndent(lines[next]) > indent) {
+        const parsed = parseMap(lines, next, countIndent(lines[next]));
+        Object.assign(obj, parsed.value);
+        i = parsed.next;
+      }
+      items.push(obj);
+    } else if (raw === '') {
+      const next = nextSignificant(lines, i + 1);
+      if (next >= 0 && countIndent(lines[next]) > indent) {
+        const parsed = parseMap(lines, next, countIndent(lines[next]));
+        items.push(parsed.value);
+        i = parsed.next;
+      } else {
+        items.push('');
+        i++;
       }
-      data[key] = isList ? items : {};
-      i = isList ? j - 1 : i;
     } else {
-      data[key] = coerce(rest);
+      items.push(coerce(raw));
+      i++;
     }
   }
-  return data;
+  return { value: items, next: i };
+}
+
+/**
+ * Parse a frontmatter block (the inner YAML, no fences) into an object.
+ */
+export function parseFrontmatter(fm) {
+  if (!fm) return {};
+  return parseMap(fm.split('\n'), 0, 0).value;
 }
 
 /** Parse a full document (with fences) into { data, body }. */
@@ -96,13 +161,51 @@ function serializeValue(v) {
   return s;
 }
 
+function serializeEntry(lines, key, value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    if (!value.length) {
+      lines.push(`${pad}${key}: []`);
+      return;
+    }
+    lines.push(`${pad}${key}:`);
+    for (const item of value) {
+      if (item && typeof item === 'object' && !Array.isArray(item)) {
+        const entries = Object.entries(item);
+        if (!entries.length) {
+          lines.push(`${pad}  - {}`);
+          continue;
+        }
+        const [first, ...rest] = entries;
+        if (first[1] && typeof first[1] === 'object' && !Array.isArray(first[1])) {
+          lines.push(`${pad}  - ${first[0]}:`);
+          serializeObject(lines, first[1], indent + 6);
+        } else {
+          lines.push(`${pad}  - ${first[0]}: ${serializeValue(first[1])}`);
+        }
+        for (const [childKey, childValue] of rest) serializeEntry(lines, childKey, childValue, indent + 4);
+      } else {
+        lines.push(`${pad}  - ${serializeValue(item)}`);
+      }
+    }
+    return;
+  }
+  if (value && typeof value === 'object') {
+    lines.push(`${pad}${key}:`);
+    serializeObject(lines, value, indent + 2);
+    return;
+  }
+  lines.push(`${pad}${key}: ${serializeValue(value)}`);
+}
+
+function serializeObject(lines, obj, indent) {
+  for (const [k, v] of Object.entries(obj)) serializeEntry(lines, k, v, indent);
+}
+
 /** Serialize a frontmatter object + body back into an SSSS document. */
 export function serializeDocument(data, body) {
   const lines = ['---'];
-  for (const [k, v] of Object.entries(data)) {
-    if (v && typeof v === 'object' && !Array.isArray(v)) continue; // skip nested maps we can't round-trip
-    lines.push(`${k}: ${serializeValue(v)}`);
-  }
+  serializeObject(lines, data, 0);
   lines.push('---');
   const b = body == null ? '' : (body.startsWith('\n') ? body : `\n${body}`);
   return lines.join('\n') + b;

package/src/registry.mjs

@@ -10,41 +10,167 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_REGISTRY_DIR = path.resolve(__dirname, '..', 'registry');
 
 const APPEND_TYPES = new Set(['conversation', 'run']);
+const SAFE_REGISTRY_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const SAFE_TYPE_NAME = /^[a-z][a-z0-9_-]{0,127}$/;
+const SAFE_FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertRecord(value, label) {
+  if (value === undefined) return;
+  if (!isRecord(value)) throw new Error(`${label} must be an object.`);
+}
+
+function assertStringArray(value, label) {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item)) {
+    throw new Error(`${label} must be an array of non-empty strings.`);
+  }
+  if (new Set(value).size !== value.length) throw new Error(`${label} must not contain duplicates.`);
+}
+
+function validatePrimitiveDefinition(name, def, source, portabilityClasses) {
+  if (!SAFE_TYPE_NAME.test(name)) throw new Error(`${source}: unsafe primitive name '${name}'.`);
+  if (!def || typeof def !== 'object' || Array.isArray(def)) {
+    throw new Error(`${source}: primitive '${name}' must be an object.`);
+  }
+  if (typeof def.append_only !== 'boolean') {
+    throw new Error(`${source}: primitive '${name}' must declare append_only as a boolean.`);
+  }
+  if (!portabilityClasses.includes(def.portability)) {
+    throw new Error(`${source}: primitive '${name}' has invalid portability '${def.portability}'.`);
+  }
+  assertStringArray(def.required_fields, `${source}: primitive '${name}' required_fields`);
+  assertStringArray(def.optional_fields, `${source}: primitive '${name}' optional_fields`);
+  assertStringArray(def.immutable_fields, `${source}: primitive '${name}' immutable_fields`);
+
+  assertRecord(def.required_when, `${source}: primitive '${name}' required_when`);
+  for (const [condition, fields] of Object.entries(def.required_when || {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_-]*==.+$/.test(condition)) {
+      throw new Error(`${source}: primitive '${name}' has invalid required_when condition '${condition}'.`);
+    }
+    assertStringArray(fields, `${source}: primitive '${name}' required_when '${condition}'`);
+  }
+  assertRecord(def.patterns, `${source}: primitive '${name}' patterns`);
+  for (const [field, pattern] of Object.entries(def.patterns || {})) {
+    if (!SAFE_FIELD_NAME.test(field)) {
+      throw new Error(`${source}: primitive '${name}' has unsafe pattern field '${field}'.`);
+    }
+    if (typeof pattern !== 'string') {
+      throw new Error(`${source}: primitive '${name}' pattern for '${field}' must be a string.`);
+    }
+    try { new RegExp(pattern, 'u'); }
+    catch (error) {
+      throw new Error(`${source}: primitive '${name}' has invalid pattern for '${field}': ${error.message}`);
+    }
+  }
+  assertRecord(def.enums, `${source}: primitive '${name}' enums`);
+  for (const [field, values] of Object.entries(def.enums || {})) {
+    if (!SAFE_FIELD_NAME.test(field)) {
+      throw new Error(`${source}: primitive '${name}' has unsafe enum field '${field}'.`);
+    }
+    assertStringArray(values, `${source}: primitive '${name}' enum '${field}'`);
+  }
+  assertRecord(def.references, `${source}: primitive '${name}' references`);
+  for (const [field, constraint] of Object.entries(def.references || {})) {
+    if (!SAFE_FIELD_NAME.test(field)) {
+      throw new Error(`${source}: primitive '${name}' has unsafe reference field '${field}'.`);
+    }
+    if (!constraint || typeof constraint !== 'object' || Array.isArray(constraint)) {
+      throw new Error(`${source}: primitive '${name}' reference '${field}' must be an object.`);
+    }
+    assertStringArray(constraint.allowed_types, `${source}: primitive '${name}' reference '${field}' allowed_types`);
+    assertStringArray(constraint.disallowed_types, `${source}: primitive '${name}' reference '${field}' disallowed_types`);
+    assertStringArray(constraint.allowed_portability, `${source}: primitive '${name}' reference '${field}' allowed_portability`);
+    if (constraint.allowed_portability?.some((value) => !portabilityClasses.includes(value))) {
+      throw new Error(`${source}: primitive '${name}' reference '${field}' has an invalid allowed_portability value.`);
+    }
+    if (constraint.must_exist !== undefined && typeof constraint.must_exist !== 'boolean') {
+      throw new Error(`${source}: primitive '${name}' reference '${field}' must_exist must be a boolean.`);
+    }
+    const overlap = (constraint.allowed_types || []).filter((value) =>
+      constraint.disallowed_types?.includes(value));
+    if (overlap.length) {
+      throw new Error(`${source}: primitive '${name}' reference '${field}' both allows and forbids: ${overlap.join(', ')}.`);
+    }
+    if (constraint.hash_field !== undefined &&
+        (typeof constraint.hash_field !== 'string' || !SAFE_FIELD_NAME.test(constraint.hash_field))) {
+      throw new Error(`${source}: primitive '${name}' reference '${field}' hash_field must be a non-empty string.`);
+    }
+  }
+}
 
 /**
  * Load the core registry and merge extension registries.
  * @param {string} [registryDir] - directory containing core.json + extensions/
- * @returns {{ types: Map<string, object>, contractTypes: Set<string>, portabilityClasses: string[], core: object }}
+ * @returns {{ types: Map<string, object>, contractTypes: Set<string>, portabilityClasses: string[], core: object, extensions: Set<string> }}
  */
 export function loadRegistries(registryDir = DEFAULT_REGISTRY_DIR) {
   const corePath = path.join(registryDir, 'core.json');
   const core = JSON.parse(fs.readFileSync(corePath, 'utf8'));
+  const portabilityClasses = Object.keys(core.portability?.classes || {});
+  if (!portabilityClasses.length) throw new Error('core.json: portability.classes must not be empty.');
+  const extensions = new Set();
 
   const types = new Map();
   for (const [name, def] of Object.entries(core.document_primitives || {})) {
+    validatePrimitiveDefinition(name, def, 'core.json', portabilityClasses);
     types.set(name, { ...def, type: name, registry: 'core' });
   }
 
   const extDir = path.join(registryDir, 'extensions');
   if (fs.existsSync(extDir)) {
-    for (const file of fs.readdirSync(extDir).filter((f) => f.endsWith('.json'))) {
-      const ext = JSON.parse(fs.readFileSync(path.join(extDir, file), 'utf8'));
+    for (const file of fs.readdirSync(extDir).filter((f) => f.endsWith('.json')).sort()) {
+      const extPath = path.join(extDir, file);
+      if (fs.lstatSync(extPath).isSymbolicLink()) {
+        throw new Error(`extensions/${file}: symlinked registries are not allowed.`);
+      }
+      const ext = JSON.parse(fs.readFileSync(extPath, 'utf8'));
+      if (!SAFE_REGISTRY_NAME.test(ext.registry || '')) {
+        throw new Error(`extensions/${file}: registry must be a safe identifier.`);
+      }
+      if (ext.registry === 'core' || extensions.has(ext.registry)) {
+        throw new Error(`extensions/${file}: duplicate or reserved registry name '${ext.registry}'.`);
+      }
+      if (ext.extends !== undefined && ext.extends !== 'core') {
+        throw new Error(`extensions/${file}: extends must be 'core'.`);
+      }
+      extensions.add(ext.registry);
       for (const [name, def] of Object.entries(ext.document_primitives || {})) {
-        if (types.has(name) && types.get(name).registry === 'core') continue; // core wins; extensions MUST NOT redefine
-        types.set(name, { ...def, type: name, registry: ext.registry || file });
+        validatePrimitiveDefinition(name, def, `extensions/${file}`, portabilityClasses);
+        if (types.has(name)) {
+          throw new Error(
+            `extensions/${file}: primitive '${name}' collides with registry '${types.get(name).registry}'.`
+          );
+        }
+        types.set(name, { ...def, type: name, registry: ext.registry });
+      }
+    }
+  }
+
+  for (const def of types.values()) {
+    for (const [field, constraint] of Object.entries(def.references || {})) {
+      for (const target of [...(constraint.allowed_types || []), ...(constraint.disallowed_types || [])]) {
+        if (!SAFE_TYPE_NAME.test(target) || !types.has(target)) {
+          throw new Error(
+            `registry '${def.registry}' primitive '${def.type}' reference '${field}' names unknown type '${target}'.`
+          );
+        }
       }
     }
   }
 
   const contractTypes = new Set(Object.keys(core.contract_primitives || {}));
-  const portabilityClasses = Object.keys(core.portability?.classes || {});
-  return { types, contractTypes, portabilityClasses, core };
+  return { types, contractTypes, portabilityClasses, core, extensions };
 }
 
 /** Is this document type append-only (events appended, never rewritten)? */
@@ -65,3 +191,119 @@ export function resolvePortability(typeDef, frontmatter) {
   if (override && order[override] != null && order[override] > (order[base] ?? 0)) return override;
   return base;
 }
+
+/** Is a registry-declared document reference a safe vault-relative path? */
+export function isSafeDocumentPath(value) {
+  if (typeof value !== 'string' || !value || value.includes('\0') || value.includes('\\')) return false;
+  if (value.startsWith('/') || path.isAbsolute(value)) return false;
+  const parts = value.split('/');
+  return !parts.some((part) => !part || part === '.' || part === '..');
+}
+
+/** Stable hash used to bind derived/translated documents to an exact source. */
+export function documentHash(content) {
+  return `sha256:${crypto.createHash('sha256').update(String(content)).digest('hex')}`;
+}
+
+function isEmpty(value) {
+  return value === undefined || value === null || value === '' ||
+    (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Validate the registry's field-level schema independently of any storage
+ * operation. Used by the engine, bundle transport, and semantic projections.
+ */
+export function validateDataConstraints(typeDef, data, universalRequired = []) {
+  const issues = [];
+  const required = new Set([...universalRequired, ...(typeDef?.required_fields || [])]);
+  for (const field of required) {
+    if (isEmpty(data[field])) issues.push({ field, issue: `Missing required field '${field}'.` });
+  }
+  for (const [condition, fields] of Object.entries(typeDef?.required_when || {})) {
+    const match = condition.match(/^([A-Za-z_][A-Za-z0-9_-]*)==(.+)$/);
+    if (!match) continue;
+    const expected = /^-?\d+$/.test(match[2]) ? Number(match[2]) : match[2];
+    if (data[match[1]] !== expected) continue;
+    for (const field of fields) {
+      if (isEmpty(data[field])) issues.push({ field, issue: `Required when ${condition}.` });
+    }
+  }
+  for (const [field, allowed] of Object.entries(typeDef?.enums || {})) {
+    if (isEmpty(data[field])) continue;
+    const values = Array.isArray(data[field]) ? data[field] : [data[field]];
+    for (const value of values) {
+      if (!allowed.includes(value)) {
+        issues.push({ field, issue: `Invalid value '${value}'; must be one of: ${allowed.join(', ')}.` });
+      }
+    }
+  }
+  for (const [field, source] of Object.entries(typeDef?.patterns || {})) {
+    if (isEmpty(data[field])) continue;
+    const expression = new RegExp(source, 'u');
+    const values = Array.isArray(data[field]) ? data[field] : [data[field]];
+    for (const value of values) {
+      if (typeof value !== 'string' || !expression.test(value)) {
+        issues.push({ field, issue: `Value must match registry pattern '${source}'.` });
+      }
+    }
+  }
+  return issues;
+}
+
+/**
+ * Validate registry-declared document references using a caller-provided
+ * resolver. This keeps path, type, portability, and hash checks shared by the
+ * Operation Contract, bundles, and semantic/localization projections.
+ */
+export function validateReferenceConstraints(typeDef, data, resolveReference, types) {
+  const issues = [];
+  for (const [field, constraint] of Object.entries(typeDef?.references || {})) {
+    const referencePath = data[field];
+    if (referencePath === undefined || referencePath === null || referencePath === '') continue;
+    if (!isSafeDocumentPath(referencePath)) {
+      issues.push({ field, issue: `Reference path '${referencePath}' is not a safe vault-relative path.` });
+      continue;
+    }
+    let referenced = null;
+    try { referenced = resolveReference(referencePath); }
+    catch (error) {
+      issues.push({ field, issue: `Reference '${referencePath}' could not be resolved: ${error.message}` });
+      continue;
+    }
+    if (!referenced) {
+      if (constraint.must_exist !== false) {
+        issues.push({ field, issue: `Referenced document '${referencePath}' does not exist.` });
+      }
+      continue;
+    }
+    const referencedType = referenced.data?.type;
+    if (!types.has(referencedType)) {
+      issues.push({ field, issue: `Referenced document declares unknown type '${referencedType || '(missing)'}'.` });
+      continue;
+    }
+    if (constraint.allowed_types && !constraint.allowed_types.includes(referencedType)) {
+      issues.push({ field, issue: `Referenced type '${referencedType}' is not allowed.` });
+    }
+    if (constraint.disallowed_types?.includes(referencedType)) {
+      issues.push({ field, issue: `Referenced type '${referencedType}' is forbidden.` });
+    }
+    const referencedPortability = resolvePortability(types.get(referencedType), referenced.data);
+    if (constraint.allowed_portability && !constraint.allowed_portability.includes(referencedPortability)) {
+      issues.push({
+        field,
+        issue: `Referenced document is '${referencedPortability}'; allowed portability: ${constraint.allowed_portability.join(', ')}.`,
+      });
+    }
+    if (constraint.hash_field) {
+      const expected = documentHash(referenced.content);
+      if (data[constraint.hash_field] !== expected) {
+        issues.push({
+          field: constraint.hash_field,
+          issue: `Source hash mismatch for '${referencePath}'; expected '${expected}'.`,
+        });
+      }
+    }
+  }
+  return issues;
+}