grimoire-framework 1.0.0

package/scripts/sign-manifest.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+#
+# sign-manifest.sh - Helper script to sign the install manifest
+#
+# Usage:
+#   ./scripts/sign-manifest.sh /path/to/grimoire.key
+#
+# Prerequisites:
+#   - minisign installed (brew install minisign / apt install minisign)
+#   - Secret key file
+#
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+MANIFEST_PATH="$PROJECT_ROOT/.grimoire/install-manifest.yaml"
+SIGNATURE_PATH="$MANIFEST_PATH.minisig"
+
+echo -e "${YELLOW}═══════════════════════════════════════════════════════════${NC}"
+echo -e "${YELLOW}  grimoire Manifest Signing Tool${NC}"
+echo -e "${YELLOW}═══════════════════════════════════════════════════════════${NC}"
+echo ""
+
+# Check minisign is installed
+if ! command -v minisign &> /dev/null; then
+    echo -e "${RED}Error: minisign is not installed${NC}"
+    echo "Install with:"
+    echo "  macOS:  brew install minisign"
+    echo "  Ubuntu: apt install minisign"
+    echo "  Windows: scoop install minisign"
+    exit 1
+fi
+
+# Check secret key path provided
+if [ -z "$1" ]; then
+    echo -e "${RED}Error: Secret key path required${NC}"
+    echo ""
+    echo "Usage: $0 /path/to/grimoire.key"
+    echo ""
+    echo "To generate a new key pair:"
+    echo "  minisign -G -p grimoire.pub -s grimoire.key"
+    exit 1
+fi
+
+SECRET_KEY="$1"
+
+# Verify secret key exists
+if [ ! -f "$SECRET_KEY" ]; then
+    echo -e "${RED}Error: Secret key not found: $SECRET_KEY${NC}"
+    exit 1
+fi
+
+# Verify manifest exists
+if [ ! -f "$MANIFEST_PATH" ]; then
+    echo -e "${RED}Error: Manifest not found: $MANIFEST_PATH${NC}"
+    echo ""
+    echo "Generate manifest first with:"
+    echo "  node bin/grimoire.js manifest:generate"
+    exit 1
+fi
+
+# Show manifest info
+echo -e "${GREEN}Manifest found:${NC} $MANIFEST_PATH"
+MANIFEST_SIZE=$(wc -c < "$MANIFEST_PATH" | tr -d ' ')
+MANIFEST_LINES=$(wc -l < "$MANIFEST_PATH" | tr -d ' ')
+echo "  Size: $MANIFEST_SIZE bytes"
+echo "  Lines: $MANIFEST_LINES"
+echo ""
+
+# Check if signature already exists
+if [ -f "$SIGNATURE_PATH" ]; then
+    echo -e "${YELLOW}Warning: Existing signature will be overwritten${NC}"
+    echo ""
+fi
+
+# Sign the manifest
+echo -e "${GREEN}Signing manifest...${NC}"
+echo ""
+
+cd "$PROJECT_ROOT/.grimoire"
+minisign -Sm install-manifest.yaml -s "$SECRET_KEY"
+
+# Verify the signature
+echo ""
+echo -e "${GREEN}Verifying signature...${NC}"
+
+# Extract public key path (assume same directory with .pub extension)
+PUBLIC_KEY="${SECRET_KEY%.key}.pub"
+if [ -f "$PUBLIC_KEY" ]; then
+    if minisign -Vm install-manifest.yaml -p "$PUBLIC_KEY" 2>/dev/null; then
+        echo -e "${GREEN}✓ Signature verified successfully${NC}"
+    else
+        echo -e "${RED}✗ Signature verification failed!${NC}"
+        exit 1
+    fi
+else
+    echo -e "${YELLOW}Note: Could not find public key at $PUBLIC_KEY${NC}"
+    echo "Skipping verification (signature was still created)"
+fi
+
+echo ""
+echo -e "${GREEN}═══════════════════════════════════════════════════════════${NC}"
+echo -e "${GREEN}  Signing Complete!${NC}"
+echo -e "${GREEN}═══════════════════════════════════════════════════════════${NC}"
+echo ""
+echo "Created: $SIGNATURE_PATH"
+echo ""
+echo "Next steps:"
+echo "  1. git add .grimoire/install-manifest.yaml.minisig"
+echo "  2. git commit -m 'chore: sign manifest for release'"
+echo "  3. npm publish"
+echo ""
+
+

package/scripts/validate-manifest.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * Validate Install Manifest
+ * Ensures install-manifest.yaml is up-to-date with actual files
+ *
+ * @script scripts/validate-manifest.js
+ * @story 6.18 - Dynamic Manifest & Brownfield Upgrade System
+ *
+ * Usage:
+ *   node scripts/validate-manifest.js
+ *   npm run validate:manifest
+ *
+ * Exit codes:
+ *   0 - Manifest is valid and up-to-date
+ *   1 - Manifest is outdated or has issues
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { hashFile } = require('../packages/installer/src/installer/file-hasher');
+const {
+  scanDirectory,
+  FOLDERS_TO_COPY,
+  ROOT_FILES_TO_COPY,
+  getFileType,
+} = require('./generate-install-manifest');
+
+/**
+ * Validation result object
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether manifest is valid
+ * @property {string[]} newFiles - Files in filesystem but not in manifest
+ * @property {string[]} removedFiles - Files in manifest but not in filesystem
+ * @property {string[]} modifiedFiles - Files with different hashes
+ * @property {string[]} errors - Error messages
+ */
+
+/**
+ * Load and parse the install manifest
+ * @returns {Object|null} - Parsed manifest or null if not found
+ */
+function loadManifest() {
+  const manifestPath = path.join(__dirname, '..', '.grimoire', 'install-manifest.yaml');
+
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(manifestPath, 'utf8');
+  return yaml.load(content);
+}
+
+/**
+ * Get current files from filesystem
+ * @returns {Map<string, Object>} - Map of relativePath -> file metadata
+ */
+function getCurrentFiles() {
+  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
+  const filesMap = new Map();
+
+  // Scan folders
+  const allFiles = [];
+  for (const folder of FOLDERS_TO_COPY) {
+    const folderPath = path.join(grimoireCoreDir, folder);
+    if (fs.existsSync(folderPath)) {
+      scanDirectory(folderPath, grimoireCoreDir, allFiles);
+    }
+  }
+
+  // Add root files
+  for (const file of ROOT_FILES_TO_COPY) {
+    const filePath = path.join(grimoireCoreDir, file);
+    if (fs.existsSync(filePath)) {
+      allFiles.push(filePath);
+    }
+  }
+
+  // Build map
+  for (const fullPath of allFiles) {
+    const relativePath = path.relative(grimoireCoreDir, fullPath).replace(/\\/g, '/');
+    try {
+      const hash = hashFile(fullPath);
+      filesMap.set(relativePath, {
+        path: relativePath,
+        hash: `sha256:${hash}`,
+        type: getFileType(relativePath),
+      });
+    } catch (error) {
+      console.warn(`Warning: Could not hash ${relativePath}: ${error.message}`);
+    }
+  }
+
+  return filesMap;
+}
+
+/**
+ * Validate manifest against current filesystem
+ * @returns {ValidationResult} - Validation results
+ */
+function validateManifest() {
+  const result = {
+    valid: true,
+    newFiles: [],
+    removedFiles: [],
+    modifiedFiles: [],
+    errors: [],
+  };
+
+  // Load manifest
+  const manifest = loadManifest();
+  if (!manifest) {
+    result.valid = false;
+    result.errors.push('install-manifest.yaml not found');
+    return result;
+  }
+
+  if (!manifest.files || !Array.isArray(manifest.files)) {
+    result.valid = false;
+    result.errors.push('Manifest has no files array');
+    return result;
+  }
+
+  // Get current files
+  const currentFiles = getCurrentFiles();
+
+  // Build set of manifest paths
+  const manifestPaths = new Set();
+  const manifestMap = new Map();
+
+  for (const entry of manifest.files) {
+    const normalizedPath = entry.path.replace(/\\/g, '/');
+    manifestPaths.add(normalizedPath);
+    manifestMap.set(normalizedPath, entry);
+  }
+
+  // Check for new files (in filesystem but not in manifest)
+  for (const [filePath, _fileData] of currentFiles) {
+    if (!manifestPaths.has(filePath)) {
+      result.newFiles.push(filePath);
+      result.valid = false;
+    }
+  }
+
+  // Check for removed files and hash mismatches
+  for (const [manifestPath, manifestEntry] of manifestMap) {
+    const currentFile = currentFiles.get(manifestPath);
+
+    if (!currentFile) {
+      // File in manifest but not in filesystem
+      result.removedFiles.push(manifestPath);
+      result.valid = false;
+    } else if (currentFile.hash !== manifestEntry.hash) {
+      // Hash mismatch
+      result.modifiedFiles.push({
+        path: manifestPath,
+        manifestHash: manifestEntry.hash,
+        currentHash: currentFile.hash,
+      });
+      result.valid = false;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Print validation report
+ * @param {ValidationResult} result - Validation results
+ */
+function printReport(result) {
+  console.log('='.repeat(60));
+  console.log('grimoire Manifest Validation Report');
+  console.log('='.repeat(60));
+  console.log('');
+
+  if (result.errors.length > 0) {
+    console.log('❌ ERRORS:');
+    for (const error of result.errors) {
+      console.log(`   - ${error}`);
+    }
+    console.log('');
+  }
+
+  if (result.newFiles.length > 0) {
+    console.log(`📁 NEW FILES (${result.newFiles.length}) - not in manifest:`);
+    for (const file of result.newFiles.slice(0, 20)) {
+      console.log(`   + ${file}`);
+    }
+    if (result.newFiles.length > 20) {
+      console.log(`   ... and ${result.newFiles.length - 20} more`);
+    }
+    console.log('');
+  }
+
+  if (result.removedFiles.length > 0) {
+    console.log(`🗑️  REMOVED FILES (${result.removedFiles.length}) - in manifest but missing:`);
+    for (const file of result.removedFiles.slice(0, 20)) {
+      console.log(`   - ${file}`);
+    }
+    if (result.removedFiles.length > 20) {
+      console.log(`   ... and ${result.removedFiles.length - 20} more`);
+    }
+    console.log('');
+  }
+
+  if (result.modifiedFiles.length > 0) {
+    console.log(`📝 MODIFIED FILES (${result.modifiedFiles.length}) - hash mismatch:`);
+    for (const file of result.modifiedFiles.slice(0, 20)) {
+      console.log(`   ~ ${file.path}`);
+      if (process.env.VERBOSE) {
+        console.log(`     manifest: ${file.manifestHash}`);
+        console.log(`     current:  ${file.currentHash}`);
+      }
+    }
+    if (result.modifiedFiles.length > 20) {
+      console.log(`   ... and ${result.modifiedFiles.length - 20} more`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  console.log('-'.repeat(60));
+  if (result.valid) {
+    console.log('✅ Manifest is VALID and up-to-date');
+  } else {
+    console.log('❌ Manifest is OUTDATED');
+    console.log('');
+    console.log('To fix, run: npm run generate:manifest');
+  }
+  console.log('-'.repeat(60));
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  try {
+    const result = validateManifest();
+    printReport(result);
+
+    if (!result.valid) {
+      process.exit(1);
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error('\n❌ Error validating manifest:', error.message);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  validateManifest,
+  loadManifest,
+  getCurrentFiles,
+  printReport,
+};
+
+

package/scripts/validate-package-completeness.js

@@ -0,0 +1,319 @@
+#!/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/grimoire.js',
+  'bin/grimoire-minimal.js',
+  // Core framework
+  '.grimoire/core-config.yaml',
+  '.grimoire/constitution.md',
+  '.grimoire/development/agents/',
+  '.grimoire/development/tasks/',
+];
+
+/**
+ * Paths that MUST NOT appear in the tarball (leak prevention).
+ */
+const EXCLUDED_PATHS = [
+  'pro/',
+  '.env',
+  '.git/',
+  'node_modules/',
+  '.grimoire/',
+  'tests/',
+];
+
+/**
+ * Entries required in package.json "files" array.
+ */
+const REQUIRED_FILES_ENTRIES = [
+  '.claude/hooks/',
+  '.claude/rules/',
+  '.grimoire/',
+  'bin/',
+];
+
+/**
+ * Bin entries that must point to existing files.
+ */
+const REQUIRED_BIN_ENTRIES = ['grimoire', 'grimoire'];
+
+/**
+ * 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('grimoire 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();
+
+