wogiflow 2.31.2 → 2.33.0

package/scripts/flow-skill-export.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+/**
+ * flow skill export — Phase 1B (wf-0342fc33)
+ *
+ * Exports a portable skill to one of two open distribution formats:
+ *   --format=agentskills@v1   (agentskills.io v1 manifest + file bundle)
+ *   --format=claude-plugin    (Claude Code plugin layout, ready for `claude plugin tag`)
+ *
+ * The export refuses (exit 1) if the portability checker reports any blocker.
+ * Blockers are printed to stderr in a citation-friendly `file:line` format.
+ *
+ * IMPORT IS NOT IMPLEMENTED. See `.claude/docs/skill-portability.md` for why
+ * (security model — quarantine + content scanner + opt-in enable — is deferred
+ * to a follow-up). Comment marker `[import would go here]` below marks the
+ * intended insertion point.
+ *
+ * Usage:
+ *   flow skill export <name> [--format=<format>] [--out=<dir>]
+ *
+ * @file scripts/flow-skill-export.js
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Resolve project root via the same env-var contract scripts/flow uses.
+const PROJECT_ROOT = process.env.WOGIFLOW_PROJECT_ROOT
+  || process.env.WOGI_PROJECT_ROOT
+  || process.cwd();
+
+const { assessSkillPortability, formatBlockers } = require('../lib/skill-portability');
+const { exportToAgentskills, AGENTSKILLS_SCHEMA_VERSION } = require('../lib/skill-export-agentskills');
+const { exportToClaudePlugin } = require('../lib/skill-export-claude-plugin');
+
+const SUPPORTED_FORMATS = new Set(['agentskills@v1', 'claude-plugin']);
+const DEFAULT_FORMAT = 'agentskills@v1';
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CLI args for `flow skill export`.
+ *
+ * @param {string[]} argv
+ * @returns {{name: string|null, format: string, out: string|null, help: boolean, force: boolean}}
+ */
+function parseArgs(argv) {
+  const options = {
+    name: null,
+    format: DEFAULT_FORMAT,
+    out: null,
+    help: false,
+    force: false, // bypass directory-exists check; never bypasses portability
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--force' || arg === '-f') {
+      options.force = true;
+    } else if (arg.startsWith('--format=')) {
+      options.format = arg.slice('--format='.length);
+    } else if (arg === '--format') {
+      if (i + 1 >= argv.length) {
+        throw new Error('--format requires a value');
+      }
+      options.format = argv[++i];
+    } else if (arg.startsWith('--out=')) {
+      options.out = arg.slice('--out='.length);
+    } else if (arg === '--out') {
+      if (i + 1 >= argv.length) {
+        throw new Error('--out requires a value');
+      }
+      options.out = argv[++i];
+    } else if (!arg.startsWith('-') && options.name === null) {
+      options.name = arg;
+    }
+  }
+
+  return options;
+}
+
+function showHelp() {
+  const lines = [
+    '',
+    'Usage: flow skill export <name> [options]',
+    '',
+    'Export a portable skill to an open distribution format.',
+    '',
+    'Arguments:',
+    '  <name>            Skill name (must exist under .claude/skills/)',
+    '',
+    'Options:',
+    '  --format=<fmt>    Output format: agentskills@v1 | claude-plugin',
+    `                    (default: ${DEFAULT_FORMAT})`,
+    '  --out=<dir>       Output directory (default: ./dist/skills/<name>/)',
+    '  --force, -f       Overwrite existing output directory',
+    '  --help, -h        Show this help',
+    '',
+    'Behavior:',
+    '  The portability checker runs first. Any WogiFlow-specific reference',
+    '  (.workflow/, /wogi-*, flow-utils, ready.json, etc.) blocks the export',
+    '  with a citation. Fix the skill or mark it explicitly non-portable.',
+    '',
+    'Examples:',
+    '  flow skill export commit',
+    '  flow skill export commit --format=claude-plugin',
+    '  flow skill export commit --format=agentskills@v1 --out=/tmp/commit-export',
+    '',
+  ];
+  console.log(lines.join('\n'));
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Write the manifest + bundle files to the output directory.
+ *
+ * For agentskills, the manifest is written to `<out>/manifest.json` and
+ * bundled files are written under `<out>/` preserving their relative paths.
+ *
+ * For claude-plugin, the manifest is already inside the `files` array under
+ * `.claude-plugin/plugin.json`, so we only iterate `files`.
+ *
+ * @param {string} outDir
+ * @param {string} format
+ * @param {{manifest: Object, files: Array<{path: string, content: string}>}} bundle
+ */
+function writeBundle(outDir, format, bundle) {
+  fs.mkdirSync(outDir, { recursive: true });
+
+  if (format === 'agentskills@v1') {
+    // Manifest at root
+    fs.writeFileSync(
+      path.join(outDir, 'manifest.json'),
+      JSON.stringify(bundle.manifest, null, 2) + '\n'
+    );
+    for (const file of bundle.files) {
+      const dest = path.join(outDir, file.path);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, file.content);
+    }
+    return;
+  }
+
+  if (format === 'claude-plugin') {
+    // claude-plugin embeds plugin.json in the files list — just write everything.
+    for (const file of bundle.files) {
+      const dest = path.join(outDir, file.path);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, file.content);
+    }
+    return;
+  }
+
+  throw new Error(`writeBundle: unknown format "${format}"`);
+}
+
+// ---------------------------------------------------------------------------
+// Pure orchestration (exported for tests; does not exit/log)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the export pipeline. Returns a structured result instead of exiting,
+ * so tests can assert behavior without spawning a child process.
+ *
+ * @param {Object} args
+ * @param {string} args.skillName
+ * @param {string} args.skillDir - Absolute path to the skill's source directory
+ * @param {string} args.format - Either 'agentskills@v1' or 'claude-plugin'
+ * @param {string} [args.outDir] - Destination dir; if omitted, no write happens
+ * @param {boolean} [args.force=false] - Overwrite existing destination dir
+ * @returns {{ok: true, bundle: Object, portability: Object, format: string, outDir: string|null}
+ *          | {ok: false, error: string, portability?: Object}}
+ */
+function runExport(args) {
+  const { skillName, skillDir, format, outDir = null, force = false } = args;
+
+  if (!SUPPORTED_FORMATS.has(format)) {
+    return {
+      ok: false,
+      error: `Unsupported format "${format}". Supported: ${[...SUPPORTED_FORMATS].join(', ')}`,
+    };
+  }
+
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    return {
+      ok: false,
+      error: `Skill "${skillName}" not found at ${skillDir}`,
+    };
+  }
+
+  // Portability gate — fail-loud on any blocker.
+  const portability = assessSkillPortability(skillDir);
+  if (!portability.portable) {
+    return {
+      ok: false,
+      error: `Skill "${skillName}" is not portable. ${formatBlockers(portability.blockers)}`,
+      portability,
+    };
+  }
+
+  // Build the bundle.
+  let bundle;
+  try {
+    if (format === 'agentskills@v1') {
+      bundle = exportToAgentskills(skillDir);
+    } else {
+      bundle = exportToClaudePlugin(skillDir);
+    }
+  } catch (err) {
+    return { ok: false, error: `Export failed: ${err.message}`, portability };
+  }
+
+  // Optional disk write.
+  if (outDir) {
+    if (fs.existsSync(outDir)) {
+      if (!force) {
+        return {
+          ok: false,
+          error: `Output directory exists: ${outDir} (use --force to overwrite)`,
+          portability,
+        };
+      }
+      // Best-effort clean — only remove our known output paths to avoid surprises.
+      try {
+        fs.rmSync(outDir, { recursive: true, force: true });
+      } catch (err) {
+        return { ok: false, error: `Failed to clear ${outDir}: ${err.message}`, portability };
+      }
+    }
+    try {
+      writeBundle(outDir, format, bundle);
+    } catch (err) {
+      return { ok: false, error: `Failed to write bundle: ${err.message}`, portability };
+    }
+  }
+
+  return { ok: true, bundle, portability, format, outDir };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    showHelp();
+    process.exit(1);
+  }
+
+  if (opts.help) {
+    showHelp();
+    return;
+  }
+
+  if (!opts.name) {
+    console.error('Error: skill name is required.');
+    showHelp();
+    process.exit(1);
+  }
+
+  if (!SUPPORTED_FORMATS.has(opts.format)) {
+    console.error(`Error: unsupported --format "${opts.format}". Supported: ${[...SUPPORTED_FORMATS].join(', ')}`);
+    process.exit(1);
+  }
+
+  const skillDir = path.join(PROJECT_ROOT, '.claude', 'skills', opts.name);
+  const outDir = opts.out
+    ? path.resolve(PROJECT_ROOT, opts.out)
+    : path.join(PROJECT_ROOT, 'dist', 'skills', opts.name);
+
+  const result = runExport({
+    skillName: opts.name,
+    skillDir,
+    format: opts.format,
+    outDir,
+    force: opts.force,
+  });
+
+  if (!result.ok) {
+    console.error(`\n✗ ${result.error}`);
+    if (result.portability && result.portability.blockers && result.portability.blockers.length > 0) {
+      console.error('\nFix these blockers or mark the skill as non-portable, then re-run:');
+      for (const b of result.portability.blockers) {
+        const where = `${b.file}:${b.line}`;
+        const detail = b.match ? ` — "${b.match}"` : '';
+        console.error(`  • [${b.label}] ${where}${detail}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  console.log(`✓ Exported skill "${opts.name}" to ${result.format}`);
+  console.log(`  Files:  ${result.bundle.files.length}`);
+  console.log(`  Output: ${result.outDir}`);
+  if (opts.format === 'agentskills@v1') {
+    console.log(`  Schema: ${AGENTSKILLS_SCHEMA_VERSION}`);
+  }
+}
+
+// =============================================================================
+// [import would go here]
+//
+// Future `flow skill import <archive>` will land here. Deferred per Phase 1B
+// spec: "Import deferred to a follow-up post-security-model design (quarantine
+// + content scanner + opt-in enable)." Implementing it now would land code
+// without a security model around running untrusted skill content (untrusted
+// .md is mostly harmless, but skills can include scripts, templates, and
+// `allowed-tools` declarations that grant tool access). See
+// .claude/docs/skill-portability.md for the design constraints.
+// =============================================================================
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = {
+  runExport,
+  parseArgs,
+  SUPPORTED_FORMATS,
+  DEFAULT_FORMAT,
+};

package/scripts/hooks/adapters/claude-code.js

@@ -446,6 +446,9 @@ Run: /wogi-start ${coreResult.nextTaskId}`;
       else if (coreResult.message) pieces.push(coreResult.message);
     }
     // Info pieces always pass through.
+    // wf-1bcc67d5: research-required nudge — placed FIRST among info pieces
+    // because it's a "do this BEFORE you answer" instruction, not background.
+    if (coreResult.researchRequiredNudge) pieces.push(coreResult.researchRequiredNudge);
     if (coreResult.phasePrompt) pieces.push(coreResult.phasePrompt);
     if (coreResult.overduePrompt) pieces.push(coreResult.overduePrompt);
 
@@ -669,9 +672,20 @@ Run: /wogi-start ${coreResult.nextTaskId}`;
     // with zero validation benefit. This was causing unnecessary token consumption
     // in target projects where generateConfig() produces the settings.
     if (rules.validation?.enabled !== false) {
+      const postToolUseEntry = hookEntry('PostToolUse', 'post-tool-use.js', HOOK_TIMEOUTS.POST_TOOL_USE);
+      // continueOnBlock (Claude Code 2.1.139+): when the PostToolUse hook returns a
+      // blocking decision (lint/typecheck failure after an Edit/Write — see
+      // transformPostToolUse → decision: 'block'), feed the reason back to Claude and
+      // continue the turn so it fixes the error in-loop instead of dead-ending. This is
+      // what CLAUDE.md's "validate after EVERY file edit" rule needs. Unknown field on
+      // older Claude Code → silently ignored, so it is safe to emit unconditionally.
+      // Only meaningful for the local 'command' transport.
+      if (postToolUseEntry.type === 'command') {
+        postToolUseEntry.continueOnBlock = true;
+      }
       hooks.PostToolUse = [{
         matcher: 'Edit|Write|Bash',
-        hooks: [hookEntry('PostToolUse', 'post-tool-use.js', HOOK_TIMEOUTS.POST_TOOL_USE)]
+        hooks: [postToolUseEntry]
       }];
     }
 

package/scripts/hooks/core/git-safety-gate.js

@@ -153,25 +153,68 @@ function rotateBackupBranches(keep) {
 }
 
 /**
- * Auto-stash current changes.
- * @returns {boolean} True if stash was created.
+ * Auto-stash current changes with verification.
+ *
+ * Returns a discriminated result so callers can distinguish:
+ *   - `no-changes` — working tree was clean; nothing to stash. Safe to proceed.
+ *   - `stashed`    — stash created AND verified present at stash@{0}. Safe to proceed.
+ *   - `failed`     — something went wrong (git error, lock contention, or stash
+ *                    silently no-op'd). Caller MUST NOT proceed with destructive
+ *                    operations — the user's uncommitted work is still in the
+ *                    working tree and would be lost.
+ *
+ * Historically (pre wf-2d3d09b8) this returned a bare boolean, which collapsed
+ * `no-changes` and `failed` into the same `false`. Callers couldn't tell the
+ * difference, so a stash failure on a dirty working tree was indistinguishable
+ * from a no-op on a clean one — and the discard-all branch let the destructive
+ * `git checkout .` / `git restore .` through either way. This was BUG-1.
+ *
+ * @param {Object} [opts]
+ * @param {Function} [opts.exec] - execSync replacement for testing (string cmd → string stdout, throws on error).
+ * @returns {{ status: 'no-changes' | 'stashed' | 'failed', error?: string, stashRef?: string }}
  */
-function autoStash() {
-  const { execSync } = require('node:child_process');
+function autoStash(opts = {}) {
+  const exec = opts.exec || require('node:child_process').execSync;
+  const runOpts = { encoding: 'utf-8', cwd: PATHS.root, stdio: ['pipe', 'pipe', 'pipe'] };
+
+  // 1. Anything to stash?
+  let status;
   try {
-    const status = execSync('git status --porcelain', {
-      encoding: 'utf-8', cwd: PATHS.root, stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-    if (!status) return false; // Nothing to stash
+    status = exec('git status --porcelain', runOpts).trim();
+  } catch (err) {
+    return { status: 'failed', error: `git status failed: ${err.message || err}` };
+  }
+  if (!status) return { status: 'no-changes' };
 
-    const timestamp = new Date().toISOString().slice(0, 19);
-    execSync(`git stash push -m "auto-backup-${timestamp}"`, {
-      encoding: 'utf-8', cwd: PATHS.root, stdio: ['pipe', 'pipe', 'pipe']
-    });
-    return true;
-  } catch (_err) {
-    return false;
+  // 2. Attempt the stash.
+  const timestamp = new Date().toISOString().slice(0, 19);
+  const stashMessage = `auto-backup-${timestamp}`;
+  try {
+    exec(`git stash push -m "${stashMessage}"`, runOpts);
+  } catch (err) {
+    return { status: 'failed', error: `git stash push failed: ${err.message || err}` };
+  }
+
+  // 3. VERIFY the stash actually saved (BUG-1 / wf-2d3d09b8). A zero exit code
+  //    from `git stash push` is NOT proof: lock contention, broken hooks, or
+  //    edge cases can leave the working tree unchanged with status 0. Confirm
+  //    by reading `git stash list` and matching our timestamped message at
+  //    stash@{0}.
+  let stashList;
+  try {
+    stashList = exec('git stash list', runOpts);
+  } catch (err) {
+    return { status: 'failed', error: `stash verification (git stash list) failed: ${err.message || err}` };
   }
+  const firstLine = (stashList || '').split('\n')[0] || '';
+  if (!firstLine.includes(stashMessage)) {
+    return {
+      status: 'failed',
+      error: `stash verification failed: expected "${stashMessage}" at stash@{0}, found: ${firstLine || '(empty)'}`
+    };
+  }
+
+  return { status: 'stashed', stashRef: 'stash@{0}' };
 }
 
 // ============================================================
@@ -230,9 +273,13 @@ function parseGitCommand(command) {
  * Check git safety for Bash commands (PreToolUse).
  * @param {string} command - Bash command
  * @param {Object} [config]
- * @returns {{ allowed: boolean, blocked: boolean, reason?: string, message?: string, autoAction?: string }}
+ * @param {Object} [_deps] - Dependency injection seam (test-only).
+ * @param {Function} [_deps.autoStash] - Override the autoStash helper (test-only).
+ * @returns {{ allowed: boolean, blocked: boolean, reason?: string, message?: string, autoAction?: string, warning?: boolean }}
  */
-function checkGitSafety(command, config) {
+function checkGitSafety(command, config, _deps) {
+  const autoStashFn = (_deps && _deps.autoStash) || autoStash;
+
   if (!isGitSafetyEnabled(config)) {
     return { allowed: true, blocked: false };
   }
@@ -253,16 +300,41 @@ function checkGitSafety(command, config) {
   // Handle: git checkout . / git restore .
   if (parsed.type === 'discard-all') {
     if (gitConfig.autoBackup) {
-      const stashed = autoStash();
+      const stashResult = autoStashFn();
+
+      // BUG-1 / wf-2d3d09b8: previously this branch returned `allowed:true`
+      // unconditionally — letting the destructive `git checkout .` /
+      // `git restore .` proceed even when the auto-backup stash silently
+      // failed, which destroyed the user's uncommitted work. Now we block on
+      // stash failure so the user can recover their work manually first.
+      if (stashResult && stashResult.status === 'failed') {
+        return {
+          allowed: false,
+          blocked: true,
+          reason: 'git-safety-stash-failed',
+          message:
+            `GIT SAFETY NET: Auto-backup stash FAILED.\n\n` +
+            `${stashResult.error || 'Unknown stash failure.'}\n\n` +
+            `Refusing to proceed with the discard operation — your uncommitted ` +
+            `work would be lost with no recovery path.\n\n` +
+            `Recover with one of:\n` +
+            `  - Commit your work first:    git add -A && git commit -m "WIP"\n` +
+            `  - Stash manually + verify:   git stash push -u -m "manual"; git stash list\n` +
+            `  - Checkpoint to a branch:    git checkout -b backup-WIP && git add -A && git commit -m "snapshot"\n\n` +
+            `Then re-run the discard command.`
+        };
+      }
+
+      const stashed = stashResult && stashResult.status === 'stashed';
       const stashMsg = stashed
-        ? 'Auto-stashed your changes before executing. Recover with: git stash pop'
+        ? `Auto-stashed your changes (${stashResult.stashRef}). Recover with: git stash pop`
         : 'No uncommitted changes to stash.';
 
       return {
         allowed: true,
         blocked: false,
         warning: true,
-        autoAction: 'stash',
+        autoAction: stashed ? 'stash' : 'no-op',
         message: `GIT SAFETY NET: ${stashMsg}\n\nProceeding with discard operation.`
       };
     }