@gregiteen/ssss-cli 0.8.0 → 0.9.1

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;

package/docs/help/localization.md

@@ -1,43 +0,0 @@
-# Localization and translation overlays (spec §5.4, §11.9)
-
-A `translation` is a structural overlay for one exact source document. It never
-forks the source or translates symbolic control fields.
-
-```yaml
----
-type: translation
-title: "Política de reembolsos — español"
-description: "Traducción al español."
-timestamp: 2026-07-10T00:00:00Z
-translation_id: refund-policy-es
-source_path: rules/refund-policy.md
-source_hash: sha256:<hash-of-current-source-bytes>
-locale: es
-status: approved
-translated_fields: [title, description, body]
-translated_title: "Política de reembolsos"
-translated_description: "Reglas de reembolso para compradores."
----
-
-Contenido traducido.
-```
-
-Only `title`, `description`, and body may change. `type`, ids, status values,
-permissions, relations, portability, and every other control field remain canonical.
-The engine rejects stale source hashes, missing or private sources, traversal,
-symlinks, recursive translation, and changes to immutable overlay identity.
-
-Draft and reviewed overlays are retained for workflow, but normal localization uses
-approved overlays only. Use `--include-drafts` only for an explicit preview.
-
-```bash
-ssss localize ./vault --locale es --out ./derived/es
-```
-
-The output must be a new or empty, non-symlinked directory outside the source vault.
-It preserves source-relative paths, excludes private/resource-bound documents by
-default, and writes `.ssss-projection.json` so the derived result is auditable and
-rebuildable.
-
-Use `ssss semantic ./vault --locale es` to query localized surfaces without
-materializing files. See also: `ssss help semantic`.

package/scripts/cmd-localize.mjs

@@ -1,44 +0,0 @@
-/** `ssss localize` — materialize a non-destructive locale projection. */
-import path from 'node:path';
-import { materializeLocale } from '../src/semantic.mjs';
-import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
-
-const HELP = usage({
-  summary: 'Materialize approved translation overlays as a derived vault projection (spec §11.9).',
-  usage: 'ssss localize <vault-dir> --locale <tag> --out <empty-dir> [options]',
-  options: [
-    ['--locale <tag>', 'Required BCP47-style target locale.'],
-    ['--out <dir>', 'Required empty directory outside the source vault.'],
-    ['--include-private', 'Explicitly include private/resource-bound source documents.'],
-    ['--include-drafts', 'Allow non-approved translation overlays.'],
-    ['--registry <dir>', 'Registry directory (default: package registry).'],
-  ],
-  examples: [
-    'ssss localize ./vault --locale es --out ./derived/es',
-  ],
-  seeAlso: ['ssss semantic', 'ssss help localization'],
-});
-
-export async function run(argv) {
-  if (wantsHelp(argv)) { console.log(HELP); return; }
-  const { positionals, flags } = parseArgs(argv, {
-    booleans: ['include-private', 'include-drafts'],
-  });
-  const vault = positionals[0];
-  if (!vault || !flags.locale || !flags.out) die('localize requires a vault, --locale, and --out.\n\n' + HELP);
-  try {
-    const manifest = materializeLocale(
-      path.resolve(vault),
-      flags.locale,
-      path.resolve(flags.out),
-      {
-        includePrivate: !!flags['include-private'],
-        includeDrafts: !!flags['include-drafts'],
-        registryDir: flags.registry,
-      }
-    );
-    process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
-  } catch (error) {
-    die(error.message);
-  }
-}