@gregiteen/ssss-cli 0.7.1 → 0.9.0

package/src/ui.mjs

@@ -0,0 +1,100 @@
+/** Typed, capability-bound generative UI projection contract. */
+import crypto from 'node:crypto';
+
+const SAFE_ID = /^[a-z][a-z0-9_.-]{0,127}$/;
+const LAYOUTS = new Set(['form', 'table', 'detail', 'detail-with-actions', 'dashboard', 'wizard']);
+
+function isRecord(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+
+export class UiRegistry {
+  constructor() { this.components = new Map(); this.actions = new Map(); }
+  registerComponent(definition) {
+    if (!SAFE_ID.test(definition?.id || '') || typeof definition.validateProps !== 'function') throw new Error('Component id and validateProps are required.');
+    if (this.components.has(definition.id)) throw new Error(`Duplicate UI component '${definition.id}'.`);
+    this.components.set(definition.id, { ...definition });
+  }
+  registerAction(definition) {
+    if (!SAFE_ID.test(definition?.id || '') || !definition.capability || !definition.command) throw new Error('Action id, capability, and command are required.');
+    if (this.actions.has(definition.id)) throw new Error(`Duplicate UI action '${definition.id}'.`);
+    this.actions.set(definition.id, { ...definition });
+  }
+}
+
+export function validateUiManifest(manifest, { registry, visibleFields = [], grantedCapabilities = [], maxComponents = 100 } = {}) {
+  const errors = [];
+  if (!isRecord(manifest)) return { valid: false, errors: [{ field: '(root)', issue: 'UI manifest must be an object.' }] };
+  if (manifest.type !== 'ssss:ui_projection') errors.push({ field: 'type', issue: 'Expected ssss:ui_projection.' });
+  if (!LAYOUTS.has(manifest.layout)) errors.push({ field: 'layout', issue: `Use one of: ${[...LAYOUTS].join(', ')}.` });
+  if (!Array.isArray(manifest.components)) errors.push({ field: 'components', issue: 'Components must be an array.' });
+  else if (manifest.components.length > maxComponents) errors.push({ field: 'components', issue: `At most ${maxComponents} components are allowed.` });
+  const allowedFields = new Set(visibleFields);
+  const capabilities = new Set(grantedCapabilities);
+  for (const [index, component] of (manifest.components || []).entries()) {
+    const prefix = `components[${index}]`;
+    if (!isRecord(component)) { errors.push({ field: prefix, issue: 'Component must be an object.' }); continue; }
+    const definition = registry?.components.get(component.component);
+    if (!definition) { errors.push({ field: `${prefix}.component`, issue: `Unregistered component '${component.component}'.` }); continue; }
+    if (component.bind && !allowedFields.has(component.bind)) errors.push({ field: `${prefix}.bind`, issue: `Field '${component.bind}' is hidden or unknown.` });
+    if (!isRecord(component.props) || typeof component.props.label !== 'string' || !component.props.label.trim()) {
+      errors.push({ field: `${prefix}.props.label`, issue: 'An accessible label is required.' });
+    }
+    if (component.action) {
+      const action = registry.actions.get(component.action);
+      if (!action) errors.push({ field: `${prefix}.action`, issue: `Unregistered action '${component.action}'.` });
+      else if (!capabilities.has(action.capability) && !capabilities.has('*:*')) errors.push({ field: `${prefix}.action`, issue: `Missing capability '${action.capability}'.` });
+    }
+    const propIssues = definition.validateProps(component.props || {});
+    for (const issue of propIssues || []) errors.push({ field: `${prefix}.props.${issue.field || '(root)'}`, issue: issue.issue || String(issue) });
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function createDeterministicUi(definition, options = {}) {
+  const fields = (options.visibleFields || definition.fields || []).map((field) => typeof field === 'string' ? { id: field, name: field, kind: 'string' } : field);
+  return {
+    type: 'ssss:ui_projection',
+    projection_id: `ui_${crypto.createHash('sha256').update(`${definition.primitive_id || definition.qualified_type}\0${options.mode || 'form'}`).digest('hex').slice(0, 16)}`,
+    primitive: definition.primitive_id || definition.qualified_type,
+    layout: options.mode || 'form',
+    title: definition.name || definition.qualified_type,
+    components: fields.map((field) => ({
+      component: field.kind === 'enum' ? 'select-field' : field.kind === 'boolean' ? 'boolean-field' : 'data-field',
+      bind: field.id,
+      props: { label: field.name || field.id, required: !!field.required, values: field.values || undefined },
+    })),
+  };
+}
+
+export async function planUi({ definition, data, principal, language, planner, registry, visibleFields, grantedCapabilities }) {
+  const fallback = createDeterministicUi(definition, { visibleFields });
+  if (typeof planner !== 'function') return { manifest: fallback, generated: false, fallback_reason: 'planner unavailable' };
+  const safeData = Object.fromEntries(Object.entries(data || {}).filter(([key]) => visibleFields.includes(key)));
+  let candidate;
+  try {
+    candidate = await planner({
+      instruction: 'Compose a UI manifest using only registered components, visible fields, and actions. Do not emit executable code.',
+      primitive: {
+        primitive_id: definition.primitive_id,
+        qualified_type: definition.qualified_type,
+        name: definition.name,
+        fields: (definition.fields || []).filter((field) => visibleFields.includes(field.id)),
+      },
+      data: safeData,
+      principal: { id: principal.id, kind: principal.kind },
+      language,
+      components: [...registry.components.keys()],
+      actions: [...registry.actions.values()].filter((action) => grantedCapabilities.includes(action.capability)).map((action) => action.id),
+    });
+  } catch (error) {
+    return { manifest: fallback, generated: false, fallback_reason: error.message };
+  }
+  const validation = validateUiManifest(candidate, { registry, visibleFields, grantedCapabilities });
+  if (!validation.valid) return { manifest: fallback, generated: false, fallback_reason: 'generated manifest rejected', errors: validation.errors };
+  return { manifest: candidate, generated: true };
+}
+
+export function actionToEnvelope(manifestComponent, registry, input = {}) {
+  const action = registry.actions.get(manifestComponent.action);
+  if (!action) throw new Error(`Unknown UI action '${manifestComponent.action}'.`);
+  return typeof action.command === 'function' ? action.command(input) : structuredClone(action.command);
+}

package/src/validator.mjs

@@ -0,0 +1,87 @@
+/** Canonical registry-driven validation shared by every SSSS host. */
+import { parseDocument } from './frontmatter.mjs';
+import {
+  composeRegistries,
+  loadRegistries,
+  resolvePrimitiveDefinition,
+  validateDataConstraints,
+  validateReferenceConstraints,
+} from './registry.mjs';
+import { validatePrimitiveDefinition } from './primitive.mjs';
+
+function registryFor(options = {}) {
+  if (options.registrySet) return options.registrySet;
+  const base = loadRegistries(options.registryDir);
+  if (!options.extensions?.length) return base;
+  return composeRegistries({ core: base.core, extensions: options.extensions });
+}
+
+function result(declaredType, definition, issues, warnings = []) {
+  return {
+    valid: issues.length === 0,
+    type: definition?.qualified_type || declaredType || 'unknown',
+    declared_type: declaredType || null,
+    registry: definition?.registry || null,
+    primitive_version: definition?.primitive_version || 1,
+    errors: issues.map((entry) => `${entry.field}: ${entry.issue}`),
+    warnings,
+    field_errors: issues,
+  };
+}
+
+export function validateData(data, options = {}) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return result(null, null, [{ field: 'frontmatter', issue: 'Document frontmatter must be an object.' }]);
+  }
+  const declaredType = typeof data.type === 'string' ? data.type : null;
+  if (!declaredType) return result(null, null, [{ field: 'type', issue: "Missing required field 'type'." }]);
+  const registrySet = registryFor(options);
+  const definition = resolvePrimitiveDefinition(registrySet, declaredType);
+  if (!definition) return result(declaredType, null, [{ field: 'type', issue: `Unknown SSSS primitive '${declaredType}'.` }]);
+  const universal = options.enforceUniversalFields === false
+    ? ['type']
+    : (registrySet.core.universal_frontmatter?.required || ['type']);
+  const issues = validateDataConstraints(definition, data, universal);
+
+  if (definition.qualified_type === 'ssss:primitive' || definition.type === 'primitive') {
+    issues.push(...validatePrimitiveDefinition(data).errors);
+  }
+
+  if (definition.references && options.resolveReference) {
+    issues.push(...validateReferenceConstraints(
+      definition,
+      data,
+      options.resolveReference,
+      registrySet.types
+    ));
+  }
+  if (options.validateExtension) {
+    const extra = options.validateExtension({ data, definition, registrySet }) || [];
+    issues.push(...extra);
+  }
+  return result(declaredType, definition, issues);
+}
+
+export function validateDocument(content, options = {}) {
+  if (typeof content !== 'string') {
+    return result(null, null, [{ field: 'content', issue: 'Document content must be a string.' }]);
+  }
+  try {
+    const parsed = parseDocument(content);
+    const validation = validateData(parsed.data, options);
+    return { ...validation, data: parsed.data, body: parsed.body };
+  } catch (error) {
+    return result(null, null, [{ field: 'frontmatter', issue: `Invalid frontmatter: ${error.message}` }]);
+  }
+}
+
+export function createValidator(options = {}) {
+  const registrySet = registryFor(options);
+  const fixed = { ...options, registrySet, extensions: undefined, registryDir: undefined };
+  return {
+    registry: registrySet,
+    validateData: (data, callOptions = {}) => validateData(data, { ...fixed, ...callOptions, registrySet }),
+    validateDocument: (content, callOptions = {}) => validateDocument(content, { ...fixed, ...callOptions, registrySet }),
+    resolve: (type) => resolvePrimitiveDefinition(registrySet, type),
+  };
+}

package/src/vfs.mjs

@@ -0,0 +1,203 @@
+/** Standard SSSS VFS adapter contract and reference implementations. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { isSafeDocumentPath } from './registry.mjs';
+
+export class VfsConflictError extends Error {
+  constructor(message) { super(message); this.name = 'VfsConflictError'; this.code = 'SSSS_VFS_CONFLICT'; }
+}
+
+export class VfsPathError extends Error {
+  constructor(message) { super(message); this.name = 'VfsPathError'; this.code = 'SSSS_VFS_PATH'; }
+}
+
+export function bytesHash(bytes) {
+  return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function asBuffer(value) {
+  return Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
+}
+
+function checkPrecondition(current, precondition = {}) {
+  if (precondition.ifAbsent && current) throw new VfsConflictError('Target already exists.');
+  if (precondition.ifPresent && !current) throw new VfsConflictError('Target does not exist.');
+  if (precondition.version !== undefined && current?.version !== precondition.version) {
+    throw new VfsConflictError(`Version mismatch; expected '${precondition.version}', found '${current?.version || '(missing)'}'.`);
+  }
+}
+
+export class MemoryVfs {
+  #entries = new Map();
+
+  async read(vfsPath) {
+    if (!isSafeDocumentPath(vfsPath)) throw new VfsPathError(`Unsafe VFS path '${vfsPath}'.`);
+    const entry = this.#entries.get(vfsPath);
+    return entry ? { bytes: Buffer.from(entry.bytes), version: entry.version, hash: entry.hash } : null;
+  }
+
+  async stat(vfsPath) {
+    const entry = await this.read(vfsPath);
+    return entry ? { path: vfsPath, kind: 'file', size: entry.bytes.length, version: entry.version, hash: entry.hash } : null;
+  }
+
+  async *list(prefix = '') {
+    if (prefix && !isSafeDocumentPath(prefix)) throw new VfsPathError(`Unsafe VFS prefix '${prefix}'.`);
+    for (const key of [...this.#entries.keys()].sort()) {
+      if (!prefix || key === prefix || key.startsWith(`${prefix}/`)) yield await this.stat(key);
+    }
+  }
+
+  async writeAtomic(vfsPath, bytes, precondition = {}) {
+    if (!isSafeDocumentPath(vfsPath)) throw new VfsPathError(`Unsafe VFS path '${vfsPath}'.`);
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    const nextBytes = asBuffer(bytes);
+    const hash = bytesHash(nextBytes);
+    const version = hash;
+    this.#entries.set(vfsPath, { bytes: Buffer.from(nextBytes), hash, version });
+    return { path: vfsPath, hash, version, size: nextBytes.length };
+  }
+
+  async append(vfsPath, bytes, precondition = {}) {
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    const combined = Buffer.concat([current?.bytes || Buffer.alloc(0), asBuffer(bytes)]);
+    return this.writeAtomic(vfsPath, combined, current ? { version: current.version } : { ifAbsent: true });
+  }
+
+  async remove(vfsPath, precondition = {}) {
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    if (!current) return { path: vfsPath, removed: false };
+    this.#entries.delete(vfsPath);
+    return { path: vfsPath, removed: true, previous_hash: current.hash };
+  }
+}
+
+export class FileSystemVfs {
+  constructor(root) {
+    if (!root) throw new Error('FileSystemVfs requires a root directory.');
+    fs.mkdirSync(root, { recursive: true });
+    this.root = fs.realpathSync(root);
+  }
+
+  #resolve(vfsPath, { allowMissing = true } = {}) {
+    if (!isSafeDocumentPath(vfsPath)) throw new VfsPathError(`Unsafe VFS path '${vfsPath}'.`);
+    const target = path.resolve(this.root, ...vfsPath.split('/'));
+    if (target === this.root || !target.startsWith(`${this.root}${path.sep}`)) {
+      throw new VfsPathError(`VFS path '${vfsPath}' escapes the root.`);
+    }
+    let cursor = target;
+    while (!fs.existsSync(cursor)) {
+      const parent = path.dirname(cursor);
+      if (parent === cursor) break;
+      cursor = parent;
+    }
+    if (fs.existsSync(cursor)) {
+      const stat = fs.lstatSync(cursor);
+      if (stat.isSymbolicLink()) throw new VfsPathError(`Symlinked VFS path is forbidden: '${vfsPath}'.`);
+      const real = fs.realpathSync(cursor);
+      if (real !== this.root && !real.startsWith(`${this.root}${path.sep}`)) {
+        throw new VfsPathError(`VFS path '${vfsPath}' escapes through a filesystem alias.`);
+      }
+    }
+    if (!allowMissing && !fs.existsSync(target)) return null;
+    return target;
+  }
+
+  async read(vfsPath) {
+    const target = this.#resolve(vfsPath, { allowMissing: false });
+    if (!target) return null;
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) throw new VfsPathError(`Symlinked VFS path is forbidden: '${vfsPath}'.`);
+    if (!stat.isFile()) throw new VfsPathError(`VFS path '${vfsPath}' is not a file.`);
+    const bytes = fs.readFileSync(target);
+    const hash = bytesHash(bytes);
+    return { bytes, hash, version: hash };
+  }
+
+  async stat(vfsPath) {
+    const entry = await this.read(vfsPath);
+    return entry ? { path: vfsPath, kind: 'file', size: entry.bytes.length, hash: entry.hash, version: entry.version } : null;
+  }
+
+  async *list(prefix = '') {
+    if (prefix && !isSafeDocumentPath(prefix)) throw new VfsPathError(`Unsafe VFS prefix '${prefix}'.`);
+    const start = prefix ? this.#resolve(prefix) : this.root;
+    if (!fs.existsSync(start)) return;
+    const stack = [start];
+    while (stack.length) {
+      const dir = stack.pop();
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const absolute = path.join(dir, entry.name);
+        const relative = path.relative(this.root, absolute).split(path.sep).join('/');
+        if (entry.isSymbolicLink()) throw new VfsPathError(`Symlinked VFS entry is forbidden: '${relative}'.`);
+        if (entry.isDirectory()) stack.push(absolute);
+        else if (entry.isFile() && (!prefix || relative === prefix || relative.startsWith(`${prefix}/`))) {
+          yield await this.stat(relative);
+        }
+      }
+    }
+  }
+
+  async writeAtomic(vfsPath, bytes, precondition = {}) {
+    const target = this.#resolve(vfsPath);
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const parentReal = fs.realpathSync(path.dirname(target));
+    if (parentReal !== this.root && !parentReal.startsWith(`${this.root}${path.sep}`)) {
+      throw new VfsPathError(`VFS parent for '${vfsPath}' escapes the root.`);
+    }
+    const nextBytes = asBuffer(bytes);
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${crypto.randomUUID()}.tmp`);
+    try {
+      fs.writeFileSync(temp, nextBytes, { flag: 'wx', mode: 0o600 });
+      fs.renameSync(temp, target);
+    } finally {
+      fs.rmSync(temp, { force: true });
+    }
+    const hash = bytesHash(nextBytes);
+    return { path: vfsPath, hash, version: hash, size: nextBytes.length };
+  }
+
+  async append(vfsPath, bytes, precondition = {}) {
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    const combined = Buffer.concat([current?.bytes || Buffer.alloc(0), asBuffer(bytes)]);
+    return this.writeAtomic(vfsPath, combined, current ? { version: current.version } : { ifAbsent: true });
+  }
+
+  async remove(vfsPath, precondition = {}) {
+    const target = this.#resolve(vfsPath, { allowMissing: false });
+    const current = await this.read(vfsPath);
+    checkPrecondition(current, precondition);
+    if (!target || !current) return { path: vfsPath, removed: false };
+    fs.rmSync(target);
+    return { path: vfsPath, removed: true, previous_hash: current.hash };
+  }
+}
+
+export async function runVfsContract(vfs) {
+  const pathName = `contract/${crypto.randomUUID()}.md`;
+  const checks = [];
+  const record = (name, condition) => checks.push({ name, passed: !!condition });
+  record('missing read returns null', await vfs.read(pathName) === null);
+  const first = await vfs.writeAtomic(pathName, 'one', { ifAbsent: true });
+  record('atomic create returns version', typeof first.version === 'string');
+  const read = await vfs.read(pathName);
+  record('read preserves bytes', read?.bytes.toString() === 'one');
+  let conflict = false;
+  try { await vfs.writeAtomic(pathName, 'two', { version: 'wrong' }); } catch (error) { conflict = error instanceof VfsConflictError; }
+  record('compare-and-swap rejects stale version', conflict);
+  const appended = await vfs.append(pathName, '\ntwo', { version: first.version });
+  record('append preserves existing bytes', (await vfs.read(pathName)).bytes.toString() === 'one\ntwo');
+  await vfs.remove(pathName, { version: appended.version });
+  record('remove deletes target', await vfs.read(pathName) === null);
+  let traversal = false;
+  try { await vfs.read('../escape.md'); } catch (error) { traversal = error instanceof VfsPathError; }
+  record('traversal is rejected', traversal);
+  return { passed: checks.every((check) => check.passed), checks };
+}

package/types/kernel.d.ts

@@ -0,0 +1,48 @@
+export type SsssCommandType = 'operation' | 'patch' | 'event' | 'delete';
+
+export interface VerifiedPrincipal {
+  id: string;
+  kind: 'human' | 'agent' | 'service' | 'system';
+  workspaceIds: string[];
+  capabilities?: string[];
+  authentication: { provider: string; assurance: string; [key: string]: unknown };
+}
+
+export interface SsssCommand {
+  type: SsssCommandType;
+  workspace_id: string;
+  idempotency_key: string;
+  path: string;
+  operation_id?: string;
+  primitive_type?: string;
+  content?: string;
+  patches?: Record<string, unknown> & { __body__?: string };
+  lease_id?: string;
+  dry_run?: boolean;
+}
+
+export interface SsssResponse {
+  success: boolean;
+  type: SsssCommandType | null;
+  operation_id: string;
+  path: string;
+  committed_at: string | null;
+  dry_run: boolean;
+  replay?: boolean;
+  event_id?: string;
+  validation: { valid: boolean; type: string | null; errors: string[]; warnings: string[] };
+  repair?: { field_errors: Array<{ field: string; issue: string }> };
+}
+
+export interface SsssKernel {
+  execute(command: SsssCommand, context: { principal: VerifiedPrincipal; [key: string]: unknown }): Promise<SsssResponse>;
+  registry: unknown;
+  validator: unknown;
+}
+
+export function canonicalRequestHash(command: SsssCommand, principal: VerifiedPrincipal): string;
+export class MemoryIdempotencyStore {
+  get(workspaceId: string, idempotencyKey: string): Promise<unknown>;
+  put(workspaceId: string, idempotencyKey: string, value: unknown): Promise<void>;
+}
+export function createKernel(options: Record<string, unknown>): SsssKernel;