@ambasada/cli 0.7.5 → 0.8.0

package/README.md

@@ -1,33 +1,29 @@
 # @ambasada/cli: `ambasada`
 
-One dependency-free file (`dist/ambasada.mjs`, the templates embedded). `pnpm build`, then `node dist/ambasada.mjs --help`;
-from source: `pnpm village --help`. `create-ambasada/` is the tiny `npm create ambasada` bin.
+Build and host apps on Ambasada. One dependency-free file (`dist/ambasada.mjs`, the platform templates embedded).
+`pnpm build`, then `node dist/ambasada.mjs --help`; from source: `pnpm village --help`. The command tree is in
+docs/PLATFORM.md §3.
 
-- `ambasada init [dir] --template next|spa|worker` (default `next`) scaffolds from `templates/` in the repo. A product
-  is one Cloudflare Worker: Next.js via OpenNext, Vite + React for Lovable/Bolt exports, or bare fetch handlers.
-  It also writes `.env` for the mock and the app manifest (`/.well-known/ambasada.json`, `src/manifest.ts`).
-- Every template is a **mini-app** for the Ambasada app (docs/MINI-APPS.md): the manifest is schema 2 (`id`, `name` ≤ 32,
-  `subtitle` ≤ 40, `description`, `icon` = a 1024×1024 opaque PNG, `splash`, `accent`, `entry`, `kind`, `category`,
-  `scopes`, `visibility`), and the page calls `ready()` from `@ambasada/miniapp` (`packages/miniapp`; the worker
-  template loads it as `<script src="https://hub.ambasada.id/miniapp.js">`) after its first render, padding the page
-  by `--ambasada-safe-area-*` and `--ambasada-host-bar`.
-- `ambasada check [url | dir] [--json]` (`src/check.ts`) says whether a product passes the mini-app checks: the manifest
-  validates, the icon is a 1024² opaque PNG, the entry has a `width=device-width` viewport, is not dark-only and loads
-  the SDK. With no argument it reads the current project's static files (no network); with a URL it fetches the live
-  origin (https, manifest served without redirects, entry 200 in under 3 s). Problems exit 1, warnings don't; `--json`
-  prints `{ ok, target, problems, warnings }`.
-- `ambasada dev` starts the mock Payments API on :8788 and the project's dev server (`next dev`, `vite` or
-  `wrangler dev`, `src/stack.ts`) on `product.url`, with `AMBASADA_*` pointed at the mock. `--mock-only`: the mock alone.
-- `src/storage.ts`: `ambasada db migrate | shell | tables | migrations`, `ambasada kv …`, `ambasada files …` on the app's
-  D1, KV and R2 through `/v1/dev/{db,kv,files}` (docs/STORAGE.md); `--local` runs the same against wrangler's local
-  state (`ambasada dev` applies `db/migrations` locally before starting the dev server). `ambasada deploy` sends the
-  project's Durable Objects and migrations from `wrangler.jsonc` and prints what the first deploy provisioned.
-- `src/commands.ts`: login (device code at `/v1/auth/device`, else paste a key; saved in `~/.config/ambasada/config.json`),
-  init, dev, deploy, link, check, offerings, wallet, ledger, logs, market, steer, webhook, links.
-- `src/mock/`: the local mock of the Payments API (fake bank, fake visitor, real receipts and webhook signatures,
-  canned LLMOK, and a fake Ambasada ID issuer so Sign in with Ambasada works offline: docs/AUTH.md). See the
-  skill's `reference/test-mode.md`.
-- `test/smoke.test.ts`: `worker` and `next` scaffolds run under `ambasada dev` and get paid 1 TON;
-  `test/templates.test.ts`: the three templates stay in step.
+```
+init [dir] [--template next|spa|worker] [--village]   login | logout | whoami
+dev [--port] [--tunnel] [--mock-only]                 deploy [--own] [--no-smoke] [--dry-run]
+tunnel | link <url> | check [url|dir]                 env list|set|unset | logs [--follow]
+db migrate|shell|tables | kv … | files …              add <addon> | upgrade [--check]
+```
+
+- `src/commands.ts`: login (device code at `/v1/auth/device`, else a key; saved in `~/.config/ambasada/config.json`,
+  the 0.7 `~/.config/village` file is moved there once), init (writes `.env` for the mock, the app manifest and
+  `.ambasada/project.json`), dev, link, check, env, logs, add. `src/deploy.ts`: build, workerd smoke test, upload.
+  `src/storage.ts`: `db`, `kv`, `files` (docs/STORAGE.md). `src/tunnel.ts`: docs/TUNNEL.md. `src/upgrade.ts`:
+  `ambasada upgrade` (docs/PLATFORM.md §3a).
+- `src/mock/`: the platform mock on :8788 (a fake Ambasada ID issuer for Sign in with Ambasada and silent sign-in,
+  a fake hub for notifications and app events, the store, files, device login).
+- `src/plugin.ts`: add-ons. A package with `"ambasada": { "plugin": "./dist/cli.mjs" }` among the project's
+  dependencies (or in `addons: []` of `ambasada.config.ts`, or `AMBASADA_ADDONS`) is imported and its
+  `register(api)` adds a namespace, aliases, mock routes, a dev hook, after-deploy hooks, smoke checks, config keys,
+  an init overlay and skills. Today: `@ambasada/village` (`ambasada village …`).
+- `src/check.ts`: the mini-app checks (manifest schema 2, 1024² opaque PNG icon, viewport, light scheme, the SDK).
+- Tests: `test/smoke.test.ts` runs the templates under `ambasada dev` (and a `--village` one through the bank and
+  deploy); `test/upgrade.test.ts` upgrades a 0.7 project; `test/templates.test.ts` keeps the templates in step.
 
 Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.