Skip to content

Package northstack: northstack new, just upgrade, agent-run releases - #3

Open
elitan wants to merge 6 commits into
mainfrom
packaging
Open

elitan wants to merge 6 commits into
mainfrom
packaging

Conversation

@elitan

@elitan elitan commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Apps no longer clone this repository. They depend on one thing, the northstack crate pinned to an exact version, and update with just upgrade, like create-next-app and bumping next.

cargo install northstack --locked
northstack new my-app && cd my-app
just dev

How it works

  • The crate carries everything that isn't the app's: the server library, the TypeScript runtime (written into web/northstack/ by just check, as before), the scripts behind just (moved from scripts/ into src/scripts/), the guide and the changelog. No npm package: one version, nothing to keep in step.
  • northstack new <dir> copies the example app from this repo at the version's tag (--local <checkout> for framework work), pins northstack = "=<version>", writes the app's AGENTS.md, README.md and docs/northstack.md (the guide), and makes the first commit.
  • Apps run their pinned CLI through a one-line cli/ crate; the justfile calls cargo run -q -p cli -- <command>. A global northstack of another version refuses to run inside the app.
  • just upgrade [version] refuses on uncommitted changes, moves the pin, replaces docs/northstack.md, prints the changelog's Upgrade steps for every version it skips, then runs just check in the new version.
  • The guide moved from the README to crates/northstack/GUIDE.md. The README now has Try it, Updating and Working on northstack sections; the repo's AGENTS.md is for framework work, apps get their own.

Releases and shipping: agent-run

Agents pull, change, run the checks locally, and push to main (or open a PR when you ask for one), then watch CI and fix right away if it goes red (AGENTS.md, repo and app template).

You prompt "release"; the agent runs python3 scripts/release.py <patch|minor|major>. It turns ## Unreleased into the version's changelog section, bumps the crate version, commits Release v<version> and pushes to main. It refuses an empty Unreleased, a patch release that has upgrade steps, a dirty tree, or a main that differs from origin/main.

release.yml runs on every push to main: when the crate version has a changelog section but no tag, it runs ci.yml and framework.yml, publishes to crates.io (skipped if already there, so a re-run finishes a failed release), then creates the tag and GitHub release. Merging this PR doesn't release anything: the changelog only has Unreleased.

Guardrails:

  • Changelog check (before pushing, and in CI on pushes to main and PRs): changes that reach apps (the crate, or template files apps keep, like the Dockerfile or justfile) must add a line under ## Unreleased with **Upgrade:** steps for app agents. [no changelog] in the commit message skips it for pure refactors.
  • AGENTS.md: never force-push main, move a v* tag, run cargo publish by hand, or push with a failing local check.

One-time human step: create a crates.io API token (scopes publish-new, publish-update) and run gh secret set CARGO_REGISTRY_TOKEN --repo elitan/northstack. Agents are told never to handle the token.

Testing

  • Repo: just verify, just e2e, cargo publish -p northstack --dry-run, Docker build and run.

  • scripts/guide_test.py (new framework.yml workflow): northstack new --local gives an app that passes just check, just remove-example works, and the guide's feature walkthrough runs as written, ending with just verify.

  • A fresh app: just ci on an empty database (no file changes), just dev started from a subfolder, just e2e (4 passed).

  • Upgrade, simulated with a local copy of the crate as a fake 0.2.0 on crates.io: pin and lock updated, guide replaced, TypeScript runtime regenerated, notes printed, check passed; the old binary then refuses to run in the app.

  • Release tooling: release.py in a throwaway clone with a fake origin (first release pushed to main, empty Unreleased, patch refused with upgrade steps, minor, patch after a release, dirty tree, wrong branch, unpushed commits); changelog_check.py pass/fail/[no changelog] cases; the release plan step for unreleased, tagged and new versions.

  • Not run: the release workflow on GitHub (needs a release PR merged), and just upgrade's crates.io lookup (nothing published yet).

  • CI's sequence (just ci on data/ci.db, then just e2e) in a fresh clone; this caught a bug where the new .env auto-creation overrode CI's DATABASE_URL.

Fixes found while testing: .env is created from .env.example when missing (so just check works in a fresh clone), web/dist exists before the first compile, the dev and e2e scripts respect CARGO_TARGET_DIR, and just dev no longer prints an error on its first start.

🤖 Generated with Claude Code

elitan and others added 2 commits November 16, 2026 20:50
…upgrade`

Apps no longer clone the repository. The `northstack` crate is the only
thing an app depends on, pinned to an exact version, and it carries
everything that isn't the app's: the server library, the TypeScript
runtime, the scripts behind `just`, and the guide.

- New `northstack` CLI (src/cli.rs): new, check, dev, logs, e2e,
  new-feature, remove-example, upgrade and the database commands. The
  dev scripts moved into the crate and run through it.
- `northstack new <dir>` copies the example app from the repository at
  the version's tag (or a local checkout with --local), pins the
  version, writes AGENTS.md, README.md and docs/northstack.md, and makes
  the first commit.
- Apps run the CLI at their pinned version through a one-line `cli/`
  crate; the justfile calls it. A global binary of another version
  refuses to run in the app.
- `just upgrade [version]` moves the pin, replaces the guide, prints the
  changelog's upgrade steps for every skipped version, and runs check.
- The guide moved from the README to crates/northstack/GUIDE.md.
  scripts/guide_test.py replaces readme-test: it creates an app with
  `northstack new --local`, removes the example and runs the walkthrough.
- Release workflow: a `v<version>` tag checks the version and changelog,
  runs CI, publishes to crates.io with trusted publishing and creates
  the GitHub release.
- Fixes found while testing: .env is created from .env.example when
  missing, web/dist exists before the first compile, the dev and e2e
  scripts respect CARGO_TARGET_DIR, and `just dev` no longer prints an
  error on its first start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A release is now something an agent does from a prompt, with guardrails:

- scripts/release.py <patch|minor|major>: from a clean, up-to-date main,
  turns `## Unreleased` into the version's changelog section, bumps the
  crate version and opens the "Release v<version>" PR. It refuses an
  empty Unreleased and a patch release that has upgrade steps.
- release.yml now runs on pushes to main: when the crate version has a
  changelog section but no tag, it runs ci.yml and framework.yml, tags
  the commit, publishes to crates.io (trusted publishing, or a
  CARGO_REGISTRY_TOKEN secret until that is set up) and creates the
  GitHub release. Every step is skipped when already done, so a re-run
  finishes a failed release.
- scripts/changelog_check.py (framework.yml, on PRs): changes that reach
  apps (the crate, or template files apps keep) add a line under
  Unreleased; released sections never change; new version sections only
  come with a version bump. The label `no changelog` skips the first rule.
- AGENTS.md: the PR flow (branch, verify, PR, wait for CI, merge), the
  changelog rules, and the release steps an agent follows. The app
  template's AGENTS.md gets the same shipping rules.
- `just upgrade` ignores the Unreleased section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@elitan elitan changed the title Package northstack: northstack new, just upgrade, release workflow Package northstack: northstack new, just upgrade, agent-run releases Nov 16, 2026
elitan and others added 4 commits November 16, 2026 21:04
CI failed in `just e2e`: the CLI now creates .env when it's missing, and
check.sh sourced it, overriding CI's DATABASE_URL, so `just ci` migrated
data/dev.db and e2e compiled against a data/ci.db that didn't exist. The
CLI already loads .env without overriding set variables, so the scripts
no longer source it.

Simpler releases for the first version:
- release.yml: one plan check (version has notes, no tag yet), the
  checks, `cargo publish` (skipped if that version is already on
  crates.io), then `gh release create`, which also makes the tag.
  Publishing uses the CARGO_REGISTRY_TOKEN secret only.
- changelog_check.py: one rule, app-facing changes must touch the
  changelog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agents now work on main and push to it; there are no pull requests.

- release.py commits "Release v<version>" on main and pushes it; that
  push starts the release workflow.
- The changelog check runs on pushes to main (against the previous
  commit) and before pushing; `[no changelog]` in a commit message skips
  it for pure refactors.
- AGENTS.md (repo and app template): pull, change, run the checks, push
  to main, watch CI and fix right away if it goes red.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The changelog check runs on pull requests too, and AGENTS.md (repo and
app template) describes both: push to main by default, a PR when the
human asks for one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mentioning the marker in a sentence no longer skips the check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant