From 951c6dcdb358d627c7e101125ca4681f4c427520 Mon Sep 17 00:00:00 2001 From: NiftyAndy Date: Tue, 28 Jul 2026 11:58:49 -0400 Subject: [PATCH] docs: restructure repository guidance --- README.md | 285 +++++++++++++---------------------------- docs/CACHING.md | 29 +++++ docs/INITIALIZATION.md | 56 ++++++++ docs/PUBLISHING.md | 45 +++++++ docs/README.md | 20 +++ docs/RELEASES.md | 47 +++++++ docs/WORKFLOWS.md | 66 ++++++++++ package.json | 1 + 8 files changed, 356 insertions(+), 193 deletions(-) create mode 100644 docs/CACHING.md create mode 100644 docs/INITIALIZATION.md create mode 100644 docs/PUBLISHING.md create mode 100644 docs/README.md create mode 100644 docs/RELEASES.md create mode 100644 docs/WORKFLOWS.md diff --git a/README.md b/README.md index c1b38c7d..0fbbea2b 100644 --- a/README.md +++ b/README.md @@ -3,229 +3,128 @@ [![npm version](https://img.shields.io/npm/v/code-foundry?logo=npm&logoColor=white)](https://www.npmjs.com/package/code-foundry) [![npm downloads](https://img.shields.io/npm/dm/code-foundry?logo=npm&logoColor=white)](https://www.npmjs.com/package/code-foundry) [![CI](../../actions/workflows/ci.yml/badge.svg?branch=main)](../../actions/workflows/ci.yml) -[![Latest GitHub release](https://img.shields.io/badge/GitHub%20release-latest-181717?logo=github)](../../releases/latest) +[![Latest release](https://img.shields.io/github/v/release/0xPlayerOne/code-foundry?logo=github)](../../releases/latest) -`code-foundry` is a repository factory for TypeScript, Rust, Python, Solidity, -and mixed-language projects. It installs agent-ready instructions, fast native -testing, security automation, release workflows, hooks, and repository policy -from one versioned package. +`code-foundry` is a versioned repository baseline for TypeScript, Rust, Python, +Solidity, and mixed-language projects. It provides language-aware workflows, +native testing, security automation, releases, hooks, repository policy, and +agent instructions from one initializer. ## Quick start -```bash -npx code-foundry init -``` - -Or select the project profile explicitly: - -```bash -npx code-foundry init \ - --languages typescript,python \ - --features all \ - --package-manager bun -``` - -Use `code-foundry sync` to update an existing repository and -`code-foundry doctor` to validate it. Add `--dry-run` to preview changes. - -Choose the license during initialization without editing generated files: - -```bash -npx code-foundry init --license mit -npx code-foundry init --license agpl-3.0-or-later -npx code-foundry init --license-file ./legal/LICENSE.txt -``` - -Reusable workflow callers use the source template's runtime automatically. For -example, initializing from `NiftyLeague/template-repo` selects that fork's -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. 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. -Workflow-only actions and Security/CodeQL analyzers stay in the versioned -runtime package and are not duplicated in consumer repositories. - -The standard Security wrapper uses the same runtime contract, so dependency -audits and the public-only Dependency Review policy can be upgraded centrally -without copying security scripts into every consumer repository. - -CodeQL is also independently reusable through the same contract. It retains -GitHub's native security-event permissions and language-specific analysis while -keeping CodeQL separate from CI and dependency security checks. - -Release automation follows the same model: the consumer keeps a short -main-branch wrapper while the shared runtime handles Release Please, GitHub -release metadata, optional npm publication, provenance, and token/trusted -publishing fallback. - -The promotion runtimes for Draft PR and Release PR are maintained in the same -versioned repository and are released before their short consumer callers move -to a new tag, avoiding a bootstrap cycle. - -Initialization defaults to AGPL for new repositories. Synchronization defaults -to `--license preserve`, so an existing repository's license is never replaced -unless you explicitly select a license or provide `--license-file`. - -The generated Git hook is intentionally a small launcher. It points at the -package-managed `.github/scripts/pre-commit.sh`, so repositories do not need to -maintain a second copy of the language-aware hook logic. - -## Setup - -1. Install [mise](https://mise.jdx.dev/). -2. Run `bash .github/scripts/bootstrap.sh` to install the pinned toolchain, enable hooks, and validate the repository. -3. Add the repository's standard scripts (`format:check`, `lint`, `type-check`, `build`, `test:unit`, `test:integration`, `test:e2e`, and `test:smoke`) when available. The shared scripts also recognize legacy aliases and skip checks that do not apply to the repository's languages or package manager. - -## Applying the baseline to an existing repository - -Run the package entrypoint from the repository root. It updates shared -workflows, GitHub forms, hooks, policy files, and tool configuration while -preserving the repository's README, `.mise.toml` selections, extra workflows, -licenses, and application code. +Run this from the root of a repository: ```bash npx code-foundry init ``` -Use `bash .github/scripts/sync-template.sh --source ... --check` to preview differences. For local template development, pass the template checkout as `--source` and `--ref staging`. - -The initializer is intentionally flag-driven so the same baseline can be used as a small repository package. Language selection controls CodeQL and records the repository profile; feature selection controls which standard workflows are installed. `auto` detects supported languages, while `all` enables every standard workflow. The resolver profiles the repository for language, package manager, project shape, release type, runners, and cache policy. - -Existing authored documentation and issue/PR templates are preserved by -default. Pass `--force` when intentionally refreshing those files from the -baseline; repository-specific workflows and application files remain protected. +Useful variants: ```bash -# Preview a TypeScript + Python repository without changing files -bash .github/scripts/init-repo.sh \ - --languages typescript,python \ - --features all \ - --dry-run - -# Initialize a Rust repository with only the core automation -bash .github/scripts/init-repo.sh \ - --languages rust \ - --features ci,codeql,security,test -``` - -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_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. - -## Releases and publishing - -The standard release workflow uses [Release Please](https://github.com/googleapis/release-please) after changes reach `main`. It opens or updates a versioned release pull request, maintains `CHANGELOG.md`, creates the GitHub release after that PR is merged, and applies semantic version bumps from Conventional Commits. The reusable `release-please-config.json` groups feature, fix, performance, dependency, documentation, test, CI, and maintenance changes in generated notes: +# Choose languages and the package manager +npx code-foundry init --languages typescript,python --package-manager bun -- `fix:` → patch, such as `1.2.3` → `1.2.4` -- `feat:` → minor, such as `1.2.3` → `1.3.0` -- `feat!:`, `fix!:`, or `BREAKING CHANGE:` → major, such as `1.2.3` → `2.0.0` - -Before `1.0.0`, `feat:` intentionally increments the minor version. This keeps pre-1.0 releases useful without treating every feature as a breaking major. - -Use `Release-As: 2.0.0` in a commit or pull request body when a specific version is required. Existing `CHANGELOG.md` files are preserved by sync and remain repository-owned. - -Release behavior is configured in `.github/template.yml`: +# Choose a license +npx code-foundry init --license mit -```yaml -release_type: auto # auto, node, python, rust, simple, or none -npm_publish: false # true only for a package published to npm +# Preview without changing files +npx code-foundry init --dry-run ``` -`auto` selects the first matching package type (`package.json`, `pyproject.toml`, `Cargo.toml`, or `version.txt`). Use `none` when the repository should not release automatically. Solidity-only repositories use `simple` with a root `version.txt`. For a repository containing multiple independently released packages, add a Release Please manifest/configuration and select the appropriate Release Please strategy rather than treating the repository as one package. - -GitHub Actions needs permission to open release pull requests. Configure a repository or organization secret named `RELEASE_PLEASE_TOKEN` containing a narrowly scoped token or GitHub App token if the default `GITHUB_TOKEN` is not allowed to create pull requests. Keep `contents`, `issues`, and `pull-requests` permissions enabled for the release workflow. - -For npm publication, set `npm_publish: true` and configure npm trusted publishing (recommended) for this repository’s `release.yml` workflow, or provide an `NPM_TOKEN` secret. The workflow detects which method is configured, and publication occurs only after Release Please creates a release tag, so ordinary pushes cannot publish packages. Keep `publishConfig.access` in `package.json` aligned with the package’s intended visibility; the baseline publishes public packages. If npm publication is enabled without either configuration, the publish job fails instead of silently skipping the release. - -The release flow is: promote `staging` into `main`; let Release Please open or update the version/changelog PR; merge that PR to create the GitHub release and tag; then publish to npm only when `npm_publish: true`. - -For a repository that does not yet contain the scripts, the initializer can be invoked directly from the published package or a downloaded copy of `init-repo.sh`; it fetches the matching sync helper automatically. The generated `.github/template.yml` is the stable configuration contract used by the package and later syncs. - -CI formatting and linting use the preloaded `ubuntu-latest` runner by default because dependency setup is usually faster there. Set `REPO_FOUNDRY_FAST_RUNNER=ubuntu-slim` only after measuring a repository where the lean image is faster; use `ubuntu-latest` for dependency-heavy or native-toolchain projects. - -Rust Build and Type-Check jobs keep compiler caches enabled. JavaScript-only Build and Type-Check jobs skip framework cache archives by default because hosted-runner compression can exceed the build time; opt in with `REPO_FOUNDRY_CACHE_BUILD=true` when a repository’s measurements show a repeatable warm-cache win. - -Branch protection is an administrator operation and is opt-in: - -```bash -bash .github/scripts/init-repo.sh --protection +For an existing installation, use `npx code-foundry sync`. Run +`npx code-foundry doctor` to inspect the resulting repository configuration. + +## What it installs + +- Short workflow callers for CI, Test, Security, CodeQL, Draft PR, Release PR, + and Release. +- A small `.githooks/pre-commit` launcher with language-aware formatting and + linting. +- `.mise.toml`, optional `mise.lock`, repository profile configuration, and + standard GitHub forms and policy files. +- AGENTS instructions, CODEOWNERS, license/notice files, and reusable release + configuration. + +The workflow implementation lives in the versioned runtime repository. A +consumer repository keeps only the callers and the small local entrypoints it +needs. Custom workflows—such as deployment, indexing, Slither, or search—are +preserved and can coexist with the standard baseline. + +## Configuration + +Initialization is flag-driven. The most important options are: + +```text +--profile auto|application|monorepo|minimal +--languages auto|typescript,rust,python,solidity +--features all|ci,codeql,security,test,draft-pr,release-pr,release,dependabot +--package-manager auto|bun|pnpm|yarn|npm +--runtime-repository OWNER/REPO +--runtime-ref TAG_OR_BRANCH +--release-type auto|node|python|rust|simple|none +--license agpl-3.0-or-later|mit|preserve|none +--license-file PATH ``` -The protection helper preserves unrelated provider checks, replaces stale template check names, and skips CodeQL analysis checks for private repositories where the workflow is intentionally skipped. - -The repository name, owner, branch names, and release metadata are resolved by GitHub Actions at runtime through `${{ github.* }}` values. Keep organization-specific details out of this baseline. - -`CODEOWNERS` is repository-aware. Initialization queries the target GitHub repository and writes its personal owner or repository administrators into the default rule. For organization repositories, administrator discovery requires an authenticated `gh` session with collaborator visibility; if discovery is unavailable, the file retains an `@OWNER` placeholder that should be replaced before merging protected changes. - -CI and hooks use Prettier and ESLint for JavaScript/TypeScript, default `rustfmt` and Clippy with warnings-as-errors for Rust, and Ruff formatting/linting for Python. - -The initializer generates a minimal `.mise.toml` from the selected language and package-manager profile instead of installing every supported tool on every runner. TypeScript/Solidity profiles always pin Node and add Bun only for Bun projects; npm, pnpm, and Yarn use Node/Corepack. CI and Security also honor an explicit `package_manager` profile before inspecting lockfiles. Existing `.mise.toml` files are preserved. Initialization also generates a committed `mise.lock` when mise is available; CI then installs exact tool URLs and checksums without repeating registry/API resolution. Workflow setup restores lockfile-keyed package caches for Bun/npm/pnpm/Yarn, Cargo, and pip; cache misses remain safe because dependencies are always re-created from their lockfiles or manifests. Set `REPO_FOUNDRY_CACHE_PACKAGES=true` when a large Bun project has a measured warm-cache win; the default `auto` policy skips oversized archives. +The selected profile is saved in `.github/template.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. -Rust profiles declare `rustfmt` and `clippy` as mise components, so they are installed once with the cached toolchain instead of being added separately by each formatting or lint job. Rust Build jobs cache only reusable debug dependency/build-script artifacts plus Cargo fingerprints; Test jobs disable build and materialized-environment caches to avoid restoring and saving large incremental trees or Python virtual environments in parallel. Cargo’s advisory database and audit tools remain separate caches whose keys follow the security script, so dependency updates do not redownload the scanner. Cargo fingerprints invalidate stale objects safely, while keeping build caches separate prevents a large Rust build from displacing dependency-download caches or parallel jobs from racing to save one partial cache. +New repositories default to AGPL-3.0-or-later. Synchronization preserves an +existing license unless a replacement is explicitly selected. Authored +documentation, application files, custom workflows, and existing `.mise.toml` +files are preserved by default; use `--force` or `--prune` only intentionally. -The shared cache action separates restore-only jobs from jobs allowed to save a cache after completion. Standard parallel CI and Test jobs pass `cache-save: false`, so they can reuse warm data without paying for redundant post-job archive uploads; the Unit and Security paths retain saving where it improves later runs. Repository-specific workflows can use the same local action when they need the same restore-only behavior. +## Workflow model -When an exact `Cargo.lock` dependency cache is restored, CI enables Cargo offline mode for compilation and tests, eliminating avoidable registry/index checks. Cache misses continue using normal online resolution. npm projects intentionally skip the installed-`node_modules` cache because `npm ci` removes that directory before installation; they still reuse the package-download cache. +The standard workflow triggers are: -Applicable jobs cache installed JavaScript dependencies only when a lockfile, workspace, or dependency entry exists; dependency-free package manifests skip both the cache lookup and install. Installed JavaScript dependencies use an `auto` policy: compact pnpm/Yarn layouts are reusable, while Bun recreates its potentially large `node_modules` tree from the cached package store. Package-store caching also defaults to `auto`: normal projects retain it, while Bun repositories with more than 512 KiB of tracked lockfiles skip the large archive when a clean registry install is typically faster. Set `cache-packages: true` or `false` to override that heuristic. Set `cache-installed: true` on the setup action when a specific Bun repository benefits from restoring its materialized tree, or `false` to force lockfile installation for any manager. Jobs also cache Corepack package-manager shims, generic fallback ESLint/Prettier state, and Python virtual environments by manifest/dependency configuration hash. Repository-owned format/lint scripts skip those fallback cache paths entirely, avoiding recursive cache scans and post-job archive work when the script does not create the cache. Formatter and linter configuration is isolated to lint-state caches, so changing formatting rules does not invalidate installed dependencies. Mutable installed environments use exact-key restores only, preventing a lockfile change from downloading stale `node_modules` or a stale virtual environment that must then be replaced. Corepack remains warm even when an installed-dependency cache is already a hit; npm and pnpm installs prefer restored package stores and npm skips redundant audit/funding work because Security runs the authoritative dependency audit separately. The generic ESLint and Prettier fallbacks enable content-based built-in caches so restored lint/format state survives fresh Git checkouts; repository-defined scripts remain authoritative. Cache misses always fall back to a clean install; cached environments must never contain credentials or generated secrets. +- Pushes to `main` and `staging`. +- Pull requests targeting `staging`. +- Draft PR automation for supported feature/fix branches. -When a repository uses multiple supported ecosystems, JavaScript, Rust, and Python dependency installation runs concurrently inside each setup job. A failure in any installer still fails the job after all active installers finish, preserving complete diagnostics without making network waits additive. CI disables Turbo and Next.js telemetry so framework jobs do not spend time on nonessential telemetry startup or network work. +Jobs are language-aware and skip irrelevant setup while remaining visible as +successful required checks. TypeScript uses ESLint, Prettier, and Bun's native +test runner. Rust uses `rustfmt`, Clippy with warnings as errors, and native +Cargo tests. Python uses Ruff, uv/pip-compatible setup, and native Python +tests. Solidity projects retain their native toolchain and test runner. -Installers also short-circuit cleanly: JavaScript projects without dependency entries do not run a package install, and Python source-only projects reuse the shared Ruff tool without creating a virtual environment. Workspace manifests and project dependency files still take the normal locked-install path. +CodeQL remains separate from CI and Security. Dependency Review is isolated in +Security and is skipped where GitHub does not support it, while JavaScript, +Python, and Rust audits remain available without GitHub Advanced Security. -E2E jobs cache Playwright, Cypress, and Puppeteer browser directories by dependency/configuration hash, avoiding repeated browser downloads while invalidating safely when the browser configuration or lockfiles change. Coverage artifacts are uploaded only when a test actually produces coverage output. +See [Workflow and CI conventions](docs/WORKFLOWS.md) for triggers, required +checks, runners, coverage, caching, and custom workflow extensions. -Repositories with Turborepo automatically cache local `.turbo/cache` results per workflow job and dependency/configuration hash when remote caching is unavailable. Fallback restores can reuse valid artifacts produced by another workflow job, while Turbo’s task hashes discard stale results. Vercel Remote Caching remains available through `TURBO_TOKEN` and `TURBO_TEAM`; when both are set, the default path passes Turbo’s `--cache=remote:rw` mode to repository scripts so local archive work is avoided. The lint, type-check, and build jobs first perform a conservative manifest-only remote-cache probe for Bun projects; when every executable task is already a hit, they install only the pinned toolchain and restore results without installing project dependencies. Any miss falls back automatically to the normal locked install. Set `cache-turbo: true` when a repository intentionally wants both local and remote caching. - -New Python profiles include pinned `uv` as an accelerated, pip-compatible installer and pinned Ruff as the shared formatter/linter. Repositories with `pyproject.toml` and `uv.lock` use `uv sync --frozen` to materialize the exact environment without repeat resolution; requirements-file projects continue using the uv/pip-compatible fallback. Existing repositories without `uv` continue using pip automatically, while existing custom tool selections and dependency-file formats remain supported. - -Python Security audits use an isolated cache for `uv tool run` environments containing `pip-audit` when uv is available, so application lockfile changes do not redownload the scanner. They retain the same pip fallback used by CI installation. Independent `requirements.txt` and `requirements-dev.txt` audits run concurrently and aggregate failures. JavaScript, Rust, and Python audit jobs run concurrently when their ecosystems are present. The Python matrix is profile-gated so repositories without applicable Python inputs avoid a no-op runner; JavaScript and Rust retain independent detection so active audits start without waiting for the profile job. Every active ecosystem still reports a failure if its audit fails. - -CI and Test jobs perform a source-only applicability check before setup. Empty integration, E2E, smoke, or language-specific jobs remain visible as successful required checks but skip runner tool installation and dependency setup. - -On pull requests and ordinary pushes, CI, Test, and Security also recognize governance-only changes (README, license, issue/PR templates, CODEOWNERS, Code of Conduct, CONTRIBUTING, and SECURITY) and leave the required jobs successful without installing tools or running unrelated checks. Any source, dependency, workflow, profile, or build configuration change runs the full applicable checks; an unavailable diff always falls back to running them. - -Security dependency audits apply the same fail-open change detection per ecosystem: JavaScript, Rust, and Python audits skip setup for source-only pushes and pull requests that do not change that ecosystem's manifests, lockfiles, audit allowlist, or shared tool configuration. Scheduled scans, manual runs, and uncertain diffs always audit normally. - -The shared setup action accepts `install-javascript`, `install-python`, and `install-rust` switches. They default to `true` for compatibility, while the standard CI jobs disable ecosystems that their task cannot use: formatting skips project Cargo/Python installs, and lint, type-check, and build skip Python dependency installation. Test jobs pass their task profile (`unit`, `integration`, `e2e`, or `smoke`) and disable unrelated ecosystem caches, dependency installs, and mise tools; mixed-language repositories therefore pay only for languages used by that suite. Mise tool installation defaults to `auto`, so each job installs only configured tools for languages actually detected in the repository. Repositories without `.mise.toml` skip mise entirely and use the runner/project environment; callers can use `mise-scope: all` when a task intentionally spans every configured ecosystem. - -It also accepts `mise-scope` (`auto`, `all`, `javascript`, `python`, or `rust`). Security's parallel ecosystem matrix uses this to install only the active language toolchain and restore only its package caches; callers that omit it get automatic profile-based tool selection, while `all` remains available for tasks that intentionally span every configured ecosystem. - -Lightweight orchestration jobs use GitHub's `ubuntu-slim` runner: Draft PR, Release PR, release detection, Release Please, npm publication, dependency review, CodeQL language detection, and dependency audits. Build, format, lint, type-check, integration/E2E/smoke tests, and active CodeQL analysis use full `ubuntu-latest` runners because toolchain initialization, native libraries, browsers, and source analysis may benefit from full runner resources. Unit tests default to `ubuntu-slim` for small projects, but dependency-heavy or native suites should set the repository variable `REPO_FOUNDRY_UNIT_RUNNER=ubuntu-latest`; measurements across the maintained monorepos showed materially faster installs and test execution on the full runner. - -Release and Security metadata jobs also use blobless checkouts where a checkout is needed, reducing source transfer while preserving on-demand manifest access. - -CodeQL keeps every configured language check visible but skips analyzers whose source, dependencies, or configuration were untouched by a push or pull request. Unchanged analyzer jobs use `ubuntu-slim` and skip both checkout and analysis while remaining visible to branch protection; changed analyzers use full `ubuntu-latest` runners. Its detection job uses a blobless, sparse checkout because it only needs Git paths, metadata, and repository manifests; analyzer jobs still use full checkouts. Scheduled and manually dispatched CodeQL runs remain full scans. - -CodeQL uploads SARIF findings for GitHub code scanning but does not archive the intermediate database in the reusable baseline; this keeps coverage and alert processing while avoiding an unnecessary database transfer. The required workflow check gates on successful SARIF upload acknowledgment and does not wait for GitHub’s asynchronous post-upload processing, shortening the CI critical path while retaining the uploaded findings. - -Coverage is enforced at 80% for Python and Bun test suites when those ecosystems expose coverage support. Rust projects must keep their native test suites green; repositories with `cargo-llvm-cov` should enforce the same 80% line target in their Cargo coverage configuration. - -## Test runner standard +## Releases and publishing -For TypeScript and JavaScript tests, use Bun's native test runner by default. Do not add Vitest to projects based on this template. Preserve specialized native runners such as Matchstick for The Graph and Hardhat for smart contracts. +The standard flow promotes `staging` into `main`, lets Release Please open a +versioned release PR, and creates a GitHub release after that PR is merged. +npm publication is opt-in through `npm_publish: true` and supports npm trusted +publishing or an `NPM_TOKEN` fallback. -## Optional Turborepo remote caching +Read [Release management](docs/RELEASES.md) and +[Publishing packages](docs/PUBLISHING.md) before enabling automated +publishing. They are intentionally written with placeholders so they can be +copied into other repositories. -Turborepo repositories can use Vercel Remote Caching without changing the workflows. Add these repository settings: +## Documentation and extensions -- Secret: `TURBO_TOKEN` -- Repository variable: `TURBO_TEAM` +The `docs/` directory contains generalized operational guides. Add +repository-specific documentation there as well; synchronization does not +replace files in `docs/`. -CI and Test pass those values to every job. Non-Turborepo repositories and repositories without the settings simply use their normal local cache behavior. This does not require the repository to deploy to Vercel. +- [Documentation index](docs/README.md) +- [Initialization and synchronization](docs/INITIALIZATION.md) +- [Workflow and CI conventions](docs/WORKFLOWS.md) +- [Release management](docs/RELEASES.md) +- [Publishing packages](docs/PUBLISHING.md) +- [Caching and remote caching](docs/CACHING.md) ## License -Unless a repository says otherwise, new material is licensed under the GNU Affero General Public License v3.0-or-later. See [LICENSE](LICENSE) and [NOTICE](NOTICE). - -## GitHub security behavior - -The CodeQL workflow uses GitHub's official CodeQL actions, detects Actions, TypeScript, Python, and Rust automatically, and runs each language in parallel. It runs automatically for public repositories and skips itself for private repositories unless GitHub Code Security is enabled. Dependency Review is isolated in the Security workflow and runs only for public pull requests. If GitHub's Code Scanning default setup is enabled, disable that generated `dynamic/github-code-scanning/codeql` workflow after installing this checked-in workflow; otherwise GitHub will run two CodeQL analyzers. The default setup can be disabled with `gh api --method PATCH repos/OWNER/REPO/code-scanning/default-setup -f state=not-configured` when Code Security is available. +Unless a repository says otherwise, new material is licensed under the GNU +Affero General Public License v3.0-or-later. See [LICENSE](LICENSE) and +[NOTICE](NOTICE). diff --git a/docs/CACHING.md b/docs/CACHING.md new file mode 100644 index 00000000..a3ed64e4 --- /dev/null +++ b/docs/CACHING.md @@ -0,0 +1,29 @@ +# Caching and remote caching + +## Local workflow caching + +The standard runtime uses lockfile- and configuration-keyed caches for package +stores, Cargo, pip/uv, browser binaries, and applicable build artifacts. Cache +misses always fall back to a clean locked install. Do not cache credentials, +generated secrets, or mutable environments without an exact dependency key. + +Repositories should measure before enabling large installed-tree or build +caches. Set repository variables such as `REPO_FOUNDRY_CACHE_PACKAGES` and +`REPO_FOUNDRY_CACHE_BUILD` only when a repeatable warm-cache benefit is proven. + +## Turborepo and Vercel Remote Caching + +Turborepo repositories can opt into Vercel Remote Caching with: + +- Secret: `TURBO_TOKEN` +- Repository variable: `TURBO_TEAM` + +Non-Turborepo repositories do not need either setting. Deployment to Vercel is +not required. Custom workflows can pass these values to Turbo directly when +the repository's task graph benefits from remote reuse. + +## Runner selection + +Lightweight detection, orchestration, audits, and release metadata jobs can use +`ubuntu-slim`. Toolchain-heavy builds, native compilation, browsers, and active +CodeQL analysis should use `ubuntu-latest` unless measurements show otherwise. diff --git a/docs/INITIALIZATION.md b/docs/INITIALIZATION.md new file mode 100644 index 00000000..12c85f4a --- /dev/null +++ b/docs/INITIALIZATION.md @@ -0,0 +1,56 @@ +# Initialization and synchronization + +## Commands + +Run the package from a repository root: + +```bash +npx code-foundry init [options] +npx code-foundry sync [options] +npx code-foundry doctor +``` + +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 +run the repository doctor. + +## Profiles and features + +Supported languages are `typescript`, `rust`, `python`, and `solidity`. +`--languages auto` detects them from manifests and source files. Profiles are +`auto`, `application`, `monorepo`, and `minimal`. + +Standard features are `ci`, `codeql`, `security`, `test`, `draft-pr`, +`release-pr`, `release`, and `dependabot`. `all` enables every standard +feature. `--prune` removes disabled standard workflows only; it never removes +custom workflows. + +## Runtime selection + +Reusable workflow callers require a literal repository and ref. By default, +the initializer derives the runtime repository from the source template. Use +these options for a fork or a staged runtime: + +```bash +npx code-foundry init \ + --runtime-repository OWNER/REPO \ + --runtime-ref v1.2.3 +``` + +Both values are persisted in `.github/template.yml` and rendered into the +standard callers. `REPO_FOUNDRY_RUNTIME_REPOSITORY` and +`REPO_FOUNDRY_RUNTIME_REF` provide equivalent environment/repository-variable +overrides. + +## Safety rules + +Synchronization preserves authored README and policy documents, existing +`.mise.toml` selections, application code, custom workflows, and repository +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 +configuration contract. Keep project-specific settings there rather than +editing generated workflow callers by hand. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md new file mode 100644 index 00000000..542f9480 --- /dev/null +++ b/docs/PUBLISHING.md @@ -0,0 +1,45 @@ +# Publishing packages + +## npm + +Set `npm_publish: true` only when the repository owns an npm package. Configure +npm trusted publishing for the repository's `release.yml` workflow whenever +possible. An `NPM_TOKEN` secret is the fallback for registries or repositories +that cannot use trusted publishing. + +The package should define its intended visibility explicitly: + +```json +{ + "publishConfig": { + "access": "public" + } +} +``` + +Publication occurs only from a Release Please tag; ordinary pushes do not +publish. The release workflow fails clearly when npm publication is enabled but +neither trusted publishing nor a token is configured. + +## GitHub Releases and GitHub Packages + +A GitHub Release is release metadata attached to a Git tag. It is independent +of the npm registry and of GitHub Packages. + +Publishing to npm does not populate the repository's GitHub Packages section. +If a repository also needs a GitHub Container Registry or npm-compatible +GitHub Package, add a repository-owned publishing workflow and credentials; +that is an optional extension rather than part of the universal baseline. + +## Provenance and verification + +Prefer trusted publishing because it provides short-lived credentials and +provenance. After a release, verify: + +```bash +npm view PACKAGE_NAME version dist-tags +gh release view vVERSION +``` + +For private or non-npm repositories, leave `npm_publish: false` and retain the +GitHub Release portion of the standard flow if versioned releases are useful. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a2acd6b6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# Documentation + +These guides describe the reusable repository baseline in provider-neutral +terms. They are suitable for copying into another repository and adapting with +its own names, environments, and deployment details. + +## Guides + +- [Initialization and synchronization](INITIALIZATION.md) +- [Workflow and CI conventions](WORKFLOWS.md) +- [Release management](RELEASES.md) +- [Publishing packages](PUBLISHING.md) +- [Caching and remote caching](CACHING.md) + +## Repository-specific documentation + +Add project-specific guides, architecture notes, runbooks, and deployment +instructions to this directory. The Code Foundry initializer preserves `docs/` +files during synchronization. Prefer clear, task-oriented filenames and link +new documents from this index when they become part of the supported workflow. diff --git a/docs/RELEASES.md b/docs/RELEASES.md new file mode 100644 index 00000000..03913e99 --- /dev/null +++ b/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/template.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. diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md new file mode 100644 index 00000000..2cf4687c --- /dev/null +++ b/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. diff --git a/package.json b/package.json index f89f0447..0b3a8f34 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ }, "files": [ "src", + "docs", ".github", ".githooks", ".editorconfig",