@pplethai/cli 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# pple CLI
+
+The Builder's terminal tool: three commands between a PPLE ID and a live app.
+
+```bash
+pple auth login                 # sign in with your PPLE ID (browser, no password in the terminal)
+pple init brave-otter           # set up the app's code in ./brave-otter, linked to the app
+pple deploy -m "Add the form"   # send the changes and put them live
+pple upgrade                    # update pple itself from npm
+```
+
+Git is an implementation detail, and so is GitHub. A Builder is told what
+happened to *their app* — "Sending your changes…", "Volunteer Sign-up is live
+at https://brave-otter.ppleth.ai" — never what happened to a branch, and never
+that there is an account somewhere they should go and get. Only a genuine
+conflict surfaces the tools underneath, and even then with an instruction
+rather than a stack trace.
+
+## Reaching the app's code
+
+App repos are private and the Builder's machine has no credential for them.
+Before each command that touches code, the CLI asks the Provisioner for a
+token scoped to that one repo, keeps it in memory, and hands it to `git`
+through the child process's environment: `GIT_ASKPASS` points at
+[`askpass/pple-askpass.mjs`](askpass/pple-askpass.mjs), which reads the token
+back out of that environment when git asks for a password. `origin` stays a
+plain URL, so the token never reaches argv (world-readable via `ps`),
+`.git/config`, or any other file. Commits are authored as the Builder's PPLE
+ID identity, which the same response supplies — the pusher is the platform's
+GitHub App, and would otherwise be the only name in an app's history. The
+reasoning is [ADR-0005](../docs/adr/0005-builders-never-hold-github-credentials.md).
+
+## How the commands work
+
+**`pple auth login`** runs the OAuth device authorization grant against PPLE
+ID: the CLI prints a code, opens the verification page, and polls until the
+Builder approves it. Tokens land in `$XDG_CONFIG_HOME/pple/credentials.json`
+(mode `0600`) — never inside an app folder, which is a repo the platform
+owns. `pple whoami` renews an expiring token silently via the refresh token.
+
+**`pple init <app>`** takes an app the Provisioner already created (ADR-0001
+— the CLI never creates repos), fetches its code, scaffolds the golden-path
+template into it under the app's own name, writes `.pple/app.json`
+linking the folder to the app, and installs the platform Skill overlay the
+Builder's AI coding agent can load (ADR-0006).
+
+**`pple deploy`** refreshes that same Skill overlay, records everything in
+the folder, sends it to the app's repo — merging in a Collaborator's work if
+there is any — then watches the platform build it and reports the live URL,
+or the build output that explains why nothing changed. It needs no
+arguments: the link file says which app. Account-only commands
+(`auth login` / `logout` / `whoami`) never touch Skills.
+
+**`pple upgrade`** asks npm what the latest `@pplethai/cli` is and, when
+this copy is one npm's global root holds, installs it — which is also how
+Skills and the golden-path template move forward (ADR-0006, ADR-0007). Any
+other install channel is told the manual `npm install -g @pplethai/cli`
+line rather than having a second copy installed over the first, and so is a
+failed install, carrying npm's own reason. The CLI never uses `sudo`: a global
+folder the Builder can't write to is theirs to fix, not the CLI's to force.
+
+## Staying current
+
+About once a day, before running the command it was given, the CLI asks npm
+whether there is a newer `pple`. It runs *before* the command because that is
+the only moment an upgrade is free: nothing is half-done, so the new version
+can simply be handed the same command line. At a terminal the Builder is
+asked, and on a yes the CLI installs the new version and re-runs the original
+command on it. With nobody at the keyboard — the AFK agent runs the CLI is
+built to serve — it prints one line about the new version and gets on with the
+command; it never asks a question that could hang.
+
+The check is written to fail towards the command. A registry that can't be
+reached says nothing at all and costs one request, not one per command:
+`update-check.json` in the CLI's config directory records that npm was
+*asked*, not what it answered. A failed upgrade prints npm's own reason and
+the manual line, then offers to carry on with the current CLI (unattended:
+carries on). Two ways to turn the whole thing off:
+
+```bash
+PPLE_NO_UPDATE_CHECK=1 pple deploy          # this run, or exported in CI
+echo '{ "updateCheck": false }' > ~/.config/pple/config.json   # this machine
+```
+
+## Layout
+
+| File | What it holds |
+| ---- | ------------- |
+| `src/cli.ts` | argument parsing and the command table |
+| `src/commands/` | one file per command, each taking only `Deps` |
+| `src/deps.ts` | every seam: fetch, clock, subprocesses, output, template/skills dirs |
+| `src/device-flow.ts` | RFC 8628 against PPLE ID |
+| `src/api.ts` | the Provisioner API, and the only place that knows its error codes |
+| `src/git.ts` | git, and the only place that names it or holds the repo token |
+| `src/scaffold.ts` | copying the golden-path template |
+| `src/skills.ts` | refreshing the platform Skill overlay into an app folder |
+| `src/npm.ts` | npm: the registry's latest version, and the install channel |
+| `src/update.ts` | the daily update check, its cadence state, and its opt-outs |
+| `askpass/pple-askpass.mjs` | what git runs to be told the app's repo token |
+
+## Development
+
+```bash
+npm install
+npm test            # drives whole commands against a fake Provisioner and real git
+npm run typecheck
+npm run build       # bundles the template and Skills, compiles to dist/
+```
+
+Tests run the real command path — real `git` in a temp directory, a fake
+platform behind `Deps.fetch`, and a virtual clock so polling loops finish
+instantly. `test/support/harness.ts` is the entry point.
+
+App repos are served in tests by `git http-backend` behind Basic auth
+(`test/support/git-server.ts`), accepting only tokens the fake platform
+minted. A local path would let every clone and push succeed with no credential
+at all, and nothing would show that the platform's token is what opens a
+private repo.
+
+The published package carries its own copies of the golden-path template
+(`npm run build:template` copies `../template`) and platform Skills
+(`npm run build:skills` copies `../skills/pple-platform`). Running from a
+checkout falls back to those repo paths directly. `PPLE_TEMPLATE_DIR`,
+`PPLE_SKILLS_DIR`, `PPLE_API_BASE`, `PPLE_SSO_BASE`, `PPLE_CLIENT_ID`,
+`PPLE_REPO_BASE`, and `PPLE_REGISTRY_BASE` override the defaults for staging
+work.
+
+## CLI release
+
+A full Phase 1 launch includes a **CLI release**: shipping
+`@pplethai/cli` (bin: `pple`) to the npm `latest` dist-tag, which is what
+Builders install and self-update from. This is **not** part of the Cloudflare
+Worker deploy — a Worker rollback must never ship or unship a CLI version.
+
+Releases happen through the **CLI release** workflow
+(`.github/workflows/cli-release.yml`): anyone with repository write dispatches
+it on `main`, and it re-runs typecheck, test, and build, asks the release gate
+whether the version in `package.json` may reach the registry, publishes, and
+only then tags the commit `cli-vX.Y.Z`. The one exception is the bootstrap
+publish that creates the package on npm, which a human runs once — see
+[docs/deploy-phase1.md](../docs/deploy-phase1.md) §3 for both.
+
+The version comes from `package.json` on `main` — the workflow takes no
+version input, and refuses to release a version npm already holds. Nobody
+edits that version by hand: a PR changing what this package ships carries a
+Changeset (`npx changeset` at the repo root, or a `skip-changeset` label if it
+ships nothing), and the Version Packages PR spends those Changesets into
+`package.json` and `CHANGELOG.md`. So `main` may sit ahead of npm — a version
+here is prepared, not shipped. See [`.changeset/README.md`](../.changeset/README.md)
+and [ADR-0008](../docs/adr/0008-cli-release-is-a-deliberate-act.md).
+
+Past the bootstrap publish that creates the package, there is no supported way
+to release from a laptop. The release gate is `scripts/release-gate.mjs`, and
+it answers locally too:
+
+```bash
+node scripts/release-gate.mjs release   # may this version reach npm?
+npm publish --access public --dry-run   # inspect the tarball, upload nothing
+```
+
+Builders install with `npm install -g @pplethai/cli`.

package/askpass/pple-askpass.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// What git asks when it needs a credential for the app's repo.
+//
+// git calls this with the prompt as its only argument and reads the answer
+// from stdout. The token reaches it through the environment of the git process
+// the CLI spawned — never through a command line, which `ps` makes readable to
+// everyone on the machine, and never through a file (ADR-0005).
+//
+// Plain .mjs rather than compiled output, shipped with its executable bit set:
+// git execs GIT_ASKPASS directly rather than through a shell, so the shebang
+// above is what finds node, and there is no build step to keep in step.
+
+const prompt = process.argv[2] ?? "";
+const answer = /username/i.test(prompt)
+  ? (process.env.PPLE_GIT_USER ?? "")
+  : (process.env.PPLE_GIT_TOKEN ?? "");
+
+process.stdout.write(`${answer}\n`);

package/dist/api.js

@@ -0,0 +1,62 @@
+// The Provisioner API as the CLI sees it. Every non-2xx answer becomes a
+// sentence a Builder can act on — this is the only place in the CLI that
+// knows the platform's error codes.
+import { CliError, SIGN_IN_EXPIRED } from "./errors.js";
+export class ProvisionerClient {
+    deps;
+    token;
+    constructor(deps, token) {
+        this.deps = deps;
+        this.token = token;
+    }
+    me() {
+        return this.request("GET", "/me");
+    }
+    app(slug) {
+        return this.request("GET", `/apps/${encodeURIComponent(slug)}`, { slug });
+    }
+    repoToken(slug) {
+        return this.request("POST", `/apps/${encodeURIComponent(slug)}/repo-token`, { slug });
+    }
+    deploys(slug) {
+        return this.request("GET", `/apps/${encodeURIComponent(slug)}/deploys`, { slug }).then((r) => r.deploys);
+    }
+    async request(method, path, context = {}) {
+        const url = `${this.deps.config.apiBase}${path}`;
+        const res = await this.deps
+            .fetch(url, {
+            method,
+            headers: { authorization: `Bearer ${this.token}` },
+        })
+            .catch(() => null);
+        if (!res) {
+            throw new CliError("Couldn't reach the PPLE Platform.", "Check your internet connection and try again.");
+        }
+        if (res.ok)
+            return (await res.json());
+        const body = (await res.json().catch(() => ({})));
+        throw platformError(res.status, body.error, context.slug);
+    }
+}
+function platformError(status, code, slug) {
+    if (status === 401)
+        return SIGN_IN_EXPIRED;
+    if (code === "not_org_member") {
+        return new CliError("Your PPLE ID isn't part of the party organization, so it can't build apps.", "Ask your team lead to add you, then try again.");
+    }
+    if (code === "agreement_required") {
+        return new CliError("You haven't accepted the Builder agreement yet.", "Accept it at https://console.ppleth.ai and run this command again.");
+    }
+    if (code === "app_has_no_repo") {
+        return new CliError(`${slug ? `"${slug}"` : "That app"} isn't finished being set up yet.`, "Wait a moment and try again; if it stays like this, ask the platform team.");
+    }
+    if (status === 404) {
+        return new CliError(slug
+            ? `There's no app called "${slug}" that belongs to you.`
+            : "That doesn't exist on the platform.", "Check the app list at https://console.ppleth.ai.");
+    }
+    if (status >= 500 || code === "sso_unavailable") {
+        return new CliError("The PPLE Platform is having trouble right now.", "Wait a moment and try again; if it keeps happening, tell the platform team.");
+    }
+    return new CliError("The PPLE Platform refused that request.", code ? `It said: ${code}` : undefined);
+}

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import os from "node:os";
+import { run } from "./cli.js";
+import { nodeDeps } from "./node-deps.js";
+import { consoleOutput } from "./ui.js";
+const out = consoleOutput((text) => process.stdout.write(text), (text) => process.stderr.write(text));
+try {
+    process.exitCode = await run(process.argv.slice(2), nodeDeps(out, os.homedir()));
+}
+catch (e) {
+    // Not a failure the CLI knows how to explain — say so plainly instead of
+    // dumping a stack trace on a Builder who can't act on it.
+    process.stderr.write("Something went wrong inside the pple CLI. Please send this to the platform team:\n");
+    process.stderr.write(`${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+    process.exitCode = 1;
+}

package/dist/cli.js

@@ -0,0 +1,103 @@
+import * as auth from "./commands/auth.js";
+import { deploy } from "./commands/deploy.js";
+import { init } from "./commands/init.js";
+import { upgrade } from "./commands/upgrade.js";
+import { CliError } from "./errors.js";
+import { checkForUpdate, wantsUpdateCheck } from "./update.js";
+const USAGE = `pple — build and ship apps on the PPLE Platform
+
+  pple auth login          sign in with your PPLE ID
+  pple auth logout         forget this computer's sign-in
+  pple whoami              show who you're signed in as
+
+  pple init <app>          set up an app's code on this computer
+  pple deploy [-m "note"]  send your changes and put them live
+
+  pple upgrade             update pple itself to the newest version
+
+Options
+  -m, --message <note>     what changed, shown in the app's history
+      --dir <folder>       where to put the app's code (pple init)
+  -h, --help               show this help
+`;
+/**
+ * Parse and run one command line. Returns the process exit code; expected
+ * failures come back as 1 with a Builder-language message already printed,
+ * and anything else throws for the entry point to report as a CLI bug.
+ */
+export async function run(argv, deps) {
+    try {
+        // Before the command, never during it: an upgrade mid-deploy would swap
+        // the CLI under its own feet, and this is the one point where handing the
+        // whole command line to the new version costs nothing.
+        if (wantsUpdateCheck(argv)) {
+            const handled = await checkForUpdate(deps, argv);
+            if (handled !== null)
+                return handled;
+        }
+        await dispatch(argv, deps);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            deps.out.fail(e);
+            return 1;
+        }
+        throw e;
+    }
+}
+async function dispatch(argv, deps) {
+    const args = [...argv];
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        deps.out.say(USAGE);
+        return;
+    }
+    const command = args.shift();
+    switch (command) {
+        case "auth": {
+            const sub = args.shift();
+            if (sub === "login")
+                return auth.login(deps);
+            if (sub === "logout")
+                return auth.logout(deps);
+            if (sub === "whoami")
+                return auth.whoami(deps);
+            throw unknown(`auth ${sub ?? ""}`.trim());
+        }
+        case "whoami":
+            return auth.whoami(deps);
+        case "init": {
+            const dir = takeOption(args, "--dir");
+            const slug = args.shift();
+            if (!slug) {
+                throw new CliError("Which app? `pple init` needs the app's name.", "Create the app at https://console.ppleth.ai — it shows you the exact command to run.");
+            }
+            return init(deps, { slug, dir });
+        }
+        case "deploy": {
+            const message = takeOption(args, "--message", "-m");
+            return deploy(deps, { message });
+        }
+        case "upgrade":
+            return upgrade(deps);
+        case "help":
+            deps.out.say(USAGE);
+            return;
+        default:
+            throw unknown(command ?? "");
+    }
+}
+function unknown(command) {
+    return new CliError(`There's no \`pple ${command}\` command.`, "Run `pple --help` to see what you can do.");
+}
+/** Pull `--name value` out of the argument list, wherever it appears. */
+function takeOption(args, long, short) {
+    const index = args.findIndex((arg) => arg === long || (short && arg === short));
+    if (index === -1)
+        return undefined;
+    const [, value] = args.splice(index, 2);
+    if (value === undefined || value.startsWith("-")) {
+        throw new CliError(`\`${long}\` needs a value after it.`);
+    }
+    return value;
+}

package/dist/commands/auth.js

@@ -0,0 +1,32 @@
+import { ProvisionerClient } from "../api.js";
+import { clearCredentials, saveCredentials } from "../credentials.js";
+import { awaitToken, requestDeviceCode } from "../device-flow.js";
+import { client } from "../session.js";
+export async function login(deps) {
+    const device = await requestDeviceCode(deps);
+    deps.out.say("To sign in, open this page and enter the code:");
+    deps.out.say();
+    deps.out.say(`  ${device.verificationUri}`);
+    deps.out.say(`  code: ${device.userCode}`);
+    deps.out.say();
+    deps.out.say("Waiting for you to approve the sign-in…");
+    await deps.openBrowser(device.verificationUriComplete ?? device.verificationUri);
+    const tokens = await awaitToken(deps, device);
+    await saveCredentials(deps, { ...tokens, ssoBase: deps.config.ssoBase });
+    const me = await new ProvisionerClient(deps, tokens.accessToken).me();
+    deps.out.say(`Signed in as ${me.name ?? me.sub}.`);
+    if (!me.isBuilder) {
+        deps.out.say("One more step before you can create apps: accept the Builder agreement at https://console.ppleth.ai");
+    }
+}
+export async function logout(deps) {
+    const had = await clearCredentials(deps);
+    deps.out.say(had ? "Signed out." : "You weren't signed in.");
+}
+export async function whoami(deps) {
+    const me = await (await client(deps)).me();
+    deps.out.say(`Signed in as ${me.name ?? me.sub}.`);
+    if (!me.isBuilder) {
+        deps.out.say("You haven't accepted the Builder agreement yet — do that at https://console.ppleth.ai");
+    }
+}

package/dist/commands/deploy.js

@@ -0,0 +1,106 @@
+import { CliError } from "../errors.js";
+import { hasLocalChanges, headCommit, isUpToDateWithRemote, recordChanges, sendChanges, } from "../git.js";
+import { findLink } from "../link.js";
+import { client } from "../session.js";
+import { refreshSkills } from "../skills.js";
+/** How often to ask the platform how the build is going. */
+const POLL_INTERVAL_MS = 3000;
+/** How long to wait for CI to pick the push up before saying so. */
+const BUILD_START_TIMEOUT_MS = 3 * 60_000;
+/** How long a build itself may take before the CLI stops watching. */
+const BUILD_TIMEOUT_MS = 10 * 60_000;
+/** How much of a failed build's log to show; the rest is in the console. */
+const LOG_TAIL_LINES = 20;
+/**
+ * Put the Builder's current work live: record it, send it, and watch the
+ * platform build it — reporting the live URL, or a failure they can read.
+ */
+export async function deploy(deps, options) {
+    const link = await findLink(deps);
+    if (link.apiBase !== "" && link.apiBase !== deps.config.apiBase) {
+        throw new CliError("This app belongs to a different PPLE Platform than the one you're signed in to.", `It was set up against ${link.apiBase}.`);
+    }
+    const api = await client(deps);
+    const app = await api.app(link.slug);
+    if (app.status === "retired") {
+        throw new CliError(`"${app.name}" has been retired.`, "A retired app can't be deployed to. Create a new app in the Console if you want to pick this work back up.");
+    }
+    if (app.status !== "ready") {
+        throw new CliError(`"${app.name}" isn't ready to receive changes yet.`, app.error
+            ? `Setting it up ran into a problem: ${app.error}`
+            : "Check on it at https://console.ppleth.ai and try again in a moment.");
+    }
+    // One token for the whole command, kept in memory: it says both what this
+    // machine may push and whose name the work goes out under (ADR-0005).
+    const access = await api.repoToken(link.slug);
+    // Keep the local Skill overlay current even when there is nothing new to
+    // send — including first seed for folders set up before Skills shipped.
+    await refreshSkills(deps, link.dir);
+    if (await hasLocalChanges(deps, link.dir)) {
+        deps.out.say("Saving your changes…");
+        await recordChanges(deps, link.dir, options.message ?? `Update ${app.name}`, access);
+    }
+    else if (await isUpToDateWithRemote(deps, link.dir, access)) {
+        deps.out.say(`Nothing new to send — ${app.name} is already live at ${app.url}`);
+        return;
+    }
+    deps.out.say("Sending your changes…");
+    await sendChanges(deps, link.dir, access);
+    const commit = await headCommit(deps, link.dir);
+    deps.out.say("Building your app… (this usually takes a minute)");
+    const result = await watchDeploy(deps, api, link.slug, commit);
+    report(deps, app, result);
+}
+async function watchDeploy(deps, api, slug, commit) {
+    const started = deps.now();
+    let build;
+    for (;;) {
+        const deploys = await api.deploys(slug);
+        const found = deploys.find((d) => d.commit === commit);
+        if (found) {
+            build = found;
+            if (found.status !== "building")
+                return found;
+        }
+        const waited = deps.now() - started;
+        // Before CI has opened a deploy there is nothing to watch; after it has,
+        // the clock that matters is the build's.
+        const limit = build ? BUILD_TIMEOUT_MS : BUILD_START_TIMEOUT_MS;
+        if (waited >= limit) {
+            throw new CliError(build
+                ? "Your changes were sent, but the build is taking longer than expected."
+                : "Your changes were sent, but the platform hasn't started building them.", `Watch it finish at https://console.ppleth.ai/apps/${slug}.`);
+        }
+        await deps.sleep(POLL_INTERVAL_MS);
+    }
+}
+/** How the Provisioner marks a deploy that a newer one overtook. */
+const SUPERSEDED = "superseded by a newer deploy";
+function report(deps, app, build) {
+    if (build.status === "failed") {
+        if (build.error === SUPERSEDED) {
+            throw new CliError("A newer deploy of this app replaced the one you were waiting for.", `Watch that one finish at https://console.ppleth.ai/apps/${app.slug}.`);
+        }
+        // A build that compiled badly explains itself in its log; a deploy that
+        // failed after the build — a bad bundle, a rejected upload — only has the
+        // platform's own reason, and the Builder must still be told something.
+        const detail = build.log ? tail(build.log, LOG_TAIL_LINES) : build.error;
+        if (detail) {
+            deps.out.say();
+            deps.out.say(detail);
+            deps.out.say();
+        }
+        throw new CliError(`${app.name} couldn't be built, so what's live hasn't changed.`, detail
+            ? "Show the message above to your AI coding agent — it says what to fix."
+            : `See what happened at https://console.ppleth.ai/apps/${app.slug}.`);
+    }
+    if (build.status === "unverified") {
+        deps.out.say(`${app.name} was updated, but it hasn't answered yet.`);
+        deps.out.say(`Give it a minute, then open ${app.url}`);
+        return;
+    }
+    deps.out.say(`${app.name} is live at ${app.url}`);
+}
+function tail(log, lines) {
+    return log.split("\n").slice(-lines).join("\n").trim();
+}

package/dist/commands/init.js

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "../errors.js";
+import { cloneApp, hasLocalChanges, recordChanges } from "../git.js";
+import { writeLink } from "../link.js";
+import { scaffold } from "../scaffold.js";
+import { client } from "../session.js";
+import { refreshSkills } from "../skills.js";
+/**
+ * Bring an app that already exists on the platform (ADR-0001: the Provisioner
+ * creates it, not the CLI) onto this computer, with the golden-path template
+ * in place and linked, ready for the Builder's AI agent to work in.
+ */
+export async function init(deps, options) {
+    const api = await client(deps);
+    const app = await api.app(options.slug);
+    if (!app.repo) {
+        throw new CliError(`"${app.name}" isn't finished being set up yet.`, "Wait a moment and run `pple init` again; if it stays like this, ask the platform team.");
+    }
+    if (app.status === "provisioning") {
+        deps.out.say("Your app is still being set up on the platform…");
+    }
+    const targetDir = path.resolve(deps.cwd, options.dir ?? app.slug);
+    await ensureAvailable(targetDir);
+    // The Builder's machine holds no credential of its own; the platform hands
+    // out one that opens this app's code and nothing else (ADR-0005).
+    const access = await api.repoToken(app.slug);
+    deps.out.say(`Setting up "${app.name}" in ${path.basename(targetDir)}/…`);
+    await cloneApp(deps, repoUrl(deps, app.repo), targetDir, access);
+    if (await isAlreadyBuilt(targetDir)) {
+        throw new CliError(`"${app.name}" already has code, so there's nothing to set up.`, `Work in that folder and run \`pple deploy\` to put changes live.`);
+    }
+    await scaffold(deps.templateDir, targetDir, app.slug);
+    await writeLink(targetDir, {
+        slug: app.slug,
+        apiBase: deps.config.apiBase,
+        url: app.url,
+    });
+    // Skills are a local overlay (ADR-0006), not app source — refresh before the
+    // first commit so the ignore rule is in place and Skill files stay untracked.
+    await refreshSkills(deps, targetDir);
+    if (await hasLocalChanges(deps, targetDir)) {
+        await recordChanges(deps, targetDir, "Start from the PPLE golden-path template", access);
+    }
+    report(deps, app, targetDir);
+}
+/** A repo the Builder may not have cloned before; https works with any helper. */
+function repoUrl(deps, repoFullName) {
+    return `${deps.config.repoBase}/${repoFullName}.git`;
+}
+async function ensureAvailable(targetDir) {
+    const entries = await fs.readdir(targetDir).catch(() => null);
+    if (entries === null)
+        return;
+    if (entries.length > 0) {
+        throw new CliError(`The folder ${path.basename(targetDir)}/ already has something in it.`, "Run `pple init` somewhere else, or pass `--dir <folder>` to pick another folder.");
+    }
+}
+/** A repo that already carries an app is one somebody has already set up. */
+async function isAlreadyBuilt(targetDir) {
+    return fs
+        .access(path.join(targetDir, "package.json"))
+        .then(() => true)
+        .catch(() => false);
+}
+function report(deps, app, targetDir) {
+    const folder = path.basename(targetDir);
+    deps.out.say();
+    deps.out.say(`"${app.name}" is ready to work on in ${folder}/`);
+    deps.out.say(`It will be live at ${app.url}`);
+    deps.out.say();
+    deps.out.say("Next:");
+    deps.out.say(`  cd ${folder}`);
+    deps.out.say("  npm install");
+    deps.out.say("  npm run dev        # see it on this computer");
+    deps.out.say("  pple deploy        # put it live");
+}

package/dist/commands/upgrade.js

@@ -0,0 +1,29 @@
+// `pple upgrade` — update the CLI itself, which is also how Skills and the
+// golden-path template move forward (ADR-0006). It replaces only an install
+// npm put there, never with sudo: a global folder the Builder can't write to
+// is theirs to fix, not the CLI's to force.
+import { CliError } from "../errors.js";
+import { installGlobally, isNewer, isNpmGlobalInstall, latestVersion, MANUAL_INSTALL, } from "../npm.js";
+import { announceUpdate, manualHint, sayOtherChannel } from "../update.js";
+export async function upgrade(deps) {
+    const latest = await latestVersion(deps);
+    if (latest === null) {
+        throw new CliError("Couldn't reach npm to check for a newer pple.", `Check your internet connection, or upgrade directly:\n\n  ${MANUAL_INSTALL}`);
+    }
+    if (!isNewer(latest, deps.version)) {
+        deps.out.say(`You're on the latest pple (${deps.version}).`);
+        return;
+    }
+    if (!(await isNpmGlobalInstall(deps))) {
+        announceUpdate(deps, latest);
+        deps.out.say();
+        sayOtherChannel(deps);
+        return;
+    }
+    deps.out.say(`Updating pple ${deps.version} → ${latest}…`);
+    const result = await installGlobally(deps, latest);
+    if (result.code !== 0) {
+        throw new CliError(`Couldn't update pple to ${latest}.`, manualHint(result));
+    }
+    deps.out.say(`pple is now ${latest}.`);
+}

package/dist/credentials.js

@@ -0,0 +1,53 @@
+// Where the Builder's PPLE ID tokens live between commands.
+//
+// One file, owner-readable only, outside any app repo — a token that lands in
+// a working copy is a token that gets pushed to a party-owned repo.
+import fs from "node:fs/promises";
+import path from "node:path";
+const FILE = "credentials.json";
+const OWNER_ONLY_FILE = 0o600;
+const OWNER_ONLY_DIR = 0o700;
+function credentialsPath(deps) {
+    return path.join(deps.configDir, FILE);
+}
+export async function loadCredentials(deps) {
+    const raw = await fs.readFile(credentialsPath(deps), "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.accessToken !== "string")
+        return null;
+    // A file written against another PPLE ID is as good as no file: it would
+    // only produce confusing 401s against the current one.
+    if (parsed.ssoBase !== deps.config.ssoBase)
+        return null;
+    return {
+        accessToken: parsed.accessToken,
+        refreshToken: typeof parsed.refreshToken === "string" ? parsed.refreshToken : null,
+        expiresAt: typeof parsed.expiresAt === "number" ? parsed.expiresAt : null,
+        ssoBase: parsed.ssoBase,
+    };
+}
+export async function saveCredentials(deps, credentials) {
+    await fs.mkdir(deps.configDir, { recursive: true, mode: OWNER_ONLY_DIR });
+    await fs.writeFile(credentialsPath(deps), `${JSON.stringify(credentials, null, 2)}\n`, { mode: OWNER_ONLY_FILE });
+    // mkdir/writeFile only apply the mode when they create; an existing file
+    // keeps whatever it had, so tighten it explicitly.
+    await fs.chmod(credentialsPath(deps), OWNER_ONLY_FILE);
+}
+/** Returns whether there was anything to forget. */
+export async function clearCredentials(deps) {
+    try {
+        await fs.unlink(credentialsPath(deps));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}