wawesome 0.14.1 → 0.14.3

package/README.md

@@ -312,27 +312,38 @@ stderr, so a redirect catches the secret and not one character besides:
 npx wawesome credentials mint ci-pipeline > secret.txt
 ```
 
-A credential carries `deploy`, reaches every App in the workspace, and expires in ninety days unless
-you say otherwise:
+A capability is one cell of a grid: a verb, `read` or `write`, and the resource it acts on. A
+credential carries the words a deploy needs, reaches every App in the workspace, and expires in
+ninety days unless you say otherwise:
 
 ```bash
-# reads and runs what somebody else shipped, restricted to one App, never expires
-npx wawesome credentials mint agent -c read,logs:read,invoke -a prod --expires never
+# reads what ran and fires a run of what somebody else shipped, on one App, never expires
+npx wawesome credentials mint runner -c read:apps,read:functions,read:invocations,write:runs -a prod --expires never
 
-# ships code and attaches the domain the project declares
-npx wawesome credentials mint ci -c deploy,domains:attach -a prod
+# ships code into an App it may create, and attaches the domain the project declares
+npx wawesome credentials mint ci -c write:apps,write:functions,write:env,read:tenant,write:domains -a prod
 ```
 
 | Flag                 | Meaning                                                                       |
 |:---------------------|:------------------------------------------------------------------------------|
-| `-c, --capability`   | `deploy`, `read`, `logs:read`, `invoke`, `domains:attach`, or any mix. Repeatable or comma-separated. Default `deploy` |
+| `-c, --capability`   | A `{read\|write}:{resource}` word — `read:apps`, `write:functions`, `write:env`, `write:runs` and the rest. Repeatable or comma-separated. Default: `write:apps`, `write:functions`, `write:env`, `read:domains`, `read:tenant` |
+| `--preset`           | The words one job needs, by the job's name: `viewer`, `deployer`, `member`. [Which credential for which job](#which-credential-for-which-job) is what each one grants. Not with `-c` |
 | `-a, --app`          | Restrict to these Apps, by slug. Repeatable. Default: every App in the workspace |
 | `--expires`          | Days, or `never`. Default: 90                                                   |
 
+The resources are `tenant`, `apps`, `functions`, `env`, `domains`, `invocations`, `runs`,
+`schedules`, `previews` and `egress`. A write reaches the read of the same resource, so
+`write:functions` carries `read:functions` and there is no reason to name both. The command prints
+the words the credential ended up with.
+
+Some things are a person's alone, whatever a credential carries: renaming the workspace, detaching a
+domain, widening the egress allowlist, billing, and this workspace's own credentials and members.
+Those are not words to mint — a credential asking for one is told a person has to be at the keyboard.
+
 An App named in a restriction does not have to exist yet. A pipeline whose first deploy creates the
-App it was minted for is the ordinary case. A restriction bounds what a credential can disturb, not
-what it can read. A Function deployed into one App still reads the whole workspace's environment at
-runtime.
+App it was minted for is the ordinary case. A restriction bounds what a credential reads as well as
+what it disturbs, and `write:functions` is the hole in it: a Function deployed into an App the
+credential does reach still reads the whole workspace's environment at runtime.
 
 ### List them
 
@@ -468,19 +479,22 @@ concluding the platform cannot do it.
 |:---------------------------|:------------------------------------------------------------------------|:--------------|
 | `list_templates`           | The template catalogue, with what each one is for                       | nothing       |
 | `get_template`             | One template's files, environment contract and outbound providers        | nothing       |
-| `list_apps`                | The Apps in the workspace, with the slug each is addressed by            | `deploy`      |
-| `list_functions`           | The Functions in one App, and what their live version carries            | `read`        |
-| `list_versions`            | A Function's Versions, and which one is live                             | `read`        |
-| `get_usage`                | The Tenant's usage and headroom                                          | `read`        |
-| `list_invocations`         | Recent Invocations of a Function, failures included                      | `logs:read`   |
-| `get_invocation`           | One Invocation by id                                                     | `logs:read`   |
-| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `logs:read`   |
-| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `logs:read`, `read` |
-| `deploy_function`          | Deploys code and the static files it carries                             | `deploy`      |
-| `deploy_status`            | How a deploy went, by the handle it answered with                        | `deploy`      |
-| `rollback_function`        | Puts a Version the Function already has back on its public address       | `deploy`      |
-| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `deploy`      |
-| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `invoke`      |
+| `list_apps`                | The Apps the credential reaches, with the slug each is addressed by      | `read:apps`   |
+| `list_functions`           | The Functions in one App, and what their live version carries            | `read:functions` |
+| `list_versions`            | A Function's Versions, and which one is live                             | `read:functions` |
+| `get_usage`                | The Tenant's usage and headroom                                          | `read:tenant` |
+| `list_invocations`         | Recent Invocations of a Function, failures included                      | `read:invocations` |
+| `get_invocation`           | One Invocation by id                                                     | `read:invocations` |
+| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `read:invocations` |
+| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `read:invocations`, `read:functions` |
+| `deploy_function`          | Deploys code and the static files it carries                             | `write:functions` |
+| `deploy_status`            | How a deploy went, by the handle it answered with                        | `read:functions` |
+| `rollback_function`        | Puts a Version the Function already has back on its public address       | `write:functions` |
+| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `write:env`   |
+| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `write:runs`  |
+
+A word that writes reaches the read of the same thing, so `write:functions` needs no `read:functions`
+beside it, and the presets below are named in exactly these words.
 
 A deploy is two calls. The first says which of your files the platform does not already hold, by
 content hash; your agent uploads those bytes to `PUT /v1/assets/{content_hash}` with the same
@@ -499,42 +513,48 @@ is all the platform permits, and an agent taking it would end yours.
 ### Which credential for which job
 
 A credential carries the words its job needs and stops there. They are the same words
-[Deploy credentials](#mint-one) mints with.
+[Deploy credentials](#mint-one) mints with, and `--preset` fills them in for you: it expands into the
+words below before the request is built, and the command prints the words the credential ended up
+with. A preset and `-c` together are refused rather than merged, since both name the same thing. The
+preset is the name of the job; the words are the grant, and they are what travels.
+
+A preset is a workspace role, and the ones offered here are the roles carrying nothing only a person
+can hold. The name a job is minted under and the standing a member is given are one thing, rather
+than two lists somebody has to keep level.
 
-**Read and investigate, without the ability to ship.** The agent reads Functions, Versions,
-Invocations and log bodies, diagnoses a failure, checks usage, and browses templates. Every tool that
-ships code or runs it refuses:
+**Read and investigate, without the ability to ship** — `viewer`, which is every `read:` word the
+platform has. The agent enumerates your Apps, reads Functions, Versions, Invocations and log bodies,
+diagnoses a failure, checks usage, and browses templates. Every tool that ships code or runs it
+refuses:
 
 ```bash
-npx wawesome credentials mint investigator -c read,logs:read -a prod
+npx wawesome credentials mint reader --preset viewer -a prod
 ```
 
-One thing to know before you hand it over: `list_apps` sits behind `deploy`, the same word the HTTP
-route behind it asks for, so an investigation credential cannot enumerate your Apps. Name the App in
-the task and every other read works.
-
-**Read, investigate and run.** The same, plus `invoke_function`, so the agent can exercise a Function
-and read what it did. It still cannot deploy, roll back, or set a variable:
+**Ship and read back** — `deployer`, which is every read plus `write:apps`, `write:functions`,
+`write:env` and `write:runs`. Deploy, run, diagnose, roll back, set a key. Every tool in the table:
 
 ```bash
-npx wawesome credentials mint runner -c read,logs:read,invoke -a prod
+npx wawesome credentials mint ci --preset deployer -a prod
 ```
 
-**The whole loop.** Deploy, run, diagnose, roll back, set a key. Every tool in the table:
+**The whole workspace** — `member`, which is the deployer's words plus `write:schedules` and
+`write:previews`, for an agent that pauses a schedule or cuts a preview as well:
 
 ```bash
-npx wawesome credentials mint agent -c deploy,read,logs:read,invoke -a prod
+npx wawesome credentials mint agent --preset member -a prod
 ```
 
-Add `domains:attach` where the project declares a custom domain the deploy should claim. Nothing
-gives an agent billing, plan changes, credential management or your workspace's slug: those are
-closed to every credential, whatever it carries.
+Add `write:domains` where the project declares a custom domain the deploy should claim. Nothing gives
+an agent billing, a plan change, credential management or your workspace's slug: those are closed to
+every credential, whatever it carries.
 
 Keep `-a` on all three. A credential restricted to one App is refused on every tool that names
 another, which is what stops an agent working on one client's project from touching another's.
-`get_invocation` and `read_invocation_logs` take an Invocation id rather than an App, and neither is
-held to the restriction yet, so an agent already holding an id can read that Invocation's telemetry
-and log body whichever App it belongs to.
+`get_invocation` and `read_invocation_logs` take an Invocation id rather than an App, and an id
+belonging to an App the credential cannot reach is answered as an id naming nothing. `list_apps`
+answers a set rather than one App, so it is narrowed instead of refused: the credential is listed the
+Apps it reaches and told nothing about the rest.
 
 ### When a tool refuses
 
@@ -542,10 +562,18 @@ A refusal is the tool's answer, not a protocol error, and it carries the same `r
 prints:
 
 - `credential-missing-capability`. The credential does not carry a word this tool needs. The refusal
-  names it in `missing_capability`, which is the word to mint a credential with.
+  names the first in `missing_capability` and every one of them in `missing_capabilities`, which are
+  the words to mint a credential with. This one answers `403` rather than `200`, with a
+  `WWW-Authenticate: Bearer error="insufficient_scope"` challenge naming the same words and where
+  this endpoint's OAuth metadata is — a connector installed through consent reads it and asks its
+  human to widen the grant rather than to install again.
 - `app-outside-credential-scope`. The credential is restricted to named Apps and this is not one of
   them. A wider capability changes nothing here.
 
+A `401` is the credential itself: revoked, expired, or one this platform never issued. Nothing else
+answers one — a workspace that cannot deploy for a lapsed plan or a restriction is refused under its
+own reason, and re-installing the connector would not fix either.
+
 A quota refusal carries its numbers under `allowance` beside the prose, so your agent reports
 "3 of 3 App slots" rather than handing you a sentence to read.
 
@@ -731,9 +759,9 @@ npx wawesome domains
 ```
 
 It prints the domain, where it got to, when the platform last checked, and the records to add. It
-changes nothing, and a deploy credential carrying `deploy` can run it, so a pipeline reads the same
-thing you do. The TXT record is minted a moment after the name is claimed, and an attach that outran
-it prints a row saying so rather than dropping the record from the list. That row is what this
+changes nothing, and a deploy credential carrying `read:domains` can run it, so a pipeline reads the
+same thing you do. The TXT record is minted a moment after the name is claimed, and an attach that
+outran it prints a row saying so rather than dropping the record from the list. That row is what this
 command fills in, and it is where the deploy sends you: deploying again would change nothing, and a
 deploy that changes nothing is refused.
 

package/dist/index.mjs

@@ -883,7 +883,7 @@ async function buildJs(entryInput, options) {
 * that has to name this version — `--version`, the dependency a scaffolded
 * project pins — reads it here, so a release bumps one file.
 */
-const CLI_VERSION = "0.14.1";
+const CLI_VERSION = "0.14.3";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1685,7 +1685,7 @@ async function detachDomainCommand(hostname, options = {}) {
 * The one place a Tenant can ask. The records used to exist only in the output
 * of a deploy that changed something, so a deploy that outran the vendor left
 * nothing to run but a second deploy, which is refused for changing nothing
-* (#617). Open to a deploy credential carrying `deploy`, since a pipeline asks
+* (#617). Open to a deploy credential carrying `read:domains`, since a pipeline asks
 * this too.
 */
 async function showDomainCommand(options = {}) {
@@ -4667,6 +4667,74 @@ async function workspaceCommand(action, target, options) {
 	process.exit(1);
 }
 //#endregion
+//#region ../shared/mint-surface.generated.ts
+const MINT_PRESETS = [
+	{
+		name: "viewer",
+		job: "Read and investigate",
+		capabilities: [
+			"read:tenant",
+			"read:apps",
+			"read:functions",
+			"read:env",
+			"read:domains",
+			"read:invocations",
+			"read:runs",
+			"read:schedules",
+			"read:previews",
+			"read:egress"
+		],
+		summary: "Reads the workspace, Apps, Functions, environment variables, domains, invocations, runs, schedules, previews and the egress allowlist. It writes nothing."
+	},
+	{
+		name: "deployer",
+		job: "Ship and read back",
+		capabilities: [
+			"read:tenant",
+			"read:apps",
+			"read:functions",
+			"read:env",
+			"read:domains",
+			"read:invocations",
+			"read:runs",
+			"read:schedules",
+			"read:previews",
+			"read:egress",
+			"write:apps",
+			"write:functions",
+			"write:env",
+			"write:runs"
+		],
+		summary: "Reads the workspace, Apps, Functions, environment variables, domains, invocations, runs, schedules, previews and the egress allowlist, and can create Apps, deploy Functions, set environment variables and run Functions. It does not attach domains, pause and resume schedules or create previews."
+	},
+	{
+		name: "member",
+		job: "Build in the workspace",
+		capabilities: [
+			"read:tenant",
+			"read:apps",
+			"read:functions",
+			"read:env",
+			"read:domains",
+			"read:invocations",
+			"read:runs",
+			"read:schedules",
+			"read:previews",
+			"read:egress",
+			"write:apps",
+			"write:functions",
+			"write:env",
+			"write:runs",
+			"write:schedules",
+			"write:previews"
+		],
+		summary: "Reads the workspace, Apps, Functions, environment variables, domains, invocations, runs, schedules, previews and the egress allowlist, and can create Apps, deploy Functions, set environment variables, run Functions, pause and resume schedules and create previews. It does not attach domains."
+	}
+];
+function mintPreset(name) {
+	return MINT_PRESETS.find((preset) => preset.name === name);
+}
+//#endregion
 //#region src/deploy-credentials.ts
 const SECRET_SHOWN_ONCE = "Copy it now. This is the only time it will be shown. If you lose it, revoke this credential and mint another.";
 const REGENERATED_SECRET_SHOWN_ONCE = "Copy it now. This is the only time it will be shown. If you lose it, regenerate this credential again.";
@@ -4689,6 +4757,54 @@ function asList(raw) {
 	const words = (Array.isArray(raw) ? raw : [raw]).flatMap((word) => String(word).split(",")).map((word) => word.trim()).filter((word) => word.length > 0);
 	return words.length > 0 ? words : void 0;
 }
+/** What the help block is written to fit. A narrower terminal wraps it again;
+* a wider one leaves the words where they are put. */
+const HELP_WIDTH = 88;
+function wordsUnder(words, gutter) {
+	const lines = [];
+	let line = "";
+	words.forEach((word, i) => {
+		const piece = i < words.length - 1 ? `${word},` : word;
+		const joined = line ? `${line} ${piece}` : piece;
+		if (line && gutter.length + joined.length > HELP_WIDTH) {
+			lines.push(gutter + line);
+			line = piece;
+		} else line = joined;
+	});
+	return line ? [...lines, gutter + line] : lines;
+}
+/**
+* Every preset with the job on one line and the words it grants under it,
+* wherever one is offered or refused.
+*
+* The words are printed rather than stood for: a name on its own would be a
+* label an owner has to trust, free to drift from the grant it makes. They are
+* under the name rather than beside it because a grid word names one resource
+* and one verb, so a job takes ten of them or more.
+*/
+function presetsOffered(indent = "  ", pad = 12) {
+	return MINT_PRESETS.flatMap((preset) => [`${indent}${preset.name.padEnd(pad)}${preset.job}`, ...wordsUnder(preset.capabilities, `${indent}${" ".repeat(pad)}`)]);
+}
+/** The `--preset` flag as `--help` states it: the job each one is for, the
+* words being too many to fit on a flag's line and printed by the command's
+* own help. */
+const PRESET_FLAG_HELP = `Grant the words a job needs: ${MINT_PRESETS.map((preset) => `${preset.name} (${preset.job.toLowerCase()})`).join(", ")}. 'wawesome credentials --help' prints what each one grants. Not with --capability`;
+/**
+* The words to mint with: the ones named, or the ones a preset names.
+*
+* A preset expands here rather than travelling as a name, so what the command
+* sends and prints is the vocabulary itself: a label the platform never sees
+* would be free to drift from the words it stands for.
+*/
+function capabilitiesAsked(options) {
+	const named = asList(options.capability);
+	const preset = options.preset?.trim();
+	if (!preset) return named;
+	if (named) fail(`--preset ${preset} and --capability ${named.join(",")} both name what this credential carries.`, "Name one of them. A preset is a fill, so pass its words to --capability if you mean to edit them:", ...presetsOffered());
+	const found = mintPreset(preset);
+	if (!found) fail(`'${preset}' is not a preset. The ones offered are:`, ...presetsOffered());
+	return [...found.capabilities];
+}
 function parseExpiry(raw) {
 	if (raw === void 0) return void 0;
 	const asked = String(raw).trim().toLowerCase();
@@ -4786,10 +4902,10 @@ async function deleteCredential(creds, credentialId) {
 * and not one character besides.
 */
 async function mintCredentialCommand(name, options) {
-	if (!name || !name.trim()) fail("No name given. Usage: wawesome credentials mint <name> [--capability deploy] [--app <app>] [--expires 90|never]", "The name is what tells the CI one from the agent one a year from now.");
+	if (!name || !name.trim()) fail("No name given. Usage: wawesome credentials mint <name> [--capability write:functions] [--app <app>] [--expires 90|never]", "The name is what tells the CI one from the agent one a year from now.");
+	const capabilities = capabilitiesAsked(options);
 	const creds = requireCredentials$1();
 	const payload = { name: name.trim() };
-	const capabilities = asList(options.capability);
 	if (capabilities) payload.capabilities = capabilities;
 	const apps = asList(options.app);
 	if (apps) payload.apps = apps;
@@ -5516,19 +5632,23 @@ cli.command("credentials [action] [target]", "Mint, list, regenerate, revoke and
     revoke <name-or-prefix>         Revoke one, immediately and for good
     delete <name-or-prefix>         Forget a revoked or expired one, freeing its name
 
+  Presets (--preset), each the words one job needs, a write carrying its read:
+${presetsOffered("    ").join("\n")}
+
   Examples:
     wawesome credentials
     wawesome credentials mint ci-pipeline
-    wawesome credentials mint agent -c read,logs:read,invoke --expires never
-    wawesome credentials mint prod-deploy -c deploy -a prod --expires 30
-    wawesome credentials mint ci -c deploy,domains:attach -a prod
+    wawesome credentials mint viewer --preset viewer -a prod
+    wawesome credentials mint reader -c read:apps,read:functions,read:invocations -a prod
+    wawesome credentials mint ci --preset deployer --expires never
+    wawesome credentials mint ci -c write:apps,write:functions,write:env,read:tenant,write:domains -a prod
     wawesome credentials mint ci-pipeline > /tmp/secret
     wawesome credentials regenerate ci-pipeline
     wawesome credentials regenerate ci --expires never --yes
     wawesome credentials revoke ci-pipeline
     wawesome credentials revoke wawe_ab3k9x --yes
-    wawesome credentials delete ci-pipeline`).option("-c, --capability <capability>", "Capability to grant: deploy, read, logs:read, invoke, domains:attach (repeatable or comma-separated, default: deploy)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated, default: every App)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-y, --yes", "Skip the confirmation a regenerate, revoke or delete asks for").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => credentialsCommand(action, target, options));
-cli.command("credentials mint <name>", "Mint a deploy credential, printing its secret exactly once").option("-c, --capability <capability>", "Capability to grant: deploy, read, logs:read, invoke, domains:attach (repeatable or comma-separated)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-v, --verbose", "Enable verbose debug output").action((name, options) => mintCredentialCommand(name, options));
+    wawesome credentials delete ci-pipeline`).option("-c, --capability <capability>", "Capability to grant, as {read|write}:{resource}: read:apps, write:functions, write:env, write:runs and the rest (repeatable or comma-separated, default: what a deploy needs)").option("--preset <preset>", PRESET_FLAG_HELP).option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated, default: every App)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-y, --yes", "Skip the confirmation a regenerate, revoke or delete asks for").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => credentialsCommand(action, target, options));
+cli.command("credentials mint <name>", "Mint a deploy credential, printing its secret exactly once").option("-c, --capability <capability>", "Capability to grant, as {read|write}:{resource}: read:apps, write:functions, write:env, write:runs and the rest (repeatable or comma-separated; a write carries its read)").option("--preset <preset>", PRESET_FLAG_HELP).option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-v, --verbose", "Enable verbose debug output").action((name, options) => mintCredentialCommand(name, options));
 cli.command("credentials list", "List deploy credentials, never their secrets").alias("credentials ls").option("-v, --verbose", "Enable verbose debug output").action((options) => listCredentialsCommand(options));
 cli.command("credentials regenerate <name-or-prefix>", "Replace a deploy credential's secret, keeping its name, capabilities and Apps").option("--expires <days|never>", "Days until the regenerated credential expires, or 'never' (default: 90)").option("-y, --yes", "Regenerate without being asked to confirm").option("-v, --verbose", "Enable verbose debug output").action((target, options) => regenerateCredentialCommand(target, options));
 cli.command("credentials revoke <name-or-prefix>", "Revoke a deploy credential, immediately and for good").option("-y, --yes", "Revoke without being asked to confirm").option("-v, --verbose", "Enable verbose debug output").action((target, options) => revokeCredentialCommand(target, options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {