@coderook/cli 0.31.12 → 0.31.13

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coderook",
   "displayName": "CodeRook",
   "description": "Save, browse and restore whole-snapshot versions of a project on CodeRook, from Claude Code.",
-  "version": "0.31.12",
+  "version": "0.31.13",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/README.md

@@ -162,6 +162,36 @@ command refuses rather than waiting. Going private never asks.
 A public project's page offers only its named versions that have not been
 hidden (see `cbx promote` and `cbx mark --hide`).
 
+## Pages
+
+A public project can be served as a website: a Unity WebGL build, a Godot web
+export, a Vite or React build, or plain HTML.
+
+    cbx pages                              # on or off, the address, the version and folder it serves
+    cbx pages auto                         # find the build in the published version and turn it on
+    cbx pages on --folder Build/WebGL      # serve a folder you name
+    cbx pages on --spa                     # unknown paths serve index.html (--no-spa undoes it)
+    cbx pages on --isolate                 # cross-origin isolation, for Godot 4 threads
+    cbx pages on --version 12              # serve one version rather than the newest published
+    cbx pages off                          # stop serving it
+
+Each project gets an address of its own, `https://<project>--<owner>.<pages domain>/`.
+Until the service's Pages domain is set up, the address reads "goes live when
+the Pages domain is set up".
+
+Only published versions are served — a save made public with `cbx promote` or
+from History — and the project must be public. Only its owner can change the
+site. Turning it on asks first, because the site runs the project's code in
+anybody's browser under its name; pass `--yes` in a script. Turning it off
+never asks.
+
+When nothing published looks like a site and you run `cbx pages auto` in the
+project's folder, it looks on the disk for a build (`dist/`, `build/`, `out/`,
+`public/`, `Build/WebGL/` and the like). A build the ignore rules leave out is
+named along with the rule responsible, and it offers to add the `.gitignore`
+line that keeps it in (`!/dist/`). It does not save or publish anything: the
+next steps are `cbx submit`, `cbx promote`, then `cbx pages auto` again.
+
 ## Ignore rules
 
 ```

package/dist/cli/src/api.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceError = void 0;
 exports.putObject = putObject;
 exports.beginUpload = beginUpload;
 exports.uploadPart = uploadPart;
@@ -22,6 +23,10 @@ exports.cancelMerge = cancelMerge;
 exports.aiAccess = aiAccess;
 exports.setAiAccess = setAiAccess;
 exports.updateProject = updateProject;
+exports.pages = pages;
+exports.setPages = setPages;
+exports.detectPages = detectPages;
+exports.autoPages = autoPages;
 exports.compareVersions = compareVersions;
 exports.fileTextAt = fileTextAt;
 exports.versions = versions;
@@ -70,6 +75,25 @@ const config_js_1 = require("./config.js");
  * than ending the run.
  */
 const REQUEST_DEADLINE_MS = 180_000;
+/**
+ * A refusal from the service, with what it said and why.
+ *
+ * Still an Error carrying the service's own sentence, so every caller that
+ * prints `error.message` goes on printing the same words. The status and the
+ * code are there for the few commands that answer a particular refusal
+ * differently — "not available here yet" is not the same as "not allowed".
+ */
+class ServiceError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ServiceError";
+    }
+}
+exports.ServiceError = ServiceError;
 async function call(route, options = {}) {
     const token = await (0, config_js_1.loadToken)();
     if (!token) {
@@ -93,7 +117,7 @@ async function call(route, options = {}) {
         if (response.status === 401) {
             throw new Error("That token was not accepted. Run: cbx sign-in");
         }
-        throw new Error(body?.error?.message ?? `${route} failed (${response.status})`);
+        throw new ServiceError(body?.error?.message ?? `${route} failed (${response.status})`, response.status, typeof body?.error?.code === "string" ? body.error.code : null);
     }
     return body;
 }
@@ -388,6 +412,94 @@ async function updateProject(repositoryId, change) {
         body: change,
     });
 }
+function pagesSettings(row) {
+    const live = row.live;
+    const entry = row.entry;
+    return {
+        enabled: row.enabled === true,
+        folder: String(row.folder ?? ""),
+        versionId: row.versionId == null ? null : String(row.versionId),
+        spa: row.spa === true,
+        isolation: row.isolation === true,
+        address: row.address == null ? null : String(row.address),
+        domainReady: row.domainReady === true,
+        live: live
+            ? {
+                id: String(live.id ?? ""),
+                sequence: Number(live.sequence ?? 0),
+                name: live.name == null ? null : String(live.name),
+            }
+            : null,
+        entry: entry
+            ? { path: String(entry.path ?? ""), found: entry.found === true }
+            : null,
+        blocked: row.blocked == null ? null : String(row.blocked),
+    };
+}
+const pagesRoute = (repositoryId) => `/v1/repositories/${encodeURIComponent(repositoryId)}/pages`;
+/** What a project's site is set to, and what it is serving. */
+async function pages(repositoryId) {
+    return pagesSettings(await call(pagesRoute(repositoryId)));
+}
+/** Change a project's site. Only what is given is sent. */
+async function setPages(repositoryId, change) {
+    return pagesSettings(await call(pagesRoute(repositoryId), {
+        method: "PUT",
+        body: change,
+    }));
+}
+/** What the newest published version looks like it could serve. */
+async function detectPages(repositoryId) {
+    const body = await call(`${pagesRoute(repositoryId)}/detect`);
+    const version = body.version;
+    const suggestion = body.suggestion;
+    return {
+        version: version
+            ? {
+                id: String(version.id ?? ""),
+                sequence: Number(version.sequence ?? 0),
+                name: version.name == null ? null : String(version.name),
+            }
+            : null,
+        suggestion: suggestion
+            ? {
+                folder: String(suggestion.folder ?? ""),
+                kind: String(suggestion.kind ?? "static"),
+                spa: suggestion.spa === true,
+                isolation: suggestion.isolation === true,
+                why: String(suggestion.why ?? ""),
+            }
+            : null,
+        candidates: Array.isArray(body.candidates)
+            ? body.candidates.map((one) => ({
+                folder: String(one.folder ?? ""),
+                kind: String(one.kind ?? "static"),
+                why: String(one.why ?? ""),
+            }))
+            : [],
+        problem: body.problem == null ? null : String(body.problem),
+    };
+}
+/**
+ * Detect and apply in one request, so what is switched on is what the
+ * service found rather than what this client last saw.
+ */
+async function autoPages(repositoryId) {
+    const body = await call(`${pagesRoute(repositoryId)}/auto`, { method: "POST" });
+    const applied = body.applied;
+    return {
+        ...pagesSettings(body),
+        applied: applied
+            ? {
+                folder: String(applied.folder ?? ""),
+                kind: String(applied.kind ?? "static"),
+                spa: applied.spa === true,
+                isolation: applied.isolation === true,
+                why: String(applied.why ?? ""),
+            }
+            : null,
+    };
+}
 /**
  * What changed between two saved versions.
  *

package/dist/cli/src/cli.js

@@ -27,6 +27,7 @@ const help_js_1 = require("./help.js");
 const progress_js_1 = require("./progress.js");
 const publish_js_1 = require("./publish.js");
 const attach_command_js_1 = require("./attach_command.js");
+const pages_command_js_1 = require("./pages_command.js");
 const project_commands_js_1 = require("./project_commands.js");
 const track_commands_js_1 = require("./track_commands.js");
 const tracks_js_1 = require("../../desktop-app/src/main/tracks.js");
@@ -2323,6 +2324,39 @@ const SPECS = [
         ],
         run: project_commands_js_1.commandVisibility,
     },
+    {
+        name: "pages",
+        group: "Your projects",
+        summary: "serve a public project as a website",
+        usage: "pages [auto|on|off] [project]",
+        detail: "With no word, says whether the project's site is on, its address, which\n" +
+            "version it serves, from which folder, and anything stopping it.\n\n" +
+            "auto finds the build in the newest published version — a Unity WebGL\n" +
+            "build, a Godot web export, a Vite or React build, or plain HTML — and\n" +
+            "turns the site on with it. When nothing published looks like a site and\n" +
+            "you are in the project's folder, it looks here instead: a build left out\n" +
+            "by the ignore rules is named, with the .gitignore line that keeps it in.\n" +
+            "It never saves or publishes for you.\n\n" +
+            "on and auto ask first, because the site runs the project's code in\n" +
+            "anybody's browser under its name. Only published versions are served,\n" +
+            "the project must be public, and only its owner can change the site.\n" +
+            "off asks nothing.",
+        options: [
+            { flags: "--folder <path>", description: "on: where index.html is; . for the top" },
+            { flags: "--spa", description: "on: unknown paths serve index.html (--no-spa undoes)" },
+            { flags: "--isolate", description: "on: cross-origin isolation, for Godot 4 threads (--no-isolate)" },
+            { flags: "--version <n|id>", description: "on: serve this version rather than the newest published" },
+            { flags: "-y, --yes", description: "turn it on, or change .gitignore, without asking" },
+        ],
+        examples: [
+            "cbx pages",
+            "cbx pages auto",
+            "cbx pages on my-game --folder Build/WebGL --isolate",
+            "cbx pages on --version 12 --yes",
+            "cbx pages off",
+        ],
+        run: pages_command_js_1.commandPages,
+    },
     {
         name: "issues",
         group: "Your projects",

package/dist/cli/src/pages_command.js

@@ -0,0 +1,625 @@
+"use strict";
+/**
+ * `cbx pages`: a public project served as a website.
+ *
+ * Kept in its own file beside the other project commands. It is one command
+ * with four answers — what the site is set to, find the build for me, on, off
+ * — and the "find it for me" answer reaches onto the disk and into the ignore
+ * rules, which none of the account-side commands do.
+ *
+ * Turning a site on is the step that asks. What it serves is the project's
+ * own code, running in a stranger's browser under the project's name, and
+ * that deserves a yes from somebody who can give one. Turning it off asks
+ * nothing: it takes nothing from anybody who should have it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILD_FOLDERS = exports.whereWords = exports.kindWords = void 0;
+exports.splitPages = splitPages;
+exports.normaliseFolder = normaliseFolder;
+exports.explainRefusal = explainRefusal;
+exports.commandPages = commandPages;
+exports.findWebBuilds = findWebBuilds;
+exports.reinclusionFor = reinclusionFor;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const api_js_1 = require("./api.js");
+const config_js_1 = require("./config.js");
+const project_commands_js_1 = require("./project_commands.js");
+const worktree_js_1 = require("../../desktop-app/src/main/worktree.js");
+const rules_js_1 = require("../../desktop-app/src/main/rules.js");
+const colour = node_process_1.default.stdout.isTTY && !node_process_1.default.env.NO_COLOR;
+const dim = (text) => (colour ? `[2m${text}[0m` : text);
+const bold = (text) => (colour ? `[1m${text}[0m` : text);
+const accent = (text) => (colour ? `[33m${text}[0m` : text);
+const red = (text) => (colour ? `[31m${text}[0m` : text);
+const green = (text) => (colour ? `[32m${text}[0m` : text);
+const SUBCOMMANDS = new Set(["status", "auto", "on", "off"]);
+/** `[action] [project]`, where the action is recognised by being one. */
+function splitPages(positional) {
+    const [first, second] = positional;
+    if (first && SUBCOMMANDS.has(first.toLowerCase())) {
+        return {
+            action: first.toLowerCase(),
+            project: second,
+        };
+    }
+    return { action: "status", project: first };
+}
+/** What a kind of build is called when it is said out loud. */
+const KIND_WORDS = {
+    unity: "a Unity WebGL build",
+    godot: "a Godot web export",
+    vite: "a Vite build",
+    next: "a Next.js static export",
+    react: "a React build",
+    static: "a website",
+};
+const kindWords = (kind) => KIND_WORDS[kind] ?? "a website";
+exports.kindWords = kindWords;
+/** "in dist/", or "at the top of the project" for the empty folder. */
+const whereWords = (folder) => folder ? `in ${folder.replace(/\/+$/, "")}/` : "at the top of the project";
+exports.whereWords = whereWords;
+/**
+ * A folder as the service wants it: forward slashes, no leading `./`, no
+ * trailing slash, and "" for the top. Typed on Windows it arrives with
+ * backslashes, and `.` is how people say "right here".
+ */
+function normaliseFolder(typed) {
+    const cleaned = typed
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^(\.\/)+/, "")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "");
+    return cleaned === "." ? "" : cleaned;
+}
+/** A switch given as `--spa`, `--spa=off` or `--no-spa`. */
+function switchValue(parsed, ...names) {
+    for (const name of names) {
+        const value = parsed.flags.get(name);
+        if (value !== undefined) {
+            if (value === true)
+                return true;
+            return !["off", "false", "no", "n", "0"].includes(value.trim().toLowerCase());
+        }
+        if (parsed.flags.get(`no-${name}`) !== undefined)
+            return false;
+    }
+    return undefined;
+}
+const sure = (parsed) => parsed.flags.get("yes") === true || parsed.flags.get("y") === true;
+/**
+ * Say a refusal in a way somebody can act on.
+ *
+ * The service's own sentence is passed on as it is — it knows why — with a
+ * line after it where there is an obvious next command. Two are recognised
+ * by status rather than wording: "this service has no Pages yet", which is
+ * not the person's fault and not something they can fix, and "only the owner
+ * can", which the service says in its own words.
+ */
+function explainRefusal(error, projectRef) {
+    if (error instanceof api_js_1.ServiceError) {
+        if (error.status === 503 ||
+            error.code === "pages_not_ready" ||
+            (error.status === 404 && error.code === "not_found")) {
+            return ["Pages is not available on this service yet."];
+        }
+        if (error.status === 403) {
+            return [
+                error.message ||
+                    "Access denied: only the project's owner or an admin can change its site.",
+            ];
+        }
+        const lines = [error.message];
+        if (error.code === "pages_needs_public") {
+            lines.push(dim(`  Make the project public first: cbx visibility public${projectRef}`));
+        }
+        else if (error.code === "version_not_public") {
+            lines.push(dim("  Only a published version can be served. cbx promote publishes a save."));
+        }
+        return lines;
+    }
+    return [error instanceof Error ? error.message : String(error)];
+}
+function refuse(error, projectRef) {
+    for (const line of explainRefusal(error, projectRef))
+        console.error(red(line));
+    return 1;
+}
+/** The settings, laid out the way somebody checks them. */
+function printSettings(project, settings) {
+    const label = (text) => `  ${text.padEnd(9)} `;
+    console.log(`${bold(project.name)} — Pages is ${settings.enabled ? green("on") : dim("off")}`);
+    console.log(label("Address") +
+        (settings.address
+            ? settings.address
+            : dim("goes live when the Pages domain is set up")));
+    if (settings.live) {
+        const name = settings.live.name ? ` ${bold(settings.live.name)}` : "";
+        const which = settings.versionId ? "pinned" : "newest published";
+        /* While off it is what would be served, so it is not called "Serving". */
+        console.log(label(settings.enabled ? "Serving" : "Would serve") +
+            `${accent(`v${settings.live.sequence}`)}${name}  ${dim(which)}`);
+    }
+    else {
+        console.log(label("Serving") + dim("nothing published yet"));
+    }
+    console.log(label("Folder") +
+        (settings.folder ? `${settings.folder}/` : "top of the project") +
+        (settings.entry ? dim(`  (${settings.entry.path})`) : ""));
+    console.log(label("Options") +
+        `single-page app ${settings.spa ? "yes" : "no"}` +
+        dim(" · ") +
+        `cross-origin isolation ${settings.isolation ? "yes" : "no"}`);
+    if (settings.entry && !settings.entry.found) {
+        console.log(accent(`  Warning: ${settings.entry.path} is not in ` +
+            (settings.live ? `v${settings.live.sequence}` : "the published files") +
+            ", so the site has no front page."));
+    }
+    if (settings.blocked)
+        console.log(label("Blocked") + red(settings.blocked));
+}
+/** Pages settings for a project, or null after saying why not. */
+async function current(project, projectRef) {
+    try {
+        return await (0, api_js_1.pages)(project.id);
+    }
+    catch (error) {
+        refuse(error, projectRef);
+        return null;
+    }
+}
+/**
+ * Show, find, switch on or switch off a project's site.
+ */
+async function commandPages(parsed) {
+    const { action, project: reference } = splitPages(parsed.positional);
+    const project = await (0, project_commands_js_1.resolveProject)(reference);
+    if (!project)
+        return 1;
+    const projectRef = reference ? ` ${reference}` : "";
+    if (action === "status") {
+        const settings = await current(project, projectRef);
+        if (!settings)
+            return 1;
+        printSettings(project, settings);
+        if (!settings.enabled) {
+            console.log("");
+            console.log(dim(`Turn it on: cbx pages auto${projectRef}   finds the build for you`));
+            console.log(dim(`        or: cbx pages on${projectRef} --folder <path>`));
+        }
+        return 0;
+    }
+    if (action === "off") {
+        try {
+            const settings = await (0, api_js_1.setPages)(project.id, { enabled: false });
+            console.log(green(`Pages is off for ${project.name}.`));
+            if (settings.address)
+                console.log(dim(`  ${settings.address} no longer serves anything.`));
+            return 0;
+        }
+        catch (error) {
+            return refuse(error, projectRef);
+        }
+    }
+    if (action === "on")
+        return turnOn(parsed, project, projectRef);
+    return auto(parsed, project, projectRef);
+}
+/** Refused rather than asked when nobody can answer; see commandVisibility. */
+function nobodyToAsk(what) {
+    console.error(red(`${what} needs a yes, and nobody is here to give one.`));
+    console.error(dim("  Run it in a terminal to be asked, or add --yes."));
+    return 1;
+}
+/** Said before the question, so the yes is to something specific. */
+function sayWhatGoesPublic(project, address) {
+    console.log(`Pages serves ${bold(project.name)}'s published files as a website` +
+        (address ? ` at ${address}` : "") +
+        ".");
+    console.log("  Anybody can open it, and the code in it runs in their browser under the project's name.");
+    if (!address)
+        console.log(dim("  It goes live when the Pages domain is set up."));
+}
+function notPublic(project, projectRef) {
+    if (project.visibility === "public")
+        return null;
+    console.error(red(`${project.name} is not public, and only a public project can have a site.`));
+    console.error(dim(`  Make it public first: cbx visibility public${projectRef}`));
+    return 1;
+}
+/** `--version 12`, `--version <id>` or `--version newest`. */
+async function versionFor(project, typed) {
+    const text = typed.trim().replace(/^v(?=\d+$)/i, "");
+    if (["newest", "latest"].includes(text.toLowerCase()))
+        return { versionId: null };
+    if (/^\d+$/.test(text)) {
+        const saved = await (0, api_js_1.versions)(project.id);
+        const found = saved.find((one) => one.sequence === Number(text));
+        if (!found)
+            return { error: `${project.name} has no v${text}.` };
+        return { versionId: found.id };
+    }
+    return { versionId: text };
+}
+async function turnOn(parsed, project, projectRef) {
+    const change = { enabled: true };
+    const folder = parsed.flags.get("folder");
+    if (folder === true) {
+        console.error(red("--folder needs a path, such as --folder dist. Use --folder . for the top."));
+        return 1;
+    }
+    if (typeof folder === "string")
+        change.folder = normaliseFolder(folder);
+    const spa = switchValue(parsed, "spa");
+    if (spa !== undefined)
+        change.spa = spa;
+    const isolation = switchValue(parsed, "isolate", "isolation");
+    if (isolation !== undefined)
+        change.isolation = isolation;
+    const version = parsed.flags.get("version");
+    if (version === true) {
+        console.error(red("--version needs a number, an id, or newest."));
+        return 1;
+    }
+    if (typeof version === "string") {
+        const found = await versionFor(project, version);
+        if ("error" in found) {
+            console.error(red(found.error));
+            return 1;
+        }
+        change.versionId = found.versionId;
+    }
+    const refused = notPublic(project, projectRef);
+    if (refused !== null)
+        return refused;
+    const before = await current(project, projectRef);
+    if (!before)
+        return 1;
+    /*
+      Asked only when the site is off. Moving a site that is already public to
+      another folder or version changes what it shows, not whether it exists,
+      and that decision has already been made by somebody who could make it.
+    */
+    if (!before.enabled && !sure(parsed)) {
+        if (!node_process_1.default.stdin.isTTY)
+            return nobodyToAsk(`Turning on Pages for ${project.name}`);
+        sayWhatGoesPublic(project, before.address);
+        if (!(await (0, project_commands_js_1.agreed)(`Turn on Pages for ${project.name}? [y/N] `))) {
+            console.log(dim(`Nothing changed. Pages is still off for ${project.name}.`));
+            return 1;
+        }
+    }
+    let settings;
+    try {
+        settings = await (0, api_js_1.setPages)(project.id, change);
+    }
+    catch (error) {
+        return refuse(error, projectRef);
+    }
+    console.log(green(before.enabled ? `Pages settings changed for ${project.name}.` : `Pages is on for ${project.name}.`));
+    console.log("");
+    printSettings(project, settings);
+    return 0;
+}
+async function auto(parsed, project, projectRef) {
+    let found;
+    try {
+        found = await (0, api_js_1.detectPages)(project.id);
+    }
+    catch (error) {
+        return refuse(error, projectRef);
+    }
+    if (found.suggestion) {
+        const suggestion = found.suggestion;
+        const where = (0, exports.whereWords)(suggestion.folder);
+        const inVersion = found.version ? ` of v${found.version.sequence}` : "";
+        console.log(`Found ${(0, exports.kindWords)(suggestion.kind)} ${where}${inVersion}.`);
+        if (suggestion.why)
+            console.log(dim(`  ${suggestion.why}`));
+        const extras = [
+            suggestion.spa ? "as a single-page app" : "",
+            suggestion.isolation ? "with cross-origin isolation" : "",
+        ].filter(Boolean);
+        if (extras.length)
+            console.log(dim(`  It would be served ${extras.join(", ")}.`));
+        const refused = notPublic(project, projectRef);
+        if (refused !== null)
+            return refused;
+        if (!sure(parsed)) {
+            if (!node_process_1.default.stdin.isTTY)
+                return nobodyToAsk(`Turning on Pages for ${project.name}`);
+            const before = await (0, api_js_1.pages)(project.id).catch(() => null);
+            sayWhatGoesPublic(project, before?.address ?? null);
+            if (!(await (0, project_commands_js_1.agreed)(`Turn on Pages for ${project.name} with this? [y/N] `))) {
+                console.log(dim("Nothing changed."));
+                return 1;
+            }
+        }
+        let settings;
+        try {
+            settings = await (0, api_js_1.autoPages)(project.id);
+        }
+        catch (error) {
+            return refuse(error, projectRef);
+        }
+        console.log(green(`Pages is on for ${project.name}.`));
+        console.log("");
+        printSettings(project, settings);
+        return 0;
+    }
+    /*
+      Nothing to serve in what was published. If this is the project's own
+      folder, the build may be sitting right here and simply never have gone
+      up — most often because the ignore rules leave build output out, which
+      is exactly right for a repository and exactly wrong for a site.
+    */
+    const root = node_process_1.default.cwd();
+    const link = await (0, config_js_1.readLink)(root).catch(() => null);
+    if (link?.repositoryId === project.id) {
+        const builds = await findWebBuilds(root);
+        if (builds.length)
+            return offerLocalBuild(parsed, root, builds, projectRef);
+    }
+    console.log(found.problem ?? "Nothing in the published files looks like a website.");
+    return 1;
+}
+// ── the build on the disk ───────────────────────────────────────────────────
+/** Where build tools put a site, in roughly the order they are met. */
+exports.BUILD_FOLDERS = [
+    "dist",
+    "build",
+    "out",
+    "public",
+    "docs",
+    "Build",
+    "WebGL",
+    "web",
+    "html5",
+    "export",
+    "site",
+    "_site",
+    "www",
+];
+async function isFile(target) {
+    try {
+        return (await (0, promises_1.stat)(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function namesIn(directory) {
+    try {
+        return await (0, promises_1.readdir)(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+/** Unity's loader beside a Build folder, or Godot's pack beside the page. */
+async function kindOf(directory) {
+    for (const entry of await namesIn(node_path_1.default.join(directory, "Build"))) {
+        if (entry.isFile() && entry.name.endsWith(".loader.js"))
+            return "unity";
+    }
+    for (const entry of await namesIn(directory)) {
+        if (entry.isFile() && entry.name.endsWith(".pck"))
+            return "godot";
+    }
+    return "static";
+}
+/**
+ * Folders here holding an index.html, engine builds first.
+ *
+ * The usual build folders, one level inside them (`Build/WebGL`,
+ * `export/web`), and any other top-level folder only when an engine's marker
+ * says it is a build — a stray index.html in `templates/` is not a site.
+ */
+async function findWebBuilds(root) {
+    const found = [];
+    const seen = new Set();
+    const consider = async (folder, needMarker) => {
+        const key = folder.toLowerCase();
+        if (seen.has(key))
+            return;
+        const directory = node_path_1.default.join(root, ...folder.split("/"));
+        if (!(await isFile(node_path_1.default.join(directory, "index.html"))))
+            return;
+        const kind = await kindOf(directory);
+        if (needMarker && kind === "static")
+            return;
+        seen.add(key);
+        found.push({ folder, kind });
+    };
+    const top = (await namesIn(root)).filter((entry) => entry.isDirectory() &&
+        !entry.name.startsWith(".") &&
+        !(0, rules_js_1.isUncounted)(entry.name) &&
+        entry.name !== "node_modules");
+    const usual = new Set(exports.BUILD_FOLDERS.map((name) => name.toLowerCase()));
+    const ordered = [...top].sort((left, right) => rank(left.name) - rank(right.name) || left.name.localeCompare(right.name));
+    function rank(name) {
+        const at = exports.BUILD_FOLDERS.findIndex((one) => one.toLowerCase() === name.toLowerCase());
+        return at === -1 ? exports.BUILD_FOLDERS.length : at;
+    }
+    for (const entry of ordered) {
+        if (!usual.has(entry.name.toLowerCase()))
+            continue;
+        await consider(entry.name, false);
+        for (const inner of await namesIn(node_path_1.default.join(root, entry.name))) {
+            if (inner.isDirectory() && !inner.name.startsWith(".")) {
+                await consider(`${entry.name}/${inner.name}`, false);
+            }
+        }
+    }
+    for (const entry of ordered) {
+        if (usual.has(entry.name.toLowerCase()))
+            continue;
+        await consider(entry.name, true);
+    }
+    /* An engine's build is a surer answer than a folder that happens to be
+       called dist, so it goes first; otherwise the usual order stands. */
+    return found.sort((left, right) => Number(left.kind === "static") - Number(right.kind === "static"));
+}
+/** Characters a gitignore pattern would read as syntax, written as themselves. */
+const literal = (name) => name.replace(/[\\[\]*?!#]/g, "\\$&");
+/** Which file a rule came from, for saying so. */
+function sourceOf(rule, layers, rules) {
+    const layer = layers.find((one) => one.rules.includes(rule));
+    if (!layer)
+        return ".gitignore";
+    if (layer.base)
+        return `${layer.base}/.gitignore`;
+    /* The personal layer, when there is one, is always first. */
+    if (rules.local.trim() && layers[0] === layer)
+        return ".git/info/exclude";
+    return ".gitignore";
+}
+const written = (rule) => `${rule.negated ? "!" : ""}${rule.anchored ? "/" : ""}${rule.pattern}${rule.directoryOnly ? "/" : ""}`;
+/**
+ * Whether the ignore rules leave a build's front page out, and what would
+ * bring it back.
+ *
+ * Asked of the same rules, the same layers and the same matcher a save
+ * uses, so the answer is the one `cbx submit` will act on. The fix is
+ * checked the same way before it is offered: git cannot re-include a file
+ * whose folder is excluded, so each excluded folder on the way down gets
+ * its own negation, and a rule in a deeper .gitignore — which outranks the
+ * project's own — is named rather than argued with.
+ */
+async function reinclusionFor(root, folder, rules) {
+    const entry = folder ? `${folder}/index.html` : "index.html";
+    const tracked = await (0, worktree_js_1.gitTracked)(root);
+    if (tracked?.files.has(entry))
+        return { excluded: false };
+    const layers = await (0, worktree_js_1.collectLayers)(root, rules);
+    const deciding = (0, rules_js_1.decidingRule)(entry, false, layers);
+    if (!deciding || deciding.negated)
+        return { excluded: false };
+    const first = { rule: written(deciding), source: sourceOf(deciding, layers, rules) };
+    const lines = [];
+    const parts = folder ? folder.split("/") : [];
+    for (let attempt = 0; attempt <= parts.length + 1; attempt += 1) {
+        const shared = withLines(rules.shared, lines);
+        const trial = await (0, worktree_js_1.collectLayers)(root, { ...rules, shared });
+        const rule = (0, rules_js_1.decidingRule)(entry, false, trial);
+        if (!rule || rule.negated)
+            return { excluded: true, ...first, lines };
+        const source = sourceOf(rule, trial, { ...rules, shared });
+        if (source !== ".gitignore" && source !== ".git/info/exclude") {
+            return {
+                excluded: true,
+                ...first,
+                lines: null,
+                obstacle: `${source} has "${written(rule)}", and a deeper .gitignore outranks the project's own. Change or remove that line there.`,
+            };
+        }
+        /* The outermost folder still left out, or the page itself. */
+        let next = null;
+        for (let depth = 1; depth <= parts.length; depth += 1) {
+            const ancestor = parts.slice(0, depth).join("/");
+            if ((0, rules_js_1.excludes)(ancestor, true, trial)) {
+                next = `!/${parts.slice(0, depth).map(literal).join("/")}/`;
+                break;
+            }
+        }
+        next ??= `!/${[...parts, "index.html"].map(literal).join("/")}`;
+        if (lines.includes(next))
+            break;
+        lines.push(next);
+    }
+    return {
+        excluded: true,
+        ...first,
+        lines: null,
+        obstacle: `A negation in .gitignore does not bring ${entry} back. Change the "${first.rule}" line in ${first.source} instead.`,
+    };
+}
+const PAGES_HEADING = "# Kept for CodeRook Pages: the site is served from this build.";
+function withLines(shared, lines) {
+    if (!lines.length)
+        return shared;
+    const body = shared.replace(/\s*$/, "");
+    return `${body}${body ? "\n\n" : ""}${PAGES_HEADING}\n${lines.join("\n")}\n`;
+}
+/** Files under a folder the rules would still leave out, a few named. */
+async function stillLeftOut(root, folder, rules) {
+    const layers = await (0, worktree_js_1.collectLayers)(root, rules);
+    const result = { count: 0, examples: [] };
+    const pending = [folder];
+    let looked = 0;
+    while (pending.length && looked < 20_000) {
+        const relative = pending.shift();
+        for (const entry of await namesIn(node_path_1.default.join(root, ...relative.split("/")))) {
+            const child = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!(0, rules_js_1.isUncounted)(entry.name))
+                    pending.push(child);
+            }
+            else if (entry.isFile()) {
+                looked += 1;
+                if ((0, rules_js_1.excludes)(child, false, layers)) {
+                    result.count += 1;
+                    if (result.examples.length < 3)
+                        result.examples.push(child);
+                }
+            }
+        }
+    }
+    return result;
+}
+function nextSteps(projectRef) {
+    console.log("");
+    console.log("Then, to serve it:");
+    console.log(`  1. cbx submit       ${dim("save the folder, build included")}`);
+    console.log(`  2. cbx promote      ${dim("publish that save (or make it public from History)")}`);
+    console.log(`  3. cbx pages auto${projectRef}   ${dim("turn Pages on with what it finds")}`);
+}
+async function offerLocalBuild(parsed, root, builds, projectRef) {
+    const build = builds[0];
+    const label = build.folder ? `${build.folder}/` : "the top of the folder";
+    console.log(`Nothing published can be served yet, but ${(0, exports.kindWords)(build.kind)} is here in ${label}.`);
+    if (builds.length > 1) {
+        console.log(dim(`  Also found: ${builds.slice(1).map((one) => `${one.folder}/`).join(", ")}`));
+    }
+    const rules = await (0, worktree_js_1.readRules)(root);
+    const verdict = await reinclusionFor(root, build.folder, rules);
+    if (!verdict.excluded) {
+        console.log("It is not in the published version: it has not been saved and published yet.");
+        nextSteps(projectRef);
+        return 0;
+    }
+    console.log(`Your ignore rules leave ${label} out of every save — "${verdict.rule}" in ${verdict.source}.`);
+    console.log(dim("  That is right for a repository, where a build can be rebuilt, and wrong for a site."));
+    if (!verdict.lines) {
+        console.log(accent(`  ${verdict.obstacle}`));
+        nextSteps(projectRef);
+        return 1;
+    }
+    console.log("Adding this to .gitignore keeps it in:");
+    for (const line of verdict.lines)
+        console.log(`  ${accent(line)}`);
+    if (!sure(parsed)) {
+        if (!node_process_1.default.stdin.isTTY)
+            return nobodyToAsk("Changing .gitignore");
+        if (!(await (0, project_commands_js_1.agreed)("Add it to .gitignore? [y/N] "))) {
+            console.log(dim("Nothing changed."));
+            return 1;
+        }
+    }
+    const changed = { ...rules, shared: withLines(rules.shared, verdict.lines) };
+    await (0, worktree_js_1.writeRules)(root, changed);
+    console.log(green(`Added to .gitignore. ${label} now goes up with the next save.`));
+    const left = await stillLeftOut(root, build.folder, changed);
+    if (left.count) {
+        console.log(accent(`  ${left.count} file${left.count === 1 ? "" : "s"} in ${label} ` +
+            `${left.count === 1 ? "is" : "are"} still left out by other rules, such as ${left.examples.join(", ")}.`));
+        console.log(dim("  cbx ignore shows the rules in force."));
+    }
+    nextSteps(projectRef);
+    return 0;
+}

package/dist/cli/src/project_commands.js

@@ -17,6 +17,7 @@ exports.commandAi = commandAi;
 exports.readLevel = readLevel;
 exports.splitVisibility = splitVisibility;
 exports.offeredPublicly = offeredPublicly;
+exports.agreed = agreed;
 exports.commandVisibility = commandVisibility;
 exports.commandVersions = commandVersions;
 const node_process_1 = __importDefault(require("node:process"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.31.12",
+  "version": "0.31.13",
   "description": "The command line for CodeRook (coderook.com): version control and project hosting for projects of any size. Every save is a compressed snapshot, private or public, never used to train AI.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",

package/skills/coderook/SKILL.md

@@ -115,6 +115,23 @@ cbx visibility private         # back to the people invited
 exactly that.** `--yes` skips the question the command would otherwise ask
 them, so only pass it once they have answered it. Going private is always safe.
 
+## Serving a project as a website
+
+```bash
+cbx pages                  # is the site on, its address, what it serves
+cbx pages auto             # find the build in what was published, and offer to serve it
+cbx pages on --folder dist # serve a folder of the published version
+cbx pages off              # stop serving it
+```
+
+**Never turn Pages on (`auto` or `on`) unless the person has asked for their
+project to be served as a site.** It runs their code in strangers' browsers
+under the project's name. Pass `--yes` only once they have said yes. Only
+published versions are served and the project must be public. When `auto`
+finds a build left out by the ignore rules it offers a `.gitignore` line and
+lists the next steps; it never saves or publishes — ask before doing those.
+Turning Pages off is always safe.
+
 ## When two saves collide
 
 If somebody saved while this folder was behind, the second save becomes a merge