recess-cli 2.1.0 → 2.3.0

package/README.md

@@ -121,6 +121,24 @@ row per request. The human-only `recess ui` console is explicitly exempt and ide
 
 ## Common flow
 
+School-onboarding work is family-first: one composite view, then a loop of "what's
+next" → the suggested command → "what's next" again, with `doctor` as the
+gate-observability instrument when something is unexpectedly dark:
+
+```bash
+recess --json onboarding family <family-id> --reason "One-screen view of this school family"
+recess --json onboarding next <family-id> --reason "What should happen next for this family"
+recess --json onboarding doctor --family <family-id> --reason "Why is the school surface dark for them"
+recess --json onboarding starter-coverage --reason "Run the pre-flip coverage gate"
+recess --json onboarding backfill-trackers --reason "Census the WS-H guardian trackers"
+```
+
+`next` returns the mission-control queue's current action plus `suggestedCommands`
+with real ids substituted; every suggested write still previews and requires its
+own `--confirm`. `doctor` reports the env kill-switches, comms mode, and
+per-guardian/per-kid flag + capability-lock + cohort-gate state — its env values
+are the answering service's only (the Worker can differ).
+
 ```bash
 recess --json users search "Morgan Rivera" --reason "Find the exact student record"
 recess --json users tier get <kid-id> --reason "Inspect the student's current tier"

package/dist/api.js

@@ -142,6 +142,23 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    async uploadPartnerLogo(image, fileName, mimeType) {
+        this.requireAuth();
+        const formData = new FormData();
+        const arrayBuffer = image.buffer.slice(image.byteOffset, image.byteOffset + image.byteLength);
+        formData.append("file", new Blob([arrayBuffer], { type: mimeType }), fileName);
+        const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
+        const response = await fetch(new URL("/admin/partner/logo-upload", this.config.apiOrigin), {
+            method: "POST",
+            headers,
+            body: formData,
+        });
+        const body = await readResponseBody(response);
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
     async uploadMapTestScores(studentId, pdf, fileName) {
         this.requireAuth();
         const formData = new FormData();

package/dist/auth.js

@@ -100,6 +100,11 @@ export async function login(config, options) {
 // 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.
+//
+// The approver grants their own scope: a guardian approving yields a family-scoped session
+// over their own kids, an admin a full-admin one. That is what lets an agent running
+// anywhere — a cloud box with no browser — hold a session at all, instead of a human having
+// to be the hands for every command.
 export async function requestDeviceAuth(config, options) {
     const response = await fetch(new URL("/auth/admin-cli/device/authorize/", config.apiOrigin), {
         method: "POST",
@@ -123,11 +128,11 @@ export async function requestDeviceAuth(config, options) {
         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\`.`,
+        instructions: `Open ${authorize.approvalUrl} in a browser and approve it while signed in to Recess as the person this agent should act as — the session takes on THAT account's scope, so a guardian grants family-only access. 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),
+// Poll the device-authorization request until a human 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) {

package/dist/cli.js

@@ -9,6 +9,7 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
+import { runSchoolCommand } from "./commands/school.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
 import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
@@ -23,6 +24,52 @@ import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
 function requiredRequestReason(parsed) {
     return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
 }
+/**
+ * Role of whoever this session belongs to.
+ *
+ * The stored identity only describes an `auth login` session; an env-cookie
+ * session may belong to someone else entirely, so ask the server rather than
+ * trusting a stale login. Used by commands that must refuse *before* their
+ * confirmation gate — an approval a human grants and the server then rejects is
+ * worse than no preview at all.
+ */
+async function resolveSessionRole(api) {
+    if (api.config.authSource === "config" && api.config.user?.role) {
+        return api.config.user.role;
+    }
+    const session = await api.client.GET("/auth/admin-cli/session/");
+    return session.data?.user.role;
+}
+/** Status values `goals edit` may send. Deliberately narrow: the backend patch
+ * route is pause/resume only, and reaching the terminal state is
+ * `goals archive`, which frees an open-goal slot and writes a different audit
+ * row. */
+const EDITABLE_GOAL_STATUSES = ["ACTIVE", "PAUSED"];
+/**
+ * Reject bad enum values in a goal patch file *before* the preview is built.
+ *
+ * A preview is what a human approves, so it must not describe a write the
+ * server will refuse. Sending `{"status":"COMPLETED"}` used to preview cleanly,
+ * resolve a compare-and-set token, mint an approval token, and only then fail
+ * at confirm — spending a human approval on an impossible request.
+ */
+function assertGoalPatchValues(patch, patchFile) {
+    const status = patch.status;
+    if (status === undefined)
+        return;
+    if (typeof status !== "string" ||
+        !EDITABLE_GOAL_STATUSES.includes(status)) {
+        const archiveHint = status === "COMPLETED"
+            ? " To close out a finished course and free an open-goal slot, use `recess goals archive <goal-id> --student <kid-id>` instead — `goals edit` cannot set a terminal status."
+            : "";
+        throw new CliError("invalid_arguments", `${path.resolve(patchFile)} sets status to ${JSON.stringify(status)}, which \`goals edit\` does not accept. Allowed: ${EDITABLE_GOAL_STATUSES.join(", ")}.${archiveHint}`, 1, {
+            field: "status",
+            value: status,
+            allowed: [...EDITABLE_GOAL_STATUSES],
+            patchFile: path.resolve(patchFile),
+        });
+    }
+}
 async function sessionStatus(config) {
     if (!config.sessionCookie) {
         return {
@@ -130,7 +177,7 @@ async function writeCommand(parsed, preview, execute) {
             details: {
                 ...preview.details,
                 operationKey,
-                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation.",
+                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation. Previewing again is harmless: it mints another key that is equally valid, because keys are bound to the payload rather than to one preview run.",
             },
         };
         await appendJobEvent({
@@ -144,7 +191,7 @@ async function writeCommand(parsed, preview, execute) {
         requireConfirmation(false, boundPreview);
     }
     if (!suppliedOperationKey) {
-        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview, requiredFlag: "--operation-key" });
+        throw new CliError("confirmation_required", "A confirmed write requires --operation-key. Run this exact command without --confirm, then pass the operationKey from the preview details. Any preview of this same payload yields a usable key.", 2, { preview, requiredFlag: "--operation-key" });
     }
     assertOperationKeyMatchesPreview(suppliedOperationKey, fingerprint, preview);
     await appendJobEvent({
@@ -476,9 +523,26 @@ function approvalTokenFor(preview) {
 function operationKeyFor(fingerprint) {
     return `op_${randomUUID().replaceAll("-", "")}_${fingerprint}`;
 }
+/**
+ * An operation key is `op_<random>_<fingerprint>`, and the fingerprint is a
+ * hash of the whole preview. Only the suffix is checked, which means **any**
+ * key minted from a preview of this exact payload works — including one from an
+ * earlier preview of the same command. That matters: previewing twice mints two
+ * different keys, both valid, and reaching for the newer one is not a mistake.
+ *
+ * The suffix is also what makes the key safe. It cannot be transplanted onto a
+ * different write, because a payload that differs by one character hashes
+ * differently and no key from the old preview will match.
+ */
 function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
     if (!operationKey.endsWith(`_${fingerprint}`)) {
-        throw new CliError("approval_mismatch", "The operation key does not belong to this preview. Start from a new preview and obtain approval again.", 2, { preview, requiredFlag: "--operation-key" });
+        throw new CliError("approval_mismatch", `This operation key was minted for a different payload, so it cannot approve this one. The key must end in _${fingerprint} — copy the operationKey out of the preview for THIS exact command (any preview of the same payload will do, newest or oldest). If the payload really did change, that is the gate working: get approval on the current preview.`, 2, {
+            preview,
+            requiredFlag: "--operation-key",
+            expectedKeySuffix: `_${fingerprint}`,
+            suppliedKey: operationKey,
+            note: "Keys are bound to the payload, not to a particular preview run. Re-previewing an unchanged command mints a new key with the same suffix; every one of them is accepted.",
+        });
     }
 }
 async function requirePreviewBoundConfirmation(parsed, preview) {
@@ -508,7 +572,7 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
         throw new CliError("approval_mismatch", "The approved preview no longer matches this request. Review the current preview and rerun with --confirm --approval-token <token>.", 2, { preview: boundPreview, requiredFlag: "--approval-token" });
     }
     if (!suppliedOperationKey) {
-        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
+        throw new CliError("confirmation_required", "A confirmed write requires --operation-key. Run this exact command without --confirm, then pass the operationKey from the preview details. Any preview of this same payload yields a usable key.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
     }
     assertOperationKeyMatchesPreview(suppliedOperationKey, approvalToken, boundPreview);
     await appendJobEvent({
@@ -1156,6 +1220,14 @@ function parseGoalTemplateDocument(doc) {
         (typeof rawSortOrder !== "number" || !Number.isInteger(rawSortOrder))) {
         throw new CliError("invalid_arguments", 'Template file field "sortOrder" must be an integer.');
     }
+    const rawCoinAmount = doc.coinAmount;
+    if (rawCoinAmount !== undefined &&
+        rawCoinAmount !== null &&
+        (typeof rawCoinAmount !== "number" ||
+            !Number.isInteger(rawCoinAmount) ||
+            rawCoinAmount < 1)) {
+        throw new CliError("invalid_arguments", 'Template file field "coinAmount" must be a positive integer.');
+    }
     const kind = assertChoice(optionalDocString(doc, "kind") ?? "SIMPLE", GOAL_TEMPLATE_KINDS, "kind");
     const setupAudience = assertChoice(optionalDocString(doc, "setupAudience") ?? "KID_FRIENDLY", GOAL_TEMPLATE_SETUP_AUDIENCES, "setupAudience");
     const starterTierRaw = optionalDocString(doc, "starterTier");
@@ -1175,6 +1247,9 @@ function parseGoalTemplateDocument(doc) {
         ...(optionalDocString(doc, "imageUrl") === undefined
             ? {}
             : { imageUrl: optionalDocString(doc, "imageUrl") }),
+        ...(rawCoinAmount === undefined || rawCoinAmount === null
+            ? {}
+            : { coinAmount: rawCoinAmount }),
         ...(optionalDocString(doc, "category") === undefined
             ? {}
             : { category: optionalDocString(doc, "category") }),
@@ -2248,6 +2323,9 @@ export async function runCommand(argv) {
     if (noun === "applications" || noun === "quotes") {
         return runApplicationsCommand({ parsed, api, writeCommand });
     }
+    if (noun === "school") {
+        return runSchoolCommand({ parsed, api, writeCommand });
+    }
     if (noun === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
         if (!search)
@@ -3084,7 +3162,18 @@ export async function runCommand(argv) {
         }
         if (verb === "create") {
             const filePath = flagString(parsed, "file", { required: true });
-            const document = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            const authoredDocument = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            const coinAmountOverride = flagNumber(parsed, "coin-amount");
+            if (coinAmountOverride !== undefined &&
+                (!Number.isInteger(coinAmountOverride) || coinAmountOverride < 1)) {
+                throw new CliError("invalid_arguments", "--coin-amount must be a positive integer.");
+            }
+            const document = {
+                ...authoredDocument,
+                ...(coinAmountOverride === undefined
+                    ? {}
+                    : { coinAmount: coinAmountOverride }),
+            };
             // C3 read-only preflight, for the same reason `enrollments create` has
             // one: the consequences an approver must weigh are resolved SERVER-side.
             // Which setupHandler runs, what shape of goal students get, and which
@@ -3110,6 +3199,7 @@ export async function runCommand(argv) {
                     category: document.category ?? null,
                     tags: document.tags,
                     isStarter: document.isStarter ?? false,
+                    coinAmount: document.coinAmount ?? null,
                 },
                 details: {
                     resolvedSetupHandler: validation.setupHandler,
@@ -3206,6 +3296,11 @@ export async function runCommand(argv) {
             const tags = flagString(parsed, "tags");
             const kind = flagString(parsed, "kind");
             const sortOrder = flagNumber(parsed, "sort-order");
+            const coinAmount = flagNumber(parsed, "coin-amount");
+            if (coinAmount !== undefined &&
+                (!Number.isInteger(coinAmount) || coinAmount < 1)) {
+                throw new CliError("invalid_arguments", "--coin-amount must be a positive integer.");
+            }
             const isStarterRaw = flagString(parsed, "is-starter");
             const setupAudienceRaw = flagString(parsed, "setup-audience");
             const isStarter = isStarterRaw === undefined
@@ -3222,6 +3317,10 @@ export async function runCommand(argv) {
                 ...(flagString(parsed, "emoji")
                     ? { emoji: flagString(parsed, "emoji") }
                     : {}),
+                ...(flagString(parsed, "image-url")
+                    ? { imageUrl: flagString(parsed, "image-url") }
+                    : {}),
+                ...(coinAmount === undefined ? {} : { coinAmount }),
                 ...(flagString(parsed, "category")
                     ? { category: flagString(parsed, "category") }
                     : {}),
@@ -3259,7 +3358,7 @@ export async function runCommand(argv) {
             // shape that caused the template incident; editing an existing spec goes
             // through the guarded /ai patch path with its destructive-change token.
             if (Object.keys(body).length === 1) {
-                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --image-url, --coin-amount, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
@@ -3270,6 +3369,28 @@ export async function runCommand(argv) {
                 body,
             })));
         }
+        if (verb === "generate-image") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const current = unwrap(await api.client.GET("/ai/goal-templates/{id}", {
+                params: { path: { id } },
+            }));
+            const prompt = flagString(parsed, "prompt");
+            return writeCommand(parsed, {
+                action: "queue paid GPT-Image-2 art regeneration",
+                target: {
+                    templateId: id,
+                    slug: current.slug,
+                    title: current.title,
+                },
+                request: { prompt: prompt ?? null },
+                details: {
+                    costNote: "This queues one paid 1024×1024 GPT-Image-2 generation and replaces the template image when it finishes. New templates already generate art automatically.",
+                },
+            }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/generate-image", {
+                params: { path: { id } },
+                body: prompt ? { prompt } : {},
+            })));
+        }
         if (verb === "delete") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
@@ -3476,9 +3597,76 @@ export async function runCommand(argv) {
                 body: { studentUserId, answers },
             })));
         }
-        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
+        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|generate-image|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
     }
     if (noun === "goals" && verb !== "files" && verb !== "pdf") {
+        if (verb === "complete" || verb === "undo-completion") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const undo = verb === "undo-completion";
+            return writeCommand(parsed, {
+                action: undo
+                    ? "undo goal completion and reverse its coin reward"
+                    : "complete a goal and grant its one-time coin reward",
+                target: { goalId },
+                request: { source: "STAFF" },
+                details: undo
+                    ? {
+                        note: "Undo is refused if the student has already spent enough coins that the reward cannot be reversed.",
+                    }
+                    : undefined,
+            }, async () => unwrap(undo
+                ? await api.client.POST("/ai/goals/{goalId}/undo-completion", {
+                    params: { path: { goalId } },
+                })
+                : await api.client.POST("/ai/goals/{goalId}/complete", {
+                    params: { path: { goalId } },
+                })));
+        }
+        if (verb === "archive" || verb === "unarchive") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const reopen = verb === "unarchive";
+            const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((goal) => goal.id === goalId);
+            if (!current) {
+                throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+            }
+            // Refuse the no-op before asking a human to approve it. Approving
+            // "archive a goal" only to be told it was already archived teaches an
+            // agent to re-approve noise.
+            if (!reopen && current.status === "COMPLETED") {
+                throw new CliError("already_archived", `Goal ${goalId} ("${current.title}") is already archived and is not holding an open-goal slot.`);
+            }
+            if (reopen && current.status !== "COMPLETED") {
+                throw new CliError("not_archived", `Goal ${goalId} ("${current.title}") is ${current.status}, not archived. There is nothing to reopen.`);
+            }
+            const preview = {
+                action: reopen
+                    ? "reopen an archived goal (consumes one of the kid's open-goal slots)"
+                    : "archive a finished goal (frees one of the kid's open-goal slots)",
+                target: {
+                    goalId,
+                    studentUserId: studentId,
+                    title: current.title,
+                    status: current.status,
+                    progress: current.progress,
+                },
+                request: { goalId },
+                details: {
+                    note: reopen
+                        ? "Returns the goal to ACTIVE so it generates daily todos again. Refused with GOAL_LIMIT_REACHED if the kid is already at the open-goal cap, and refused for goals completed through the staff reward path (those need `goals undo-completion`, which reverses the coins)."
+                        : "Sets the terminal COMPLETED status. Grants no coins and posts no activity — use `goals complete` (staff only) when the kid should receive the goal's reward. The goal, its history, and its past todos all stay; only the open-goal slot is released. Any already-scheduled future todos on this goal are left alone, matching `goals complete`.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(reopen
+                ? await api.client.POST("/ai/goals/{goalId}/unarchive", {
+                    params: { path: { goalId } },
+                })
+                : await api.client.POST("/ai/goals/{goalId}/archive", {
+                    params: { path: { goalId } },
+                })));
+        }
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
             return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
@@ -3647,6 +3835,7 @@ export async function runCommand(argv) {
             const studentId = flagString(parsed, "student", { required: true });
             const patchFile = flagString(parsed, "patch-file", { required: true });
             const patch = (await readJsonFile(patchFile, "Goal patch file"));
+            assertGoalPatchValues(patch, patchFile);
             patch.delta = flagString(parsed, "delta", { required: true });
             const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId: studentId } },
@@ -3672,6 +3861,15 @@ export async function runCommand(argv) {
         if (verb === "delete") {
             const goalId = positional(parsed, 2, "goal ID");
             const studentId = flagString(parsed, "student", { required: true });
+            // Deletion is an /admin/* route, so a guardian or guide session can never
+            // complete it. Refuse here, before the preview, rather than rendering a
+            // full and entirely plausible preview — resolved goal, named title,
+            // described soft-delete — that a human approves and the server then
+            // answers 401. A preview is a promise about what --confirm will do.
+            const sessionRole = await resolveSessionRole(api);
+            if (sessionRole && sessionRole !== "ADMIN") {
+                throw new CliError("forbidden", "Deleting a goal is staff-only. To free an open-goal slot for a finished course, use `recess goals archive <goal-id> --student <kid-id>` — it sets the terminal status, keeps the goal and its history, and needs no staff involvement.", 1, { sessionRole, requiredRole: "ADMIN", alternative: "goals archive" });
+            }
             const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId: studentId } },
             })).goals.find((goal) => goal.id === goalId);
@@ -3789,7 +3987,7 @@ export async function runCommand(argv) {
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|archive|unarchive|complete|undo-completion|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {

package/dist/command-schema.js

@@ -15,6 +15,7 @@ const BOOLEAN_FLAGS = new Set([
     "full",
     "help",
     "immediate",
+    "keep-tokens",
     "include-deleted",
     "json",
     "mirrored",