@mediamonks/canopy-cli 0.7.10 → 0.7.12

package/dist/docs/data.md

@@ -1,85 +0,0 @@
----
-title: Working with project data
-description: Pulling, snapshotting, and restoring your project database.
----
-
-Each Canopy project gets its own database and blob storage (D1 and R2 on the
-Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
-through the Canopy SDK at runtime; the CLI gives you tools to manage the data
-around it.
-
-## Collections in your app (SDK)
-
-The paved road is document-style collections:
-
-```ts
-await canopy.db.collection("blog_posts").insert({ title: "Hello" });
-```
-
-**Collection names must be lowercase** — start with a letter, then letters,
-digits, and underscores only (`^[a-z][a-z0-9_]*$`). `blog_posts` is fine;
-`blogPosts` or `BlogPosts` are **not** and throw at runtime:
-
-> `Invalid collection name "BlogPosts" — use lowercase letters, digits and underscores.`
-
-Use `snake_case` for multi-word names. This mirrors the collection name straight
-into the underlying database, so keeping it lowercase avoids case-sensitivity
-surprises.
-
-## Dialects and raw SQL
-
-The document API above is portable — it behaves the same on every platform
-target. Raw SQL is not: `canopy.db.sql()` passes your statement through
-untranslated, so it speaks whatever the target's database speaks. Ask the
-platform which that is:
-
-```ts
-await canopy.db.dialect(); // "sqlite" | "postgres"
-```
-
-Parameterize with `?` on sqlite and `$1` on postgres. One more per-target
-difference: `collection().search()` is real full-text search (FTS5) on sqlite
-targets, and a plain substring match on postgres targets — different matches,
-no ranking.
-
-## Download a dump
-
-```bash
-canopy db pull                 # writes <slug>-<timestamp>.sql
-canopy db pull --out data.sql  # choose the filename
-```
-
-A plain SQL dump you can inspect, diff, or keep as a backup.
-
-## Snapshots (server-side backups)
-
-```bash
-canopy db snapshot     # store a dump on the platform
-canopy db snapshots    # list stored snapshots
-```
-
-Snapshots live on the platform and can be restored at any time — handy before a
-risky change.
-
-## Restore — destructive
-
-> **Warning:** Restoring **replaces ALL project data**. Take a snapshot first — a snapshot taken seconds earlier
-> is your undo button.
-
-Restore from either source:
-
-```bash
-canopy db restore backup.sql          # from a local dump
-canopy db restore --snapshot <key>    # from a server-side snapshot
-```
-
-You'll be asked to type the project slug to confirm. `--yes` skips that prompt —
-use it only in scripts you trust.
-
-## Safe workflow for agents
-
-Before any destructive data change:
-
-1. `canopy db snapshot` — take a restore point.
-2. Make the change (or test it first with `canopy dev --local --pull`).
-3. If something goes wrong, `canopy db restore --snapshot <key>`.

package/dist/docs/deploy.md

@@ -1,81 +0,0 @@
----
-title: Deploying a project
-description: How canopy deploy builds, uploads, and makes a version live.
----
-
-From inside a project directory:
-
-```bash
-canopy deploy
-```
-
-This uploads your built assets to the platform, creates a new immutable deploy
-version, and makes it live. Each deploy is versioned (`v1`, `v2`, …).
-
-Under the hood a deploy is three steps: the platform authorizes it and issues a
-short-lived signed upload grant, the CLI uploads each file directly against
-that grant, and a completion call checks the bundle and makes the new version
-live. You only ever run `canopy deploy` — but it means a half-uploaded deploy
-is never served.
-
-## Building first
-
-If your project needs a build step (React SPA, anything with a bundler), declare
-the build command in `canopy.json` — `canopy deploy` runs it automatically
-before uploading. To skip the build and upload whatever is already in the
-output directory (or the static files as-is for a `static` project):
-
-```bash
-canopy deploy --no-build
-```
-
-## Trying it on staging first
-
-Nervous about a change — especially one with schema migrations or backend
-code? Deploy it to the project's staging channel first, then promote the exact
-same version once it checks out:
-
-```bash
-canopy deploy --staging   # own URL, own database (a copy of live)
-canopy promote            # make that version live
-```
-
-See [Staging & promoting](https://docs.canopy.website/guides/staging).
-
-## Rolling back
-
-Every deploy is kept, so you can instantly revert:
-
-```bash
-canopy rollback          # pick a version from history
-canopy rollback v3       # make v3 live again
-```
-
-Rollback re-points the live version at an existing deploy — it does not
-rebuild, and the project's backend rolls back with it.
-
-## Downloading a version
-
-Every version's assets can be pulled back down as a zip — the exact files that
-were deployed, for any version in the history:
-
-```bash
-canopy download          # the live version (pick from history in a terminal)
-canopy download v3       # a specific version
-canopy download v3 --out release.zip
-```
-
-The same download is available per version from the dashboard (project overview
-→ Deploys). Handy for archiving a release or moving a matured project off the
-platform.
-
-## Seeing the live site
-
-```bash
-canopy open
-```
-
-## Deploying from CI
-
-For automated push-to-main deploys, use a deploy token instead of an interactive
-login — see `canopy docs ci`.

package/dist/docs/dev.md

@@ -1,72 +0,0 @@
----
-title: Local development
-description: Running a project locally against live or sandboxed data.
----
-
-From inside a project directory:
-
-```bash
-canopy dev
-```
-
-By default `canopy dev` runs your project locally but talks to **live platform
-data** (your project's real database, blobs, and AI). This is the fastest way to
-develop against realistic state.
-
-- `--port <port>` — choose the dev-server port.
-
-## Offline sandbox
-
-To develop without touching live data — for example on a plane, or before you
-trust a destructive change — use a local sandbox backed by an embedded database
-and a filesystem blob store:
-
-```bash
-canopy dev --local
-```
-
-This creates a local database and blobs under `.canopy/local/` in your
-project. The sandbox starts empty.
-
-To seed the sandbox from a fresh copy of production data first:
-
-```bash
-canopy dev --local --pull
-```
-
-`.canopy/local/` is disposable — delete it to reset the sandbox.
-
-By default the sandbox runs PGlite (embedded Postgres), so raw
-`canopy.db.sql()` speaks the postgres dialect there, while your deployed
-project speaks whatever its platform target speaks (`canopy.db.dialect()`
-tells you — sqlite on Cloudflare). Collections (`canopy.db.collection(...)`)
-behave the same in both, so this only matters for hand-written SQL — see
-`canopy docs data`. If your project's raw SQL targets a sqlite site, lock the
-dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an
-embedded SQLite engine instead, so the same SQL works locally and deployed —
-see [canopy dev](https://docs.canopy.website/cli/dev).
-
-## Backend worker
-
-Projects with a `worker` entry in `canopy.json` get their backend locally too:
-`/api/*` is served by your worker in both modes, with the same `env` it has in
-production (`env.CANOPY`, `env.DB`, `env.BLOB`, `env.USER`). Edit and refresh —
-there's no build step.
-
-Secrets are the one thing that doesn't come from the dashboard. Stored values
-are never downloadable, so put local ones in a `.dev.vars` file next to
-`canopy.json`:
-
-```
-STRIPE_KEY=sk_test_local
-```
-
-Your worker reads them the same way it reads dashboard secrets
-(`c.env.STRIPE_KEY`). `canopy dev` prints which dashboard secret names your
-`.dev.vars` is missing. Keep the file out of git — the scaffolds ignore it.
-
-## Which mode should an agent use?
-
-- Iterating on UI or read-only features → `canopy dev` (live data, realistic).
-- Testing writes, migrations, or anything destructive → `canopy dev --local`
-  (optionally `--pull` to start from real data).

package/dist/docs/developers-agents-and-ai.md

@@ -1,95 +0,0 @@
----
-title: Building with agents
-description: Teach your coding agent Canopy — the agent skill, offline docs, template guardrails, and prompts that work.
----
-
-Canopy is built to be driven by coding agents. Three pieces make that work:
-an installable agent skill, docs the CLI carries offline, and guardrail files
-every new project ships with. Set them up once and your agent knows how to
-scaffold, run, deploy, and manage data without guessing.
-
-## Install the skill
-
-From your project (or any repo the agent works in):
-
-```bash
-canopy skill install
-```
-
-This writes the skill to the tool-neutral `.agents/skills/canopy/` tree and
-symlinks `.claude/skills/canopy` to it, so Claude Code picks it up while other
-agents read `.agents/`. `canopy upgrade` refreshes it alongside the CLI.
-
-The skill teaches an agent to:
-
-- **Check install and login first** — `canopy --version`, `canopy whoami`,
-  and how to run `canopy login` correctly (hand the browser sign-in to the
-  human; never touch credentials).
-- **Read docs before acting** — prefer `canopy docs <topic>` and
-  `canopy <command> --help` over guessing flags.
-- **Choose the right starter** — `spa` for anything real (typed SDK),
-  `static` only for trivial pages, `worker` when server-side code is needed —
-  and use `canopy init <slug>` (never `canopy create`) for a project that
-  already exists.
-- **Respect safety rules** — confirm before deploys, snapshot before
-  `canopy db restore`, treat `canopy delete` as destructive.
-
-## Offline docs for agents
-
-The CLI ships the full platform documentation and keeps it fresh from the
-platform, so an agent can read it without a browser — even before signing in:
-
-```bash
-canopy docs            # list all topics
-canopy docs deploy     # print one topic
-canopy docs cli --refresh   # force a re-fetch from the platform
-```
-
-Topics mirror the [guides](https://docs.canopy.website/guides/getting-started) on this site:
-`getting-started`, `cli`, `dev`, `deploy`, `data`, `ci`, `troubleshooting`,
-and more.
-
-## Template guardrails
-
-Every scaffolded project includes an `AGENTS.md` (the agent-facing README)
-that encodes the platform's boundaries, so an agent starting cold in the repo
-already knows the rules:
-
-- **Don't add auth** — the platform authenticates every request first.
-- **Don't store secrets** in the repo or browser code; set them in the
-  dashboard, and only a backend worker reads them.
-- **No SSR, no custom servers, no external databases** — data goes through
-  `canopy.db` and `canopy.blob`.
-- `canopy dev` uses **live** project data: snapshot before risky writes, or
-  use `canopy dev --local` for an offline sandbox where writes never reach
-  the platform.
-
-## Prompts that work
-
-With the skill installed, these are safe, copy-pasteable asks — each maps to
-commands the skill and docs actually cover:
-
-```text
-Set up Canopy in this repo: check the CLI is installed and I'm logged in,
-then install the Canopy skill and skim `canopy docs getting-started`.
-```
-
-```text
-Create a new Canopy project for a team lunch-voting app (spa template),
-run it locally with `canopy dev`, and build the first version of the UI.
-```
-
-```text
-Deploy this project to Canopy, then open the live site so I can check it.
-If anything looks wrong, roll back to the previous version.
-```
-
-```text
-Take a database snapshot, then pull the production data with
-`canopy db pull` and use the dump to reproduce the bug locally with
-`canopy dev --local --pull`.
-```
-
-> **Note:** Deploys go live behind company sign-in and restores replace all project data — a well-behaved
-> agent will confirm both with you first. That caution comes from the skill; keep it installed and
-> current.

package/dist/docs/developers-architecture.md

@@ -1,106 +0,0 @@
----
-title: How the platform serves your project
-description: What happens between a browser and your deployed code — auth wall, static assets, the optional backend worker, and where data lives.
----
-
-You never manage servers on Canopy, but it helps to know what the platform
-does with a request. This page covers the pieces a project developer actually
-touches; platform internals stay out of it.
-
-## The request path
-
-Every project lives at `https://<slug>.canopy.<domain>`. Requests hit the
-**gateway** first, which enforces authentication before any of your project's
-bytes are served — then either serves your deployed static files or, if the
-project has one, dispatches `/api/*` to your backend worker.
-
-```mermaid
-flowchart TD
-    B[Browser] --> G["Gateway<br/>auth wall: OneLogin session<br/>or client password"]
-    G -->|"most paths"| A["Static assets<br/>deployed build, SPA fallback"]
-    G -->|"/api/*"| W["Backend worker<br/>(optional, canopy.json 'worker')"]
-    G -->|"/_api/data/v1/*"| P["Platform data plane<br/>auth · db · blob · ai"]
-    W --> P
-    P --> D[("Project database<br/>+ blob prefix")]
-```
-
-## The auth wall
-
-Authentication is a platform property — your app cannot opt out, and must not
-build its own. A visitor without a valid session is redirected into the
-OneLogin sign-in flow; on projects with client access enabled, outsiders get a
-password page and receive a scope-limited `external` session instead. Only
-after that does any project code or asset get served. Your app just asks
-`canopy.auth.user()` who came through the door
-(see the [SDK reference](https://docs.canopy.website/sdk)).
-
-## Static assets and the SPA fallback
-
-A deploy uploads your built files as an immutable, numbered version; serving
-reads whichever version is live. Requests for paths that don't match a file
-fall back to `index.html`, so client-side routes like `/settings` work on a
-hard refresh without any configuration. Rollback just repoints "live" at an
-earlier version — instant, nothing rebuilt.
-
-The full path — including caching, version-pinned `v12-dot-<slug>` preview
-hosts, and the security review — is in
-[How static files are served](https://docs.canopy.website/guides/static-serving).
-
-## The optional backend worker
-
-Most projects are frontend-only: the SDK talks straight to the platform, and
-no server code exists. When you need server-side code — say, calling an
-external API with a secret the browser can't hold — the `worker` template adds
-a backend, declared in `canopy.json`:
-
-```json
-{
-  "slug": "my-app",
-  "build": "npm run build",
-  "dist": "dist",
-  "worker": "worker/index.ts"
-}
-```
-
-Requests under `/api/*` reach the worker (Hono-style handlers); everything
-else is still static serving. Three things to know:
-
-- **Requests arrive authenticated.** The worker sits behind the same gateway
-  wall as the frontend.
-- **Platform access goes through the same SDK**, via the `CANOPY` service
-  binding — same budgets, same data isolation as the browser:
-
-  ```ts
-  app.get("/api/hello", async (c) => {
-    const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
-    const user = await canopy.auth.user();
-    return c.json({ message: `Hello, ${user.name}!` });
-  });
-  ```
-
-- **Secrets and schedules come from the dashboard.** Secrets (Settings →
-  Secrets) land as Workers-shaped bindings (`c.env.MY_API_KEY`, not
-  `process.env`); dashboard Schedules invoke an exported
-  `scheduled(event, env)` — switch on `event.name`.
-
-> **Warning:** Backend workers are capability-gated per target: today the GCP target runs them, while on
-> Cloudflare sites a worker deploy answers a clear "not supported yet". Frontend-only projects
-> deploy everywhere.
-
-## Where your data lives
-
-Every project gets its own database and its own blob-storage prefix. No other
-project can read them, and deleting the project tears everything down. The
-document API is portable across targets; raw SQL speaks the target's dialect
-(`sqlite` or `postgres` — ask `canopy.db.dialect()`). Dumps, snapshots, and
-restores are CLI commands — see the [project data guide](https://docs.canopy.website/guides/data).
-
-## Sites
-
-A _site_ is one installation of the whole platform. The CLI ships three
-profiles — `main` (canopy.website, Cloudflare), `staging` (thanarie.dev,
-Cloudflare), and `gcp-pilot` (canopy.monks.zone, GCP) — and always shows which
-one you're on. Projects pin theirs in `canopy.json`; `--profile` or
-`CANOPY_PROFILE` overrides per command. Most projects only ever use `main`.
-Target differences (dialect, full-text search, worker support) surface as
-capabilities, not separate APIs.

package/dist/docs/getting-started.md

@@ -1,108 +0,0 @@
----
-title: Getting started
-description: Install the CLI, sign in with OneLogin, and ship your first project.
----
-
-Canopy is Monks' managed platform for vibecoded projects. You build a small web
-app, and Canopy hosts it, gives it a database, blob storage, and AI — no
-infrastructure to manage.
-
-This guide is written so an AI coding agent (Claude, Cursor, etc.) can follow it
-on your behalf. Everything runs through one command-line tool: `canopy`.
-
-## 1. Install the CLI
-
-The CLI is published on npm. Install it globally:
-
-```bash
-npm install -g @mediamonks/canopy-cli
-```
-
-Confirm it's on your PATH:
-
-```bash
-canopy --version
-```
-
-If `npm` isn't available, install Node.js 20+ first (https://nodejs.org), then
-re-run the install.
-
-## 2. Sign in
-
-Canopy authenticates through Monks' OneLogin. Run:
-
-```bash
-canopy login
-```
-
-This opens your browser. **Finish the sign-in there** — the CLI waits for the
-browser to redirect back, then stores a token in `~/.canopy/config.json`.
-
-> If you are an agent: run `canopy login`, then stop and tell the human to
-> complete the sign-in in the browser window that just opened. Never ask for or
-> type the user's password or any codes yourself.
-
-Check who you are at any time:
-
-```bash
-canopy whoami
-```
-
-## 3. Create your first project
-
-```bash
-canopy create
-```
-
-This prompts for a name and a starter template, scaffolds a runnable project
-directory, and registers the project on the platform. To skip the prompts:
-
-```bash
-canopy create "My App" --scaffold --template spa
-```
-
-> If you are an agent: don't stop at printing this command. Ask the person what
-> they'd like to build and what it's about, then pick a name and template for
-> them and run `canopy create` non-interactively — then keep going and build
-> it. Aim for a working first project, not a list of commands.
-
-Templates: **`static`** (no-build html/css/js; SDK served untyped from the
-platform) is the default and fine for a trivial page or two. Reach for
-**`spa`** (Vite + React + TypeScript; typed SDK from npm) once you lean on the
-SDK or expect the app to grow — most projects want this.
-
-## 4. Run it locally
-
-```bash
-cd my-app
-canopy dev
-```
-
-Your project runs against live platform data by default. For an offline sandbox
-with local data, use `canopy dev --local`.
-
-## 5. Deploy
-
-```bash
-canopy deploy
-```
-
-Then open the live site:
-
-```bash
-canopy open
-```
-
-## Where to go next
-
-Everything the CLI can do is documented and available offline. List the topics:
-
-```bash
-canopy docs
-```
-
-Read one, e.g.:
-
-```bash
-canopy docs deploy
-```