code-foundry 0.20.3 → 0.21.0

package/.github/scripts/init-repo.sh

@@ -12,6 +12,7 @@ languages="${REPO_FOUNDRY_LANGUAGES:-auto}"
 features="${REPO_FOUNDRY_FEATURES:-all}"
 package_manager="${REPO_FOUNDRY_PACKAGE_MANAGER:-auto}"
 runtime_repository="${REPO_FOUNDRY_RUNTIME_REPOSITORY:-}"
+runtime_ref="${REPO_FOUNDRY_RUNTIME_REF:-}"
 bootstrap=true
 release_type="${REPO_FOUNDRY_RELEASE_TYPE:-auto}"
 npm_publish="${REPO_FOUNDRY_NPM_PUBLISH:-false}"
@@ -39,6 +40,7 @@ Options:
                              ci,codeql,security,test,draft-pr,release-pr,release,dependabot
   --package-manager NAME     auto, bun, pnpm, yarn, or npm
   --runtime-repository OWNER/REPO  Reusable workflow runtime repository (auto from source)
+  --runtime-ref REF           Reusable workflow runtime tag or branch
   --release-type NAME        auto, node, python, rust, or simple
   --license NAME             agpl-3.0-or-later, mit, preserve, or none
   --license-file PATH        Use an exact custom license file
@@ -66,6 +68,7 @@ while [ "$#" -gt 0 ]; do
     --features) features="${2:?missing feature list}"; shift 2 ;;
     --package-manager) package_manager="${2:?missing package manager}"; shift 2 ;;
     --runtime-repository) runtime_repository="${2:?missing runtime repository}"; shift 2 ;;
+    --runtime-ref) runtime_ref="${2:?missing runtime ref}"; shift 2 ;;
     --release-type) release_type="${2:?missing release type}"; shift 2 ;;
     --license) license="${2:?missing license}"; shift 2 ;;
     --license-file) license_file="${2:?missing license file}"; shift 2 ;;
@@ -114,6 +117,7 @@ sync_args=(
   --license "$license"
 )
 if [ -n "$runtime_repository" ]; then sync_args+=(--runtime-repository "$runtime_repository"); fi
+if [ -n "$runtime_ref" ]; then sync_args+=(--runtime-ref "$runtime_ref"); fi
 if [ -n "$license_file" ]; then sync_args+=(--license-file "$license_file"); fi
 if [ "$dry_run" = true ]; then sync_args+=(--check); else sync_args+=(--apply); fi
 if [ "$prune" = true ]; then sync_args+=(--prune); fi
@@ -132,6 +136,7 @@ languages="$(awk -F': ' '/^languages:/ {print $2; exit}' .github/template.yml 2>
 features="$(awk -F': ' '/^features:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
 package_manager="$(awk -F': ' '/^package_manager:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
 runtime_repository="$(awk -F': ' '/^runtime_repository:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
+runtime_ref="$(awk -F': ' '/^runtime_ref:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
 release_type="$(awk -F': ' '/^release_type:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
 npm_publish="$(awk -F': ' '/^npm_publish:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
 license="$(awk -F': ' '/^license:/ {print $2; exit}' .github/template.yml 2>/dev/null || true)"
@@ -145,6 +150,7 @@ license="$(awk -F': ' '/^license:/ {print $2; exit}' .github/template.yml 2>/dev
   printf 'features: %s\n' "$features"
   printf 'package_manager: %s\n' "$package_manager"
   printf 'runtime_repository: %s\n' "$runtime_repository"
+  printf 'runtime_ref: %s\n' "$runtime_ref"
   printf 'release_type: %s\n' "$release_type"
   printf 'npm_publish: %s\n' "$npm_publish"
   printf 'license: %s\n' "$license"

package/.github/scripts/sync-template.sh

@@ -14,6 +14,7 @@ Options:
   --features LIST   all or comma-separated standard features
   --package-manager NAME  auto, bun, pnpm, yarn, or npm
   --runtime-repository OWNER/REPO  Reusable workflow runtime repository
+  --runtime-ref REF  Reusable workflow runtime tag or branch
   --license NAME     preserve, agpl-3.0-or-later, mit, or none
   --license-file PATH  Use an exact custom license file
   --check           Preview changes (default)
@@ -42,8 +43,11 @@ package_manager="${REPO_FOUNDRY_PACKAGE_MANAGER:-}"
 package_manager_set=false
 [ -n "${REPO_FOUNDRY_PACKAGE_MANAGER:-}" ] && package_manager_set=true
 runtime_repository="${REPO_FOUNDRY_RUNTIME_REPOSITORY:-}"
+runtime_ref="${REPO_FOUNDRY_RUNTIME_REF:-}"
 runtime_repository_set=false
 [ -n "${REPO_FOUNDRY_RUNTIME_REPOSITORY:-}" ] && runtime_repository_set=true
+runtime_ref_set=false
+[ -n "${REPO_FOUNDRY_RUNTIME_REF:-}" ] && runtime_ref_set=true
 template_ref=""
 release_type="${REPO_FOUNDRY_RELEASE_TYPE:-auto}"
 npm_publish="${REPO_FOUNDRY_NPM_PUBLISH:-false}"
@@ -109,6 +113,7 @@ while [ "$#" -gt 0 ]; do
     --features) features="${2:?missing feature list}"; features_set=true; shift 2 ;;
     --package-manager) package_manager="${2:?missing package manager}"; package_manager_set=true; shift 2 ;;
     --runtime-repository) runtime_repository="${2:?missing runtime repository}"; runtime_repository_set=true; shift 2 ;;
+    --runtime-ref) runtime_ref="${2:?missing runtime ref}"; runtime_ref_set=true; shift 2 ;;
     --license) license="${2:?missing license}"; license_set=true; shift 2 ;;
     --license-file) license_file="${2:?missing license file}"; shift 2 ;;
     --check) mode="check"; shift ;;
@@ -140,6 +145,9 @@ if [ -f .github/template.yml ]; then
   if [ "$runtime_repository_set" = false ]; then
     runtime_repository="$(awk -F': ' '/^runtime_repository:/ {print $2; exit}' .github/template.yml)"
   fi
+  if [ "$runtime_ref_set" = false ]; then
+    runtime_ref="$(awk -F': ' '/^runtime_ref:/ {print $2; exit}' .github/template.yml)"
+  fi
   template_ref="$(awk -F': ' '/^template:/ {print $2; exit}' .github/template.yml)"
   if [ "$release_type_set" != true ]; then
     configured_release_type="$(awk -F': ' '/^release_type:/ {print $2; exit}' .github/template.yml)"
@@ -196,6 +204,16 @@ else
   template_root="$temp_dir/template-repo"
 fi
 
+# Prefer an explicit CLI/environment value, then the target's saved contract,
+# then the source template's contract, and finally the stable public runtime.
+if [ -z "$runtime_ref" ] && [ -f "$template_root/.github/template.yml" ]; then
+  runtime_ref="$(awk -F': ' '/^runtime_ref:/ {print $2; exit}' "$template_root/.github/template.yml")"
+fi
+[ -n "$runtime_ref" ] || runtime_ref="v0.20.2"
+case "$runtime_ref" in
+  ''|*[!A-Za-z0-9._/-]*) printf 'Runtime ref contains unsupported characters: %s\n' "$runtime_ref" >&2; exit 2 ;;
+esac
+
 # Resolve the effective profile after the template is available. This gives
 # CLI flags and GitHub repository variables priority over template defaults,
 # while making automatic detection concrete in the generated profile.
@@ -206,6 +224,7 @@ if [ -f "$template_root/.github/scripts/profile.sh" ]; then
     REPO_FOUNDRY_FEATURES="$features" \
     REPO_FOUNDRY_PACKAGE_MANAGER="$package_manager" \
     REPO_FOUNDRY_RUNTIME_REPOSITORY="$runtime_repository" \
+    REPO_FOUNDRY_RUNTIME_REF="$runtime_ref" \
     REPO_FOUNDRY_RELEASE_TYPE="$release_type" \
     REPO_FOUNDRY_NPM_PUBLISH="$npm_publish" \
     bash "$template_root/.github/scripts/profile.sh" detect --root "$PWD"
@@ -374,19 +393,25 @@ done
 # selected runtime repository while leaving custom workflows untouched. Read
 # the source's configured runtime first so forks remain self-contained.
 source_runtime_repository=""
+source_runtime_ref=""
 if [ -f "$template_root/.github/template.yml" ]; then
   source_runtime_repository="$(awk -F': ' '/^runtime_repository:/ {print $2; exit}' "$template_root/.github/template.yml")"
+  source_runtime_ref="$(awk -F': ' '/^runtime_ref:/ {print $2; exit}' "$template_root/.github/template.yml")"
 fi
 [ -n "$source_runtime_repository" ] || source_runtime_repository="0xPlayerOne/code-foundry"
+[ -n "$source_runtime_ref" ] || source_runtime_ref="$runtime_ref"
 for file in .github/workflows/ci.yml .github/workflows/test.yml .github/workflows/security.yml .github/workflows/codeql.yml .github/workflows/draft-pr.yml .github/workflows/release-pr.yml .github/workflows/release.yml; do
   [ -f "$file" ] || continue
-  if grep -qF "$source_runtime_repository" "$file" && [ "$source_runtime_repository" != "$runtime_repository" ]; then
+  if grep -qF "$source_runtime_repository@" "$file" || grep -q 'runtime-ref:' "$file"; then
     changed=$((changed + 1))
     if [ "$mode" = "check" ]; then
       printf 'Would render runtime repository in %s\n' "$file"
     else
       rendered_workflow="$(mktemp)"
-      sed "s#${source_runtime_repository}#${runtime_repository}#g" "$file" > "$rendered_workflow"
+      sed -E \
+        -e "s#${source_runtime_repository}@[^[:space:]]+#${runtime_repository}@${runtime_ref}#g" \
+        -e "s#runtime-ref: [^[:space:]]+#runtime-ref: ${runtime_ref}#g" \
+        "$file" > "$rendered_workflow"
       mv "$rendered_workflow" "$file"
       printf 'Rendered runtime repository in %s\n' "$file"
     fi
@@ -566,6 +591,7 @@ if [ "$mode" = "apply" ]; then
       printf 'package_manager: %s\n' "$package_manager"
     fi
     printf 'runtime_repository: %s\n' "$runtime_repository"
+    printf 'runtime_ref: %s\n' "$runtime_ref"
     printf 'release_type: %s\n' "$release_type"
     printf 'npm_publish: %s\n' "$npm_publish"
     printf 'license: %s\n' "$license"

package/.github/template.yml

@@ -5,6 +5,7 @@ languages: typescript
 features: all
 package_manager: bun
 runtime_repository: 0xPlayerOne/code-foundry
+runtime_ref: v0.20.2
 release_type: node
 npm_publish: true
 license: agpl-3.0-or-later

package/.github/template.yml.example

@@ -6,6 +6,7 @@ languages: auto
 features: all
 package_manager: auto
 runtime_repository: 0xPlayerOne/code-foundry
+runtime_ref: v0.20.2
 release_type: auto
 npm_publish: false
 license: preserve

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.21.0](https://github.com/0xPlayerOne/code-foundry/compare/v0.20.3...v0.21.0) (2026-07-28)
+
+
+### Features
+
+* **runtime:** configure reusable workflow refs ([55f20d2](https://github.com/0xPlayerOne/code-foundry/commit/55f20d278f23ece1fed1166f1cad1b15c985ee90))
+
 ## [0.20.3](https://github.com/0xPlayerOne/code-foundry/compare/v0.20.2...v0.20.3) (2026-07-28)
 
 

package/README.md

@@ -42,7 +42,9 @@ runtime without extra flags. Use `--runtime-repository OWNER/REPO` (or
 `REPO_FOUNDRY_RUNTIME_REPOSITORY`) only when you want to override it. The
 selected repository is saved in `.github/template.yml` and rendered into the
 small CI, Test, Security, CodeQL, Draft PR, and Release PR wrappers
-automatically.
+automatically. Use `--runtime-ref REF` (or `REPO_FOUNDRY_RUNTIME_REF`) to pin
+those callers to a fork's release tag or branch; the selected ref is persisted
+alongside the runtime repository.
 
 Normal synchronization imports only the local hook, agent-facing command,
 profile/release, initializer, doctor, ownership, and protection entrypoints.
@@ -114,7 +116,7 @@ bash .github/scripts/init-repo.sh \
 
 Supported profiles are `application`, `monorepo`, and `minimal`; use `auto` to detect one. Supported languages are `typescript`, `rust`, `python`, and `solidity`. Supported feature flags are `ci`, `codeql`, `security`, `test`, `draft-pr`, `release-pr`, `release`, and `dependabot`. Use `--prune` only when you explicitly want disabled standard workflows removed; custom workflows are always preserved. The selected profile is stored in `.github/template.yml`, which makes later syncs repeatable and lets workflows consume repository-specific settings without duplicating the template scripts.
 
-Profile precedence is consistent everywhere: explicit CLI flags, then `REPO_FOUNDRY_*` GitHub repository variables/environment values, then `.github/template.yml`, then automatic detection and standard defaults. Useful repository variables include `REPO_FOUNDRY_PROFILE`, `REPO_FOUNDRY_LANGUAGES`, `REPO_FOUNDRY_FEATURES`, `REPO_FOUNDRY_PACKAGE_MANAGER`, `REPO_FOUNDRY_RUNTIME_REPOSITORY`, `REPO_FOUNDRY_RUNNER`, `REPO_FOUNDRY_UNIT_RUNNER`, `REPO_FOUNDRY_CACHE_PACKAGES`, `REPO_FOUNDRY_CACHE_BUILD`, `REPO_FOUNDRY_COVERAGE_MINIMUM`, and `REPO_FOUNDRY_TURBO_REMOTE`. Use CLI flags for one-off initialization; use repository variables for local overrides that should not be committed.
+Profile precedence is consistent everywhere: explicit CLI flags, then `REPO_FOUNDRY_*` GitHub repository variables/environment values, then `.github/template.yml`, then automatic detection and standard defaults. Useful repository variables include `REPO_FOUNDRY_PROFILE`, `REPO_FOUNDRY_LANGUAGES`, `REPO_FOUNDRY_FEATURES`, `REPO_FOUNDRY_PACKAGE_MANAGER`, `REPO_FOUNDRY_RUNTIME_REPOSITORY`, `REPO_FOUNDRY_RUNTIME_REF`, `REPO_FOUNDRY_RUNNER`, `REPO_FOUNDRY_UNIT_RUNNER`, `REPO_FOUNDRY_CACHE_PACKAGES`, `REPO_FOUNDRY_CACHE_BUILD`, `REPO_FOUNDRY_COVERAGE_MINIMUM`, and `REPO_FOUNDRY_TURBO_REMOTE`. Use CLI flags for one-off initialization; use repository variables for local overrides that should not be committed.
 
 Inspect the resolved profile at any time with `bash .github/scripts/profile.sh detect`; use `profile.sh get KEY` when another script needs one setting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.20.3",
+  "version": "0.21.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

@@ -23,6 +23,7 @@ Init/sync options:
   --features LIST           all or ci,codeql,security,test,draft-pr,release-pr,release,dependabot
   --package-manager NAME    auto, bun, pnpm, yarn, or npm
   --runtime-repository OWNER/REPO  Reusable workflow runtime repository
+  --runtime-ref REF          Reusable workflow runtime tag or branch
   --release-type NAME        auto, node, python, rust, simple, or none
   --license NAME             agpl-3.0-or-later, mit, preserve, or none
   --license-file PATH        Use an exact custom license file
@@ -54,6 +55,7 @@ function parseArgs(argv) {
     // initializer can then derive the runtime from --source, which keeps
     // organization forks plug-and-play.
     runtimeRepository: process.env.REPO_FOUNDRY_RUNTIME_REPOSITORY || '',
+    runtimeRef: process.env.REPO_FOUNDRY_RUNTIME_REF || '',
     releaseType: process.env.REPO_FOUNDRY_RELEASE_TYPE || 'auto',
     license: process.env.REPO_FOUNDRY_LICENSE || (command === 'init' ? 'agpl-3.0-or-later' : 'preserve'),
     licenseFile: process.env.REPO_FOUNDRY_LICENSE_FILE || '',
@@ -75,6 +77,7 @@ function parseArgs(argv) {
     ['--features', 'features'],
     ['--package-manager', 'packageManager'],
     ['--runtime-repository', 'runtimeRepository'],
+    ['--runtime-ref', 'runtimeRef'],
     ['--release-type', 'releaseType'],
     ['--license', 'license'],
     ['--license-file', 'licenseFile'],
@@ -127,6 +130,7 @@ function main() {
   if (options.languagesSet) common.push('--languages', options.languages)
   if (options.featuresSet) common.push('--features', options.features)
   if (options.runtimeRepository) common.push('--runtime-repository', options.runtimeRepository)
+  if (options.runtimeRef) common.push('--runtime-ref', options.runtimeRef)
   if (options.prune) common.push('--prune')
   if (options.force) common.push('--force')
   if (options.dryRun) common.push('--check')
@@ -144,6 +148,7 @@ function main() {
       '--license', options.license,
     ]
     if (options.runtimeRepository) initArgs.push('--runtime-repository', options.runtimeRepository)
+    if (options.runtimeRef) initArgs.push('--runtime-ref', options.runtimeRef)
     if (options.licenseFile) initArgs.push('--license-file', options.licenseFile)
     if (options.protection) initArgs.push('--protection')
     if (options.dryRun) initArgs.push('--dry-run')