From a26cf906a35b6cfef609f22762a8c0c65e8ee64a Mon Sep 17 00:00:00 2001 From: Akos Orban Date: Wed, 29 Jul 2026 14:45:25 +0200 Subject: [PATCH] chore: rebrand to @mantacode/mna-cli + doc fixes before first release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prepares the CLI for its first npm release under the @mantacode scope. Rename: the package becomes `@mantacode/mna-cli` (was `@mynextadventure/cli`). The scope holds multiple products, so the package name carries the product prefix; the installed binary stays `mna`. Homebrew references now point at `mantacode/homebrew-tap` / `brew install mantacode/tap/mna`. Packaging hardening: added `publishConfig.access: public` alongside the workflow's existing `--access public` (scoped packages are private by default, which bites hardest on the first publish), plus repository/homepage/ bugs/keywords metadata for the npm page. RELEASING.md now states the first-release version explicitly (0.1.0, not 1.0.0 — 1.0.0 is reserved as the signal that the /v1/ contract is frozen) and warns that NPM_TOKEN must exist before the tag is pushed, since a failed publish burns the version number. DEVELOPMENT.md documented the codegen source priority backwards: it claimed the live URL is tried first with the committed snapshot as fallback, but scripts/codegen.ts tries the snapshot first. It also still called releasing "out of scope until Phase 8" and pointed at a design doc in another repo. README: fixed a `git clone` URL for an org that doesn't exist, and the paste-token host (app.mynextadventure.cloud). skills/mna/ is left alone — PR #3 already truth-passed it. Version deliberately left at 0.0.1; RELEASING.md owns the bump. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01AsdP2hvt4XQhYxkdNREXUq --- .github/workflows/release.yml | 3 +++ DEVELOPMENT.md | 17 +++++++++---- README.md | 8 +++--- RELEASING.md | 47 +++++++++++++++++++++++------------ homebrew/mna.rb | 8 +++--- package.json | 20 ++++++++++++++- 6 files changed, 73 insertions(+), 30 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b07e507..90dafb3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -85,6 +85,9 @@ jobs: - name: Build npm bundle run: bun run build + # @mantacode/mna-cli is a scoped package, which npm treats as private by + # default — --access public is required (belt-and-braces alongside + # publishConfig.access in package.json), especially on the first publish. - name: Publish to npm run: npm publish --access public env: diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b414b00..39f5b99 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -30,10 +30,16 @@ bun run codegen # regen types from production OpenAPI Without `MNA_OPENAPI_URL` set, `bun run codegen` tries sources in order: -1. `https://api.mynextadventure.cloud/v1/openapi.json` (the live public spec) -2. `openapi.json` at the repo root (committed snapshot, refreshed periodically) +1. `openapi.json` at the repo root (committed snapshot) +2. `https://api.mynextadventure.cloud/v1/openapi.json` (the live public spec) -The snapshot fallback exists so CI and fresh clones work even when the production endpoint is unreachable. Once the production deploy is reliably online, prefer the URL — the committed snapshot will be regenerated on a slower cadence to track major contract changes. +The snapshot comes first so CI and fresh clones are deterministic and land green regardless of deploy timing; the URL is the fallback for a checkout where the snapshot is missing. To type-check against the current production surface instead, force it: + +```bash +MNA_OPENAPI_URL=https://api.mynextadventure.cloud/v1/openapi.json bun run codegen +``` + +The snapshot is refreshed on a slower cadence than the server deploys, so it can lag production by additive (backwards-compatible) fields. Refresh it by running the command above and committing the resulting `openapi.json`. ## Codegen against a local server @@ -66,5 +72,6 @@ introduce tests that hit production unless they're explicitly opt-in (`MNA_E2E=1 ## Releasing -Out of scope until Phase 8. See `docs/superpowers/specs/2026-05-21-mna-cli-design.md` -in the `travel-plans` repo for the release plan. +See [RELEASING.md](./RELEASING.md). Releases are driven by pushing a `vX.Y.Z` +tag, which builds the native binaries, cuts a GitHub Release, and publishes +`@mantacode/mna-cli` to npm. diff --git a/README.md b/README.md index a083ce1..8fcf19c 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Releases. npm and Homebrew distribution land with the first tag. ### npm (Node 20+) ```bash -npm install -g @mynextadventure/cli +npm install -g @mantacode/mna-cli ``` This installs the `mna` binary. It bundles all dependencies as a single @@ -24,7 +24,7 @@ JS file; no Bun required. ### Homebrew (macOS + Linux) ```bash -brew install mynextadventure/tap/mna +brew install mantacode/tap/mna ``` Installs a precompiled native binary. The tap is updated per release; see @@ -47,7 +47,7 @@ mna --version ### From source (development) ```bash -git clone https://github.com/mynextadventure/mna-cli +git clone https://github.com/akoso/mna-cli cd mna-cli bun install bun run codegen @@ -67,7 +67,7 @@ mna trips show # detail view If you prefer headless / paste-token login: ```bash -mna login --paste-token # generate the key from the user menu on mynextadventure.cloud +mna login --paste-token # generate the key from the user menu on app.mynextadventure.cloud ``` ## Use it as a Claude Code skill diff --git a/RELEASING.md b/RELEASING.md index 7265bd1..8c3e10e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -4,7 +4,11 @@ The release pipeline is driven by tag pushes. Tagging a commit `vX.Y.Z` runs `.github/workflows/release.yml`, which builds three native binaries (`darwin-arm64`, `darwin-x64`, `linux-x64`), uploads them to a GitHub Release as `.tar.gz` + `.sha256`, and publishes the bundled npm package -`@mynextadventure/cli` to the public registry. +`@mantacode/mna-cli` to the public registry. + +The npm package is `@mantacode/mna-cli`; the binary it installs is `mna`. +The `@mantacode` scope is shared across products, so the package name carries +the product prefix while the command stays short. ## Cutting a release @@ -25,7 +29,7 @@ Release as `.tar.gz` + `.sha256`, and publishes the bundled npm package 4. Watch the **Release** workflow on GitHub Actions. When it completes: - A new GitHub Release `vX.Y.Z` exists with three `mna-.tar.gz` assets and their `.sha256` files. - - npm has a new `@mynextadventure/cli@X.Y.Z` version. + - npm has a new `@mantacode/mna-cli@X.Y.Z` version. 5. Refresh the Homebrew tap (see below). @@ -42,27 +46,39 @@ Release as `.tar.gz` + `.sha256`, and publishes the bundled npm package These steps only matter the *first* time we release. After that, follow "Cutting a release" above. -1. **Claim the npm scope and package name.** Sign in to npmjs.com as the - org owner and create an organization `@mynextadventure` (or use an - existing one). Confirm `@mynextadventure/cli` is unclaimed and reserve - it by publishing `0.0.0-prerelease` from a clean checkout if needed: +**First-release version: `0.1.0`.** The repo currently sits at `0.0.1` +(never published). `1.0.0` is deliberately reserved: shipping `1.0.0` is the +signal that the `/v1/` API contract is frozen and breaking changes require +`/v2/`. Until then releases stay in the `0.x` range, and `homebrew/mna.rb` +already carries `version "0.1.0"` as its placeholder. + +1. **Confirm the npm scope and package name.** `@mantacode` is the owner's + personal npm scope (username `mantacode`), so no organization needs to be + created — but a scoped package is private by default, which is why both + `package.json` (`publishConfig.access`) and the release workflow pass + `--access public`. Sanity-check the tarball from a clean checkout before + the first tag: ```bash bun run codegen bun run build - npm publish --access public --dry-run # sanity check - npm publish --access public # for real + npm publish --access public --dry-run # inspect the file list, do not publish ``` + The real publish happens from CI on the tag push — do not publish by hand. + 2. **Add `NPM_TOKEN` to GitHub repo secrets.** On npmjs.com → User → Access Tokens → "Generate New Token" → type **Automation**. Copy the token, then on GitHub: Settings → Secrets and variables → Actions → - New repository secret → `NPM_TOKEN`. + New repository secret → `NPM_TOKEN`. **The tag must not be pushed before + this secret exists** — the `publish-npm` job will fail and the version + number is then burned (never reuse one). 3. **Create the Homebrew tap repo.** Make a public GitHub repo named - `akoso/homebrew-tap` (or `mynextadventure/homebrew-tap`). Inside it, - create `Formula/mna.rb` from this repo's `homebrew/mna.rb` template - with the SHAs filled in (see next section). + `mantacode/homebrew-tap` — the `homebrew-` prefix is what lets Homebrew + resolve `brew install mantacode/tap/mna`. Inside it, create + `Formula/mna.rb` from this repo's `homebrew/mna.rb` template with the + SHAs filled in (see next section). ## Refreshing the Homebrew tap after a release @@ -77,7 +93,7 @@ The tap is not automated yet. After every release: cat /tmp/mna-vX.Y.Z/mna-linux-x64.tar.gz.sha256 ``` -2. In a checkout of `akoso/homebrew-tap`, edit `Formula/mna.rb`: +2. In a checkout of `mantacode/homebrew-tap`, edit `Formula/mna.rb`: - Update `version "X.Y.Z"`. - Replace each `sha256 "..."` with the values from step 1. @@ -91,8 +107,7 @@ The tap is not automated yet. After every release: 4. Verify install works from a clean machine: ```bash - brew tap mynextadventure/tap - brew install mna + brew install mantacode/tap/mna mna --version # should print X.Y.Z ``` @@ -103,7 +118,7 @@ that opens a PR against the tap repo from `release.yml`. - **GitHub Release:** `gh release delete vX.Y.Z --yes` and delete the tag (`git tag -d vX.Y.Z && git push --delete origin vX.Y.Z`). -- **npm:** `npm unpublish @mynextadventure/cli@X.Y.Z` works only within +- **npm:** `npm unpublish @mantacode/mna-cli@X.Y.Z` works only within 72 hours of publish. After that, publish a new patch version with the fix. **Never** reuse a version number. - **Homebrew:** revert the formula commit in the tap repo. diff --git a/homebrew/mna.rb b/homebrew/mna.rb index a7e33b5..8fccad2 100644 --- a/homebrew/mna.rb +++ b/homebrew/mna.rb @@ -1,10 +1,10 @@ # Template Homebrew formula for the mna CLI. # # This file is versioned alongside the source as a template. To make -# `brew install mynextadventure/tap/mna` work, copy this file into the -# separate `mynextadventure/homebrew-tap` (or `akoso/homebrew-tap`) GitHub -# repo at `Formula/mna.rb`, and update `version` + each `sha256` after a -# new GitHub Release is published. See RELEASING.md. +# `brew install mantacode/tap/mna` work, copy this file into the separate +# `mantacode/homebrew-tap` GitHub repo at `Formula/mna.rb`, and update +# `version` + each `sha256` after a new GitHub Release is published. +# See RELEASING.md. class Mna < Formula desc "Command-line tool for My Next Adventure trip planning" diff --git a/package.json b/package.json index 14a7514..e86d8b6 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,30 @@ { - "name": "@mynextadventure/cli", + "name": "@mantacode/mna-cli", "version": "0.0.1", "description": "Command-line tool for My Next Adventure trip planning.", "license": "MIT", "type": "module", + "homepage": "https://github.com/akoso/mna-cli#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/akoso/mna-cli.git" + }, + "bugs": { + "url": "https://github.com/akoso/mna-cli/issues" + }, + "keywords": [ + "cli", + "travel", + "trip-planning", + "my-next-adventure", + "claude-code-skill" + ], "bin": { "mna": "./dist/mna.js" }, + "publishConfig": { + "access": "public" + }, "files": [ "dist/mna.js", "skills/**",