@mediamonks/canopy-cli 0.3.1 → 0.4.1

package/dist/docs/cli.md

@@ -17,10 +17,16 @@ is the overview.
 
 ## Projects
 
-- `canopy create [name]` — create and register a project.
+- `canopy create [name]` — register a **new** project (and scaffold it).
   - `--slug <slug>` — URL slug (defaults to a slugified name).
   - `--template <id>` — `static` | `spa` | `worker` (picker when omitted).
-  - `--scaffold` — write `./<slug>/` from the starter template.
+  - `--scaffold` — write `./<slug>/` from the starter template (on by default;
+    `--no-scaffold` to only register).
+- `canopy init [slug] [dir]` — set up a local folder for an **existing** project
+  (e.g. one created in the dashboard) — does **not** register a new project.
+  - `dir` — `.` for the current directory, a path, or `./<slug>/` when omitted.
+  - `--template <id>` — template to scaffold (picker when omitted).
+  - `--no-scaffold` — link an app you already have: just write a `canopy.json`.
 - `canopy projects` — list your projects. `--all` includes ones you can't edit.
 - `canopy delete [slug]` — full teardown of a project. `--yes` skips the
   type-the-slug confirmation.

package/dist/docs/data.md

@@ -9,6 +9,23 @@ Each Canopy project gets its own database (D1) and blob storage (R2). 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 SQLite storage, so keeping it lowercase avoids case-sensitivity surprises.
+
 ## Download a dump
 
 ```bash

package/dist/docs/getting-started.md

@@ -50,7 +50,7 @@ Check who you are at any time:
 canopy whoami
 ```
 
-## 3. Create a project
+## 3. Create your first project
 
 ```bash
 canopy create
@@ -63,6 +63,11 @@ directory, and registers the project on the platform. To skip the prompts:
 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

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-B34Xg7L3.mjs";
+import { t as version } from "./package-CA5g4zPx.mjs";
 import { i as runRefresh, r as notifyOfUpdate } from "./version-check-CoWgQs2h.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/index.ts
@@ -44,9 +44,10 @@ const main = defineCommand({
 		login: () => import("./login-Dif9Y32q.mjs").then((m) => m.loginCommand),
 		whoami: () => import("./login-Dif9Y32q.mjs").then((m) => m.whoamiCommand),
 		logout: () => import("./login-Dif9Y32q.mjs").then((m) => m.logoutCommand),
-		create: () => import("./projects-DOYKtMZC.mjs").then((m) => m.createCommand),
-		projects: () => import("./projects-DOYKtMZC.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-DOYKtMZC.mjs").then((m) => m.deleteCommand),
+		create: () => import("./projects-DbKcG5kx.mjs").then((m) => m.createCommand),
+		init: () => import("./projects-DbKcG5kx.mjs").then((m) => m.initCommand),
+		projects: () => import("./projects-DbKcG5kx.mjs").then((m) => m.projectsCommand),
+		delete: () => import("./projects-DbKcG5kx.mjs").then((m) => m.deleteCommand),
 		dev: () => import("./dev-D_GlUULk.mjs").then((m) => m.devCommand),
 		deploy: () => import("./deploy-N88l4Kt3.mjs").then((m) => m.deployCommand),
 		rollback: () => import("./deploy-N88l4Kt3.mjs").then((m) => m.rollbackCommand),
@@ -54,8 +55,8 @@ const main = defineCommand({
 		db: () => import("./db-CtUG4vfG.mjs").then((m) => m.dbCommand),
 		open: () => import("./open-xLiGUz_W.mjs").then((m) => m.openCommand),
 		docs: () => import("./docs-C3aOAx_A.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-BlRch5eA.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-DblPIwpX.mjs").then((m) => m.upgradeCommand),
+		skill: () => import("./skill-DMs7GNl7.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-BMTdpOxO.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });

package/dist/{package-B34Xg7L3.mjs → package-CA5g4zPx.mjs}

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

package/dist/{projects-DOYKtMZC.mjs → projects-DbKcG5kx.mjs}

@@ -1,5 +1,5 @@
 import { t as apiRequest } from "./api-CyJ-wBZh.mjs";
-import { r as projectUrl } from "./project-CpiPLNby.mjs";
+import { a as tryReadCanopyJson, r as projectUrl } from "./project-CpiPLNby.mjs";
 import { i as unwrap, n as reportErrors, r as requireTty } from "./ui-C8VuPzGp.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
@@ -156,6 +156,104 @@ const createCommand = defineCommand({
 		} else p.outro("Registered without scaffolding — add a canopy.json to deploy an existing app.");
 	})
 });
+/** Empty enough to scaffold into: missing, or holding only dotfiles (.git, .agents…). */
+function isEmptyish(dir) {
+	if (!existsSync(dir)) return true;
+	return readdirSync(dir).every((name) => name.startsWith("."));
+}
+const initCommand = defineCommand({
+	meta: {
+		name: "init",
+		description: "Set up a local folder for an existing project (dashboard or CLI created)"
+	},
+	args: {
+		slug: {
+			type: "positional",
+			description: "Project slug (picked from your projects when omitted)",
+			required: false
+		},
+		dir: {
+			type: "positional",
+			description: "Target directory: '.' for the current dir, a path, or ./<slug>/ when omitted",
+			required: false
+		},
+		template: {
+			type: "string",
+			description: `Template to scaffold: ${TEMPLATES.map((t) => t.id).join(" | ")} (picker when omitted)`
+		},
+		scaffold: {
+			type: "boolean",
+			default: true,
+			description: "Scaffold from a starter template",
+			negativeDescription: "Only link an existing app — write a canopy.json, no template"
+		}
+	},
+	run: reportErrors("init", async ({ args }) => {
+		p.intro("canopy init");
+		const { projects, is_admin: isAdmin } = await apiRequest("GET", "/projects");
+		const editable = isAdmin ? projects : projects.filter((project) => project.role);
+		let slug = args.slug?.trim();
+		if (slug) {
+			if (!projects.some((project) => project.slug === slug)) throw new Error(`No project "${slug}" — check the slug, or create it with \`canopy create\`.`);
+			if (!editable.some((project) => project.slug === slug)) throw new Error(`You don't have edit access to "${slug}".`);
+		} else {
+			requireTty("pass the project slug as an argument.");
+			if (editable.length === 0) throw new Error("You have no projects to set up — create one with `canopy create`, or in the dashboard.");
+			slug = unwrap(await p.select({
+				message: "Project",
+				options: editable.map((project) => ({
+					value: project.slug,
+					label: project.slug,
+					hint: project.name
+				}))
+			}));
+		}
+		const project = projects.find((candidate) => candidate.slug === slug);
+		if (!project) throw new Error(`No project "${slug}".`);
+		const dirArg = args.dir;
+		const targetDir = dirArg === "." ? process.cwd() : resolve(dirArg ?? slug);
+		const rel = relative(process.cwd(), targetDir) || ".";
+		if (args.scaffold) {
+			if (!isEmptyish(targetDir)) throw new Error(`${rel} already has files — link it with \`canopy init ${slug} ${rel} --no-scaffold\`, or pick an empty directory.`);
+			let template = TEMPLATES.find((t) => t.id === (args.template ?? "static"));
+			if (!template) throw new Error(`Unknown template "${args.template}" — available: ${TEMPLATES.map((t) => t.id).join(", ")}.`);
+			if (!args.template && process.stdin.isTTY) {
+				const id = unwrap(await p.select({
+					message: "Template",
+					options: TEMPLATES.filter((t) => !t.hidden).map((t) => ({
+						value: t.id,
+						label: t.label,
+						hint: t.hint
+					}))
+				}));
+				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
+			});
+			const steps = [
+				...rel === "." ? [] : [`cd ${rel}`],
+				...template.needsInstall ? ["npm install"] : [],
+				"canopy dev   (or deploy right away: canopy deploy)"
+			];
+			p.note(steps.join("\n"), `Scaffolded ${rel}/ (${template.id}) for ${slug} — next`);
+			p.outro(`Live URL (after first deploy): ${projectUrl(slug)}`);
+			return;
+		}
+		mkdirSync(targetDir, { recursive: true });
+		const existing = tryReadCanopyJson(targetDir);
+		if (existing?.slug && existing.slug !== slug) throw new Error(`${rel}/canopy.json already links to "${existing.slug}" — remove it to relink to "${slug}".`);
+		if (existing?.slug === slug) {
+			p.outro(`${rel} is already linked to ${slug}.`);
+			return;
+		}
+		writeFileSync(join(targetDir, "canopy.json"), `${JSON.stringify({ slug }, null, 2)}\n`);
+		p.note("Add \"dist\"/\"build\" to canopy.json if this app has a build step, then:\ncanopy deploy", `Linked ${rel} to ${slug}`);
+		p.outro(`Live URL (after first deploy): ${projectUrl(slug)}`);
+	})
+});
 const projectsCommand = defineCommand({
 	meta: {
 		name: "projects",
@@ -225,4 +323,4 @@ const deleteCommand = defineCommand({
 	})
 });
 //#endregion
-export { createCommand, deleteCommand, projectsCommand };
+export { createCommand, deleteCommand, initCommand, projectsCommand };

package/dist/skill/canopy/SKILL.md

@@ -45,6 +45,26 @@ canopy whoami      # is there a valid login?
 
 Skip login if `canopy whoami` already shows a valid, unexpired token.
 
+## Then: offer to build their first project
+
+Once the CLI is installed and signed in, **do not just print a list of
+commands and stop.** The person following the getting-started prompt is often
+non-technical and expects you to drive. Take the lead:
+
+1. Ask them, in plain language, whether they'd like to create their first
+   Canopy project now — and **what it's about** (what should it do, who's it
+   for). Ask one short question at a time; wait for the answer.
+2. From their answer, pick a sensible name and template (see the template
+   guidance below — default to `spa` for anything beyond a trivial page), then
+   scaffold it for them non-interactively, e.g.
+   `canopy create "Their App Name" --template spa`.
+3. `cd` into the new folder, then keep going — build the thing they described,
+   running `canopy dev` to preview and `canopy docs`/`canopy <cmd> --help`
+   whenever you need platform details.
+
+Only fall back to handing them raw commands if they say they'd rather do it
+themselves. The goal is a working first project, not a command cheat-sheet.
+
 ## Then: read the docs for whatever you're doing
 
 The CLI ships the full documentation and keeps it fresh from the platform. List
@@ -62,7 +82,11 @@ truth and never go stale.
 
 ## Command map (quick orientation — see `canopy docs cli` for detail)
 
-- Create a project: `canopy create`
+- Create a **new** project: `canopy create`
+- Set up a folder for an **existing** project (e.g. made in the dashboard):
+  `canopy init <slug>` — never use `canopy create` for a project that already
+  exists; that would register a duplicate. `canopy init <slug> .` targets the
+  current directory; add `--no-scaffold` to link an app you already have.
 - Run locally: `canopy dev` (live data) or `canopy dev --local` (offline sandbox)
 - Deploy: `canopy deploy` (add `--build` if the project has a build step)
 - Roll back: `canopy rollback`
@@ -70,9 +94,10 @@ truth and never go stale.
 - Manage data: `canopy db pull | snapshot | snapshots | restore`
 - CI credentials: `canopy token create | list | revoke`
 
-## Choosing a starter template (`canopy create`)
+## Choosing a starter template (`canopy create` / `canopy init`)
 
-`canopy create` offers three scaffolds. **`static` is the default, but reach
+Both `canopy create` and `canopy init` scaffold from the same three templates.
+**`static` is the default, but reach
 for it only when the app is genuinely trivial** — a page or two with light SDK
 use. Its SDK is served untyped from the platform (`/_api/v1/sdk.js`): no
 autocomplete, no type-checking, mistakes only show up in the browser.

package/dist/{skill-BlRch5eA.mjs → skill-DMs7GNl7.mjs}

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

package/dist/{upgrade-DblPIwpX.mjs → upgrade-BMTdpOxO.mjs}

@@ -115,7 +115,7 @@ const upgradeCommand = defineCommand({
 		console.log(`Upgrading via ${command}: ${command} ${cmd.join(" ")}`);
 		await run(command, cmd);
 		console.log(`\nDone. Run \`canopy --version\` to confirm.`);
-		const { skillInstalled } = await import("./skill-BlRch5eA.mjs");
+		const { skillInstalled } = await import("./skill-DMs7GNl7.mjs");
 		if (skillInstalled(process.cwd())) {
 			console.log("Refreshing the Canopy agent skill in this repo…");
 			await run("canopy", ["skill", "install"]).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediamonks/canopy-cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"