forge-workflow 0.0.10 → 0.1.0-beta.3

package/docs/VALIDATION.md

@@ -1,363 +0,0 @@
-# Validation & Enforcement
-
-Forge includes built-in validation and TDD enforcement to ensure quality and consistency.
-
-## Table of Contents
-
-- [Git Hooks](#git-hooks)
-- [Validation CLI](#validation-cli)
-- [Validators by Stage](#validators-by-stage)
-- [Override Mechanisms](#override-mechanisms)
-- [Configuration](#configuration)
-
----
-
-## Git Hooks
-
-Forge uses [Lefthook](https://github.com/evilmartians/lefthook) for fast, language-agnostic git hooks.
-
-### Pre-Commit Hook
-
-**Purpose**: Enforce TDD by blocking commits of source code without tests.
-
-**Trigger**: Before every commit
-
-**Checks**:
-- Detects staged source files (`.js`, `.ts`, `.py`, `.go`, `.java`, `.rb`, etc.)
-- Verifies corresponding test files exist (`.test.js`, `.spec.ts`, etc.)
-- Excludes config files, test files, and documentation
-
-**Behavior**:
-When source code lacks tests, offers guided recovery:
-
-```
-⚠️  Looks like you're committing source code without tests:
-
-  - src/user-service.js
-
-📋 TDD Reminder:
-  Write tests BEFORE implementation (RED-GREEN-REFACTOR)
-
-What would you like to do?
-  1. Unstage source files (keep tests staged)
-  2. Continue anyway (I have a good reason)
-  3. Abort commit (let me add tests)
-
-Your choice (1-3):
-```
-
-**Override**:
-```bash
-git commit --no-verify  # Skip in emergencies
-```
-
-### Pre-Push Hook
-
-**Purpose**: Ensure all tests pass before pushing to remote.
-
-**Trigger**: Before every push
-
-**Checks**:
-- Runs `bun test`
-- Verifies all tests pass
-
-**Override**:
-```bash
-LEFTHOOK=0 git push  # Skip all hooks
-```
-
----
-
-## Validation CLI
-
-The `forge-preflight` CLI checks prerequisites for each workflow stage.
-
-### Usage
-
-```bash
-forge-preflight <command>
-```
-
-### Commands
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `status` | Check project prerequisites | Setup, onboarding |
-| `dev` | Validate before `/dev` | Before implementation |
-| `ship` | Validate before `/ship` | Before creating PR |
-
----
-
-## Validators by Stage
-
-### `forge-preflight status`
-
-**Purpose**: Check basic project setup
-
-**Checks**:
-- ✓ Git repository initialized
-- ✓ `package.json` exists
-- ✓ Test framework configured (`bun test` script)
-- ✓ Node.js installed
-
-**Example**:
-```bash
-$ forge-preflight status
-
-Checking project prerequisites...
-
-Validation Results:
-
-  ✓ Git repository
-  ✓ package.json exists
-  ✓ Test framework configured
-  ✓ Node.js installed
-
-✅ All checks passed!
-```
-
----
-
-### `forge-preflight dev`
-
-**Purpose**: Validate before starting implementation (`/dev`)
-
-**Checks**:
-- ✓ On feature branch (`feat/*`, `fix/*`, `docs/*`)
-- ✓ Plan file exists (`docs/plans/*.md`)
-- ✓ Research file exists (`docs/research/*.md`)
-- ✓ Test directory exists
-
-**Example**:
-```bash
-$ forge-preflight dev
-
-Validating prerequisites for /dev stage...
-
-Validation Results:
-
-  ✓ On feature branch
-  ✓ Plan file exists
-  ✓ Research file exists
-  ✓ Test directory exists
-
-✅ All checks passed!
-```
-
-**Failed Example**:
-```bash
-$ forge-preflight dev
-
-Validating prerequisites for /dev stage...
-
-Validation Results:
-
-  ✗ On feature branch
-    Not on a feature branch. Create one: git checkout -b feat/your-feature
-  ✓ Plan file exists
-  ✗ Research file exists
-    No research file found in docs/research/. Run: /research
-
-❌ Some checks failed. Please fix the issues above.
-```
-
----
-
-### `forge-preflight ship`
-
-**Purpose**: Validate before creating PR (`/ship`)
-
-**Checks**:
-- ✓ Tests exist (`.test.js`, `.spec.ts` files)
-- ✓ Tests pass (`bun test` succeeds)
-- ✓ Documentation updated (`README.md` or `docs/`)
-- ✓ No uncommitted changes
-
-**Example**:
-```bash
-$ forge-preflight ship
-
-Validating prerequisites for /ship stage...
-
-Validation Results:
-
-  ✓ Tests exist
-  ✓ Tests pass
-  ✓ Documentation updated
-  ✓ No uncommitted changes
-
-✅ All checks passed!
-```
-
----
-
-## Override Mechanisms
-
-### Git Hooks
-
-**Emergency Override** (use sparingly):
-
-```bash
-# Skip pre-commit hook
-git commit --no-verify -m "Emergency hotfix"
-
-# Skip pre-push hook
-LEFTHOOK=0 git push
-```
-
-**When to use**:
-- Emergency hotfixes
-- Work-in-progress commits (before pushing)
-- Non-code commits (docs, config)
-
-**When NOT to use**:
-- Regular development
-- Public repositories
-- Production deployments
-
-### Validation CLI
-
-The CLI provides guidance but doesn't block actions. You can proceed manually if checks fail.
-
----
-
-## Configuration
-
-### Lefthook Configuration
-
-Edit `lefthook.yml` to customize hooks:
-
-```yaml
-pre-commit:
-  commands:
-    tdd-check:
-      run: node .forge/hooks/check-tdd.js
-      stage_fixed: false
-      tags: tdd
-      glob: "*.{js,ts,jsx,tsx,py,go,java,rb}"
-
-pre-push:
-  commands:
-    tests:
-      run: bun test
-      tags: tests
-```
-
-**Options**:
-- `run`: Command to execute
-- `stage_fixed`: Auto-stage modified files (false = safer)
-- `tags`: Categorize hooks
-- `glob`: File patterns to trigger hook
-
-### Custom Test Patterns
-
-Edit `.forge/hooks/check-tdd.js` to add custom test patterns:
-
-```javascript
-// Around line 72
-const testPatterns = [
-  `${basename}.test${ext}`,
-  `${basename}.spec${ext}`,
-  `test/${basename}.test${ext}`,
-  `tests/${basename}.test${ext}`,
-  `__tests__/${basename}.test${ext}`,
-  // Add custom patterns here
-  `${dir}/__tests__/${basename}${ext}`,
-  `spec/${basename}_spec${ext}`,  // RSpec style
-];
-```
-
-### Validation CLI Customization
-
-Edit `bin/forge-preflight.js` to add custom validators:
-
-```javascript
-function validateCustomStage() {
-  console.log('Validating custom stage...\n');
-
-  check('Custom check', () => {
-    // Your validation logic
-    return true;
-  }, 'Custom error message');
-
-  return printResults();
-}
-```
-
----
-
-## Installation
-
-Hooks are automatically installed when you run:
-
-```bash
-# Install lefthook (one-time)
-bun add -d lefthook
-
-# Set up Forge
-bunx forge setup
-```
-
-The hooks will be automatically installed in your project's `.git/hooks/` directory.
-
-**Manual installation** (if needed):
-
-```bash
-# If you prefer global installation
-bun install -g lefthook
-
-# Install hooks
-lefthook install
-```
-
----
-
-## Troubleshooting
-
-### Hooks not running
-
-```bash
-# Check lefthook installation
-lefthook version
-
-# Reinstall hooks
-lefthook install
-
-# Check git hooks directory
-ls -la .git/hooks/
-```
-
-### False positives
-
-If the hook incorrectly flags a file:
-
-1. **Short-term**: Use `--no-verify` to skip
-2. **Long-term**: Update exclusion patterns in `.forge/hooks/check-tdd.js`
-
-### Tests failing on push
-
-```bash
-# Run tests locally
-bun test
-
-# Fix failures, then
-git push
-```
-
----
-
-## Best Practices
-
-1. **Write tests first**: Let the hooks guide you to TDD
-2. **Don't abuse overrides**: Only use `--no-verify` in emergencies
-3. **Keep tests fast**: Pre-push hooks run on every push
-4. **Document exceptions**: If you override, explain why in commit message
-5. **Update validators**: Customize for your project's needs
-
----
-
-## See Also
-
-- [Workflow Guide](../AGENTS.md) - Complete 7-stage workflow
-- [TDD Guide](../CLAUDE.md) - TDD principles and practices
-- [Lefthook Docs](https://github.com/evilmartians/lefthook) - Full hook configuration

package/lib/agents/cline.plugin.json

@@ -1,29 +0,0 @@
-{
-  "id": "cline",
-  "name": "Cline",
-  "version": "1.0.0",
-  "description": "VS Code agent extension",
-  "homepage": "https://github.com/cline/cline",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "workflows": ".cline/workflows"
-  },
-  "files": {
-    "rootConfig": ".clinerules"
-  },
-  "support": {
-    "status": "deprecated",
-    "surface": "editor-native",
-    "install": {
-      "required": false,
-      "repairRequired": false
-    }
-  },
-  "setup": {
-    "copyCommands": true
-  }
-}

package/lib/agents/copilot.plugin.json

@@ -1,24 +0,0 @@
-{
-  "id": "copilot",
-  "name": "GitHub Copilot",
-  "version": "1.0.0",
-  "description": "GitHub's AI assistant with native instructions and prompts",
-  "homepage": "https://github.com/features/copilot",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "prompts": ".github/prompts",
-    "instructions": ".github/instructions"
-  },
-  "files": {
-    "rootConfig": ".github/copilot-instructions.md"
-  },
-  "setup": {
-    "needsConversion": true,
-    "promptFormat": true,
-    "customSetup": "copilot"
-  }
-}

package/lib/agents/kilocode.plugin.json

@@ -1,22 +0,0 @@
-{
-  "id": "kilocode",
-  "name": "Kilo Code",
-  "version": "1.0.0",
-  "description": "VS Code extension with native workflows, rules, and skills",
-  "homepage": "https://marketplace.visualstudio.com/items?itemName=kilo-code",
-  "capabilities": {
-    "commands": true,
-    "skills": true,
-    "hooks": false
-  },
-  "directories": {
-    "workflows": ".kilocode/workflows",
-    "rules": ".kilocode/rules",
-    "skills": ".kilocode/skills/forge-workflow"
-  },
-  "setup": {
-    "copyRules": true,
-    "createSkill": true,
-    "needsConversion": true
-  }
-}

package/lib/agents/opencode.plugin.json

@@ -1,23 +0,0 @@
-{
-  "id": "opencode",
-  "name": "OpenCode",
-  "version": "1.0.0",
-  "description": "Open-source agent with native config and agent definitions",
-  "homepage": "https://opencode.ai",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "commands": ".opencode/commands",
-    "agents": ".opencode/agents"
-  },
-  "files": {
-    "rootConfig": "opencode.json"
-  },
-  "setup": {
-    "copyCommands": true,
-    "customSetup": "opencode"
-  }
-}

package/lib/agents/roo.plugin.json

@@ -1,30 +0,0 @@
-{
-  "id": "roo",
-  "name": "Roo Code",
-  "version": "1.0.0",
-  "description": "Cline fork with modes",
-  "homepage": "https://github.com/roocode/roo",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "commands": ".roo/commands"
-  },
-  "files": {
-    "rootConfig": ".roorules"
-  },
-  "support": {
-    "status": "deprecated",
-    "surface": "editor-native",
-    "install": {
-      "required": false,
-      "repairRequired": false
-    }
-  },
-  "setup": {
-    "copyCommands": true,
-    "needsConversion": true
-  }
-}

package/lib/beads-bootstrap.js

@@ -1,225 +0,0 @@
-'use strict';
-
-const { execFileSync } = require('node:child_process');
-const fs = require('node:fs');
-const path = require('node:path');
-const { safeBeadsInit } = require('./beads-setup');
-
-function isIgnorableFsError(error) {
-  return ['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM'].includes(error?.code);
-}
-
-function isRecoverableCommandError(error) {
-  return error?.code === 'ENOENT' || typeof error?.status === 'number';
-}
-
-function hasBackupJsonl(backupDir, fsApi) {
-  try {
-    return fsApi.readdirSync(backupDir).some((entry) => entry.endsWith('.jsonl'));
-  } catch (err) {
-    if (isIgnorableFsError(err)) {
-      return false;
-    }
-    throw err;
-  }
-}
-
-function resolveMainWorktree(projectRoot, exec) {
-  try {
-    const commonDir = exec('git', ['rev-parse', '--git-common-dir'], {
-      cwd: projectRoot,
-      encoding: 'utf8',
-      stdio: 'pipe'
-    }).trim();
-    return path.resolve(projectRoot, commonDir, '..');
-  } catch (err) {
-    if (isRecoverableCommandError(err)) {
-      return projectRoot;
-    }
-    throw err;
-  }
-}
-
-function isRecoverableBeadsError(error) {
-  const message = error?.message ?? String(error ?? '');
-  return (
-    /database(?:\s+[^\s]+)?\s+not found/i.test(message) ||
-    message.includes('failed to open database') ||
-    message.includes('no beads configuration found')
-  );
-}
-
-function readMetadataDatabaseName(projectRoot, fsApi) {
-  const metadataPath = path.resolve(projectRoot, '.beads', 'metadata.json');
-  if (!fsApi.existsSync(metadataPath)) {
-    return null;
-  }
-
-  try {
-    const metadata = JSON.parse(fsApi.readFileSync(metadataPath, 'utf8'));
-    if (typeof metadata.dolt_database === 'string' && metadata.dolt_database.trim()) {
-      return metadata.dolt_database.trim();
-    }
-  } catch (err) {
-    if (err instanceof SyntaxError || isIgnorableFsError(err)) {
-      return null;
-    }
-    throw err;
-  }
-
-  return null;
-}
-
-function stageExistingBeadsDest(beadsDest, fsApi) {
-  if (!fsApi.existsSync(beadsDest)) {
-    return null;
-  }
-
-  const stagedDest = `${beadsDest}.bootstrap-backup`;
-  if (fsApi.existsSync(stagedDest) && typeof fsApi.rmSync === 'function') {
-    fsApi.rmSync(stagedDest, { recursive: true, force: true });
-  }
-
-  if (typeof fsApi.renameSync === 'function') {
-    fsApi.renameSync(beadsDest, stagedDest);
-    return stagedDest;
-  }
-
-  if (typeof fsApi.rmSync === 'function') {
-    fsApi.rmSync(beadsDest, { recursive: true, force: true });
-  }
-
-  return null;
-}
-
-function restoreStagedBeadsDest(beadsDest, stagedDest, fsApi) {
-  if (!stagedDest || fsApi.existsSync(beadsDest) || typeof fsApi.renameSync !== 'function') {
-    return;
-  }
-
-  fsApi.renameSync(stagedDest, beadsDest);
-}
-
-function cleanupStagedBeadsDest(stagedDest, fsApi) {
-  if (!stagedDest || !fsApi.existsSync(stagedDest) || typeof fsApi.rmSync !== 'function') {
-    return;
-  }
-
-  fsApi.rmSync(stagedDest, { recursive: true, force: true });
-}
-
-function tryLinkBeadsSource(beadsSource, beadsDest, platform, fsApi) {
-  if (!fsApi.existsSync(beadsSource)) {
-    return false;
-  }
-
-  const stagedDest = stageExistingBeadsDest(beadsDest, fsApi);
-
-  try {
-    if (platform === 'win32') {
-      fsApi.symlinkSync(beadsSource, beadsDest, 'junction');
-    } else {
-      fsApi.symlinkSync(beadsSource, beadsDest);
-    }
-
-    cleanupStagedBeadsDest(stagedDest, fsApi);
-    return true;
-  } catch (symlinkErr) {
-    restoreStagedBeadsDest(beadsDest, stagedDest, fsApi);
-    if (symlinkErr.code !== 'EPERM') {
-      throw symlinkErr;
-    }
-    return false;
-  }
-}
-
-function buildInitArgs(mainProjectRoot, projectRoot, fsApi) {
-  const metadataDatabaseName = readMetadataDatabaseName(mainProjectRoot, fsApi)
-    || readMetadataDatabaseName(projectRoot, fsApi);
-  const initArgs = ['init', '--force'];
-  if (metadataDatabaseName) {
-    initArgs.push('--database', metadataDatabaseName);
-  }
-
-  return initArgs;
-}
-
-function runFreshInit(projectRoot, mainProjectRoot, beadsSource, initArgs, exec, runSafeBeadsInit, fsApi) {
-  const safeInitResult = runSafeBeadsInit(projectRoot, {
-    prefix: path.basename(mainProjectRoot),
-    execBdInit: (root) => {
-      exec('bd', initArgs, { cwd: root, stdio: 'pipe' });
-    }
-  });
-
-  if (!safeInitResult.success) {
-    const initMessage = safeInitResult.errors?.[0]
-      || safeInitResult.warnings?.[0]
-      || 'unknown safeBeadsInit failure';
-    return {
-      success: false,
-      strategy: 'fresh-init-failed',
-      warning: `Beads bootstrap fresh init failed: ${initMessage}`
-    };
-  }
-
-  if (safeInitResult.skipped) {
-    return {
-      success: true,
-      strategy: 'existing-state',
-      warning: 'Beads bootstrap reused existing initialized state'
-    };
-  }
-
-  const backupDir = path.resolve(beadsSource, 'backup');
-  if (hasBackupJsonl(backupDir, fsApi)) {
-    try {
-      exec('bd', ['backup', 'restore', backupDir], { cwd: projectRoot, stdio: 'pipe' });
-      return {
-        success: true,
-        strategy: 'backup-restore',
-        warning: 'Beads bootstrap restored from backup'
-      };
-    } catch (restoreErr) {
-      return {
-        success: true,
-        strategy: 'fresh-init',
-        warning: `Beads bootstrap initialized fresh after backup restore failed: ${restoreErr.message}`
-      };
-    }
-  }
-
-  return {
-    success: true,
-    strategy: 'fresh-init',
-    warning: 'Beads bootstrap initialized fresh (no backup found)'
-  };
-}
-
-function bootstrapBeads(projectRoot, options = {}) {
-  const exec = options._exec || execFileSync;
-  const fsApi = options._fs || fs;
-  const platform = options._platform || process.platform;
-  const runSafeBeadsInit = options._safeBeadsInit || safeBeadsInit;
-  const mainProjectRoot = options.mainProjectRoot || resolveMainWorktree(projectRoot, exec);
-  const beadsSource = path.resolve(mainProjectRoot, '.beads');
-  const beadsDest = path.resolve(projectRoot, '.beads');
-
-  if (beadsSource === beadsDest) {
-    return { success: true, strategy: 'in-place', warning: null };
-  }
-
-  if (tryLinkBeadsSource(beadsSource, beadsDest, platform, fsApi)) {
-    return { success: true, strategy: 'linked', warning: null };
-  }
-
-  const initArgs = buildInitArgs(mainProjectRoot, projectRoot, fsApi);
-  return runFreshInit(projectRoot, mainProjectRoot, beadsSource, initArgs, exec, runSafeBeadsInit, fsApi);
-}
-
-module.exports = {
-  bootstrapBeads,
-  hasBackupJsonl,
-  isRecoverableBeadsError,
-  resolveMainWorktree,
-};