recess-cli 2.2.0 → 2.4.0

package/README.md

@@ -111,7 +111,7 @@ Error or write preview:
 
 Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
 
-`recess --json agent-context` returns the canonical command/flag/positional schema. `recess --json help payout recipients` returns scoped help. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
+`recess --json agent-context` returns the canonical command/flag/positional schema filtered to the scope claim already stored in the current CLI session. Bare help, scoped help, and `agent-context` make no API request; real commands still go through server authorization, while `auth status` and `doctor` perform live session checks. `recess --json help payout recipients` returns scoped help, and human help marks exact-admin commands with `◆`. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
 
 Every command-driven request to the Recess API except `auth` requires `--reason "..."`: a
 non-empty, human-readable purpose of at most 1024 characters. The CLI sends it as
@@ -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"
@@ -231,6 +249,7 @@ recess --json students schedule --student <kid-id> --days 30 --reason "Review th
 recess --json students xp-history --student <kid-id> --range month --reason "Review recent XP history"
 recess --json goals list --student <kid-id> --reason "Review the student's goals"
 recess --json todos create --student <kid-id> --title "Read chapter 4" --reason "Add the assigned reading"
+recess --json todos complete <todo-id> --xp 35 --reason "Complete the todo with a 35 XP total reward"
 recess --json goals delete <goal-id> --student <kid-id> --reason "Remove this obsolete goal"
 recess --json todos delete <todo-id> --reason "Remove this disposable todo"
 recess --json todos generate-applet <todo-id> --student <kid-id> --reason "Generate this todo's applet"
@@ -240,7 +259,9 @@ recess --json rocky get --student <kid-id> --reason "Inspect the student's Rocky
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
-into the confirmed request. Applet generation is staff-only: it resolves the todo's latest learning
+into the confirmed request. `todos complete` is staff-only; `--xp` is the target total XP for the
+todo, so its preview reports prior credit and the new delta before the normal completion and reward
+side effects run. Applet generation is also staff-only: it resolves the todo's latest learning
 analysis, defaults the generated todo to tomorrow in the student's timezone, and lets the server
 select v1 or v2 for that student. A guardian cannot target another family, inspect frozen/deleted
 template history, choose todo rewards/completion/internal fields, or use the ADMIN-only

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

@@ -24,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 {
@@ -45,6 +91,69 @@ async function sessionStatus(config) {
     }
     return { ...result.data, authSource: config.authSource };
 }
+const DISCOVERY_ROLE_BY_SCOPE = {
+    full_admin: "ADMIN",
+    family_ai: "GUARDIAN",
+    guide_students: "GUIDE",
+    village_home: "KID",
+};
+/**
+ * Command discovery is intentionally local: the signed session cookie already
+ * carries the role, CLI scope, and expiry minted at login. Decoding those
+ * unverified claims is safe here because they only hide or reveal help text;
+ * every real command still sends the cookie to the server for authorization.
+ */
+function resolveCommandDiscovery(config) {
+    const signedOut = {
+        scope: null,
+        role: null,
+        source: "signed_out",
+    };
+    const unavailable = {
+        scope: null,
+        role: null,
+        source: "unavailable",
+    };
+    if (!config.sessionCookie)
+        return signedOut;
+    try {
+        const separator = config.sessionCookie.indexOf("=");
+        if (separator < 1)
+            return unavailable;
+        const cookieValue = decodeURIComponent(config.sessionCookie.slice(separator + 1).split(";", 1)[0]);
+        const payloadSegment = cookieValue.split(".")[1];
+        if (!payloadSegment)
+            return unavailable;
+        const value = JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return unavailable;
+        }
+        const claim = value;
+        if (typeof claim.exp !== "number" || !Number.isFinite(claim.exp)) {
+            return unavailable;
+        }
+        if (claim.exp * 1000 <= Date.now()) {
+            return signedOut;
+        }
+        const scope = typeof claim.cliScope === "string" &&
+            Object.hasOwn(DISCOVERY_ROLE_BY_SCOPE, claim.cliScope)
+            ? claim.cliScope
+            : claim.role === "ADMIN" && claim.adminCli === true
+                ? "full_admin"
+                : null;
+        if (!scope || claim.role !== DISCOVERY_ROLE_BY_SCOPE[scope]) {
+            return unavailable;
+        }
+        return {
+            scope,
+            role: DISCOVERY_ROLE_BY_SCOPE[scope],
+            source: "session_claim",
+        };
+    }
+    catch {
+        return unavailable;
+    }
+}
 async function doctor(config, reason) {
     const checks = {
         config: {
@@ -131,7 +240,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({
@@ -145,7 +254,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({
@@ -477,9 +586,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) {
@@ -509,7 +635,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({
@@ -1447,19 +1573,28 @@ export async function runCommand(argv) {
                 .map((name) => `--${name}`)
                 .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
         }
-        return { help: scopedHelp(HELP, commands, []) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, [], discovery) };
     }
     if (noun === "help" || hasFlag(parsed, "help")) {
         const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
-        return { help: scopedHelp(HELP, commands, scope) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, scope, discovery) };
     }
     validateInvocation(parsed, commands);
     if (noun === "agent-context") {
-        const profiles = await listProfiles();
+        const [profiles, config] = await Promise.all([
+            listProfiles(),
+            resolveConfig(flagString(parsed, "profile")),
+        ]);
+        const discovery = resolveCommandDiscovery(config);
         return agentContext(commands, {
             cliVersion: await readCliVersion(),
             availableProfiles: profiles.profiles.map((profile) => profile.name),
             feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+            discovery,
         });
     }
     if (noun === "profile") {
@@ -3559,6 +3694,51 @@ export async function runCommand(argv) {
                     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/", {
@@ -3727,6 +3907,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 } },
@@ -3752,6 +3933,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);
@@ -3869,7 +4059,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|complete|undo-completion|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") {
@@ -3970,6 +4160,60 @@ export async function runCommand(argv) {
                 body,
             })));
         }
+        if (verb === "complete") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const targetXp = flagNumber(parsed, "xp");
+            if (targetXp === undefined ||
+                !Number.isInteger(targetXp) ||
+                targetXp <= 0) {
+                throw new CliError("invalid_arguments", "--xp must be a positive integer. It is the target total XP credited for this todo; prior awards count toward that total.");
+            }
+            const [currentResponse, detailsResponse] = await Promise.all([
+                api.client.GET("/tutor/browser/todos/{id}/", {
+                    params: { path: { id: todoId } },
+                }),
+                api.client.GET("/admin/todos/{id}/details", {
+                    params: { path: { id: todoId } },
+                }),
+            ]);
+            const current = unwrap(currentResponse);
+            const completionXpAwarded = unwrap(detailsResponse).totalXpAwarded ?? 0;
+            if (current.status === "COMPLETED") {
+                throw new CliError("already_completed", `Todo ${todoId} ("${current.title}") is already completed with ${completionXpAwarded} completion XP credited.`);
+            }
+            const body = {
+                status: "COMPLETED",
+                xpReward: targetXp,
+                expectedUpdatedAt: current.updatedAt,
+            };
+            const newXp = Math.max(0, targetXp - completionXpAwarded);
+            const preview = {
+                action: "complete a todo through the staff reward path and set its total credited XP target",
+                target: {
+                    todoId,
+                    studentUserId: current.userId,
+                    studentName: [current.user.firstName, current.user.lastName]
+                        .filter(Boolean)
+                        .join(" ") || null,
+                    title: current.title,
+                    status: current.status,
+                    goal: current.goal,
+                },
+                request: body,
+                details: {
+                    currentXpReward: current.xpReward,
+                    alreadyAwardedXp: completionXpAwarded,
+                    targetTotalXp: targetXp,
+                    newlyAwardedXp: newXp,
+                    configuredCoinReward: current.reward,
+                    note: `The XP ledger is delta-guarded: this writes at most ${newXp} new XP so the todo reaches ${targetXp} total. Completion also claims any unawarded portion of the todo's configured ${current.reward}-coin reward, replaces its active completion analysis with a manual-completion record, records completion activity, may complete a linked goal module and its configured rewards, and may notify the parent through the normal completion pipeline.`,
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/admin/todos/{id}", {
+                params: { path: { id: todoId } },
+                body,
+            })));
+        }
         if (verb === "delete") {
             const todoId = positional(parsed, 2, "todo ID");
             const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
@@ -4038,7 +4282,7 @@ export async function runCommand(argv) {
                 body: targetDueDateISO ? { targetDueDateISO } : {},
             })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|delete|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|complete|delete|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });