code-foundry 0.21.1 → 0.22.0

package/docs/RELEASES.md

@@ -0,0 +1,47 @@
+# Release management
+
+## Branch flow
+
+The standard environment flow is:
+
+```text
+topic branch -> staging -> main -> versioned release
+```
+
+Keep commits Conventional Commit-shaped (`feat:`, `fix:`, `docs:`, `ci:`,
+`chore:`, and so on). Release Please uses them to select patch/minor/major
+versions and generate grouped changelog notes.
+
+The release workflow opens or updates a versioned PR after changes reach
+`main`. Merging that PR updates the changelog, creates the Git tag and GitHub
+Release, and triggers any configured package publication.
+
+For an explicit version, put `Release-As: 2.0.0` in a commit or pull request
+body. Existing `CHANGELOG.md` history remains repository-owned.
+
+## Configuration
+
+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
+```
+
+`auto` selects a supported manifest. Use `simple` with `version.txt` for a
+repository without a package manifest and `none` for a repository that should
+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.
+
+## Operational checklist
+
+1. Merge tested changes from `staging` into `main`.
+2. Review the generated Release Please PR and changelog.
+3. Merge the release PR with the repository's normal linear-history policy.
+4. Confirm the GitHub Release and any package publication.
+5. Synchronize `staging` with the new `main` release commit.

package/docs/WORKFLOWS.md

@@ -0,0 +1,66 @@
+# Workflow and CI conventions
+
+## Standard triggers
+
+The default standard callers use:
+
+```yaml
+push:
+  branches: [main, staging]
+pull_request:
+  branches: [staging]
+```
+
+Draft PR automation may additionally listen to supported topic branches.
+Custom deployment, indexing, search, Slither, or other workflows are
+repository-owned extensions and should keep their own triggers and permissions.
+
+## Standard workflow responsibilities
+
+| Workflow | Responsibility |
+| --- | --- |
+| CI | Format, lint, type-check, and build |
+| Test | Unit, integration, E2E, and smoke tests |
+| Security | Profile, audits, and public-only Dependency Review |
+| CodeQL | GitHub-native code scanning, kept separate from CI |
+| Draft PR | Create/update development pull requests |
+| Release PR | Promote `staging` into `main` |
+| Release | Release Please, GitHub release, and optional npm publication |
+
+Use concise job names such as `CI / Format`, `Test / Unit`, and
+`CodeQL / Analyze (Python)`. Required checks should match the jobs actually
+enabled for the repository profile.
+
+## Language defaults
+
+- TypeScript/JavaScript: ESLint, Prettier, and Bun's native `bun test`.
+- Rust: default `rustfmt`, Clippy with `-D warnings`, and Cargo tests.
+- Python: Ruff formatting/linting, uv when a compatible lockfile exists, and
+  native Python tests.
+- Solidity: preserve the repository's native Hardhat, Foundry, or specialized
+  test/security workflows.
+
+Jobs detect applicability before installing tools. Empty language or test
+surfaces remain successful and visible, so branch protection does not become
+ambiguous for mixed-language repositories.
+
+## Security behavior
+
+CodeQL is a separate workflow using GitHub's official actions. Dependency
+Review is skipped where GitHub does not support it, while JavaScript, Python,
+and Rust audits remain available without Advanced Security. If GitHub default
+setup is enabled, disable its generated CodeQL workflow to avoid duplicate
+analysis.
+
+## Branch protection
+
+Use the initializer's protection helper after reviewing the repository's
+enabled features:
+
+```bash
+bash .github/scripts/init-repo.sh --protection
+```
+
+Keep strict status checks, linear history, and conversation resolution enabled.
+For a repository with optional features disabled, do not require checks that
+will never run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.21.1",
+  "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",
@@ -18,6 +18,7 @@
   },
   "files": [
     "src",
+    "docs",
     ".github",
     ".githooks",
     ".editorconfig",

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