From cebe948fbc44a027d905d26a972ab243f6a5d9c6 Mon Sep 17 00:00:00 2001 From: matamune Date: Tue, 12 May 2026 17:09:22 +0000 Subject: [PATCH] Document Codeberg development flow --- .../skills/codeberg-development-flow/SKILL.md | 61 +++++++++++++ .../agents/openai.yaml | 4 + .../references/development-flow.md | 71 ++++++++++++++++ README.md | 11 ++- docs/development-flow.md | 85 +++++++++++++++++++ 5 files changed, 229 insertions(+), 3 deletions(-) create mode 100644 .codex/skills/codeberg-development-flow/SKILL.md create mode 100644 .codex/skills/codeberg-development-flow/agents/openai.yaml create mode 100644 .codex/skills/codeberg-development-flow/references/development-flow.md create mode 100644 docs/development-flow.md diff --git a/.codex/skills/codeberg-development-flow/SKILL.md b/.codex/skills/codeberg-development-flow/SKILL.md new file mode 100644 index 0000000..df57ca0 --- /dev/null +++ b/.codex/skills/codeberg-development-flow/SKILL.md @@ -0,0 +1,61 @@ +--- +name: codeberg-development-flow +description: Use when working in this repository on development flow, remotes, Codeberg or Forgejo CLI operations, commit signing, mirroring to GitHub, npm trusted publishing, release validation, or publishing @peezy.tech/codex-flows. +--- + +# Codeberg Development Flow + +## Overview + +Use Codeberg as the primary development forge and GitHub only as the npm trusted-publishing mirror. + +## Core Rules + +- Treat `origin` as Codeberg: `git@codeberg.org:peezy-tech/codex-flows.git`. +- Treat `github` as the GitHub mirror: `https://github.com/peezy-tech/codex-flows.git`. +- Push normal development to Codeberg first. +- Push to GitHub only when the release workflow must publish to npm. +- Do not add npm tokens to the repo or GitHub secrets. GitHub publishes through trusted publishing. +- Use package name `@peezy.tech/codex-flows`, not `@peezy-tech/codex-flows`. + +## Setup Checks + +When asked to set up or verify the repo, check: + +```bash +git remote -v +ssh -T git@codeberg.org +fj auth list +gpg --list-secret-keys --keyid-format=long +``` + +Expected local key files: + +```text +~/.ssh/id_ed25519_codeberg.pub +~/.config/codeberg-keys/matamune-codeberg-gpg.asc +``` + +## Release Workflow + +Before release, run: + +```bash +bun run --filter @peezy.tech/codex-flows release:check +bun run check:types +bun run test +git diff --check +``` + +Then: + +1. Bump `packages/codex-client/package.json`. +2. Commit. +3. Push to Codeberg: `git push origin main`. +4. Push to GitHub mirror: `git push github main`. +5. Run GitHub workflow `.github/workflows/publish-codex-flows.yml` with `confirm_package=@peezy.tech/codex-flows`. +6. Verify `npm dist-tag ls @peezy.tech/codex-flows`. + +## References + +- Read `references/development-flow.md` for exact setup and command details. diff --git a/.codex/skills/codeberg-development-flow/agents/openai.yaml b/.codex/skills/codeberg-development-flow/agents/openai.yaml new file mode 100644 index 0000000..222aca8 --- /dev/null +++ b/.codex/skills/codeberg-development-flow/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Codeberg Development Flow" + short_description: "Codeberg-first development and releases." + default_prompt: "Use the Codeberg-first development flow for remotes, commits, Forgejo CLI, mirrors, and npm releases." diff --git a/.codex/skills/codeberg-development-flow/references/development-flow.md b/.codex/skills/codeberg-development-flow/references/development-flow.md new file mode 100644 index 0000000..3fd7540 --- /dev/null +++ b/.codex/skills/codeberg-development-flow/references/development-flow.md @@ -0,0 +1,71 @@ +# Codeberg Development Flow Reference + +## Remotes + +```bash +git remote -v +# origin git@codeberg.org:peezy-tech/codex-flows.git +# github https://github.com/peezy-tech/codex-flows.git +``` + +Use Codeberg for day-to-day pushes: + +```bash +git push origin main +``` + +Use GitHub only to run npm trusted publishing: + +```bash +git push github main +gh workflow run publish-codex-flows.yml --repo peezy-tech/codex-flows --ref main -f confirm_package='@peezy.tech/codex-flows' +``` + +## Keys + +SSH public key: + +```text +~/.ssh/id_ed25519_codeberg.pub +``` + +GPG public key: + +```text +~/.config/codeberg-keys/matamune-codeberg-gpg.asc +``` + +Git signing is expected: + +```bash +git config --global commit.gpgsign true +git config --global user.signingkey E3B0D5FB2E5CF11FAFB2EA113BB8E7D3B968A324 +``` + +## Forgejo CLI + +`forgejo-cli` is installed as `fj`. + +After a Codeberg application token exists: + +```bash +fj auth add-key +fj auth use-ssh true +fj auth list +``` + +## Package Release Gate + +```bash +bun run --filter @peezy.tech/codex-flows release:check +bun run check:types +bun run test +git diff --check +``` + +Verify npm after GitHub Actions publishing: + +```bash +npm dist-tag ls @peezy.tech/codex-flows +npm view @peezy.tech/codex-flows version repository --json +``` diff --git a/README.md b/README.md index 3697bea..11f5694 100644 --- a/README.md +++ b/README.md @@ -61,11 +61,16 @@ bun run test `bun run test` currently runs the `@peezy.tech/codex-flows` transport tests. +## Development Flow + +Development happens on Codeberg. GitHub is kept as a release mirror for npm trusted publishing. + +See [docs/development-flow.md](docs/development-flow.md) for remotes, key setup, Forgejo CLI setup, and the release procedure. + ## Publishing -The public home for this monorepo is `peezy-tech/codex-flows`. When seeding that -repo, copy this working tree without `.git`, initialize a fresh git history, and -push it to the new public GitHub repo. +The public development home for this monorepo is `codeberg.org/peezy-tech/codex-flows`. +The GitHub mirror at `peezy-tech/codex-flows` exists for npm trusted publishing. `@peezy.tech/codex-flows` is published from `packages/codex-client`. diff --git a/docs/development-flow.md b/docs/development-flow.md new file mode 100644 index 0000000..579b41a --- /dev/null +++ b/docs/development-flow.md @@ -0,0 +1,85 @@ +# Development Flow + +This monorepo is developed on Codeberg and mirrored to GitHub only for npm trusted publishing. + +## Remotes + +Use Codeberg as the normal development remote: + +```bash +git remote -v +# origin git@codeberg.org:peezy-tech/codex-flows.git +# github https://github.com/peezy-tech/codex-flows.git +``` + +Push ordinary development to Codeberg: + +```bash +git push origin main +``` + +Push to GitHub only when a release needs the trusted publishing workflow: + +```bash +git push github main +``` + +## Machine Keys + +This machine uses a dedicated Codeberg SSH key: + +```text +~/.ssh/id_ed25519_codeberg.pub +``` + +The public GPG key for commit verification is exported here: + +```text +~/.config/codeberg-keys/matamune-codeberg-gpg.asc +``` + +Upload both public keys to the Codeberg account before pushing over SSH or expecting verified commits. + +## Forgejo CLI + +`forgejo-cli` is installed as `fj`. + +Authenticate with Codeberg after creating an application token: + +```bash +fj auth add-key +fj auth use-ssh true +fj auth list +``` + +If browser login is available, this may also work: + +```bash +fj auth login +fj auth use-ssh true +``` + +## Releases + +Release package: `@peezy.tech/codex-flows` + +Before publishing: + +```bash +bun run --filter @peezy.tech/codex-flows release:check +bun run check:types +bun run test +git diff --check +``` + +To publish through GitHub trusted publishing: + +1. Bump `packages/codex-client/package.json`. +2. Commit and push to Codeberg. +3. Push the same commit to GitHub. +4. Run `.github/workflows/publish-codex-flows.yml` on GitHub with confirmation input `@peezy.tech/codex-flows`. +5. Verify npm: + +```bash +npm dist-tag ls @peezy.tech/codex-flows +```