x43.fast 0.0.0-stage → 0.1.0

package/dist/project.js

@@ -0,0 +1,75 @@
+// A capsule project on disk: its source files, its x43.json, and what `init`/`pull` write.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { isAppName } from "./schemas.js";
+/** A message for the person: printed as is, without a stack trace. */
+export class Fail extends Error {
+}
+/** cli/ (from src/ and from dist/ alike): templates, types and AGENTS.md live there. */
+export const CLI = fileURLToPath(new URL("..", import.meta.url));
+export const SIDES = ["server", "client", "shared"];
+/** The vendored type project (scripts/vendor-types.mjs): the runtime it came from and the checker's options. */
+export const TYPES = join(CLI, "types");
+export const runtime = z
+    .object({ runtime: z.string(), commit: z.string(), compilerOptions: z.record(z.string(), z.unknown()), paths: z.record(z.string(), z.string()) })
+    .parse(JSON.parse(readFileSync(join(TYPES, "runtime.json"), "utf8")));
+/** A tsconfig with the hosted checker's options, resolving `cloudapps/*` and `preact*` from `types`. */
+export function tsconfig(types, include) {
+    const paths = Object.fromEntries(Object.entries(runtime.paths).map(([specifier, file]) => [specifier, [`${types}/${file}`]]));
+    return { compilerOptions: { ...runtime.compilerOptions, paths }, include: [...include, `${types}/dom.d.ts`] };
+}
+/** Every file under `root` as `{ "a/b.ts": text }` (posix paths relative to `root`, sorted); {} if it's missing. */
+function readTree(root) {
+    if (!existsSync(root))
+        return {};
+    const paths = readdirSync(root, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(root, join(entry.parentPath, entry.name)).split(sep).join("/"));
+    return Object.fromEntries(paths.sort().map((path) => [path, readFileSync(join(root, path), "utf8")]));
+}
+/** The capsule's source files in `dir`: every .ts/.tsx under server/, client/ and shared/. */
+export function collectFiles(dir) {
+    return Object.fromEntries(SIDES.flatMap((side) => Object.entries(readTree(join(dir, side))).map(([path, text]) => [`${side}/${path}`, text]))
+        .filter(([path]) => /\.tsx?$/.test(path)));
+}
+const Project = z.object({ name: z.string().refine(isAppName, "not a valid app name") });
+/** The app name saved in `dir`/x43.json, if there is one. */
+export function savedName(dir) {
+    const path = join(dir, "x43.json");
+    if (!existsSync(path))
+        return undefined;
+    const project = Project.safeParse(JSON.parse(readFileSync(path, "utf8")));
+    if (!project.success)
+        throw new Fail(`${path}: expected { "name": "<app name>" }`);
+    return project.data.name;
+}
+const projectJson = (name) => `${JSON.stringify({ name }, null, 2)}\n`;
+export const saveName = (dir, name) => writeFileSync(join(dir, "x43.json"), projectJson(name));
+export const TEMPLATES = ["todo", "blank"];
+export const template = (name) => readTree(join(CLI, "templates", name));
+/**
+ * Writes a project: the app's files plus what editors and agents need (tsconfig.json, the vendored
+ * types/, AGENTS.md, CLAUDE.md), and x43.json if a name is given. Refuses to overwrite any file.
+ */
+export function writeProject(dir, app, name) {
+    const files = {
+        ...app,
+        "tsconfig.json": `${JSON.stringify(tsconfig("./types", [...SIDES]), null, 2)}\n`,
+        ...Object.fromEntries(Object.entries(readTree(TYPES)).map(([path, text]) => [`types/${path}`, text])),
+        "AGENTS.md": readFileSync(join(CLI, "AGENTS.md"), "utf8"),
+        "CLAUDE.md": "@AGENTS.md\n",
+        ...(name ? { "x43.json": projectJson(name) } : {}),
+    };
+    const existing = Object.keys(files).filter((path) => existsSync(join(dir, path)));
+    if (existing.length) {
+        const more = existing.length > 3 ? ` and ${existing.length - 3} more` : "";
+        throw new Fail(`Won't overwrite existing files in ${dir}: ${existing.slice(0, 3).join(", ")}${more}.`);
+    }
+    for (const [path, text] of Object.entries(files)) {
+        mkdirSync(dirname(join(dir, path)), { recursive: true });
+        writeFileSync(join(dir, path), text);
+    }
+    return Object.keys(files);
+}

package/dist/schemas.js

@@ -0,0 +1,104 @@
+// The Host's publish API shapes and the app name rule, copied from mvp/src/shared/api.ts (cli/ is
+// standalone). Keep them in sync with that file.
+import { z } from "zod";
+/** An app name: one hostname label of at most 32 characters. */
+const NAME = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+// Names that would look like the site's own hosts (`api-app.x43.fast`, …).
+const RESERVED = new Set(["api", "www", "mail", "admin"]);
+export const isAppName = (name) => NAME.test(name) && !RESERVED.has(name);
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+// The largest multiple of 36 that fits in a byte: bytes at or past it are dropped, so `% 36` favours no letter.
+const UNBIASED = 256 - (256 % ALPHABET.length);
+/** A fresh app name: 6 random characters from [a-z0-9] (lowercase: DNS is case-insensitive). */
+export function randomName(length = 6) {
+    let name = "";
+    while (name.length < length) {
+        for (const byte of crypto.getRandomValues(new Uint8Array(length))) {
+            if (byte < UNBIASED && name.length < length)
+                name += ALPHABET[byte % ALPHABET.length];
+        }
+    }
+    return name;
+}
+/** An app's source files: `{ [path]: source }`. */
+export const Files = z.record(z.string(), z.string());
+/** The body of a publish, and the answer to `GET /api/apps/:name/files`. */
+export const FilesBody = z.object({ files: Files });
+export const Published = z.discriminatedUnion("ok", [
+    // `warning`: the Host couldn't prerender `/`, so it is served empty until its script runs.
+    z.object({ ok: z.literal(true), hash: z.string(), url: z.string(), warning: z.string().optional() }),
+    z.object({ ok: z.literal(false), errors: z.array(z.string()) }),
+]);
+export const Called = z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), value: z.unknown() }),
+    z.object({ ok: z.literal(false), error: z.string() }),
+]);
+/** `POST /api/apps/:name/sandbox`: each call's result; the writes were rolled back. */
+export const Sandboxed = z.object({ results: z.array(Called) });
+/** `GET /api/apps/:name/errors`: the live version's runtime errors, most recently seen first. */
+export const Errors = z.object({
+    errors: z.array(z.object({
+        source: z.enum(["server", "browser"]),
+        where: z.string(),
+        name: z.string(),
+        message: z.string(),
+        stack: z.string(),
+        count: z.number(),
+        firstSeen: z.number(),
+        lastSeen: z.number(),
+    })),
+});
+/**
+ * `runtime`: the runtime build the live version was built with (null: nothing published). `expiresAt`: when
+ * its plan deletes it (ms; on an idle expiry, if it stays idle; null: never or nothing published).
+ */
+export const AppStatus = z.object({ name: z.string(), url: z.string(), hash: z.string().nullable(), runtime: z.string().nullable(), expiresAt: z.number().nullable().default(null) });
+/** `GET /api/version`: the Host's runtime build. */
+export const HostVersion = z.object({ runtime: z.string() });
+/** Any refusal outside those results (401, 403, 404, 405, 413, a malformed body). */
+export const Refused = z.object({ ok: z.literal(false), error: z.string() });
+/** An account; `plan` is guest, free, pro or admin. */
+export const User = z.object({ id: z.string(), login: z.string(), name: z.string().nullable(), plan: z.string() });
+/** `GET /api/me`: the account, its plan's limits (the fields shown here) and its apps. */
+export const Me = z.object({
+    user: User,
+    limits: z.object({
+        label: z.string(),
+        apps: z.number().nullable(),
+        visitors: z.number(),
+        bytes: z.number(),
+        versions: z.number(),
+        cronMinutes: z.number().nullable(),
+        expiry: z.object({ after: z.enum(["created", "idle"]), days: z.number() }).nullable(),
+        webBuilder: z.boolean(),
+        // Pro: outbound fetch, secrets, HTTP endpoints (absent from Hosts before them).
+        fetch: z.boolean().default(false),
+        // Pro: uploads and custom domains (absent from Hosts before them).
+        uploadBytes: z.number().default(0),
+        domains: z.number().default(0),
+    }),
+    apps: z.array(z.object({ name: z.string(), url: z.string(), title: z.string().nullable(), version: z.number().nullable(), created: z.number() })),
+});
+/** `POST /api/guest` (no token): a guest account (no sign-in), its token, and the claim code and link that keep its apps. */
+export const Guest = z.object({ token: z.string(), claim: z.string(), claimUrl: z.string(), user: User });
+/** `POST /api/claim`: the guest's apps now yours, and those over your plan's app limit (still deleted on the guest's schedule). */
+export const Claimed = z.object({ claimed: z.array(z.string()), left: z.array(z.string()) });
+/** `POST /api/device`: open `url` (it shows `code`), then poll `POST /api/device/token` with `device`. */
+export const DeviceStart = z.object({ code: z.string(), device: z.string(), url: z.string(), interval: z.number(), expiresIn: z.number() });
+/** Still waiting, or approved: the token, handed out once. */
+export const DevicePoll = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("pending") }),
+    z.object({ status: z.literal("approved"), token: z.string(), user: User }),
+]);
+export const Ok = z.object({ ok: z.literal(true) });
+/** `GET /api/apps/:name/secrets`: names only, never values. */
+export const Secrets = z.object({ secrets: z.array(z.object({ name: z.string(), updated: z.number() })) });
+/** A custom domain (`/api/domains`): served once `active`; `records`: what to add at the domain's DNS provider. */
+export const Domain = z.object({
+    hostname: z.string(),
+    app: z.string(),
+    status: z.enum(["pending", "active"]),
+    records: z.array(z.object({ type: z.enum(["CNAME", "TXT"]), name: z.string(), value: z.string() })),
+    errors: z.array(z.string()),
+});
+export const Domains = z.object({ domains: z.array(Domain) });

package/dist/x43.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+// x43: create, check and deploy Cloud apps (capsules) through the Host's publish API.
+import { spawn } from "node:child_process";
+import { relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_API, findLogin, loadLogin, loginOrGuest, parseCalls, removeLogin, request, saveLogin, trimApi } from "./api.js";
+import { importErrors, typeErrors } from "./check.js";
+import { collectFiles, Fail, runtime, savedName, saveName, template, TEMPLATES, writeProject } from "./project.js";
+import { AppStatus, Called, Claimed, DevicePoll, DeviceStart, Domain, Domains, Errors, FilesBody, HostVersion, isAppName, Me, Ok, Published, randomName, Sandboxed, Secrets } from "./schemas.js";
+const HELP = `x43: build live web apps on Cloud apps (${DEFAULT_API.replace(/\/api$/, "")})
+
+  x43 init [dir] [--template todo|blank]   write a new capsule project (default: todo, in .)
+  x43 check                                type-check the capsule here and apply the Host's import rules
+  x43 deploy [--name <name>] [--no-check]  check, then publish; the first deploy picks a name (x43.json).
+                                           Not logged in: deploys as a guest (apps deleted after 7 days)
+  x43 login [--api <url>]                  sign in: open the link it prints, approve the code, done
+  x43 login --token [--api <url>]          save a token instead (read from stdin or a hidden prompt)
+  x43 claim                                after \`x43 login\`: move this machine's guest apps to your account
+  x43 whoami                               your account, plan and its limits
+  x43 apps                                 your apps
+  x43 logout                               revoke this machine's token and forget it
+  x43 status [--name <name>]               name, URL, live version and when it is deleted
+  x43 call <query|mutation> <handler> [json args] [… more calls] [--commit] [--name <name>]
+                                           test handlers on the live app (as the user "builder-agent") in a
+                                           sandbox: later calls see earlier writes, then all are rolled back;
+                                           --commit saves the writes (only for seed data you were asked for)
+  x43 errors [--name <name>]               the live version's runtime errors (server and browser), newest first
+  x43 secret set <NAME> [--name <name>]    set a secret (value from stdin or a hidden prompt; Pro): ctx.secrets.NAME
+  x43 secret list | rm <NAME>              the app's secrets' names (never values); delete one
+  x43 pull <name> [dir]                    download an app's live source into a new project
+  x43 open [--name <name>]                 print (and open) the app's URL
+  x43 domain add <hostname> [--name <name>]  serve the app on your own domain (Pro); prints the DNS records to add
+  x43 domain status                        your domains: pending or active, and their DNS records
+  x43 domain remove <hostname>             stop serving an app on that domain
+
+Env: X43_API, X43_TOKEN override the saved login. Agents: see AGENTS.md.`;
+const { values, positionals } = (() => {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                api: { type: "string" },
+                token: { type: "boolean" },
+                template: { type: "string" },
+                name: { type: "string" },
+                "no-check": { type: "boolean" },
+                commit: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch (e) {
+        console.error(`x43: ${e instanceof Error ? e.message : String(e)}\n\n${HELP}`);
+        process.exit(2);
+    }
+})();
+const [command, ...args] = positionals;
+const here = process.cwd();
+const commands = {
+    async login() {
+        const api = trimApi(values.api ?? process.env.X43_API ?? DEFAULT_API);
+        const token = values.token ? await readSecret(`Token for ${api}: `) : await deviceLogin(api);
+        if (!token)
+            throw new Fail("No token given.");
+        const { runtime: host } = await request({ api, token }, "/version", HostVersion);
+        const { user, limits } = await request({ api, token }, "/me", Me);
+        // A guest's claim outlives its token, for `x43 claim`.
+        const before = findLogin().login;
+        const unclaimed = before?.api === api ? ("guest" in before ? before.guest : before.unclaimed) : undefined;
+        console.log(`Logged in to ${api} as ${user.login} (${limits.label}; saved in ${saveLogin({ api, token, unclaimed })}).`);
+        if (unclaimed)
+            console.log("Run `x43 claim` to keep your guest apps on this account.");
+        warnRuntime(host);
+    },
+    async whoami() {
+        const login = loadLogin();
+        const { user, limits: l, apps } = await request(login, "/me", Me);
+        const expiry = !l.expiry ? "never expire" : l.expiry.after === "idle" ? `are deleted after ${l.expiry.days} idle days` : `are deleted ${l.expiry.days} days after their first deploy`;
+        console.log(`${user.login}${user.name ? ` (${user.name})` : ""} on ${login.api}`);
+        console.log(`plan     ${l.label}: ${apps.length}${l.apps === null ? "" : ` of ${l.apps}`} apps; per app ${l.visitors} visitors at once, ${Math.round(l.bytes / 1_048_576)} MiB of data, ${l.versions} versions kept, ${l.cronMinutes === null ? "no crons" : `crons every ${l.cronMinutes} min at most`}${l.fetch ? "; fetch, secrets and HTTP endpoints" : ""}${l.uploadBytes ? `; ${l.uploadBytes / 1024 ** 3} GiB of uploads` : ""}${l.domains ? `; ${l.domains} custom domain${l.domains > 1 ? "s" : ""}` : ""}; apps ${expiry}`);
+        if ("guest" in login)
+            console.log("You're a guest (no login). To keep your apps: `x43 login`, then `x43 claim`.");
+    },
+    async apps() {
+        const { apps, limits } = await request(loadLogin(), "/me", Me);
+        if (!apps.length)
+            return console.log("No apps yet: `x43 init` then `x43 deploy`.");
+        // Only an expiry from creation is known here; `x43 status` has the exact one.
+        const deleted = (created) => (limits.expiry?.after === "created" ? `  deleted ${expiry(created + limits.expiry.days * DAY_MS)}` : "");
+        for (const a of apps)
+            console.log(`${a.name.padEnd(12)} ${(a.version === null ? "-" : `v${a.version}`).padEnd(5)} ${a.url}${a.title ? `  ${a.title}` : ""}${deleted(a.created)}`);
+    },
+    async logout() {
+        const login = loadLogin();
+        // The internal token can't be revoked (the Host says so); the file goes either way.
+        const revoked = await request(login, "/logout", Ok, {}).then(() => true, () => false);
+        const path = removeLogin();
+        console.log(`${revoked ? "Revoked the token" : "Couldn't revoke the token"}${path ? ` and removed ${path}` : ""}.`);
+        if ("guest" in login)
+            console.log("That was a guest login: its apps can't be claimed any more and are deleted on schedule.");
+    },
+    async init() {
+        const dir = resolve(args[0] ?? ".");
+        const name = values.template ?? "todo";
+        const chosen = TEMPLATES.find((t) => t === name);
+        if (!chosen)
+            throw new Fail(`Unknown template "${name}" (choose ${TEMPLATES.join(" or ")}).`);
+        const written = writeProject(dir, template(chosen));
+        const cd = relative(here, dir);
+        console.log(`Created a ${chosen} capsule in ${cd || "."} (${written.length} files). Next:${cd ? ` cd ${cd} &&` : ""} x43 check && x43 deploy`);
+    },
+    async check() {
+        const files = capsule();
+        const errors = await checkErrors(files);
+        if (errors.length)
+            failWith(errors, `check found ${errors.length} error${errors.length > 1 ? "s" : ""}.`);
+        console.log(`check: ok (${Object.keys(files).length} files)`);
+    },
+    async deploy() {
+        const files = capsule();
+        if (!values["no-check"]) {
+            const errors = await checkErrors(files);
+            if (errors.length)
+                failWith(errors, `check found ${errors.length} error${errors.length > 1 ? "s" : ""}; fix them (or deploy with --no-check).`);
+        }
+        const login = await loginOrGuest(); // no login yet: a guest account, saved like one
+        const saved = savedName(here);
+        const name = saved || values.name ? appName() : await freshName(login);
+        const result = await request(login, `/apps/${name}/publish`, Published, { files });
+        if (!result.ok)
+            failWith(result.errors, "The Host refused the files.");
+        if (!saved)
+            saveName(here, name);
+        console.log(`Deployed ${name} (${result.hash.slice(0, 12)}): ${result.url}`);
+        if (result.warning)
+            console.error(`warning: ${result.warning}`);
+        if ("guest" in login) {
+            const { expiresAt } = await appStatus(login, name);
+            console.log(`\nThis is a guest app (no login): it is deleted ${expiresAt === null ? "after 7 days" : expiry(expiresAt)}.`);
+            console.log(`To keep it: \`x43 login\`, then \`x43 claim\` (or open ${login.guest.url} signed in).`);
+        }
+    },
+    async status() {
+        const status = await appStatus(loadLogin(), appName());
+        console.log(`name     ${status.name}\nurl      ${status.url}`);
+        console.log(status.hash ? `version  ${status.hash.slice(0, 12)} (runtime ${status.runtime})` : "version  not published");
+        if (status.hash)
+            console.log(`expires  ${status.expiresAt === null ? "never" : expiry(status.expiresAt)}`);
+        if (status.runtime)
+            warnRuntime(status.runtime);
+    },
+    async claim() {
+        const login = loadLogin();
+        if ("guest" in login)
+            throw new Fail("You're a guest: `x43 login` first, then `x43 claim` moves your guest apps to that account.");
+        if (!login.unclaimed)
+            throw new Fail("No guest apps to claim on this machine (a guest's `x43 deploy` saves its claim).");
+        const { claimed, left } = await request(login, "/claim", Claimed, { code: login.unclaimed.code });
+        saveLogin({ api: login.api, token: login.token });
+        console.log(claimed.length ? `Claimed ${claimed.join(", ")}: now yours, on your plan's limits.` : "No apps were moved.");
+        if (left.length)
+            console.log(`Not claimed (over your plan's app limit; deleted on the guest schedule): ${left.join(", ")}.`);
+    },
+    async call() {
+        const calls = parseCalls(args);
+        const login = loadLogin();
+        const app = appName();
+        const results = values.commit ? [] : (await request(login, `/apps/${app}/sandbox`, Sandboxed, { calls })).results;
+        for (const c of values.commit ? calls : [])
+            results.push(await request(login, `/apps/${app}/call`, Called, c)); // in order
+        for (const [i, result] of results.entries()) {
+            const { kind, name } = calls[i];
+            if (calls.length > 1)
+                console.log(`# ${kind} ${name}`);
+            console.log(result.ok ? JSON.stringify(result.value ?? null, null, 2) : `failed: ${result.error}`);
+        }
+        console.error(values.commit ? "(committed: visitors see these writes)" : "(sandbox: rolled back, nothing was saved; --commit saves)");
+        const failed = results.filter((r) => !r.ok).length;
+        if (failed)
+            throw new Fail(`${failed} of ${calls.length} call${calls.length > 1 ? "s" : ""} failed.`);
+    },
+    async errors() {
+        const { errors } = await request(loadLogin(), `/apps/${appName()}/errors`, Errors);
+        if (!errors.length)
+            return console.log("No runtime errors in the live version.");
+        for (const e of errors) {
+            const ago = Math.max(0, Math.round((Date.now() - e.lastSeen) / 60_000));
+            console.log(`${e.source} · ${e.where} · ${e.name}: ${e.message} (×${e.count}, last ${ago ? `${ago} min ago` : "just now"})`);
+            if (e.stack)
+                console.log(`    at ${e.stack}`);
+        }
+    },
+    async secret() {
+        const [action, secret] = args;
+        const login = loadLogin();
+        const base = `/apps/${appName()}/secrets`;
+        if (action === "list" && !secret) {
+            const { secrets } = await request(login, base, Secrets);
+            if (!secrets.length)
+                return console.log("No secrets. Set one with `x43 secret set NAME`.");
+            for (const s of secrets)
+                console.log(s.name);
+            return;
+        }
+        if (!secret || (action !== "set" && action !== "rm"))
+            throw new Fail("Usage: x43 secret set <NAME> | x43 secret list | x43 secret rm <NAME>");
+        const path = `${base}/${encodeURIComponent(secret)}`;
+        if (action === "rm") {
+            await request(login, path, Ok, undefined, "DELETE");
+            return console.log(`Deleted ${secret}.`);
+        }
+        const value = await readSecret(`Value for ${secret} (hidden): `);
+        if (!value)
+            throw new Fail("No value given.");
+        await request(login, path, Ok, { value }, "PUT");
+        console.log(`Set ${secret}: mutations, crons and HTTP handlers read it as ctx.secrets.${secret}.`);
+    },
+    async pull() {
+        const [name, dir = name] = args;
+        if (!name || !isAppName(name))
+            throw new Fail("Usage: x43 pull <name> [dir]");
+        const { files } = await request(loadLogin(), `/apps/${name}/files`, FilesBody);
+        if (!Object.keys(files).length)
+            throw new Fail(`${name} has nothing published.`);
+        writeProject(resolve(dir), files, name);
+        console.log(`Pulled ${name} into ${dir} (${Object.keys(files).join(", ")}).`);
+    },
+    async open() {
+        const { url, hash } = await appStatus(loadLogin(), appName());
+        console.log(url);
+        if (!hash)
+            console.error("(nothing published yet)");
+        openUrl(url);
+    },
+    async domain() {
+        const [action, hostname] = args;
+        const login = loadLogin();
+        if (action === "add" && hostname) {
+            const domain = await request(login, "/domains", Domain, { hostname, app: appName() });
+            console.log(`Added ${domain.hostname} for ${domain.app}. Add these DNS records at your domain's DNS provider:`);
+            printDomain(domain);
+            return console.log("Then run `x43 domain status` until it says active (usually a few minutes after the records are in).");
+        }
+        if (action === "status") {
+            const { domains } = await request(login, "/domains", Domains);
+            if (!domains.length)
+                return console.log("No custom domains: `x43 domain add <hostname>` (Pro).");
+            for (const d of domains) {
+                console.log(`${d.hostname} → ${d.app}: ${d.status === "active" ? `active, https://${d.hostname}` : "pending"}`);
+                if (d.status === "pending")
+                    printDomain(d);
+            }
+            return;
+        }
+        if (action === "remove" && hostname) {
+            await request(login, `/domains/${encodeURIComponent(hostname)}`, Ok, undefined, "DELETE");
+            return console.log(`Removed ${hostname}; you can delete its DNS records.`);
+        }
+        throw new Fail("Usage: x43 domain add <hostname> [--name <name>] | x43 domain status | x43 domain remove <hostname>");
+    },
+};
+function printDomain(domain) {
+    for (const r of domain.records)
+        console.log(`  ${r.type.padEnd(6)} ${r.name}  ${r.value}`);
+    for (const e of domain.errors)
+        console.log(`  (Cloudflare: ${e})`);
+}
+/** The capsule's files in the current directory; fails if there is none. */
+function capsule() {
+    const files = collectFiles(here);
+    if (!Object.keys(files).length)
+        throw new Fail(`No capsule in ${here} (no server/ or client/ files). Run \`x43 init\` first.`);
+    return files;
+}
+const checkErrors = async (files) => [...(await importErrors(files)), ...typeErrors(here)];
+function failWith(errors, summary) {
+    for (const error of errors)
+        console.log(error);
+    throw new Fail(summary);
+}
+/** --name, else x43.json's name. */
+function appName() {
+    const name = values.name ?? savedName(here);
+    if (!name)
+        throw new Fail("No app here: run `x43 deploy` first, or pass --name <name>.");
+    if (!isAppName(name))
+        throw new Fail(`"${name}" isn't a valid app name (a-z, 0-9 and dashes, at most 32).`);
+    return name;
+}
+const appStatus = (login, name) => request(login, `/apps/${name}`, AppStatus);
+/** A random name with nothing published under it (the API takes any name, so don't replace someone's app). */
+async function freshName(login) {
+    for (let i = 0; i < 5; i++) {
+        const name = randomName();
+        if ((await appStatus(login, name)).hash === null)
+            return name;
+    }
+    throw new Fail("Couldn't find a free app name; pass --name <name>.");
+}
+const DAY_MS = 86_400_000;
+/** A deletion time: `on 2026-11-20 (in 7 days)`. */
+const expiry = (at) => `on ${new Date(at).toISOString().slice(0, 10)} (in ${Math.max(0, Math.ceil((at - Date.now()) / DAY_MS))} days)`;
+function warnRuntime(host) {
+    if (host === runtime.runtime)
+        return;
+    console.error(`warning: the Host's runtime is ${host}, this CLI's types are from ${runtime.runtime}; \`x43 check\` may disagree with the Host until the CLI is updated.`);
+}
+/** The device login: the person approves the printed code in the browser, signed in; returns the new token. */
+async function deviceLogin(api) {
+    const start = await request({ api }, "/device", DeviceStart, {});
+    console.log(`Open ${start.url}\nand approve the code ${start.code} (it expires in ${Math.round(start.expiresIn / 60)} minutes).`);
+    openUrl(start.url);
+    const deadline = Date.now() + start.expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, start.interval * 1000));
+        const polled = await request({ api }, "/device/token", DevicePoll, { device: start.device });
+        if (polled.status === "approved")
+            return polled.token;
+    }
+    throw new Fail("The code expired before it was approved; run `x43 login` again.");
+}
+/** Opens a URL in the browser when a person is at the terminal. */
+function openUrl(url) {
+    if (!process.stdout.isTTY)
+        return;
+    const [cmd, ...rest] = process.platform === "darwin" ? ["open"] : process.platform === "win32" ? ["cmd", "/c", "start", '""'] : ["xdg-open"];
+    spawn(cmd, [...rest, url], { detached: true, stdio: "ignore" }).on("error", () => { }).unref();
+}
+/** A token or secret: all of stdin when piped, else a prompt that doesn't echo. */
+async function readSecret(prompt) {
+    const { stdin } = process;
+    let text = "";
+    if (!stdin.isTTY) {
+        for await (const chunk of stdin)
+            text += String(chunk);
+        return text.trim();
+    }
+    process.stderr.write(prompt);
+    stdin.setRawMode(true);
+    try {
+        for await (const chunk of stdin) {
+            for (const char of String(chunk)) {
+                if (char === "\r" || char === "\n")
+                    return text.trim();
+                if (char === "\u0003")
+                    throw new Fail("Cancelled.");
+                text = char === "\u007f" || char === "\b" ? text.slice(0, -1) : text + char;
+            }
+        }
+        return text.trim();
+    }
+    finally {
+        stdin.setRawMode(false);
+        process.stderr.write("\n");
+    }
+}
+const isCommand = (name) => name !== undefined && Object.hasOwn(commands, name);
+if (values.help || !command) {
+    console.log(HELP);
+}
+else if (!isCommand(command)) {
+    console.error(`x43: unknown command "${command}"\n\n${HELP}`);
+    process.exitCode = 2;
+}
+else {
+    try {
+        await commands[command]();
+    }
+    catch (e) {
+        // A Fail is meant for the person; anything else is a bug, still shown without a stack.
+        console.error(`x43: ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 1;
+    }
+}

package/llms.txt

@@ -0,0 +1,27 @@
+# x43
+
+> x43 (Cloud apps) hosts small live web apps ("capsules"): a TypeScript server (schema, queries, mutations and crons over a per-app database) and a Preact + Tailwind client with a tiny router, deployed with the `x43` CLI to https://<name>-app.x43.fast.
+
+The full guide for coding agents is AGENTS.md (copied into every project by `x43 init`).
+
+## Guide
+
+- [The loop](AGENTS.md#the-loop): init → write files → `x43 check` until clean → `x43 deploy` (no account needed: a guest app, deleted after 7 days unless the person runs `x43 login` then `x43 claim`) → `x43 call` (sandboxed) and `x43 errors` to test → share the URL
+- [App layout](AGENTS.md#app-layout): server/index.ts, client/index.tsx, shared/*.ts
+- [Imports](AGENTS.md#imports): what each directory may import
+- [Server](AGENTS.md#server-cloudappsserver): schema and validators (nested data), indexes, ctx.db queries (range, order, paginate), ctx.auth, crons, meta (title, description, icon, fonts)
+- [Client](AGENTS.md#client-cloudappsclient): createClient, useQuery, useMutation, usePaginatedQuery, Router/Route/Link, useTitle, Preact, Tailwind
+- [Landing pages](AGENTS.md#landing-pages): sections, meta and fonts, a private waitlist form, no invented claims, what `/` shows before its script runs
+- [Example](AGENTS.md#example-a-complete-app): a complete app
+- [Pro: other sites, secrets, webhooks](AGENTS.md#pro-other-sites-secrets-webhooks): fetch allowlist, ctx.secrets and x43 secret, HTTP endpoints at /_http/…
+- [Testing with x43 call and x43 errors](AGENTS.md#testing-with-x43-call-and-x43-errors)
+- [What the platform can't do](AGENTS.md#what-the-platform-cant-do)
+- [Limits](AGENTS.md#limits): per plan (Guest, Free, Pro); `x43 whoami` prints yours
+- [Common mistakes](AGENTS.md#common-mistakes)
+- [CLI reference](AGENTS.md#cli-reference)
+
+## Optional
+
+- [README.md](README.md): installing the CLI, deploying as a guest, login (`x43 login`: approve a code on x43.fast) and `x43 claim`, commands, types
+- [types/cloudapps/runtime/server.d.ts](types/cloudapps/runtime/server.d.ts): exact server API types
+- [types/cloudapps/runtime/client.d.ts](types/cloudapps/runtime/client.d.ts): exact client API types

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "x43.fast",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Create, check and deploy live web apps on x43.fast from any coding agent",
+  "license": "UNLICENSED",
+  "homepage": "https://x43.fast",
+  "keywords": ["x43", "deploy", "agents", "cli", "cloudflare", "web apps"],
+  "type": "module",
+  "bin": { "x43": "dist/x43.js" },
+  "engines": { "node": ">=22" },
+  "files": ["dist", "types", "templates", "skills", "AGENTS.md", "CHATS.md", "llms.txt"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/x43.js",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test 'test/*.test.ts'",
+    "vendor-types": "node scripts/vendor-types.mjs"
+  },
+  "dependencies": {
+    "es-module-lexer": "3.0.4",
+    "sucrase": "3.35.1",
+    "typescript": "7.0.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6"
+  }
+}

package/skills/x43/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: x43
+description: Build, check and deploy a small live web app (site, tool, tracker, poll, guestbook, game…) on x43 / Cloud apps (x43.fast) with the x43 CLI. Use when the user asks to make, build, create, deploy, publish or change an app, site or tool "on x43", "on cloud apps" or "on x43.fast", or works in a directory with an x43.json.
+---
+
+# x43: live apps on x43.fast
+
+An x43 app (capsule) is `server/index.ts` (schema, queries, mutations) + `client/index.tsx` (a Preact `App`, Tailwind classes) + optional `shared/*.ts`. The Host builds and runs it at `https://<name>-app.x43.fast`. Read the project's `AGENTS.md` (`x43 init` and `x43 pull` write it) before writing code: it has the exact rules, the API and an example.
+
+## Loop
+
+1. No account is needed to start: without a login, `x43 deploy` deploys as a guest, and guest apps are deleted 7 days after their first deploy. Tell the user so; to keep the app, they run `x43 login` themselves (it prints a link and code they approve on x43.fast; the token must never pass through you or a command line), then `x43 claim`. If a command says "refused the token", ask them to run `x43 login`. `x43 whoami` shows the account and its plan's limits.
+2. New app: `x43 init <dir> && cd <dir>`. Existing app: `cd` into it (it has `x43.json`), or `x43 pull <name> <dir>`.
+3. Write or edit `server/index.ts`, `client/index.tsx` (and `shared/` if needed). Keep it to one screen and only what was asked.
+4. `x43 check`; fix every `path:line:col TSxxxx message`; repeat until `check: ok`.
+5. `x43 deploy`; if the Host refuses (`path:line:col message`), fix and deploy again.
+6. Test on the live app in one sandboxed sequence (rolled back, visitors see nothing): `x43 call mutation <name> '<json args>' query <name>`; confirm the results. Then `x43 errors`. Fix → check → deploy → call until right. `--commit` only for seed data the user asked for.
+7. Give the user the URL from `x43 deploy` (or `x43 open`) and one short paragraph on what the app does.
+
+## Rules that bite (details in AGENTS.md)
+
+- server imports only `cloudapps/server` + relative; client only `preact`, `preact/hooks`, `cloudapps/client` + relative, plus `import type app from "../server"`; shared only relative. No npm packages, React or localStorage for data.
+- Growing lists go in their own table (`v.id` + index), not `v.array`; read with an index and `take`/`paginate`/`count`, not by collecting a table. Time-based work (daily resets, expiry) is a cron. Args are one JSON object (`{}` for none) and untrusted: validate and `throw new Error("…")`.
+- Preact: `class`, `onInput`, hooks from `preact/hooks`; `useQuery` is `undefined` while loading; catch mutation rejections.
+- Don't use `--no-check` to get past type errors.
+- `/` is rendered to HTML at deploy (queries loading): browser globals (`window`, `document`, `localStorage`) only in `useEffect` and handlers, or `x43 deploy` warns and `/` is empty until its script runs.
+- Pro only: `fetch: ["api.example.com"]` in `capsule()` lets mutations, crons and HTTP handlers (not queries) call those hosts over https; `ctx.secrets.NAME` holds API keys the user sets with `x43 secret set NAME` (ask them to run it; never put a key in code or pass it through you); `http: { "POST /hook": (ctx, req) => ({ status, body }) }` serves webhooks at `<app URL>/_http/hook`. Other plans: the deploy is refused; tell the user.
+- APIs (AI, weather, email, payments) only through Pro `fetch` with the user's key; otherwise say so and build the closest honest version. No scripts from other sites (fonts: `meta.fonts`); images from other sites only over https and not on the Guest plan. A deploy over the plan's limits (apps, cron interval) is refused: tell the user. Data is shared by default; private (filtered by `ctx.auth.userId`) only when clearly personal; show only actions the server allows.
+- Uploads only on Pro: `const { url } = await upload(file)` from `cloudapps/client` (images or PDF, ≤ 10 MiB; store the `url`), `ctx.files.delete(url)` in a mutation. Custom domains (Pro): `x43 domain add <hostname>`, only when asked.
+
+## Landing pages
+
+Stacked full-width Tailwind sections (hero with one call to action, features, FAQ, footer), mobile first. `meta`: real title, one-line description, emoji `icon`, `fonts: ["Inter", "Playfair Display"]` (used as `font-[Inter]`, `font-[Playfair_Display]`). A waitlist/contact form is a validating mutation that stores the entry with no query returning it; the owner reads entries in the Data tab. No invented testimonials, logos, numbers or quotes. Keep the text static in components so it is in the HTML of `/`.