wawesome 0.16.0 → 0.17.0

package/README.md

@@ -478,9 +478,9 @@ 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       |
+| `whoami`                   | The workspace, where it is administered, the words this credential carries and which of them a tool here asks for, 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       |
+| `get_template`             | One template's source, environment contract and outbound providers; its tests and build configuration are named, and read on request | nothing       |
 | `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` |
@@ -493,6 +493,8 @@ concluding the platform cannot do it.
 | `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` |
+| `request_upload`           | Asks the person you are working with for files the conversation cannot produce, and answers a link to give them | `write:functions` |
+| `list_uploads`             | What the person sent against one upload session, ready to declare on the next deploy | `read: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` |
@@ -505,8 +507,11 @@ 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.
+offers, rather than finding the edge by being refused in front of you. Each word also says whether a
+tool here asks for it. Your credential can carry `write:schedules` with no schedule tool on this
+endpoint, and the mark is what stops an agent offering to schedule a job: a word with no tool behind
+it is done on the dashboard rather than being withheld from 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
@@ -681,6 +686,18 @@ Two rules to know about:
   `favicon.ico`, `robots.txt` and a `.well-known/` directory are what that is for; hashed build
   output belongs under `assets/`.
 
+**A version carries exactly the files its deploy declared.** Nothing is inherited from the version
+before it, so taking `"assets"` out of `wawesome-function.json` — or pointing it at a directory your
+build no longer writes to — is not an edit but every file on the site going at once. A deploy that
+would do that against a Function serving files today is refused, and tells you how many would go:
+
+```bash
+npx wawesome deploy --drop-assets
+```
+
+Removing *some* of the files is ordinary editing and needs nothing: only the wholesale drop is
+refused, because that is the shape of a mistake rather than of a decision.
+
 **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`,
@@ -790,10 +807,16 @@ Add `"domain"` and your App answers at a name you own, beside the address it alr
 }
 ```
 
-The deploy attaches it and prints two DNS records to add at your registrar. The TXT record proves you
-own the name, which is what issues the certificate. The CNAME points traffic here, and you add that
-one once the certificate is issued, so a site that is already live never spends a minute answering on
-a certificate that is not there yet.
+The deploy attaches it and prints three DNS records to add at your registrar. The TXT record proves
+you own the name. The `_acme-challenge` CNAME beside it issues the certificate and keeps renewing it
+for as long as it stays there, so nobody comes back to your registrar at renewal time — if an
+`_acme-challenge` TXT record is already at that name, delete it, because a TXT and this CNAME cannot
+both sit there. The last CNAME points traffic here, and you add that one once the certificate is
+issued, so a site that is already live never spends a minute answering on a certificate that is not
+there yet.
+
+Nothing you are asked to add ever changes. Copy a value into your registrar, come back an hour later,
+and it is the same value.
 
 Your deploy waits for neither. It attaches the domain, prints the records and finishes, and every
 later deploy states where the domain got to: not verified, ownership verified, certificate issued, or
@@ -807,10 +830,10 @@ 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 `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.
+same thing you do. Where the platform does not hold a record yet 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.
 
 A custom domain is granted from the Solo plan upwards, one per App. On a plan that grants none, the
 deploy prints the refusal and lands everything else it was doing.

package/dist/index.mjs

@@ -905,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.16.0";
+const CLI_VERSION = "0.17.0";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1873,10 +1873,9 @@ function domainsUrl(creds, app) {
 /**
 * Where a domain got to, said beside the name itself.
 *
-* Each state names the one record that is outstanding, because the two are
-* added a day apart: the TXT issues the certificate, and the CNAME is pointed
-* here afterwards so a site that is already live never answers on a
-* certificate that is not there yet.
+* Each state names the one record that is outstanding. The two that prove the
+* name go in first and the traffic CNAME a day later, so a site that is already
+* live never answers on a certificate that is not there yet.
 *
 * Read off the records too, never the states alone: naming a record the payload
 * does not carry left a reader holding the CNAME alone (#610).
@@ -1885,22 +1884,26 @@ function whereItGotTo(domain) {
 	const { state } = domain;
 	if (state.serving) return "serving";
 	if (state.certificate_active) return "certificate issued, so point the CNAME here to cut over";
-	if (state.ownership_verified) return "ownership verified, and the certificate is being issued";
-	if (domain.certificate_record_pending) return "not verified yet, and the TXT record is not ready";
-	return "not verified yet, so add the TXT record below";
+	if (state.ownership_verified) return domain.certificate_record_pending ? "name verified, and the certificate record is not ready" : "name verified, so add the certificate CNAME below";
+	if (domain.ownership_record_pending) return "not verified yet, and the TXT record is not ready";
+	return "not verified yet, so add the records below";
 }
 /**
 * What a record is for, and when to add it.
 *
-* The order is stated rather than implied. The TXT proves control and issues
-* the certificate; the CNAME is pointed here afterwards, so a name already
-* serving a live site never answers on a certificate that is not there yet.
-* That is why the platform validates before the cutover, and a reader holding
-* the CNAME alone could read the old caption as a label rather than as an
-* instruction to wait (#617).
+* The order is stated rather than implied. The TXT proves the name is theirs
+* and the CNAME beside it issues the certificate; the traffic record is pointed
+* here afterwards, so a name already serving a live site never answers on a
+* certificate that is not there yet. That is why the platform validates before
+* the cutover, and a reader holding the traffic record alone could read the old
+* caption as a label rather than as an instruction to wait (#617).
 */
 function whatItIsFor(purpose) {
-	return purpose === "certificate" ? "Add this first. It proves you own the name and issues the certificate" : "Add this once the certificate is active. It points traffic here";
+	switch (purpose) {
+		case "ownership": return "Add this first. It proves you own the name";
+		case "certificate": return "Add this first too. It issues the certificate and keeps it renewed";
+		default: return "Add this once the certificate is active. It points traffic here";
+	}
 }
 /** What the dashboard's empty state shows. Kept the same by hand, not by anything. */
 const DOMAIN_CONFIG_LINE = "\"domain\": \"shop.client.com\"";
@@ -1948,7 +1951,7 @@ function domainLines(outcome) {
 * the whole of #610 and #617.
 */
 function attachedDomainLines(domain, printedBy = "deploy") {
-	const { hostname, records, state, last_checked_at, detaching, certificate_record_pending } = domain;
+	const { hostname, records, state, last_checked_at, detaching, ownership_record_pending, certificate_record_pending } = domain;
 	if (detaching) return [
 		"",
 		`  Domain:     \x1b[33m${hostname}: being detached\x1b[0m`,
@@ -1964,9 +1967,13 @@ function attachedDomainLines(domain, printedBy = "deploy") {
 		lines.push(`${VALUE_COLUMN}This app's own address answers too, so nothing pointed at it breaks.`);
 		return lines;
 	}
+	const pending = Boolean(ownership_record_pending || certificate_record_pending);
 	lines.push("", "  DNS records to add at your registrar:");
-	lines.push(...recordLines(records, certificate_record_pending, "    "));
-	lines.push("", ...closingLines(certificate_record_pending, printedBy));
+	lines.push(...recordLines(records, {
+		ownership_record_pending,
+		certificate_record_pending
+	}, "    "));
+	lines.push("", ...closingLines(pending, printedBy));
 	return lines;
 }
 /**
@@ -1993,9 +2000,9 @@ function pairLines(domain, legs, printedBy) {
 	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, "      "));
+		lines.push(...recordLines(leg.records ?? [], leg, "      "));
 	}
-	const pending = outstanding.some((leg) => leg.certificate_record_pending);
+	const pending = outstanding.some((leg) => leg.ownership_record_pending || leg.certificate_record_pending);
 	lines.push("", ...closingLines(pending, printedBy));
 	return lines;
 }
@@ -2009,12 +2016,16 @@ function whereTheLegGotTo(leg) {
 * 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) {
+function recordLines(records, pending, 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));
+	if (pending.ownership_record_pending) lines.push("", `${indent}${whatItIsFor("ownership")}:`, row("TXT", "not ready yet"));
+	if (pending.certificate_record_pending) lines.push("", `${indent}${whatItIsFor("certificate")}:`, row("CNAME", "not ready yet"));
+	for (const record of records) {
+		lines.push("", `${indent}${whatItIsFor(record.purpose)}:`, row(record.type, record.name, record.value));
+		if (record.purpose === "certificate") lines.push(`${indent}  Delete any _acme-challenge TXT record already at that name.`);
+	}
 	return lines;
 }
 /** Every hostname a claim answers at, for a block naming the claim in one line. */
@@ -2029,9 +2040,9 @@ function claimedHostnames(domain) {
 * nothing is refused, so the one piece of advice the reader was given was the
 * one they could not take.
 */
-function closingLines(certificateRecordPending, printedBy) {
-	if (!certificateRecordPending) return indented(`${printedBy === "deploy" ? "The deploy is finished. " : ""}This domain comes up on its own once the records resolve.`);
-	const asking = "The TXT record is not ready yet. The platform asks the certificate vendor again on its own.";
+function closingLines(aRecordIsPending, printedBy) {
+	if (!aRecordIsPending) return indented(`${printedBy === "deploy" ? "The deploy is finished. " : ""}This domain comes up on its own once the records resolve.`);
+	const asking = "A record is not ready yet. The platform asks the certificate vendor again on its own.";
 	if (printedBy === "domains") return indented(`${asking} Run this again in a minute.`);
 	return [...indented(`${asking} The deploy is finished either way. To read the record when it lands, run`), `${VALUE_COLUMN}  \x1b[36mwawesome domains\x1b[0m`];
 }
@@ -2968,7 +2979,8 @@ function shadowingLines(shadowed) {
 function declaredFields(declared) {
 	return {
 		...declared.visibility ? { visibility: declared.visibility } : {},
-		...declared.confirmPublish ? { confirm_publish: true } : {}
+		...declared.confirmPublish ? { confirm_publish: true } : {},
+		...declared.confirmAssetDrop ? { confirm_asset_drop: true } : {}
 	};
 }
 /**
@@ -2982,6 +2994,15 @@ function declaredVisibility(value) {
 	console.error("[wawesome] It must be \"public\" or \"private\".");
 	process.exit(1);
 }
+function reportAssetDropRefusal(message) {
+	console.error(`\n[wawesome] \x1b[31mError: ${message}\x1b[0m`);
+	console.error("[wawesome] Nothing was deployed. A version carries exactly the files its");
+	console.error("[wawesome] deploy declared, so this one would take every file the live");
+	console.error("[wawesome] version serves off the site at once.");
+	console.error("[wawesome] Point \x1B[36m\"assets\"\x1B[0m in wawesome-function.json at the directory");
+	console.error("[wawesome] holding them, or re-run with \x1B[36mwawesome deploy --drop-assets\x1B[0m to");
+	console.error("[wawesome] remove them.\n");
+}
 function reportPublishRefusal(message) {
 	console.error(`\n[wawesome] \x1b[31mError: ${message}\x1b[0m`);
 	console.error("[wawesome] Nothing was deployed. This Function is private, so its address");
@@ -3009,7 +3030,8 @@ async function deploy(entryInput, options) {
 	const { app, function: funcName } = config;
 	const declared = {
 		visibility: declaredVisibility(config.visibility),
-		confirmPublish: Boolean(options.publish)
+		confirmPublish: Boolean(options.publish),
+		confirmAssetDrop: Boolean(options.dropAssets)
 	};
 	const domainName = declaredDomain(config.domain);
 	if (isVerbose) {
@@ -3100,6 +3122,10 @@ async function deploy(entryInput, options) {
 				reportPublishRefusal(refusal.message);
 				process.exit(1);
 			}
+			if (refusal.reason === "asset-drop-needs-confirmation") {
+				reportAssetDropRefusal(refusal.message);
+				process.exit(1);
+			}
 			console.error(`\n[wawesome] \x1b[31mError: ${refusal.message}\x1b[0m`);
 			const advice = planLimitAdvice(refusal.reason);
 			if (advice) console.error(`[wawesome] ${advice}\n`);
@@ -5920,7 +5946,7 @@ async function credentialsCommand(action, target, options) {
 //#region src/index.ts
 const cli = cac("wawesome");
 cli.command("build [entry]", "Bundle a serverless function to an optimized JS file").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").action((entry, options) => buildJs(entry, options));
-cli.command("deploy [entry]", "Build, upload, and promote a serverless function").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").option("--skip-build", "Skip the build step, deploy an already-built bundle").option("--publish", "Confirm putting a private function back on its public address").action((entry, options) => deploy(entry, options));
+cli.command("deploy [entry]", "Build, upload, and promote a serverless function").option("-o, --out <path>", "Output JS bundle path", { default: "dist/index.js" }).option("-v, --verbose", "Enable verbose debug output").option("--skip-build", "Skip the build step, deploy an already-built bundle").option("--publish", "Confirm putting a private function back on its public address").option("--drop-assets", "Confirm a deploy carrying no static files where the live version serves some").action((entry, options) => deploy(entry, options));
 cli.command("version [action] [target]", "Manage versions (e.g. 'version list', 'version switch [version]')").option("-e, --env <environment>", "Target environment (default: production)").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => {
 	if (!action || action === "list" || action === "ls") return listVersions(options);
 	if (action === "switch" || action === "use" || action === "select") return switchVersion(target, options);

package/package.json

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