@mesh-tech/mesh-cli 0.12.7 → 0.13.0

package/README.md

@@ -0,0 +1,227 @@
+# @mesh-tech/mesh-cli
+
+`mesh` is the command-line entry point to the **Mesh platform** — Trabian's
+platform for building and running financial-services applications.
+
+It is the one `@mesh-tech/*` package published to public npm, so a clean laptop
+can install it with **no registry auth at all**, and the CLI then bootstraps
+everything else: your platform login, your package-registry access, a new app,
+a full local stack, and the documentation.
+
+This page is the getting-started path. Every command below also answers
+`--help`, and the complete reference ships inside the docs you start in
+[step 6](#6-read-the-full-docs).
+
+---
+
+## Requirements
+
+| Need | Why |
+|---|---|
+| Node 22+ and `pnpm` (`corepack enable`) | Everything below |
+| Docker Desktop (or equivalent) | Only for `mesh start` / `mesh dev` |
+| A Mesh account | Issued by your Mesh contact; used by `mesh login` |
+| `registry` access on that account | The grant that unlocks `@mesh-tech/*` packages and the docs |
+
+**You do not need an AWS account** to install packages, run an app locally, or
+read the docs. AWS credentials only come into play if you *deploy*
+(`mesh deploy`, `mesh stack`).
+
+---
+
+## 1. Install
+
+```bash
+npm i -g @mesh-tech/mesh-cli
+mesh --version
+```
+
+`mesh --version` must print **0.12.0 or newer**. If it prints `0.1.x`, or the
+install fails with `E401`, see [Troubleshooting](#troubleshooting) — both are
+known, one-command fixes.
+
+## 2. Sign in
+
+```bash
+mesh login mesh.dev
+```
+
+A browser opens; sign in with your Mesh identity. The session is cached under
+`~/.config/mesh/`. `mesh login --status` shows who you are; `mesh logout <context>`
+clears it.
+
+`mesh login` finishes by refreshing your registry auth automatically, so in the
+happy path step 3 is already done.
+
+## 3. Get registry access
+
+```bash
+mesh registry login mesh.dev
+mesh registry status
+```
+
+`mesh registry login` asks the platform's registry-auth broker for a
+package-read token using the session from step 2, and writes the `@mesh-tech`
+scope + token into your `~/.npmrc`. No AWS credential is created on your
+machine, and the token is short-lived by design (12 hours) — re-run
+`mesh login mesh.dev` when it expires.
+
+**If your account does not hold the grant yet**, the command tells you so and
+**sends the access request** — it prints the request URL the platform returned.
+Contact your Mesh contact to have **registry access granted to your user**, then
+run `mesh registry login mesh.dev` again (a token minted before the grant does
+not carry it, so a fresh login is required).
+
+Everything after this point — installing `@mesh-tech/*` packages, and the local
+docs server — depends on this step.
+
+## 4. Create an app
+
+```bash
+mesh create-app --tenant acme --name billing --primitives service,database,temporal
+```
+
+Scaffolds a new tenant application. `--primitives` selects what the app gets
+(`service`, `database`, `temporal`, `bucket`; default `service`). Run
+`mesh create-app --help` for the full option list, or omit the flags to be
+prompted.
+
+## 5. Run it locally
+
+Two commands, in this order:
+
+```bash
+mesh start          # the full-local Mesh platform — Docker only, no AWS, no VPN
+mesh dev            # from inside your app repo: run the app against it
+```
+
+- `mesh status` — component health, endpoints, and ports.
+- `mesh stop` — stop the local platform (`--destroy` also drops volumes).
+- `mesh dev doctor` — diagnoses a dev session (credentials, tunnels, config,
+  ports, Temporal) and names the fix.
+- `mesh dev logs <service>` / `mesh dev restart <service>` — per-service control.
+- `mesh dev --externals` — also realize the app's declared external services,
+  mocked from their OpenAPI spec, run locally, or pointed at the real vendor.
+
+`mesh start` brings up the platform's own services in Docker (the Hub included,
+when its images are available — `--no-hub` skips it); `mesh dev` runs *your*
+app's processes against them.
+
+### Setting up a platform of your own
+
+Most app developers never need this — the platform is already running for you.
+If you are standing one up:
+
+```bash
+mesh init platform acme --domain example.com
+```
+
+scaffolds a tenant **platform** repo (the core + platform Pulumi layers on
+`@mesh-tech/infra-components`) that deploys with `mesh deploy` unmodified.
+
+For an existing app repo, `mesh init app-tenant` is the **doctor**, not a
+scaffolder: it checks auth, registry access, tenant registration, repo shape,
+and agent skills, and repairs what it can with `--fix`. Re-run it any time
+something looks wrong.
+
+## 6. Read the full docs
+
+The Mesh documentation is served **locally, by the CLI** — same access grant as
+the packages, no public site to keep in sync:
+
+```bash
+mesh docs start     # → http://localhost:4400
+mesh docs stop
+```
+
+`mesh docs start` runs detached (in a tmux session named `mesh-docs`) and prints
+the URL once the server answers. Outside a `mesh-platform` checkout it fetches
+the published docs artifact from the role-gated registry, so it needs
+[step 3](#3-get-registry-access) to have succeeded. Useful flags:
+
+| Flag | Effect |
+|---|---|
+| `-p, --port <port>` | serve on another port (`0` picks a free one) |
+| `-v, --version <version>` | pin a docs version (default: latest) |
+| `--foreground` | serve in the foreground (automatic for agents/CI) |
+
+`mesh docs list` shows the published versions. The full `mesh` CLI reference —
+every command, every flag, generated from the binary itself — is a page inside
+that site.
+
+---
+
+## Troubleshooting
+
+### `npm i -g @mesh-tech/mesh-cli` fails with `E401`
+
+This machine already points the `@mesh-tech` scope at the private registry with
+an **expired** token, and npm maps registries per *scope*, never per package —
+so it tried the private registry for a package that is published publicly.
+Override the scope for this one command:
+
+```bash
+npm i -g @mesh-tech/mesh-cli --@mesh-tech:registry=https://registry.npmjs.org
+```
+
+`--registry=…` alone does **not** work: a scope mapping outranks it. Refreshing
+the token (`mesh registry login mesh.dev`) fixes it too.
+
+The release publishes the same version of `@mesh-tech/mesh-cli` to both
+registries in the same job, so the two copies are the same artifact — there is
+no fork to reconcile. Every *other* `@mesh-tech/*` package is private-registry
+only, so keep the scope mapping for `pnpm install` in an app repo; only the CLI
+bootstrap needs the override.
+
+### The install works, but `mesh --version` prints `0.1.x`
+
+You got an abandoned public package from February 2026 that predates the current
+CLI — nothing after it will work. Reinstall:
+
+```bash
+npm rm -g @mesh-tech/mesh-cli
+npm i -g @mesh-tech/mesh-cli
+```
+
+### `mesh: not inside a Mesh workspace (no node_modules/.bin/mesh found)`
+
+An old launcher shim at `~/.local/bin/mesh` is shadowing the global CLI on your
+`PATH`. The package is installed and fine — just unreachable.
+
+```bash
+which -a mesh          # the shim is listed above the npm global bin
+rm ~/.local/bin/mesh   # if you don't develop the platform itself
+```
+
+If you *do* work in a `mesh-platform` checkout, run
+`pnpm exec mesh install-shim --force` there instead — the current shim runs the
+checkout's source inside a checkout and falls through to the global CLI
+everywhere else.
+
+### `Your Mesh account (…) is not authorized to read @mesh-tech packages.`
+
+Your account and session are fine; you don't hold the registry grant yet. The
+message names the request URL — see [step 3](#3-get-registry-access).
+
+### `No valid Mesh session …`
+
+Your session expired. Run `mesh login mesh.dev` again.
+
+### `No configuration found for "mesh.dev"`
+
+Either you are offline, or the platform is not publishing its discovery document
+yet. Use the platform's full domain instead, e.g.
+`mesh login dev.platform.meshtech.io`.
+
+---
+
+## Getting help
+
+- `mesh --help`, and `--help` on any subcommand.
+- `mesh docs start` — the full documentation, locally.
+- Anything else: your Mesh contact.
+
+## License
+
+UNLICENSED — © Trabian. Access to the Mesh platform and its packages is granted
+per account.

package/assets/app-skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: __APP_NAME__
+description: This skill should be used when working on the __APP_NAME__ app — its workflows, services, schemas, config, deploys, and the conventions that are specific to it. Grow it as the app grows; it is the only skill that knows this app.
+---
+
+# __APP_NAME__
+
+> **This file is yours.** `mesh create-app` seeded the stub; `mesh skills sync`
+> never touches it again. It carries no managed marker on purpose — the app repo
+> knows the app better than any platform skill can, so this is where the
+> app-specific knowledge belongs.
+
+## Where the platform knowledge lives (don't duplicate it here)
+
+| For | Load |
+|---|---|
+| Scaffold → wire → run → debug a Mesh app | `.claude/skills/mesh-app-kit-apps/SKILL.md`, or `pnpm exec intent load @mesh-tech/app-kit#apps` |
+| Exact `AppEnvironment` / primitive / Temporal API signatures | `pnpm exec intent load @mesh-tech/app-kit#core` |
+| `mesh` CLI commands (`dev`, `deploy`, `stack`, `hub dev`, tunnels, db) | `.claude/skills/mesh-core/SKILL.md` |
+| Everything installed that ships a skill | `pnpm exec intent list` |
+
+Read those first. This file is for what they cannot know.
+
+## What this app is
+
+<!-- One paragraph: what __APP_NAME__ does and who calls it. -->
+
+- **Path:** `__APP_PATH__`
+- **Primitives:**
+  <!-- e.g. service (Hono API), database (Prisma), temporal worker, bucket -->
+
+## Conventions specific to this app
+
+<!--
+Fill these in as you learn them. Good candidates:
+  - the domain vocabulary an agent will otherwise guess wrong
+  - which module owns what, and what must never import what
+  - the shape of the app's config and where each value comes from
+  - required env/secrets and how they are provisioned
+  - workflow/activity naming and versioning rules
+  - test fixtures and how to run just this app's suite
+-->
+
+## Gotchas
+
+<!--
+Every time an agent (or you) gets something wrong twice, write it here.
+This section is what makes the skill worth loading.
+-->
+
+## Runbook
+
+```bash
+cd __APP_PATH__
+pnpm install
+mesh dev            # run locally
+mesh hub dev        # watch this session's runs in a local Hub
+mesh deploy up      # deploy via the stack's deployer role
+```