@nextsparkjs/ai-workflow 0.1.0-beta.100

package/scripts/postinstall.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * @nextsparkjs/ai-workflow postinstall hook
+ *
+ * Automatically syncs AI workflow files (.claude/, .cursor/, etc.) when the package is updated.
+ * Only runs in NextSpark projects that already have AI workflow set up.
+ *
+ * Debug mode: Set NEXTSPARK_DEBUG=1 to see detailed logs
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname, resolve, isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+
+const DEBUG = process.env.NEXTSPARK_DEBUG === '1';
+
+function debug(message) {
+  if (DEBUG) {
+    console.log(`  [DEBUG] ${message}`);
+  }
+}
+
+/**
+ * Find the project root by walking up from the current directory
+ * until we find a package.json that isn't inside node_modules
+ */
+function findProjectRoot() {
+  // When running postinstall, we're in node_modules/@nextsparkjs/ai-workflow
+  // We need to find the project root (where the user's package.json is)
+  let current = process.cwd();
+
+  // If we're inside node_modules, walk up to find the project root
+  if (current.includes('node_modules')) {
+    // Go up until we're out of node_modules
+    const parts = current.split('node_modules');
+    current = parts[0].replace(/[/\\]$/, ''); // Remove trailing slash
+  }
+
+  return current;
+}
+
+/**
+ * Validate that the project root path is safe to use
+ */
+function validateProjectRoot(projectRoot) {
+  // Must be an absolute path
+  if (!isAbsolute(projectRoot)) {
+    debug(`Invalid path: not absolute - ${projectRoot}`);
+    return false;
+  }
+
+  // Must exist
+  if (!existsSync(projectRoot)) {
+    debug(`Invalid path: does not exist - ${projectRoot}`);
+    return false;
+  }
+
+  // Resolve to canonical path and verify it doesn't escape
+  const resolved = resolve(projectRoot);
+  if (resolved !== projectRoot && !projectRoot.startsWith(resolved)) {
+    debug(`Invalid path: resolution mismatch - ${projectRoot} vs ${resolved}`);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Detect if we're in the NextSpark development monorepo.
+ * Consumer projects may also have pnpm-workspace.yaml (for themes/plugins),
+ * so we check for packages/core/ which only exists in the dev monorepo.
+ */
+function isDevMonorepo(projectRoot) {
+  const isMonorepo = existsSync(join(projectRoot, 'packages', 'core', 'package.json'));
+  if (isMonorepo) {
+    debug('Skipping: NextSpark development monorepo detected');
+  }
+  return isMonorepo;
+}
+
+/**
+ * Detect if we're in a NextSpark consumer project
+ */
+function isNextSparkProject(projectRoot) {
+  // If we're in the dev monorepo, skip
+  if (isDevMonorepo(projectRoot)) {
+    return false;
+  }
+
+  // Check for package.json with nextspark dependency
+  const pkgPath = join(projectRoot, 'package.json');
+  if (!existsSync(pkgPath)) {
+    debug('Skipping: no package.json found');
+    return false;
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    const hasNextSpark = !!(deps['@nextsparkjs/core'] || deps['@nextsparkjs/cli']);
+    if (!hasNextSpark) {
+      debug('Skipping: no NextSpark dependencies found');
+    }
+    return hasNextSpark;
+  } catch {
+    debug('Skipping: failed to parse package.json');
+    return false;
+  }
+}
+
+/**
+ * Find the .claude/ folder location.
+ * In workspace setups, .claude/ may be in the parent directory (e.g., web/ is a
+ * workspace member but .claude/ lives at the monorepo root alongside web/).
+ * Returns the directory containing .claude/, or null if not found.
+ */
+function findClaudeRoot(projectRoot) {
+  // Check project root itself
+  if (existsSync(join(projectRoot, '.claude'))) {
+    debug(`.claude/ found at ${projectRoot}`);
+    return projectRoot;
+  }
+
+  // Check parent directory (workspace pattern: my-project/web/ has package.json,
+  // but .claude/ is at my-project/)
+  const parentDir = resolve(projectRoot, '..');
+  if (existsSync(join(parentDir, '.claude'))) {
+    debug(`.claude/ found at parent: ${parentDir}`);
+    return parentDir;
+  }
+
+  debug('Skipping: no .claude/ folder found (AI workflow not set up yet)');
+  return null;
+}
+
+/**
+ * Find the setup.mjs script path relative to this postinstall script
+ */
+function getSetupScriptPath() {
+  // This script is at packages/ai-workflow/scripts/postinstall.mjs
+  // setup.mjs is at packages/ai-workflow/scripts/setup.mjs
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const setupPath = join(__dirname, 'setup.mjs');
+
+  if (existsSync(setupPath)) {
+    return setupPath;
+  }
+
+  debug(`Setup script not found at ${setupPath}`);
+  return null;
+}
+
+// Main execution
+try {
+  const projectRoot = findProjectRoot();
+  debug(`Project root: ${projectRoot}`);
+
+  // Validate project root path
+  if (!validateProjectRoot(projectRoot)) {
+    debug('Skipping: invalid project root path');
+    process.exit(0);
+  }
+
+  // Only run in NextSpark projects with an existing .claude/ folder
+  if (isNextSparkProject(projectRoot)) {
+    const claudeRoot = findClaudeRoot(projectRoot);
+    if (claudeRoot) {
+      console.log('\n  📦 @nextsparkjs/ai-workflow updated - syncing AI workflow files...\n');
+
+      const setupScript = getSetupScriptPath();
+      if (setupScript) {
+        try {
+          execSync(`node "${setupScript}" claude`, {
+            stdio: 'inherit',
+            cwd: claudeRoot,
+          });
+        } catch (syncError) {
+          console.warn('\n  ⚠️  Auto-sync failed. Run manually: npx nextspark sync:ai\n');
+          debug(`Sync error: ${syncError.message}`);
+        }
+      } else {
+        debug('Skipping: setup.mjs script not found');
+      }
+    }
+  }
+} catch (error) {
+  // Postinstall hooks should not break installations
+  // The user can always run the sync manually
+  if (DEBUG) {
+    console.warn('\n  [DEBUG] Postinstall error:', error.message);
+    if (error.stack) {
+      console.warn(error.stack);
+    }
+  }
+}

package/scripts/setup.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+/**
+ * @nextsparkjs/ai-workflow - Setup Script
+ *
+ * Copies AI workflow templates to the consumer's project directory.
+ * Uses file-by-file copy to preserve user-created files.
+ *
+ * Usage:
+ *   node node_modules/@nextsparkjs/ai-workflow/scripts/setup.mjs [editor]
+ *   nextspark setup:ai --editor claude
+ *
+ * Editor options:
+ *   claude        Setup Claude Code (.claude/)
+ *   cursor        Setup Cursor (coming soon)
+ *   antigravity   Setup Antigravity (coming soon)
+ *   all           Setup all available editors
+ *   (no arg)      Defaults to "claude"
+ *
+ * Copy strategy:
+ *   agents/, commands/, skills/, templates/, workflows/, _docs/
+ *     → Overwrite matching files, preserve user-created files
+ *   config/*.schema.json
+ *     → Always overwrite (schema updates)
+ *   config/*.json (non-schema)
+ *     → Copy only if not exists (user config — never overwrite)
+ *   sessions/
+ *     → Create directory if not exists, never copy content
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// Package root = where this script lives (packages/ai-workflow/ or node_modules/@nextsparkjs/ai-workflow/)
+const PACKAGE_ROOT = path.resolve(__dirname, '..')
+
+// Consumer project root = where the user runs from
+const PROJECT_ROOT = process.cwd()
+
+// ---------------------------------------------------------------------------
+// Editor definitions
+// ---------------------------------------------------------------------------
+
+const EDITORS = {
+  claude: {
+    enabled: true,
+    source: 'claude',    // subdirectory in package
+    target: '.claude',   // subdirectory in consumer project
+  },
+  cursor: {
+    enabled: false,
+    source: 'cursor',
+    target: '.cursor',
+  },
+  antigravity: {
+    enabled: false,
+    source: 'antigravity',
+    target: '.antigravity',
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Copy strategies per directory
+// ---------------------------------------------------------------------------
+
+/** Directories where matching files are overwritten */
+const OVERWRITE_DIRS = new Set([
+  'agents',
+  'commands',
+  'skills',
+  'templates',
+  'workflows',
+  '_docs',
+])
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const colors = {
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+}
+
+function log(msg, color = 'reset') {
+  console.log(`${colors[color]}${msg}${colors.reset}`)
+}
+
+/**
+ * Recursively get all files in a directory (relative paths).
+ */
+function getAllFiles(dir, baseDir = dir) {
+  const results = []
+  if (!fs.existsSync(dir)) return results
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      results.push(...getAllFiles(fullPath, baseDir))
+    } else if (entry.name !== '.gitkeep') {
+      results.push(path.relative(baseDir, fullPath))
+    }
+  }
+  return results
+}
+
+/**
+ * Copy a single file, creating parent directories as needed.
+ */
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest)
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true })
+  }
+  fs.copyFileSync(src, dest)
+}
+
+// ---------------------------------------------------------------------------
+// Setup logic for a single editor
+// ---------------------------------------------------------------------------
+
+function setupEditor(name, cfg) {
+  const sourceRoot = path.join(PACKAGE_ROOT, cfg.source)
+  const targetRoot = path.join(PROJECT_ROOT, cfg.target)
+
+  if (!fs.existsSync(sourceRoot)) {
+    log(`  Source not found: ${sourceRoot}`, 'red')
+    return { overwritten: 0, created: 0, preserved: 0 }
+  }
+
+  // Ensure target root exists
+  if (!fs.existsSync(targetRoot)) {
+    fs.mkdirSync(targetRoot, { recursive: true })
+  }
+
+  let overwritten = 0
+  let created = 0
+  let preserved = 0
+
+  // 1. Process overwrite directories (agents, commands, skills, etc.)
+  for (const dirName of OVERWRITE_DIRS) {
+    const srcDir = path.join(sourceRoot, dirName)
+    if (!fs.existsSync(srcDir)) continue
+
+    const files = getAllFiles(srcDir)
+    for (const relPath of files) {
+      const srcFile = path.join(srcDir, relPath)
+      const destFile = path.join(targetRoot, dirName, relPath)
+      const existed = fs.existsSync(destFile)
+
+      copyFile(srcFile, destFile)
+
+      if (existed) {
+        overwritten++
+      } else {
+        created++
+      }
+    }
+
+    if (files.length > 0) {
+      log(`  ${dirName}/: ${files.length} files`, 'green')
+    }
+  }
+
+  // 2. Process config/ directory with mixed strategy
+  const srcConfig = path.join(sourceRoot, 'config')
+  const destConfig = path.join(targetRoot, 'config')
+
+  if (fs.existsSync(srcConfig)) {
+    if (!fs.existsSync(destConfig)) {
+      fs.mkdirSync(destConfig, { recursive: true })
+    }
+
+    let schemasCopied = 0
+    let configsCreated = 0
+    let configsPreserved = 0
+
+    for (const file of fs.readdirSync(srcConfig)) {
+      const srcFile = path.join(srcConfig, file)
+      const destFile = path.join(destConfig, file)
+
+      // Skip non-files and .gitkeep
+      if (!fs.statSync(srcFile).isFile() || file === '.gitkeep') continue
+
+      const isSchema = file.endsWith('.schema.json')
+
+      if (isSchema) {
+        // Schema files: always overwrite
+        copyFile(srcFile, destFile)
+        schemasCopied++
+        overwritten++
+      } else {
+        // Config files: copy only if not exists
+        if (fs.existsSync(destFile)) {
+          configsPreserved++
+          preserved++
+        } else {
+          copyFile(srcFile, destFile)
+          configsCreated++
+          created++
+        }
+      }
+    }
+
+    if (schemasCopied > 0) {
+      log(`  config/*.schema.json: ${schemasCopied} schemas updated`, 'green')
+    }
+    if (configsCreated > 0) {
+      log(`  config/*.json: ${configsCreated} new configs created`, 'green')
+    }
+    if (configsPreserved > 0) {
+      log(`  config/*.json: ${configsPreserved} user configs preserved`, 'blue')
+    }
+  }
+
+  // 3. Ensure sessions/ directory exists (never copy content)
+  const sessionsDir = path.join(targetRoot, 'sessions')
+  if (!fs.existsSync(sessionsDir)) {
+    fs.mkdirSync(sessionsDir, { recursive: true })
+    log(`  sessions/: created (empty)`, 'green')
+  } else {
+    log(`  sessions/: exists (preserved)`, 'blue')
+  }
+
+  return { overwritten, created, preserved }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+const editorArg = process.argv[2] || 'claude'
+
+log(`\n${colors.bold}@nextsparkjs/ai-workflow — Setup${colors.reset}\n`, 'cyan')
+log(`Package: ${PACKAGE_ROOT}`, 'dim')
+log(`Project: ${PROJECT_ROOT}\n`, 'dim')
+
+if (editorArg === 'all') {
+  for (const [name, cfg] of Object.entries(EDITORS)) {
+    if (cfg.enabled) {
+      log(`Setting up ${name}:`, 'cyan')
+      const stats = setupEditor(name, cfg)
+      log(`  Total: ${stats.overwritten} updated, ${stats.created} created, ${stats.preserved} preserved\n`, 'dim')
+    } else {
+      log(`${name}: coming soon\n`, 'yellow')
+    }
+  }
+} else {
+  const cfg = EDITORS[editorArg]
+
+  if (!cfg) {
+    log(`Unknown editor: ${editorArg}`, 'red')
+    log(`Available: ${Object.keys(EDITORS).join(', ')}, all`, 'dim')
+    process.exit(1)
+  }
+
+  if (!cfg.enabled) {
+    log(`${editorArg}: coming soon`, 'yellow')
+    log(`Currently supported: claude`, 'dim')
+    process.exit(0)
+  }
+
+  log(`Setting up ${editorArg}:`, 'cyan')
+  const stats = setupEditor(editorArg, cfg)
+
+  log('')
+  log(`Setup complete!`, 'green')
+  log(`  ${stats.overwritten} files updated`, 'dim')
+  log(`  ${stats.created} files created`, 'dim')
+  log(`  ${stats.preserved} files preserved`, 'dim')
+  log('')
+}

package/scripts/sync.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * @nextsparkjs/ai-workflow - Sync Script
+ *
+ * Syncs the monorepo's working .claude/ directory into the publishable
+ * packages/ai-workflow/claude/ directory. Run manually before npm publish.
+ *
+ * Usage:
+ *   node packages/ai-workflow/scripts/sync.mjs
+ *   # or from package dir:
+ *   pnpm sync
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// Package root = packages/ai-workflow/
+const PACKAGE_ROOT = path.resolve(__dirname, '..')
+// Monorepo root = repo/
+const MONOREPO_ROOT = path.resolve(PACKAGE_ROOT, '../..')
+
+// ---------------------------------------------------------------------------
+// Editor definitions (future-proof)
+// ---------------------------------------------------------------------------
+
+const EDITORS = {
+  claude: {
+    sourceDir: '.claude',
+    targetDir: 'claude',
+    enabled: true,
+  },
+  cursor: {
+    sourceDir: '.cursor',
+    targetDir: 'cursor',
+    enabled: false,
+  },
+  antigravity: {
+    sourceDir: '.antigravity',
+    targetDir: 'antigravity',
+    enabled: false,
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Sync mapping: directories and files to copy from .claude/ to claude/
+// ---------------------------------------------------------------------------
+
+/** Directories to sync (cleaned before copy) */
+const SYNC_DIRS = [
+  'agents',
+  'commands',
+  'skills',
+  'templates',
+  'workflows',
+  '_docs',
+]
+
+/** Subdirectories to exclude from sync (monorepo-only content) */
+const EXCLUDE_DIRS = new Set(['_monorepo'])
+
+/** File globs within config/ to sync (only schemas) */
+const CONFIG_SYNC_PATTERN = /\.schema\.json$/
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const colors = {
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+}
+
+function log(msg, color = 'reset') {
+  console.log(`${colors[color]}${msg}${colors.reset}`)
+}
+
+function getAllFiles(dir, baseDir = dir) {
+  const results = []
+  if (!fs.existsSync(dir)) return results
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (EXCLUDE_DIRS.has(entry.name)) continue
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      results.push(...getAllFiles(fullPath, baseDir))
+    } else {
+      results.push(path.relative(baseDir, fullPath))
+    }
+  }
+  return results
+}
+
+function removeDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest)
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true })
+  }
+  fs.copyFileSync(src, dest)
+}
+
+// ---------------------------------------------------------------------------
+// Main sync logic
+// ---------------------------------------------------------------------------
+
+function syncEditor(name, cfg) {
+  const sourceRoot = path.join(MONOREPO_ROOT, cfg.sourceDir)
+  const targetRoot = path.join(PACKAGE_ROOT, cfg.targetDir)
+
+  if (!fs.existsSync(sourceRoot)) {
+    log(`  Source not found: ${sourceRoot}`, 'red')
+    return { copied: 0, removed: 0, skipped: 0 }
+  }
+
+  let copied = 0
+  let removed = 0
+  let skipped = 0
+
+  // 1. Sync directories: clean target then copy
+  for (const dirName of SYNC_DIRS) {
+    const srcDir = path.join(sourceRoot, dirName)
+    const destDir = path.join(targetRoot, dirName)
+
+    if (!fs.existsSync(srcDir)) {
+      skipped++
+      continue
+    }
+
+    // Clean target directory (remove stale files)
+    if (fs.existsSync(destDir)) {
+      const oldFiles = getAllFiles(destDir)
+      removeDir(destDir)
+      removed += oldFiles.length
+    }
+
+    // Copy all files
+    const files = getAllFiles(srcDir)
+    for (const relPath of files) {
+      copyFile(
+        path.join(srcDir, relPath),
+        path.join(destDir, relPath)
+      )
+      copied++
+    }
+
+    log(`  ${dirName}/: ${files.length} files`, 'green')
+  }
+
+  // 2. Sync config/ schemas only
+  const srcConfig = path.join(sourceRoot, 'config')
+  const destConfig = path.join(targetRoot, 'config')
+
+  if (fs.existsSync(srcConfig)) {
+    let schemaCount = 0
+    for (const file of fs.readdirSync(srcConfig)) {
+      if (CONFIG_SYNC_PATTERN.test(file)) {
+        copyFile(
+          path.join(srcConfig, file),
+          path.join(destConfig, file)
+        )
+        schemaCount++
+        copied++
+      }
+    }
+    log(`  config/*.schema.json: ${schemaCount} files`, 'green')
+    log(`  config/*.json (templates): preserved`, 'dim')
+  }
+
+  return { copied, removed, skipped }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+log('\n@nextsparkjs/ai-workflow — Sync\n', 'cyan')
+log(`Source: ${MONOREPO_ROOT}/.claude/`, 'dim')
+log(`Target: ${PACKAGE_ROOT}/claude/\n`, 'dim')
+
+let totalCopied = 0
+let totalRemoved = 0
+
+for (const [name, cfg] of Object.entries(EDITORS)) {
+  if (!cfg.enabled) {
+    log(`${name}: coming soon (skipped)`, 'dim')
+    continue
+  }
+
+  log(`Syncing ${name}:`, 'cyan')
+  const stats = syncEditor(name, cfg)
+  totalCopied += stats.copied
+  totalRemoved += stats.removed
+}
+
+log(`\nDone: ${totalCopied} files copied, ${totalRemoved} stale files removed.\n`, 'green')