recess-cli 2.2.0 → 2.4.0

package/dist/commands/school.js

@@ -1,3 +1,6 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { unwrap } from "../api.js";
 import { flagList, flagString, hasFlag } from "../args.js";
 import { CliError } from "../errors.js";
@@ -9,6 +12,7 @@ const SCHOOL_TIERS = [
     "complete",
     "platform",
 ];
+const PROGRAM_TYPES = ["PARTNER", "SCHOOL"];
 const RESOLVE_ACTIONS = ["waive", "cancel"];
 const RECONCILIATION_OUTCOMES = ["refunded", "kept", "written_off"];
 /** post.start-memberships.ts caps the body at ten kids per call. */
@@ -16,6 +20,38 @@ const MEMBERSHIP_KID_LIMIT = 10;
 function dollars(cents) {
     return `$${(cents / 100).toFixed(2)}`;
 }
+/** The exact type set post.partner-logo-upload.ts accepts, keyed by extension. */
+const LOGO_MIME_BY_EXT = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+async function readLogoFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const mimeType = LOGO_MIME_BY_EXT[path.extname(absolutePath).toLowerCase()];
+    if (!mimeType) {
+        throw new CliError("invalid_arguments", "--file must be a .png, .jpg, .jpeg, .gif, .webp, or .svg image.");
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `Logo file does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    return {
+        bytes,
+        fileName: path.basename(absolutePath),
+        mimeType,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
 function kidName(firstName, lastName, fallback) {
     return [firstName, lastName].filter(Boolean).join(" ") || fallback;
 }
@@ -460,6 +496,232 @@ export async function runSchoolCommand({ parsed, api, writeCommand, }) {
         }
         throw new CliError("invalid_arguments", "Use school codes list|get|create|set-kids|replace|resend|revoke.");
     }
+    if (verb === "create") {
+        const slug = flagString(parsed, "slug", { required: true });
+        const name = flagString(parsed, "name", { required: true });
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", {
+            required: true,
+            min: 0,
+        });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpCents = flagInteger(parsed, "token-topup-cents", {
+            min: 0,
+            max: 10_000_000,
+        });
+        if (programType === "SCHOOL" && tokenTopUpCents !== creditGrant) {
+            throw new CliError("invalid_arguments", "SCHOOL programs require --token-topup-cents equal to --credit-grant (the server enforces the same rule).");
+        }
+        const body = {
+            slug,
+            name,
+            defaultInitialCreditGrant: creditGrant,
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        return writeCommand(parsed, {
+            action: `create the ${programType ?? "PARTNER"}-program institution "${name}" (${slug})`,
+            target: { slug },
+            request: body,
+            details: {
+                moneyLevers: {
+                    defaultInitialCreditGrant: creditGrant,
+                    monthlyTokenTopUpCents: tokenTopUpCents ?? null,
+                    warning: "For SCHOOL programs the monthly target tops EVERY kid in the institution up to it on the next cron run — these numbers spend real money at scale.",
+                },
+                duplicateGuard: "A taken slug 409s; pick another rather than retrying.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/", { body })));
+    }
+    if (verb === "update") {
+        const institutionId = positional(parsed, 2, "institution ID");
+        const slug = flagString(parsed, "slug");
+        const name = flagString(parsed, "name");
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", { min: 0 });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpRaw = flagString(parsed, "token-topup-cents");
+        const tokenTopUpCents = tokenTopUpRaw === undefined
+            ? undefined
+            : tokenTopUpRaw === "none"
+                ? null
+                : flagInteger(parsed, "token-topup-cents", {
+                    min: 0,
+                    max: 10_000_000,
+                });
+        const body = {
+            ...(slug ? { slug } : {}),
+            ...(name ? { name } : {}),
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(creditGrant !== undefined
+                ? { defaultInitialCreditGrant: creditGrant }
+                : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        if (Object.keys(body).length === 0) {
+            throw new CliError("invalid_arguments", "Pass at least one field to change (--slug, --name, --logo-url, --credit-grant, --program-type, --token-topup-cents).");
+        }
+        const touchesMoney = creditGrant !== undefined ||
+            tokenTopUpCents !== undefined ||
+            programType !== undefined;
+        return writeCommand(parsed, {
+            action: touchesMoney
+                ? "edit this institution INCLUDING a money lever or the program type (exact-ADMIN only)"
+                : "edit this institution's descriptive metadata (name/slug/logo)",
+            target: { institutionId },
+            request: body,
+            details: {
+                ...(touchesMoney
+                    ? {
+                        moneyWarning: "defaultInitialCreditGrant / monthlyTokenTopUpCents / programType are money levers: the monthly target tops EVERY kid up to it on the next cron. A GUIDE or PROGRAM session gets 403 for these fields.",
+                    }
+                    : {}),
+                ...(programType
+                    ? {
+                        programTypeGuard: "A type flip is refused while families are attached or unused invite codes exist — resolve those first.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{id}", {
+            params: { path: { id: institutionId } },
+            body,
+        })));
+    }
+    if (verb === "representatives") {
+        const subverb = parsed.positionals[2] ?? "";
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/representatives", {
+                params: { path: { slug: requireSlug() } },
+            }));
+        }
+        if (subverb === "search") {
+            const q = flagString(parsed, "query", { required: true });
+            return unwrap(await api.client.GET("/admin/partner/representatives/search", {
+                params: { query: { q } },
+            }));
+        }
+        if (subverb === "add") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            // Resolve the exact person first so the approval names who gains the
+            // representative surface, not a bare id.
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId } },
+            }));
+            return writeCommand(parsed, {
+                action: "add this GUIDE/ADMIN as a representative of the institution",
+                target: {
+                    slug,
+                    userId,
+                    name: kidName(user.firstName, user.lastName, userId),
+                    role: user.role,
+                },
+                request: { userId },
+                details: {
+                    refusal: "Non-GUIDE/ADMIN users are refused by the server.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/representatives", {
+                params: { path: { slug } },
+                body: { userId },
+            })));
+        }
+        if (subverb === "remove") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            return writeCommand(parsed, {
+                action: "remove this representative from the institution",
+                target: { slug, userId },
+                request: {},
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/representatives/{userId}", { params: { path: { slug, userId } } })));
+        }
+        throw new CliError("invalid_arguments", "Use school representatives list|search|add|remove.");
+    }
+    if (verb === "credit-transactions") {
+        const slug = requireSlug();
+        const page = flagInteger(parsed, "page", { min: 0 });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/credit-transactions", {
+            params: {
+                path: { slug },
+                query: {
+                    ...(page !== undefined ? { page } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            },
+        }));
+    }
+    if (verb === "kid-slots") {
+        const kidId = positional(parsed, 2, "kid ID");
+        const slug = requireSlug();
+        const slotsRaw = flagString(parsed, "slots", { required: true });
+        const concurrentClassSlots = slotsRaw === "unlimited"
+            ? null
+            : flagInteger(parsed, "slots", { min: 0 });
+        const premiumClassSlots = flagInteger(parsed, "premium-slots", {
+            min: 0,
+            max: 20,
+        });
+        const body = {
+            concurrentClassSlots,
+            ...(premiumClassSlots !== undefined ? { premiumClassSlots } : {}),
+        };
+        return writeCommand(parsed, {
+            action: "set this school kid's concurrent class slots directly (the raw slot override — `users tier set` is the tier-driven path)",
+            target: { kidId, slug },
+            request: body,
+            details: {
+                slots: concurrentClassSlots ?? "unlimited",
+                ...(premiumClassSlots !== undefined
+                    ? { premiumSlots: premiumClassSlots }
+                    : {}),
+                note: "SCHOOL-program kids only; the write re-checks membership under the family lock so it cannot race a concurrent revert.",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/kids/{kidId}/slots", {
+            params: { path: { slug, kidId } },
+            body,
+        })));
+    }
+    if (verb === "partner-family") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const enabledRaw = flagString(parsed, "enabled", { required: true });
+        const enabled = assertChoice(enabledRaw, ["true", "false"], "--enabled") ===
+            "true";
+        return writeCommand(parsed, {
+            action: enabled
+                ? "attach this family to the PARTNER institution"
+                : "detach this family from the PARTNER institution",
+            target: { familyId, slug },
+            request: { enabled },
+            details: {
+                scope: "PARTNER programs only — the server refuses SCHOOL institutions here, because school families carry entitlements this generic toggle cannot safely provision or remove (use `school convert`/`school revert`).",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/families/{familyId}", {
+            params: { path: { slug, familyId } },
+            body: { enabled },
+        })));
+    }
+    if (verb === "logo-upload") {
+        const filePath = flagString(parsed, "file", { required: true });
+        const { bytes, fileName, mimeType, sha256 } = await readLogoFile(filePath);
+        return writeCommand(parsed, {
+            action: "upload this image to the assets CDN as a partner-institution logo (returns a URL for `school create/update --logo-url`)",
+            target: { fileName },
+            request: { fileName, mimeType, bytes: bytes.byteLength, sha256 },
+        }, async () => api.uploadPartnerLogo(bytes, fileName, mimeType));
+    }
     throw new CliError("invalid_arguments", "Unknown school command. Run `recess school --help` for the current command list.");
 }
 //# sourceMappingURL=school.js.map

package/dist/help.js

@@ -133,6 +133,11 @@ Usage:
     [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
   recess [--json] onboarding timeline <family-id>
   recess [--json] onboarding readiness <family-id>
+  recess [--json] onboarding family <family-id>
+  recess [--json] onboarding next <family-id>
+  recess [--json] onboarding doctor [--family <family-id>]
+  recess [--json] onboarding starter-coverage
+  recess [--json] onboarding backfill-trackers [--apply] [--confirm]
   recess [--json] onboarding active-tutors <family-id>
   recess [--json] onboarding meetings <family-id>
   recess [--json] onboarding cohort-options <family-id> [--kid <kid-id>]
@@ -223,6 +228,24 @@ Usage:
     --data-file <invite.json> [--confirm]
   recess [--json] school codes resend <code-id> --school <institution-slug> [--confirm]
   recess [--json] school codes revoke <code-id> --school <institution-slug> [--confirm]
+  recess [--json] school create --slug <slug> --name TEXT --credit-grant N
+    [--logo-url URL] [--program-type PARTNER|SCHOOL] [--token-topup-cents N] [--confirm]
+  recess [--json] school update <institution-id> [--slug <slug>] [--name TEXT]
+    [--logo-url URL] [--credit-grant N] [--program-type PARTNER|SCHOOL]
+    [--token-topup-cents N] [--confirm]
+  recess [--json] school representatives list --school <institution-slug>
+  recess [--json] school representatives search --query TEXT
+  recess [--json] school representatives add --school <institution-slug>
+    --user <user-id> [--confirm]
+  recess [--json] school representatives remove --school <institution-slug>
+    --user <user-id> [--confirm]
+  recess [--json] school credit-transactions --school <institution-slug>
+    [--page 0] [--limit 50]
+  recess [--json] school kid-slots <kid-id> --school <institution-slug>
+    --slots N [--premium-slots N] [--confirm]
+  recess [--json] school partner-family <family-id> --school <institution-slug>
+    --enabled true|false [--confirm]
+  recess [--json] school logo-upload --file </path/logo.png> [--confirm]
   recess [--json] village models list [--world village-1] [--query TEXT] [--archived]
   recess [--json] village models upload --file </path/model.glb>
     [--world village-1] [--name TEXT] [--id ID] [--description TEXT] [--tags A,B]
@@ -309,6 +332,10 @@ Usage:
     [--confirm --approval-token TOKEN]
   recess [--json] goals complete <goal-id> [--confirm]
   recess [--json] goals undo-completion <goal-id> [--confirm]
+  recess [--json] goals archive <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
+  recess [--json] goals unarchive <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
   recess [--json] goals queue get <goal-id> --student <kid-id>
   recess [--json] goals queue set <goal-id> --student <kid-id>
     --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -317,6 +344,8 @@ Usage:
     [--due-date YYYY-MM-DD] [--estimated-minutes N] [--url URL] [--confirm]
   recess [--json] todos edit <todo-id> --patch-file <path/patch.json>
     [--confirm --approval-token TOKEN]
+  recess [--json] todos complete <todo-id> --xp N
+    [--confirm --approval-token TOKEN]
   recess [--json] todos delete <todo-id>
     [--confirm --approval-token TOKEN]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>
@@ -366,6 +395,26 @@ the backend's own dryRun before the gate and previews the per-student outcome.
 409s STALE_WRITE and writes nothing. The spec is unreachable from "set-metadata"
 by design — an existing spec is edited only through the guarded /ai patch path.
 
+School-onboarding workflow notes: "onboarding family" is the one-screen view
+(status + readiness + next action + intake session + active tutors, in
+parallel; flag-gated pieces degrade to a labeled "unavailable"). "onboarding
+next" returns the mission-control queue's current action for the family PLUS
+suggestedCommands — the exact commands that perform it, ids substituted.
+"onboarding doctor" answers "who actually sees the school-onboarding surface
+and why": the env kill-switches (SCHOOL_ONBOARDING_V1_FORCE,
+SCHOOL_ONBOARDING_CUTOVER), comms master switch + mode, the acting staffer's
+flag evaluation, and per-guardian/per-kid flag, capability-lock, and
+cohort-gate state; env values are the answering service's only — the Worker
+can differ. "onboarding starter-coverage" is the read-only pre-flip gate
+(ok:false = do not flip the flag). "onboarding backfill-trackers" is the WS-H
+census (read-only); --apply re-takes the census as the preview and stamps only
+the arm-1 guardians, exact-ADMIN, re-derived under a per-guardian lock
+server-side. "school create/update" carry money levers
+(--credit-grant/--token-topup-cents/--program-type spend real money via the
+monthly top-up cron and are exact-ADMIN on update); descriptive edits
+(name/slug/logo) are ordinary staff writes. "school kid-slots" is the raw
+slot override; "users tier set" is the tier-driven path.
+
 Onboarding notes: "status" and "intake-session" are reads — "intake-session"
 looks up the current IN_PROGRESS session without creating one (prints a "none
 yet" result when absent). "intake-session-create" is the explicit write that
@@ -392,9 +441,11 @@ endDate minus one day) and shows the computed date in the preview.
 Auth notes: "auth login" runs the browser loopback flow for ADMIN, GUIDE, a GUARDIAN with
 access:ai, or a KID using only Village home building. Guardian sessions are family-scoped and
 cannot call /admin; KID sessions cannot call any non-Village API command. For a headless
-cloud agent, the ADMIN-only "auth request" prints an approval URL to hand a Recess admin; after they
-approve it in a browser, "auth poll" collects the 12h session. When it lapses, run
-"auth request" again for a fresh link. Both paths yield the same session.
+cloud agent that has no local browser to open, "auth request" prints an approval URL; whoever
+opens it and approves in a signed-in web session grants THEIR OWN scope, so a guardian approving
+mints a family-scoped session and only an admin can mint a full-admin one. "auth poll" then
+collects the 12h session. Kids cannot approve. When it lapses, run "auth request" again for a
+fresh link. Both paths yield the same session.
 
 Skill notes: this CLI's own agent skill ships inside the npm package AND is served
 by the server, so wording/Gotcha updates arrive without an npm release. "setup"

package/dist/http.js

@@ -3,6 +3,44 @@ export const RECESS_CLIENT_HEADER = "x-recess-client";
 export const RECESS_CLIENT_CLI = "cli";
 export const RECESS_CLIENT_CLI_UI = "cli-ui";
 export const RECESS_REASON_HEADER = "x-recess-reason";
+/**
+ * Set alongside the reason when it had to be percent-encoded to survive the
+ * header. The server decodes only when this is present, so a literal `%` in an
+ * all-ASCII reason is never mangled.
+ */
+export const RECESS_REASON_ENCODING_HEADER = "x-recess-reason-encoding";
+export const RECESS_REASON_ENCODING_UTF8 = "utf-8-percent";
+const ASCII_PRINTABLE = /^[\x20-\x7E]*$/;
+/**
+ * Make a human-written reason safe to put in an HTTP header.
+ *
+ * Headers are ByteStrings: any code point above U+00FF throws
+ * "Cannot convert argument to a ByteString because the character at index N
+ * has a value of 8212" — 8212 being an em dash. The error names no field, so
+ * the failure looks like a bug in whatever command you happened to run, and
+ * typing an em dash or a curly quote in `--reason` is completely ordinary.
+ *
+ * Common typography is folded to its ASCII equivalent so the audit log stays
+ * readable; anything still non-ASCII (accented names, CJK, emoji) is
+ * UTF-8 percent-encoded and flagged for the server to decode, which is lossless.
+ */
+export function encodeReasonHeader(reason) {
+    const folded = reason
+        // Typography first, so the audit log keeps a readable reason instead of a
+        // percent-escaped one. These are what people actually type.
+        .replace(/[\u2010-\u2015\u2212]/g, "-") // hyphens, en/em dashes, minus
+        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+        .replace(/\u2026/g, "...")
+        .replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ")
+        .replace(/[\u200B-\u200D\uFEFF]/g, "");
+    if (ASCII_PRINTABLE.test(folded))
+        return { value: folded };
+    return {
+        value: encodeURIComponent(folded),
+        encoding: RECESS_REASON_ENCODING_UTF8,
+    };
+}
 export function requireCliRequestReason(value) {
     const reason = value?.trim();
     if (!reason) {
@@ -15,8 +53,13 @@ export function requireCliRequestReason(value) {
 }
 export function markCliRequest(headers, reason, client = RECESS_CLIENT_CLI) {
     headers.set(RECESS_CLIENT_HEADER, client);
-    if (reason)
-        headers.set(RECESS_REASON_HEADER, reason);
+    if (reason) {
+        const encoded = encodeReasonHeader(reason);
+        headers.set(RECESS_REASON_HEADER, encoded.value);
+        if (encoded.encoding) {
+            headers.set(RECESS_REASON_ENCODING_HEADER, encoded.encoding);
+        }
+    }
     return headers;
 }
 export function cliRequestHeaders(init, reason, client = RECESS_CLIENT_CLI) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -33,14 +33,17 @@ recess --json skills admin get recess-admin --all-references --reason "Load staf
 
 Use `skills guardian list` or `skills admin list` when the needed skill is not obvious. Never substitute one audience for the other. A guardian session cannot fetch the admin catalog; an admin may fetch either catalog.
 
-For machine-readable discovery, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
+For machine-readable discovery filtered to the current session's locally decoded CLI scope, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. These discovery commands make no API request; `auth status` and `doctor` are the live session checks. Human help uses `◇` for shared commands and `◆` for exact-admin commands. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
 
 ## Authentication
 
 - Workstation: `recess --json auth login` opens Recess SSO.
-- Headless device authorization is staff-only: `auth request`, human approval, then `auth poll`.
-- Sessions last 12 hours and are rechecked against the live user role and permissions.
-- `auth status` inspects the current session; `auth logout` clears the stored session.
+- Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
+  Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
+  grants family-only access, not staff access. Kids cannot approve.
+- Sessions last 12 hours. `auth status` and `doctor` recheck the live user role and permissions;
+  discovery stays local and may reflect the minted scope until the next login.
+- `auth logout` clears the stored session.
 - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.
 
 Never print or paste session cookies, device codes, or config-file contents.

package/skill/recess-cli/agents/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.3.0",
-  "minCliVersion": "2.1.0"
+  "version": "2.5.0",
+  "minCliVersion": "2.4.0"
 }