forge-workflow 0.0.6 → 0.0.8

package/lib/frontmatter.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * @module frontmatter
+ *
+ * Utility for parsing and manipulating YAML frontmatter using gray-matter.
+ *
+ * This is the canonical frontmatter library for runtime code that needs
+ * full gray-matter capabilities (e.g., commands-reset, plugin transforms).
+ *
+ * Note: scripts/sync-commands.js uses its own hand-rolled YAML parser
+ * (via the `yaml` package) because sync runs at build time and must not
+ * depend on gray-matter being installed in the target project.
+ *
+ * @example
+ *   const { parse, stringify, stripAll, keepOnly } = require('./frontmatter');
+ *   const { data, content } = parse(raw);
+ *   const rebuilt = stringify(data, content);
+ */
+
+const matter = require('gray-matter');
+
+/**
+ * Parse YAML frontmatter from a markdown string.
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @returns {{ data: Record<string, unknown>, content: string }}
+ */
+function parse(content) {
+  const result = matter(content);
+  return { data: result.data, content: result.content };
+}
+
+/**
+ * Build a file string from frontmatter data and body content.
+ *
+ * @param {Record<string, unknown>} data - Key-value pairs for the YAML block
+ * @param {string} content - The markdown body content
+ * @returns {string}
+ */
+function stringify(data, content) {
+  return matter.stringify(content, data);
+}
+
+/**
+ * Strip all frontmatter, returning only the body content.
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @returns {string} Body content without frontmatter
+ */
+function stripAll(content) {
+  const result = matter(content);
+  return result.content;
+}
+
+/**
+ * Keep only specified fields in frontmatter, strip the rest.
+ *
+ * If none of the specified fields exist, returns body only (no frontmatter).
+ *
+ * @param {string} content - Raw file content with optional frontmatter
+ * @param {string[]} fields - Field names to keep
+ * @returns {string} Rebuilt file with filtered frontmatter
+ */
+function keepOnly(content, fields) {
+  const result = matter(content);
+  const filtered = {};
+  for (const field of fields) {
+    if (Object.hasOwn(result.data, field)) {
+      filtered[field] = result.data[field];
+    }
+  }
+  if (Object.keys(filtered).length === 0) {
+    return result.content;
+  }
+  return matter.stringify(result.content, filtered);
+}
+
+module.exports = { parse, stringify, stripAll, keepOnly };

package/lib/husky-migration.js

@@ -11,6 +11,65 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync, spawnSync } = require('node:child_process');
 
+function readGitDirPointer(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  if (!fs.existsSync(gitPath)) {
+    return null;
+  }
+
+  try {
+    const gitStat = fs.statSync(gitPath);
+    if (gitStat.isDirectory()) {
+      return gitPath;
+    }
+    if (!gitStat.isFile()) {
+      return null;
+    }
+
+    const pointer = fs.readFileSync(gitPath, 'utf8').trim();
+    if (!pointer.startsWith('gitdir:')) {
+      return null;
+    }
+
+    return path.resolve(projectRoot, pointer.replace(/^gitdir:\s*/, ''));
+  } catch {
+    return null;
+  }
+}
+
+function hasHooksPathConfigured(projectRoot) {
+  const gitDir = readGitDirPointer(projectRoot);
+  if (!gitDir) {
+    return false;
+  }
+
+  const configCandidates = [path.join(gitDir, 'config')];
+  const commonDirPath = path.join(gitDir, 'commondir');
+  if (fs.existsSync(commonDirPath)) {
+    try {
+      const commonDir = fs.readFileSync(commonDirPath, 'utf8').trim();
+      if (commonDir) {
+        configCandidates.push(path.resolve(gitDir, commonDir, 'config'));
+      }
+    } catch {
+      // Ignore unreadable commondir files and fall back to direct config candidates.
+    }
+  }
+
+  return configCandidates.some((configPath) => {
+    if (!fs.existsSync(configPath)) {
+      return false;
+    }
+
+    try {
+      const gitConfig = fs.readFileSync(configPath, 'utf8');
+      return /hooksPath\s*=/.test(gitConfig);
+    } catch {
+      return false;
+    }
+  });
+}
+
 /**
  * Resolve a command to its full path to avoid relying on inherited PATH.
  * Falls back to the command name if resolution fails.
@@ -24,7 +83,7 @@ function resolveCommand(command) {
     if (result.status === 0 && result.stdout) {
       return result.stdout.trim().split(/\r?\n/)[0].trim();
     }
-  } catch (_e) {
+  } catch {
     // Expected: command resolution may fail if 'which'/'where.exe' is unavailable — fall back to bare command name
   }
   return command;
@@ -67,13 +126,43 @@ const KNOWN_PATTERNS = [
  */
 const HUSKY_INTERNAL = new Set(['_', '.gitignore', 'husky.sh']);
 
+function resolveGitDir(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  if (!fs.existsSync(gitPath)) {
+    return null;
+  }
+
+  try {
+    const stat = fs.statSync(gitPath);
+    if (stat.isDirectory()) {
+      return gitPath;
+    }
+
+    if (stat.isFile()) {
+      const pointer = fs.readFileSync(gitPath, 'utf8').trim();
+      const separatorIndex = pointer.indexOf(':');
+      const label = separatorIndex === -1 ? pointer : pointer.slice(0, separatorIndex).trim().toLowerCase();
+      if (label === 'gitdir') {
+        const gitDir = pointer.slice(separatorIndex + 1).trim();
+        if (gitDir) {
+          return path.resolve(projectRoot, gitDir);
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
 /**
  * Detect whether Husky is installed in a project.
  *
  * @param {string} projectRoot - Absolute path to the project root.
  * @returns {{ found: boolean, huskyDir: string|null, hasHooksPath: boolean }}
  */
-function detectHusky(projectRoot) {
+function _detectHuskyLegacy(projectRoot) {
   const huskyDir = path.join(projectRoot, '.husky');
   const found = fs.existsSync(huskyDir) && fs.statSync(huskyDir).isDirectory();
 
@@ -83,12 +172,13 @@ function detectHusky(projectRoot) {
 
   // Check for core.hooksPath in .git/config
   let hasHooksPath = false;
-  const gitConfigPath = path.join(projectRoot, '.git', 'config');
-  if (fs.existsSync(gitConfigPath)) {
+  const gitDir = resolveGitDir(projectRoot);
+  const gitConfigPath = gitDir ? path.join(gitDir, 'config') : null;
+  if (gitConfigPath && fs.existsSync(gitConfigPath)) {
     try {
       const gitConfig = fs.readFileSync(gitConfigPath, 'utf8');
       hasHooksPath = /hooksPath\s*=/.test(gitConfig);
-    } catch (_err) {
+    } catch {
       // Expected: .git/config may be unreadable or malformed — assume no hooksPath is configured
     }
   }
@@ -96,6 +186,17 @@ function detectHusky(projectRoot) {
   return { found: true, huskyDir, hasHooksPath };
 }
 
+function detectHusky(projectRoot) {
+  const huskyDir = path.join(projectRoot, '.husky');
+  const found = fs.existsSync(huskyDir) && fs.statSync(huskyDir).isDirectory();
+
+  if (!found) {
+    return { found: false, huskyDir: null, hasHooksPath: false };
+  }
+
+  return { found: true, huskyDir, hasHooksPath: hasHooksPathConfigured(projectRoot) };
+}
+
 /**
  * Strip Husky boilerplate (shebang, sourcing _/husky.sh, blank lines) from hook content.
  *
@@ -167,9 +268,9 @@ function parseHookFile(huskyDir, hookName, mapped, unmapped) {
   let content;
   try {
     content = fs.readFileSync(filePath, 'utf8');
-  } catch (_err) {
+  } catch (err) {
     // Expected: hook file may be unreadable due to permissions — report as unmapped
-    unmapped.push({ hook: hookName, reason: `Cannot read file: ${_err.message}` });
+    unmapped.push({ hook: hookName, reason: `Cannot read file: ${err.message}` });
     return;
   }
 
@@ -211,7 +312,7 @@ function mapHuskyHooks(huskyDir) {
   let entries;
   try {
     entries = fs.readdirSync(huskyDir, { withFileTypes: true });
-  } catch (_err) {
+  } catch {
     // Expected: .husky/ directory may be unreadable — return empty results
     return { mapped, unmapped };
   }
@@ -254,7 +355,7 @@ function validateNoSymlinks(huskyDir) {
       if (stat.isSymbolicLink()) {
         symlinkFiles.push(entry.name);
       }
-    } catch (_err) {
+    } catch {
       // Expected: file may have been removed between readdir and lstat — skip unstattable entries
     }
   }
@@ -285,7 +386,7 @@ function formatHookCommands(hooks) {
  * @returns {string} Updated YAML content with hooks merged in.
  */
 function mergeHookTypeIntoYaml(yaml, hookType, hooks) {
-  const commandsRegex = new RegExp(String.raw`(` + hookType + String.raw`:\s*\n(?:.*\n)*?\s+commands:\s*\n)`, 'm');
+  const commandsRegex = new RegExp(String.raw`(${hookType}:\s*\n(?:.*\n)*?\s+commands:\s*\n)`, 'm');
   const commandsMatch = commandsRegex.exec(yaml);
   if (commandsMatch) {
     const insertion = formatHookCommands(hooks);
@@ -344,7 +445,7 @@ function unsetHooksPath(projectRoot) {
       stdio: 'ignore',
     });
     return true;
-  } catch (_err) {
+  } catch {
     // Expected: git config --unset fails when core.hooksPath is not set — safe to ignore
     return false;
   }
@@ -410,7 +511,7 @@ function migrateHusky(projectRoot, options = {}) {
   if (fs.existsSync(lefthookPath)) {
     try {
       existingContent = fs.readFileSync(lefthookPath, 'utf8');
-    } catch (_err) {
+    } catch {
       // Expected: existing lefthook.yml may be unreadable — will create a new one instead
     }
   }

package/lib/lefthook-check.js

@@ -11,17 +11,26 @@ const path = require('node:path');
  * is actually available in node_modules/.bin.
  *
  * @param {string} projectRoot - Absolute path to the project root directory.
- * @returns {{ installed: boolean, binaryAvailable: boolean, message: string }}
+ * @returns {{ installed: boolean, binaryAvailable: boolean, state: string, message: string }}
  *   - installed: true if lefthook appears in dependencies or devDependencies
  *   - binaryAvailable: true if the lefthook binary exists in node_modules/.bin
+ *   - state: explicit installation state for runtime health checks
  *   - message: actionable guidance when something is missing, empty string when OK
  */
 function checkLefthookStatus(projectRoot) {
-  const pkgPath = path.join(projectRoot, 'package.json');
+  const root = typeof projectRoot === 'string' && projectRoot.trim()
+    ? projectRoot
+    : process.cwd();
+  const pkgPath = path.join(root, 'package.json');
 
   // No package.json — nothing to report
   if (!fs.existsSync(pkgPath)) {
-    return { installed: false, binaryAvailable: false, message: '' };
+    return {
+      installed: false,
+      binaryAvailable: false,
+      state: 'missing-package',
+      message: ''
+    };
   }
 
   let pkg;
@@ -29,7 +38,12 @@ function checkLefthookStatus(projectRoot) {
     pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
   } catch (_err) {
     // Expected: package.json may contain invalid JSON — treat as absent
-    return { installed: false, binaryAvailable: false, message: '' };
+    return {
+      installed: false,
+      binaryAvailable: false,
+      state: 'missing-package',
+      message: ''
+    };
   }
 
   const installed = Boolean(
@@ -40,12 +54,13 @@ function checkLefthookStatus(projectRoot) {
     return {
       installed: false,
       binaryAvailable: false,
+      state: 'missing-dependency',
       message: 'lefthook not found. Run: bun add -D lefthook && bun install',
     };
   }
 
   // Check for the binary in node_modules/.bin
-  const binDir = path.join(projectRoot, 'node_modules', '.bin');
+  const binDir = path.join(root, 'node_modules', '.bin');
   const binaryAvailable =
     fs.existsSync(path.join(binDir, 'lefthook')) ||
     fs.existsSync(path.join(binDir, 'lefthook.cmd'));
@@ -54,12 +69,18 @@ function checkLefthookStatus(projectRoot) {
     return {
       installed: true,
       binaryAvailable: false,
+      state: 'missing-binary',
       message:
         'lefthook is in package.json but not installed. Run: bun install',
     };
   }
 
-  return { installed: true, binaryAvailable: true, message: '' };
+  return {
+    installed: true,
+    binaryAvailable: true,
+    state: 'installed',
+    message: ''
+  };
 }
 
 module.exports = { checkLefthookStatus };

package/lib/plugin-manager.js

@@ -8,6 +8,221 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const SUPPORT_STATUSES = Object.freeze([
+  'first-class',
+  'supported',
+  'compatibility',
+  'deprecated',
+  'unsupported',
+]);
+
+const NATIVE_SURFACES = Object.freeze([
+  'cli-first',
+  'editor-native',
+  'desktop-app',
+  'web-app',
+  'terminal-native',
+  'hybrid',
+]);
+
+const DEFAULT_SUPPORT_STATUS = 'supported';
+
+const SURFACE_BY_AGENT_ID = Object.freeze({
+  claude: 'cli-first',
+  codex: 'cli-first',
+  opencode: 'cli-first',
+  cline: 'editor-native',
+  cursor: 'editor-native',
+  copilot: 'editor-native',
+  kilocode: 'editor-native',
+  roo: 'editor-native',
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateCapabilityFlags(capabilities, errors) {
+  const booleanFields = ['commands', 'rules', 'skills', 'mcp', 'contextMode'];
+
+  booleanFields.forEach((field) => {
+    if (capabilities[field] !== undefined && typeof capabilities[field] !== 'boolean') {
+      errors.push(`"capabilities.${field}" must be a boolean`);
+    }
+  });
+
+  if (capabilities.hooks !== undefined) {
+    if (typeof capabilities.hooks === 'boolean') {
+      return;
+    }
+
+    if (!isPlainObject(capabilities.hooks)) {
+      errors.push('"capabilities.hooks" must be a boolean or an object');
+      return;
+    }
+
+    if (
+      capabilities.hooks.blocking !== undefined &&
+      typeof capabilities.hooks.blocking !== 'boolean'
+    ) {
+      errors.push('"capabilities.hooks.blocking" must be a boolean');
+    }
+  }
+}
+
+function validateSupportMetadata(support, errors) {
+  if (support === undefined) {
+    return;
+  }
+
+  if (!isPlainObject(support)) {
+    errors.push('"support" must be an object');
+    return;
+  }
+
+  if (support.status !== undefined) {
+    if (
+      typeof support.status !== 'string' ||
+      !SUPPORT_STATUSES.includes(support.status)
+    ) {
+      errors.push(
+        `"support.status" must be one of: ${SUPPORT_STATUSES.join(', ')}`
+      );
+    }
+  }
+
+  if (support.surface !== undefined) {
+    if (
+      typeof support.surface !== 'string' ||
+      !NATIVE_SURFACES.includes(support.surface)
+    ) {
+      errors.push(
+        `"support.surface" must be one of: ${NATIVE_SURFACES.join(', ')}`
+      );
+    }
+  }
+
+  if (support.install !== undefined) {
+    if (!isPlainObject(support.install)) {
+      errors.push('"support.install" must be an object');
+    } else {
+      if (
+        support.install.required !== undefined &&
+        typeof support.install.required !== 'boolean'
+      ) {
+        errors.push('"support.install.required" must be a boolean');
+      }
+
+      if (
+        support.install.repairRequired !== undefined &&
+        typeof support.install.repairRequired !== 'boolean'
+      ) {
+        errors.push('"support.install.repairRequired" must be a boolean');
+      }
+    }
+  }
+}
+
+function collectPluginValidationErrors(plugin) {
+  const errors = [];
+
+  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
+    return ['Plugin must be a non-null object'];
+  }
+
+  const required = ['id', 'name', 'version', 'directories'];
+
+  required.forEach((field) => {
+    if (!plugin[field]) {
+      errors.push(`Missing required field "${field}"`);
+    }
+  });
+
+  if (plugin.id !== undefined && typeof plugin.id !== 'string') {
+    errors.push('"id" must be a string');
+  }
+  if (plugin.name !== undefined && typeof plugin.name !== 'string') {
+    errors.push('"name" must be a string');
+  }
+  if (plugin.version !== undefined && typeof plugin.version !== 'string') {
+    errors.push('"version" must be a string');
+  }
+  if (plugin.directories !== undefined) {
+    if (!isPlainObject(plugin.directories)) {
+      errors.push('"directories" must be an object');
+    } else if (Object.keys(plugin.directories).length === 0) {
+      errors.push('"directories" must not be empty');
+    }
+  }
+
+  if (plugin.description !== undefined && typeof plugin.description !== 'string') {
+    errors.push('"description" must be a string');
+  }
+  if (plugin.homepage !== undefined && typeof plugin.homepage !== 'string') {
+    errors.push('"homepage" must be a string');
+  }
+
+  if (plugin.capabilities !== undefined) {
+    if (!isPlainObject(plugin.capabilities)) {
+      errors.push('"capabilities" must be an object');
+    } else {
+      validateCapabilityFlags(plugin.capabilities, errors);
+    }
+  }
+
+  validateSupportMetadata(plugin.support, errors);
+
+  return errors;
+}
+
+function inferNativeSurface(plugin) {
+  if (plugin.support && typeof plugin.support.surface === 'string') {
+    return plugin.support.surface;
+  }
+
+  if (plugin.id && SURFACE_BY_AGENT_ID[plugin.id]) {
+    return SURFACE_BY_AGENT_ID[plugin.id];
+  }
+
+  if (plugin.directories && (plugin.directories.instructions || plugin.directories.prompts)) {
+    return 'editor-native';
+  }
+
+  return 'cli-first';
+}
+
+function normalizePluginMetadata(plugin) {
+  const validationErrors = collectPluginValidationErrors(plugin);
+  if (validationErrors.length > 0) {
+    throw new Error(`Invalid plugin schema: ${validationErrors.join('; ')}`);
+  }
+
+  const capabilities = isPlainObject(plugin.capabilities) ? plugin.capabilities : {};
+  const support = isPlainObject(plugin.support) ? plugin.support : {};
+  const hooks = capabilities.hooks;
+  const blockingHooks = isPlainObject(hooks) ? hooks.blocking : hooks;
+
+  return {
+    ...plugin,
+    normalizedCapabilities: {
+      nativeSurface: inferNativeSurface(plugin),
+      supportStatus: support.status || DEFAULT_SUPPORT_STATUS,
+      commands: Boolean(capabilities.commands),
+      rules: Boolean(capabilities.rules),
+      skills: Boolean(capabilities.skills),
+      mcp: Boolean(capabilities.mcp),
+      contextMode: Boolean(capabilities.contextMode),
+      hooks: {
+        blocking: Boolean(blockingHooks),
+      },
+      install: {
+        required: Boolean(support.install?.required),
+        repairRequired: Boolean(support.install?.repairRequired),
+      },
+    },
+  };
+}
+
 class PluginManager {
   constructor() {
     this.plugins = new Map();
@@ -34,13 +249,14 @@ class PluginManager {
         const content = fs.readFileSync(path.join(pluginDir, file), 'utf-8');
         const plugin = JSON.parse(content);
         this.validatePlugin(plugin);
+        const normalizedPlugin = normalizePluginMetadata(plugin);
 
         // Check for duplicate IDs
-        if (this.plugins.has(plugin.id)) {
-          throw new Error(`Plugin with ID "${plugin.id}" already exists`);
+        if (this.plugins.has(normalizedPlugin.id)) {
+          throw new Error(`Plugin with ID "${normalizedPlugin.id}" already exists`);
         }
 
-        this.plugins.set(plugin.id, plugin);
+        this.plugins.set(normalizedPlugin.id, normalizedPlugin);
       } catch (error) {
         // Re-throw with file context
         throw new Error(`Failed to load plugin ${file}: ${error.message}`);
@@ -54,35 +270,10 @@ class PluginManager {
    * @throws {Error} If validation fails
    */
   validatePlugin(plugin) {
-    const required = ['id', 'name', 'version', 'directories'];
+    const errors = collectPluginValidationErrors(plugin);
 
-    // Check required fields exist
-    required.forEach(field => {
-      if (!plugin[field]) {
-        throw new Error(`Plugin validation failed: missing required field "${field}"`);
-      }
-    });
-
-    // Validate field types
-    if (typeof plugin.id !== 'string') {
-      throw new TypeError('Plugin validation failed: "id" must be a string');
-    }
-    if (typeof plugin.name !== 'string') {
-      throw new TypeError('Plugin validation failed: "name" must be a string');
-    }
-    if (typeof plugin.version !== 'string') {
-      throw new TypeError('Plugin validation failed: "version" must be a string');
-    }
-    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
-      throw new TypeError('Plugin validation failed: "directories" must be an object');
-    }
-
-    // Validate optional fields if present
-    if (plugin.description && typeof plugin.description !== 'string') {
-      throw new TypeError('Plugin validation failed: "description" must be a string');
-    }
-    if (plugin.homepage && typeof plugin.homepage !== 'string') {
-      throw new TypeError('Plugin validation failed: "homepage" must be a string');
+    if (errors.length > 0) {
+      throw new Error(`Plugin validation failed: ${errors[0]}`);
     }
   }
 
@@ -118,49 +309,11 @@ class PluginManager {
  * @returns {{valid: boolean, errors: Array<string>}}
  */
 function validatePluginSchema(plugin) {
-  const errors = [];
-
-  // Check if plugin is an object
-  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
-    return { valid: false, errors: ['Plugin must be a non-null object'] };
-  }
-
-  // Check required fields
-  const required = ['id', 'name', 'version', 'directories'];
-  required.forEach(field => {
-    if (!plugin[field]) {
-      errors.push(`Missing required field "${field}"`);
-    }
-  });
-
-  // Validate field types
-  if (plugin.id !== undefined && typeof plugin.id !== 'string') {
-    errors.push('"id" must be a string');
-  }
-  if (plugin.name !== undefined && typeof plugin.name !== 'string') {
-    errors.push('"name" must be a string');
-  }
-  if (plugin.version !== undefined && typeof plugin.version !== 'string') {
-    errors.push('"version" must be a string');
-  }
-  if (plugin.directories !== undefined) {
-    if (typeof plugin.directories !== 'object' || Array.isArray(plugin.directories)) {
-      errors.push('"directories" must be an object');
-    } else if (Object.keys(plugin.directories).length === 0) {
-      errors.push('"directories" must not be empty');
-    }
-  }
-
-  // Validate optional fields if present
-  if (plugin.description !== undefined && typeof plugin.description !== 'string') {
-    errors.push('"description" must be a string');
-  }
-  if (plugin.homepage !== undefined && typeof plugin.homepage !== 'string') {
-    errors.push('"homepage" must be a string');
-  }
-
+  const errors = collectPluginValidationErrors(plugin);
   return { valid: errors.length === 0, errors };
 }
 
 module.exports = PluginManager;
+module.exports.PluginManager = PluginManager;
 module.exports.validatePluginSchema = validatePluginSchema;
+module.exports.normalizePluginMetadata = normalizePluginMetadata;