forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/beads-sync-scaffold.js

@@ -3,6 +3,9 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { cleanupDeprecatedSyncFiles } = require('./deprecated-sync-cleanup');
+
+const DEFAULT_BEADS_VERSION = '1.0.0';
 
 /**
  * Detect the default branch of the repository.
@@ -60,7 +63,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 +86,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 +129,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);
@@ -137,124 +142,48 @@ function templateWorkflows(workflowDir, branch, beadsVersion, createdFiles = [])
   }
 }
 
-/**
- * @typedef {Object} ScaffoldResult
- * @property {string[]} filesCreated - Relative paths of files written (new or overwritten)
- * @property {string[]} filesSkipped - Relative paths of files that already existed and were preserved
- */
+function cleanupDeprecatedBeadsSync(projectRoot, options = {}) {
+  return cleanupDeprecatedSyncFiles(projectRoot, options);
+}
 
 /**
- * Copy a single file from src to dest, creating parent directories as needed.
- *
- * @param {string} src - Absolute source path
- * @param {string} dest - Absolute destination path
- * @returns {void}
+ * @typedef {Object} ScaffoldResult
+ * @property {string[]} filesCreated - Always empty; retained for deprecated API compatibility.
+ * @property {string[]} filesSkipped - Always empty; retained for deprecated API compatibility.
+ * @property {string[]} filesRemoved - Relative paths of deprecated generated sync files removed.
+ * @property {boolean} deprecated - Indicates the legacy scaffold path is deprecated.
+ * @property {string} message - Deprecation guidance for future sync direction.
  */
-function copyFileWithDirs(src, dest) {
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.copyFileSync(src, dest);
-}
 
 /**
- * Scaffold Beads sync workflows and scripts to the user's project.
+ * Deprecated compatibility shim for removed Beads/GitHub sync scaffolding.
  *
- * Copies workflow templates, sync modules, config, and mapping stub into
- * the project's `.github/` tree from the forge package source.
+ * Performs cleanup of generated legacy sync artifacts only. User-owned files
+ * at matching paths are preserved unless their content matches known generated
+ * templates.
  *
  * @param {string} projectRoot - Absolute path to the user's project root
  * @param {string} packageDir - Absolute path to the forge package install location
  * @param {Object} [_options={}] - Reserved for future options
- * @returns {ScaffoldResult}
+ * @returns {ScaffoldResult} Deprecated cleanup result.
  */
 function scaffoldBeadsSync(projectRoot, packageDir, _options = {}) {
-  /** @type {string[]} */
-  const filesCreated = [];
-  /** @type {string[]} */
-  const filesSkipped = [];
-
-  const githubDir = path.join(projectRoot, '.github');
-
-  // --- Step a: Copy workflow templates ---
-  const workflowNames = ['github-to-beads.yml', 'beads-to-github.yml'];
-  const srcWorkflowsDir = path.join(packageDir, '.github', 'workflows');
-
-  for (const name of workflowNames) {
-    const src = path.join(srcWorkflowsDir, name);
-    const relPath = `.github/workflows/${name}`;
-    const dest = path.join(projectRoot, '.github', 'workflows', name);
-
-    if (!fs.existsSync(src)) continue;
-    if (fs.existsSync(dest)) {
-      filesSkipped.push(relPath);
-    } else {
-      copyFileWithDirs(src, dest);
-      filesCreated.push(relPath);
-    }
-  }
-
-  // --- Step b: Copy sync modules ---
-  const srcSyncDir = path.join(packageDir, 'scripts', 'github-beads-sync');
-  const destSyncDir = path.join(githubDir, 'scripts', 'beads-sync');
-
-  if (fs.existsSync(srcSyncDir)) {
-    const entries = fs.readdirSync(srcSyncDir);
-    for (const entry of entries) {
-      const srcFile = path.join(srcSyncDir, entry);
-      const stat = fs.statSync(srcFile);
-      if (stat.isFile()) {
-        const relPath = `.github/scripts/beads-sync/${entry}`;
-        const dest = path.join(destSyncDir, entry);
-        if (fs.existsSync(dest)) {
-          filesSkipped.push(relPath);
-        } else {
-          copyFileWithDirs(srcFile, dest);
-          filesCreated.push(relPath);
-        }
-      }
-    }
-  }
-
-  // --- Step c: Create beads-sync-config.json ---
-  const configRelPath = '.github/beads-sync-config.json';
-  const configDest = path.join(githubDir, 'beads-sync-config.json');
-  const srcConfig = path.join(packageDir, 'scripts', 'github-beads-sync.config.json');
-
-  if (fs.existsSync(configDest)) {
-    filesSkipped.push(configRelPath);
-  } else if (fs.existsSync(srcConfig)) {
-    copyFileWithDirs(srcConfig, configDest);
-    filesCreated.push(configRelPath);
-  } else {
-    // Create a sensible default config
-    const defaultConfig = {
-      defaultType: 'task',
-      defaultPriority: 2,
-      mapAssignee: true,
-      publicRepoGate: 'none'
-    };
-    fs.mkdirSync(path.dirname(configDest), { recursive: true });
-    fs.writeFileSync(configDest, JSON.stringify(defaultConfig, null, 2) + '\n');
-    filesCreated.push(configRelPath);
-  }
-
-  // --- Step d: Create beads-mapping.json if not exists ---
-  const mappingRelPath = '.github/beads-mapping.json';
-  const mappingDest = path.join(githubDir, 'beads-mapping.json');
-
-  if (fs.existsSync(mappingDest)) {
-    filesSkipped.push(mappingRelPath);
-  } else {
-    fs.mkdirSync(path.dirname(mappingDest), { recursive: true });
-    fs.writeFileSync(mappingDest, '{}');
-    filesCreated.push(mappingRelPath);
-  }
-
-  return { filesCreated, filesSkipped };
+  const cleanup = cleanupDeprecatedBeadsSync(projectRoot, { packageDir });
+
+  return {
+    filesCreated: [],
+    filesSkipped: [],
+    filesRemoved: cleanup.removed,
+    deprecated: true,
+    message: 'Beads GitHub sync scaffolding is deprecated; future GitHub issue sync must use Forge Kernel/server authority.'
+  };
 }
 
 module.exports = {
+  DEFAULT_BEADS_VERSION,
   detectDefaultBranch,
   detectBeadsVersion,
   templateWorkflows,
+  cleanupDeprecatedBeadsSync,
   scaffoldBeadsSync,
 };

package/lib/codex-skills.js

@@ -2,6 +2,19 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const { populateAgentSkills } = require('./skills-sync');
+
+/**
+ * Codex's documented repo-local skill discovery directory, relative to a project
+ * root. Codex scans `.agents/skills/<name>/SKILL.md` from the current working
+ * directory up to the repo root (developers.openai.com/codex/skills). Unlike the
+ * GLOBAL `$CODEX_HOME/skills` install, this surface is COMMITTED to the repo (kept
+ * byte-identical to the canonical `skills/` source by a pre-commit sync hook and
+ * the drift gate), so a teammate who clones the repo WITHOUT running `forge setup`
+ * still gets the Forge skills/stages auto-discovered.
+ */
+const CODEX_REPO_SKILLS_DIR = '.agents/skills';
+
 function injectForgeAdapter(content, commandName) {
   const adapter = [
     '> Forge stage adapter',
@@ -20,7 +33,10 @@ function injectForgeAdapter(content, commandName) {
 }
 
 function listCodexSkillEntries(sourceRoot) {
-  const skillsDir = path.join(sourceRoot, '.codex', 'skills');
+  // Read from the canonical `skills/` source (single source of truth) rather than
+  // a committed `.codex/skills` mirror. The GLOBAL `$CODEX_HOME/skills` install is
+  // generated from these entries with the stage adapter injected below.
+  const skillsDir = path.join(sourceRoot, 'skills');
 
   if (!fs.existsSync(skillsDir)) {
     return [];
@@ -94,10 +110,44 @@ function buildCodexSkillInstallPlan(sourceRoot, options = {}) {
   }));
 }
 
+/**
+ * Absolute path to a project's repo-local Codex skill discovery dir.
+ *
+ * @param {string} projectRoot - The project/repo root.
+ * @returns {string} `<projectRoot>/.agents/skills`.
+ */
+function resolveCodexRepoSkillsDir(projectRoot) {
+  return path.join(projectRoot, '.agents', 'skills');
+}
+
+/**
+ * Generate the repo-local Codex skill discovery mirror (`.agents/skills`) from
+ * the canonical `skills/` source.
+ *
+ * Content matches the other harness mirrors byte-for-byte (raw canonical — the
+ * `$CODEX_HOME` stage adapter is NOT injected here) so the skills-sync drift gate
+ * can enforce it, and so repo-local discovery reaches parity with the
+ * `.claude/skills` / `.cursor/skills` discovery surfaces.
+ *
+ * @param {object} params
+ * @param {string} params.sourceRoot - Root containing the canonical `skills/` dir.
+ * @param {string} params.projectRoot - Target project/repo root.
+ * @param {boolean} [params.clean=false] - Remove stale canonical-managed dirs first.
+ * @returns {{targetSkillsDir: string, written: string[]}}
+ */
+function populateCodexRepoSkills({ sourceRoot, projectRoot, clean = false }) {
+  const targetSkillsDir = resolveCodexRepoSkillsDir(projectRoot);
+  const { written } = populateAgentSkills({ sourceRoot, targetSkillsDir, clean });
+  return { targetSkillsDir, written };
+}
+
 module.exports = {
+  CODEX_REPO_SKILLS_DIR,
   buildCodexSkillInstallPlan,
   formatCodexSkillsInstallDir,
   listCodexSkillEntries,
+  populateCodexRepoSkills,
   resolveCodexHome,
+  resolveCodexRepoSkillsDir,
   resolveCodexSkillsInstallDir,
 };