recess-cli 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# Recess CLI
+
+`recess-cli` is the typed, agent-friendly command layer for Recess staff operations. It uses the web-server OpenAPI document, authenticates admins through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
+
+## Install (staff — no checkout needed)
+
+Published to npm as [`recess-cli`](https://www.npmjs.com/package/recess-cli). On any machine with Node 20+:
+
+```bash
+npm install -g recess-cli
+recess setup
+```
+
+`setup` installs the bundled skill for both Codex and Claude and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
+
+Publishing is a manual GitHub Action (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR, then run the workflow. It publishes with `pnpm`, not `npm`, because the manifest uses the workspace `catalog:` protocol for `openapi-fetch` and only pnpm rewrites it to a real range in the tarball.
+
+## Install (from a checkout — CLI development)
+
+From the monolith root:
+
+```bash
+pnpm install
+pnpm --dir apps/admin-cli run client:generate
+pnpm --dir apps/admin-cli run install-persistent
+```
+
+`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops).
+
+## One-time SSO setup
+
+Create an approved `OAuthClient` row in each Recess environment. This remains a manual security operation. Configure:
+
+- `name`: `Recess Admin CLI`
+- `approved`: `true`
+- `adminCliEnabled`: `true`
+- `jwtSecret`: a new secret
+- `redirectUris`: exactly `http://127.0.0.1:8765/callback`
+- `defaultlaunchUrl`: leave `null`; the CLI constructs and opens the Recess OAuth URL itself
+
+The production row ID (`c7e34138-18f9-45b1-a2fb-26a4e3a6d739`) is the CLI's built-in default, so production login needs no client-ID setup. `--client-id`, `RECESS_CLI_OAUTH_CLIENT_ID`, and a stored client ID remain overrides for local/staging clients. The web-server decodes the assertion audience, loads that exact `OAuthClient`, and requires both `approved` and `adminCliEnabled`; there is no separate server environment allowlist. Production redirect validation is exact, so a different callback port must also be explicitly registered.
+
+The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess admin session at `~/.recess-cli/config.json` with mode `0600`.
+
+```bash
+recess --json auth login
+recess --json doctor
+```
+
+## JSON contract
+
+With `--json`, stdout contains only one JSON object.
+
+Success:
+
+```json
+{"ok":true,"data":{"results":[]}}
+```
+
+Error or write preview:
+
+```json
+{"ok":false,"error":{"code":"confirmation_required","message":"...","details":{"preview":{},"requiredFlag":"--confirm"}}}
+```
+
+Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
+
+## Common flow
+
+```bash
+recess --json users search "Morgan Rivera"
+recess --json users tier get <kid-id>
+recess --json users tier preview <kid-id> --tier lite --slots 1
+recess --json students upload-map-scores --student <kid-id> --file /path/to/map-report.pdf
+recess --json enrollments list --user <kid-id>
+recess --json subscriptions list --family <family-id> --kid <kid-id>
+recess --json invoices list --subscription <subscription-id>
+```
+
+Preview a write by omitting `--confirm`:
+
+```bash
+recess --json billing pause --subscription <subscription-id> --until 2026-09-01
+```
+
+After a human approves that exact preview, rerun the unchanged command with `--confirm`.
+
+School tier writes require the `updatedAt` token from `users tier get`. Their read-only preflight
+shows `capabilitiesLockedNow`/`capabilitiesLockedAfter`, the resolved class allowance, current
+`slotsUsed`, and whether the change would strand registrations. Stranding is refused unless the
+human explicitly approves the exceptional `--allow-strand` override.
+
+MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing tutor-dashboard extraction route.
+
+See `recess --help` for the complete P0 command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/api.js

@@ -0,0 +1,120 @@
+import createClient from "openapi-fetch";
+import { apiError, CliError } from "./errors.js";
+export class RecessAdminApi {
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        this.client = createClient({
+            baseUrl: config.apiOrigin,
+            headers: config.sessionCookie
+                ? { cookie: config.sessionCookie }
+                : undefined,
+        });
+    }
+    requireAuth() {
+        if (!this.config.sessionCookie) {
+            throw new CliError("auth_required", "No admin session found. Run `recess auth login`.");
+        }
+    }
+    async rawGet(path) {
+        this.requireAuth();
+        if (!path.startsWith("/") || path.startsWith("//")) {
+            throw new CliError("invalid_arguments", "Raw request paths must start with one '/'.");
+        }
+        const response = await fetch(new URL(path, this.config.apiOrigin), {
+            headers: { cookie: this.config.sessionCookie },
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Preserve a non-JSON API response as text.
+        }
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+    async villageRequest(path, options = {}) {
+        this.requireAuth();
+        const response = await fetch(new URL(path, this.config.apiOrigin), {
+            method: options.method ?? "GET",
+            headers: {
+                cookie: this.config.sessionCookie,
+                ...(options.body === undefined
+                    ? {}
+                    : { "content-type": "application/json" }),
+            },
+            ...(options.body === undefined
+                ? {}
+                : { body: JSON.stringify(options.body) }),
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Preserve a non-JSON bridge response as text.
+        }
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+    async uploadVillageModel(worldId, file, fileName, metadata) {
+        this.requireAuth();
+        const form = new FormData();
+        for (const [key, value] of Object.entries(metadata)) {
+            if (value !== undefined)
+                form.set(key, String(value));
+        }
+        const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+        form.set("file", new Blob([arrayBuffer], { type: "model/gltf-binary" }), fileName);
+        const response = await fetch(new URL(`/admin/village/models/upload?worldId=${encodeURIComponent(worldId)}`, this.config.apiOrigin), {
+            method: "POST",
+            headers: { cookie: this.config.sessionCookie },
+            body: form,
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Preserve a non-JSON bridge response as text.
+        }
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+    async uploadMapTestScores(studentId, pdf, fileName) {
+        this.requireAuth();
+        const formData = new FormData();
+        formData.append("file", new Blob([pdf], { type: "application/pdf" }), fileName);
+        const response = await fetch(new URL(`/tutor/students/${encodeURIComponent(studentId)}/map-test-scores/upload`, this.config.apiOrigin), {
+            method: "POST",
+            headers: { cookie: this.config.sessionCookie },
+            body: formData,
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Preserve a non-JSON API response as text.
+        }
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+}
+export function unwrap(result) {
+    if (!result.response.ok || result.data === undefined) {
+        throw apiError(result.response.status, result.error);
+    }
+    return result.data;
+}
+//# sourceMappingURL=api.js.map

package/dist/args.js

@@ -0,0 +1,71 @@
+import { CliError } from "./errors.js";
+const BOOLEAN_FLAGS = new Set([
+    "allow-strand",
+    "cancel-subscriptions",
+    "archived",
+    "confirm",
+    "full",
+    "help",
+    "immediate",
+    "mirrored",
+    "no-collision",
+    "json",
+    "restore",
+    "revoke",
+    "send-email",
+    "visual-only",
+]);
+export function parseArgs(args) {
+    const positionals = [];
+    const flags = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        const equalsAt = value.indexOf("=");
+        if (equalsAt > 2) {
+            flags.set(value.slice(2, equalsAt), value.slice(equalsAt + 1));
+            continue;
+        }
+        const name = value.slice(2);
+        if (BOOLEAN_FLAGS.has(name)) {
+            flags.set(name, true);
+            continue;
+        }
+        const next = args[index + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(name, next);
+            index += 1;
+        }
+        else {
+            flags.set(name, true);
+        }
+    }
+    return { positionals, flags };
+}
+export function flagString(parsed, name, options = {}) {
+    const value = parsed.flags.get(name);
+    if (value === true) {
+        throw new CliError("invalid_arguments", `--${name} requires a value.`);
+    }
+    if (value === undefined && options.required) {
+        throw new CliError("invalid_arguments", `Missing required --${name}.`);
+    }
+    return value;
+}
+export function flagNumber(parsed, name) {
+    const value = flagString(parsed, name);
+    if (value === undefined)
+        return undefined;
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        throw new CliError("invalid_arguments", `--${name} must be a number.`);
+    }
+    return number;
+}
+export function hasFlag(parsed, name) {
+    return parsed.flags.has(name);
+}
+//# sourceMappingURL=args.js.map

package/dist/auth.js

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { clearPendingDeviceAuth, updateStoredConfig } from "./config.js";
+import { apiError, CliError } from "./errors.js";
+function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+}
+export function waitForSsoCallback(port, expectedState) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new CliError("auth_timeout", "Timed out waiting for Recess SSO."));
+        }, 5 * 60 * 1000);
+        const server = createServer((request, response) => {
+            const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                response.writeHead(404).end("Not found");
+                return;
+            }
+            const state = url.searchParams.get("state");
+            if (state !== expectedState) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Invalid Recess admin CLI sign-in callback.");
+                return;
+            }
+            const oauthError = url.searchParams.get("error");
+            if (oauthError) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Recess admin CLI sign-in was denied.");
+                clearTimeout(timeout);
+                server.close();
+                reject(new CliError("auth_failed", `SSO login was denied: ${oauthError}.`));
+                return;
+            }
+            const token = url.searchParams.get("token");
+            if (!token) {
+                response.writeHead(400, { "content-type": "text/plain" });
+                response.end("Invalid Recess admin CLI sign-in callback.");
+                return;
+            }
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            response.end("<!doctype html><title>Recess admin CLI</title><p>Signed in. You can close this tab and return to the terminal.</p>");
+            clearTimeout(timeout);
+            server.close();
+            resolve(token);
+        });
+        server.once("error", (error) => {
+            clearTimeout(timeout);
+            reject(new CliError("callback_unavailable", `Could not listen on 127.0.0.1:${port}: ${error.message}`));
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+export async function login(config, options) {
+    const state = randomBytes(24).toString("base64url");
+    const redirectUri = `http://127.0.0.1:${options.callbackPort}/callback`;
+    const authorizeUrl = new URL("/oauth", config.webOrigin);
+    authorizeUrl.searchParams.set("client_id", options.oauthClientId);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("type", "sso");
+    const callback = waitForSsoCallback(options.callbackPort, state);
+    openBrowser(authorizeUrl.toString());
+    const assertion = await callback;
+    const response = await fetch(new URL("/auth/admin-cli/exchange/", config.apiOrigin), {
+        method: "POST",
+        headers: { authorization: `Bearer ${assertion}` },
+    });
+    const body = (await response.json());
+    if (!response.ok)
+        throw apiError(response.status, body);
+    const pair = response.headers.get("set-cookie")?.split(";", 1)[0];
+    if (!pair?.includes("=")) {
+        throw new CliError("auth_failed", "The Recess API did not return an admin session cookie.");
+    }
+    const exchange = body;
+    await updateStoredConfig({
+        apiOrigin: config.apiOrigin,
+        webOrigin: config.webOrigin,
+        oauthClientId: options.oauthClientId,
+        sessionCookie: pair,
+        sessionExpiresAt: exchange.expiresAt,
+        user: exchange.user,
+    });
+    return exchange;
+}
+// Start the headless (device-authorization) sign-in. Non-blocking: it stores the secret
+// device code locally and returns the approval URL for the agent to surface to a human, who
+// approves it in a browser. The agent then calls `pollDeviceAuth` to collect the session.
+export async function requestDeviceAuth(config, options) {
+    const response = await fetch(new URL("/auth/admin-cli/device/authorize/", config.apiOrigin), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(options.label ? { label: options.label } : {}),
+    });
+    const body = (await response.json());
+    if (!response.ok)
+        throw apiError(response.status, body);
+    const authorize = body;
+    await updateStoredConfig({
+        apiOrigin: config.apiOrigin,
+        webOrigin: config.webOrigin,
+        pendingDeviceCode: authorize.deviceCode,
+        pendingUserCode: authorize.userCode,
+        pendingApprovalUrl: authorize.approvalUrl,
+        pendingExpiresAt: authorize.expiresAt,
+    });
+    return {
+        approvalUrl: authorize.approvalUrl,
+        userCode: authorize.userCode,
+        expiresAt: authorize.expiresAt,
+        interval: authorize.interval,
+        instructions: `Open ${authorize.approvalUrl} in a browser, approve as a Recess admin, then run \`recess auth poll\`.`,
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Poll the device-authorization request until an admin approves it (then store the session),
+// or it is denied / expires / the timeout elapses. On a plain timeout the pending request is
+// preserved so the agent can call `auth poll` again after the human approves.
+export async function pollDeviceAuth(config, options) {
+    const deviceCode = config.pendingDeviceCode;
+    if (!deviceCode) {
+        throw new CliError("auth_required", "No pending sign-in. Run `recess auth request` first.");
+    }
+    const intervalMs = options.intervalMs ?? 5000;
+    const deadline = Date.now() + options.timeoutMs;
+    const pendingExpiry = config.pendingExpiresAt
+        ? Date.parse(config.pendingExpiresAt)
+        : undefined;
+    for (;;) {
+        const response = await fetch(new URL("/auth/admin-cli/device/token/", config.apiOrigin), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ deviceCode }),
+        });
+        const body = (await response.json());
+        if (!response.ok) {
+            await clearPendingDeviceAuth();
+            throw apiError(response.status, body);
+        }
+        const token = body;
+        if (token.status === "approved") {
+            const pair = response.headers.get("set-cookie")?.split(";", 1)[0];
+            if (!pair?.includes("=")) {
+                throw new CliError("auth_failed", "The Recess API approved the request but did not return a session cookie.");
+            }
+            const exchange = {
+                success: true,
+                expiresAt: token.expiresAt ?? "",
+                user: token.user,
+            };
+            await updateStoredConfig({
+                apiOrigin: config.apiOrigin,
+                webOrigin: config.webOrigin,
+                sessionCookie: pair,
+                sessionExpiresAt: exchange.expiresAt,
+                user: exchange.user,
+            });
+            await clearPendingDeviceAuth();
+            return exchange;
+        }
+        if (token.status === "denied") {
+            await clearPendingDeviceAuth();
+            throw new CliError("auth_failed", "The sign-in request was denied.");
+        }
+        if (token.status === "expired" || token.status === "consumed") {
+            await clearPendingDeviceAuth();
+            throw new CliError("auth_failed", token.status === "expired"
+                ? "The sign-in request expired. Run `recess auth request` again."
+                : "The sign-in request was already used. Run `recess auth request` again.");
+        }
+        // status === "pending": wait and retry, unless we would run past the deadline
+        // or the request's own expiry.
+        const nextTick = Date.now() + intervalMs;
+        if (nextTick >= deadline || (pendingExpiry && nextTick >= pendingExpiry)) {
+            throw new CliError("auth_timeout", "Timed out waiting for approval. Approve the link, then run `recess auth poll`.");
+        }
+        await sleep(intervalMs);
+    }
+}
+//# sourceMappingURL=auth.js.map