sinapse-ai 1.12.2 → 1.14.0

package/docs/guides/grounding-setup.md

@@ -1,154 +0,0 @@
-# Grounding Setup Guide
-
-> Story 10.47 — opt-in BYO (Bring Your Own) vault, design system, brand.
-
-## What is grounding?
-
-Most agent frameworks assume the LLM already knows everything about your
-business. SINAPSE-AI assumes the opposite: it ships three optional
-**grounding** channels that connect agents to your real context.
-
-| Channel | Purpose | Disabled = |
-|---------|---------|------------|
-| **Vault** | Inject context from your markdown notes vault into agent prompts | Hook is a no-op |
-| **Design System** | Resolve tokens / components / layouts from your DS source-of-truth so agents stop generating generic `max-w-7xl shadcn-default` UIs | Hook is a no-op (high-quality fallback principles still apply at the framework level) |
-| **Brand** | Read your brandbook (positioning, MVV, tone-of-voice) so copy and UX nasce aligned to your brand | Hook is a no-op |
-
-All three are independent. Configure the ones that matter, skip the rest.
-
-## When does each one make sense?
-
-- **Enable vault grounding** if you keep a structured markdown knowledge base with notes about your projects, clients, decisions, or domain. Agents reference these instead of inventing.
-- **Enable design system grounding** if your project has a defined visual identity (tokens, components, layout primitives). Without it, design agents fall back to generic principles — still good, but not yours.
-- **Enable brand grounding** if you have a brandbook with positioning, MVV, tone-of-voice. Especially valuable for copy + storytelling squads.
-- **Skip all three** if you're prototyping or evaluating. The framework defaults are high-quality enough to ship; you can come back later via `--reconfigure`.
-
-## How to configure
-
-### Option A — interactive wizard (recommended)
-
-```bash
-npx sinapse-ai install            # first run, prompts every section
-npx sinapse-ai install --reconfigure   # re-run prompts on an existing install
-```
-
-The wizard asks one question per section. Each accepts a path or empty
-(skip). Empty answers leave the section disabled and the corresponding
-shipped hook stays a complete no-op.
-
-### Option B — manual edit
-
-The wizard writes to `~/.claude/sinapse-ai-config.yaml`. You can create or
-edit this file directly using the schema below.
-
-```yaml
-version: "1"
-grounding:
-  vault:
-    enabled: true
-    path: "/absolute/path/to/your/vault"
-    domains: []           # optional: list of domain tags to filter on
-  designSystem:
-    enabled: true
-    profileName: "my-product-ds"
-    rootPath: "/absolute/path/to/your/design-system"
-  brand:
-    enabled: false
-    profileName: ""
-    brandbookPath: ""
-```
-
-Generic JSON examples for copy-paste reference live in
-`packages/installer/templates/`:
-
-- `vault-routing.example.json`
-- `ds-routing.example.json`
-- `brand-routing.example.json`
-
-## How fallback works
-
-When a section is disabled (or the YAML file is absent altogether), the
-shipped grounding hook for that section returns `null`. Agents proceed
-without that channel of context. There are **no warnings, no errors, no
-log noise** — only silence.
-
-Design system grounding has an additional safety net: even with the hook
-disabled, the framework's design-system rules still apply
-high-quality fallback principles (no hardcoded `max-w-7xl`, fluid
-typography, semantic tokens) so generated UIs do not collapse into
-generic SaaS templates.
-
-## Schema versioning
-
-The top-level `version` field allows future migrations. Always check
-`~/.claude/sinapse-ai-config.yaml` after a major SINAPSE-AI upgrade. If
-the schema bumps, the installer will migrate it on the next run; manual
-edits should preserve unknown keys.
-
-## Privacy
-
-Paths configured here stay local on your machine. SINAPSE-AI does not
-ship vault contents anywhere. The grounding hooks read locally and
-inject only what the agent's working context requires for the task at
-hand.
-
-## How the hooks work (Story GA-1.6)
-
-After running `sinapse-ai install` (or `update`), three executable hooks
-are placed in `~/.sinapse/hooks/` and registered in
-`~/.claude/settings.json` under `UserPromptSubmit`:
-
-| Hook | Reads from config | Activates when | Injects |
-|------|-------------------|---------------|---------|
-| `sinapse-vault-grounding.cjs` | `grounding.vault` | Any prompt ≥ 10 chars | `<vault-grounding>` with up to 5 most-recent vault notes (500 chars each, 6000 total cap) |
-| `sinapse-ds-grounding.cjs` | `grounding.designSystem` | Prompt contains UI keywords (PT + EN: `pagina`, `componente`, `layout`, `react`, `tailwind`, etc.) | `<ds-grounding>` with the first 3000 chars of the DS law file (`0.0-guidelines.md`, `principles.md`, `README.md`, …) |
-| `sinapse-brand-grounding.cjs` | `grounding.brand` | Any prompt ≥ 10 chars | `<brand-grounding>` with the first 2000 chars of the brandbook |
-
-All three follow the same contract:
-
-- **Fail-open** — any error (missing config, malformed YAML, unreadable
-  file, timeout) exits 0 silently. Claude Code never sees a broken
-  prompt because grounding misfired.
-- **Anti-double-injection** — if the prompt already contains the
-  matching tag (e.g. another tool or a previous hook ran), the hook is
-  a no-op.
-- **Timeout 3500 ms** — each hook short-circuits on its own timer so a
-  slow filesystem can't stall agent activation.
-- **Size caps** — vault 6000 / DS 3000 / brand 2000 chars. Truncated
-  with a `[...truncated...]` marker.
-
-### Coexistence with personal hooks
-
-If you also maintain personal global hooks (e.g.
-`~/.claude/hooks/vault-grounding.cjs` reading from
-`~/.claude/vault-routing.json`), the framework hooks are
-**file-name-prefixed** with `sinapse-` and **read a different config
-file** (`~/.claude/sinapse-ai-config.yaml`). Both can run side-by-side
-without conflict — the fail-open guarantee makes any duplication
-harmless.
-
-### Disabling temporarily
-
-Open `~/.claude/sinapse-ai-config.yaml` and set the section's
-`enabled: false`. Re-running `sinapse-ai install --reconfigure` lets you
-update paths interactively.
-
-## What grounding does NOT do (today)
-
-Story `10.47` shipped the **foundation** (schema, wizard, no-op library
-hooks). Story `GA-1.6` (this entry) ships **executable hooks** that
-inject real context. The concrete domain integration logic — parsing
-note frontmatter, walking a deep DS token tree, reading a
-brandbook PDF — still lands in follow-up stories per channel.
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| "Vault grounding configured" message but no notes injected | Concrete parser not yet shipped (out-of-scope for 10.47) | Wait for follow-up story, or open an issue if blocking |
-| Hook errors during agent run | Should not happen — hooks short-circuit on any error | Check `~/.claude/sinapse-ai-config.yaml` is valid YAML; report issue if persistent |
-| Wizard does not re-ask grounding questions | Upsert mode — already configured | Run with `--reconfigure` to re-prompt |
-
----
-
-*See also:* [`README.md`](../../README.md), [`packages/installer/templates/README.md`](../../packages/installer/templates/README.md).

package/packages/installer/src/pro/pro-scaffolder.js

@@ -1,449 +0,0 @@
-/**
- * Pro Content Scaffolder
- *
- * Copies premium content (squads, configs, feature registry) from
- * node_modules/@sinapse-fullstack/pro/ into the user's project after
- * license activation.
- *
- * @module packages/installer/src/pro/pro-scaffolder
- * @story INS-3.1 — Implement Pro Content Scaffolder
- */
-
-'use strict';
-
-const fs = require('fs-extra');
-const path = require('path');
-const yaml = require('js-yaml');
-const { hashFileAsync, hashFilesMatchAsync } = require('../installer/file-hasher');
-
-/**
- * Directories excluded from scaffolding (private/internal squads).
- */
-const SCAFFOLD_EXCLUDES = [
-  'mmos-squad',
-];
-
-/**
- * Items to scaffold from pro package into user project.
- * Each entry defines source (relative to proSourceDir) and dest (relative to targetDir).
- */
-const SCAFFOLD_ITEMS = [
-  {
-    type: 'directory',
-    source: 'squads',
-    dest: 'squads',
-    description: 'Pro squads',
-    required: true,
-  },
-  {
-    type: 'file',
-    source: 'pro-config.yaml',
-    dest: path.join('.sinapse-ai', 'pro-config.yaml'),
-    description: 'Pro configuration',
-    required: true,
-  },
-  {
-    type: 'file',
-    source: 'feature-registry.yaml',
-    dest: path.join('.sinapse-ai', 'feature-registry.yaml'),
-    description: 'Feature registry',
-    required: false,
-  },
-];
-
-/**
- * Scaffold pro content into user project.
- *
- * @param {string} targetDir - Project root directory
- * @param {string} proSourceDir - Path to pro package content (node_modules/@sinapse-fullstack/pro)
- * @param {Object} [options={}] - Scaffold options
- * @param {Function} [options.onProgress] - Progress callback ({item, status, message})
- * @param {boolean} [options.force=false] - Force overwrite even if content exists
- * @returns {Promise<Object>} Scaffold result with copiedFiles, warnings, manifest
- */
-async function scaffoldProContent(targetDir, proSourceDir, options = {}) {
-  const { onProgress = null, force = false } = options;
-
-  const result = {
-    success: false,
-    copiedFiles: [],
-    skippedFiles: [],
-    warnings: [],
-    errors: [],
-    manifest: null,
-    versionInfo: null,
-  };
-
-  // Track files for rollback on partial failure
-  const rollbackFiles = [];
-
-  // Validate pro source exists
-  if (!await fs.pathExists(proSourceDir)) {
-    result.errors.push(
-      `Pro package not found at ${proSourceDir}. Run "npm install @sinapse-fullstack/pro" first.`,
-    );
-    return result;
-  }
-
-  try {
-    for (const item of SCAFFOLD_ITEMS) {
-      const sourcePath = path.join(proSourceDir, item.source);
-      const destPath = path.join(targetDir, item.dest);
-
-      // Check source exists
-      if (!await fs.pathExists(sourcePath)) {
-        if (item.required) {
-          throw new Error(`Required pro content not found: ${item.source}`);
-        }
-        const warning = `${item.description} (${item.source}) not found in pro package — skipping`;
-        result.warnings.push(warning);
-        if (onProgress) {
-          onProgress({ item: item.source, status: 'warning', message: warning });
-        }
-        continue;
-      }
-
-      if (item.type === 'directory') {
-        const copied = await scaffoldDirectory(sourcePath, destPath, { force, rollbackFiles, baseDir: targetDir });
-        result.copiedFiles.push(...copied.copiedFiles);
-        result.skippedFiles.push(...copied.skippedFiles);
-      } else {
-        const copied = await scaffoldFile(sourcePath, destPath, { force, rollbackFiles, baseDir: targetDir });
-        if (copied.skipped) {
-          result.skippedFiles.push(copied.relativePath);
-        } else {
-          result.copiedFiles.push(copied.relativePath);
-        }
-      }
-
-      if (onProgress) {
-        onProgress({ item: item.source, status: 'done', message: `${item.description} scaffolded` });
-      }
-    }
-
-    // Merge pro-config into core-config
-    const merged = await mergeProConfig(targetDir);
-    if (merged && onProgress) {
-      onProgress({ item: 'pro-config', status: 'done', message: 'Pro config merged into core-config.yaml' });
-    }
-
-    // Install squad agent commands to IDEs
-    const commandsResult = await installSquadCommands(targetDir);
-    if (commandsResult.installed > 0) {
-      result.copiedFiles.push(...commandsResult.files);
-      if (onProgress) {
-        onProgress({ item: 'squad-setup', status: 'done',
-          message: `${commandsResult.installed} squad agent commands installed` });
-      }
-    }
-
-    // Generate pro-version.json (AC4)
-    const versionInfo = await generateProVersionJson(targetDir, proSourceDir, result.copiedFiles);
-    result.versionInfo = versionInfo;
-    result.copiedFiles.push('pro-version.json');
-    rollbackFiles.push(path.join(targetDir, 'pro-version.json'));
-
-    // Generate pro-installed-manifest.yaml (AC8)
-    const manifest = await generateInstalledManifest(targetDir, result.copiedFiles);
-    result.manifest = manifest;
-    result.copiedFiles.push('pro-installed-manifest.yaml');
-    rollbackFiles.push(path.join(targetDir, 'pro-installed-manifest.yaml'));
-
-    result.success = true;
-
-  } catch (error) {
-    result.errors.push(error.message);
-
-    // Rollback partially copied files (AC6)
-    const rollbackResult = await rollbackScaffold(rollbackFiles);
-    if (rollbackResult.errors.length > 0) {
-      result.errors.push(`Rollback errors: ${rollbackResult.errors.join(', ')}`);
-    }
-    result.warnings.push(
-      `Scaffolding failed: ${error.message}. ${rollbackResult.removed} files cleaned up.`,
-    );
-  }
-
-  return result;
-}
-
-/**
- * Scaffold a directory recursively with idempotency checks.
- *
- * @param {string} sourceDir - Source directory
- * @param {string} destDir - Destination directory
- * @param {Object} options - Options
- * @returns {Promise<Object>} Result with copiedFiles and skippedFiles
- */
-async function scaffoldDirectory(sourceDir, destDir, options = {}) {
-  const { force = false, rollbackFiles = [], baseDir } = options;
-  const copiedFiles = [];
-  const skippedFiles = [];
-
-  await fs.ensureDir(destDir);
-
-  const items = await fs.readdir(sourceDir, { withFileTypes: true });
-
-  for (const item of items) {
-    // Skip excluded directories (e.g. private squads)
-    if (SCAFFOLD_EXCLUDES.includes(item.name)) {
-      continue;
-    }
-
-    const sourcePath = path.join(sourceDir, item.name);
-    const destPath = path.join(destDir, item.name);
-
-    if (item.isDirectory()) {
-      const sub = await scaffoldDirectory(sourcePath, destPath, options);
-      copiedFiles.push(...sub.copiedFiles);
-      skippedFiles.push(...sub.skippedFiles);
-    } else {
-      const result = await scaffoldFile(sourcePath, destPath, { force, rollbackFiles, baseDir });
-      if (result.skipped) {
-        skippedFiles.push(result.relativePath);
-      } else {
-        copiedFiles.push(result.relativePath);
-      }
-    }
-  }
-
-  return { copiedFiles, skippedFiles };
-}
-
-/**
- * Scaffold a single file with idempotency (AC5).
- * If dest exists and has identical hash, skip. If user modified, skip (preserve).
- *
- * @param {string} sourcePath - Source file path
- * @param {string} destPath - Destination file path
- * @param {Object} options - Options
- * @returns {Promise<Object>} Result with relativePath and skipped flag
- */
-async function scaffoldFile(sourcePath, destPath, options = {}) {
-  const { force = false, rollbackFiles = [], baseDir } = options;
-  const base = baseDir || path.resolve(destPath, '..', '..');
-  const relativePath = path.relative(base, destPath).replace(/\\/g, '/');
-
-  // Idempotency check (AC5) — async to avoid blocking event loop
-  if (!force && await fs.pathExists(destPath)) {
-    try {
-      if (await hashFilesMatchAsync(sourcePath, destPath)) {
-        // Identical — skip
-        return { relativePath, skipped: true };
-      }
-    } catch {
-      // Hash comparison failed — overwrite to be safe
-    }
-  }
-
-  await fs.ensureDir(path.dirname(destPath));
-  await fs.copy(sourcePath, destPath);
-  rollbackFiles.push(destPath);
-
-  return { relativePath, skipped: false };
-}
-
-/**
- * Generate pro-version.json with SHA256 hashes for version tracking (AC4).
- *
- * @param {string} targetDir - Project root
- * @param {string} proSourceDir - Pro package directory
- * @param {string[]} copiedFiles - List of copied file relative paths
- * @returns {Promise<Object>} Version info object
- */
-async function generateProVersionJson(targetDir, proSourceDir, copiedFiles) {
-  // Read pro package version
-  let proVersion = 'unknown';
-  const proPkgPath = path.join(proSourceDir, 'package.json');
-  if (await fs.pathExists(proPkgPath)) {
-    try {
-      const proPkg = await fs.readJson(proPkgPath);
-      proVersion = proPkg.version || 'unknown';
-    } catch {
-      // Keep 'unknown'
-    }
-  }
-
-  // Generate hashes for all copied files
-  const fileHashes = {};
-  for (const relativePath of copiedFiles) {
-    const absolutePath = path.join(targetDir, relativePath);
-    try {
-      if (await fs.pathExists(absolutePath)) {
-        const stats = await fs.stat(absolutePath);
-        if (stats.isFile()) {
-          fileHashes[relativePath] = `sha256:${await hashFileAsync(absolutePath)}`;
-        }
-      }
-    } catch {
-      // Skip unhashable files
-    }
-  }
-
-  const versionInfo = {
-    proVersion,
-    installedAt: new Date().toISOString(),
-    fileCount: copiedFiles.length,
-    fileHashes,
-  };
-
-  const versionPath = path.join(targetDir, 'pro-version.json');
-  await fs.writeJson(versionPath, versionInfo, { spaces: 2 });
-
-  return versionInfo;
-}
-
-/**
- * Generate pro-installed-manifest.yaml listing all scaffolded files (AC8).
- *
- * @param {string} targetDir - Project root
- * @param {string[]} copiedFiles - List of copied file relative paths
- * @returns {Promise<Object>} Manifest object
- */
-async function generateInstalledManifest(targetDir, copiedFiles) {
-  const files = [];
-  for (const relativePath of copiedFiles) {
-    const absolutePath = path.join(targetDir, relativePath);
-    let timestamp = new Date().toISOString();
-    try {
-      if (await fs.pathExists(absolutePath)) {
-        const stats = await fs.stat(absolutePath);
-        timestamp = stats.mtime.toISOString();
-      }
-    } catch {
-      // Use current time
-    }
-    files.push({ path: relativePath, timestamp });
-  }
-
-  const manifest = {
-    generatedAt: new Date().toISOString(),
-    totalFiles: files.length,
-    files,
-  };
-
-  const manifestPath = path.join(targetDir, 'pro-installed-manifest.yaml');
-  await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
-
-  return manifest;
-}
-
-/**
- * Rollback partially scaffolded files on error (AC6).
- *
- * @param {string[]} rollbackFiles - Absolute paths to remove
- * @returns {Promise<Object>} Rollback result with removed count and errors
- */
-async function rollbackScaffold(rollbackFiles) {
-  let removed = 0;
-  const errors = [];
-
-  for (const filePath of rollbackFiles) {
-    try {
-      if (await fs.pathExists(filePath)) {
-        await fs.remove(filePath);
-        removed++;
-      }
-    } catch (error) {
-      errors.push(`Failed to remove ${filePath}: ${error.message}`);
-    }
-  }
-
-  return { removed, errors };
-}
-
-/**
- * Merge pro-config.yaml sections into core-config.yaml.
- * Deep merges top-level keys (pro, memory, metrics, integrations, squads).
- *
- * @param {string} targetDir - Project root directory
- * @returns {Promise<boolean>} True if merge was performed
- */
-async function mergeProConfig(targetDir) {
-  const coreConfigPath = path.join(targetDir, '.sinapse-ai', 'core-config.yaml');
-  const proConfigPath = path.join(targetDir, '.sinapse-ai', 'pro-config.yaml');
-
-  if (!await fs.pathExists(proConfigPath) || !await fs.pathExists(coreConfigPath)) {
-    return false;
-  }
-
-  const coreConfig = yaml.load(await fs.readFile(coreConfigPath, 'utf8')) || {};
-  const proConfig = yaml.load(await fs.readFile(proConfigPath, 'utf8')) || {};
-
-  for (const [key, value] of Object.entries(proConfig)) {
-    if (coreConfig[key] && typeof coreConfig[key] === 'object' && typeof value === 'object' && !Array.isArray(value)) {
-      coreConfig[key] = { ...coreConfig[key], ...value };
-    } else {
-      coreConfig[key] = value;
-    }
-  }
-
-  await fs.writeFile(coreConfigPath, yaml.dump(coreConfig, { lineWidth: -1 }), 'utf8');
-  return true;
-}
-
-/**
- * Install squad agent commands into active IDE directories.
- * Detects which IDEs are configured and copies agent .md files accordingly.
- *
- * @param {string} targetDir - Project root directory
- * @returns {Promise<Object>} Result with installed count and file list
- */
-async function installSquadCommands(targetDir) {
-  const squadsDir = path.join(targetDir, 'squads');
-  if (!await fs.pathExists(squadsDir)) return { installed: 0, files: [] };
-
-  const ideTargets = [
-    { check: path.join('.claude', 'commands'), dest: (squad) => path.join('.claude', 'commands', squad) },
-    { check: path.join('.codex', 'agents'), dest: () => path.join('.codex', 'agents') },
-    { check: path.join('.gemini', 'rules'), dest: (squad) => path.join('.gemini', 'rules', squad) },
-    { check: path.join('.cursor', 'rules'), dest: () => path.join('.cursor', 'rules') },
-  ];
-
-  const activeIDEs = [];
-  for (const ide of ideTargets) {
-    if (await fs.pathExists(path.join(targetDir, ide.check))) {
-      activeIDEs.push(ide);
-    }
-  }
-  if (activeIDEs.length === 0) return { installed: 0, files: [] };
-
-  const files = [];
-  const items = await fs.readdir(squadsDir, { withFileTypes: true });
-
-  for (const item of items) {
-    if (!item.isDirectory()) continue;
-    const agentsDir = path.join(squadsDir, item.name, 'agents');
-    if (!await fs.pathExists(agentsDir)) continue;
-
-    const agentFiles = (await fs.readdir(agentsDir))
-      .filter(f => f.endsWith('.md') && !f.startsWith('test-'));
-
-    for (const ide of activeIDEs) {
-      const destDir = path.join(targetDir, ide.dest(item.name));
-      await fs.ensureDir(destDir);
-      for (const agentFile of agentFiles) {
-        await fs.copy(
-          path.join(agentsDir, agentFile),
-          path.join(destDir, agentFile),
-        );
-        files.push(path.relative(targetDir, path.join(destDir, agentFile)).replace(/\\/g, '/'));
-      }
-    }
-  }
-
-  return { installed: files.length, files };
-}
-
-module.exports = {
-  scaffoldProContent,
-  scaffoldDirectory,
-  scaffoldFile,
-  generateProVersionJson,
-  generateInstalledManifest,
-  rollbackScaffold,
-  mergeProConfig,
-  installSquadCommands,
-  SCAFFOLD_ITEMS,
-  SCAFFOLD_EXCLUDES,
-};