@gregiteen/ssss-cli 0.7.0

package/scripts/validate-skills.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Skill-package conformance: every skill shipped under skills/ (tracked,
+ * published — as opposed to an agent tool's local .agent/skills/ vendor
+ * copy) must (a) validate as an SSSS `skill` primitive per
+ * registry/core.json, and (b) satisfy the skill package's own required
+ * directory structure (scripts/, references/, evals/, subagents/, each
+ * non-empty, evals/evals.json with 3+ assertions).
+ *
+ * This is the automatic backstop for a bug this repo actually shipped: the
+ * skill-format guide told agents `type: skill` was a frontmatter
+ * anti-pattern, when registry/core.json and docs/ssss-spec.md §5.4 both
+ * REQUIRE it. Every skill in this repo silently violated its own spec.
+ * Wired into `ssss conformance` (scripts/conformance.mjs) so that class of
+ * drift can't recur unnoticed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRegistries } from '../src/registry.mjs';
+import { parseDocument } from '../src/frontmatter.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
+const REQUIRED_DIRS = ['scripts', 'references', 'evals', 'subagents'];
+const MIN_EVALS = 3;
+const NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+function nonEmptyRealFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f !== '.gitkeep' && !f.startsWith('.'));
+}
+
+/**
+ * @returns {string[]} human-readable problem descriptions; empty = fully conformant.
+ */
+export function validateSkills(skillsDir = SKILLS_DIR) {
+  const problems = [];
+  if (!fs.existsSync(skillsDir)) return problems; // nothing shipped yet is not an error
+
+  const { types, core } = loadRegistries();
+  const skillDef = types.get('skill');
+  if (!skillDef) {
+    problems.push("registry/core.json no longer defines a 'skill' primitive — validate-skills.mjs is stale.");
+    return problems;
+  }
+  const requiredFields = [
+    ...new Set([
+      ...(core.universal_frontmatter?.required || ['type']),
+      ...(skillDef.required_fields || ['type', 'name', 'description']),
+    ]),
+  ];
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+  for (const entry of entries) {
+    const name = entry.name;
+    const dir = path.join(skillsDir, name);
+    const skillMd = path.join(dir, 'SKILL.md');
+
+    if (!fs.existsSync(skillMd)) {
+      problems.push(`skills/${name}/: missing SKILL.md (canonical filename, spec §4.4).`);
+      continue;
+    }
+
+    // ── Frontmatter: must validate against the registry's skill primitive ──
+    const { data } = parseDocument(fs.readFileSync(skillMd, 'utf8'));
+    for (const field of requiredFields) {
+      if (data[field] === undefined || data[field] === null || data[field] === '') {
+        problems.push(`skills/${name}/SKILL.md: missing required field '${field}' (registry/core.json skill primitive).`);
+      }
+    }
+    if (data.type !== undefined && data.type !== 'skill') {
+      problems.push(`skills/${name}/SKILL.md: type is '${data.type}', expected 'skill'.`);
+    }
+    if (data.name !== undefined && data.name !== name) {
+      problems.push(`skills/${name}/SKILL.md: frontmatter name '${data.name}' does not match its directory name '${name}' (spec §13 naming convention).`);
+    }
+    if (!NAME_RE.test(name)) {
+      problems.push(`skills/${name}/: directory name is not kebab-case (spec §13 naming convention).`);
+    }
+
+    // ── Required directory structure ──
+    for (const sub of REQUIRED_DIRS) {
+      const files = nonEmptyRealFiles(path.join(dir, sub));
+      if (!files.length) {
+        problems.push(`skills/${name}/${sub}/: required and must contain at least one real file (a bare .gitkeep does not count).`);
+      }
+    }
+
+    // ── evals/evals.json shape ──
+    const evalsPath = path.join(dir, 'evals', 'evals.json');
+    if (fs.existsSync(evalsPath)) {
+      try {
+        const evals = JSON.parse(fs.readFileSync(evalsPath, 'utf8'));
+        if (!Array.isArray(evals) || evals.length < MIN_EVALS) {
+          problems.push(`skills/${name}/evals/evals.json: must be an array of at least ${MIN_EVALS} assertions (found ${Array.isArray(evals) ? evals.length : 'non-array'}).`);
+        }
+      } catch (err) {
+        problems.push(`skills/${name}/evals/evals.json: invalid JSON (${err.message}).`);
+      }
+    }
+  }
+
+  return problems;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const problems = validateSkills();
+  if (problems.length) {
+    console.error('❌ Skill conformance failed:');
+    for (const p of problems) console.error(`   • ${p}`);
+    process.exit(1);
+  }
+  console.log('✅ Skill conformance: every shipped skill validates against the skill primitive and required directory structure.');
+}

package/src/bundle.mjs

@@ -0,0 +1,261 @@
+/**
+ * The `.ucw` bundle format (§16) and the provisioning contract (§17).
+ *
+ * Harvested and canonicalized from ultrachat's `WorkspaceVfsPackageService`
+ * (the export/package shape) and `server/types/workspace.ts` (the template
+ * variable, provisioning-step, and edge-relation vocabularies). Generalized to
+ * be registry-driven: portability filtering reads `registry/core.json` §5.5
+ * rather than ultrachat's hard-coded capability booleans, and the primitive
+ * inventory counts by registry `type` rather than a closed category enum.
+ *
+ * Three pure-ish verbs (§17.1):
+ *   exportBundle(vault, opts)        vault + profile  → bundle           (pure)
+ *   provisionBundle(bundle, opts)    bundle + params  → replayable plan
+ *   importBundle(plan, vault, eng)   plan  + engine   → committed state  (idempotent)
+ */
+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';
+
+const PROFILE_INCLUDES = {
+  backup: new Set(['structural', 'tenant_private', 'resource_bound']),
+  template: new Set(['structural', 'resource_bound']),
+  sale: new Set(['structural', 'resource_bound']),
+};
+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']);
+
+function isSafeBundlePath(p) {
+  if (typeof p !== 'string' || !p || p.includes('\0')) return false;
+  if (p.startsWith('/') || p.startsWith('\\') || p.includes('\\')) return false;
+  const parts = p.split('/');
+  return !parts.some((part) => part === '' || part === '.' || part === '..');
+}
+
+/** Canonical, path-sorted serialization of files — the hash + transport pre-image (§16.1). */
+function canonicalFiles(files) {
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return sorted.map((f) => ({ path: f.path, content: f.content }));
+}
+
+/** sha256 over the canonical file serialization (§16.3). */
+export function contentHash(files) {
+  const pre = JSON.stringify(canonicalFiles(files));
+  return 'sha256:' + crypto.createHash('sha256').update(pre).digest('hex');
+}
+
+/** Recursively list *.md files under a vault, excluding the event log. */
+function walkVault(vaultRoot) {
+  const out = [];
+  (function rec(dir, rel) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue; // skip .events, dotfiles
+      if (entry.isSymbolicLink()) throw new Error(`Refusing to export symlinked vault entry: ${rel ? `${rel}/` : ''}${entry.name}`);
+      const abs = path.join(dir, entry.name);
+      const r = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) rec(abs, r);
+      else if (entry.name.endsWith('.md')) out.push({ path: r, content: fs.readFileSync(abs, 'utf8') });
+    }
+  })(vaultRoot, '');
+  return out;
+}
+
+/**
+ * export(vault, profile) → bundle (§17.1). Walks the vault, filters by the §5.5
+ * portability rules for the profile, sorts by path, builds the inventory, and
+ * computes provenance. Pure: equal vault state + profile → byte-identical bundle.
+ */
+export function exportBundle(vaultRoot, opts = {}) {
+  const { profile = 'backup', registryDir, name = 'untitled', description = '', version = '0.1.0',
+    exporter = '@ssss/cli', 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 dropped = [];
+  const kept = [];
+  const inventory = {};
+
+  for (const file of walkVault(vaultRoot)) {
+    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 (type) inventory[type] = (inventory[type] || 0) + 1;
+  }
+
+  const files = canonicalFiles(kept);
+  const manifest = {
+    name, description, version,
+    exported_at: exportedAt,
+    ssss_core_version: loadRegistries(registryDir).core.spec_version,
+    required_extensions: requiredExtensions,
+    export_profile: profile,
+    primitive_inventory: inventory,
+    provisioning,
+    parameters,
+    file_count: files.length,
+    provenance: { content_hash: contentHash(files), exporter },
+  };
+  // source_workspace_id is operator-identifying — only carried in a backup (§16.2).
+  if (profile === 'backup' && sourceWorkspaceId) manifest.source_workspace_id = sourceWorkspaceId;
+  return { manifest, files, _dropped: dropped };
+}
+
+/**
+ * Validate a bundle against the registry bundle schema (§16) and the profile/
+ * portability conformance rules (§5.5). Returns { valid, errors }.
+ */
+export function validateBundle(bundle, opts = {}) {
+  const errors = [];
+  const { types, core } = loadRegistries(opts.registryDir);
+  const m = bundle && bundle.manifest;
+  if (!m) return { valid: false, errors: ['bundle has no manifest'] };
+
+  for (const f of core.bundle.manifest_required_fields) {
+    if (m[f] === undefined || m[f] === null) errors.push(`manifest missing required field '${f}'`);
+  }
+  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}`);
+  }
+  const seenPaths = new Set();
+  for (const file of bundle.files || []) {
+    if (!isSafeBundlePath(file.path)) {
+      errors.push(`file '${file.path || '(missing)'}' has an unsafe bundle path`);
+      continue;
+    }
+    if (seenPaths.has(file.path)) errors.push(`duplicate file path '${file.path}'`);
+    seenPaths.add(file.path);
+  }
+  // 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}`);
+    }
+  }
+  // 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 || '');
+      if (base === 'index.md' || base === 'log.md') continue;
+      const { data } = parseDocument(file.content);
+      const def = types.get(data.type);
+      if (!def) {
+        errors.push(`file '${file.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}'`);
+        }
+      }
+      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}'`);
+      }
+    }
+  }
+  // Provisioning step + parameter vocabularies (§17.2 / §16.5).
+  for (const s of m.provisioning || []) {
+    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 f of core.bundle.parameter_fields.required) {
+      if (p[f] === undefined) errors.push(`parameter '${p.key || '?'}' missing '${f}'`);
+    }
+    if (p.source && !PARAM_SOURCES.has(p.source)) errors.push(`parameter '${p.key}' has invalid source '${p.source}'`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/** Extract internal references a file points at: `[[slug]]` links and relative `*.md` paths. */
+function internalRefs(content) {
+  const refs = new Set();
+  for (const m of content.matchAll(/\[\[([^\]]+)\]\]/g)) refs.add(m[1].trim());
+  return [...refs];
+}
+
+/**
+ * provision(bundle, params, target) → replayable plan (§17.1). Resolves
+ * parameters, checks link integrity under id-remap (§17.3), and emits an ordered
+ * list of Operation Contract envelopes (§6). Does not touch the filesystem.
+ */
+export function provisionBundle(bundle, opts = {}) {
+  const { parameters = {}, workspaceId = 'ws-provision', pathPrefix = '', dryRun = false } = opts;
+  const validation = validateBundle(bundle, { registryDir: opts.registryDir });
+  if (!validation.valid) {
+    return { ok: false, plan: [], unresolved: [], danglingLinks: [], errors: validation.errors, steps: [] };
+  }
+  const m = bundle.manifest;
+
+  // Resolve required parameters (§16.5).
+  const unresolved = [];
+  for (const p of m.parameters || []) {
+    if (p.required && parameters[p.key] === undefined && p.defaultValue === undefined) unresolved.push(p.key);
+  }
+
+  // Id-remap: every file is placed under the target prefix; build the slug set so
+  // we can verify link integrity (§17.3) against the remapped target.
+  const normalizedPrefix = pathPrefix ? pathPrefix.replace(/\/$/, '') : '';
+  if (normalizedPrefix && !isSafeBundlePath(normalizedPrefix)) {
+    return { ok: false, plan: [], unresolved, danglingLinks: [], errors: [`unsafe path prefix '${pathPrefix}'`], steps: m.provisioning || [] };
+  }
+  const remap = (rel) => (normalizedPrefix ? `${normalizedPrefix}/${rel}` : rel);
+  const presentSlugs = new Set();
+  for (const f of bundle.files) {
+    const { data } = parseDocument(f.content);
+    if (data.slug) presentSlugs.add(data.slug);
+    presentSlugs.add(f.path.replace(/\.md$/, ''));
+    presentSlugs.add(f.path.replace(/.*\//, '').replace(/\.md$/, ''));
+  }
+  const danglingLinks = [];
+  for (const f of bundle.files) {
+    for (const ref of internalRefs(f.content)) {
+      if (!presentSlugs.has(ref)) danglingLinks.push({ file: f.path, ref });
+    }
+  }
+
+  // Build the envelope plan. Deterministic idempotency keys make import a no-op on re-run.
+  const plan = bundle.files.map((f) => {
+    const targetPath = remap(f.path);
+    const key = 'prov-' + crypto.createHash('sha256').update(workspaceId + ':' + targetPath).digest('hex').slice(0, 24);
+    return { type: 'operation', idempotency_key: key, path: targetPath, workspace_id: workspaceId, content: f.content, intent: 'provision', dry_run: dryRun, actor: { role: 'system' } };
+  });
+
+  const ok = unresolved.length === 0 && danglingLinks.length === 0;
+  return { ok, plan, unresolved, danglingLinks, steps: m.provisioning || [] };
+}
+
+/**
+ * import(plan, target) → replay (§17.1). Runs each envelope through the engine
+ * (§6.3). Idempotent: each envelope's idempotency_key makes a re-run a no-op.
+ */
+export function importBundle(plan, vaultRoot, engine) {
+  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 };
+}