joby_kit_new

# joby_kit.new

Generates a new Phoenix application with [JobyKit](https://github.com/jobycorp/joby_kit)
wired in from the first commit.

```sh
mix archive.install hex joby_kit_new
mix joby_kit.new my_app
cd my_app
mix phx.server
```

## Why this is a separate package

`joby_kit.new` has to run before a project exists, so it can only be a
Mix archive. Everything else the kit provides —
`mix joby_kit.install`, `joby_kit.bootstrap`, `joby_kit.gen.wrapper`,
`joby_kit.lint` — runs *inside* a project that already has `:joby_kit`
as a dependency.

Shipping all of them in one archive meant two copies of those tasks
existed on any machine with the archive installed: the global one and
the project's. The global one answered, so **an app's `mix.exs` did not
control which JobyKit generated its files** — whichever archive was on
the machine did. In practice that produced apps scaffolded from a
version nobody had pinned, and template fixes that silently never
reached anyone.

Splitting removes the possibility rather than detecting it. This package
contains the project generator and nothing else, so it has nothing to
shadow. It is the same arrangement Phoenix uses: `phx_new` is a separate
hex package from `phoenix`.

For the same reason this package has **no `:joby_kit` dependency**. It
writes `{:joby_kit, "~> X.Y"}` into the generated `mix.exs` and then
shells out to `mix joby_kit.install` inside the new app, so the
scaffolding comes from the kit version that app just pinned.

## What it does

1. `mix phx.new <app> --no-install` (plus any forwarded flags).
2. Adds `{:joby_kit, "~> X.Y"}` to the new app's `mix.exs`.
3. `mix deps.get`.
4. Replaces the kit-owned HTML layer: `<app>_web.ex`, `layouts.ex`, and
   `root.html.heex` — including Phoenix's pre-paint theme script, so
   light/dark switching works out of the box.
5. Deletes the Phoenix scaffolding the kit supersedes (`core_components.ex`,
   `PageController`, `PageHTML`).
6. Runs `mix joby_kit.install` in the new app — manifest, previews,
   `/design` and `/custom-designs` pages, `AGENTS.md` and `CLAUDE.md`.
7. Generates `HomeLive` and a JobyKit-wired `router.ex`.
8. `mix assets.setup && mix assets.build`, so the first `mix phx.server`
   serves real CSS instead of 404ing.

## Flags

Forwarded to `phx.new`: `--database`, `--binary-id`, `--module`,
`--app`, `--no-ecto`, `--no-mailer`, `--no-dashboard`, `--no-gettext`,
`--verbose`. `--no-install` is always forced, because `:joby_kit` has to
be in the dep list before the fetch.

Generator-specific:

* `--joby-kit-path <path>` — write a path dep instead of a hex dep, for
  working on the kit itself.

## Versioning

The kit release this generator targets is a literal in
`Mix.Tasks.JobyKit.New` (`@joby_kit_version`), bumped alongside a kit
release — the same way `phx.new` tracks `phoenix`. It is not read from a
loaded `:joby_kit`, because there deliberately isn't one.

## License

MIT.