aios-core 4.0.2 → 4.1.0

package/scripts/package-synapse.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+/**
+ * SYNAPSE Package Builder — Creates a distributable ZIP for collaborators.
+ *
+ * Usage: node scripts/package-synapse.js
+ * Output: synapse-package.zip in project root
+ *
+ * The ZIP contains all SYNAPSE files organized by category with a
+ * README-INSTALL.md tutorial for setting up SYNAPSE in a new project.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const OUT_DIR = path.join(ROOT, '.synapse-package');
+const ZIP_NAME = 'synapse-package.zip';
+
+// ── File manifest ──────────────────────────────────────────────────────────
+
+const FILES = {
+  // Core Engine
+  'core/engine.js': '.aios-core/core/synapse/engine.js',
+  'core/context/context-tracker.js': '.aios-core/core/synapse/context/context-tracker.js',
+  'core/domain/domain-loader.js': '.aios-core/core/synapse/domain/domain-loader.js',
+  'core/layers/layer-processor.js': '.aios-core/core/synapse/layers/layer-processor.js',
+  'core/layers/l0-constitution.js': '.aios-core/core/synapse/layers/l0-constitution.js',
+  'core/layers/l1-global.js': '.aios-core/core/synapse/layers/l1-global.js',
+  'core/layers/l2-agent.js': '.aios-core/core/synapse/layers/l2-agent.js',
+  'core/layers/l3-workflow.js': '.aios-core/core/synapse/layers/l3-workflow.js',
+  'core/layers/l4-task.js': '.aios-core/core/synapse/layers/l4-task.js',
+  'core/layers/l5-squad.js': '.aios-core/core/synapse/layers/l5-squad.js',
+  'core/layers/l6-keyword.js': '.aios-core/core/synapse/layers/l6-keyword.js',
+  'core/layers/l7-star-command.js': '.aios-core/core/synapse/layers/l7-star-command.js',
+  'core/memory/memory-bridge.js': '.aios-core/core/synapse/memory/memory-bridge.js',
+  'core/output/formatter.js': '.aios-core/core/synapse/output/formatter.js',
+  'core/session/session-manager.js': '.aios-core/core/synapse/session/session-manager.js',
+  'core/scripts/generate-constitution.js': '.aios-core/core/synapse/scripts/generate-constitution.js',
+  'core/utils/paths.js': '.aios-core/core/synapse/utils/paths.js',
+  'core/utils/tokens.js': '.aios-core/core/synapse/utils/tokens.js',
+
+  // Diagnostics
+  'core/diagnostics/synapse-diagnostics.js': '.aios-core/core/synapse/diagnostics/synapse-diagnostics.js',
+  'core/diagnostics/report-formatter.js': '.aios-core/core/synapse/diagnostics/report-formatter.js',
+  'core/diagnostics/collectors/safe-read-json.js': '.aios-core/core/synapse/diagnostics/collectors/safe-read-json.js',
+  'core/diagnostics/collectors/hook-collector.js': '.aios-core/core/synapse/diagnostics/collectors/hook-collector.js',
+  'core/diagnostics/collectors/session-collector.js': '.aios-core/core/synapse/diagnostics/collectors/session-collector.js',
+  'core/diagnostics/collectors/manifest-collector.js': '.aios-core/core/synapse/diagnostics/collectors/manifest-collector.js',
+  'core/diagnostics/collectors/pipeline-collector.js': '.aios-core/core/synapse/diagnostics/collectors/pipeline-collector.js',
+  'core/diagnostics/collectors/uap-collector.js': '.aios-core/core/synapse/diagnostics/collectors/uap-collector.js',
+  'core/diagnostics/collectors/timing-collector.js': '.aios-core/core/synapse/diagnostics/collectors/timing-collector.js',
+  'core/diagnostics/collectors/quality-collector.js': '.aios-core/core/synapse/diagnostics/collectors/quality-collector.js',
+  'core/diagnostics/collectors/consistency-collector.js': '.aios-core/core/synapse/diagnostics/collectors/consistency-collector.js',
+  'core/diagnostics/collectors/output-analyzer.js': '.aios-core/core/synapse/diagnostics/collectors/output-analyzer.js',
+  'core/diagnostics/collectors/relevance-matrix.js': '.aios-core/core/synapse/diagnostics/collectors/relevance-matrix.js',
+
+  // Hook Entry Point
+  'hook/synapse-engine.js': '.claude/hooks/synapse-engine.js',
+
+  // Commands
+  'commands/manager.md': '.claude/commands/synapse/manager.md',
+  'commands/tasks/add-rule.md': '.claude/commands/synapse/tasks/add-rule.md',
+  'commands/tasks/create-command.md': '.claude/commands/synapse/tasks/create-command.md',
+  'commands/tasks/create-domain.md': '.claude/commands/synapse/tasks/create-domain.md',
+  'commands/tasks/diagnose-synapse.md': '.claude/commands/synapse/tasks/diagnose-synapse.md',
+  'commands/tasks/edit-rule.md': '.claude/commands/synapse/tasks/edit-rule.md',
+  'commands/tasks/suggest-domain.md': '.claude/commands/synapse/tasks/suggest-domain.md',
+  'commands/tasks/toggle-domain.md': '.claude/commands/synapse/tasks/toggle-domain.md',
+  'commands/templates/domain-template': '.claude/commands/synapse/templates/domain-template',
+  'commands/templates/manifest-entry-template': '.claude/commands/synapse/templates/manifest-entry-template',
+  'commands/utils/manifest-parser-reference.md': '.claude/commands/synapse/utils/manifest-parser-reference.md',
+
+  // Skills
+  'skills/SKILL.md': '.claude/skills/synapse/SKILL.md',
+  'skills/references/brackets.md': '.claude/skills/synapse/references/brackets.md',
+  'skills/references/commands.md': '.claude/skills/synapse/references/commands.md',
+  'skills/references/domains.md': '.claude/skills/synapse/references/domains.md',
+  'skills/references/layers.md': '.claude/skills/synapse/references/layers.md',
+  'skills/references/manifest.md': '.claude/skills/synapse/references/manifest.md',
+  'skills/assets/README.md': '.claude/skills/synapse/assets/README.md',
+
+  // Documentation
+  'docs/SYNAPSE-FLOWCHARTS.md': 'docs/architecture/SYNAPSE/SYNAPSE-FLOWCHARTS.md',
+  'docs/DESIGN-SYNAPSE-ENGINE.md': 'docs/architecture/SYNAPSE/docs/DESIGN-SYNAPSE-ENGINE.md',
+};
+
+// Runtime domain files to copy from .synapse/
+const RUNTIME_DOMAINS = [
+  'manifest', 'constitution', 'global', 'context', 'commands',
+  'agent-dev', 'agent-qa', 'agent-architect', 'agent-pm', 'agent-po',
+  'agent-sm', 'agent-devops', 'agent-analyst', 'agent-data-engineer',
+  'agent-ux', 'agent-aios-master', 'agent-squad-creator',
+  'workflow-story-dev', 'workflow-epic-create', 'workflow-arch-review',
+];
+
+// ── Build ──────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log('Building SYNAPSE package...\n');
+
+  // Clean
+  if (fs.existsSync(OUT_DIR)) fs.rmSync(OUT_DIR, { recursive: true });
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+
+  // Copy files
+  let copied = 0;
+  let missing = 0;
+  for (const [dest, src] of Object.entries(FILES)) {
+    const srcPath = path.join(ROOT, src);
+    const destPath = path.join(OUT_DIR, dest);
+    if (!fs.existsSync(srcPath)) {
+      console.warn(`  SKIP (missing): ${src}`);
+      missing++;
+      continue;
+    }
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.copyFileSync(srcPath, destPath);
+    copied++;
+  }
+
+  // Copy runtime domains
+  const runtimeDir = path.join(OUT_DIR, 'runtime');
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  for (const domain of RUNTIME_DOMAINS) {
+    const srcPath = path.join(ROOT, '.synapse', domain);
+    if (fs.existsSync(srcPath)) {
+      fs.copyFileSync(srcPath, path.join(runtimeDir, domain));
+      copied++;
+    } else {
+      console.warn(`  SKIP (runtime): .synapse/${domain}`);
+      missing++;
+    }
+  }
+
+  // Copy tests
+  const testsDir = path.join(OUT_DIR, 'tests');
+  copyDirRecursive(path.join(ROOT, 'tests', 'synapse'), testsDir);
+
+  // Generate README-INSTALL.md
+  generateReadme(OUT_DIR);
+
+  console.log(`\nCopied: ${copied} files | Missing: ${missing} files`);
+
+  // Create ZIP
+  const zipPath = path.join(ROOT, ZIP_NAME);
+  if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
+
+  try {
+    // Use PowerShell Compress-Archive on Windows
+    execSync(
+      `powershell -Command "Compress-Archive -Path '${OUT_DIR}\\*' -DestinationPath '${zipPath}' -Force"`,
+      { stdio: 'inherit' },
+    );
+    console.log(`\nZIP created: ${ZIP_NAME}`);
+    console.log(`Size: ${(fs.statSync(zipPath).size / 1024).toFixed(1)} KB`);
+  } catch (err) {
+    console.error('Failed to create ZIP:', err.message);
+    console.log(`Package directory still available at: ${OUT_DIR}`);
+  }
+
+  // Cleanup temp dir
+  if (fs.existsSync(zipPath) && fs.existsSync(OUT_DIR)) {
+    fs.rmSync(OUT_DIR, { recursive: true });
+  }
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function generateReadme(outDir) {
+  const content = `# SYNAPSE Context Engine — Installation Guide
+
+## What is SYNAPSE?
+
+SYNAPSE (Synkra Adaptive Processing & State Engine) is the JIT context injection
+engine for AIOS. On every user prompt, it injects \`<synapse-rules>\` with adaptive
+contextual rules through an 8-layer pipeline.
+
+## Prerequisites
+
+- **Node.js** 18+
+- **Claude Code** CLI with hook support
+- **AIOS Core** installed (\`npx aios-core install\`)
+
+## Quick Install
+
+### 1. Copy Core Engine
+
+Copy the \`core/\` directory to your project:
+
+\`\`\`
+cp -r core/ <your-project>/.aios-core/core/synapse/
+\`\`\`
+
+### 2. Copy Hook Entry Point
+
+\`\`\`
+cp hook/synapse-engine.js <your-project>/.claude/hooks/
+\`\`\`
+
+### 3. Register the Hook
+
+Add to \`.claude/settings.local.json\`:
+
+\`\`\`json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "node .claude/hooks/synapse-engine.js"
+      }
+    ]
+  }
+}
+\`\`\`
+
+### 4. Copy Runtime Domains
+
+\`\`\`
+cp -r runtime/ <your-project>/.synapse/
+mkdir -p <your-project>/.synapse/sessions
+mkdir -p <your-project>/.synapse/metrics
+mkdir -p <your-project>/.synapse/cache
+\`\`\`
+
+### 5. Copy Commands & Skills (Optional)
+
+\`\`\`
+cp -r commands/ <your-project>/.claude/commands/synapse/
+cp -r skills/ <your-project>/.claude/skills/synapse/
+\`\`\`
+
+### 6. Update .gitignore
+
+Add these lines:
+
+\`\`\`
+.synapse/sessions/
+.synapse/metrics/
+.synapse/cache/
+!.claude/hooks/synapse-engine.js
+\`\`\`
+
+## Verification
+
+After installation, activate any agent and run:
+
+\`\`\`
+/synapse:tasks:diagnose-synapse
+\`\`\`
+
+Expected: All checks PASS, Context Quality grade B or higher.
+
+## Architecture
+
+See \`docs/SYNAPSE-FLOWCHARTS.md\` for complete visual architecture including:
+- 8-layer pipeline flow
+- Context brackets (FRESH/MODERATE/DEPLETED/CRITICAL)
+- Domain system
+- Session management
+- Diagnostics pipeline (10 collectors)
+- Metrics persistence
+
+## Tests
+
+Copy \`tests/\` to your project and run:
+
+\`\`\`bash
+npx jest synapse
+\`\`\`
+
+Expected: 749+ tests passing.
+
+## File Structure
+
+\`\`\`
+synapse-package/
+├── README-INSTALL.md          # This file
+├── core/                      # Engine source (.aios-core/core/synapse/)
+│   ├── engine.js              # Main orchestrator
+│   ├── context/               # Bracket tracker
+│   ├── domain/                # Manifest + domain loader
+│   ├── layers/                # L0-L7 layer processors
+│   ├── memory/                # MIS bridge (Pro)
+│   ├── output/                # XML formatter
+│   ├── session/               # Session manager
+│   ├── diagnostics/           # Observability (10 collectors)
+│   ├── scripts/               # Constitution generator
+│   └── utils/                 # Path + token helpers
+├── hook/                      # .claude/hooks/synapse-engine.js
+├── commands/                  # .claude/commands/synapse/
+├── skills/                    # .claude/skills/synapse/
+├── runtime/                   # .synapse/ domain files (manifest, domains)
+├── docs/                      # Architecture documentation
+└── tests/                     # Full test suite (749+ tests)
+\`\`\`
+
+---
+
+*SYNAPSE Context Engine v2.0 — Synkra AIOS*
+*Generated: ${new Date().toISOString().split('T')[0]}*
+`;
+
+  fs.writeFileSync(path.join(outDir, 'README-INSTALL.md'), content, 'utf8');
+}
+
+main();

package/scripts/validate-package-completeness.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * Validate Package Completeness for npm Publishing
+ *
+ * Ensures the npm tarball contains all critical files and excludes
+ * private content before publishing. Runs as prepublishOnly hook.
+ *
+ * @script scripts/validate-package-completeness.js
+ * @story INS-2 - Release Pipeline: Preview to Latest
+ *
+ * Usage:
+ *   node scripts/validate-package-completeness.js
+ *   node scripts/validate-package-completeness.js --verbose
+ *
+ * Exit codes:
+ *   0 - Package is complete and safe to publish
+ *   1 - Validation failed (missing files, leaked content, or config issues)
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const VERBOSE = process.argv.includes('--verbose') || process.env.VERBOSE === 'true';
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+/**
+ * Files/directories that MUST be present in the tarball.
+ * Paths are relative to package root, checked as prefixes against tarball entries.
+ */
+const REQUIRED_PATHS = [
+  // Hooks (critical - these were missing in v4.0.0)
+  '.claude/hooks/synapse-engine.js',
+  '.claude/hooks/precompact-session-digest.js',
+  // Rules
+  '.claude/rules/',
+  // CLI binaries
+  'bin/aios.js',
+  'bin/aios-minimal.js',
+  // Core framework
+  '.aios-core/core-config.yaml',
+  '.aios-core/constitution.md',
+  '.aios-core/development/agents/',
+  '.aios-core/development/tasks/',
+];
+
+/**
+ * Paths that MUST NOT appear in the tarball (leak prevention).
+ */
+const EXCLUDED_PATHS = [
+  'pro/',
+  '.env',
+  '.git/',
+  'node_modules/',
+  '.aios/',
+  'tests/',
+];
+
+/**
+ * Entries required in package.json "files" array.
+ */
+const REQUIRED_FILES_ENTRIES = [
+  '.claude/hooks/',
+  '.claude/rules/',
+  '.aios-core/',
+  'bin/',
+];
+
+/**
+ * Bin entries that must point to existing files.
+ */
+const REQUIRED_BIN_ENTRIES = ['aios', 'aios-core'];
+
+/**
+ * Runtime dependencies that must be present.
+ */
+const REQUIRED_DEPENDENCIES = ['js-yaml', 'execa', 'chalk', 'commander', 'fs-extra'];
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+let totalChecks = 0;
+let passedChecks = 0;
+let failedChecks = 0;
+const failures = [];
+
+function log(msg) {
+  console.log(msg);
+}
+
+function verbose(msg) {
+  if (VERBOSE) {
+    console.log(`  [verbose] ${msg}`);
+  }
+}
+
+function check(description, passed, detail) {
+  totalChecks++;
+  if (passed) {
+    passedChecks++;
+    log(`  PASS  ${description}`);
+  } else {
+    failedChecks++;
+    const msg = detail ? `${description} -- ${detail}` : description;
+    failures.push(msg);
+    log(`  FAIL  ${description}`);
+    if (detail) {
+      log(`         ${detail}`);
+    }
+  }
+}
+
+function getTarballContents() {
+  try {
+    const output = execSync('npm pack --dry-run --json 2>&1', {
+      cwd: ROOT,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+
+    // npm pack --json outputs a JSON array
+    const parsed = JSON.parse(output);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+      throw new Error('npm pack --json returned empty result');
+    }
+
+    const files = parsed[0].files || [];
+    return files.map((f) => f.path);
+  } catch (parseError) {
+    // Fallback: parse text output from npm pack --dry-run
+    verbose(`JSON parse failed, falling back to text output: ${parseError.message}`);
+    try {
+      const output = execSync('npm pack --dry-run 2>&1', {
+        cwd: ROOT,
+        encoding: 'utf8',
+        timeout: 30000,
+      });
+
+      // Text output has lines like "npm notice 1.2kB .claude/hooks/synapse-engine.js"
+      const lines = output.split('\n');
+      return lines
+        .filter((line) => line.includes('npm notice') && !line.includes('=== Tarball'))
+        .map((line) => {
+          // Extract file path (last token after size)
+          const match = line.match(/npm notice\s+[\d.]+[kMG]?B?\s+(.+)/);
+          return match ? match[1].trim() : null;
+        })
+        .filter(Boolean);
+    } catch (fallbackError) {
+      log(`  FAIL  Could not run npm pack: ${fallbackError.message}`);
+      return null;
+    }
+  }
+}
+
+function loadPackageJson() {
+  const pkgPath = path.join(ROOT, 'package.json');
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+}
+
+// ─── Validation Phases ──────────────────────────────────────────────────────
+
+function validateTarballContents(tarballFiles) {
+  log('\n--- Phase 1: Tarball Contents ---\n');
+
+  if (!tarballFiles) {
+    check('npm pack --dry-run executed', false, 'Failed to get tarball contents');
+    return;
+  }
+
+  verbose(`Tarball contains ${tarballFiles.length} files`);
+
+  // Check required paths exist
+  for (const required of REQUIRED_PATHS) {
+    const isDir = required.endsWith('/');
+    let found;
+
+    if (isDir) {
+      found = tarballFiles.some((f) => f.startsWith(required) || f.startsWith(`package/${required}`));
+    } else {
+      found = tarballFiles.some((f) => f === required || f === `package/${required}`);
+    }
+
+    check(
+      `Required: ${required}`,
+      found,
+      found ? undefined : `Not found in tarball (${tarballFiles.length} files scanned)`
+    );
+  }
+
+  // Check excluded paths do NOT exist
+  for (const excluded of EXCLUDED_PATHS) {
+    const leaked = tarballFiles.filter(
+      (f) => f.startsWith(excluded) || f.startsWith(`package/${excluded}`)
+    );
+
+    check(
+      `Excluded: ${excluded} not in tarball`,
+      leaked.length === 0,
+      leaked.length > 0 ? `LEAK DETECTED: ${leaked.slice(0, 3).join(', ')}` : undefined
+    );
+  }
+}
+
+function validatePackageJson(pkg) {
+  log('\n--- Phase 2: package.json Validation ---\n');
+
+  // Check "files" array includes required entries
+  const filesArray = pkg.files || [];
+
+  for (const entry of REQUIRED_FILES_ENTRIES) {
+    const found = filesArray.some((f) => f === entry || f.startsWith(entry));
+    check(
+      `files[] includes "${entry}"`,
+      found,
+      found ? undefined : `Add "${entry}" to package.json "files" array`
+    );
+  }
+
+  // Check bin entries point to existing files
+  const binEntries = pkg.bin || {};
+  for (const name of REQUIRED_BIN_ENTRIES) {
+    const binPath = binEntries[name];
+    if (!binPath) {
+      check(`bin.${name} defined`, false, `Missing bin entry for "${name}"`);
+      continue;
+    }
+
+    const fullPath = path.join(ROOT, binPath);
+    const exists = fs.existsSync(fullPath);
+    check(
+      `bin.${name} -> ${binPath} exists`,
+      exists,
+      exists ? undefined : `File not found: ${fullPath}`
+    );
+  }
+
+  // Check runtime dependencies
+  const deps = pkg.dependencies || {};
+  for (const dep of REQUIRED_DEPENDENCIES) {
+    check(
+      `dependency: ${dep}`,
+      dep in deps,
+      dep in deps ? undefined : `Missing runtime dependency "${dep}"`
+    );
+  }
+}
+
+function validateBinScripts() {
+  log('\n--- Phase 3: Bin Script Validation ---\n');
+
+  const pkg = loadPackageJson();
+  const binEntries = pkg.bin || {};
+
+  for (const [name, binPath] of Object.entries(binEntries)) {
+    const fullPath = path.join(ROOT, binPath);
+    if (!fs.existsSync(fullPath)) {
+      verbose(`Skipping shebang check for missing file: ${binPath}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const firstLine = content.split('\n')[0];
+    const hasShebang = firstLine.startsWith('#!/usr/bin/env node');
+
+    check(
+      `${name} (${binPath}) has correct shebang`,
+      hasShebang,
+      hasShebang ? undefined : `Expected "#!/usr/bin/env node", got "${firstLine.substring(0, 40)}"`
+    );
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  log('='.repeat(60));
+  log('AIOS-Core Package Completeness Validation');
+  log('='.repeat(60));
+
+  const pkg = loadPackageJson();
+  log(`\nPackage: ${pkg.name}@${pkg.version}`);
+
+  // Phase 1: Tarball contents
+  const tarballFiles = getTarballContents();
+  validateTarballContents(tarballFiles);
+
+  // Phase 2: package.json
+  validatePackageJson(pkg);
+
+  // Phase 3: Bin scripts
+  validateBinScripts();
+
+  // Summary
+  log('\n' + '='.repeat(60));
+  log(`Results: ${passedChecks}/${totalChecks} passed, ${failedChecks} failed`);
+
+  if (failures.length > 0) {
+    log('\nFailures:');
+    for (const f of failures) {
+      log(`  - ${f}`);
+    }
+    log('\n' + '='.repeat(60));
+    log('BLOCKED: Package is NOT safe to publish.');
+    log('Fix the issues above before running npm publish.');
+    log('='.repeat(60));
+    process.exit(1);
+  }
+
+  log('\n' + '='.repeat(60));
+  log('PASSED: Package is complete and safe to publish.');
+  log('='.repeat(60));
+  process.exit(0);
+}
+
+main();