code-foundry 0.21.2 → 0.22.0

package/README.md

@@ -34,6 +34,10 @@ npx code-foundry init --dry-run
 For an existing installation, use `npx code-foundry sync`. Run
 `npx code-foundry doctor` to inspect the resulting repository configuration.
 
+If `.github/code-foundry.yml` already exists, initialization uses it automatically.
+You can also supply a different file with `--config PATH`; after changing the
+file, run `npx code-foundry sync` to render the selected configuration.
+
 ## What it installs
 
 - Short workflow callers for CI, Test, Security, CodeQL, Draft PR, Release PR,
@@ -66,11 +70,12 @@ Initialization is flag-driven. The most important options are:
 --license-file PATH
 ```
 
-The selected profile is saved in `.github/template.yml`. Explicit flags take
+The selected profile is saved in `.github/code-foundry.yml`. Explicit flags take
 precedence over `REPO_FOUNDRY_*` environment/repository variables, which take
 precedence over that file and automatic detection. See
-[Initialization and synchronization](docs/INITIALIZATION.md) for the full
-configuration contract.
+[Configuration reference](docs/CONFIGURATION.md) for the visual configuration
+guide and [Initialization and synchronization](docs/INITIALIZATION.md) for
+the safety and precedence rules.
 
 New repositories default to AGPL-3.0-or-later. Synchronization preserves an
 existing license unless a replacement is explicitly selected. Authored

package/docs/CONFIGURATION.md

@@ -0,0 +1,87 @@
+# Configuration reference
+
+`.github/code-foundry.yml` is the repository's single Code Foundry control plane.
+Initialize from it with:
+
+```bash
+npx code-foundry init --config .github/code-foundry.yml
+```
+
+After initialization, edit the file and run `npx code-foundry sync` to render
+the selected callers and refresh the local baseline. Existing authored files
+and custom workflows remain protected.
+
+## Configuration flow
+
+```text
+code-foundry.yml
+    |
+    +--> profile and language detection
+    +--> enabled standard workflow callers
+    +--> runtime repository and ref
+    +--> workflow runner selection
+    +--> release, license, cache, and coverage policy
+```
+
+## Core settings
+
+| Key | Values | Purpose |
+| --- | --- | --- |
+| `profile` | `auto`, `application`, `monorepo`, `minimal` | Repository shape |
+| `languages` | `auto` or comma-separated languages | Toolchain and CodeQL scope |
+| `package_manager` | `auto`, `bun`, `pnpm`, `yarn`, `npm` | Locked JavaScript setup |
+| `features` | `all` or comma-separated names | Standard callers to install |
+| `prune_standard` | `true` or `false` | Remove disabled standard callers on sync |
+| `runtime_repository` | `OWNER/REPO` or blank | Reusable workflow source |
+| `runtime_ref` | tag or branch | Reusable workflow version |
+| `release_type` | `auto`, `node`, `python`, `rust`, `simple`, `none` | Release Please strategy |
+| `npm_publish` | `true` or `false` | Opt into npm publication |
+| `license` | license name, `preserve`, `none` | License generation policy |
+| `license_file` | path | Optional exact license source |
+
+Supported languages are TypeScript, Rust, Python, and Solidity. Supported
+features are `ci`, `codeql`, `security`, `test`, `draft-pr`, `release-pr`,
+`release`, and `dependabot`.
+
+## Workflow runners
+
+Each caller can select its default runner without editing workflow YAML:
+
+| Key | Default | Controls |
+| --- | --- | --- |
+| `runner` | `ubuntu-latest` | Shared fallback |
+| `unit_runner` | `ubuntu-slim` | Unit tests |
+| `ci_runner` | `ubuntu-latest` | Format, lint, type-check, build |
+| `test_runner` | `ubuntu-latest` | Integration, E2E, smoke |
+| `security_runner` | `ubuntu-slim` | Profile and dependency security jobs |
+| `codeql_runner` | `ubuntu-latest` | CodeQL detection and analyzers |
+| `pr_runner` | `ubuntu-slim` | Draft and Release PR automation |
+| `release_runner` | `ubuntu-slim` | Release and package publication |
+
+Use the full runner for native toolchains, browsers, or measured dependency
+workloads. Use `ubuntu-slim` for lightweight orchestration and small projects.
+
+## Performance and quality
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `cache_packages` | `auto` | Package-store caching policy |
+| `cache_build` | `auto` | Build-cache policy |
+| `coverage_minimum` | `80` | Shared Bun/Python coverage target |
+| `turbo_remote` | `auto` | Turborepo remote-cache policy |
+
+Turborepo remote caching still requires the repository secret `TURBO_TOKEN` and
+the variable `TURBO_TEAM`; the file controls policy, not credentials.
+
+## Precedence
+
+The resolved value order is:
+
+```text
+explicit CLI flag -> REPO_FOUNDRY_* variable -> code-foundry.yml -> detection/default
+```
+
+Use variables for temporary CI overrides. Keep durable repository policy in
+`.github/code-foundry.yml` so humans and agents have one discoverable source of
+truth. The example file is a commented starter guide; it is intentionally not
+a second generated configuration.

package/docs/INITIALIZATION.md

@@ -10,6 +10,17 @@ npx code-foundry sync [options]
 npx code-foundry doctor
 ```
 
+When `.github/code-foundry.yml` already exists, `init` treats it as the primary
+configuration and does not replace its values with CLI defaults. To use another
+file, pass it explicitly:
+
+```bash
+npx code-foundry init --config ./configs/code-foundry.yml
+```
+
+The file is copied to `.github/code-foundry.yml`, normalized, and used to render
+the standard callers. Later edits can be applied with `npx code-foundry sync`.
+
 Use `--dry-run` to preview changes. Use `--no-bootstrap` when the repository is
 being initialized in CI or on a machine without mise. Run
 `bash .github/scripts/bootstrap.sh` later to install tools, enable hooks, and
@@ -38,7 +49,7 @@ npx code-foundry init \
   --runtime-ref v1.2.3
 ```
 
-Both values are persisted in `.github/template.yml` and rendered into the
+Both values are persisted in `.github/code-foundry.yml` and rendered into the
 standard callers. `REPO_FOUNDRY_RUNTIME_REPOSITORY` and
 `REPO_FOUNDRY_RUNTIME_REF` provide equivalent environment/repository-variable
 overrides.
@@ -51,6 +62,6 @@ documentation. Existing licenses are preserved unless a license or license
 file is explicitly selected. Use `--force` only when intentionally refreshing
 protected standard documents.
 
-The initializer generates `.github/template.yml` as the repository-owned
+The initializer generates `.github/code-foundry.yml` as the repository-owned
 configuration contract. Keep project-specific settings there rather than
 editing generated workflow callers by hand.

package/docs/README.md

@@ -7,6 +7,7 @@ its own names, environments, and deployment details.
 ## Guides
 
 - [Initialization and synchronization](INITIALIZATION.md)
+- [Configuration reference](CONFIGURATION.md)
 - [Workflow and CI conventions](WORKFLOWS.md)
 - [Release management](RELEASES.md)
 - [Publishing packages](PUBLISHING.md)

package/docs/RELEASES.md

@@ -21,7 +21,7 @@ body. Existing `CHANGELOG.md` history remains repository-owned.
 
 ## Configuration
 
-Set these values in `.github/template.yml`:
+Set these values in `.github/code-foundry.yml`:
 
 ```yaml
 release_type: auto   # auto, node, python, rust, simple, or none

package/package.json

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

@@ -18,6 +18,7 @@ Init/sync options:
   --target PATH             Repository directory (default: current directory)
   --source PATH_OR_URL      Template source override
   --ref REF                 Template branch or tag (default: main)
+  --config PATH             Use a .github/code-foundry.yml configuration file
   --profile NAME            auto, application, monorepo, or minimal
   --languages LIST          auto or typescript,rust,python,solidity
   --features LIST           all or ci,codeql,security,test,draft-pr,release-pr,release,dependabot
@@ -47,6 +48,7 @@ function parseArgs(argv) {
     target: process.cwd(),
     source: packageRoot,
     ref: 'main',
+    config: process.env.REPO_FOUNDRY_CONFIG || '',
     profile: process.env.REPO_FOUNDRY_PROFILE || 'auto',
     languages: process.env.REPO_FOUNDRY_LANGUAGES || 'auto',
     features: process.env.REPO_FOUNDRY_FEATURES || 'all',
@@ -62,6 +64,14 @@ function parseArgs(argv) {
     npmPublish: process.env.REPO_FOUNDRY_NPM_PUBLISH === 'true',
     languagesSet: false,
     featuresSet: false,
+    profileSet: Boolean(process.env.REPO_FOUNDRY_PROFILE),
+    packageManagerSet: Boolean(process.env.REPO_FOUNDRY_PACKAGE_MANAGER),
+    runtimeRepositorySet: Boolean(process.env.REPO_FOUNDRY_RUNTIME_REPOSITORY),
+    runtimeRefSet: Boolean(process.env.REPO_FOUNDRY_RUNTIME_REF),
+    releaseTypeSet: Boolean(process.env.REPO_FOUNDRY_RELEASE_TYPE),
+    licenseSet: Boolean(process.env.REPO_FOUNDRY_LICENSE),
+    licenseFileSet: Boolean(process.env.REPO_FOUNDRY_LICENSE_FILE),
+    npmPublishSet: Boolean(process.env.REPO_FOUNDRY_NPM_PUBLISH),
     dryRun: false,
     prune: false,
     force: false,
@@ -72,6 +82,7 @@ function parseArgs(argv) {
     ['--target', 'target'],
     ['--source', 'source'],
     ['--ref', 'ref'],
+    ['--config', 'config'],
     ['--profile', 'profile'],
     ['--languages', 'languages'],
     ['--features', 'features'],
@@ -95,6 +106,13 @@ function parseArgs(argv) {
       options[values.get(arg)] = value
       if (arg === '--languages') options.languagesSet = true
       if (arg === '--features') options.featuresSet = true
+      if (arg === '--profile') options.profileSet = true
+      if (arg === '--package-manager') options.packageManagerSet = true
+      if (arg === '--runtime-repository') options.runtimeRepositorySet = true
+      if (arg === '--runtime-ref') options.runtimeRefSet = true
+      if (arg === '--release-type') options.releaseTypeSet = true
+      if (arg === '--license') options.licenseSet = true
+      if (arg === '--license-file') options.licenseFileSet = true
       continue
     }
     if (arg === '--dry-run') options.dryRun = true
@@ -102,7 +120,7 @@ function parseArgs(argv) {
     else if (arg === '--prune') options.prune = true
     else if (arg === '--protection') options.protection = true
     else if (arg === '--no-bootstrap') options.bootstrap = false
-    else if (arg === '--npm-publish') options.npmPublish = true
+    else if (arg === '--npm-publish') { options.npmPublish = true; options.npmPublishSet = true }
     else fail(`unknown option: ${arg}`)
   }
 
@@ -125,12 +143,16 @@ function main() {
   const { command, options } = parseArgs(process.argv.slice(2))
   const target = resolve(options.target)
   const common = ['--source', options.source, '--ref', options.ref]
-  common.push('--license', options.license)
-  if (options.licenseFile) common.push('--license-file', options.licenseFile)
+  if (options.config) common.push('--config', options.config)
+  if (options.profileSet) common.push('--profile', options.profile)
   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.packageManagerSet) common.push('--package-manager', options.packageManager)
+  if (options.runtimeRepositorySet) common.push('--runtime-repository', options.runtimeRepository)
+  if (options.runtimeRefSet) common.push('--runtime-ref', options.runtimeRef)
+  if (options.releaseTypeSet) common.push('--release-type', options.releaseType)
+  if (options.licenseSet) common.push('--license', options.license)
+  if (options.licenseFileSet && options.licenseFile) common.push('--license-file', options.licenseFile)
   if (options.prune) common.push('--prune')
   if (options.force) common.push('--force')
   if (options.dryRun) common.push('--check')
@@ -140,21 +162,22 @@ function main() {
     const initArgs = [
       '--source', options.source,
       '--ref', options.ref,
-      '--profile', options.profile,
-      '--languages', options.languages,
-      '--features', options.features,
-      '--package-manager', options.packageManager,
-      '--release-type', options.releaseType,
-      '--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.profileSet) initArgs.push('--profile', options.profile)
+    if (options.languagesSet) initArgs.push('--languages', options.languages)
+    if (options.featuresSet) initArgs.push('--features', options.features)
+    if (options.packageManagerSet) initArgs.push('--package-manager', options.packageManager)
+    if (options.releaseTypeSet) initArgs.push('--release-type', options.releaseType)
+    if (options.licenseSet) initArgs.push('--license', options.license)
+    if (options.config) initArgs.push('--config', options.config)
+    if (options.runtimeRepositorySet) initArgs.push('--runtime-repository', options.runtimeRepository)
+    if (options.runtimeRefSet) initArgs.push('--runtime-ref', options.runtimeRef)
+    if (options.licenseFileSet && options.licenseFile) initArgs.push('--license-file', options.licenseFile)
     if (options.protection) initArgs.push('--protection')
     if (options.dryRun) initArgs.push('--dry-run')
     if (options.prune) initArgs.push('--prune')
     if (options.force) initArgs.push('--force')
-    if (options.npmPublish) initArgs.push('--npm-publish')
+    if (options.npmPublishSet && options.npmPublish) initArgs.push('--npm-publish')
     if (!options.bootstrap) initArgs.push('--no-bootstrap')
     run('init-repo.sh', initArgs, target)
   } else if (command === 'sync') {

package/.github/template.yml.example

@@ -1,18 +0,0 @@
-# Repository-specific settings for the shared initializer and sync scripts.
-version: 1
-template: code-foundry@latest
-profile: auto
-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
-runner: ubuntu-latest
-unit_runner: ubuntu-slim
-cache_packages: auto
-cache_build: auto
-coverage_minimum: 80
-turbo_remote: auto