@mediamonks/canopy-cli 0.7.43 → 0.7.44

package/dist/docs/platform-members-and-access.md

@@ -1,6 +1,6 @@
 ---
 title: Members & access
-description: Everything on Canopy sits behind Monks sign-in. Collaborators manage a project; other Monks can view the live app — unless you tighten it.
+description: Everything on Canopy sits behind Monks sign-in. Editors manage a project, viewers open it, and your app can hand out its own roles on top.
 ---
 
 Nothing on Canopy is reachable by the anonymous internet. Every project URL
@@ -23,52 +23,76 @@ nobody outside the team can touch its data or settings.
 
 ## Roles
 
-- **Owner** — the person who created the project. Owners govern it: they
-  invite and remove collaborators, change access settings, and can delete
-  the project.
-- **Collaborator** — invited teammates. They can do day-to-day work — deploy,
-  roll back, browse and edit data, manage schedules and secrets — but not
-  delete the project or manage its roster.
-- **Platform admin** — can manage any project from the dashboard. Admins keep
-  governance access, but they do not silently bypass a collaborators-only
-  live app (see below).
-
-## Inviting collaborators
-
-Open the project's **Settings** tab and use the **Collaborators** card. Start
-typing a name or email: colleagues who have signed in to Canopy before show up
-as suggestions, and picking one adds them immediately.
-
-Someone who has never opened Canopy can be added too — type their full
-company email and choose **Invite by email**. They appear on the roster as
-**invited** and become a collaborator automatically the first time they sign
-in, whether that's opening the project's URL or running `canopy login`. Until
-then the invite grants nothing. You can withdraw a pending invite from the
-same card. Canopy doesn't send them a message, so let them know yourself.
-
-Only company addresses that can sign in to Canopy can be invited. Owners (and
-admins) can also remove people from the same card.
-
-## Collaborators-only mode
-
-Sometimes "any Monk can look" is too open — payroll prototypes, sensitive
-client work, unfinished things you'd rather not demo by accident. Flip on
-**Settings → Who at Monks can open it → Restrict to collaborators** and the
-live app is limited to the project's roster:
-
-- Other Monks who open the URL get a clear "limited to its collaborators"
-  page instead of the app.
-- The project still appears in the company list — it isn't hidden, just
+Everyone on a project's roster has one Canopy role:
+
+- **Owner**: the person who created the project. Owners govern it: they add
+  and remove members, decide who is an editor or a viewer, change access
+  settings, and can delete the project.
+- **Editor**: does the day-to-day work. Editors deploy, roll back, browse and
+  edit data, and manage schedules, secrets and app roles. They can't delete
+  the project or change who is on it.
+- **Viewer**: can open the app, and nothing else. Viewers don't see the
+  project's management pages. Adding someone as a viewer only makes a
+  difference when the project is limited to members, or when you give them
+  [app roles](#app-roles).
+- **Platform admin**: can manage any project from the dashboard. Admins don't
+  quietly get past a members-only app (see below).
+
+## Adding members
+
+Open the project's **Settings → Access** page and use the **Members** card.
+Start typing a name or email: colleagues who have signed in to Canopy before
+show up as suggestions. Pick **Editor** or **Viewer** and add them.
+
+Someone who has never opened Canopy can be added too. Type their full company
+email and choose **Invite by email**. They show up as **invited** and join
+automatically the first time they sign in, whether that's opening the
+project's URL or running `canopy login`. Until then the invite grants nothing.
+Canopy doesn't send them a message, so let them know yourself.
+
+The owner can switch anyone between editor and viewer, remove people, or
+withdraw an invite from the same card. From a terminal,
+[`canopy members`](https://docs.canopy.website/cli/members) does the same.
+
+## App roles
+
+Many apps need their own permissions: "everyone can look, but only a few
+people approve", or "only these people get in, each with their own role".
+App roles cover that without a table of emails in your code.
+
+Under **Settings → Access → App roles**, create the roles your app needs. Each
+has a name and a slug, like `approver`. Then give members their roles from the
+Members card. Your app reads them as `roles` on the signed-in user, from
+[`auth.user()`](https://docs.canopy.website/sdk/auth) or `env.CALLER` in a backend worker.
+
+One role is always the **default**. Everyone who can open the app has it,
+client-password visitors included, so you don't have to hand it out. The first
+role you create becomes the default, and you can make another one the default
+at any time.
+
+Canopy hands roles to your app but never checks them for you. Read
+[Roles and permissions](https://docs.canopy.website/guides/roles) for how to use them safely.
+
+## Members-only mode
+
+Sometimes "any Monk can look" is too open: payroll prototypes, sensitive
+client work, unfinished things you'd rather not demo by accident. Turn on
+**Settings → Access → Who at Monks can open it → Restrict to members** and the
+live app is limited to the project's roster, editors and viewers alike:
+
+- Other Monks who open the URL get a "limited to its members" page instead of
+  the app.
+- The project still appears in the company list. It isn't hidden, just
   closed.
 - Platform admins can still manage the project in the dashboard, but they
-  must add themselves as collaborators if they need to open the live app.
-- [Client password access](https://docs.canopy.website/platform/client-access), if you've enabled
-  it, is unaffected — the two controls are independent.
+  must add themselves as members to open the live app.
+- [Client password access](https://docs.canopy.website/platform/client-access), if you've turned it on,
+  is unaffected. The two controls are independent.
 
 Turning it off again is the same toggle.
 
-> **Note:** Collaborators-only gates the **live app**. Management access (settings, data, deploys) is always
-> members-only, regardless of this toggle.
+> **Note:** Members-only gates the **live app**. Management pages (settings, data, deploys) are always for the
+> owner and editors only, whatever this toggle says.
 
 ## Platform admins and the Admin page
 

package/dist/docs/roles.md

@@ -0,0 +1,100 @@
+---
+title: Roles and permissions
+description: Give people different powers inside your app with app roles, and check them where it counts.
+---
+
+Canopy decides who can open your app. App roles decide what each person can
+do once they're in. You create the roles, give them to people, and your code
+reads them. Canopy never checks them for you.
+
+## Two kinds of role
+
+- **Canopy roles** (owner, editor, viewer) are about the project itself: who
+  can deploy, see the data, change settings. Viewers can only open the app.
+  See [Members and access](https://docs.canopy.website/platform/members-and-access).
+- **App roles** are your app's own labels, like `approver` or `admin`. They
+  mean whatever your code makes them mean.
+
+The two are independent. A viewer can be your app's `admin`, and an editor
+can have no app roles at all.
+
+## Set roles up
+
+In the dashboard, open **Settings → Access**:
+
+1. Under **App roles**, add a role. Give it a name ("Approver") and check the
+   slug (`approver`). The slug is what your code checks, and it can't change
+   later. The name can.
+2. Under **Members**, open the tag button next to someone and tick their
+   roles. To give roles to a colleague who only needs to use the app, add
+   them as a **Viewer** first.
+
+Or from a terminal, which is also how an agent sets them up:
+
+```bash
+canopy roles add "Approver"
+canopy members add jane@monks.com --viewer --app-role approver
+canopy roles list
+```
+
+## The default role
+
+The first role you create is the **default**. Everyone who can open the app
+has it: members, any other Monk on an open project, and client-password
+visitors. That lets your code treat everyone the same way ("everyone is at
+least a `user`") without listing every person. Make another role the default
+whenever you like; everyone's roles change with it. The default role can't be
+deleted while other roles exist.
+
+## Read roles in your code
+
+`roles` is a list of slugs, the default first:
+
+```ts
+const user = await canopy.auth.user();
+user.roles; // ["user", "approver"]
+```
+
+In a backend worker, `env.CALLER.roles` holds the same list without a round
+trip, and so does `env.USER.roles` for a signed-in Monk.
+
+## Check roles where it counts
+
+A check that only runs in the browser hides buttons. It doesn't protect
+anything, because a visitor can call your data and routes directly. Put the
+check that matters in your backend worker:
+
+```ts
+app.post("/api/approve/:id", async (c) => {
+  if (!c.env.CALLER?.roles?.includes("approver")) {
+    return c.json({ error: "approvers only" }, 403);
+  }
+  // only approvers get here
+});
+```
+
+Keep data that only some roles may see in tables or collections whose names
+start with `private_`. Pages can't reach those, only your worker can. See
+[Database](https://docs.canopy.website/sdk/database).
+
+## Try another role locally
+
+`canopy dev` runs with your own roles. To see the app the way someone else
+does, pass `--as-role`:
+
+```bash
+canopy dev --as-role reviewer
+```
+
+You keep the project's default role, as a real visitor would, and get
+`reviewer` instead of your own roles. It only changes your local session.
+Nothing changes on the platform.
+
+## Good to know
+
+- Role changes reach your app within a few seconds.
+- A backend deployed before app roles existed sees no `roles` on
+  `env.CALLER` until you redeploy it. `auth.user()` has them right away.
+- Client-password visitors all share one password, so they only ever get the
+  default role.
+- Scheduled runs have no caller and no roles.

package/dist/docs/sdk-auth.md

@@ -15,15 +15,16 @@ Returns the authenticated user for the current session as a `CanopyUser`:
 
 ```ts
 const user = await canopy.auth.user();
-// { id: "…", email: "ada@monks.com", name: "Ada Lovelace", kind: "monk" }
+// { id: "…", email: "ada@monks.com", name: "Ada Lovelace", kind: "monk", roles: ["user"] }
 ```
 
-| Field   | Type                   | Meaning                                                                                                                |
-| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `id`    | `string`               | Stable subject from OneLogin — safe to key user data on.                                                               |
-| `email` | `string`               | The user's email address.                                                                                              |
-| `name`  | `string`               | Display name.                                                                                                          |
-| `kind`  | `"monk" \| "external"` | `"monk"` = signed in through OneLogin; `"external"` = a visitor who got in with the project's client password instead. |
+| Field   | Type                   | Meaning                                                                                                                            |
+| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `id`    | `string`               | Stable subject from OneLogin — safe to key user data on.                                                                           |
+| `email` | `string`               | The user's email address.                                                                                                          |
+| `name`  | `string`               | Display name.                                                                                                                      |
+| `kind`  | `"monk" \| "external"` | `"monk"` = signed in through OneLogin; `"external"` = a visitor who got in with the project's client password instead.             |
+| `roles` | `string[]`             | The project's [app roles](https://docs.canopy.website/guides/roles) this person has: the default role first, then their own. Empty when the project has none. |
 
 `kind: "external"` sessions come from client-password access — clients viewing
 a shared project without a Monks account. Branch on it when externals should
@@ -46,8 +47,8 @@ if (user.kind === "external") {
 ### In a backend worker
 
 A worker route already knows who is calling, without asking: `env.CALLER`
-holds the same `id`, `email`, `name` and `kind` that `auth.user()` returns,
-plus `agent`, which is `true` when an AI agent is acting for a Monk.
+holds the same `id`, `email`, `name`, `kind` and `roles` that `auth.user()`
+returns, plus `agent`, which is `true` when an AI agent is acting for a Monk.
 
 ```ts
 import type { CanopyCaller } from "@mediamonks/canopy";
@@ -67,7 +68,20 @@ A client-password visitor has no email address and is named `"Client"`. Its
 `id` changes with every password unlock, so don't key data on it that has to
 last.
 
-A backend gets `env.CALLER` from its next deploy. Until it is redeployed,
+This is the place to check app roles, because a visitor can't change what
+your worker sees:
+
+```ts
+app.post("/api/approve/:id", (c) => {
+  if (!c.env.CALLER?.roles?.includes("approver")) {
+    return c.json({ error: "approvers only" }, 403);
+  }
+  // …
+});
+```
+
+A backend gets `env.CALLER` from its next deploy, and `roles` on it from its
+first deploy after app roles shipped. Until it is redeployed,
 `auth.user()` through the `CANOPY` binding gives the same answer:
 
 ```ts

package/dist/docs/sdk-realtime.md

@@ -121,7 +121,7 @@ right away and `onOpen` runs, so the page catches up from the database. A
 quick switch away and back keeps the connection.
 
 Every connection also renews itself about every quarter of an hour, and
-whenever access to the project changes (the client password, collaborators
+whenever access to the project changes (the client password, members
 only, someone removed). Each renewal runs `onOpen` again, which is what
 keeps the reload-on-open pattern correct.
 

package/dist/docs/static-serving.md

@@ -17,7 +17,7 @@ Every request passes the sign-in wall before a single byte of your project is
 read. A visitor arrives with a company login, or — if you've turned on
 [client access](https://docs.canopy.website/platform/client-access) — the project's password. There is no
 public URL, no "unlisted" link, and no way to opt a single file out. A project
-is readable by any signed-in colleague unless you set it to collaborators only,
+is readable by any signed-in colleague unless you set it to members only,
 in [members and access](https://docs.canopy.website/platform/members-and-access).
 
 ## Deep links work — routing is yours

package/dist/{docs-CaAgJWK3.mjs → docs-KmN6jD1S.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-XOtqboS1.mjs";
+import { t as version } from "./package-Bvly8-rB.mjs";
 import { r as siteConfig } from "./site-0i7wAJqg.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
 import { n as agentHeaders } from "./api-Bl6SG8Oq.mjs";

package/dist/{feedback-CMnG2Zvs.mjs → feedback-B5-95neo.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-XOtqboS1.mjs";
+import { t as version } from "./package-Bvly8-rB.mjs";
 import { f as tryReadCanopyJson, l as resolveProject, o as projectDirArgs, p as tryResolveProject, r as siteConfig } from "./site-0i7wAJqg.mjs";
 import { a as apiRequest, c as credentials, i as apiDownload, o as apiUpload, s as commonHeaders } from "./api-Bl6SG8Oq.mjs";
 import { r as reportErrors, t as formatDateTime } from "./ui-CLnICOne.mjs";

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-XOtqboS1.mjs";
+import { t as version } from "./package-Bvly8-rB.mjs";
 import { i as siteHeaderLine, n as setInvocationProfile } from "./site-0i7wAJqg.mjs";
 import { a as notifyOfUpdate, o as runRefresh } from "./version-check-CcsA1QjI.mjs";
 import { defineCommand, runMain } from "citty";
@@ -71,7 +71,7 @@ const main = defineCommand({
 		projects: () => import("./projects-BRG2HnBs.mjs").then((m) => m.projectsCommand),
 		delete: () => import("./projects-BRG2HnBs.mjs").then((m) => m.deleteCommand),
 		rename: () => import("./rename-BGKa25Rq.mjs").then((m) => m.renameCommand),
-		dev: () => import("./dev-BmI5kwoG.mjs").then((m) => m.devCommand),
+		dev: () => import("./dev-CUJKgaqJ.mjs").then((m) => m.devCommand),
 		deploy: () => import("./deploy-ExrIeX_m.mjs").then((m) => m.deployCommand),
 		promote: () => import("./deploy-ExrIeX_m.mjs").then((m) => m.promoteCommand),
 		staging: () => import("./staging-_2Js0Fkc.mjs").then((m) => m.stagingCommand),
@@ -80,18 +80,20 @@ const main = defineCommand({
 		token: () => import("./token-7vSNuz-X.mjs").then((m) => m.tokenCommand),
 		egress: () => import("./egress-C2amvqmE.mjs").then((m) => m.egressCommand),
 		secrets: () => import("./secrets-BjbIi7Gp.mjs").then((m) => m.secretsCommand),
+		roles: () => import("./roles-BDZaN3vi.mjs").then((m) => m.rolesCommand),
+		members: () => import("./roles-BDZaN3vi.mjs").then((m) => m.membersCommand),
 		schedule: () => import("./schedule-BcqBspn3.mjs").then((m) => m.scheduleCommand),
-		feedback: () => import("./feedback-CMnG2Zvs.mjs").then((m) => m.feedbackCommand),
+		feedback: () => import("./feedback-B5-95neo.mjs").then((m) => m.feedbackCommand),
 		db: () => import("./db-BJJGydgL.mjs").then((m) => m.dbCommand),
 		usage: () => import("./usage-DGGmTwjJ.mjs").then((m) => m.usageCommand),
 		ai: () => import("./ai-FBHTSCLZ.mjs").then((m) => m.aiCommand),
 		open: () => import("./open-Bpz4C2Sr.mjs").then((m) => m.openCommand),
-		browse: () => import("./browse-dyOThTyf.mjs").then((m) => m.browseCommand),
-		docs: () => import("./docs-CaAgJWK3.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-Ct-aCOzg.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-DJogeXAF.mjs").then((m) => m.upgradeCommand),
+		browse: () => import("./browse-B8-0dweq.mjs").then((m) => m.browseCommand),
+		docs: () => import("./docs-KmN6jD1S.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-DRLniv-I.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-D_yrD7zp.mjs").then((m) => m.upgradeCommand),
 		logs: () => import("./logs-BnrNZvLc.mjs").then((m) => m.logsCommand),
-		mcp: () => import("./mcp-BVIU4j9N.mjs").then((m) => m.mcpCommand),
+		mcp: () => import("./mcp-DZdMNTWr.mjs").then((m) => m.mcpCommand),
 		repo: () => import("./repo-DmFs6H9m.mjs").then((m) => m.repoCommand),
 		template: () => import("./project-template-715H_lnu.mjs").then((m) => m.templateCommand)
 	}

package/dist/{local-2xtxtoUd.mjs → local-CIkL7tXP.mjs}

@@ -1,6 +1,6 @@
 import { r as apiDataRequest } from "./api-Bl6SG8Oq.mjs";
-import { a as realtimeRouter, c as META_COLUMNS, l as blobRouter, n as WORKER_ATTEST_HEADER, o as dbRouter, s as hasPrivateNames } from "./src-CScXotBB.mjs";
-import { a as rewriteApiPath } from "./dev-adLLSY1F.mjs";
+import { a as realtimeRouter, c as META_COLUMNS, l as blobRouter, n as WORKER_ATTEST_HEADER, o as dbRouter, s as hasPrivateNames } from "./src-8vxOBOxW.mjs";
+import { a as rewriteApiPath } from "./dev-Cq98yblV.mjs";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
@@ -942,7 +942,8 @@ async function createSandbox(options) {
 		id: "local-dev",
 		email: options.email ?? "dev@localhost",
 		name: "Local Dev",
-		kind: "monk"
+		kind: "monk",
+		roles: options.roles ?? []
 	}));
 	app.all("/data/v1/ai/*", (c) => c.json({
 		error: "not_available_in_local_dev",

package/dist/{mcp-BVIU4j9N.mjs → mcp-DZdMNTWr.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-XOtqboS1.mjs";
+import { t as version } from "./package-Bvly8-rB.mjs";
 import { c as projectUrl, d as stagingUrl, p as tryResolveProject, r as siteConfig } from "./site-0i7wAJqg.mjs";
 import { a as apiRequest, d as noticeRenamesOnly, l as currentSlug, t as ApiError } from "./api-Bl6SG8Oq.mjs";
 import { t as liveDevServer } from "./dev-server-file-Dk9pk4AR.mjs";
@@ -171,7 +171,7 @@ function explainRefusal(status, body, project) {
 		case "agent_token_required":
 		case "agent_token_invalid": return "Canopy refused the sign-in for this agent session — run `canopy login` and restart the MCP server.";
 		case "agent_token_scope": return `The agent credential does not cover ${project} on this channel.`;
-		case "members_only": return `${project} is limited to its collaborators — ask the owner to add you.`;
+		case "members_only": return `${project} is limited to its members — ask the owner to add you.`;
 		case "project_not_found": return `There is no project ${project} on this site — check the slug and --profile.`;
 		case "project_paused": return `${project} is paused.`;
 		case "project_moved": return `${project} has moved${body.moved_to ? ` to ${body.moved_to}` : ""}.`;

package/dist/{package-XOtqboS1.mjs → package-Bvly8-rB.mjs}

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

package/dist/roles-BDZaN3vi.mjs

@@ -0,0 +1,2 @@
+import { i as membersCommand, o as rolesCommand } from "./roles-UM0Iiws6.mjs";
+export { membersCommand, rolesCommand };