@mediamonks/canopy-cli 0.3.0 → 0.4.0

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/getting-started.md

@@ -60,9 +60,14 @@ 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 static
+canopy create "My App" --scaffold --template spa
 ```
 
+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

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-DyEUYkEq.mjs";
+import { t as version } from "./package-BNWFYk8y.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-DJT_mJDR.mjs").then((m) => m.createCommand),
-		projects: () => import("./projects-DJT_mJDR.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-DJT_mJDR.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-nN0e59rO.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-C5IoUEZg.mjs").then((m) => m.upgradeCommand),
+		skill: () => import("./skill-esz0u6PO.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-D_fgGLxu.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });

package/dist/{package-DyEUYkEq.mjs → package-BNWFYk8y.mjs}

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

package/dist/{projects-DJT_mJDR.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";
@@ -21,12 +21,12 @@ const TEMPLATES = [
 	{
 		id: "static",
 		label: "Static site",
-		hint: "plain html/css/js, no build step (default)"
+		hint: "plain html/css/js, no build; untyped SDK from the platform — simplest apps only"
 	},
 	{
 		id: "spa",
 		label: "React SPA",
-		hint: "Vite + React + TypeScript, SDK from npm",
+		hint: "Vite + React + TypeScript, typed SDK from npm — best for real SDK use or growth",
 		needsInstall: true
 	},
 	{
@@ -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

@@ -62,7 +62,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,6 +74,30 @@ 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` / `canopy init`)
+
+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.
+
+Prefer **`spa`** the moment either is true — which covers most real projects:
+
+- **You lean on the SDK** (`db` queries, `blob`, `ai` — anything past a stray
+  `auth.user()`). `spa` installs the SDK from npm (`@mediamonks/canopy`), fully
+  typed, so the compiler catches mistakes as you write them.
+- **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).
+
+Non-interactive: `canopy create "My App" --template spa`. **When unsure between
+`static` and `spa`, pick `spa`.**
+
 ## Safety rules
 
 - **Destructive commands** — `canopy db restore` and `canopy delete` wipe data.

package/dist/{skill-nN0e59rO.mjs → skill-esz0u6PO.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-DyEUYkEq.mjs";
+import { t as version } from "./package-BNWFYk8y.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-C5IoUEZg.mjs → upgrade-D_fgGLxu.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-nN0e59rO.mjs");
+		const { skillInstalled } = await import("./skill-esz0u6PO.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.0",
+  "version": "0.4.0",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"
@@ -19,8 +19,8 @@
     "hono": "^4.8.0",
     "miniflare": "^4.20260714.0",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
-    "@mediamonks/canopy": "0.0.1",
-    "@mediamonks/canopy-data-plane": "0.0.1"
+    "@mediamonks/canopy-data-plane": "0.0.1",
+    "@mediamonks/canopy": "0.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",