wawesome 0.14.3 → 0.16.0

package/README.md

@@ -118,6 +118,7 @@ npx wawesome deploy
 | `npx wawesome env set <key> <val>`      | Set an environment variable (add `--secret` for write-only)         |
 | `npx wawesome env rm <key>`             | Delete an environment variable                                      |
 | `npx wawesome domains`                  | Show the app's domain, its state, and the DNS records to add        |
+| `npx wawesome domains adopt`            | Write the domain the app answers at into wawesome-function.json     |
 | `npx wawesome domains detach <host>`    | Stop serving the app at a domain you attached                       |
 | `npx wawesome credentials`              | List deploy credentials: name, prefix, capabilities, Apps, last use |
 | `npx wawesome credentials mint <name>`  | Mint a deploy credential and print its secret, once                 |
@@ -477,11 +478,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` |
@@ -491,11 +494,20 @@ concluding the platform cannot do it.
 | `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`   |
+| `attach_domain`            | Attaches a domain to an App and answers the DNS records that make it work | `write:domains` |
+| `cancel_domain_claim`      | Gives up a domain claim nobody has proved control of, freeing the App's place | `write:domains` |
+| `check_domain`             | Where the domain attached to an App got to, asked at the certificate vendor | `read:domains` |
 | `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
@@ -545,9 +557,13 @@ npx wawesome credentials mint ci --preset deployer -a prod
 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.
+Add `write:domains` where the project declares a custom domain the deploy should claim, or where an
+agent attaches one for somebody who has no terminal — it also gives back a claim nobody has proved
+control of yet, and never takes a live name off an App. Nothing gives
+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 +618,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 +666,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.
@@ -771,13 +818,27 @@ deploy prints the refusal and lands everything else it was doing.
 The address derived from your workspace slug keeps serving after you attach a domain. Both names
 answer, so webhooks and integrations already pointed at the old one keep working.
 
-An apex domain, `client.com` with no `www`, attaches like any other name. Whether a CNAME may sit at
-your zone root is your DNS provider's rule, and where it cannot, attach `www.client.com` and configure
-the redirect at the provider.
+An apex domain, `client.com` with no `www`, claims `www.client.com` with it, and attaching the `www`
+claims the apex. Both halves are one domain against your App's one place, and both are printed with
+their own state and their own records, because a visitor typing either one should reach your site.
+Where your DNS provider cannot hold a CNAME at your zone root, that half is reported as not claimed
+with the reason, and attaching the same name again picks it up once your DNS can carry it.
+
+The file is not the only door. A domain can also be attached from the dashboard or by an agent, and
+then your App answers at a name `wawesome-function.json` has never heard of. A deploy says so and
+edits nothing — what was committed is what ships — so the file is written by a command of your own:
+
+```bash
+npx wawesome domains adopt
+```
+
+It writes the attached hostname into `wawesome-function.json` and changes nothing about the domain.
+Where the file already declares a *different* name, it refuses and prints both: an App carries one
+domain, and which of the two names it should be is yours to settle rather than a file to overwrite.
 
 Deleting the line detaches nothing. Detaching takes a live site dark, which is not something a
 deploy should infer from a deleted line. So the deploy reports the domain it found and left serving,
-and names the one command that takes it off:
+names the command that writes it into the file, and names the one command that takes it off:
 
 ```bash
 npx wawesome domains detach shop.client.com
@@ -796,7 +857,7 @@ handler sees it, and off your response before the caller does. So **do not name
 own on that prefix**. It is dropped silently rather than rejected, and you will not get an error
 telling you why it vanished.
 
-Four headers arrive or leave on it, and the stripping is what makes them worth trusting:
+Five headers arrive or leave on it, and the stripping is what makes them worth trusting:
 
 | Header | Direction | What it means |
 | --- | --- | --- |
@@ -804,6 +865,7 @@ Four headers arrive or leave on it, and the stripping is what makes them worth t
 | `x-wawesome-trigger` | inbound | How this run started: `caller` when someone called your address, `schedule` when fired by a Schedule. A caller cannot forge it in production (stripped inbound). On the local development surface, pass `x-wawesome-trigger: schedule` to exercise a background run by hand with the collapsed budget. |
 | `x-wawesome-invocation-id` | outbound | The id of this run, the key to fetch its logs with `npx wawesome logs --invocation <id>`. |
 | `x-wawesome-error` | outbound | Present only when the platform failed, never when your Function did. Its *absence* means the status on the wire is yours, up to the moment your response is committed and no further. |
+| `x-wawesome-document` | outbound | Set it to the path of a document your own deploy carried (`index.html`) and the platform streams that file in place of the body you returned. Your status and your other headers stand; the content type and the length are the file's. Naming a path your deploy does not carry is a `500`, and your logs say which path you named. |
 
 ### Testing against the guest's JavaScript surface