@mediamonks/canopy-cli 0.5.1 → 0.6.0

package/dist/docs/sdk.md

@@ -0,0 +1,113 @@
+---
+title: Using the SDK
+description: One typed client for auth, data, files, AI, and services — no keys, no connection strings, the platform authenticates for you.
+---
+
+`@mediamonks/canopy` is a thin, typed client over the platform's project API.
+One `createCanopy()` call gives you five modules — `auth`, `db`, `blob`, `ai`,
+and `services` — and that is the entire surface. There are no API keys,
+connection strings, or environment variables to manage: every call rides the
+session the platform already established before your code ran.
+
+The same code works everywhere your project runs — in the browser during
+`canopy dev`, in the deployed site, and in a project's backend worker.
+
+## Getting the SDK
+
+You usually don't install anything. The `spa` and `worker` templates ship with
+`@mediamonks/canopy` in `package.json`; the `static` template imports the same
+bundle straight from the platform, untyped but always version-matched to the
+API:
+
+```ts
+// spa / worker templates (typed, from npm)
+import { createCanopy } from "@mediamonks/canopy";
+
+// static template (untyped, served by the platform)
+import { createCanopy } from "/_api/data/v1/sdk.js";
+```
+
+## createCanopy(config)
+
+`createCanopy` takes an optional config object and returns the client:
+
+```ts
+import { createCanopy } from "@mediamonks/canopy";
+
+const canopy = createCanopy();
+// canopy.auth, canopy.db, canopy.blob, canopy.ai, canopy.services
+```
+
+| Option    | Type           | Default        | What it does                                                                                         |
+| --------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
+| `baseUrl` | `string`       | `"/_api"`      | Base URL of the platform data API. The default is same-origin, so it works untouched in the browser. |
+| `fetch`   | `typeof fetch` | global `fetch` | Override how requests are sent — a backend worker passes its platform service binding here.          |
+
+In the browser no config is needed. In a backend worker (the `worker`
+template), the platform is reachable through the `CANOPY` service binding, so
+create the client per request with that binding's fetch:
+
+```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 from the backend, ${user.name}!` });
+});
+```
+
+## One instance, shared
+
+In the browser, create the client once and import it everywhere. The scaffolds
+do this in `src/canopy.ts`:
+
+```ts
+// src/canopy.ts
+import { createCanopy } from "@mediamonks/canopy";
+
+export const canopy = createCanopy();
+```
+
+## Error handling
+
+Any call that fails throws a `CanopyError` (exported from the package). It
+extends `Error` with the HTTP `status` of the failed request; `message` carries
+the response body when the platform sent one:
+
+```ts
+import { CanopyError } from "@mediamonks/canopy";
+
+try {
+  await canopy.db.collection("todos").insert({ title: "hi", done: false });
+} catch (err) {
+  if (err instanceof CanopyError && err.status === 403) {
+    // e.g. a viewer hitting a write — show a friendly message
+  }
+  throw err;
+}
+```
+
+Two read calls are deliberately soft instead: `collection.get(id)` and
+`blob.get(key)` resolve to `null` for a missing document or object rather than
+throwing.
+
+## Where it runs
+
+The client is plain `fetch` underneath, so behavior is identical across
+environments:
+
+- **Browser, deployed** — calls go to same-origin `/_api`; the platform
+  authenticated the visitor before your page loaded, and the session cookie
+  rides along automatically.
+- **Browser, `canopy dev`** — the dev server proxies `/_api` to the platform
+  with your CLI login, so local code talks to your project's real data.
+- **Backend worker** — pass the `CANOPY` service binding's fetch (shown
+  above); the incoming request's identity carries through, so `auth.user()`
+  and per-project budgets behave exactly as in the browser.
+
+## Modules
+
+- [Auth](https://docs.canopy.website/sdk/auth) — who is signed in, and ending sessions.
+- [Database](https://docs.canopy.website/sdk/database) — document collections, plus a raw SQL escape hatch.
+- [Files](https://docs.canopy.website/sdk/files) — private blob storage under the project's prefix.
+- [AI](https://docs.canopy.website/sdk/ai) — metered, budget-capped LLM access.
+- [Services](https://docs.canopy.website/sdk/services) — curated internal data services.

package/dist/docs/static-serving.md

@@ -1,4 +1,7 @@
-# How static files are served
+---
+title: How static files are served
+description: The full path a browser request takes to a deployed file.
+---
 
 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

package/dist/docs/troubleshooting.md

@@ -1,10 +1,8 @@
 ---
 title: Troubleshooting
-summary: Common errors and how to resolve them.
+description: Common errors and how to resolve them.
 ---
 
-# Troubleshooting
-
 ## `command not found: canopy`
 
 The CLI isn't installed or isn't on your PATH. Install it:

package/dist/{docs-DvSPpSIR.mjs → docs-Cept8t_3.mjs}

@@ -1,5 +1,5 @@
-import { n as siteConfig } from "./site-BJjoePQS.mjs";
-import { n as reportErrors } from "./ui-DThlyHgo.mjs";
+import { n as siteConfig } from "./site-DQnysZ3W.mjs";
+import { n as reportErrors } from "./ui-BhzMeKQl.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -24,12 +24,20 @@ const cacheDir = join(homedir(), ".canopy", "docs-cache");
 const indexPath = join(cacheDir, "index.json");
 const CACHE_TTL_MS = 3600 * 1e3;
 const FETCH_TIMEOUT_MS = 4e3;
-/** The bundled snapshot dir: dist/docs when published, repo docs/guides in dev. */
+/**
+* The bundled snapshot dir: dist/docs when published (generated by
+* sync-templates from the terminal-docs corpus), with raw guide sources as a
+* dev last resort — those are MDX, which agents read fine untransformed.
+*/
 function bundledDocsDir() {
 	const base = fileURLToPath(new URL(".", import.meta.url));
-	for (const candidate of [join(base, "docs"), join(base, "..", "..", "..", "docs", "guides")]) if (existsSync(candidate)) return candidate;
+	for (const candidate of [
+		join(base, "docs"),
+		join(base, "..", "dist", "docs"),
+		join(base, "..", "..", "..", "apps", "docs", "content", "docs", "guides")
+	]) if (existsSync(candidate)) return candidate;
 }
-/** Parse `---\ntitle: …\nsummary: …\n---\n<body>` frontmatter. */
+/** Parse `---\ntitle: …\ndescription: …\n---\n<body>` frontmatter. */
 function parseFrontmatter(raw) {
 	const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
 	if (!match?.[1] || match[2] === void 0) return { body: raw.trim() };
@@ -40,7 +48,7 @@ function parseFrontmatter(raw) {
 	}
 	return {
 		title: meta["title"],
-		summary: meta["summary"],
+		summary: meta["description"] ?? meta["summary"],
 		body: match[2].trim()
 	};
 }
@@ -96,8 +104,8 @@ function topicsFromFallback() {
 	} catch {}
 	const dir = bundledDocsDir();
 	if (!dir) return [];
-	return readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => {
-		const slug = f.replace(/\.md$/, "");
+	return readdirSync(dir).filter((f) => /\.mdx?$/.test(f)).map((f) => {
+		const slug = f.replace(/\.mdx?$/, "");
 		const { title, summary } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
 		return {
 			slug,
@@ -111,8 +119,13 @@ function bodyFromFallback(slug) {
 	const cached = join(cacheDir, `${slug}.md`);
 	if (existsSync(cached)) return readFileSync(cached, "utf8");
 	const dir = bundledDocsDir();
-	const file = dir && join(dir, `${slug}.md`);
-	if (file && existsSync(file)) return parseFrontmatter(readFileSync(file, "utf8")).body;
+	for (const ext of [".md", ".mdx"]) {
+		const file = dir && join(dir, `${slug}${ext}`);
+		if (file && existsSync(file)) {
+			const { title, body } = parseFrontmatter(readFileSync(file, "utf8"));
+			return title ? `# ${title}\n\n${body}` : body;
+		}
+	}
 }
 async function listTopics(refresh) {
 	const { apiUrl } = siteConfig();

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { t as version } from "./package-CHoZKzaw.mjs";
-import { r as siteHeaderLine, t as setInvocationProfile } from "./site-BJjoePQS.mjs";
+import { t as version } from "./package-D1wDsLSU.mjs";
+import { r as siteHeaderLine, t as setInvocationProfile } from "./site-DQnysZ3W.mjs";
 import { i as runRefresh, r as notifyOfUpdate } from "./version-check-Cuh6HaLX.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/index.ts
@@ -73,24 +73,24 @@ const main = defineCommand({
 		description: "canopy — create and deploy vibecoded projects"
 	},
 	subCommands: {
-		login: () => import("./login-BO6abf40.mjs").then((m) => m.loginCommand),
-		whoami: () => import("./login-BO6abf40.mjs").then((m) => m.whoamiCommand),
-		logout: () => import("./login-BO6abf40.mjs").then((m) => m.logoutCommand),
-		create: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.createCommand),
-		init: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.initCommand),
-		projects: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.deleteCommand),
-		dev: () => import("./dev-BJ5xEwqW.mjs").then((m) => m.devCommand),
-		deploy: () => import("./deploy-alC2--pZ.mjs").then((m) => m.deployCommand),
-		rollback: () => import("./deploy-alC2--pZ.mjs").then((m) => m.rollbackCommand),
-		download: () => import("./deploy-alC2--pZ.mjs").then((m) => m.downloadCommand),
-		token: () => import("./token-BeF9zczg.mjs").then((m) => m.tokenCommand),
-		db: () => import("./db-BW1ZolWn.mjs").then((m) => m.dbCommand),
-		usage: () => import("./usage-DQpH7A3X.mjs").then((m) => m.usageCommand),
-		open: () => import("./open-DnlYDqrU.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-DvSPpSIR.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-CW0QSbAJ.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-CGz1yzsW.mjs").then((m) => m.upgradeCommand),
+		login: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.loginCommand),
+		whoami: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.whoamiCommand),
+		logout: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.logoutCommand),
+		create: () => import("./projects-CoGh8m9A.mjs").then((m) => m.createCommand),
+		init: () => import("./projects-CoGh8m9A.mjs").then((m) => m.initCommand),
+		projects: () => import("./projects-CoGh8m9A.mjs").then((m) => m.projectsCommand),
+		delete: () => import("./projects-CoGh8m9A.mjs").then((m) => m.deleteCommand),
+		dev: () => import("./dev-DV5ud7AJ.mjs").then((m) => m.devCommand),
+		deploy: () => import("./deploy-DdSSL227.mjs").then((m) => m.deployCommand),
+		rollback: () => import("./deploy-DdSSL227.mjs").then((m) => m.rollbackCommand),
+		download: () => import("./deploy-DdSSL227.mjs").then((m) => m.downloadCommand),
+		token: () => import("./token-CWgp_Lqe.mjs").then((m) => m.tokenCommand),
+		db: () => import("./db-BpnjQUkF.mjs").then((m) => m.dbCommand),
+		usage: () => import("./usage-CYQRLXwf.mjs").then((m) => m.usageCommand),
+		open: () => import("./open-BmgYBSdR.mjs").then((m) => m.openCommand),
+		docs: () => import("./docs-Cept8t_3.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-192EdixC.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-BrHSSg2e.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });