@gregiteen/ssss-cli 0.7.1 → 0.8.0

package/src/bundle.mjs

@@ -16,9 +16,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { loadRegistries, resolvePortability } from './registry.mjs';
+import {
+  loadRegistries,
+  resolvePortability,
+  validateDataConstraints,
+  validateReferenceConstraints,
+} from './registry.mjs';
 import { parseDocument, serializeDocument } from './frontmatter.mjs';
 
+export const DEFAULT_EXPORTER = '@gregiteen/ssss-cli';
+
 const PROFILE_INCLUDES = {
   backup: new Set(['structural', 'tenant_private', 'resource_bound']),
   template: new Set(['structural', 'resource_bound']),
@@ -133,7 +140,7 @@ function walkVault(vaultRoot) {
  */
 export function exportBundle(vaultRoot, opts = {}) {
   const { profile = 'backup', registryDir, name = 'untitled', description = '', version = '0.1.0',
-    exporter = '@ssss/cli', requiredExtensions = [], parameters = [], provisioning = [],
+    exporter = DEFAULT_EXPORTER, requiredExtensions = [], parameters = [], provisioning = [],
     sourceWorkspaceId, exportedAt = '1970-01-01T00:00:00.000Z' } = opts;
   const includes = PROFILE_INCLUDES[profile];
   if (!includes) throw new Error(`Unknown export profile '${profile}'. Use backup | template | sale.`);
@@ -145,8 +152,35 @@ export function exportBundle(vaultRoot, opts = {}) {
   const manifestParameters = [...parameters];
   const manifestProvisioning = [...provisioning];
   const manifestDraft = { parameters: manifestParameters, provisioning: manifestProvisioning };
+  const vaultFiles = walkVault(vaultRoot);
+  const vaultDocuments = new Map(vaultFiles.map((file) => {
+    const parsed = parseDocument(file.content);
+    return [file.path, { ...file, ...parsed }];
+  }));
 
-  for (const file of walkVault(vaultRoot)) {
+  for (const document of vaultDocuments.values()) {
+    const base = path.basename(document.path);
+    if (base === 'index.md' || base === 'log.md') continue;
+    const definition = types.get(document.data.type);
+    if (!definition) throw new Error(`Cannot export '${document.path}': unknown type '${document.data.type || '(missing)'}'.`);
+    const issues = [
+      ...validateDataConstraints(definition, document.data, core.universal_frontmatter?.required || ['type']),
+      ...validateReferenceConstraints(
+      definition,
+      document.data,
+      (referencePath) => vaultDocuments.get(referencePath) || null,
+      types
+      ),
+    ];
+    if (issues.length) {
+      throw new Error(
+        `Cannot export '${document.path}': ` +
+        issues.map((issue) => `${issue.field}: ${issue.issue}`).join('; ')
+      );
+    }
+  }
+
+  for (const file of vaultFiles) {
     const { data } = parseDocument(file.content);
     const type = data.type;
     const typeDef = types.get(type);
@@ -188,14 +222,29 @@ export function validateBundle(bundle, opts = {}) {
   const errors = [];
   const { types, core, extensions } = loadRegistries(opts.registryDir);
   const m = bundle && bundle.manifest;
-  if (!m) return { valid: false, errors: ['bundle has no manifest'] };
+  if (!m || typeof m !== 'object' || Array.isArray(m)) {
+    return { valid: false, errors: ['bundle has no object manifest'] };
+  }
   const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const requiredExtensions = Array.isArray(m.required_extensions) ? m.required_extensions : [];
+  const provisioning = Array.isArray(m.provisioning) ? m.provisioning : [];
+  const parameters = Array.isArray(m.parameters) ? m.parameters : [];
 
   for (const f of core.bundle.manifest_required_fields) {
     if (m[f] === undefined || m[f] === null) errors.push(`manifest missing required field '${f}'`);
   }
   if (!Array.isArray(bundle.files)) errors.push('bundle.files must be an array');
-  for (const ext of m.required_extensions || []) {
+  if (!Array.isArray(m.required_extensions)) errors.push('manifest.required_extensions must be an array');
+  if (!Array.isArray(m.provisioning)) errors.push('manifest.provisioning must be an array');
+  if (!Array.isArray(m.parameters)) errors.push('manifest.parameters must be an array');
+  if (!m.primitive_inventory || typeof m.primitive_inventory !== 'object' || Array.isArray(m.primitive_inventory)) {
+    errors.push('manifest.primitive_inventory must be an object');
+  }
+  for (const ext of requiredExtensions) {
+    if (typeof ext !== 'string' || !ext) {
+      errors.push('required extension ids must be non-empty strings');
+      continue;
+    }
     if (!extensions.has(ext)) errors.push(`required extension '${ext}' is not loaded`);
   }
   if (!PROFILE_INCLUDES[m.export_profile]) errors.push(`invalid export_profile '${m.export_profile}'`);
@@ -206,71 +255,110 @@ export function validateBundle(bundle, opts = {}) {
     errors.push(`file_count ${m.file_count} ≠ actual ${files.length}`);
   }
   const seenPaths = new Set();
+  const bundleDocuments = new Map();
+  let fileShapeValid = true;
   for (const file of files) {
+    if (!file || typeof file !== 'object' || Array.isArray(file)) {
+      errors.push('bundle file entries must be objects');
+      fileShapeValid = false;
+      continue;
+    }
     if (!isSafeBundlePath(file.path)) {
       errors.push(`file '${file.path || '(missing)'}' has an unsafe bundle path`);
+      fileShapeValid = false;
+      continue;
+    }
+    if (typeof file.content !== 'string') {
+      errors.push(`file '${file.path}' content must be a string`);
+      fileShapeValid = false;
       continue;
     }
     if (seenPaths.has(file.path)) errors.push(`duplicate file path '${file.path}'`);
     seenPaths.add(file.path);
+    try { bundleDocuments.set(file.path, { ...file, ...parseDocument(file.content) }); }
+    catch (error) {
+      errors.push(`file '${file.path}' could not be parsed: ${error.message}`);
+      fileShapeValid = false;
+    }
   }
   // Provenance: recompute the content hash and reject on mismatch (§16.3).
   if (m.provenance) {
-    for (const f of core.bundle.provenance_required_fields) {
-      if (m.provenance[f] === undefined) errors.push(`provenance missing '${f}'`);
-    }
-    const recomputed = contentHash(files);
-    if (m.provenance.content_hash && m.provenance.content_hash !== recomputed) {
-      errors.push(`content_hash mismatch: manifest ${m.provenance.content_hash} ≠ recomputed ${recomputed}`);
+    if (typeof m.provenance !== 'object' || Array.isArray(m.provenance)) {
+      errors.push('manifest.provenance must be an object');
+    } else {
+      for (const f of core.bundle.provenance_required_fields) {
+        if (m.provenance[f] === undefined) errors.push(`provenance missing '${f}'`);
+      }
+      if (fileShapeValid) {
+        const recomputed = contentHash(files);
+        if (m.provenance.content_hash && m.provenance.content_hash !== recomputed) {
+          errors.push(`content_hash mismatch: manifest ${m.provenance.content_hash} ≠ recomputed ${recomputed}`);
+        }
+      }
     }
   }
   // Portability conformance: no file may exceed what the profile permits (§5.5).
   const includes = PROFILE_INCLUDES[m.export_profile];
   if (includes) {
-    for (const file of files) {
-      if (!isSafeBundlePath(file.path)) continue;
-      const base = path.basename(file.path || '');
+    for (const document of bundleDocuments.values()) {
+      const base = path.basename(document.path);
       if (base === 'index.md' || base === 'log.md') continue;
-      const { data } = parseDocument(file.content);
+      const { data } = document;
       const def = types.get(data.type);
       if (!def) {
-        errors.push(`file '${file.path}' declares unknown type '${data.type || '(missing)'}'`);
+        errors.push(`file '${document.path}' declares unknown type '${data.type || '(missing)'}'`);
         continue;
       }
-      const requiredFields = [
-        ...new Set([
-          ...(core.universal_frontmatter?.required || ['type']),
-          ...(def.required_fields || []),
-        ]),
-      ];
-      for (const f of requiredFields) {
-        if (data[f] === undefined || data[f] === null || data[f] === '' || (Array.isArray(data[f]) && data[f].length === 0)) {
-          errors.push(`file '${file.path}' missing required frontmatter field '${f}'`);
-        }
+      for (const issue of validateDataConstraints(
+        def,
+        data,
+        core.universal_frontmatter?.required || ['type']
+      )) {
+        errors.push(`file '${document.path}' ${issue.field}: ${issue.issue}`);
       }
       const klass = resolvePortability(types.get(data.type), data);
       if (!includes.has(klass)) {
-        errors.push(`file '${file.path}' is ${klass}, excluded by profile '${m.export_profile}'`);
+        errors.push(`file '${document.path}' is ${klass}, excluded by profile '${m.export_profile}'`);
       }
       if ((m.export_profile === 'sale' || m.export_profile === 'template') && klass === 'resource_bound') {
         const binds = def.resource?.binds || [];
         if (!binds.length) {
-          errors.push(`file '${file.path}' is resource_bound but registry type '${data.type}' declares no resource.binds`);
+          errors.push(`file '${document.path}' is resource_bound but registry type '${data.type}' declares no resource.binds`);
         }
         for (const field of binds) {
           if (data[field] !== 'REQUIREMENT') {
-            errors.push(`file '${file.path}' leaks resource_bound field '${field}' in ${m.export_profile} bundle`);
+            errors.push(`file '${document.path}' leaks resource_bound field '${field}' in ${m.export_profile} bundle`);
           }
         }
       }
     }
   }
+  for (const document of bundleDocuments.values()) {
+    const definition = types.get(document.data.type);
+    const issues = validateReferenceConstraints(
+      definition,
+      document.data,
+      (referencePath) => bundleDocuments.get(referencePath) || null,
+      types
+    );
+    for (const issue of issues) {
+      errors.push(`file '${document.path}' ${issue.field}: ${issue.issue}`);
+    }
+  }
   // Provisioning step + parameter vocabularies (§17.2 / §16.5).
-  for (const s of m.provisioning || []) {
+  for (const s of provisioning) {
+    if (!s || typeof s !== 'object' || Array.isArray(s)) {
+      errors.push('provisioning entries must be objects');
+      continue;
+    }
     if (!STEP_SYSTEMS.has(s.system)) errors.push(`provisioning step '${s.id}' has invalid system '${s.system}'`);
     if (!STEP_MODES.has(s.mode)) errors.push(`provisioning step '${s.id}' has invalid mode '${s.mode}'`);
   }
-  for (const p of m.parameters || []) {
+  for (const p of parameters) {
+    if (!p || typeof p !== 'object' || Array.isArray(p)) {
+      errors.push('parameter entries must be objects');
+      continue;
+    }
     for (const f of core.bundle.parameter_fields.required) {
       if (p[f] === undefined) errors.push(`parameter '${p.key || '?'}' missing '${f}'`);
     }
@@ -342,9 +430,57 @@ export function provisionBundle(bundle, opts = {}) {
  * (§6.3). Idempotent: each envelope's idempotency_key makes a re-run a no-op.
  */
 export function importBundle(plan, vaultRoot, engine) {
+  const dryRunFlags = new Set(plan.map((envelope) => !!envelope.dry_run));
+  if (dryRunFlags.size > 1) {
+    return {
+      ok: false,
+      committed: 0,
+      wouldCommit: 0,
+      results: [{
+        success: false,
+        validation: { valid: false, errors: ['Import plan may not mix dry_run and commit envelopes.'] },
+      }],
+    };
+  }
+  const plannedDocuments = new Map();
+  for (const envelope of plan) {
+    if (envelope.type !== 'operation' || typeof envelope.content !== 'string') continue;
+    plannedDocuments.set(envelope.path, {
+      path: envelope.path,
+      content: envelope.content,
+      ...parseDocument(envelope.content),
+    });
+  }
+  const operationOptions = {
+    referenceResolver: (referencePath) => plannedDocuments.get(referencePath),
+  };
+  // Two-phase import: validate the complete plan with in-plan references first.
+  // A single invalid document prevents every commit, eliminating partial bundle
+  // installation and allowing dry-run to validate cross-file constraints.
+  const preflight = plan.map((envelope) => {
+    const preflightKey = 'preflight-' + crypto.createHash('sha256')
+      .update(`${envelope.workspace_id}:${envelope.idempotency_key}:${envelope.path}`)
+      .digest('hex')
+      .slice(0, 32);
+    return engine.processOperation(
+      { ...envelope, idempotency_key: preflightKey, dry_run: true },
+      vaultRoot,
+      operationOptions
+    );
+  });
+  if (!preflight.every((result) => result.success)) {
+    return { ok: false, committed: 0, wouldCommit: 0, results: preflight };
+  }
+  if (dryRunFlags.has(true)) {
+    return {
+      ok: true,
+      committed: 0,
+      wouldCommit: preflight.filter((result) => !result.replay).length,
+      results: preflight,
+    };
+  }
   const results = [];
-  for (const env of plan) results.push(engine.processOperation(env, vaultRoot));
+  for (const env of plan) results.push(engine.processOperation(env, vaultRoot, operationOptions));
   const committed = results.filter((r) => r.success && !r.replay && !r.dry_run).length;
-  const wouldCommit = results.filter((r) => r.success && !r.replay && r.dry_run).length;
-  return { ok: results.every((r) => r.success), committed, wouldCommit, results };
+  return { ok: results.every((r) => r.success), committed, wouldCommit: 0, results };
 }

package/src/engine.mjs

@@ -15,7 +15,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { parseDocument, serializeDocument } from './frontmatter.mjs';
-import { loadRegistries, isAppendType } from './registry.mjs';
+import {
+  loadRegistries,
+  isAppendType,
+  validateReferenceConstraints,
+} from './registry.mjs';
 
 const ENVELOPE_TYPES = ['operation', 'patch', 'event', 'delete'];
 const ENVELOPE_REQUIRED = {
@@ -150,7 +154,7 @@ export function createEngine({ registryDir, leaseStore } = {}) {
     return { field, value };
   }
 
-  function validateContent(resolvedType, data, filePath) {
+  function validateContent(resolvedType, data, filePath, vaultRoot, referenceResolver) {
     const def = types.get(resolvedType);
     const errors = [];
     const repair = [];
@@ -193,6 +197,43 @@ export function createEngine({ registryDir, leaseStore } = {}) {
         }
       }
     }
+    // patterns: portable string constraints declared by the registry. These
+    // are anchored by each pattern author and compiled during registry load.
+    for (const [field, pattern] of Object.entries(def.patterns || {})) {
+      if (isEmpty(data[field])) continue;
+      const values = Array.isArray(data[field]) ? data[field] : [data[field]];
+      const expression = new RegExp(pattern, 'u');
+      for (const value of values) {
+        if (typeof value !== 'string' || !expression.test(value)) {
+          errors.push(`Invalid format for field '${field}' on type '${resolvedType}'.`);
+          repair.push({ field, issue: `Must match registry pattern '${pattern}'.` });
+        }
+      }
+    }
+    if (vaultRoot && def.references) {
+      const referenceIssues = validateReferenceConstraints(
+        def,
+        data,
+        (referencePath) => {
+          if (referenceResolver) {
+            const planned = referenceResolver(referencePath);
+            if (planned !== undefined && planned !== null) return planned;
+          }
+          const target = resolveContainedPath(vaultRoot, referencePath);
+          if (!fs.existsSync(target)) return null;
+          const stat = fs.lstatSync(target);
+          if (stat.isSymbolicLink()) throw new Error('symlinked references are not allowed');
+          if (!stat.isFile()) throw new Error('reference target is not a file');
+          const content = fs.readFileSync(target, 'utf8');
+          return { path: referencePath, content, data: parseDocument(content).data };
+        },
+        types
+      );
+      for (const issue of referenceIssues) {
+        errors.push(`${issue.field}: ${issue.issue}`);
+        repair.push(issue);
+      }
+    }
     return { errors, repair };
   }
 
@@ -297,7 +338,13 @@ export function createEngine({ registryDir, leaseStore } = {}) {
         const { data } = parseDocument(envelope.content);
         resolvedType = data.type || null;
         if (!resolvedType) { errors.push(`Missing required frontmatter field 'type' in ${envelope.path}.`); repair.push({ field: 'type', issue: 'Frontmatter must declare a type.' }); }
-        else ({ errors, repair } = validateContent(resolvedType, data, envelope.path));
+        else ({ errors, repair } = validateContent(
+          resolvedType,
+          data,
+          envelope.path,
+          vaultRoot,
+          options.referenceResolver
+        ));
       }
       if (!errors.length && fs.existsSync(abs) && !envelope.path.endsWith('/index.md')) {
         const { data: existingData } = parseDocument(fs.readFileSync(abs, 'utf8'));
@@ -305,6 +352,13 @@ export function createEngine({ registryDir, leaseStore } = {}) {
           errors.push(`Type rewrite refused for ${envelope.path}: existing type '${existingData.type}' cannot be replaced by '${resolvedType}'.`);
           repair.push({ field: 'type', issue: 'Use a migration controlled by a privileged host; operation writes may not change an existing file type.' });
         }
+        const { data: nextData } = parseDocument(envelope.content);
+        for (const field of types.get(resolvedType)?.immutable_fields || []) {
+          if (stableStringify(existingData[field]) !== stableStringify(nextData[field])) {
+            errors.push(`Operation may not change immutable field '${field}' for ${envelope.path}.`);
+            repair.push({ field, issue: 'Use an explicit migration rather than replacing an immutable identity field.' });
+          }
+        }
       }
       // append-type rewrite guard
       if (!errors.length && isAppendType(types.get(resolvedType)) && fs.existsSync(abs)) {
@@ -326,13 +380,33 @@ export function createEngine({ registryDir, leaseStore } = {}) {
         const merged = { ...data };
         for (const [k, v] of Object.entries(envelope.patches)) if (k !== '__body__') merged[k] = v;
         resolvedType = merged.type || null;
+        for (const field of types.get(resolvedType)?.immutable_fields || []) {
+          if (Object.prototype.hasOwnProperty.call(envelope.patches, field) &&
+              stableStringify(data[field]) !== stableStringify(merged[field])) {
+            errors.push(`Patch may not change immutable field '${field}' for ${envelope.path}.`);
+            repair.push({ field, issue: 'Use an explicit migration rather than patching an immutable identity field.' });
+          }
+        }
         const append = isAppendType(types.get(resolvedType));
         let newBody = body;
         if (envelope.patches.__body__ !== undefined) {
           if (append) newBody = body.replace(/\s+$/, '') + '\n' + envelope.patches.__body__;
           else newBody = envelope.patches.__body__;
         }
-        ({ errors, repair } = resolvedType ? validateContent(resolvedType, merged, envelope.path) : { errors: ["Missing required field 'type'."], repair: [{ field: 'type', issue: 'No type after merge.' }] });
+        if (resolvedType) {
+          const contentValidation = validateContent(
+            resolvedType,
+            merged,
+            envelope.path,
+            vaultRoot,
+            options.referenceResolver
+          );
+          errors.push(...contentValidation.errors);
+          repair.push(...contentValidation.repair);
+        } else {
+          errors.push("Missing required field 'type'.");
+          repair.push({ field: 'type', issue: 'No type after merge.' });
+        }
         mergedForCommit = { data: merged, body: newBody };
       }
     } else if (envelope.type === 'event') {