@ponderbot/cli 0.1.0-alpha.21

package/README.md

@@ -0,0 +1,112 @@
+# @ponderbot/cli
+
+Ponderbot manifest, run, and control-plane CLI.
+
+## Stack Lifecycle
+
+Start and stop the local Docker compose stack from the repo root:
+
+```sh
+ponder start
+ponder stop
+```
+
+`ponder start --build` runs the core compose target with image builds
+enabled. If `PONDERBOT_HOME` is unset, the CLI creates and forwards
+`<repoRoot>/.ponderbot`; an operator-provided value is preserved. If
+`PONDERBOT_BOOTSTRAP_TOKEN` is unset, `ponder start` creates and reuses a
+development bootstrap token under `PONDERBOT_HOME`, passes it to the runtime, and
+prints the `PONDERBOT_URL`, `PONDERBOT_SPACE_ID`, and `PONDERBOT_TOKEN` block
+that `createClient()` reads.
+
+For runtime development, use the foreground repo-root script:
+
+```sh
+bun dev
+```
+
+It runs the full local dev loop through Turbo: an initial SDK build, SDK and CLI
+`tsdown --watch` tasks, `ponder start --dev --build` for the runtime stack, and
+`docker attach ponderbot-runtime` for the interactive IEx console. The runtime
+command layers `docker/compose/targets/dev.yml` on the core compose stack, uses
+Docker Compose Watch to sync `runtime/` into the container filesystem, and runs
+`mix deps.get && exec iex -S mix phx.server` with Phoenix code reloading.
+Runtime Elixir edits are recompiled on the next HTTP request. Background-only
+changes reload when a later request hits the endpoint. Changes to `mix.exs` or
+`mix.lock` sync, restart the runtime, and refresh dependencies before booting.
+
+For the same dev stack without the Turbo watchers:
+
+```sh
+ponder start --dev
+```
+
+`dev.yml` is an overlay, not a target; use `--dev` rather than
+`--target dev`.
+
+From the repo root, `bun stop` delegates to `ponder stop`.
+
+## Spaces
+
+`ponder start` creates the default development space automatically. To choose a
+different local space for the printed env block, pass `--space`:
+
+```sh
+ponder start --space dev
+ponder manifest dev
+```
+
+`ponder manifest dev` checks the configured dev space first. If it is missing, it prints
+the exact `ponder spaces create <id>` command and exits without deploying.
+
+Manifest commands:
+
+```sh
+ponder manifest validate
+ponder manifest deploy
+ponder manifest dev
+```
+
+`ponder manifest deploy --env staging` stores an immutable Project Release under
+the Project name and environment. A deployment environment needs a Runtime URL
+and token, but it does not need a Space. `ponder manifest dev` still needs a
+development Space because it runs definitions directly.
+
+When `project.worker.build` does not set `dockerfile`, the deploy command
+bundles the Ponderbot definition graph and Worker Entry into a separate artifact.
+It copies only the compiled modules and required Agent and Skill Markdown files.
+It does not copy `.env` files, application source, package-manager lockfiles, or
+the project `node_modules` directory. It does not use the project package
+manager. Docker Buildx builds and pushes the image with a registry cache, and
+the Release stores the registry manifest digest from BuildKit metadata.
+
+The project package manager does not affect the generated Worker Image. The CLI
+bundles normal JavaScript dependencies. It detects native Node packages and puts
+their exact names and versions in the artifact package file. The image uses its
+own npm dependency stage only when these external packages exist. Set
+`worker.build.external` to a list of exact npm package names when a package must
+remain external because it loads code or assets dynamically. The project still
+uses `@ponderbot/sdk` for authoring and local loading. The CLI bundles the SDK
+Worker Entry into the artifact. A project can set `worker.build.dockerfile` when
+it needs a custom system image or install process.
+
+Useful space commands:
+
+```sh
+ponder spaces list
+ponder spaces create customer-acme --name "Acme"
+ponder spaces show customer-acme
+ponder spaces budget customer-acme
+ponder spaces budget customer-acme --set budget.json
+```
+
+Use `--json` before the command for scripting, for example:
+
+```sh
+ponder --json spaces show customer-acme
+```
+
+List and create require a service token with `spaces:read` or `spaces:write`
+granted on `service_auth_space: "*"`. Space-scoped tokens can read or update the
+space they are granted, but cannot list or create spaces. When the runtime
+returns 403 for a spaces command, the CLI prints the missing grant guidance.

package/dist/main.d.ts

@@ -0,0 +1 @@
+export { };