@pplethai/cli 0.1.0

package/dist/deps.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_CONFIG = {
+    apiBase: "https://api.ppleth.ai",
+    ssoBase: "https://sso.peoplesparty.or.th",
+    clientId: "382216793067947795",
+    repoBase: "https://github.com",
+    registryBase: "https://registry.npmjs.org",
+};
+export function platformConfig(env) {
+    return {
+        apiBase: env.PPLE_API_BASE ?? DEFAULT_CONFIG.apiBase,
+        ssoBase: env.PPLE_SSO_BASE ?? DEFAULT_CONFIG.ssoBase,
+        clientId: env.PPLE_CLIENT_ID ?? DEFAULT_CONFIG.clientId,
+        repoBase: env.PPLE_REPO_BASE ?? DEFAULT_CONFIG.repoBase,
+        registryBase: env.PPLE_REGISTRY_BASE ?? DEFAULT_CONFIG.registryBase,
+    };
+}
+/** XDG-style config home, so credentials never land in the app's repo. */
+export function configDir(env, homeDir) {
+    const base = env.XDG_CONFIG_HOME?.trim();
+    return path.join(base && base !== "" ? base : path.join(homeDir, ".config"), "pple");
+}
+/**
+ * Whether the CLI may check npm for a newer version. `PPLE_NO_UPDATE_CHECK`
+ * is the scripted-environment escape hatch; a local config file is the other
+ * half of the opt-out, and lives with the check itself.
+ */
+export function updateChecksAllowed(env) {
+    const raw = env.PPLE_NO_UPDATE_CHECK?.trim().toLowerCase();
+    return !raw || raw === "0" || raw === "false";
+}
+/** The CLI's own package directory — one above `src/` in a checkout, `dist/` once built. */
+export function packageRoot() {
+    return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+/**
+ * The version this CLI was published as, read from its own `package.json`.
+ * A checkout mid-build can be missing or unreadable — an unknown version
+ * simply means upgrade treats anything on npm as newer.
+ */
+export function packageVersion() {
+    try {
+        const manifest = readFileSync(path.join(packageRoot(), "package.json"), "utf8");
+        return String(JSON.parse(manifest).version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * The template ships inside the published package (`npm run build:template`
+ * copies it there); running from a checkout, it is the repo's own directory.
+ */
+export function resolveTemplateDir(env) {
+    const override = env.PPLE_TEMPLATE_DIR?.trim();
+    if (override)
+        return override;
+    const bundled = path.join(packageRoot(), "templates", "golden-path");
+    if (existsSync(bundled))
+        return bundled;
+    // Running from a checkout of the platform repo, before `build:template`.
+    return path.join(path.dirname(packageRoot()), "template");
+}
+/**
+ * Platform Skills ship inside the published package (`npm run build:skills`
+ * copies them there); running from a checkout, they are the repo's own
+ * `skills/pple-platform/`.
+ */
+export function resolveSkillsDir(env) {
+    const override = env.PPLE_SKILLS_DIR?.trim();
+    if (override)
+        return override;
+    const bundled = path.join(packageRoot(), "skills", "pple-platform");
+    if (existsSync(bundled))
+        return bundled;
+    return path.join(path.dirname(packageRoot()), "skills", "pple-platform");
+}
+/**
+ * The helper GIT_ASKPASS points at, which feeds git the app's repo token.
+ * git execs it directly rather than through a shell, so it ships with its
+ * executable bit set and finds node from its own shebang.
+ */
+export function askpassHelper() {
+    return path.join(packageRoot(), "askpass", "pple-askpass.mjs");
+}

package/dist/device-flow.js

@@ -0,0 +1,115 @@
+// OAuth 2.0 device authorization grant (RFC 8628) against PPLE ID.
+//
+// A terminal cannot receive a redirect, so the CLI asks PPLE ID for a code,
+// the Builder approves it in a browser (on any device), and the CLI polls
+// until the token is issued. Nothing sensitive is ever typed into the
+// terminal, and the CLI never handles the Builder's password.
+import { CliError } from "./errors.js";
+/** Zitadel's OAuth endpoints; the userinfo path the Provisioner uses too. */
+const DEVICE_AUTHORIZATION_PATH = "/oauth/v2/device_authorization";
+const TOKEN_PATH = "/oauth/v2/token";
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** `offline_access` is what makes a refresh token — and a durable login. */
+const SCOPES = "openid profile offline_access";
+function form(fields) {
+    return {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(fields).toString(),
+    };
+}
+const UNREACHABLE = new CliError("Couldn't reach PPLE ID to sign you in.", "Check your internet connection and try `pple auth login` again.");
+export async function requestDeviceCode(deps) {
+    const { ssoBase, clientId } = deps.config;
+    const res = await deps
+        .fetch(`${ssoBase}${DEVICE_AUTHORIZATION_PATH}`, form({ client_id: clientId, scope: SCOPES }))
+        .catch(() => null);
+    if (!res || !res.ok)
+        throw UNREACHABLE;
+    const body = (await res.json().catch(() => ({})));
+    if (!body.device_code || !body.user_code || !body.verification_uri) {
+        throw UNREACHABLE;
+    }
+    return {
+        deviceCode: body.device_code,
+        userCode: body.user_code,
+        verificationUri: body.verification_uri,
+        verificationUriComplete: body.verification_uri_complete ?? null,
+        expiresInMs: (body.expires_in ?? 600) * 1000,
+        // RFC 8628 says 5 seconds when the server doesn't specify.
+        intervalMs: (body.interval ?? 5) * 1000,
+    };
+}
+/**
+ * Poll until the Builder approves in the browser. Backs off when told to
+ * (`slow_down`), and gives up when the code expires rather than looping
+ * forever in front of someone who walked away.
+ */
+export async function awaitToken(deps, device) {
+    const { ssoBase, clientId } = deps.config;
+    const deadline = deps.now() + device.expiresInMs;
+    let intervalMs = device.intervalMs;
+    while (deps.now() < deadline) {
+        await deps.sleep(intervalMs);
+        const res = await deps
+            .fetch(`${ssoBase}${TOKEN_PATH}`, form({
+            client_id: clientId,
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: device.deviceCode,
+        }))
+            .catch(() => null);
+        if (!res)
+            throw UNREACHABLE;
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok && body.access_token)
+            return toTokenSet(deps, body);
+        switch (body.error) {
+            case "authorization_pending":
+                break;
+            case "slow_down":
+                intervalMs += 5000;
+                break;
+            case "access_denied":
+                throw new CliError("Sign-in was declined in the browser.", "Run `pple auth login` again if that wasn't you.");
+            case "expired_token":
+                throw expiredCode();
+            default:
+                throw new CliError("PPLE ID refused the sign-in.", body.error_description ?? "Try `pple auth login` again.");
+        }
+    }
+    throw expiredCode();
+}
+function expiredCode() {
+    return new CliError("The sign-in code expired before it was approved.", "Run `pple auth login` again — the browser step has to finish within a few minutes.");
+}
+/** Trade a refresh token for a fresh access token; null if it no longer works. */
+export async function refresh(deps, refreshToken) {
+    const { ssoBase, clientId } = deps.config;
+    const res = await deps
+        .fetch(`${ssoBase}${TOKEN_PATH}`, form({
+        client_id: clientId,
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        scope: SCOPES,
+    }))
+        .catch(() => null);
+    if (!res || !res.ok)
+        return null;
+    const body = (await res.json().catch(() => ({})));
+    if (!body.access_token)
+        return null;
+    return {
+        ...toTokenSet(deps, body),
+        // Rotation is optional: keep the current token when none comes back.
+        refreshToken: body.refresh_token ?? refreshToken,
+    };
+}
+function toTokenSet(deps, body) {
+    return {
+        accessToken: body.access_token,
+        refreshToken: body.refresh_token ?? null,
+        expiresAt: typeof body.expires_in === "number"
+            ? deps.now() + body.expires_in * 1000
+            : null,
+    };
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Every failure a Builder can see is a CliError: a sentence about their app,
+ * optionally followed by the one thing to do next. Anything else escaping to
+ * the top level is a bug in the CLI and is reported as such.
+ */
+export class CliError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = "CliError";
+    }
+}
+/** Both ends of the sign-in — the stored token, and what the platform says. */
+export const SIGNED_OUT = new CliError("You're not signed in.", "Run `pple auth login` first.");
+export const SIGN_IN_EXPIRED = new CliError("Your sign-in has expired.", "Run `pple auth login` to sign in again.");

package/dist/git.js

@@ -0,0 +1,127 @@
+// Git, masked.
+//
+// Builders are not expected to know git, so nothing above this module names
+// it: `pple init` "sets up the app's code", `pple deploy` "sends changes".
+// Every failure that a Builder could plausibly hit is translated here; the
+// raw git output only survives in the hint, where it helps whoever is asked
+// for help next.
+import { CliError } from "./errors.js";
+/** Builder Apps deploy from main; the workflow builds nothing else. */
+export const MAIN_BRANCH = "main";
+/** The username half of the Basic credential; GitHub ignores its value. */
+const TOKEN_USERNAME = "x-access-token";
+/**
+ * Every git invocation runs with the app's token in its environment and none
+ * of the machine's own credentials in play:
+ *
+ * - `GIT_ASKPASS` is how the token reaches git. Passing it in the URL would
+ *   put it in argv, which `ps` shows to every user on the machine, and in
+ *   `.git/config` once git wrote the remote down.
+ * - `credential.helper=` empties the helper list, so a keychain entry left
+ *   over from someone's own GitHub account can't answer ahead of the platform.
+ * - `GIT_TERMINAL_PROMPT=0` stops git asking a Builder for a password it is
+ *   the platform's job to supply.
+ */
+async function git(deps, dir, args, access) {
+    return deps.run("git", access ? ["-c", "credential.helper=", ...args] : args, {
+        cwd: dir,
+        env: {
+            GIT_TERMINAL_PROMPT: "0",
+            ...(access
+                ? {
+                    GIT_ASKPASS: deps.gitAskpass,
+                    PPLE_GIT_USER: TOKEN_USERNAME,
+                    PPLE_GIT_TOKEN: access.token,
+                }
+                : {}),
+        },
+    });
+}
+/** Author every commit as the Builder, since the pusher is the platform's bot. */
+function authorArgs(access) {
+    return [
+        "-c",
+        `user.name=${access.author.name}`,
+        "-c",
+        `user.email=${access.author.email}`,
+    ];
+}
+/**
+ * git failed because it was not allowed near the app's repo. The token is the
+ * platform's to mint, so this is the platform having declined — not something
+ * a Builder fixes with a credential of their own.
+ */
+function isAccessFailure(result) {
+    return /authentication|could not read|403|denied|not found/i.test(`${result.stdout}\n${result.stderr}`);
+}
+function noAccess(action, command) {
+    return new CliError(`The platform wouldn't let this computer ${action}.`, `Check that the app is still yours at https://console.ppleth.ai, then run \`${command}\` again.`);
+}
+function unreadableFolder(result) {
+    return new CliError("Couldn't read your app's folder.", result.stderr.trim());
+}
+async function gitOrThrow(deps, dir, args, onFailure, access) {
+    const result = await git(deps, dir, args, access).catch(() => {
+        throw new CliError("This computer doesn't have the tools the PPLE CLI needs.", "Install git (https://git-scm.com/downloads) and run the command again.");
+    });
+    if (result.code !== 0)
+        throw onFailure(result);
+    return result;
+}
+/** Fetch an app's code into `targetDir`, which must not exist yet. */
+export async function cloneApp(deps, repoUrl, targetDir, access) {
+    await gitOrThrow(deps, deps.cwd, ["clone", repoUrl, targetDir], (result) => isAccessFailure(result)
+        ? noAccess("reach your app's code", "pple init")
+        : new CliError("Couldn't fetch your app's code.", result.stderr.trim()), access);
+}
+/** True when the working copy holds changes that haven't been recorded yet. */
+export async function hasLocalChanges(deps, dir) {
+    const result = await gitOrThrow(deps, dir, ["status", "--porcelain"], unreadableFolder);
+    return result.stdout.trim() !== "";
+}
+/** Record every change in the folder as one entry in the app's history. */
+export async function recordChanges(deps, dir, message, access) {
+    await gitOrThrow(deps, dir, ["add", "-A"], unreadableFolder);
+    await gitOrThrow(deps, dir, [...authorArgs(access), "commit", "-m", message], (r) => new CliError("Couldn't save your changes.", r.stderr.trim()));
+}
+export async function headCommit(deps, dir) {
+    const result = await gitOrThrow(deps, dir, ["rev-parse", "HEAD"], (r) => new CliError("Couldn't read your app's history.", r.stderr.trim()));
+    return result.stdout.trim();
+}
+/** True when the local branch already matches what the platform has. */
+export async function isUpToDateWithRemote(deps, dir, access) {
+    await git(deps, dir, ["fetch", "origin", MAIN_BRANCH], access);
+    const local = await git(deps, dir, ["rev-parse", "HEAD"]);
+    const remote = await git(deps, dir, ["rev-parse", `origin/${MAIN_BRANCH}`]);
+    if (local.code !== 0 || remote.code !== 0)
+        return false;
+    return local.stdout.trim() === remote.stdout.trim();
+}
+/**
+ * Send the recorded changes to the platform. When the app has changes this
+ * copy hasn't seen — a Collaborator deployed meanwhile — they are merged in
+ * first, and only a genuine conflict reaches the Builder.
+ */
+export async function sendChanges(deps, dir, access) {
+    const push = ["push", "origin", `HEAD:${MAIN_BRANCH}`];
+    const pushed = await git(deps, dir, push, access);
+    if (pushed.code === 0)
+        return;
+    const output = `${pushed.stdout}\n${pushed.stderr}`;
+    if (!/rejected|non-fast-forward|fetch first/i.test(output)) {
+        if (isAccessFailure(pushed)) {
+            throw noAccess("send changes to your app", "pple deploy");
+        }
+        throw new CliError("Couldn't send your changes.", pushed.stderr.trim());
+    }
+    deps.out.say("Someone else changed this app — bringing their work in first…");
+    const rebase = await git(deps, dir, [...authorArgs(access), "pull", "--rebase", "origin", MAIN_BRANCH], access);
+    if (rebase.code !== 0) {
+        await git(deps, dir, ["rebase", "--abort"]);
+        throw new CliError("Your changes clash with changes someone else already deployed.", "Ask your AI coding agent to reconcile the two versions, then run `pple deploy` again.");
+    }
+    const retried = await git(deps, dir, push, access);
+    if (retried.code !== 0) {
+        throw new CliError("Couldn't send your changes.", retried.stderr.trim());
+    }
+}

package/dist/link.js

@@ -0,0 +1,49 @@
+// The link between a folder on a Builder's computer and an app on the
+// platform. `pple init` writes it, `pple deploy` reads it — which is why
+// deploy needs no arguments and cannot ship the wrong app.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.js";
+export const LINK_DIR = ".pple";
+export const LINK_FILE = "app.json";
+export async function writeLink(dir, link) {
+    await fs.mkdir(path.join(dir, LINK_DIR), { recursive: true });
+    await fs.writeFile(path.join(dir, LINK_DIR, LINK_FILE), `${JSON.stringify(link, null, 2)}\n`);
+}
+/**
+ * Find the app this command is about by walking up from the current folder,
+ * so `pple deploy` works from anywhere inside the app.
+ */
+export async function findLink(deps) {
+    let dir = path.resolve(deps.cwd);
+    for (;;) {
+        const candidate = path.join(dir, LINK_DIR, LINK_FILE);
+        const raw = await fs.readFile(candidate, "utf8").catch(() => null);
+        if (raw !== null) {
+            const link = parseLink(raw);
+            if (link)
+                return { ...link, dir };
+            throw new CliError("This app's platform link is damaged.", "Run `pple init <app>` in a fresh folder to set it up again.");
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new CliError("This folder isn't a PPLE app.", "Move into your app's folder, or run `pple init <app>` to set one up.");
+}
+function parseLink(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.slug !== "string" || parsed.slug === "")
+            return null;
+        return {
+            slug: parsed.slug,
+            apiBase: typeof parsed.apiBase === "string" ? parsed.apiBase : "",
+            url: typeof parsed.url === "string" ? parsed.url : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/node-deps.js

@@ -0,0 +1,84 @@
+// The Node implementations behind `Deps` — the only part of the CLI that
+// touches the real filesystem, the real clock, and real subprocesses.
+import { spawn } from "node:child_process";
+import readline from "node:readline/promises";
+import { askpassHelper, configDir, packageRoot, packageVersion, platformConfig, resolveSkillsDir, resolveTemplateDir, updateChecksAllowed, } from "./deps.js";
+export function spawnRun(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => (stdout += String(chunk)));
+        child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr }));
+    });
+}
+/** Best-effort browser launch: login still works from the printed URL. */
+async function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    await spawnRun(command, [url], { cwd: process.cwd() }).catch(() => undefined);
+}
+/** A yes/no question at the terminal. Anything but yes means no. */
+async function confirm(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Run the Builder's command line again on the `pple` that is installed now.
+ * The child inherits the terminal, so a re-run deploy still prompts and
+ * prints as if the Builder had typed it themselves.
+ *
+ * It re-runs the same script path deliberately: a global install replaces
+ * what that path resolves to, so the old path is exactly how to reach the new
+ * version — and the path this process was started from is the one the Builder
+ * chose, whatever else is on PATH.
+ */
+function reexec(argv) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [process.argv[1], ...argv], {
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 0));
+    });
+}
+export function nodeDeps(out, homeDir) {
+    return {
+        fetch: globalThis.fetch.bind(globalThis),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        cwd: process.cwd(),
+        configDir: configDir(process.env, homeDir),
+        out,
+        openBrowser,
+        run: spawnRun,
+        templateDir: resolveTemplateDir(process.env),
+        skillsDir: resolveSkillsDir(process.env),
+        packageDir: packageRoot(),
+        version: packageVersion(),
+        interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+        confirm,
+        reexec,
+        updateChecks: updateChecksAllowed(process.env),
+        gitAskpass: askpassHelper(),
+        config: platformConfig(process.env),
+    };
+}

package/dist/npm.js

@@ -0,0 +1,127 @@
+// npm, and the only place that names it: what the registry says the latest
+// CLI is, and whether this copy is one npm's global root holds. Everything
+// here answers a question — nothing here talks to the Builder.
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+export const PACKAGE = "@pplethai/cli";
+/** The line a Builder can always fall back to, whatever went wrong. */
+export const MANUAL_INSTALL = `npm install -g ${PACKAGE}`;
+/** What npm's `latest` dist-tag points at, or null when npm can't be reached. */
+export async function latestVersion(deps) {
+    const response = await deps
+        .fetch(`${deps.config.registryBase}/${PACKAGE}/latest`, {
+        headers: { accept: "application/json" },
+    })
+        .catch(() => null);
+    if (!response?.ok)
+        return null;
+    const body = (await response.json().catch(() => null));
+    return typeof body?.version === "string" && body.version !== ""
+        ? body.version
+        : null;
+}
+/**
+ * Whether the running CLI is the copy npm's global root holds. Anything else
+ * — a Homebrew wrapper, a checkout, another package manager — is a channel
+ * the CLI doesn't own and must not install over.
+ */
+export async function isNpmGlobalInstall(deps) {
+    const result = await deps
+        .run("npm", ["root", "-g"], { cwd: deps.cwd })
+        .catch(() => null);
+    if (!result || result.code !== 0)
+        return false;
+    const globalRoot = result.stdout.trim();
+    if (globalRoot === "")
+        return false;
+    return contains(globalRoot, deps.packageDir);
+}
+/**
+ * Install a specific version globally. Never with sudo — see ADR-0007.
+ *
+ * An npm that can't be started at all (not on PATH, not executable) comes
+ * back as a failed run rather than a rejection: to a Builder that is the same
+ * event as an install that failed, and it deserves the same explanation
+ * instead of a stack trace.
+ */
+export function installGlobally(deps, version) {
+    return deps
+        .run("npm", ["install", "-g", `${PACKAGE}@${version}`], { cwd: deps.cwd })
+        .catch((e) => ({
+        code: 1,
+        stdout: "",
+        stderr: e instanceof Error ? e.message : String(e),
+    }));
+}
+/**
+ * Whether `child` sits inside `parent`. Both sides are resolved through
+ * symlinks first: a Node install managed by nvm or Volta reaches the CLI by a
+ * symlinked path, and comparing the two spellings would call a perfectly
+ * ordinary npm-global install "some other channel".
+ */
+async function contains(parent, child) {
+    const [from, to] = await Promise.all([resolve(parent), resolve(child)]);
+    const relative = path.relative(from, to);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+/** Real path where one exists; the literal path where it doesn't. */
+async function resolve(dir) {
+    return realpath(dir).catch(() => path.resolve(dir));
+}
+/**
+ * Compare two npm versions. Prereleases sort below their own release, dotted
+ * prerelease segments compare numerically where both sides are numbers, and
+ * anything unparseable counts as older so a broken version never wins.
+ */
+export function isNewer(candidate, current) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(current);
+    if (!a)
+        return false;
+    if (!b)
+        return true;
+    for (let i = 0; i < 3; i += 1) {
+        if (a.parts[i] !== b.parts[i])
+            return a.parts[i] > b.parts[i];
+    }
+    return comparePrerelease(a.prerelease, b.prerelease) > 0;
+}
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(version.trim());
+    if (!match)
+        return null;
+    return {
+        parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] ? match[4].split(".") : [],
+    };
+}
+/** Semver's prerelease rules: a release outranks any prerelease of itself. */
+function comparePrerelease(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const left = a[i];
+        const right = b[i];
+        if (left === undefined)
+            return -1;
+        if (right === undefined)
+            return 1;
+        const numeric = /^\d+$/.test(left) && /^\d+$/.test(right);
+        if (left === right)
+            continue;
+        return numeric ? (Number(left) > Number(right) ? 1 : -1) : left > right ? 1 : -1;
+    }
+    return 0;
+}
+/** The most useful line npm printed, without the noise around it. */
+export function npmMessage(result) {
+    const lines = `${result.stderr}\n${result.stdout}`
+        .split("\n")
+        .map((line) => line.replace(/^npm (ERR!|error|warn)\s*/i, "").trim())
+        .filter((line) => line !== "");
+    return lines.slice(0, 3).join("\n") || "it stopped without saying why.";
+}

package/dist/scaffold.js

@@ -0,0 +1,58 @@
+// Copying the golden-path template into an app's folder.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { MANUAL_INSTALL } from "./npm.js";
+/** Build output and local secrets are never part of a fresh app. */
+const SKIP = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    ".wrangler",
+    ".dev.vars",
+    ".env",
+]);
+/**
+ * npm strips a file literally named `.gitignore` from published packages, so
+ * the bundled template carries it under a safe name and it is restored here.
+ */
+const RESTORED_NAMES = new Map([["gitignore", ".gitignore"]]);
+/** The name the template uses for itself everywhere it names something. */
+const TEMPLATE_SLUG = "pple-app";
+/** Files whose contents name the app: package name, D1 database, R2 bucket. */
+const PERSONALIZED = new Set(["package.json", "package-lock.json", "wrangler.jsonc"]);
+export async function scaffold(templateDir, targetDir, slug) {
+    const entries = await fs.readdir(templateDir).catch(() => null);
+    if (entries === null) {
+        throw new CliError("The PPLE app template is missing from this installation of the CLI.", `Reinstall the CLI (\`${MANUAL_INSTALL}\`) and try again.`);
+    }
+    const written = [];
+    await copyDir({ from: templateDir, to: targetDir, prefix: "", slug, written });
+    return written.sort();
+}
+async function copyDir(step) {
+    for (const entry of await fs.readdir(step.from, { withFileTypes: true })) {
+        if (SKIP.has(entry.name))
+            continue;
+        const name = RESTORED_NAMES.get(entry.name) ?? entry.name;
+        const source = path.join(step.from, entry.name);
+        const destination = path.join(step.to, name);
+        const relative = step.prefix === "" ? name : `${step.prefix}/${name}`;
+        if (entry.isDirectory()) {
+            await fs.mkdir(destination, { recursive: true });
+            await copyDir({ ...step, from: source, to: destination, prefix: relative });
+            continue;
+        }
+        if (PERSONALIZED.has(name)) {
+            const contents = await fs.readFile(source, "utf8");
+            await fs.writeFile(destination, replaceAll(contents, TEMPLATE_SLUG, step.slug));
+        }
+        else {
+            await fs.copyFile(source, destination);
+        }
+        step.written.push(relative);
+    }
+}
+function replaceAll(text, from, to) {
+    return text.split(from).join(to);
+}