techbro 0.0.0-stage → 0.5.0

package/src/upgrade.js

@@ -0,0 +1,94 @@
+import { parseRepoUrl } from "./github.js";
+import { MANAGED_VERSION, REVIEW_WORKFLOW, classifyManaged, managedFiles } from "./managed.js";
+
+const HELPER = ".github/techbro/review.mjs";
+const ACTION = ".github/actions/techbro/action.yml";
+const TRIO = [REVIEW_WORKFLOW, ACTION, HELPER];
+
+export const upgradeBranch = () => `techbro/upgrade-v${MANAGED_VERSION}`;
+const SCOPE_HINT =
+  "the token needs push access, and the `workflow` scope (classic token) or Workflows: write (fine-grained) to change .github/workflows; protected branches are never bypassed";
+
+export async function upgradeTeam({ teamName, config, client, dryRun = false }) {
+  const name = teamName ?? config.currentTeam;
+  const team = name && config.teams[name];
+  if (!team) throw new Error(name ? `unknown team "${name}"` : "no current team; run techbro team create or team join first");
+  const { owner: o, repo: r } = parseRepoUrl(team.url);
+  const repo = await client.getRepo(o, r);
+  if (!repo.permissions?.pull) throw new Error(`no read access to ${o}/${r}`);
+  if (!dryRun && !repo.permissions?.push) throw new Error(`no write access to ${o}/${r}; use --dry-run or ask a writer to upgrade`);
+  const base = repo.defaultBranch;
+
+  const actions = [];
+  const changes = [];
+  const params = { owner: o, repo: r };
+  const files = managedFiles(params);
+  const state = new Map();
+  for (const f of files) {
+    const cur = await client.getFileText(o, r, f.path, base);
+    state.set(f.path, classifyManaged(f.path, cur, params));
+  }
+  const pairHeld = TRIO.some((p) => state.get(p) === "customized");
+  for (const f of files) {
+    let kind = state.get(f.path);
+    if (kind === "customized" && f.seed) kind = "current";
+    const paired = TRIO.includes(f.path);
+    if (kind === "missing") {
+      actions.push({ path: f.path, action: "add" });
+      changes.push({ path: f.path, content: f.content });
+    } else if (kind === "pristine-old" && paired && pairHeld) {
+      const candidate = `${f.path}.techbro-new`;
+      actions.push({ path: f.path, action: "customized", candidate });
+      if ((await client.getFileText(o, r, candidate, base)) !== f.content) changes.push({ path: candidate, content: f.content });
+    } else if (kind === "pristine-old") {
+      actions.push({ path: f.path, action: "update" });
+      changes.push({ path: f.path, content: f.content });
+    } else if (kind === "current") {
+      actions.push({ path: f.path, action: "skip" });
+    } else {
+      const candidate = `${f.path}.techbro-new`;
+      actions.push({ path: f.path, action: "customized", candidate });
+      if ((await client.getFileText(o, r, candidate, base)) !== f.content) changes.push({ path: candidate, content: f.content });
+    }
+  }
+  const result = { team: name, repo: `${o}/${r}`, base, actions };
+  if (!changes.length) return { ...result, status: "current" };
+  if (dryRun) return { ...result, status: "dry-run", changes: changes.map((c) => c.path) };
+
+  const branch = upgradeBranch();
+  const wrap = async (fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      if ([401, 403, 404, 409, 422].includes(err.status)) throw new Error(`${err.message}\n${SCOPE_HINT}`);
+      throw err;
+    }
+  };
+  return wrap(async () => {
+    let head = await client.getBranchSha(o, r, branch);
+    let toWrite = changes;
+    if (head === null) {
+      head = await client.getBranchSha(o, r, base);
+      await client.createRef(o, r, branch, head);
+    } else {
+      toWrite = [];
+      for (const c of changes) if ((await client.getFileText(o, r, c.path, branch)) !== c.content) toWrite.push(c);
+    }
+    if (toWrite.length) {
+      const commit = await client.commitFiles(o, r, { baseSha: head, files: toWrite, message: `techbro: upgrade managed files (v${MANAGED_VERSION})` });
+      await client.updateRef(o, r, branch, commit);
+    }
+    const open = await client.listPulls(o, r, { head: branch, base });
+    if (open.length) return { ...result, status: "pr-existing", prUrl: open[0].url, branch, committed: toWrite.map((c) => c.path) };
+    const lines = actions.map((a) =>
+      a.action === "customized" ? `- ${a.path}: customized, kept; review ${a.candidate} and merge by hand, then delete it` : `- ${a.path}: ${a.action}`,
+    );
+    const pr = await client.createPull(o, r, {
+      title: `techbro: upgrade managed files (v${MANAGED_VERSION})`,
+      head: branch,
+      base,
+      body: `Managed file upgrade.\n\n${lines.join("\n")}\n\nmembers.json and projects.json are never touched.`,
+    });
+    return { ...result, status: "pr-created", prUrl: pr.url, branch, committed: toWrite.map((c) => c.path) };
+  });
+}

package/templates/_default/.agents/skills/README.md

@@ -0,0 +1,36 @@
+# Portable project skills
+
+| Skill | Use when |
+| --- | --- |
+| [frontend-feature](frontend-feature/SKILL.md) | Adding or fixing React pages, client state, or API interactions |
+| [rust-backend-feature](rust-backend-feature/SKILL.md) | Implementing Axum endpoints and model behavior |
+| [database-migrations](database-migrations/SKILL.md) | Planning approved schema changes and verifying migrations |
+| [release-safe-change](release-safe-change/SKILL.md) | Verifying a change for release, compatibility, and graceful draining |
+
+`.agents/skills/` is portable storage, not a universal automatic-discovery directory.
+Explicitly ask your agent to load the relevant `SKILL.md`, or configure its
+documented skill discovery mechanism to use this directory. Load more than one
+when a change crosses concerns. Do not assume a skill was loaded merely because
+it is present in the repository.
+
+The Engineering Convention in the template `README.md` is authoritative. Keep a
+link to that convention if replacing the README during project setup. Skills
+summarize workflows, not exceptions: preserve established project choices and
+follow explicit project instructions. Obtain tech team approval before schema
+or API contract changes, authentication/permission changes, and high-risk work.
+
+## Provenance and references
+
+These are original, project-authored instructions grounded in this template's
+convention, scripts, and sample code. No third-party skill text was copied;
+no third-party skill license or endorsement is claimed. Official documentation
+links are references only:
+
+- [shadcn/ui JavaScript](https://ui.shadcn.com/docs/javascript)
+- [Axum](https://docs.rs/axum/latest/axum/)
+- [SQLx](https://docs.rs/sqlx/latest/sqlx/)
+- [SQLx CLI](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/README.md)
+
+Use installed versions, manifests, toolchain pins, and lockfiles as the source
+of truth. The `latest` documentation URLs do not authorize upgrades or guarantee
+that an example matches the project's installed version.

package/templates/_default/.agents/skills/database-migrations/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: database-migrations
+description: Plan approved independent SQLx migrations and verify PostgreSQL and SQLite schema compatibility safely.
+---
+
+# Database migrations
+
+## Approval gate
+
+- Read the Engineering Convention and existing schema/migration history first.
+- Obtain tech team approval BEFORE implementing any new or changed schema.
+  Document the logical change, affected queries, compatibility, and target engines.
+- Destructive execution additionally requires explicit authorization for the
+  target environment. Never silently drop, truncate, reset, or overwrite data.
+- Escalate sensitive-data, permission, authentication, or availability risks.
+  Continue only independent low-risk work while a decision is pending.
+
+## Author an independent migration
+
+- Keep SQL outside application source in the paired directories
+  `database/migrations/postgres/` and `database/migrations/sqlite/`.
+- Use ordered timestamp filenames following existing migrations. Keep logical
+  schema intent aligned across engines and document unavoidable differences.
+- Never edit/delete a migration already applied to a shared environment;
+  add a corrective migration instead.
+- Keep SQLx as the runner, with migration history and locking. Arrange one
+  migration job per target database; filenames alone do not prevent races.
+- Do not run migrations on application startup, in `/health`, or in `/ready`.
+  The runner must work without building or starting the backend.
+- Parameterize application SQL with SQLx bind values; keep persistence in
+  backend models. Do not concatenate user input into SQL or migration commands.
+- Review constraints, indexes, transaction boundaries, locks, and data volume.
+  Document long-running/backfill work rather than assuming it is instantaneous.
+
+## Expand/contract compatibility
+
+1. Add compatible structures first; old and new application versions must work.
+2. Backfill with a reviewed, restartable data transformation where needed.
+3. Switch application reads/writes after validation and approved deployment.
+4. Remove obsolete structures in a later, separately approved contract change.
+
+For destructive steps, record backup and restore procedures, cut-over criteria,
+and recovery limits. A reverse migration cannot recover deleted data by magic.
+Do not infer rollback safety from the existence of a down script.
+
+## Run only against explicitly selected test databases
+
+From repository root, with `DATABASE_URL` set to an isolated disposable target:
+
+```bash
+scripts/db-migrate postgres
+scripts/db-migrate sqlite
+# Equivalent documented entry points:
+npm run db:migrate:postgres
+npm run db:migrate:sqlite
+```
+
+Run each engine with its own URL; do not reuse a production `.env`. The script
+loads `.env` when no URL is set, invokes `sqlx database create`, then
+`sqlx migrate run --source database/migrations/<engine>`.
+
+## Verification and evidence
+
+- Verify fresh installation AND upgrade from the previous supported schema.
+- Seed representative existing data before upgrade; assert preservation,
+  constraints, query behavior, and old/new application compatibility afterward.
+- Run actual PostgreSQL integration tests for PostgreSQL-bound changes;
+  SQLite tests and static SQL inspection are not substitute evidence.
+- State databases/versions used, commands, results, and any integration gaps.
+- Consult [SQLx CLI](https://github.com/transact-rs/sqlx/blob/main/sqlx-cli/README.md)
+  and [SQLx](https://docs.rs/sqlx/latest/sqlx/) for installed-version behavior.
+  Pins and lockfiles control; do not blindly follow latest docs or upgrade tools.

package/templates/_default/.agents/skills/frontend-feature/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: frontend-feature
+description: Implement and test React JavaScript features within the existing Vite frontend and approved API contracts.
+---
+
+# Frontend feature
+
+## Before editing
+
+- Read the Engineering Convention and frontend README; preserve project choices.
+- Use JavaScript/JSX, React, Vite, Tailwind, and the existing shadcn components.
+  Do not introduce TypeScript, Next.js, or a second styling system.
+- Inspect `apps/frontend/package.json`, its lockfile, `components.json`, and
+  nearby tests before choosing APIs or adding dependencies.
+- Confirm the required behavior uses an approved API contract. New or changed
+  contracts require tech team approval before dependent implementation.
+- Escalate authentication, permissions, sensitive data, payments, or other
+  security/availability risks before implementation. UI hiding is not authorization.
+
+## Test first
+
+1. Add a page/component test describing the user-visible outcome or reproducing
+   the bug. Use Vitest and React Testing Library, following nearby tests.
+2. Run the focused test and actually observe the expected behavioral failure.
+   Fix setup/import failures before treating a test as the red step.
+3. Implement the smallest passing change, then refactor while tests stay green.
+4. Cover useful loading, empty, success, and error cases; mock `fetch` for API
+   tests rather than depending on a live backend.
+
+## Place responsibilities
+
+- Register navigation in `apps/frontend/src/routes.jsx` using React Router's
+  existing browser-history setup; keep path-based resource URLs and deep links.
+- Put route views in `src/pages/`, reusable views in `src/components/`, and
+  reuse `src/components/ui/` before creating replacements.
+- Put HTTP calls in `src/api/`, coordination in `src/hooks/`, and pure data
+  transformations/client state helpers in `src/models/`.
+- Follow `src/api/client.js` for response/error handling. Keep secrets out of
+  bundles; the frontend never accesses the database directly.
+- Keep backend validation authoritative. Retain camelCase payloads and the
+  documented error contract rather than inventing a parallel client contract.
+- Preserve existing styles, layout conventions, tokens, accessibility, and
+  component behavior. Avoid opportunistic restyling during feature work.
+- Prefer focused functions and existing helpers; add JSDoc for exported APIs
+  and non-obvious shared data shapes, not comments on every line.
+
+## Verify from repository root
+
+```bash
+npm --prefix apps/frontend run test -- --run src/api/client.test.js
+npm run check:frontend
+npm --prefix apps/frontend run build
+```
+
+The first command is an existing focused-test example; substitute the changed
+test path relative to `apps/frontend`. Run checks after refactoring, not just
+after the first green test. Report commands, outcomes, and any unverified
+browser/deep-link behavior; do not silently bypass a failing check.
+
+## References and completion
+
+- Consult [shadcn JavaScript docs](https://ui.shadcn.com/docs/javascript) only
+  for the installed configuration; lockfiles control versions, not latest docs.
+- Update API documentation only within approved scope. Include tests, changed
+  behavior, approval references, and verification evidence in the handoff.

package/templates/_default/.agents/skills/release-safe-change/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: release-safe-change
+description: Verify test-first changes, release checks, backward compatibility, health identity, readiness, and SIGTERM draining.
+---
+
+# Release-safe change
+
+## Scope and authority
+
+- Read the Engineering Convention, project READMEs, and `docs/deployment.md`.
+  Preserve established stack, branching, and release choices.
+- Confirm approvals for schema/API contracts and high-risk authentication,
+  permissions, sensitive-data, destructive, availability, or cost changes.
+- Record exceptions and scope. Never bypass a failing gate without explicit
+  approval and follow-up work; routine implementation follows normal review.
+
+## Red, green, refactor
+
+1. Write an outside-in test for the expected behavior or regression.
+2. Run it BEFORE implementation and actually observe the intended failure.
+   Compilation/setup failures do not establish a red behavioral test.
+3. Make the smallest passing change; rerun the test and observe green.
+4. Refactor while green, then run the full applicable checks below.
+5. Report the red and green commands/results, not merely that tests were added.
+
+## Full checks from repository root
+
+```bash
+scripts/check
+npm --prefix apps/frontend run build
+cargo build --locked -p backend
+```
+
+`scripts/check` runs rustfmt, locked Clippy with warnings denied, locked Rust
+tests, frontend Prettier check, ESLint, and Vitest. `npm run check` is the root
+equivalent. Use committed toolchain pins/lockfiles; do not resolve floating
+latest dependencies as part of release verification.
+
+Add target-engine PostgreSQL checks for database changes, plus contract and
+browser checks appropriate to risk. State what the baseline does not test.
+Keep check/build results separate from deployed-system evidence.
+
+## Application readiness
+
+- Keep processes stateless and interchangeable; no local-only sessions/uploads
+  that fail when two instances serve concurrently. Shared deployments use Postgres.
+- Keep runtime configuration environment-driven and use the same built image
+  across environments. Do not bake secrets or environment-specific settings in.
+- Verify `/health` returns liveness plus running `version` and `build` identity.
+  It must not expose secrets or run migrations.
+- Verify `/ready` fails with `503` when required dependencies are unavailable
+  and while draining; dependency checks must be bounded and inexpensive.
+- Exercise SIGTERM on a running process: readiness becomes `503`, the configured
+  drain period elapses, in-flight requests finish, the pool closes, and exit is `0`.
+  A unit test of a flag alone is not live shutdown evidence.
+- Preserve tracing JSON logs and request IDs without sensitive payloads.
+
+## Cut-over and rollback
+
+- Run independent approved migrations before starting the new instance.
+- Verify old/new code can coexist against the expanded schema and within the
+  same API version. Defer removals until a later approved contract release.
+- Confirm rollback can serve against the resulting schema; otherwise require
+  an approved exception and explicit cut-over/recovery plan.
+- Do not claim zero downtime from passing tests, readiness code, or this skill.
+  That claim needs live load-balancer evidence under traffic during cut-over
+  and drain, including request outcomes and instance version/build identity.
+- If live evidence is unavailable, report application readiness separately and
+  label end-to-end zero-downtime behavior unverified.
+
+## Handoff
+
+Summarize behavior, approvals, compatibility, exact checks and outcomes,
+remaining operational risks, and deployment/rollback evidence. Do not push,
+deploy, or execute destructive operations unless specifically authorized.

package/templates/_default/.agents/skills/rust-backend-feature/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: rust-backend-feature
+description: Implement tested Axum and Tokio backend behavior with SQLx persistence and existing JSON contracts.
+---
+
+# Rust backend feature
+
+## Establish scope
+
+- Read the Engineering Convention, backend README, `Cargo.toml`, `Cargo.lock`
+  when present, and `rust-toolchain.toml`; preserve established choices.
+- Keep one modular-monolith backend using Axum, Tokio, Serde, and SQLx.
+  Avoid an ORM, microservice split, or generic repository framework.
+- Obtain tech team approval BEFORE new/changed schema or API contracts.
+  Authentication, permissions, sensitive data, payments, destructive operations,
+  and material availability/cost changes also need explicit risk approval.
+- Existing approval covers its recorded scope, not unrelated improvements.
+
+## Outside-in tests
+
+1. Start with a contract/regression test in `apps/backend/tests/api.rs` for the
+   expected HTTP method, status, headers, and JSON behavior.
+2. Run it and observe the intended behavioral failure before implementation.
+   A compiler error or unavailable database is not proof of a failing behavior.
+3. Add model tests for validation and edge cases; implement the smallest fix.
+4. Refactor with tests green. Keep tests isolated, using the existing SQLite
+   fixture for lightweight checks, not shared mutable databases.
+5. For SQL, constraints, concurrency, or PostgreSQL-specific behavior, also
+   test against an actual isolated PostgreSQL database. SQLite is insufficient.
+
+## Implementation boundaries
+
+- Register endpoints in `apps/backend/src/routes.rs`.
+- Keep `src/controllers/` thin: extract/validate input, enforce authorization,
+  call models, and map results. Never treat client-side checks as security.
+- Keep domain rules and SQLx persistence in `src/models/`; use `src/views/`
+  for response representations when a separate type clarifies the contract.
+- Bind SQL parameters, use transactions for atomic related writes, and retain
+  appropriate constraints. Never interpolate untrusted SQL values.
+- Use existing `src/error.rs` handling and request ID propagation. Keep JSON
+  fields camelCase, collection pagination, and consistent HTTP error statuses.
+- Preserve `{ "error": { "code": "...", "message": "..." }, "requestId": "..." }`;
+  optional details must not expose internal errors or credentials.
+- Avoid unchecked `unwrap()`/`expect()` on request paths. Handle failures with
+  the established error mapping and bounded external-service timeouts.
+- Preserve tracing JSON stdout logs and request correlation; log useful
+  outcomes without passwords, tokens, full payloads, or unnecessary personal data.
+- Never add startup migrations. Use the independent migration workflow.
+- Keep `/health`, `/ready`, configuration, and graceful shutdown compatible.
+
+## Verify from repository root
+
+```bash
+cargo test --locked -p backend --test api
+npm run check:backend
+cargo build --locked -p backend
+```
+
+Use a focused test filter during red/green iterations. Report PostgreSQL checks
+separately from the default SQLite tests, including any checks not performed.
+
+## References and handoff
+
+- [Axum](https://docs.rs/axum/latest/axum/) and
+  [SQLx](https://docs.rs/sqlx/latest/sqlx/) are references, not upgrade mandates.
+  Select documentation matching installed versions and committed lockfiles.
+- Record contract/schema approvals, changed behavior, relevant API examples,
+  and actual test/build evidence. Do not claim unrun integration checks passed.

package/templates/_default/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.rs]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

package/templates/_default/.env.example

@@ -0,0 +1,9 @@
+APP_NAME=my-app
+APP_PORT=8080
+# Local development (SQLite). PostgreSQL form:
+# DATABASE_URL=postgres://user:password@localhost:5432/my_app
+DATABASE_URL=sqlite://local.db?mode=rwc
+RUST_LOG=info
+# Seconds /ready reports 503 after SIGTERM before the listener closes (default 5)
+SHUTDOWN_DRAIN_SECONDS=5
+CORS_ALLOWED_ORIGINS=http://localhost:5173

package/templates/_default/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# Templates pin actions to tags for readability; teams should pin to commit SHAs.
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.95.0
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all --check
+      - run: cargo clippy --locked --all-targets -- -D warnings
+      - run: cargo test --locked
+
+  frontend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: apps/frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: apps/frontend/package-lock.json
+      - run: npm ci
+      - run: npm run format:check
+      - run: npm run lint
+      - run: npm run test -- --run
+      - run: npm run build
+
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/backend/Dockerfile
+          push: false
+      - uses: docker/build-push-action@v6
+        with:
+          context: apps/frontend
+          push: false
+      - uses: docker/build-push-action@v6
+        with:
+          context: database
+          push: false

package/templates/_default/.nvmrc

@@ -0,0 +1 @@
+22