@gregiteen/ssss-cli 0.7.0 → 0.8.0

package/src/bundle.mjs

@@ -16,8 +16,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { loadRegistries, resolvePortability } from './registry.mjs';
-import { parseDocument } from './frontmatter.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']),
@@ -27,6 +34,13 @@ const PROFILE_INCLUDES = {
 const STEP_SYSTEMS = new Set(['workspace', 'branding', 'email', 'phone', 'domains', 'accounts', 'deployments', 'marketplace', 'tabs', 'automation']);
 const STEP_MODES = new Set(['existing', 'provision', 'install', 'generate', 'configure']);
 const PARAM_SOURCES = new Set(['user', 'llm', 'graph', 'system']);
+const RESOURCE_SYSTEM_BY_KIND = {
+  api_connection: 'automation',
+  domain: 'domains',
+  email: 'email',
+  mailbox: 'email',
+  phone: 'phone',
+};
 
 function isSafeBundlePath(p) {
   if (typeof p !== 'string' || !p || p.includes('\0')) return false;
@@ -41,6 +55,62 @@ function canonicalFiles(files) {
   return sorted.map((f) => ({ path: f.path, content: f.content }));
 }
 
+function requirementParameterKey(type, field) {
+  return `${type}_${field}`.replace(/[^A-Za-z0-9_]+/g, '_');
+}
+
+function resourceFieldParameterAliases(type, field) {
+  const aliases = [requirementParameterKey(type, field), field];
+  if (type === 'domain' && field === 'domain_name') aliases.push('domain');
+  if (type === 'phone_number' && field === 'phone_number') aliases.push('phone');
+  return aliases;
+}
+
+function ensureRequirementDeclarations(manifest, typeDef, resourceFields) {
+  const type = typeDef.type;
+  const resource = typeDef.resource || {};
+  const existingParams = new Set((manifest.parameters || []).map((p) => p.key));
+  for (const field of resourceFields) {
+    if (resourceFieldParameterAliases(type, field).some((key) => existingParams.has(key))) continue;
+    const key = requirementParameterKey(type, field);
+    if (!existingParams.has(key)) {
+      manifest.parameters.push({
+        key,
+        label: `${resource.kind || type} ${field}`.replace(/_/g, ' '),
+        type: 'string',
+        scope: 'workspace',
+        source: 'user',
+        required: false,
+        description: `Satisfies the ${type} resource requirement field '${field}'.`,
+      });
+      existingParams.add(key);
+    }
+  }
+
+  const stepId = `bind-${type}`.replace(/[^A-Za-z0-9_-]+/g, '-');
+  if (!(manifest.provisioning || []).some((s) => s.id === stepId)) {
+    manifest.provisioning.push({
+      id: stepId,
+      label: `Bind ${resource.kind || type}`,
+      system: RESOURCE_SYSTEM_BY_KIND[resource.kind] || 'accounts',
+      mode: 'provision',
+      required: true,
+      notes: resource.provision_relation || 'resource_bound requirement',
+    });
+  }
+}
+
+function reduceResourceBoundFile(file, typeDef, profile) {
+  const binds = typeDef?.resource?.binds;
+  if (!Array.isArray(binds) || binds.length === 0) {
+    throw new Error(`Cannot export resource_bound '${file.path}' in ${profile}: registry type '${typeDef?.type || '(unknown)'}' does not declare resource.binds.`);
+  }
+  const { data, body } = parseDocument(file.content);
+  const reduced = { ...data, x_portability: 'resource_bound' };
+  for (const field of binds) reduced[field] = 'REQUIREMENT';
+  return { path: file.path, content: serializeDocument(reduced, body), resourceFields: binds };
+}
+
 /** sha256 over the canonical file serialization (§16.3). */
 export function contentHash(files) {
   const pre = JSON.stringify(canonicalFiles(files));
@@ -70,23 +140,59 @@ 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.`);
 
-  const { types } = loadRegistries(registryDir);
+  const { types, core } = loadRegistries(registryDir);
   const dropped = [];
   const kept = [];
   const inventory = {};
+  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 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 walkVault(vaultRoot)) {
+  for (const file of vaultFiles) {
     const { data } = parseDocument(file.content);
     const type = data.type;
     const typeDef = types.get(type);
     const klass = resolvePortability(typeDef, data);
     if (!includes.has(klass)) { dropped.push({ path: file.path, type, portability: klass }); continue; }
-    kept.push(file);
+    if ((profile === 'sale' || profile === 'template') && klass === 'resource_bound') {
+      const reduced = reduceResourceBoundFile(file, typeDef, profile);
+      kept.push({ path: reduced.path, content: reduced.content });
+      ensureRequirementDeclarations(manifestDraft, typeDef, reduced.resourceFields);
+    } else {
+      kept.push(file);
+    }
     if (type) inventory[type] = (inventory[type] || 0) + 1;
   }
 
@@ -94,12 +200,12 @@ export function exportBundle(vaultRoot, opts = {}) {
   const manifest = {
     name, description, version,
     exported_at: exportedAt,
-    ssss_core_version: loadRegistries(registryDir).core.spec_version,
+    ssss_core_version: core.spec_version,
     required_extensions: requiredExtensions,
     export_profile: profile,
     primitive_inventory: inventory,
-    provisioning,
-    parameters,
+    provisioning: manifestProvisioning,
+    parameters: manifestParameters,
     file_count: files.length,
     provenance: { content_hash: contentHash(files), exporter },
   };
@@ -114,75 +220,145 @@ export function exportBundle(vaultRoot, opts = {}) {
  */
 export function validateBundle(bundle, opts = {}) {
   const errors = [];
-  const { types, core } = loadRegistries(opts.registryDir);
+  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');
+  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}'`);
   if (m.ssss_core_version && m.ssss_core_version !== core.spec_version) {
     errors.push(`bundle targets ssss_core_version ${m.ssss_core_version}; host is ${core.spec_version}`);
   }
-  if (Array.isArray(bundle.files) && m.file_count !== bundle.files.length) {
-    errors.push(`file_count ${m.file_count} ≠ actual ${bundle.files.length}`);
+  if (m.file_count !== files.length) {
+    errors.push(`file_count ${m.file_count} ≠ actual ${files.length}`);
   }
   const seenPaths = new Set();
-  for (const file of bundle.files || []) {
+  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(bundle.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 bundle.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 '${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 '${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}'`);
     }
@@ -254,8 +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));
-  const committed = results.filter((r) => r.success && !r.replay).length;
-  return { ok: results.every((r) => r.success), committed, results };
+  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;
+  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') {