@mediamonks/canopy-cli 0.7.5 → 0.7.6

package/dist/docs/platform-sites-and-profiles.md

@@ -0,0 +1,61 @@
+---
+title: Sites & profiles
+description: Canopy runs as more than one installation. Most people only ever use main — here's what the others are and how the CLI keeps them straight.
+---
+
+Canopy isn't a single installation: the same platform runs as a few separate
+**sites**, each with its own domain, its own projects, and its own data.
+Unless someone told you otherwise, **you're on `main` and can stop reading
+here** — the rest of this page explains what the other sites are for and how
+the CLI targets them.
+
+## The sites
+
+| Site        | Project URLs          | What it's for                                     |
+| ----------- | --------------------- | ------------------------------------------------- |
+| `main`      | `*.canopy.website`    | The real platform. Your projects live here.       |
+| `staging`   | `*.thanarie.dev`      | The platform team's testbed for platform changes. |
+| `gcp-pilot` | `*.canopy.monks.zone` | A pilot running on Google Cloud.                  |
+
+Sites are fully separate: a project on `main` doesn't exist on `staging`, and
+signing in to one doesn't create anything on another. They can also differ in
+what they support — the dashboard simply hides features a site can't honor,
+and the API says `not_supported_on_target` if asked directly.
+
+## What a profile is
+
+A **profile** is the CLI's name for a site. `canopy login` signs you in once
+via OneLogin and stores a credential for every site in one go; the profile
+just picks which one a command talks to.
+
+Three things decide the effective profile, in order:
+
+1. `--profile <id>` on the command (or the `CANOPY_PROFILE` environment
+   variable) — one-off override.
+2. The `"profile"` pinned in the project's `canopy.json` — set when the
+   project was created, so a checkout always targets the site it belongs to.
+3. Your default active profile — `main` unless you chose otherwise at login.
+
+Every command prints the site it's talking to in its header line, and
+`canopy whoami` shows your email, active profile, and API host — so there's
+never a mystery about where a deploy just went.
+
+```bash
+canopy whoami                          # who am I, on which site?
+canopy --profile gcp-pilot deploy      # one command against the pilot
+```
+
+## When you'd actually care
+
+- **Never, usually.** Day-to-day work on your own projects is all `main`,
+  and the `canopy.json` pin keeps it that way without any flags.
+- **Trying backend features.** Custom backends and
+  [schedules](https://docs.canopy.website/platform/schedules) currently run on `gcp-pilot`, so
+  experiments with those happen there.
+- **Helping test platform changes.** If the platform team asks you to check
+  something on `staging`, `--profile staging` points any command at it.
+
+> **Note:** Deploying to a different site publishes a **separate copy** of the project there — it doesn't move
+> or mirror the one on `main`. Each site keeps its own versions, data, and members.
+
+- [CLI reference](https://docs.canopy.website/guides/cli) — Every canopy command, including login, whoami, and the --profile flag.

package/dist/docs/static-serving.md

@@ -7,12 +7,10 @@ This explains the full path a browser request takes to receive a deployed
 project's `index.html` and its assets (JS/CSS/images/fonts), and reviews that
 path from a **security** and a **performance** angle.
 
-Everything a visitor sees is a _deployed_ build stored in R2. On Cloudflare
-there is no origin server running the project's code — the platform serves
-pre-built static files. (On the GCP target, `/api/*` requests dispatch to a
-per-project Cloud Run backend; everything else is still static serving. On
-Cloudflare, per-project workers remain a Phase 2 TODO and the capability is
-gated off.)
+Everything a visitor sees is a _deployed_ build stored in R2 — the platform
+serves pre-built static files. (When a project has a backend worker, `/api/*`
+requests dispatch to it — Workers for Platforms on Cloudflare, Cloud Run on
+GCP; everything else is still static serving.)
 
 Asset serving is the hottest **data-plane** path (see
 [`docs/09-plane-split.md`](../09-plane-split.md)): it lives at
@@ -213,8 +211,7 @@ These are observations, not known incidents — worth a conscious decision:
    runs on a `*.canopy.<domain>` origin that shares the session-cookie domain.
    The session cookie's flags (HttpOnly/SameSite/Secure) in
    [`session.ts`](../../apps/gateway/src/session.ts) are the mitigation to keep an
-   eye on; a per-project origin isolation (Phase 2 dev workers) would be the
-   stronger fix.
+   eye on; per-project origin isolation would be the stronger fix.
 3. **SPA fallback returns `index.html` with 200 for unknown paths**, including
    things that look like missing assets (`/assets/typo.js` → HTML). That's normal
    SPA behavior but can mask 404s and, combined with #1, is another reason

package/dist/docs/troubleshooting.md

@@ -47,11 +47,11 @@ The `CANOPY_DEPLOY_TOKEN` was revoked or is wrong. Create a new one with
 
 ## `not_supported_on_target` (501)
 
-Some features are platform-target-specific: on the Cloudflare target,
-per-project worker backends, dashboard schedules, and secret injection are not
-available and answer this error (the dashboard hides those panels). It's not a
-failure of your project — the feature doesn't exist on the target your platform
-runs on.
+Some features are platform-target-specific: a site whose platform target
+doesn't support a feature (for example per-project worker backends, dashboard
+schedules, or secret injection) answers this error, and the dashboard hides
+those panels. It's not a failure of your project — the feature doesn't exist
+on the target your platform runs on.
 
 ## `ai_budget_exceeded` (429)
 
@@ -73,9 +73,7 @@ canopy egress allow api.example.com
 
 or use dashboard Settings → Outbound hosts. Details and entry rules:
 [Outbound requests](https://docs.canopy.website/platform/egress). Calls made through the SDK /
-`env.CANOPY.fetch` don't count as egress and are unaffected. On the Cloudflare
-target outbound requests are currently unrestricted, so this error only
-appears on GCP.
+`env.CANOPY.fetch` don't count as egress and are unaffected.
 
 ## The worker returns errors and you can't see why
 

package/dist/{docs-DQmUReJR.mjs → docs-DhAz6QWS.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-yVoO2pq4.mjs";
+import { t as version } from "./package-CPXtNnfc.mjs";
 import { n as siteConfig } from "./site-BUlQR117.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
 import { n as reportErrors } from "./ui-CpdtK7mt.mjs";
@@ -9,9 +9,10 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/docs.ts
 /**
-* canopy docs — user/agent-facing guides, served live by the platform
-* (GET /control/v1/docs) so they never go stale, with a local cache and a bundled
-* snapshot as offline fallbacks.
+* canopy docs — the full docs site in the terminal (guides, platform, CLI and
+* SDK references), served live by the platform (GET /control/v1/docs) so it
+* never goes stale, with a local cache and a bundled snapshot as offline
+* fallbacks. The listing is grouped per docs-site section.
 *
 * The platform requires a login for docs (internal platform), so fetches carry
 * the CLI token when there is one; without it we simply fall back to the
@@ -98,15 +99,25 @@ function writeCache(file, content) {
 		writeFileSync(join(cacheDir, file), content);
 	} catch {}
 }
-/** Topics from cache, else from the bundled snapshot's frontmatter. */
-function topicsFromFallback() {
+/** The index from cache, else from the bundled snapshot. */
+function indexFromFallback() {
 	try {
 		const cached = JSON.parse(readFileSync(indexPath, "utf8"));
-		if (cached.topics?.length) return cached.topics;
+		if (cached.topics?.length) return {
+			topics: cached.topics,
+			sections: cached.sections
+		};
 	} catch {}
 	const dir = bundledDocsDir();
-	if (!dir) return [];
-	return readdirSync(dir).filter((f) => /\.mdx?$/.test(f)).map((f) => {
+	if (!dir) return { topics: [] };
+	try {
+		const { sections } = JSON.parse(readFileSync(join(dir, "index.json"), "utf8"));
+		if (sections?.length) return {
+			topics: sections.flatMap((s) => s.topics),
+			sections
+		};
+	} catch {}
+	return { topics: readdirSync(dir).filter((f) => /\.mdx?$/.test(f)).map((f) => {
 		const slug = f.replace(/\.mdx?$/, "");
 		const { title, summary } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
 		return {
@@ -114,7 +125,7 @@ function topicsFromFallback() {
 			title: title ?? slug,
 			summary: summary ?? ""
 		};
-	});
+	}) };
 }
 /** A single doc's body from cache, else from the bundled snapshot. */
 function bodyFromFallback(slug) {
@@ -129,7 +140,7 @@ function bodyFromFallback(slug) {
 		}
 	}
 }
-async function listTopics(refresh) {
+async function listIndex(refresh) {
 	const { apiUrl } = siteConfig();
 	if (refresh || !cacheFresh()) {
 		const data = await fetchJson(`${apiUrl}/control/v1/docs`);
@@ -138,10 +149,10 @@ async function listTopics(refresh) {
 				fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				...data
 			}));
-			return data.topics;
+			return data;
 		}
 	}
-	return topicsFromFallback();
+	return indexFromFallback();
 }
 async function readTopic(slug, refresh) {
 	const { apiUrl } = siteConfig();
@@ -157,7 +168,7 @@ async function readTopic(slug, refresh) {
 const docsCommand = defineCommand({
 	meta: {
 		name: "docs",
-		description: "Read the Canopy guides (offline-capable)"
+		description: "Read the Canopy docs (offline-capable)"
 	},
 	args: {
 		topic: {
@@ -177,16 +188,27 @@ const docsCommand = defineCommand({
 		const latest = latestKnownVersion();
 		if (latest && compareSemver(version, latest) < 0) console.error(`Note: these docs describe CLI ${latest}; you have ${version} — commands or flags they mention may not exist here. Run \`canopy upgrade\`.\n`);
 		if (!topic) {
-			const topics = await listTopics(refresh);
-			if (topics.length === 0) throw new Error("No docs available — check your connection, or reinstall the CLI.");
-			const width = Math.max(...topics.map((t) => t.slug.length));
-			console.log("Canopy docs — run `canopy docs <topic>`:\n");
-			for (const t of topics) console.log(`  ${t.slug.padEnd(width)}  ${t.summary}`);
+			const index = await listIndex(refresh);
+			if (index.topics.length === 0) throw new Error("No docs available — check your connection, or reinstall the CLI.");
+			console.log("Canopy docs — run `canopy docs <topic>`:");
+			const groups = index.sections?.length ? index.sections : [{
+				key: "all",
+				title: "",
+				description: "",
+				topics: index.topics
+			}];
+			for (const section of groups) {
+				const heading = [section.title, section.description].filter(Boolean).join(" — ");
+				console.log(heading ? `\n${heading}` : "");
+				const width = Math.max(...section.topics.map((t) => t.slug.length));
+				for (const t of section.topics) console.log(`  ${t.slug.padEnd(width)}  ${t.summary}`);
+			}
 			return;
 		}
 		const body = await readTopic(topic, refresh);
 		if (body === void 0) {
-			const known = (await listTopics(false)).map((t) => t.slug).join(", ");
+			const { topics } = await listIndex(false);
+			const known = topics.map((t) => t.slug).join(", ");
 			throw new Error(`No doc "${topic}".${known ? ` Available: ${known}.` : ""}`);
 		}
 		console.log(body);

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-yVoO2pq4.mjs";
+import { t as version } from "./package-CPXtNnfc.mjs";
 import { r as siteHeaderLine, t as setInvocationProfile } from "./site-BUlQR117.mjs";
 import { a as notifyOfUpdate, o as runRefresh } from "./version-check-CcsA1QjI.mjs";
 import { defineCommand, runMain } from "citty";
@@ -63,10 +63,10 @@ const main = defineCommand({
 		login: () => import("./login-C1x1l3qg.mjs").then((m) => m.loginCommand),
 		whoami: () => import("./login-C1x1l3qg.mjs").then((m) => m.whoamiCommand),
 		logout: () => import("./login-C1x1l3qg.mjs").then((m) => m.logoutCommand),
-		create: () => import("./projects-D2fDeWNU.mjs").then((m) => m.createCommand),
-		init: () => import("./projects-D2fDeWNU.mjs").then((m) => m.initCommand),
-		projects: () => import("./projects-D2fDeWNU.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-D2fDeWNU.mjs").then((m) => m.deleteCommand),
+		create: () => import("./projects-C9TBoiW7.mjs").then((m) => m.createCommand),
+		init: () => import("./projects-C9TBoiW7.mjs").then((m) => m.initCommand),
+		projects: () => import("./projects-C9TBoiW7.mjs").then((m) => m.projectsCommand),
+		delete: () => import("./projects-C9TBoiW7.mjs").then((m) => m.deleteCommand),
 		dev: () => import("./dev-D6Sy15Wv.mjs").then((m) => m.devCommand),
 		deploy: () => import("./deploy-ClioT9ZC.mjs").then((m) => m.deployCommand),
 		promote: () => import("./deploy-ClioT9ZC.mjs").then((m) => m.promoteCommand),
@@ -78,10 +78,10 @@ const main = defineCommand({
 		db: () => import("./db-D3RKaLVU.mjs").then((m) => m.dbCommand),
 		usage: () => import("./usage-wpew0a2M.mjs").then((m) => m.usageCommand),
 		open: () => import("./open-CLSh6oez.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-DQmUReJR.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-12Ga-2UT.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-Du6U0xjp.mjs").then((m) => m.upgradeCommand),
-		logs: () => import("./logs-DBLDS3aQ.mjs").then((m) => m.logsCommand)
+		docs: () => import("./docs-DhAz6QWS.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-BCX4cUeP.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-jLu7jI0r.mjs").then((m) => m.upgradeCommand),
+		logs: () => import("./logs-DuzM-_Rn.mjs").then((m) => m.logsCommand)
 	}
 });
 if (process.argv[2] !== "upgrade") notifyOfUpdate(version);

package/dist/{logs-DBLDS3aQ.mjs → logs-DuzM-_Rn.mjs}

@@ -34,7 +34,7 @@ async function fetchLogs(slug, params) {
 	if (params.limit) query.set("limit", String(params.limit));
 	return withContext(apiRequest("GET", `/projects/${slug}/logs?${query}`), {
 		action: `read worker logs for "${slug}"`,
-		fixes: { not_supported_on_target: "Worker logs aren't available on this site yet — GCP sites only." }
+		fixes: { not_supported_on_target: "Worker logs aren't available on this site yet." }
 	});
 }
 const logsCommand = defineCommand({

package/dist/{package-yVoO2pq4.mjs → package-CPXtNnfc.mjs}

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.7.5";
+var version = "0.7.6";
 //#endregion
 export { version as t };

package/dist/{projects-D2fDeWNU.mjs → projects-C9TBoiW7.mjs}

@@ -30,10 +30,9 @@ const TEMPLATES = [
 	},
 	{
 		id: "worker",
-		label: "React SPA + backend Worker",
-		hint: "adds Hono handlers in worker/ — Phase 2 preview",
-		needsInstall: true,
-		hidden: true
+		label: "React SPA + backend worker",
+		hint: "spa plus server-side handlers in worker/ — for secrets, schedules, external APIs",
+		needsInstall: true
 	}
 ];
 function templatesRoot() {
@@ -134,7 +133,7 @@ const createCommand = defineCommand({
 		if (scaffold && !args.template && process.stdin.isTTY) {
 			const id = unwrap(await p.select({
 				message: "Template",
-				options: TEMPLATES.filter((t) => !t.hidden).map((t) => ({
+				options: TEMPLATES.map((t) => ({
 					value: t.id,
 					label: t.label,
 					hint: t.hint
@@ -142,7 +141,6 @@ const createCommand = defineCommand({
 			}));
 			template = TEMPLATES.find((t) => t.id === id) ?? template;
 		}
-		if (template.hidden) p.log.warn("Per-project Workers are not deployable yet (Phase 2) — `canopy deploy` publishes the frontend only for now.");
 		const targetDir = resolve(slug);
 		if (scaffold && existsSync(targetDir)) throw new Error(`Directory ./${slug} already exists — remove it, or use --no-scaffold to only register.`);
 		const spin = p.spinner();
@@ -241,7 +239,7 @@ const initCommand = defineCommand({
 			if (!args.template && process.stdin.isTTY) {
 				const id = unwrap(await p.select({
 					message: "Template",
-					options: TEMPLATES.filter((t) => !t.hidden).map((t) => ({
+					options: TEMPLATES.map((t) => ({
 						value: t.id,
 						label: t.label,
 						hint: t.hint
@@ -249,7 +247,6 @@ const initCommand = defineCommand({
 				}));
 				template = TEMPLATES.find((t) => t.id === id) ?? template;
 			}
-			if (template.hidden) p.log.warn("Per-project Workers are not deployable yet (Phase 2) — `canopy deploy` publishes the frontend only for now.");
 			scaffoldTemplate(template.id, targetDir, {
 				name: project.name,
 				slug

package/dist/skill/canopy/SKILL.md

@@ -75,10 +75,12 @@ canopy docs            # list all topics
 canopy docs deploy     # print one topic
 ```
 
-Available topics include: `getting-started`, `cli` (full command reference),
-`deploy`, `dev`, `data`, `ci`, `troubleshooting`. Always prefer `canopy docs`
-and `canopy <command> --help` over guessing flags — they are the source of
-truth and never go stale.
+The listing is grouped by section: guides (`getting-started`, `deploy`, `dev`,
+`data`, `ci`, `troubleshooting`, …), platform feature pages (`platform-*`), a
+per-command CLI reference (`cli-<command>`, plus `cli` for the one-page
+overview), and the SDK reference (`sdk-*`). Always prefer `canopy docs` and
+`canopy <command> --help` over guessing flags — they are the source of truth
+and never go stale.
 
 ## Command map (quick orientation — see `canopy docs cli` for detail)
 
@@ -133,10 +135,10 @@ Prefer **`spa`** the moment either is true — which covers most real projects:
 - **The app will grow.** `spa` is Vite + React + TypeScript, giving components,
   routing, and state a real home; `static` has no build step to organise into.
 
-Use **`worker`** (`--template worker`; hidden from the picker) only when you
-need server-side backend code — e.g. calling an external API with a secret the
-browser can't hold. Per-project Workers are a Phase 2 preview (frontend deploys
-now; `worker/` is picked up once the platform supports it).
+Use **`worker`** when you need server-side backend code — e.g. calling an
+external API with a secret the browser can't hold, or running scheduled jobs.
+It's `spa` plus Hono-style handlers in `worker/`; `canopy deploy` publishes
+the frontend and the worker together.
 
 Non-interactive: `canopy create "My App" --template spa`. **When unsure between
 `static` and `spa`, pick `spa`.**

package/dist/{skill-12Ga-2UT.mjs → skill-BCX4cUeP.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-yVoO2pq4.mjs";
+import { t as version } from "./package-CPXtNnfc.mjs";
 import { n as reportErrors } from "./ui-CpdtK7mt.mjs";
 import { defineCommand } from "citty";
 import { cpSync, existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";

package/dist/templates/worker/AGENTS.md

@@ -5,9 +5,6 @@ A Vite + React single-page app plus a per-project backend Worker on
 projects. Everything is served behind company login; there is no
 infrastructure to manage and none should be added.
 
-> On GCP, `canopy deploy` publishes the frontend **and** the `worker/`
-> backend (Cloud Run). Cloudflare WfP upload is still Phase 2.
-
 ## Canopy skill
 
 The full SDK reference (auth, db, blob, ai) and platform guardrails ship as an

package/dist/templates/worker/README.md

@@ -4,14 +4,10 @@ A [Canopy](https://dashboard.thanarie.dev) project — Vite + React with a
 backend Worker (`worker/`). Live (behind company login) at
 https://{{slug}}.thanarie.dev after the first `canopy deploy`.
 
-> Per-project Workers are a Canopy Phase 2 capability: `canopy deploy`
-> publishes the frontend only for now — `worker/` deploys automatically once
-> the platform supports it.
-
 - `npm install` — once, then:
 - `canopy dev` — develop locally against the live platform (real data!)
 - `canopy dev --local [--pull]` — offline sandbox with local data instead
-- `canopy deploy` — build and publish `dist/`
+- `canopy deploy` — build and publish the frontend and the `worker/` backend
 - `AGENTS.md` — project guardrails and skill setup for coding agents
 
 Push-to-main deploys are prepared in `.github/workflows/canopy-deploy.yml`

package/dist/{upgrade-Du6U0xjp.mjs → upgrade-jLu7jI0r.mjs}

@@ -112,7 +112,7 @@ const upgradeCommand = defineCommand({
 		const spec = `${PACKAGE_NAME}@${args.version ?? "latest"}`;
 		const command = pmCommand(pm);
 		const cmd = installArgs(pm, spec);
-		const { skillInstalled } = await import("./skill-12Ga-2UT.mjs");
+		const { skillInstalled } = await import("./skill-BCX4cUeP.mjs");
 		const refreshSkill = skillInstalled(process.cwd());
 		console.log(`Upgrading via ${command}: ${command} ${cmd.join(" ")}`);
 		await run(command, cmd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediamonks/canopy-cli",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"
@@ -20,8 +20,8 @@
     "esbuild": "^0.28.1",
     "hono": "^4.8.0",
     "vite-server": "npm:vite@^7",
-    "@mediamonks/canopy": "0.0.4",
-    "@mediamonks/canopy-data-plane": "0.0.2"
+    "@mediamonks/canopy-data-plane": "0.0.2",
+    "@mediamonks/canopy": "0.0.4"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",