scc-universal 1.1.0

package/scripts/lib/schema-validator.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * schema-validator.js — Shared AJV schema validation for SCC.
+ *
+ * - Graceful AJV import with fallback when not installed
+ * - Cached schema, AJV instance, and compiled validators
+ * - Consistent error formatting: `${instancePath || '/'} ${message}`
+ * - Entity validation against $defs-based schemas
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Graceful AJV import — fallback when not installed (bare environments)
+let Ajv = null;
+try {
+  const ajvModule = require('ajv');
+  Ajv = ajvModule.default || ajvModule;
+} catch (_error) {
+  Ajv = null;
+}
+
+// Caches
+let cachedAjv = null;
+const cachedSchemas = new Map();
+const cachedValidators = new Map();
+
+function getAjv() {
+  if (cachedAjv) return cachedAjv;
+  if (!Ajv) return null;
+  cachedAjv = new Ajv({ allErrors: true, strict: false });
+  return cachedAjv;
+}
+
+function readSchema(schemaPath) {
+  const resolved = path.resolve(schemaPath);
+  if (cachedSchemas.has(resolved)) return cachedSchemas.get(resolved);
+  const schema = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  cachedSchemas.set(resolved, schema);
+  return schema;
+}
+
+function getValidator(schemaPath) {
+  const resolved = path.resolve(schemaPath);
+  if (cachedValidators.has(resolved)) return cachedValidators.get(resolved);
+
+  const ajv = getAjv();
+  if (!ajv) return createFallbackValidator();
+
+  const schema = readSchema(resolved);
+  const validator = ajv.compile(schema);
+  cachedValidators.set(resolved, validator);
+  return validator;
+}
+
+function getEntityValidator(schemaPath, entityName) {
+  const cacheKey = `${path.resolve(schemaPath)}#${entityName}`;
+  if (cachedValidators.has(cacheKey)) return cachedValidators.get(cacheKey);
+
+  const ajv = getAjv();
+  if (!ajv) return createFallbackValidator();
+
+  const schema = readSchema(schemaPath);
+  if (!schema.$defs || !schema.$defs[entityName]) {
+    throw new Error(`Unknown schema entity: ${entityName} in ${schemaPath}`);
+  }
+
+  const entitySchema = {
+    $schema: schema.$schema,
+    ...schema.$defs[entityName],
+    $defs: schema.$defs,
+  };
+  const validator = ajv.compile(entitySchema);
+  cachedValidators.set(cacheKey, validator);
+  return validator;
+}
+
+/**
+ * Fallback validator when AJV is not installed.
+ * Returns a validator function with same interface: validate(data) → boolean, validate.errors → array.
+ */
+function createFallbackValidator() {
+  const validate = (data) => {
+    const errors = [];
+    validate.errors = errors;
+
+    if (data === null || data === undefined) {
+      errors.push({ instancePath: '/', message: 'must not be null or undefined' });
+      return false;
+    }
+    if (typeof data !== 'object' || Array.isArray(data)) {
+      errors.push({ instancePath: '/', message: 'must be object' });
+      return false;
+    }
+    return true;
+  };
+  validate.errors = [];
+  return validate;
+}
+
+/**
+ * Format AJV errors into a readable string.
+ */
+function formatErrors(errors) {
+  if (!errors || errors.length === 0) return '';
+  return errors
+    .map(e => `${e.instancePath || '/'} ${e.message}`)
+    .join('; ');
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Validate data against a JSON schema file.
+ * @param {string} schemaPath - path to JSON schema file
+ * @param {*} data - data to validate
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+function validateAgainstSchema(schemaPath, data) {
+  const validator = getValidator(schemaPath);
+  const valid = validator(data);
+  return { valid, errors: validator.errors || [] };
+}
+
+/**
+ * Validate data against a schema, throw on invalid.
+ * @param {string} schemaPath - path to JSON schema file
+ * @param {*} data - data to validate
+ * @param {string} [label] - label for error message
+ */
+function assertAgainstSchema(schemaPath, data, label) {
+  const result = validateAgainstSchema(schemaPath, data);
+  if (!result.valid) {
+    throw new Error(`Invalid${label ? ` ${label}` : ''}: ${formatErrors(result.errors)}`);
+  }
+}
+
+/**
+ * Validate data against a named entity definition ($defs) in a schema.
+ * @param {string} schemaPath - path to JSON schema file
+ * @param {string} entityName - name of the entity in $defs
+ * @param {*} data - data to validate
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+function validateEntity(schemaPath, entityName, data) {
+  const validator = getEntityValidator(schemaPath, entityName);
+  const valid = validator(data);
+  return { valid, errors: validator.errors || [] };
+}
+
+/**
+ * Validate entity against a schema, throw on invalid.
+ * @param {string} schemaPath - path to JSON schema file
+ * @param {string} entityName - name of the entity in $defs
+ * @param {*} data - data to validate
+ * @param {string} [label] - label for error message
+ */
+function assertValidEntity(schemaPath, entityName, data, label) {
+  const result = validateEntity(schemaPath, entityName, data);
+  if (!result.valid) {
+    throw new Error(`Invalid ${entityName}${label ? ` (${label})` : ''}: ${formatErrors(result.errors)}`);
+  }
+}
+
+/**
+ * Check if AJV is available.
+ */
+function hasAjv() {
+  return Ajv !== null;
+}
+
+/**
+ * Clear all caches (useful for testing).
+ */
+function clearCaches() {
+  cachedAjv = null;
+  cachedSchemas.clear();
+  cachedValidators.clear();
+}
+
+module.exports = {
+  validateAgainstSchema,
+  assertAgainstSchema,
+  validateEntity,
+  assertValidEntity,
+  formatErrors,
+  hasAjv,
+  clearCaches,
+};

package/scripts/lib/skill-adapter.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * skill-adapter.js — Transforms SCC skills from Claude Code format to Cursor format.
+ *
+ * Claude Code skills use: name, description, origin, user-invocable, allowed-tools, context, etc.
+ * Cursor skills use: name, description, disable-model-invocation, license, compatibility, metadata.
+ *
+ * This adapter strips Claude-only fields, maps user-invocable to disable-model-invocation,
+ * and outputs clean Cursor-compatible SKILL.md files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter, serializeFrontmatter, ensureDir, copyFile } = require('./utils');
+
+// Fields that Cursor recognizes in SKILL.md frontmatter
+const CURSOR_ALLOWED_FIELDS = new Set([
+  'name',
+  'description',
+  'disable-model-invocation',
+  'license',
+  'compatibility',
+  'metadata',
+]);
+
+/**
+ * Transform a single SKILL.md content string from Claude Code to Cursor format.
+ * @param {string} content - raw SKILL.md content
+ * @returns {string} - transformed SKILL.md content for Cursor
+ */
+function transformSkill(content) {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const cursorFm = {};
+
+  // Copy allowed fields
+  for (const key of Object.keys(frontmatter)) {
+    if (CURSOR_ALLOWED_FIELDS.has(key)) {
+      cursorFm[key] = frontmatter[key];
+    }
+  }
+
+  // EXample for future Map user-invocable → disable-model-invocation
+  /*if (frontmatter['user-invocable'] !== undefined) {
+    const isUserInvocable = String(frontmatter['user-invocable']).toLowerCase() === 'true';
+    if (isUserInvocable) {
+      cursorFm['disable-model-invocation'] = false;
+    }
+    // When user-invocable is false (auto-only), omit disable-model-invocation
+    // so Cursor defaults to model-can-invoke behavior
+  }*/
+
+  return serializeFrontmatter(cursorFm, body);
+}
+
+/**
+ * Transform and copy an entire skill directory.
+ * Transforms SKILL.md frontmatter; copies all other files as-is.
+ * @param {string} srcDir - source skill directory (e.g., skills/sf-help/)
+ * @param {string} destDir - destination directory (e.g., .cursor/skills/sf-help/)
+ */
+function transformSkillDir(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Source skill directory not found: ${srcDir}`);
+  }
+
+  ensureDir(destDir);
+  copyDirRecursive(srcDir, destDir);
+}
+
+/**
+ * Recursively copy a directory, transforming SKILL.md files.
+ * @param {string} src - source directory
+ * @param {string} dest - destination directory
+ */
+function copyDirRecursive(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else if (entry.name === 'SKILL.md') {
+      // Transform SKILL.md frontmatter
+      const content = fs.readFileSync(srcPath, 'utf8');
+      const transformed = transformSkill(content);
+      ensureDir(path.dirname(destPath));
+      fs.writeFileSync(destPath, transformed, 'utf8');
+    } else {
+      // Copy other files as-is
+      copyFile(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { transformSkill, transformSkillDir, CURSOR_ALLOWED_FIELDS };

package/scripts/lib/state-store.js

@@ -0,0 +1,376 @@
+'use strict';
+
+/**
+ * state-store.js — Schema-validated JSON state store for SCC.
+ *
+ * Persists to ~/.scc/state.json with 6 entity types (validated against state-store.schema.json):
+ *   - sessions:         AI session tracking
+ *   - skillRuns:        Skill execution history
+ *   - skillVersions:    Skill version tracking
+ *   - decisions:        Decision records
+ *   - installState:     Installation tracking (replaces legacy installedFiles)
+ *   - governanceEvents: Governor limit/security events
+ *
+ * Backward-compatible: saveState/loadState/clearState/removeFiles still work for existing callers.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { assertValidEntity } = require('./schema-validator');
+
+const STATE_DIR = path.join(os.homedir(), '.scc');
+const STATE_PATH = path.join(STATE_DIR, 'state.json');
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schemas', 'state-store.schema.json');
+
+// Entity collection names (must match schema properties)
+const ENTITY_COLLECTIONS = ['sessions', 'skillRuns', 'skillVersions', 'decisions', 'installState', 'governanceEvents'];
+
+function ensureStateDir() {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+}
+
+/**
+ * Create an empty state object with all entity collections.
+ */
+function emptyState() {
+  const state = {};
+  for (const col of ENTITY_COLLECTIONS) {
+    state[col] = [];
+  }
+  return state;
+}
+
+/**
+ * Load raw JSON state from disk.
+ */
+function loadJsonState() {
+  try {
+    const raw = fs.readFileSync(STATE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+
+    // Detect and migrate legacy format
+    if (parsed.installedFiles || parsed.lastProfile) {
+      return migrateLegacyState(parsed);
+    }
+
+    // Ensure all collections exist
+    const state = emptyState();
+    for (const col of ENTITY_COLLECTIONS) {
+      if (Array.isArray(parsed[col])) {
+        state[col] = parsed[col];
+      }
+    }
+    return state;
+  } catch {
+    return emptyState();
+  }
+}
+
+/**
+ * Migrate legacy state format (installedFiles/lastProfile) to entity model.
+ */
+function migrateLegacyState(legacy) {
+  const state = emptyState();
+
+  // Legacy state migration: v1.0.0 used fine-grained module IDs (rules-apex, agents-lwc, etc.)
+  // v2.0.0 uses 7 bundle IDs (core, apex, lwc, platform, devops, security, extended).
+  const LEGACY_PREFIXES = ['rules-', 'agents-', 'commands-', 'skills-', 'hooks-', 'platform-'];
+  const hasLegacyModules = (legacy.installedFiles || []).some(f =>
+    f.module && LEGACY_PREFIXES.some(prefix => f.module.startsWith(prefix))
+  );
+
+  // If legacy module IDs detected, wipe and return empty
+  if (hasLegacyModules) {
+    saveJsonState(state);
+    return state;
+  }
+
+  // Migrate installedFiles to installState entities (group by target)
+  if (Array.isArray(legacy.installedFiles) && legacy.installedFiles.length > 0) {
+    const byTarget = new Map();
+    for (const f of legacy.installedFiles) {
+      const target = f.target || legacy.lastTarget || 'claude';
+      if (!byTarget.has(target)) byTarget.set(target, []);
+      byTarget.get(target).push(f);
+    }
+    for (const [target, files] of byTarget) {
+      state.installState.push({
+        targetId: target,
+        targetRoot: process.cwd(),
+        profile: legacy.lastProfile || null,
+        modules: [],
+        operations: files.map(f => ({
+          kind: 'copy',
+          moduleId: f.module || '',
+          sourceRelativePath: f.srcPath || '',
+          destinationPath: f.destPath || '',
+          strategy: 'overwrite',
+          ownership: 'scc',
+          scaffoldOnly: false,
+          hash: f.hash || null,
+        })),
+        installedAt: legacy.lastInstalledAt || new Date().toISOString(),
+        sourceVersion: null,
+      });
+    }
+  }
+
+  // Migrate legacy sessions
+  if (Array.isArray(legacy.sessions)) {
+    for (const s of legacy.sessions) {
+      state.sessions.push({
+        id: `legacy-${s.installedAt || Date.now()}`,
+        adapterId: 'scc-install',
+        harness: s.target || 'claude',
+        state: 'completed',
+        repoRoot: null,
+        startedAt: s.installedAt || null,
+        endedAt: s.installedAt || null,
+        snapshot: { profile: s.profile, fileCount: s.fileCount },
+      });
+    }
+  }
+
+  // Write migrated state
+  saveJsonState(state);
+  return state;
+}
+
+function saveJsonState(state) {
+  ensureStateDir();
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+}
+
+// ── Entity Operations (schema-validated) ────────────────────────────────────
+
+/**
+ * Upsert an entity into a collection. Validates against schema before saving.
+ * If entity with same `id` exists, it's replaced.
+ */
+function upsertEntity(collectionName, entityName, entity) {
+  assertValidEntity(SCHEMA_PATH, entityName, entity);
+
+  const state = loadJsonState();
+  if (!Array.isArray(state[collectionName])) {
+    state[collectionName] = [];
+  }
+
+  // Replace by id if exists, otherwise append
+  const idField = entity.id ? 'id' : (entity.skillId ? 'skillId' : null);
+  if (idField && entity[idField]) {
+    const idx = state[collectionName].findIndex(e => e[idField] === entity[idField]);
+    if (idx >= 0) {
+      state[collectionName][idx] = entity;
+    } else {
+      state[collectionName].push(entity);
+    }
+  } else {
+    state[collectionName].push(entity);
+  }
+
+  saveJsonState(state);
+}
+
+function upsertSession(entity) {
+  upsertEntity('sessions', 'session', entity);
+}
+
+function upsertSkillRun(entity) {
+  upsertEntity('skillRuns', 'skillRun', entity);
+}
+
+function upsertSkillVersion(entity) {
+  upsertEntity('skillVersions', 'skillVersion', entity);
+}
+
+function upsertDecision(entity) {
+  upsertEntity('decisions', 'decision', entity);
+}
+
+function upsertGovernanceEvent(entity) {
+  upsertEntity('governanceEvents', 'governanceEvent', entity);
+}
+
+// ── Query Helpers ───────────────────────────────────────────────────────────
+
+function listSessions() {
+  return loadJsonState().sessions;
+}
+
+function listSkillRuns(sessionId) {
+  const runs = loadJsonState().skillRuns;
+  return sessionId ? runs.filter(r => r.sessionId === sessionId) : runs;
+}
+
+function listDecisions(sessionId) {
+  const decisions = loadJsonState().decisions;
+  return sessionId ? decisions.filter(d => d.sessionId === sessionId) : decisions;
+}
+
+function listGovernanceEvents(sessionId) {
+  const events = loadJsonState().governanceEvents;
+  return sessionId ? events.filter(e => e.sessionId === sessionId) : events;
+}
+
+/**
+ * Collect all operations across all installState entities into flat installedFiles format.
+ */
+function allOperations(state) {
+  const files = [];
+  for (const install of state.installState) {
+    for (const op of install.operations) {
+      files.push({
+        destPath: op.destinationPath,
+        srcPath: op.sourceRelativePath,
+        module: op.moduleId,
+        hash: op.hash || null,
+        installedAt: install.installedAt,
+        profile: install.profile,
+        target: install.targetId,
+      });
+    }
+  }
+  return files;
+}
+
+// ── Backward-Compatible API ─────────────────────────────────────────────────
+
+/**
+ * Save installation state (backward-compatible).
+ * Translates old format to installState entity.
+ */
+function saveState(state) {
+  ensureStateDir();
+  const now = state.installedAt || new Date().toISOString();
+  const current = loadJsonState();
+
+  // Create installState entity from legacy format
+  const installEntity = {
+    targetId: state.target || 'claude',
+    targetRoot: process.cwd(),
+    profile: state.profile || null,
+    modules: [],
+    operations: (state.installedFiles || []).map(f => ({
+      kind: 'copy',
+      moduleId: f.module || '',
+      sourceRelativePath: f.srcPath || '',
+      destinationPath: f.destPath || '',
+      strategy: 'overwrite',
+      ownership: 'scc',
+      scaffoldOnly: false,
+      hash: f.hash || null,
+    })),
+    installedAt: now,
+    sourceVersion: null,
+  };
+
+  // Merge operations: replace entries with same destinationPath
+  const existingInstall = current.installState[current.installState.length - 1];
+  if (existingInstall) {
+    const existingOps = new Map(existingInstall.operations.map(op => [op.destinationPath, op]));
+    for (const op of installEntity.operations) {
+      existingOps.set(op.destinationPath, op);
+    }
+    installEntity.operations = Array.from(existingOps.values());
+  }
+
+  // Replace or append installState
+  if (current.installState.length > 0) {
+    current.installState[current.installState.length - 1] = installEntity;
+  } else {
+    current.installState.push(installEntity);
+  }
+
+  // Record session
+  current.sessions.push({
+    id: `install-${now}`,
+    adapterId: 'scc-install',
+    harness: state.target || 'claude',
+    state: 'completed',
+    repoRoot: null,
+    startedAt: now,
+    endedAt: now,
+    snapshot: { profile: state.profile, fileCount: (state.installedFiles || []).length },
+  });
+
+  saveJsonState(current);
+}
+
+/**
+ * Load current installation state (backward-compatible).
+ * Returns format expected by existing callers.
+ */
+function loadState() {
+  const state = loadJsonState();
+  const latest = state.installState[state.installState.length - 1];
+
+  // Legacy module ID detection in entity format
+  const LEGACY_PREFIXES = ['rules-', 'agents-', 'commands-', 'skills-', 'hooks-', 'platform-'];
+  if (latest) {
+    const hasLegacy = latest.operations.some(op =>
+      op.moduleId && LEGACY_PREFIXES.some(prefix => op.moduleId.startsWith(prefix))
+    );
+    if (hasLegacy) {
+      clearState();
+      return { profile: null, target: null, installedAt: null, installedFiles: [], sessions: [] };
+    }
+  }
+
+  return {
+    profile: latest ? latest.profile : null,
+    target: latest ? latest.targetId : null,
+    installedAt: latest ? latest.installedAt : null,
+    installedFiles: allOperations(state),
+    sessions: state.sessions.map(s => ({
+      profile: s.snapshot?.profile || null,
+      target: s.harness,
+      fileCount: s.snapshot?.fileCount || 0,
+      installedAt: s.startedAt,
+    })),
+  };
+}
+
+/**
+ * Clear all SCC state.
+ */
+function clearState() {
+  try { fs.unlinkSync(STATE_PATH); } catch { /* ignore */ }
+  // Also clean up legacy DB file if it exists
+  const legacyDbPath = path.join(STATE_DIR, 'state.db');
+  try { fs.unlinkSync(legacyDbPath); } catch { /* ignore */ }
+}
+
+/**
+ * Remove specific files from the state store.
+ * @param {string[]} destPaths
+ */
+function removeFiles(destPaths) {
+  const state = loadJsonState();
+  const removeSet = new Set(destPaths);
+
+  for (const install of state.installState) {
+    install.operations = install.operations.filter(op => !removeSet.has(op.destinationPath));
+  }
+
+  saveJsonState(state);
+}
+
+module.exports = {
+  // Backward-compatible API
+  saveState,
+  loadState,
+  clearState,
+  removeFiles,
+  // Entity operations (schema-validated)
+  upsertSession,
+  upsertSkillRun,
+  upsertSkillVersion,
+  upsertDecision,
+  upsertGovernanceEvent,
+  // Query helpers
+  listSessions,
+  listSkillRuns,
+  listDecisions,
+  listGovernanceEvents,
+};