forge-workflow 0.0.9 → 0.0.10

package/lib/beads-bootstrap.js

@@ -0,0 +1,225 @@
+'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,
+};

package/lib/beads-health-check.js

@@ -10,6 +10,7 @@
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const { bootstrapBeads, isRecoverableBeadsError } = require('./beads-bootstrap');
 
 /**
  * @typedef {Object} HealthCheckResult
@@ -49,6 +50,46 @@ function cleanupTestIssue(jsonlPath, issueId) {
   fs.writeFileSync(jsonlPath, filtered.length > 0 ? filtered.join('\n') + '\n' : '');
 }
 
+function appendWarning(existingWarning, nextWarning) {
+  return existingWarning ? `${existingWarning}; ${nextWarning}` : nextWarning;
+}
+
+function createHealthCheckIssue(exec, execOpts) {
+  return exec('bd', [
+    'create',
+    '--title=Setup verification',
+    '--type=task',
+    '--priority=4'
+  ], execOpts);
+}
+
+function createIssueWithRecovery(projectRoot, exec, execOpts, bootstrap) {
+  try {
+    return { output: createHealthCheckIssue(exec, execOpts), warning: null };
+  } catch (createErr) {
+    if (!isRecoverableBeadsError(createErr)) {
+      throw createErr;
+    }
+
+    const bootstrapResult = bootstrap(projectRoot);
+    if (!bootstrapResult?.success) {
+      const extra = bootstrapResult?.warning ? `; ${bootstrapResult.warning}` : '';
+      return {
+        error: `${createErr.message}${extra}`
+      };
+    }
+
+    const bootstrapWarning = bootstrapResult.warning
+      ? `bootstrap warning: ${bootstrapResult.warning}`
+      : `bootstrap warning: recovered via ${bootstrapResult.strategy}`;
+
+    return {
+      output: createHealthCheckIssue(exec, execOpts),
+      warning: bootstrapWarning
+    };
+  }
+}
+
 /**
  * Run a Beads health check smoke test.
  *
@@ -62,6 +103,7 @@ function cleanupTestIssue(jsonlPath, issueId) {
  */
 function beadsHealthCheck(projectRoot, options = {}) {
   const exec = options._exec || execFileSync;
+  const bootstrap = options._bootstrap || ((root) => bootstrapBeads(root, { _exec: exec }));
   const execOpts = { cwd: projectRoot, encoding: 'utf8' };
 
   /** @type {string|undefined} */
@@ -71,14 +113,18 @@ function beadsHealthCheck(projectRoot, options = {}) {
   /** @type {string|null} */
   let issueId;
   try {
-    const createOutput = exec('bd', [
-      'create',
-      '--title=Setup verification',
-      '--type=task',
-      '--priority=4'
-    ], execOpts);
+    const createResult = createIssueWithRecovery(projectRoot, exec, execOpts, bootstrap);
+    if (createResult.error) {
+      return {
+        healthy: false,
+        failedStep: 'create',
+        error: createResult.error
+      };
+    }
+
+    warning = createResult.warning || warning;
 
-    issueId = parseIssueId(createOutput);
+    issueId = parseIssueId(createResult.output);
     if (!issueId) {
       return {
         healthy: false,
@@ -120,7 +166,7 @@ function beadsHealthCheck(projectRoot, options = {}) {
     exec('bd', ['sync'], execOpts);
   } catch (syncErr) {
     // Sync failure is non-fatal (no remote configured is common)
-    warning = `bd sync warning: ${syncErr.message}`;
+    warning = appendWarning(warning, `bd sync warning: ${syncErr.message}`);
   }
 
   // Step d: Remove the test issue from JSONL
@@ -128,8 +174,7 @@ function beadsHealthCheck(projectRoot, options = {}) {
     cleanupTestIssue(path.join(projectRoot, '.beads', 'issues.jsonl'), issueId);
   } catch (cleanupErr) {
     // Cleanup failure is non-fatal
-    const cleanupWarning = `cleanup warning: ${cleanupErr.message}`;
-    warning = warning ? `${warning}; ${cleanupWarning}` : cleanupWarning;
+    warning = appendWarning(warning, `cleanup warning: ${cleanupErr.message}`);
   }
 
   return {

package/lib/beads-setup.js

@@ -2,7 +2,7 @@
  * Utilities for configuring Beads during `forge setup`.
  *
  * Handles prefix sanitization, config/gitignore generation,
- * initialization detection, and issues.jsonl pre-seeding.
+ * initialization detection, and legacy JSONL compatibility shims.
  *
  * @module beads-setup
  */
@@ -10,6 +10,15 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { secureExecFileSync } = require('./shell-utils');
+
+function isIgnorableFsError(error) {
+  return ['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM'].includes(error?.code);
+}
+
+function isRecoverableCommandError(error) {
+  return error?.code === 'ENOENT' || typeof error?.status === 'number';
+}
 
 /**
  * Resolve a command to its full path to avoid relying on inherited PATH.
@@ -24,7 +33,10 @@ function resolveCommand(command) {
     if (result.status === 0 && result.stdout) {
       return result.stdout.trim().split(/\r?\n/)[0].trim();
     }
-  } catch (_e) {
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
     // Expected: command resolution may fail if 'which'/'where.exe' is unavailable — fall back to bare command name
   }
   return command;
@@ -108,10 +120,15 @@ function writeBeadsGitignore(projectRoot) {
 /**
  * Check whether Beads is properly initialized in a project.
  *
- * Returns `true` only when all of the following are present:
+ * Returns `true` when all of the following are present:
  * - `.beads/` directory exists
  * - `.beads/config.yaml` exists and contains an `issue-prefix` key
- * - `.beads/issues.jsonl` exists
+ * - the config points to either:
+ *   - a legacy SQLite tracker with legacy data markers present, or
+ *   - a Dolt-backed tracker with at least one post-`bd init` marker present
+ *
+ * Legacy SQLite-backed Beads installs also count as initialized so `forge setup`
+ * does not run `bd init` over an existing tracker before migration.
  *
  * @param {string} projectRoot - Absolute path to the project root
  * @returns {boolean} `true` if Beads is fully initialized
@@ -119,34 +136,74 @@ function writeBeadsGitignore(projectRoot) {
 function isBeadsInitialized(projectRoot) {
   const beadsDir = path.join(projectRoot, '.beads');
   const configPath = path.join(beadsDir, 'config.yaml');
-  const jsonlPath = path.join(beadsDir, 'issues.jsonl');
 
   if (!fs.existsSync(beadsDir)) return false;
   if (!fs.existsSync(configPath)) return false;
-  if (!fs.existsSync(jsonlPath)) return false;
 
   const configContent = fs.readFileSync(configPath, 'utf8');
   if (!configContent.includes('issue-prefix:')) return false;
 
-  return true;
+  const hasLegacyState = [
+    'issues.jsonl',
+    'backup',
+    'bd.db',
+    'beads.db',
+    'db.sqlite'
+  ].some((entry) => fs.existsSync(path.join(beadsDir, entry)));
+  const hasDoltMetadata = fs.existsSync(path.join(beadsDir, 'metadata.json'));
+  const hasDoltCompanionState = [
+    'README.md',
+    'hooks',
+    'redirect'
+  ].some((entry) => fs.existsSync(path.join(beadsDir, entry)));
+  const hasDoltState = hasDoltMetadata && hasDoltCompanionState;
+
+  if (configContent.includes('backend: sqlite')) {
+    return hasLegacyState;
+  }
+
+  if (configContent.includes('backend: dolt')) {
+    return hasDoltState;
+  }
+
+  return hasLegacyState || hasDoltState;
+}
+
+function readBeadsDatabaseName(projectRoot) {
+  const metadataPath = path.join(projectRoot, '.beads', 'metadata.json');
+  if (!fs.existsSync(metadataPath)) {
+    return null;
+  }
+
+  try {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    if (typeof metadata.dolt_database === 'string' && metadata.dolt_database.trim()) {
+      return metadata.dolt_database.trim();
+    }
+    if (typeof metadata.database === 'string' && metadata.database.trim()) {
+      return metadata.database.trim();
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError || isIgnorableFsError(error)) {
+      return null;
+    }
+    throw error;
+  }
+
+  return null;
 }
 
 /**
- * Ensure `issues.jsonl` exists inside `.beads/`.
+ * Legacy compatibility shim for the removed JSONL pre-seed workaround.
  *
- * Creates the `.beads/` directory and an empty `issues.jsonl` if either
- * is missing. Leaves an existing `issues.jsonl` untouched.
+ * Beads latest no longer requires `.beads/issues.jsonl` during init, so
+ * this helper intentionally does nothing. It remains exported because some
+ * older tests and setup paths still import it.
  *
- * @param {string} projectRoot - Absolute path to the project root
+ * @param {string} _projectRoot - Absolute path to the project root
  */
-function preSeedJsonl(projectRoot) {
-  const beadsDir = path.join(projectRoot, '.beads');
-  fs.mkdirSync(beadsDir, { recursive: true });
-
-  const jsonlPath = path.join(beadsDir, 'issues.jsonl');
-  if (!fs.existsSync(jsonlPath)) {
-    fs.writeFileSync(jsonlPath, '', 'utf8');
-  }
+function preSeedJsonl(_projectRoot) {
+  // Legacy no-op: Dolt-backed Beads no longer requires JSONL pre-seeding.
 }
 
 // ---------------------------------------------------------------------------
@@ -212,6 +269,31 @@ function restoreDirectory(dirPath, snapshot) {
   }
 }
 
+function resolveHooksDir(projectRoot) {
+  const fallbackHooksDir = path.join(projectRoot, '.git', 'hooks');
+
+  try {
+    const gitHooksPath = secureExecFileSync(resolveCommand('git'), ['rev-parse', '--git-path', 'hooks'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (!gitHooksPath) {
+      return fallbackHooksDir;
+    }
+
+    return path.isAbsolute(gitHooksPath)
+      ? gitHooksPath
+      : path.resolve(projectRoot, gitHooksPath);
+  } catch (error) {
+    if (isRecoverableCommandError(error)) {
+      return fallbackHooksDir;
+    }
+    throw error;
+  }
+}
+
 /**
  * Default bd init executor — calls `execFileSync('bd', ['init'])`.
  *
@@ -237,7 +319,7 @@ function defaultExecBdInit(projectRoot) {
  *   e. Run bd init (via execBdInit callback or default execFileSync)
  *   f. Restore .git/hooks/ from snapshot
  *   g. Restore lefthook hooks if callback provided
- *   h. Pre-seed issues.jsonl
+ *   h. Skip the removed issues.jsonl pre-seed workaround
  *
  * @param {string} projectRoot - Absolute path to the project root
  * @param {Object} [options={}] - Configuration options
@@ -279,7 +361,7 @@ function safeBeadsInit(projectRoot, options = {}) {
   }
 
   // (d) Snapshot current .git/hooks/ directory
-  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  const hooksDir = resolveHooksDir(projectRoot);
   const hooksSnapshot = snapshotDirectory(hooksDir);
 
   // (e) Run bd init — wrapped in try/catch
@@ -316,13 +398,6 @@ function safeBeadsInit(projectRoot, options = {}) {
     }
   }
 
-  // (h) Pre-seed JSONL if empty
-  try {
-    preSeedJsonl(projectRoot);
-  } catch (err) {
-    warnings.push(`Failed to pre-seed issues.jsonl: ${err.message}`);
-  }
-
   return {
     success: true,
     skipped: false,
@@ -336,6 +411,7 @@ module.exports = {
   writeBeadsConfig,
   writeBeadsGitignore,
   isBeadsInitialized,
+  readBeadsDatabaseName,
   preSeedJsonl,
   safeBeadsInit
 };

package/lib/beads-sync-scaffold.js

@@ -4,6 +4,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
+const DEFAULT_BEADS_VERSION = '1.0.0';
+
 /**
  * Detect the default branch of the repository.
  *
@@ -60,7 +62,7 @@ function detectDefaultBranch(projectRoot, options = {}) {
  *
  * Strategy (in order):
  *   1. `bd --version` -> parse version string (e.g. "beads version 0.52.0" -> "0.52.0")
- *   2. Fall back to known-good default `'0.49.1'`
+ *   2. Fall back to the current repo baseline release
  *
  * @param {object} [options] - Options object.
  * @param {Function} [options._exec] - Injected execFileSync for testing.
@@ -83,7 +85,7 @@ function detectBeadsVersion(options = {}) {
     // Expected: 'bd --version' fails when bd CLI is not installed — fall through to default version
   }
 
-  return '0.49.1';
+  return DEFAULT_BEADS_VERSION;
 }
 
 /**
@@ -126,10 +128,12 @@ function templateWorkflows(workflowDir, branch, beadsVersion, createdFiles = [])
       /branches:\s*\[master\]/g,
       `branches: [${branch}]`
     );
-    content = content.replaceAll(
-      /BD_VERSION="0\.49\.1"/g,
-      `BD_VERSION="${beadsVersion}"`
-    );
+    for (const version of ['0.49.1', DEFAULT_BEADS_VERSION, '__FORGE_BEADS_VERSION__']) {
+      content = content.replaceAll(
+        `BD_VERSION="${version}"`,
+        `BD_VERSION="${beadsVersion}"`
+      );
+    }
     // Only write if content actually changed
     if (content !== original) {
       fs.writeFileSync(filePath, content);
@@ -253,6 +257,7 @@ function scaffoldBeadsSync(projectRoot, packageDir, _options = {}) {
 }
 
 module.exports = {
+  DEFAULT_BEADS_VERSION,
   detectDefaultBranch,
   detectBeadsVersion,
   templateWorkflows,

package/lib/commands/_issue.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { execFileSync } = require('node:child_process');
+const { runIssueOperation } = require('../forge-issues');
 
 const SUBCOMMANDS = {
   create: {
@@ -110,14 +111,23 @@ function buildBdArgs(subcommand, rawArgs) {
   return spec.buildBdArgs(args);
 }
 
+const WRITE_SUBCOMMANDS = new Set(['create', 'update', 'claim', 'close']);
+
 async function runIssueSubcommand(subcommand, args, projectRoot, opts = {}) {
-  const exec = opts._exec || execFileSync;
   const bdArgs = buildBdArgs(subcommand, args);
 
   if (!Array.isArray(bdArgs)) {
     return { success: false, error: bdArgs.error };
   }
 
+  if (WRITE_SUBCOMMANDS.has(subcommand)) {
+    const runner = opts.runIssueOperation || runIssueOperation;
+    const operation = subcommand === 'claim' ? 'update' : subcommand;
+    return runner(operation, bdArgs.slice(1), projectRoot, opts);
+  }
+
+  const exec = opts._exec || execFileSync;
+
   try {
     exec('bd', bdArgs, getExecOptions(projectRoot));
     return { success: true, subcommand };

package/lib/commands/issues.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { runIssueOperation } = require('../forge-issues');
+
+const SUPPORTED_SUBCOMMANDS = ['create', 'list', 'show', 'close', 'update'];
+
+function normalizeArgs(args = []) {
+  return args.filter(arg => arg !== '--');
+}
+
+function formatHelp() {
+  return [
+    'Usage: forge issues <subcommand> [...]',
+    '',
+    'Supported subcommands:',
+    '  create  Create an issue through Forge',
+    '  list    List issues through Forge',
+    '  show    Show a single issue through Forge',
+    '  close   Close an issue through Forge',
+    '  update  Update an issue through Forge',
+  ].join('\n');
+}
+
+module.exports = {
+  name: 'issues',
+  description: 'Manage issues through the Forge authority layer',
+  usage: 'forge issues <subcommand> [...]',
+  flags: {},
+  handler: async (args, _flags, projectRoot, opts = {}) => {
+    const [subcommand, ...rest] = normalizeArgs(args);
+
+    if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+      return {
+        success: true,
+        output: formatHelp(),
+      };
+    }
+
+    if (!SUPPORTED_SUBCOMMANDS.includes(subcommand)) {
+      return {
+        success: false,
+        error: `Unknown issue subcommand '${subcommand}'.\n\n${formatHelp()}`,
+      };
+    }
+
+    const runner = opts.runIssueOperation || runIssueOperation;
+    return runner(subcommand, rest, projectRoot, opts);
+  },
+};