recess-cli 3.3.1 → 3.4.0

package/dist/api.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import createClient from "openapi-fetch";
 import { apiError, CliError } from "./errors.js";
-import { cliRequestHeaders, markCliRequest, RECESS_CLIENT_CLI, } from "./http.js";
+import { cliRequestHeaders, markCliRequest, noteServerCliVersions, RECESS_CLIENT_CLI, } from "./http.js";
 const idempotencyContext = new AsyncLocalStorage();
 export function withIdempotencyContext(context, execute) {
     return idempotencyContext.run(context, execute);
@@ -40,6 +40,10 @@ export class RecessAdminApi {
                 applyIdempotencyHeaders(request.headers);
                 return request;
             },
+            onResponse({ response }) {
+                noteServerCliVersions(response.headers);
+                return response;
+            },
         });
     }
     requireAuth() {
@@ -55,6 +59,7 @@ export class RecessAdminApi {
         const response = await fetch(new URL(path, this.config.apiOrigin), {
             headers: cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag),
         });
+        noteServerCliVersions(response.headers);
         const text = await response.text();
         let body = text;
         try {

package/dist/args.js

@@ -6,6 +6,7 @@ import { CliError } from "./errors.js";
  */
 export const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
 const BOOLEAN_FLAGS = new Set([
+    "clear",
     "zero-balance",
     "allow-assigned-edits",
     "all-references",

package/dist/cli.js

@@ -21,7 +21,8 @@ import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
 import { HELP } from "./help.js";
 export { HELP };
-import { cliRequestHeaders, requireCliRequestReason } from "./http.js";
+import { cliRequestHeaders, noteServerCliVersions, requireCliRequestReason, } from "./http.js";
+import { runSelfUpdate, UPGRADE_COMMAND, updateNoticeText, updateStatus, } from "./update-notice.js";
 import { requireConfirmation } from "./safety.js";
 import { installSkill, isEphemeralInstall, readBundledSkillVersion, readCliVersion, } from "./setup.js";
 import { compareVersions, updateSkillFromServer } from "./skill-update.js";
@@ -174,6 +175,7 @@ async function doctor(config, reason) {
             headers: cliRequestHeaders(undefined, reason),
             signal: AbortSignal.timeout(5000),
         });
+        noteServerCliVersions(response.headers);
         checks.api = { reachable: response.ok, status: response.status };
     }
     catch (error) {
@@ -183,6 +185,9 @@ async function doctor(config, reason) {
         };
     }
     checks.skill = await skillStatus(config, reason);
+    const update = updateStatus(await readCliVersion());
+    const updateAction = updateNoticeText(update);
+    checks.update = updateAction ? { ...update, action: updateAction } : update;
     return checks;
 }
 /**
@@ -1438,6 +1443,19 @@ function parseGoalTemplateDocument(doc) {
  * Resolve a template reference that may be a UUID or a slug. Slugs are what an
  * author types and what the skill's prose uses; the routes take a UUID only.
  */
+/**
+ * `/challenges-v2/{id}/preview` on the web app: the template as the card a
+ * kid would see, with no chat around it. Returned by `goal-templates get`
+ * and `create` so an agent can open it, or hand it to the human, right after
+ * authoring.
+ */
+function goalTemplatePreviewUrl(webOrigin, templateId) {
+    return new URL(`/challenges-v2/${encodeURIComponent(templateId)}/preview`, webOrigin).toString();
+}
+/** Runs the template with Rocky as a kid would (staff only; ephemeral, never touches real todos). */
+function goalTemplatePlayTestUrl(webOrigin, templateId) {
+    return new URL(`/challenges-v2/${encodeURIComponent(templateId)}?play=1`, webOrigin).toString();
+}
 async function resolveGoalTemplateId(api, reference) {
     if (UUID_RE.test(reference))
         return reference;
@@ -1910,7 +1928,11 @@ export async function executeRecessCommand(argv, options = {}) {
         }
     }
     const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
-    const requestReason = noun === "auth" ? undefined : requiredRequestReason(parsed);
+    const requestReason = noun === "auth"
+        ? undefined
+        : noun === "update"
+            ? requireCliRequestReason(flagString(parsed, "reason") ?? "check for a recess CLI update")
+            : requiredRequestReason(parsed);
     if (noun === "doctor" && isRemote) {
         return {
             transport: "streamable-http-mcp",
@@ -1922,6 +1944,31 @@ export async function executeRecessCommand(argv, options = {}) {
     }
     if (noun === "doctor")
         return doctor(config, requestReason);
+    if (noun === "update") {
+        if (isRemote) {
+            throw new CliError("remote_command_unavailable", "The update command is not exposed by the hosted Recess CLI.");
+        }
+        const cliVersion = await readCliVersion();
+        const probe = await fetch(new URL("/health", config.apiOrigin), {
+            headers: cliRequestHeaders(undefined, requestReason),
+            signal: AbortSignal.timeout(5000),
+        }).catch(() => null);
+        if (probe)
+            noteServerCliVersions(probe.headers);
+        const status = updateStatus(cliVersion);
+        if (status.state === "current")
+            return { ...status, updated: false };
+        if (isEphemeralInstall()) {
+            throw new CliError("invalid_arguments", "This recess is running from a temporary npx cache. Run `npx recess-cli@latest` or install it with `npm install -g recess-cli@latest`.");
+        }
+        requireConfirmation(hasFlag(parsed, "confirm"), {
+            action: "install the latest recess CLI globally with npm",
+            target: { ...status },
+            request: { command: UPGRADE_COMMAND },
+        });
+        const result = await runSelfUpdate();
+        return { ...status, updated: true, ...result };
+    }
     if (noun === "setup") {
         // Always lay down the bundled copy first: it is the floor, and it is the
         // only copy guaranteed to match this binary. The served upgrade below is
@@ -2484,6 +2531,145 @@ export async function executeRecessCommand(argv, options = {}) {
             body,
         })));
     }
+    if (noun === "users" && verb === "school") {
+        const action = parsed.positionals[2];
+        const userId = positional(parsed, 3, "user ID");
+        if (action === "status")
+            return unwrap(await api.client.GET("/admin/users/{userId}/school-status", {
+                params: { path: { userId } },
+            }));
+        if (action === "history")
+            return unwrap(await api.client.GET("/admin/users/{userId}/school-history", {
+                params: {
+                    path: { userId },
+                    query: {
+                        limit: flagNumber(parsed, "limit"),
+                        cursor: flagNumber(parsed, "cursor"),
+                    },
+                },
+            }));
+        if (action === "complete-action") {
+            const actionId = positional(parsed, 4, "action ID");
+            const body = { reason: flagString(parsed, "note", { required: true }) };
+            return writeCommand(parsed, {
+                action: "record verified provider cancellation or deactivation; does not contact the provider",
+                target: { userId, actionId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/users/{userId}/school-actions/{actionId}/complete", { params: { path: { userId, actionId } }, body })));
+        }
+        const status = action === "withdraw" ? "WITHDRAWN" : "ACTIVE";
+        const tierId = action === "restore"
+            ? assertChoice(flagString(parsed, "tier", { required: true }), SCHOOL_TIER_IDS, "--tier")
+            : undefined;
+        const body = {
+            status,
+            reason: flagString(parsed, "note", { required: true }),
+            expectedUpdatedAt: flagString(parsed, "expected-updated-at", {
+                required: true,
+            }),
+            ...(tierId ? { tierId } : {}),
+        };
+        return writeCommand(parsed, {
+            action: status === "WITHDRAWN"
+                ? "withdraw SCHOOL student, cancel subscriptions immediately without refund, and revoke external learning access"
+                : "restore Recess access; billing, classes, and external accounts are not restarted",
+            target: { userId },
+            request: body,
+            details: status === "WITHDRAWN"
+                ? {
+                    cancelSubscriptionsImmediately: true,
+                    refunds: false,
+                    revokeExternalAccess: true,
+                    ixlRemoval: "nightly roster import",
+                    manualProviderFollowUpMayBeRequired: true,
+                }
+                : { restartsBilling: false, restoresExternalAccounts: false },
+        }, async () => unwrap(await api.client.PATCH("/admin/users/{userId}/school-status", {
+            params: { path: { userId } },
+            body,
+        })));
+    }
+    if (noun === "users" && verb === "enrollment") {
+        if (parsed.positionals[2] === "set-partner-school-cc") {
+            const school = positional(parsed, 3, "partner school ID or slug");
+            const email = flagString(parsed, "email");
+            const clear = hasFlag(parsed, "clear");
+            if (!!email === clear) {
+                throw new CliError("invalid_arguments", "Specify either --email <address> or --clear.");
+            }
+            const { schools } = unwrap(await api.client.GET("/admin/users/enrollment-partner-schools"));
+            const partnerSchool = schools.find((entry) => entry.id === school || entry.slug === school);
+            if (!partnerSchool)
+                throw new CliError("invalid_arguments", "Unknown partner school. Use users enrollment list-partner-schools.");
+            const body = {
+                communicationsCcEmail: email?.trim().toLowerCase() ?? null,
+            };
+            return writeCommand(parsed, {
+                action: "set partner school communications CC",
+                target: {
+                    id: partnerSchool.id,
+                    slug: partnerSchool.slug,
+                    name: partnerSchool.name,
+                },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/users/enrollment-partner-schools/{schoolId}/communications", {
+                params: { path: { schoolId: partnerSchool.id } },
+                body,
+            })));
+        }
+        if (parsed.positionals[2] === "history") {
+            const userId = positional(parsed, 3, "user ID");
+            return unwrap(await api.client.GET("/admin/users/{userId}/enrollment-history", {
+                params: {
+                    path: { userId },
+                    query: {
+                        limit: flagNumber(parsed, "limit"),
+                        cursor: flagNumber(parsed, "cursor"),
+                    },
+                },
+            }));
+        }
+        if (parsed.positionals[2] === "list-partner-schools") {
+            return unwrap(await api.client.GET("/admin/users/enrollment-partner-schools"));
+        }
+        const userId = positional(parsed, 3, "user ID");
+        const entities = {
+            "online-learning-program": "ONLINE_LEARNING_PROGRAM",
+            "recess-academy-school": "RECESS_ACADEMY_SCHOOL",
+            "partner-school": "PARTNER_SCHOOL",
+            unset: null,
+        };
+        const entity = assertChoice(flagString(parsed, "entity", { required: true }), [
+            "online-learning-program",
+            "recess-academy-school",
+            "partner-school",
+            "unset",
+        ], "--entity");
+        const partner = flagString(parsed, "partner-school");
+        if ((entity === "partner-school") !== !!partner) {
+            throw new CliError("invalid_arguments", "--partner-school is required only with --entity partner-school.");
+        }
+        const schools = partner
+            ? unwrap(await api.client.GET("/admin/users/enrollment-partner-schools"))
+                .schools
+            : [];
+        const partnerSchool = schools.find((school) => school.id === partner || school.slug === partner);
+        if (partner && !partnerSchool) {
+            throw new CliError("invalid_arguments", "Unknown partner school. Use users enrollment list-partner-schools to find its ID or slug.");
+        }
+        const body = {
+            enrollmentEntity: entities[entity],
+            enrollmentPartnerSchoolId: partnerSchool?.id ?? null,
+        };
+        return writeCommand(parsed, {
+            action: "set user enrollment entity",
+            target: { userId, partnerSchool: partnerSchool ?? null },
+            request: body,
+        }, async () => unwrap(await api.client.PATCH("/admin/users/{userId}/enrollment-entity", {
+            params: { path: { userId } },
+            body,
+        })));
+    }
     if (noun === "users" && verb === "get") {
         const userId = positional(parsed, 2, "user ID");
         return unwrap(await api.client.GET("/admin/users/{userId}", {
@@ -3708,7 +3894,13 @@ export async function executeRecessCommand(argv, options = {}) {
                     setupWorkflowSpec: template.setupWorkflowSpec,
                 };
             }
-            return template;
+            // The card a kid would see, with no chat around it: the page to open
+            // (or hand to the human) after authoring.
+            return {
+                ...template,
+                previewUrl: goalTemplatePreviewUrl(config.webOrigin, template.id),
+                playTestUrl: goalTemplatePlayTestUrl(config.webOrigin, template.id),
+            };
         }
         if (verb === "versions") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3800,9 +3992,16 @@ export async function executeRecessCommand(argv, options = {}) {
                     specInventory: validation.totals,
                     note: "Setup mode is DETERMINISTIC_WORKFLOW and is one-way: this template can never be converted back to a chat-driven setup.",
                 },
-            }, async () => unwrap(await api.client.POST("/ai/goal-templates/", {
-                body: document,
-            })));
+            }, async () => {
+                const created = unwrap(await api.client.POST("/ai/goal-templates/", {
+                    body: document,
+                }));
+                return {
+                    ...created,
+                    previewUrl: goalTemplatePreviewUrl(config.webOrigin, created.id),
+                    playTestUrl: goalTemplatePlayTestUrl(config.webOrigin, created.id),
+                };
+            });
         }
         if (verb === "policy") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));

package/dist/command-schema.js

@@ -135,6 +135,7 @@ const LOCAL_COMMAND_NOUNS = new Set([
     "jobs",
     "profile",
     "setup",
+    "update",
 ]);
 const AUTHENTICATED_COMMAND_PREFIXES = [
     "village build",

package/dist/help.js

@@ -17,6 +17,7 @@ Usage:
   recess [--json] agent-context
   recess [--json] setup [--skill-only]
   recess [--json] doctor
+  recess [--json] update [--confirm]
   recess [--json] profile list
   recess [--json] profile show <name>
   recess [--json] profile save <name> [--api-origin URL] [--web-origin URL]
@@ -34,6 +35,18 @@ Usage:
   recess [--json] auth status|logout
   recess [--json] users search <name-or-id> [--limit 10]
   recess [--json] users get <user-id>
+  recess [--json] users school complete-action <user-id> <action-id> --note <text> [--confirm]
+  recess [--json] users school status <user-id>
+  recess [--json] users school history <user-id> [--limit 25] [--cursor <id>]
+  recess [--json] users school withdraw <user-id> --note <text> --expected-updated-at <iso> [--confirm]
+  recess [--json] users school restore <user-id> --tier <tier-id> --note <text> --expected-updated-at <iso> [--confirm]
+  recess [--json] users enrollment history <user-id> [--limit 25] [--cursor <id>]
+  recess [--json] users enrollment set-partner-school-cc <school-id-or-slug>
+    [--email <address> | --clear] [--confirm]
+  recess [--json] users enrollment list-partner-schools
+  recess [--json] users enrollment set <user-id>
+    --entity online-learning-program|recess-academy-school|partner-school|unset
+    [--partner-school <school-id-or-slug>] [--confirm]
   recess [--json] users lock <user-id> [--confirm]
   recess [--json] users unlock <user-id> [--confirm]
   recess [--json] users disable <user-id> [--whole-family] [--allow-billing] [--confirm]

package/dist/http.js

@@ -10,6 +10,25 @@ export const RECESS_REASON_HEADER = "x-recess-reason";
  */
 export const RECESS_REASON_ENCODING_HEADER = "x-recess-reason-encoding";
 export const RECESS_REASON_ENCODING_UTF8 = "utf-8-percent";
+export const RECESS_CLI_VERSION_HEADER = "x-recess-cli-version";
+export const RECESS_CLI_LATEST_HEADER = "x-recess-cli-latest";
+export const RECESS_CLI_MINIMUM_HEADER = "x-recess-cli-minimum";
+let requestCliVersion;
+const observedCliVersions = {};
+export function setRequestCliVersion(version) {
+    requestCliVersion = version;
+}
+export function noteServerCliVersions(headers) {
+    const latest = headers.get(RECESS_CLI_LATEST_HEADER)?.trim();
+    const minimum = headers.get(RECESS_CLI_MINIMUM_HEADER)?.trim();
+    if (latest)
+        observedCliVersions.latest = latest;
+    if (minimum)
+        observedCliVersions.minimum = minimum;
+}
+export function serverCliVersions() {
+    return { ...observedCliVersions };
+}
 const ASCII_PRINTABLE = /^[\x20-\x7E]*$/;
 /**
  * Make a human-written reason safe to put in an HTTP header.
@@ -53,6 +72,8 @@ export function requireCliRequestReason(value) {
 }
 export function markCliRequest(headers, reason, client = RECESS_CLIENT_CLI) {
     headers.set(RECESS_CLIENT_HEADER, client);
+    if (requestCliVersion)
+        headers.set(RECESS_CLI_VERSION_HEADER, requestCliVersion);
     if (reason) {
         const encoded = encodeReasonHeader(reason);
         headers.set(RECESS_REASON_HEADER, encoded.value);

package/dist/index.js

@@ -4,6 +4,9 @@ import { parseArgs } from "./args.js";
 import { runCommand } from "./cli.js";
 import { deliverJson } from "./delivery.js";
 import { CliError } from "./errors.js";
+import { setRequestCliVersion } from "./http.js";
+import { readCliVersion } from "./setup.js";
+import { printUpdateNotice } from "./update-notice.js";
 async function withInteractiveAdmissionStage(args) {
     const parsed = parseArgs(args);
     if (parsed.flags.has("json") ||
@@ -41,6 +44,8 @@ async function withInteractiveAdmissionStage(args) {
 const argv = await withInteractiveAdmissionStage(process.argv.slice(2));
 const parsedArgv = parseArgs(argv);
 const json = parsedArgv.flags.has("json");
+const cliVersion = await readCliVersion();
+setRequestCliVersion(cliVersion);
 // The interactive console owns the terminal, so it runs before the JSON
 // envelope machinery rather than through it.
 if (argv[0] === "ui") {
@@ -103,4 +108,7 @@ catch (error) {
     }
     process.exitCode = cliError.exitCode;
 }
+if (parsedArgv.positionals[0] !== "update") {
+    await printUpdateNotice(cliVersion);
+}
 //# sourceMappingURL=index.js.map

package/dist/update-notice.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultConfigPath } from "./config.js";
+import { CliError } from "./errors.js";
+import { serverCliVersions } from "./http.js";
+import { compareVersions } from "./skill-update.js";
+export const UPGRADE_COMMAND = "npm install -g recess-cli@latest";
+const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export function updateStatus(cliVersion, versions = serverCliVersions()) {
+    const { latest, minimum } = versions;
+    if (minimum && compareVersions(cliVersion, minimum) < 0) {
+        return { state: "required", cliVersion, latest, minimum };
+    }
+    if (!latest)
+        return { state: "unknown", cliVersion };
+    if (compareVersions(cliVersion, latest) < 0) {
+        return { state: "available", cliVersion, latest, minimum };
+    }
+    return { state: "current", cliVersion, latest };
+}
+export function updateNoticeText(status) {
+    if (status.state === "required") {
+        return `Warning: recess ${status.cliVersion} is older than the minimum supported version ${status.minimum}, so some commands may fail. Update with \`recess update --confirm\` or \`${UPGRADE_COMMAND}\`.`;
+    }
+    if (status.state === "available") {
+        return `recess ${status.latest} is available (you have ${status.cliVersion}). Update with \`recess update --confirm\` or \`${UPGRADE_COMMAND}\`.`;
+    }
+    return null;
+}
+function noticeStampPath() {
+    return path.join(path.dirname(defaultConfigPath()), "update-notice.json");
+}
+async function recentlyNotified(latest) {
+    try {
+        const stamp = JSON.parse(await fs.readFile(noticeStampPath(), "utf8"));
+        if (stamp.latest !== latest || !stamp.notifiedAt)
+            return false;
+        return Date.now() - Date.parse(stamp.notifiedAt) < NOTICE_INTERVAL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+async function recordNotice(latest) {
+    try {
+        await fs.mkdir(path.dirname(noticeStampPath()), { recursive: true });
+        await fs.writeFile(noticeStampPath(), JSON.stringify({ latest, notifiedAt: new Date().toISOString() }));
+    }
+    catch {
+        return;
+    }
+}
+export async function printUpdateNotice(cliVersion, write = (text) => process.stderr.write(text)) {
+    if (process.env.RECESS_CLI_NO_UPDATE_NOTICE === "1")
+        return;
+    const status = updateStatus(cliVersion);
+    const text = updateNoticeText(status);
+    if (!text)
+        return;
+    if (status.state === "available") {
+        if (await recentlyNotified(status.latest))
+            return;
+        await recordNotice(status.latest);
+    }
+    write(`\n${text}\n`);
+}
+export async function runSelfUpdate() {
+    const [bin, ...args] = UPGRADE_COMMAND.split(" ");
+    const exitCode = await new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            stdio: ["ignore", process.stderr, process.stderr],
+            shell: process.platform === "win32",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 1));
+    }).catch((error) => {
+        throw new CliError("update_failed", `Could not run \`${UPGRADE_COMMAND}\`: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    if (exitCode !== 0) {
+        throw new CliError("update_failed", `\`${UPGRADE_COMMAND}\` exited with code ${exitCode}. Run it yourself to see the full npm output; a permissions error usually means the global npm directory needs sudo or a Node version manager.`);
+    }
+    return { command: UPGRADE_COMMAND, exitCode };
+}
+//# sourceMappingURL=update-notice.js.map

package/package.json

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

package/skill/recess-cli/SKILL.md

@@ -107,6 +107,9 @@ prompts a model for them.
   findings — fix them and publish again. Both commands wait for the result (`--no-wait` to return the
   build id and poll with `apps status`).
 - `recess --json apps pull <project-id> [dir]` downloads a project you own to keep editing it.
+- A published `appUrl` is also a valid goal queue entry (`goals queue set`, or a template's
+  external practice queue): each app becomes one module. Build interactive content this way rather
+  than linking a chat artifact the kid cannot open inside Recess.
 - `recess --json apps standards "<words or notation>"` finds the CCSS standard for `manifest.json`
   (`"grade 4 adding fractions"` → `4.NF.B.3a`…); guides rarely know the codes, look them up.