wawesome 0.15.0 → 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                 |
@@ -493,6 +494,9 @@ 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`  |
 
@@ -553,7 +557,9 @@ 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
+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
@@ -812,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
@@ -837,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 |
 | --- | --- | --- |
@@ -845,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
 

package/dist/index.mjs

@@ -232,12 +232,11 @@ function deleteCredentials() {
 	}
 	return false;
 }
-/**
-* Read wawesome-function.json from the project directory.
-*/
+function getFunctionConfigPath(projectDir) {
+	return path.join(projectDir || process.cwd(), "wawesome-function.json");
+}
 function readFunctionConfig(projectDir) {
-	const dir = projectDir || process.cwd();
-	const configPath = path.join(dir, "wawesome-function.json");
+	const configPath = getFunctionConfigPath(projectDir);
 	if (!fs.existsSync(configPath)) return null;
 	try {
 		const raw = fs.readFileSync(configPath, "utf-8");
@@ -906,7 +905,7 @@ async function buildHandler(entryInput, config, 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.15.0";
+const CLI_VERSION = "0.16.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1579,7 +1578,7 @@ async function applyDeclaredDomain(creds, app, hostname) {
 			said: whatWentWrong(err)
 		};
 	}
-	const attached = held.find((domain) => isSameHostname(domain.hostname, hostname));
+	const attached = held.find((domain) => carries(domain, hostname));
 	if (attached) return {
 		kind: "unchanged",
 		domain: attached
@@ -1631,6 +1630,15 @@ function whatWentWrong(err) {
 	return errorText(err);
 }
 /**
+* Whether a claim answers at the declared name — at the leg it reads as, or at
+* the other half it carries. A file naming the `www` of an apex-led claim
+* declares a name the App already answers at, and re-attaching it every deploy
+* would report a change nothing made.
+*/
+function carries(domain, declared) {
+	return [domain.hostname, ...(domain.legs ?? []).filter((leg) => leg.claimed).map((leg) => leg.hostname)].some((name) => isSameHostname(name, declared));
+}
+/**
 * The comparison the platform makes: a name is held lowercase without its
 * trailing dot, so `shop.client.com.` in the file is the domain already
 * attached rather than a second one to ask for on every deploy.
@@ -1722,6 +1730,105 @@ async function detachDomainCommand(hostname, options = {}) {
 	}
 }
 /**
+* The project's configuration as a file to write rather than as settings to
+* read: the raw text, so what is written back keeps the shape of what was
+* committed, and a file that does not parse is refused rather than replaced.
+*/
+function projectConfig() {
+	const path = getFunctionConfigPath();
+	if (!fs.existsSync(path)) {
+		console.error("[wawesome] Error: No wawesome-function.json found in the current directory.");
+		console.error("[wawesome] Run this from the project that deploys the app.");
+		process.exit(1);
+	}
+	const text = fs.readFileSync(path, "utf-8");
+	try {
+		return {
+			path,
+			text,
+			parsed: JSON.parse(text)
+		};
+	} catch (err) {
+		console.error(`[wawesome] Error: wawesome-function.json is not valid JSON: ${errorText(err)}`);
+		console.error("[wawesome] Nothing was written. Fix the file and run this again.");
+		process.exit(1);
+	}
+}
+/**
+* The declared domain written back, in the indentation the file already uses so
+* the diff is the one line.
+*/
+function writeDeclaredDomain(config, hostname) {
+	const indent = /\n([ \t]+)"/.exec(config.text)?.[1] ?? "  ";
+	const written = JSON.stringify({
+		...config.parsed,
+		domain: hostname
+	}, null, indent);
+	fs.writeFileSync(config.path, config.text.endsWith("\n") ? `${written}\n` : written, "utf-8");
+}
+/**
+* Write the domain the App carries into wawesome-function.json.
+*
+* The fix named beside the drift a deploy reports (ADR-0034). The platform row
+* is what serves and the file is a desired state, so a name attached from the
+* dashboard or by an agent is a name this file has never heard of — and a
+* deploy will not write it, because a deploy never edits a tracked file.
+*
+* A file naming a different domain is two names in play and a person's
+* question: both are printed and nothing is written.
+*/
+async function adoptDomainCommand(hostname, options = {}) {
+	if (hostname?.trim()) {
+		console.error(`[wawesome] Error: 'wawesome domains adopt' takes no hostname, and '${hostname.trim()}' was given.`);
+		console.error("[wawesome] It writes the name the app already answers at, which it reads from the platform.");
+		process.exit(1);
+	}
+	const config = projectConfig();
+	const { creds, app } = credentialsAndApp(options);
+	const deploysTo = typeof config.parsed.app === "string" ? config.parsed.app.trim() : void 0;
+	if (deploysTo && deploysTo !== app) {
+		console.error(`[wawesome] Error: wawesome-function.json deploys to app '${deploysTo}', and --app names '${app}'.`);
+		console.error("[wawesome] Nothing was written: a name off another app does not belong in this file.");
+		process.exit(1);
+	}
+	let held;
+	try {
+		held = await listDomains(creds, app);
+	} catch (err) {
+		console.error(`[wawesome] Error: ${whatWentWrong(err)}`);
+		process.exit(1);
+	}
+	const attached = held.find((domain) => !domain.detaching);
+	if (!attached) {
+		console.log(`[wawesome] No domain is attached to app '${app}', so there is nothing to adopt.`);
+		console.log(held.length > 0 ? "[wawesome] The one it carried is being detached." : "[wawesome] Attach one from the dashboard, from an agent, or by declaring it here and deploying.");
+		return;
+	}
+	const declared = declaredDomain(config.parsed.domain);
+	if (declared && carries(attached, declared)) {
+		console.log(`[wawesome] wawesome-function.json already declares '${declared}'.`);
+		console.log(`[wawesome] App '${app}' answers at it, so nothing was written.`);
+		return;
+	}
+	if (declared) {
+		console.error(`[wawesome] Error: Two domains are in play on app '${app}'.`);
+		console.error(`[wawesome]   wawesome-function.json declares '${declared}'`);
+		console.error(`[wawesome]   the app answers at '${attached.hostname}'`);
+		console.error("[wawesome] Nothing was written. An App carries one domain, so which of the two");
+		console.error("[wawesome] it is is yours to settle: edit the line yourself, or take the attached");
+		console.error("[wawesome] one off with");
+		console.error(`[wawesome]   \x1b[36mwawesome domains detach ${attached.hostname}\x1b[0m`);
+		console.error("[wawesome] and deploy to attach the declared one.");
+		process.exit(1);
+	}
+	writeDeclaredDomain(config, attached.hostname);
+	console.log(`[wawesome] wawesome-function.json now declares '${attached.hostname}'.`);
+	const answersAt = claimedHostnames(attached);
+	if (answersAt.length > 1) console.log(`[wawesome] The app answers at both halves of the name: ${answersAt.join(", ")}.`);
+	console.log("[wawesome] Nothing about the domain changed: it was attached already, and the file");
+	console.log("[wawesome] now says so. Commit it, and every deploy from here agrees.");
+}
+/**
 * What this App answers at, read and printed.
 *
 * The one place a Tenant can ask. The records used to exist only in the output
@@ -1752,10 +1859,12 @@ async function showDomainCommand(options = {}) {
 async function domainsCommand(action, target, options = {}) {
 	const verb = (action || "").toLowerCase().trim();
 	if (verb === "detach") return detachDomainCommand(target, options);
+	if (verb === "adopt") return adoptDomainCommand(target, options);
 	if (!verb) return showDomainCommand(options);
 	console.error(`[wawesome] Error: Unknown command '${["domains", action].filter(Boolean).join(" ")}'.`);
-	console.error("[wawesome] Usage: wawesome domains [detach <hostname>]");
-	console.error("[wawesome] A domain is attached by declaring it in wawesome-function.json.");
+	console.error("[wawesome] Usage: wawesome domains [adopt | detach <hostname>]");
+	console.error("[wawesome] A domain is attached by declaring it in wawesome-function.json, from the");
+	console.error("[wawesome] dashboard, or by an agent.");
 	process.exit(1);
 }
 function domainsUrl(creds, app) {
@@ -1809,10 +1918,14 @@ function domainLines(outcome) {
 	if (outcome.kind === "undeclared") {
 		const { hostname, state } = outcome.domain;
 		const left = state.serving ? "it is still serving" : "nothing changed";
+		const answersAt = claimedHostnames(outcome.domain);
 		return [
 			"",
 			`  Domain:     \x1b[33m${hostname}: attached, and this project declares no domain\x1b[0m`,
-			...wrapped(`Nothing was detached and ${left}. A domain comes off an App when somebody names it, never because a line was deleted. Declare it again in wawesome-function.json, or take it off with`).map((line) => `${VALUE_COLUMN}${line}`),
+			...answersAt.length > 1 ? indented(`Both halves of the name are attached: ${answersAt.join(", ")}.`) : [],
+			...indented(`Nothing was detached and ${left}. A domain comes off an App when somebody names it, never because a line was deleted. To write it into wawesome-function.json, run`),
+			`${VALUE_COLUMN}  \x1b[36mwawesome domains adopt\x1b[0m`,
+			...indented("To take it off the App instead, run"),
 			`${VALUE_COLUMN}  \x1b[36mwawesome domains detach ${hostname}\x1b[0m`
 		];
 	}
@@ -1843,21 +1956,73 @@ function attachedDomainLines(domain, printedBy = "deploy") {
 		`${VALUE_COLUMN}Remove 'domain' from wawesome-function.json, or deploy again`,
 		`${VALUE_COLUMN}once it is gone to attach it afresh.`
 	];
+	const legs = domain.legs ?? [];
+	if (legs.length > 1) return pairLines(domain, legs, printedBy);
 	const lines = ["", `  Domain:     \x1b[36m${hostname}\x1b[0m: ${whereItGotTo(domain)}`];
 	if (last_checked_at) lines.push(`${VALUE_COLUMN}Last checked ${asUtc$1(last_checked_at)}.`);
 	if (state.serving) {
 		lines.push(`${VALUE_COLUMN}This app's own address answers too, so nothing pointed at it breaks.`);
 		return lines;
 	}
-	const nameWidth = Math.max(...records.map((record) => record.name.length));
-	const row = (type, name, value = "") => `      ${type.padEnd(5)}  ${name.padEnd(nameWidth)}  ${value}`.trimEnd();
 	lines.push("", "  DNS records to add at your registrar:");
-	if (certificate_record_pending) lines.push("", `    ${whatItIsFor("certificate")}:`, row("TXT", "not ready yet"));
-	for (const record of records) lines.push("", `    ${whatItIsFor(record.purpose)}:`, row(record.type, record.name, record.value));
+	lines.push(...recordLines(records, certificate_record_pending, "    "));
 	lines.push("", ...closingLines(certificate_record_pending, printedBy));
 	return lines;
 }
 /**
+* A claim carrying both halves of a name: where the claim got to, then each leg
+* with its own state and its own records.
+*
+* Every leg is named, the half nothing claimed included. Four records to add
+* rather than two is the cost of a name that answers at both halves, and a leg
+* left out of this block is a record nobody adds on the name a visitor typed.
+*/
+function pairLines(domain, legs, printedBy) {
+	const lines = ["", `  Domain:     \x1b[36m${domain.hostname}\x1b[0m: ${domain.state.serving ? "serving at both halves of the name" : "coming up, and each half of the name is below"}`];
+	if (domain.last_checked_at) lines.push(`${VALUE_COLUMN}Last checked ${asUtc$1(domain.last_checked_at)}.`);
+	lines.push("");
+	for (const leg of legs) {
+		lines.push(`${VALUE_COLUMN}${leg.hostname}: ${whereTheLegGotTo(leg)}`);
+		if (leg.unclaimed_reason) lines.push(...wrapped(leg.unclaimed_reason).map((line) => `${VALUE_COLUMN}  ${line}`));
+	}
+	const outstanding = legs.filter((leg) => leg.claimed && !leg.state.serving);
+	if (outstanding.length === 0) {
+		lines.push(`${VALUE_COLUMN}This app's own address answers too, so nothing pointed at it breaks.`);
+		return lines;
+	}
+	lines.push("", "  DNS records to add at your registrar:");
+	for (const leg of outstanding) {
+		lines.push("", `    ${leg.hostname}:`);
+		lines.push(...recordLines(leg.records ?? [], leg.certificate_record_pending, "      "));
+	}
+	const pending = outstanding.some((leg) => leg.certificate_record_pending);
+	lines.push("", ...closingLines(pending, printedBy));
+	return lines;
+}
+function whereTheLegGotTo(leg) {
+	return leg.claimed ? whereItGotTo(leg) : "not claimed";
+}
+/**
+* The records one leg is waiting on, each under what it is for.
+*
+* What each record is for goes above it rather than beside it. A DCV value is
+* 40-odd characters a person has to copy exactly, and a fourth column puts the
+* row past the width of the terminal it is being copied out of.
+*/
+function recordLines(records, certificateRecordPending, indent) {
+	const nameWidth = Math.max(0, ...records.map((record) => record.name.length));
+	const row = (type, name, value = "") => `${indent}  ${type.padEnd(5)}  ${name.padEnd(nameWidth)}  ${value}`.trimEnd();
+	const lines = [];
+	if (certificateRecordPending) lines.push("", `${indent}${whatItIsFor("certificate")}:`, row("TXT", "not ready yet"));
+	for (const record of records) lines.push("", `${indent}${whatItIsFor(record.purpose)}:`, row(record.type, record.name, record.value));
+	return lines;
+}
+/** Every hostname a claim answers at, for a block naming the claim in one line. */
+function claimedHostnames(domain) {
+	const claimed = (domain.legs ?? []).filter((leg) => leg.claimed).map((leg) => leg.hostname);
+	return claimed.length > 0 ? claimed : [domain.hostname];
+}
+/**
 * What is left to do, which is nothing.
 *
 * The pending case pointed at another deploy until #617: a deploy that changed
@@ -5767,7 +5932,8 @@ cli.command("env [action] [key] [value]", "Manage environment variables (set, li
 cli.command("env set <key> <value>", "Set or overwrite an environment variable on the current app").option("-s, --secret", "Flag variable as secret (write-only)").option("-v, --verbose", "Enable verbose debug output").action((key, value, options) => setEnvVar(key, value, options));
 cli.command("env list", "List environment variables for the current app").alias("env ls").option("-v, --verbose", "Enable verbose debug output").action((options) => listEnvVars(options));
 cli.command("env rm <key>", "Delete an environment variable from the current app").alias("env remove").alias("env delete").alias("env unset").option("-v, --verbose", "Enable verbose debug output").action((key, options) => removeEnvVar(key, options));
-cli.command("domains [action] [hostname]", "Show the custom domain on the current app, its state and its DNS records").usage("domains [action] [hostname]\n\nWith no action, prints the app's domain, where it got to, when the platform last checked, and the records to add.\n\nActions:\n  detach <hostname>   Stop serving the app at a domain you attached\n\nA domain is attached by declaring it in wawesome-function.json and deploying.").example("wawesome domains").example("wawesome domains detach shop.client.com").option("-a, --app <slug>", "App to act on (default: the app in wawesome-function.json)").action((action, hostname, options) => domainsCommand(action, hostname, options));
+cli.command("domains [action] [hostname]", "Show the custom domain on the current app, its state and its DNS records").usage("domains [action] [hostname]\n\nWith no action, prints the app's domain, every half of it, where each got to, when the platform last checked, and the records to add.\n\nActions:\n  adopt               Write the attached domain into wawesome-function.json\n  detach <hostname>   Stop serving the app at a domain you attached\n\nA domain is attached by declaring it in wawesome-function.json and deploying, from the dashboard, or by an agent.").example("wawesome domains").example("wawesome domains adopt").example("wawesome domains detach shop.client.com").option("-a, --app <slug>", "App to act on (default: the app in wawesome-function.json)").action((action, hostname, options) => domainsCommand(action, hostname, options));
+cli.command("domains adopt", "Write the domain the current app answers at into wawesome-function.json").option("-a, --app <slug>", "App to act on (default: the app in wawesome-function.json)").action((options) => adoptDomainCommand(void 0, options));
 cli.command("domains detach <hostname>", "Stop serving the current app at a domain you attached").option("-a, --app <slug>", "App to act on (default: the app in wawesome-function.json)").action((hostname, options) => detachDomainCommand(hostname, options));
 cli.command("login", "Authenticate with the wawesome.io platform").option("--api <url>", "API URL (default: https://api.wawesome.io)").option("--gateway <url>", "Alias for --api <url>").option("--dashboard <url>", "Dashboard URL (default: https://dashboard.wawesome.io)").option("--provider <name>", "OAuth provider (default: github)").option("--workspace <name>", "Name for the workspace, when signing up without a terminal to prompt").option("--accept-terms", "Accept the terms of service and privacy policy, when signing up without a terminal to prompt").option("-v, --verbose", "Enable verbose debug output").action((options) => login(options));
 cli.command("logout", "Clear stored authentication credentials").action(() => logout());

package/package.json

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