diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc index cc3df2050..d6348d063 100644 --- a/.cursor/rules/general.mdc +++ b/.cursor/rules/general.mdc @@ -44,8 +44,9 @@ alwaysApply: true - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 00c3186cd..c031c6791 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -13,8 +13,9 @@ Review in English based on the following coding standards. - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS.md b/AGENTS.md index b16128b11..270400e2e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS_EXTRA.md b/AGENTS_EXTRA.md index 141b45684..11f5a3d27 100644 --- a/AGENTS_EXTRA.md +++ b/AGENTS_EXTRA.md @@ -1,5 +1,6 @@ -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/CLAUDE.md b/CLAUDE.md index 05b53b902..658cacfa3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/GEMINI.md b/GEMINI.md index dbe87f36a..27ca60dbb 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/README.md b/README.md index ffa481305..072bce3cc 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,7 @@ [![wbfy](https://img.shields.io/badge/wbfy-12.5.5-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy) :recycle: An npm package designed for reusing general code across multiple projects at WillBooster Inc. + +## Documents + +- [Rules that `wbfy` and `wb` expect of target repositories](docs/expected-repository-rules.md) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md new file mode 100644 index 000000000..d929c6f59 --- /dev/null +++ b/docs/expected-repository-rules.md @@ -0,0 +1,53 @@ +# Rules That `wbfy` and `wb` Expect of Target Repositories + +`wbfy` is a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. +Both tools therefore support exactly one canonical format per file and one canonical repository layout. +A repository that deviates from these rules is fixed manually (or by re-running `wbfy`); the tools do not add code to accommodate deviations, and they may fail fast or overwrite deviating files with canonical output. + +## Repository preconditions + +- Bun at or above the pinned minimum version is installed; `wbfy` aborts otherwise. +- The target directory has a `package.json` (or another supported manifest such as `poetry.lock`, `uv.lock`, `go.mod`, `pom.xml`, `pubspec.yaml`). +- Monorepos place workspaces under `packages/*` and/or the patterns declared in the root `package.json` `workspaces` array. +- Every managed file is a regular in-repository file: symlinks and paths resolving outside the repository are refused. +- Git dependency specifiers in `package.json` files may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run (other ecosystems' manifests are not checked). +- The wbfy badge in `README.md` records the applied `wbfy` version and is the idempotency marker; do not edit or remove it. +- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml`, never in `.env*` application files — the sole exception is `.env.cloudflare`, a gitignored, untracked file holding Cloudflare deploy credentials; `bunfig.toml` uses Bun's isolated linker; `bun.lock` carries no Takumi Guard (`npm.flatt.tech`) URLs in its `resolved` fields (explicit direct tarball dependency URLs and legitimate scoped private-registry URLs such as Verdaccio's remain). + +## Ownership markers: what a human may edit + +| File(s) | Ownership | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone — except in `test-rust.yml` of a Rust repository, where every job not calling a reusable workflow is removed); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except `gen-pr*.yml`, `autofix.yml`, `autofix-apply.yml`, `sync-init.yml`, and `.github/semantic.yml`, which are deleted by filename alone regardless of content, and `release.yml`, which is deleted wholesale when no release branch is configured. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while custom segments in `postinstall` (and in a hand-written `gen-code`) keep their position relative to the recognized generation segment, and a managed `gen-code` is rewritten as `bun wb gen-code` followed by the custom segments. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | + +## File-format rules + +- `package.json` must be strict JSON and is always rewritten via `sort-package-json`. +- `tsconfig.json`, `.vscode/settings.json`, and `pyrightconfig.json` must be JSONC; `.releaserc.json` strict JSON; workflows YAML mappings; `renovate.jsonc` is the only supported Renovate config location. +- Unparseable auxiliary configs (tsconfig, workflows, Renovate, VS Code, pyright) are skipped with a warning and never overwritten. Exceptions: an invalid `package.json` marks the target invalid and fails the run; `fnox.toml` parse or layout errors fail the run; an unparseable `mise.toml` is left untouched and only logged; an unparseable `.gemini/config.yaml` is replaced with the canonical config. +- `fnox.toml` layout is strict: an age provider named exactly `[providers.age]`, no `import`, no profile-specific providers, a root `fnox.toml` when a nested config declares its own age provider, and the file must be git-tracked. Development defaults live in `[secrets]`; `test`/`staging`/`production` overrides live in `[profiles..secrets]`. + +## Project structure expected by `wb` + +- Source code lives in `src/`, scripts in `scripts/`, framework code in `app/`. +- Under `test/`, only `unit/`, `e2e/`, `debug/`, `helpers/`, and `fixtures/` may exist, and `*.test.*` / `*.spec.*` files only under the first three (fixture data under `test/fixtures/` and hidden entries are exempt); violations fail `wb lint` and `wb test`. A non-workspace-root package with its own `playwright.config.ts` must have `test/e2e/`; a workspace root may share a root-level `playwright.config.ts` while the e2e specs live in one app package. +- `package.json` scripts follow the `wbfy`-generated set (`typecheck`, `lint`, `test`, `test/ci`, `verify`, …); optional hooks such as `build`, `gen-code`, `deploy`, `deploy:staging`, `seed`, and `docker/build/prepare` are picked up by name. +- `WB_ENV` is one of `development` / `test` / `staging` / `production`; environment variables come from `fnox.toml` plus `mise env`. +- Docker apps have a `Dockerfile` whose container listens on port 8080 (the host port comes from `PORT`); dev servers default to port 3000 (8787 for plain Workers). +- Cloudflare Workers use a `wrangler.jsonc`/`wrangler.json` config; `wb deploy` targets Workers only, requires `WB_ENV` of `staging`/`production`, and reads Cloudflare credentials from `.env.cloudflare` (gitignored and untracked). `.dev.vars` and `worker-configuration.d.ts` are generated, never hand-written. +- Prisma schemas live at `prisma/schema.prisma`, `prisma/schema/`, or `db/schema.prisma`; i18n resources in `i18n/` with default locale `ja-JP`; a Chakra theme at `src/theme.ts`. +- Real Node.js must be on `PATH` (not a Bun shim) for Playwright, wrangler, and vinext. +- macOS and Linux only; Windows is unsupported. + +## GitHub-side conventions (WillBooster / WillBoosterLab repositories) + +- Squash-only merges with `PR_TITLE` messages, auto-merge enabled, and head-branch deletion on merge. +- A `Protect main` ruleset (WillBooster-owned repositories only, excluding `reusable-workflows`) requires the `test / test` and `semantic-pr / semantic-pr` status checks — plus `test-rust / test-rust` when the repository contains a `Cargo.toml` — and forbids force-pushes and deletion. +- CI calls the organization's own `reusable-workflows` repository (`WillBooster/…` or `WillBoosterLab/…`) at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY` for private repositories, `PUBLIC_FNOX_AGE_KEY` for public WillBooster repositories, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for consumers or publishers of `@willbooster-private/*` packages). +- A fixed label taxonomy (`d1`–`d5`, `p1`–`p4`, `r: …`, `s: …`, `t: …`) replaces GitHub's default labels. +- Releases use semantic-release with Conventional Commits; the version field is `0.0.0-semantically-released`.