code-foundry 0.27.17 → 0.28.0

package/.github/workflows/release.yml

@@ -8,6 +8,16 @@ on:
         required: false
         type: string
         default: ubuntu-slim
+      runtime-repository:
+        description: Repository containing the Code Foundry runtime.
+        required: false
+        type: string
+        default: 0xPlayerOne/code-foundry
+      runtime-ref:
+        description: Code Foundry runtime tag or ref.
+        required: false
+        type: string
+        default: v0.27.18
 
 permissions:
   contents: write
@@ -71,6 +81,16 @@ jobs:
             `release_type=${releaseType}\nlegacy_release_type=${legacyReleaseType}\nnpm_publish=${npmPublish}\n`,
           )
           NODE
+      - name: Detect release credentials
+        id: credentials
+        env:
+          RELEASE_PLEASE_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+        run: |
+          if [ -n "$RELEASE_PLEASE_TOKEN" ]; then
+            echo "auto_merge=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "auto_merge=false" >> "$GITHUB_OUTPUT"
+          fi
       - name: Release Please
         id: release
         if: steps.profile.outputs.release_type != 'none'
@@ -79,10 +99,14 @@ jobs:
           token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
           config-file: release-please-config.json
           release-type: ${{ steps.profile.outputs.legacy_release_type }}
+      - name: Leave release pull request for manual merge
+        if: steps.release.outputs.prs_created == 'true' && steps.credentials.outputs.auto_merge != 'true'
+        run: |
+          echo "::notice title=Manual release merge required::Release Please created or updated a version pull request. RELEASE_PLEASE_TOKEN is not configured, so Code Foundry skipped guarded auto-merge. Configure the token before merging when downstream release workflows must run automatically."
       - name: Merge generated version pull requests
-        if: steps.release.outputs.prs_created == 'true'
+        if: steps.release.outputs.prs_created == 'true' && steps.credentials.outputs.auto_merge == 'true'
         env:
-          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
         run: |
           set -euo pipefail
 
@@ -154,6 +178,47 @@ jobs:
               --delete-branch
           done
 
+  reconcile:
+    name: Release / Reconcile
+    needs: release
+    if: needs.release.outputs.release_created == 'true'
+    runs-on: ${{ inputs.runner }}
+    timeout-minutes: 15
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Checkout runtime
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ inputs.runtime-repository }}
+          ref: ${{ inputs.runtime-ref }}
+          path: .code-foundry
+          sparse-checkout: |
+            src
+            release-please-config.json
+      - name: Check staging branch
+        id: staging
+        run: |
+          if git ls-remote --exit-code origin refs/heads/staging >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            git fetch --no-tags origin main staging
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Reconcile release metadata
+        if: steps.staging.outputs.exists == 'true'
+        run: node .code-foundry/src/cli.mjs release reconcile --github --base main --head staging
+      - name: Skip without staging
+        if: steps.staging.outputs.exists != 'true'
+        run: echo 'No staging branch exists; release reconciliation is not applicable.'
+
   npm:
     name: Release / Publish npm
     needs: release

package/.github/workflows/release_self-ci.yml

@@ -17,4 +17,6 @@ jobs:
     uses: ./.github/workflows/release.yml
     with:
       runner: ubuntu-slim
+      runtime-repository: 0xPlayerOne/code-foundry
+      runtime-ref: v0.27.18
     secrets: inherit

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.28.0](https://github.com/0xPlayerOne/code-foundry/compare/v0.27.18...v0.28.0) (2026-07-29)
+
+
+### Features
+
+* **release:** reconcile staging after release metadata ([4de1ad6](https://github.com/0xPlayerOne/code-foundry/commit/4de1ad64bd9276344368934ab555e6cb31a90784))
+
+## [0.27.18](https://github.com/0xPlayerOne/code-foundry/compare/v0.27.17...v0.27.18) (2026-07-29)
+
+
+### Bug Fixes
+
+* **release:** degrade gracefully without release token ([69ac43a](https://github.com/0xPlayerOne/code-foundry/commit/69ac43acfa2813495b8da0535942afbbedae3017))
+
 ## [0.27.17](https://github.com/0xPlayerOne/code-foundry/compare/v0.27.16...v0.27.17) (2026-07-29)
 
 

package/docs/RELEASES.md

@@ -29,8 +29,8 @@ body. Existing `CHANGELOG.md` history remains repository-owned.
 Set these values in `.github/code-foundry.yml`:
 
 ```yaml
-release_type: auto   # auto, node, python, rust, simple, or none
-npm_publish: false   # true only for an npm package
+release_type: auto # auto, node, python, rust, simple, or none
+npm_publish: false # true only for an npm package
 ```
 
 `auto` selects a supported manifest. Use `simple` with `version.txt` for a
@@ -39,9 +39,16 @@ not release automatically.
 
 ## Pull request permissions
 
-If the default `GITHUB_TOKEN` cannot create pull requests, configure a narrowly
-scoped `RELEASE_PLEASE_TOKEN` repository or organization secret. The release
-workflow needs `contents`, `issues`, and `pull-requests` permissions.
+Release Please falls back to the repository's `GITHUB_TOKEN` when a
+`RELEASE_PLEASE_TOKEN` secret is unavailable. In that mode, Code Foundry opens
+or updates the version pull request, leaves it for manual merge, and completes
+the release job successfully.
+
+Configure a narrowly scoped `RELEASE_PLEASE_TOKEN` repository or organization
+secret to enable guarded automatic merging and downstream workflows triggered
+by the resulting release. The token needs `contents`, `issues`, and
+`pull-requests` write permissions. Code Foundry validates every changed path in
+the generated version pull request before using the token to merge it.
 
 ## Operational checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.27.17",
+  "version": "0.28.0",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/cli.mjs

@@ -4,11 +4,12 @@
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { doctor } from './commands/doctor.mjs'
+import { reconcileRelease } from './commands/release.mjs'
 import { syncRepository } from './commands/sync.mjs'
 
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
 
-/** @typedef {{ target: string, dryRun: boolean, force: boolean }} Options */
+/** @typedef {{ target: string, dryRun: boolean, force: boolean, github: boolean, base: string, head: string }} Options */
 /** @typedef {{ command: string, options: Options }} ParsedArgs */
 
 const usage = `code-foundry — initialize and maintain agent-ready repositories
@@ -17,6 +18,7 @@ Usage:
   npx code-foundry init [--target PATH]
   npx code-foundry sync [--target PATH]
   npx code-foundry doctor [--target PATH]
+  npx code-foundry release reconcile [--github] [--base BRANCH] [--head BRANCH]
 
 The repository configuration lives in .github/code-foundry.yml.
 init detects the repository, creates that file, and renders the baseline.
@@ -26,6 +28,9 @@ Options:
   --target PATH   Repository directory (default: current directory)
   --dry-run       Preview changes without writing files
   --force         Replace protected standard documents
+  --github        Apply a verified fast-forward through GitHub
+  --base BRANCH   Release source branch (default: main)
+  --head BRANCH   Branch to reconcile (default: staging)
   -h, --help      Show this help
 `
 
@@ -40,7 +45,12 @@ function parseArgs(argv) {
   const first = argv[0]
   const hasCommand = Boolean(first && !first.startsWith('-'))
   const command = hasCommand ? /** @type {string} */ (argv.shift()) : 'init'
-  const options = { target: process.cwd(), dryRun: false, force: false }
+  const options = { target: process.cwd(), dryRun: false, force: false, github: false, base: 'main', head: 'staging' }
+
+  if (command === 'release') {
+    const subcommand = argv.shift()
+    if (subcommand !== 'reconcile') fail(`unknown release command: ${subcommand ?? '(missing)'}; use release reconcile`)
+  }
 
   while (argv.length) {
     const arg = argv.shift()
@@ -54,6 +64,9 @@ function parseArgs(argv) {
       options.target = value
     } else if (arg === '--dry-run') options.dryRun = true
     else if (arg === '--force') options.force = true
+    else if (arg === '--github') options.github = true
+    else if (arg === '--base') options.base = argv.shift() ?? fail('--base requires a branch')
+    else if (arg === '--head') options.head = argv.shift() ?? fail('--head requires a branch')
     else fail(`unknown option: ${arg}; run --help for the supported options`)
   }
 
@@ -83,6 +96,12 @@ function main() {
       console.error(`code-foundry: ${error instanceof Error ? error.message : String(error)}`)
       process.exitCode = 1
     }
+  } else if (command === 'release') {
+    try {
+      reconcileRelease(target, options)
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error))
+    }
   }
   else fail(`unknown command: ${command}`)
 }

package/src/commands/release.mjs

@@ -0,0 +1,64 @@
+// @ts-check
+
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { approvedReleaseFiles, classifyReconciliation, readReleaseConfig } from '../lib/release-policy.mjs'
+
+/** @typedef {{ target: string, dryRun: boolean, github: boolean, base: string, head: string }} ReleaseOptions */
+
+/**
+ * Reconcile staging after Release Please updates main. The local mode is
+ * deterministic and suitable for CI; --github applies only a verified
+ * fast-forward through the GitHub API and otherwise fails closed.
+ * @param {string} root
+ * @param {ReleaseOptions} options
+ */
+export function reconcileRelease(root, options) {
+  const target = resolve(root)
+  const base = options.base || 'main'
+  const head = options.head || 'staging'
+  const mainSha = git(target, ['rev-parse', `origin/${base}`]) || git(target, ['rev-parse', base])
+  const stagingSha = git(target, ['rev-parse', `origin/${head}`]) || git(target, ['rev-parse', head])
+  const mergeBaseSha = git(target, ['merge-base', mainSha, stagingSha])
+  const mainChangedPaths = diffNames(target, mergeBaseSha, mainSha)
+  const stagingChangedPaths = diffNames(target, mergeBaseSha, stagingSha)
+  const plan = classifyReconciliation({
+    mainSha,
+    stagingSha,
+    mergeBaseSha,
+    mainChangedPaths,
+    stagingChangedPaths,
+    allowed: approvedReleaseFiles(readReleaseConfig(target)),
+  })
+  console.log(JSON.stringify({ base, head, ...plan }, null, 2))
+  if (plan.action === 'fail') throw new Error(plan.reason + (plan.unexpected?.length ? ` Unexpected paths: ${plan.unexpected.join(', ')}` : ''))
+  if (plan.action !== 'fast-forward' || !options.github || options.dryRun) return plan
+  if (!process.env.GITHUB_REPOSITORY) throw new Error('GITHUB_REPOSITORY is required for --github reconciliation.')
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+  if (!token) throw new Error('GH_TOKEN or GITHUB_TOKEN is required for --github reconciliation.')
+  const result = spawnSync('gh', [
+    'api', '--method', 'PATCH', `repos/${process.env.GITHUB_REPOSITORY}/git/refs/heads/${head}`,
+    '-f', `sha=${plan.targetSha}`, '-F', 'force=false',
+  ], { cwd: target, stdio: 'inherit', env: { ...process.env, GH_TOKEN: token } })
+  if (result.status !== 0) throw new Error(`GitHub refused the protected fast-forward of ${head}.`)
+  return plan
+}
+
+/** @param {string} root @param {string[]} args @returns {string} */
+function git(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : ''
+}
+
+/** @param {string} root @param {string} from @param {string} to @returns {string[]} */
+function diffNames(root, from, to) {
+  if (!from || !to || from === to) return []
+  const result = spawnSync('git', ['diff', '--name-only', from, to], { cwd: root, encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.split(/\r?\n/).filter(Boolean) : []
+}
+
+/** @param {string} root */
+export function releaseConfigExists(root) {
+  return existsSync(join(resolve(root), 'release-please-config.json'))
+}

package/src/lib/release-policy.mjs

@@ -0,0 +1,108 @@
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const DEFAULT_RELEASE_FILES = new Set([
+  '.release-please-manifest.json',
+  'CHANGELOG.md',
+  'Cargo.lock',
+  'Cargo.toml',
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'package.json',
+  'pnpm-lock.yaml',
+  'pyproject.toml',
+  'uv.lock',
+  'version.txt',
+  'yarn.lock',
+])
+
+/** @param {string} root @returns {Record<string, unknown>} */
+export function readReleaseConfig(root) {
+  const file = join(root, 'release-please-config.json')
+  if (!existsSync(file)) return {}
+  try { return JSON.parse(readFileSync(file, 'utf8')) }
+  catch { return {} }
+}
+
+/**
+ * Return the release files allowed to change during an automated reconciliation.
+ * Package manifests are scoped beneath their Release Please package directory.
+ * @param {Record<string, unknown>} config
+ * @returns {Set<string>}
+ */
+export function approvedReleaseFiles(config = {}) {
+  const allowed = new Set(DEFAULT_RELEASE_FILES)
+  addExtraFiles(allowed, config['extra-files'])
+  const packages = config.packages
+  if (packages && typeof packages === 'object' && !Array.isArray(packages)) {
+    for (const [directory, value] of Object.entries(packages)) {
+      const prefix = directory === '.' ? '' : directory.replace(/\/$/, '')
+      for (const file of DEFAULT_RELEASE_FILES) addPath(allowed, prefix, file)
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        addExtraFiles(allowed, value['extra-files'], prefix)
+      }
+    }
+  }
+  return allowed
+}
+
+/** @param {Set<string>} allowed @param {unknown} entries @param {string} [prefix] */
+function addExtraFiles(allowed, entries, prefix = '') {
+  if (!Array.isArray(entries)) return
+  for (const entry of entries) {
+    const path = typeof entry === 'string' ? entry : entry && typeof entry === 'object' && 'path' in entry ? entry.path : ''
+    if (typeof path === 'string' && path) addPath(allowed, prefix, path)
+  }
+}
+
+/** @param {Set<string>} allowed @param {string} prefix @param {string} path */
+function addPath(allowed, prefix, path) {
+  const clean = path.replace(/^\.\//, '').replace(/\\/g, '/')
+  allowed.add(prefix ? `${prefix}/${clean}` : clean)
+}
+
+/** @param {string[]} paths @param {Set<string>} allowed @returns {string[]} */
+export function unexpectedReleasePaths(paths, allowed) {
+  return [...new Set(paths.map((path) => path.trim()).filter(Boolean))]
+    .filter((path) => !allowed.has(path))
+}
+
+/**
+ * Classify the relationship between main and staging. A fast-forward is safe
+ * only when main is the ancestor of staging or staging is the ancestor of main
+ * and the intervening main files are release metadata.
+ * @param {{ mainSha: string, stagingSha: string, mergeBaseSha?: string, mainChangedPaths?: string[], stagingChangedPaths?: string[], allowed?: Set<string> }} input
+ */
+export function classifyReconciliation(input) {
+  const {
+    mainSha,
+    stagingSha,
+    mergeBaseSha = '',
+    mainChangedPaths = [],
+    stagingChangedPaths = [],
+    allowed = approvedReleaseFiles(),
+  } = input
+  if (!mainSha || !stagingSha) return { action: 'fail', reason: 'Missing branch SHA.' }
+  if (mainSha === stagingSha) return { action: 'aligned', reason: 'Branches already point at the same commit.' }
+  if (mainSha === mergeBaseSha) {
+    return { action: 'none', reason: 'staging contains commits that are not on main; no release-only reconciliation is needed.' }
+  }
+  const unexpectedMain = unexpectedReleasePaths(mainChangedPaths, allowed)
+  const unexpectedStaging = unexpectedReleasePaths(stagingChangedPaths, allowed)
+  if (unexpectedMain.length || unexpectedStaging.length) {
+    return {
+      action: 'fail',
+      reason: 'Branch divergence includes repository code or configuration.',
+      unexpected: [...new Set([...unexpectedMain, ...unexpectedStaging])],
+    }
+  }
+  if (stagingSha === mergeBaseSha) {
+    return { action: 'fast-forward', targetSha: mainSha, reason: 'main only added approved release metadata.' }
+  }
+  return { action: 'pull-request', targetSha: mainSha, reason: 'Branches diverged, but only approved release metadata changed.' }
+}
+
+export { DEFAULT_RELEASE_FILES }