@reactive-skills/runtime 0.1.0

package/dist/sync/cli.js

@@ -0,0 +1,186 @@
+import path from 'node:path';
+import os from 'node:os';
+import { runSync } from './engine.js';
+function parseArgs(args) {
+    const result = {
+        targetDirs: [],
+        dryRun: false,
+        noBackup: false,
+        json: false,
+        help: false,
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        switch (arg) {
+            case '--help':
+            case '-h':
+                result.help = true;
+                break;
+            case '--dry-run':
+                result.dryRun = true;
+                break;
+            case '--force':
+                break;
+            case '--no-backup':
+                result.noBackup = true;
+                break;
+            case '--json':
+                result.json = true;
+                break;
+            case '--source':
+            case '-s':
+                if (i + 1 < args.length) {
+                    result.sourceDir = path.resolve(args[++i]);
+                }
+                break;
+            case '--target':
+            case '-t':
+                if (i + 1 < args.length) {
+                    result.targetDirs.push(path.resolve(args[++i]));
+                }
+                break;
+            case '--skill':
+                if (i + 1 < args.length) {
+                    result.targetSkill = args[++i];
+                }
+                break;
+            default:
+                if (arg.startsWith('-')) {
+                    throw new Error(`Unknown flag: ${arg}`);
+                }
+                if (!result.sourceDir) {
+                    result.sourceDir = path.resolve(arg);
+                }
+                else {
+                    result.targetDirs.push(path.resolve(arg));
+                }
+        }
+        i++;
+    }
+    return result;
+}
+function printHelp() {
+    console.log(`
+reactive-skills sync-engine: Locked mirror/PUT skill synchronization
+
+Usage:
+  reactive-skills sync-engine [source] [targets...] [flags]
+
+Arguments:
+  source                Source skills directory (default: ~/.agents/skills)
+  target                One or more target directories (default: all known satellites)
+
+Flags:
+  --source, -s <dir>    Source skills directory
+  --target, -t <dir>    Add a target directory (repeatable)
+  --skill <name>        Sync a specific skill only
+  --dry-run             Preview changes without writing
+  --mirror              Mirror mode (default, only supported mode): destination
+                        becomes identical to source distributable payload
+  --force               Accepted but no-op (mirror is the only mode)
+  --no-backup           Skip timestamped backup before overwrite
+  --json                Machine-readable JSON output
+  --help, -h            Show this help
+
+Satellites (default targets):
+  ~/.agents/skills
+  ~/.claude/skills
+  ~/.codex/skills
+  ~/.gemini/config/skills
+  ~/.pi/skills
+  ~/.kilocode/skills
+  ~/.copilot/skills
+  ~/.hermes/skills
+  ~/.crew/skills
+`);
+}
+function defaultTargets() {
+    const home = os.homedir();
+    return [
+        path.join(home, '.agents', 'skills'),
+        path.join(home, '.claude', 'skills'),
+        path.join(home, '.codex', 'skills'),
+        path.join(home, '.gemini', 'config', 'skills'),
+        path.join(home, '.pi', 'skills'),
+        path.join(home, '.kilocode', 'skills'),
+        path.join(home, '.copilot', 'skills'),
+        path.join(home, '.hermes', 'skills'),
+        path.join(home, '.crew', 'skills'),
+    ];
+}
+function formatReport(report, json) {
+    if (json) {
+        return JSON.stringify(report, null, 2);
+    }
+    const lines = [];
+    const prefix = report.dryRun ? '[dry-run] ' : '';
+    lines.push(`${prefix}Source: ${report.sourceDir}`);
+    lines.push(`${prefix}Skills: ${report.skillsFound} found, ${report.skillsValid} valid, ${report.skillsInvalid} invalid`);
+    lines.push(`${prefix}Targets: ${report.targetDirs.length}`);
+    lines.push('');
+    for (const r of report.results) {
+        const icon = r.action === 'mirrored' ? '⇄' :
+            r.action === 'unchanged' ? '=' :
+                r.action === 'skipped_invalid' ? '!' :
+                    r.action === 'backed_up' ? '~' :
+                        r.action === 'skipped_overlap' ? '⊘' : '?';
+        const detail = r.reason || r.backupPath || '';
+        lines.push(`  ${icon} ${r.skill} -> ${path.basename(r.target)} ${detail}`);
+    }
+    if (report.orphans.length > 0) {
+        lines.push('');
+        lines.push('Orphans (in dest but not source):');
+        for (const o of report.orphans) {
+            lines.push(`  ${path.basename(o.target)}: ${o.names.join(', ')}`);
+        }
+    }
+    if (report.errors.length > 0) {
+        lines.push('');
+        lines.push('Errors:');
+        for (const e of report.errors) {
+            lines.push(`  ! ${e}`);
+        }
+    }
+    lines.push('');
+    lines.push(`${report.errors.length === 0 ? 'OK' : 'ERRORS'}: ${report.results.length} results, ${report.errors.length} errors`);
+    return lines.join('\n');
+}
+export async function syncEngineCommand(args) {
+    let opts;
+    try {
+        opts = parseArgs(args);
+    }
+    catch (err) {
+        return `ERROR: ${err.message}\n\nUse --help for usage.`;
+    }
+    if (opts.help) {
+        printHelp();
+        return '';
+    }
+    const sourceDir = opts.sourceDir || path.join(os.homedir(), '.agents', 'skills');
+    const targetDirs = opts.targetDirs.length > 0 ? opts.targetDirs : defaultTargets();
+    const report = runSync({
+        sourceDir,
+        targetDirs,
+        targetSkill: opts.targetSkill,
+        dryRun: opts.dryRun,
+        backup: !opts.noBackup,
+    });
+    return formatReport(report, opts.json);
+}
+const isDirectRun = process.argv[1] &&
+    (process.argv[1].endsWith('sync/cli.js') ||
+        process.argv[1].endsWith('sync\\cli.js') ||
+        process.argv[1].endsWith('sync/cli.ts'));
+if (isDirectRun) {
+    syncEngineCommand(process.argv.slice(2))
+        .then((output) => {
+        if (output)
+            console.log(output);
+    })
+        .catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}

package/dist/sync/engine.d.ts

@@ -0,0 +1,2 @@
+import { SyncOptions, SyncReport } from './types.js';
+export declare function runSync(options: SyncOptions): SyncReport;

package/dist/sync/engine.js

@@ -0,0 +1,366 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const NEVER_SKILLS = new Set([
+    '.git', '.docs', '.reactive', '.playwright-mcp', '.backup', '.sync-backups',
+    'tests', 'scripts', 'node_modules', 'dist', 'axi',
+    '.cache', '.tmp', '.idea', '.vscode',
+]);
+const EXCLUDE_FROM_SKILL = new Set([
+    '.git', '.docs', '.reactive', '.playwright-mcp', '.backup', '.sync-backups',
+    'tests', 'scripts', 'node_modules', 'dist',
+]);
+function discoverSkills(sourceDir, targetSkill) {
+    if (!fs.existsSync(sourceDir))
+        return [];
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+    const skills = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        if (NEVER_SKILLS.has(e.name))
+            continue;
+        if (targetSkill && e.name !== targetSkill)
+            continue;
+        const dirPath = path.join(sourceDir, e.name);
+        const hasSkillMd = fs.existsSync(path.join(dirPath, 'SKILL.md')) ||
+            fs.existsSync(path.join(dirPath, 'skill.md'));
+        const hasSkillYaml = fs.existsSync(path.join(dirPath, 'skill.yaml'));
+        const isValid = hasSkillMd || hasSkillYaml;
+        skills.push({
+            name: e.name,
+            path: dirPath,
+            hasSkillMd,
+            hasSkillYaml,
+            isValid,
+        });
+    }
+    return skills;
+}
+function getDistributableFiles(skillPath) {
+    const files = [];
+    function walk(dir, rel = '') {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const e of entries) {
+            if (EXCLUDE_FROM_SKILL.has(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            const relPath = rel ? path.join(rel, e.name) : e.name;
+            if (e.isDirectory()) {
+                walk(full, relPath);
+            }
+            else if (e.isFile()) {
+                files.push(relPath);
+            }
+        }
+    }
+    walk(skillPath);
+    return files.sort();
+}
+function hashFile(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+function getFileHashes(skillPath, files) {
+    const hashes = new Map();
+    for (const f of files) {
+        hashes.set(f, hashFile(path.join(skillPath, f)));
+    }
+    return hashes;
+}
+function hasExcludedEntryAnywhere(dirPath) {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const e of entries) {
+        if (EXCLUDE_FROM_SKILL.has(e.name))
+            return true;
+        if (e.isDirectory()) {
+            const full = path.join(dirPath, e.name);
+            if (hasExcludedEntryAnywhere(full))
+                return true;
+        }
+    }
+    return false;
+}
+function getDistributableEntries(skillPath) {
+    const entries = [];
+    function walk(dir, rel = '') {
+        const subdirs = [];
+        const files = [];
+        const all = fs.readdirSync(dir, { withFileTypes: true });
+        for (const e of all) {
+            if (EXCLUDE_FROM_SKILL.has(e.name))
+                continue;
+            const relPath = rel ? path.join(rel, e.name) : e.name;
+            if (e.isDirectory()) {
+                subdirs.push({ rel: relPath, full: path.join(dir, e.name) });
+            }
+            else if (e.isFile()) {
+                files.push(relPath);
+            }
+        }
+        for (const d of subdirs.sort((a, b) => a.rel.localeCompare(b.rel))) {
+            entries.push(d.rel);
+            walk(d.full, d.rel);
+        }
+        for (const f of files.sort()) {
+            entries.push(f);
+        }
+    }
+    walk(skillPath);
+    return entries;
+}
+function directoriesEqual(srcPath, destPath) {
+    const srcEntries = getDistributableEntries(srcPath);
+    const destEntries = getDistributableEntries(destPath);
+    if (srcEntries.length !== destEntries.length)
+        return false;
+    for (let i = 0; i < srcEntries.length; i++) {
+        if (srcEntries[i] !== destEntries[i])
+            return false;
+    }
+    const srcFiles = getDistributableFiles(srcPath);
+    const destFiles = getDistributableFiles(destPath);
+    if (srcFiles.length !== destFiles.length)
+        return false;
+    for (let i = 0; i < srcFiles.length; i++) {
+        if (srcFiles[i] !== destFiles[i])
+            return false;
+    }
+    const srcHashes = getFileHashes(srcPath, srcFiles);
+    const destHashes = getFileHashes(destPath, destFiles);
+    for (const [file, hash] of srcHashes) {
+        if (destHashes.get(file) !== hash)
+            return false;
+    }
+    if (hasExcludedEntryAnywhere(destPath))
+        return false;
+    return true;
+}
+function copyToStaging(srcPath, stagingPath) {
+    const entries = fs.readdirSync(srcPath, { withFileTypes: true });
+    fs.mkdirSync(stagingPath, { recursive: true });
+    for (const e of entries) {
+        if (EXCLUDE_FROM_SKILL.has(e.name))
+            continue;
+        const s = path.join(srcPath, e.name);
+        const d = path.join(stagingPath, e.name);
+        if (e.isDirectory()) {
+            copyToStaging(s, d);
+        }
+        else if (e.isFile()) {
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+function createExternalBackup(targetDir, skillName) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const suffix = crypto.randomBytes(6).toString('hex');
+    const backupRoot = path.join(targetDir, '.sync-backups', skillName);
+    const backupPath = path.join(backupRoot, `${ts}-${suffix}`);
+    fs.mkdirSync(backupPath, { recursive: true });
+    const destSkillPath = path.join(targetDir, skillName);
+    if (fs.existsSync(destSkillPath)) {
+        const entries = fs.readdirSync(destSkillPath, { withFileTypes: true });
+        for (const e of entries) {
+            const s = path.join(destSkillPath, e.name);
+            const d = path.join(backupPath, e.name);
+            if (e.isDirectory()) {
+                fs.cpSync(s, d, { recursive: true });
+            }
+            else if (e.isFile()) {
+                fs.copyFileSync(s, d);
+            }
+        }
+    }
+    return backupPath;
+}
+function removeDirectoryRecursive(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const e of entries) {
+        const full = path.join(dirPath, e.name);
+        if (e.isDirectory()) {
+            removeDirectoryRecursive(full);
+        }
+        else {
+            fs.unlinkSync(full);
+        }
+    }
+    fs.rmdirSync(dirPath);
+}
+function atomicSwap(stagingPath, destPath) {
+    const destParent = path.dirname(destPath);
+    const destName = path.basename(destPath);
+    let oldPath;
+    try {
+        if (fs.existsSync(destPath)) {
+            oldPath = path.join(destParent, `.old-${destName}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`);
+            fs.renameSync(destPath, oldPath);
+        }
+        fs.renameSync(stagingPath, destPath);
+        if (oldPath && fs.existsSync(oldPath)) {
+            removeDirectoryRecursive(oldPath);
+            oldPath = undefined;
+        }
+    }
+    catch (err) {
+        if (oldPath && fs.existsSync(oldPath)) {
+            try {
+                fs.renameSync(oldPath, destPath);
+            }
+            catch {
+            }
+        }
+        throw err;
+    }
+}
+function pathsOverlap(sourceDir, targetDir) {
+    const absSource = path.resolve(sourceDir);
+    const absTarget = path.resolve(targetDir);
+    const source = process.platform === 'win32' ? absSource.toLowerCase() : absSource;
+    const target = process.platform === 'win32' ? absTarget.toLowerCase() : absTarget;
+    const sourceToTarget = path.relative(source, target);
+    const targetToSource = path.relative(target, source);
+    const isSameOrChild = (relative) => relative === '' ||
+        (relative !== '..' &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative));
+    return isSameOrChild(sourceToTarget) || isSameOrChild(targetToSource);
+}
+export function runSync(options) {
+    const { sourceDir, targetDirs, targetSkill, dryRun = false, backup = true, } = options;
+    const report = {
+        dryRun,
+        sourceDir,
+        targetDirs,
+        skillsFound: 0,
+        skillsValid: 0,
+        skillsInvalid: 0,
+        results: [],
+        orphans: [],
+        errors: [],
+    };
+    if (!fs.existsSync(sourceDir)) {
+        report.errors.push(`Source directory not found: ${sourceDir}`);
+        return report;
+    }
+    const skills = discoverSkills(sourceDir, targetSkill);
+    report.skillsFound = skills.length;
+    report.skillsValid = skills.filter(s => s.isValid).length;
+    report.skillsInvalid = skills.filter(s => !s.isValid).length;
+    for (const targetDir of targetDirs) {
+        if (pathsOverlap(sourceDir, targetDir)) {
+            report.errors.push(`Source and destination overlap: ${sourceDir} -> ${targetDir}`);
+            for (const skill of skills) {
+                report.results.push({
+                    skill: skill.name,
+                    target: targetDir,
+                    action: 'skipped_overlap',
+                    reason: 'Source and destination overlap; skipping to prevent data loss',
+                });
+            }
+            continue;
+        }
+        if (!dryRun) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        for (const skill of skills) {
+            const destPath = path.join(targetDir, skill.name);
+            if (!skill.isValid) {
+                report.results.push({
+                    skill: skill.name,
+                    target: targetDir,
+                    action: 'skipped_invalid',
+                    reason: 'Missing SKILL.md or skill.yaml',
+                });
+                continue;
+            }
+            const alreadyIdentical = fs.existsSync(destPath) && directoriesEqual(skill.path, destPath);
+            if (alreadyIdentical) {
+                report.results.push({
+                    skill: skill.name,
+                    target: targetDir,
+                    action: 'unchanged',
+                });
+                continue;
+            }
+            if (dryRun) {
+                report.results.push({
+                    skill: skill.name,
+                    target: targetDir,
+                    action: 'mirrored',
+                    reason: 'dry-run',
+                });
+                continue;
+            }
+            let backupPath;
+            let stagingPath;
+            try {
+                if (backup && fs.existsSync(destPath)) {
+                    backupPath = createExternalBackup(targetDir, skill.name);
+                    report.results.push({
+                        skill: skill.name,
+                        target: targetDir,
+                        action: 'backed_up',
+                        backupPath,
+                    });
+                }
+                stagingPath = path.join(targetDir, `.staging-${skill.name}-${Date.now()}`);
+                copyToStaging(skill.path, stagingPath);
+                if (!directoriesEqual(skill.path, stagingPath)) {
+                    throw new Error('Staging validation failed: payload does not match source');
+                }
+                atomicSwap(stagingPath, destPath);
+                stagingPath = undefined;
+                report.results.push({
+                    skill: skill.name,
+                    target: targetDir,
+                    action: 'mirrored',
+                    backupPath,
+                });
+            }
+            catch (err) {
+                if (stagingPath && fs.existsSync(stagingPath)) {
+                    removeDirectoryRecursive(stagingPath);
+                }
+                stagingPath = undefined;
+                // atomicSwap restores the previous destination on failure, so the
+                // destination should already be intact. If it is missing (e.g. the
+                // rename-back also failed), fall back to the external backup so the
+                // destination is never lost.
+                if (backupPath && !fs.existsSync(destPath)) {
+                    const destSkillPath = path.join(targetDir, skill.name);
+                    const entries = fs.readdirSync(backupPath, { withFileTypes: true });
+                    fs.mkdirSync(destSkillPath, { recursive: true });
+                    for (const e of entries) {
+                        const s = path.join(backupPath, e.name);
+                        const d = path.join(destSkillPath, e.name);
+                        if (e.isDirectory()) {
+                            fs.cpSync(s, d, { recursive: true });
+                        }
+                        else if (e.isFile()) {
+                            fs.copyFileSync(s, d);
+                        }
+                    }
+                }
+                report.errors.push(`Mirror failed for ${skill.name} to ${targetDir}: ${err.message}`);
+            }
+        }
+        if (fs.existsSync(targetDir)) {
+            const destEntries = fs.readdirSync(targetDir, { withFileTypes: true });
+            const destNames = destEntries
+                .filter(e => e.isDirectory() &&
+                !e.name.startsWith('.staging') &&
+                !e.name.startsWith('.old-') &&
+                e.name !== '.sync-backups')
+                .map(e => e.name);
+            const sourceNames = new Set(skills.map(s => s.name));
+            const orphans = destNames.filter(n => !sourceNames.has(n));
+            if (orphans.length > 0) {
+                report.orphans.push({ target: targetDir, names: orphans });
+            }
+        }
+    }
+    return report;
+}

package/dist/sync/types.d.ts

@@ -0,0 +1,35 @@
+export interface SkillEntry {
+    name: string;
+    path: string;
+    hasSkillMd: boolean;
+    hasSkillYaml: boolean;
+    isValid: boolean;
+}
+export interface SyncOptions {
+    sourceDir: string;
+    targetDirs: string[];
+    targetSkill?: string;
+    dryRun?: boolean;
+    backup?: boolean;
+}
+export interface SyncResult {
+    skill: string;
+    target: string;
+    action: 'mirrored' | 'unchanged' | 'skipped_invalid' | 'backed_up' | 'skipped_overlap';
+    backupPath?: string;
+    reason?: string;
+}
+export interface SyncReport {
+    dryRun: boolean;
+    sourceDir: string;
+    targetDirs: string[];
+    skillsFound: number;
+    skillsValid: number;
+    skillsInvalid: number;
+    results: SyncResult[];
+    orphans: {
+        target: string;
+        names: string[];
+    }[];
+    errors: string[];
+}

package/dist/sync/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@reactive-skills/runtime",
+  "version": "0.1.0",
+  "description": "Reactive Skills Architecture (RSA) core runtime — FSM engine, event store, guard evaluator, projection engine, MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./sync": "./dist/sync/cli.js"
+  },
+  "bin": {
+    "reactive-skills-dev": "./dist/cli/dev.js",
+    "reactive-skills-sync": "./dist/sync/cli.js",
+    "reactive-skills-mcp": "./dist/mcp/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "fsm",
+    "hsm",
+    "event-driven",
+    "event-sourcing",
+    "reactive"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Reactive-Skills/reactive-skills.git",
+    "directory": "packages/runtime"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "tslib": "^2.3.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@swc-node/register": "~1.11.1",
+    "@swc/cli": "~0.8.1",
+    "@swc/core": "~1.15.5",
+    "@swc/helpers": "~0.5.18",
+    "@types/handlebars": "^4.1.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4"
+  },
+  "bugs": {
+    "url": "https://github.com/Reactive-Skills/reactive-skills/issues"
+  },
+  "homepage": "https://github.com/Reactive-Skills/reactive-skills#readme",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --config vitest.config.ts && npm run check:docs && npm run check:prose",
+    "check:docs": "node scripts/check-docs.js",
+    "check:prose": "tsx scripts/check-prose.ts",
+    "bump:patch": "node scripts/bump-version.js patch",
+    "bump:minor": "node scripts/bump-version.js minor",
+    "bump:major": "node scripts/bump-version.js major",
+    "demo": "tsx examples/simulate-tdd.ts"
+  }
+}