wawesome 0.14.3 → 0.15.0

package/README.md

@@ -477,11 +477,13 @@ concluding the platform cannot do it.
 
 | Tool                       | What it does                                                            | Needs         |
 |:---------------------------|:------------------------------------------------------------------------|:--------------|
+| `whoami`                   | The workspace, where it is administered, the words this credential carries, the Apps it reaches | nothing       |
 | `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 the credential reaches, with the slug each is addressed by      | `read:apps`   |
+| `list_apps`                | The Apps the credential reaches, each with its address and its dashboard page | `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_function_source`      | The code a Function is running, and the static files it carries          | `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` |
@@ -492,10 +494,16 @@ concluding the platform cannot do it.
 | `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`  |
+| `fetch_function`           | Fetches one path from a Function's live Version and answers what it served | `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.
 
+`whoami` is the one to call first. It answers the workspace, every word the credential carries and
+the Apps it reaches, and it asks for nothing — so your agent can say what it is able to do before it
+offers, rather than finding the edge by being refused in front of you. A member's session calling the
+endpoint gets the same answer for the role they hold.
+
 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
 credential and asks again, so a redeploy that changed only its code uploads nothing. The second
@@ -546,8 +554,10 @@ npx wawesome credentials mint agent --preset member -a prod
 ```
 
 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.
+an agent billing, a plan change, credential management or the ability to rename your workspace: those
+are closed to every credential, whatever it carries. Reading the workspace's name and address is not
+among them — `whoami` answers both to any credential, which is how the agent knows where what it
+deploys will appear.
 
 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.
@@ -602,6 +612,33 @@ URL, serving the code its callers already hold. The CLI remembers where this dir
 deployed and asks before that happens, naming both URLs. If you meant it, delete the old Function
 from the dashboard once nothing calls it.
 
+### A site with no handler
+
+Leave `entry` out, write no `src/index.ts`, and point `"assets"` at the directory your build wrote
+its pages into:
+
+```json
+{
+  "app": "my-app",
+  "function": "root",
+  "assets": "dist"
+}
+```
+
+That deploys the pages and no code at all, and the site is live at your App's address. Nothing in the
+file declares a kind: a project with a handler is one that has an entry point, and a project with
+both deploys them together and rolls them back together.
+
+An `entry` you did name and that is not there is a hard error, so a typo never quietly becomes a site
+with nothing running behind it. Every deploy says which of the two it landed.
+
+One thing the deploy will warn you about: everything beneath a Function's address reaches that
+Function, so a page your root Function carries at `about/index.html` is shadowed by a sibling Function
+named `about`. The deploy says so and names both addresses. It refuses nothing — the two Functions are
+versioned independently, and either one may deploy first.
+
+### Static files
+
 Add `"assets"` to deploy static files beside your code:
 
 ```json
@@ -623,28 +660,32 @@ Files are served straight from object storage; your Function is never invoked fo
 invocation is recorded. They answer on your App's own hostname and nowhere else. On the
 development path form (`/x/<tenant>/<app>/<function>/...`) the same address reaches your handler
 as it always has, because a file on an origin every workspace shares would be same-origin with
-all of them. Each carries `Cache-Control: public, max-age=31536000, immutable` and an
-`ETag`, so name your build output by content hash. A file's bytes must never change under a name a
-browser has already cached for a year. The content type comes from the extension against a fixed
-allowlist and is never sniffed; anything off it is served as a download.
+all of them. A file beneath `assets/` carries `Cache-Control: public, max-age=31536000, immutable`,
+so name your build output by content hash: its bytes must never change under a name a browser has
+already cached for a year. A file outside `assets/` keeps one name across every deploy, so it carries
+`max-age=300` instead — five minutes is inside the reach of a deploy and of a rollback, which a year
+is not. The content type comes from the extension against a fixed allowlist and is never sniffed;
+anything off it is served as a download.
 
 Two rules to know about:
 
 - **Everything beneath `assets/` is static**, whatever the deploy carries. A request there never
   reaches your handler, and an unknown path under it is a 404 rather than a route for you to answer.
-- **At most 100 files may sit outside `assets/`.** Those paths travel on the version record so a
-  request can be routed without a lookup per file. Put bulk output under `assets/`, where a file
-  costs nothing; `favicon.ico`, `robots.txt` and a `.well-known/` directory are what the rest is
-  for.
-
-**HTML is refused at deploy time.** Your Function renders its own markup, and a document served from
-your App's own origin is the sharpest same-origin risk a static file carries.
-
-**An SVG is served inert.** The rule behind the refusal above is that nothing you deploy as a file
-becomes a page on your App's own origin, and an SVG opened directly in a browser would become one.
-It runs script, and it renders whatever HTML a `<foreignObject>` holds. It is served rather than
-refused because making it inert costs the file nothing. An `<img src="logo.svg">` never ran that
-script and is never checked against the policy, so your drawings render as they always did. Every
+- **A file outside `assets/` answers at its own name**, however many of them a deploy carries.
+  `favicon.ico`, `robots.txt` and a `.well-known/` directory are what that is for; hashed build
+  output belongs under `assets/`.
+
+**A page is a file like any other.** An `index.html` your build wrote is deployed, hashed, retained
+and billed exactly as your other files are, and it is what a directory-style address resolves to: a
+path whose last segment carries no extension is served the `index.html` beneath it, so `/`, `/about`,
+`/about/` and `/blog/hello` each answer with a page. A page revalidates rather than being pinned for a
+year, wherever it sits, so deploying and refreshing is a loop that works.
+
+**An SVG is served inert.** Nothing you deploy as a resource should be able to run script on your
+App's own origin, and an SVG opened directly in a browser can: it runs script, and it renders whatever
+HTML a `<foreignObject>` holds. It is served rather than refused because making it inert costs the
+file nothing. An `<img src="logo.svg">` never ran that script and is never checked against the
+policy, so your drawings render as they always did. Every
 SVG and XML file carries `Content-Security-Policy: script-src 'none'; sandbox`, and only navigating
 straight to one loses anything. Such a file is sandboxed onto an origin of its own, so its links no
 longer navigate and a page embedding it through `<object>` or `<iframe>` cannot reach into its DOM.