recess-cli 1.9.0 → 1.9.2

package/README.md

@@ -197,13 +197,16 @@ recess --json students schedule --student <kid-id> --days 30
 recess --json students xp-history --student <kid-id> --range month
 recess --json goals list --student <kid-id>
 recess --json todos create --student <kid-id> --title "Read chapter 4"
+recess --json todos generate-applet <todo-id> --student <kid-id> [--due-date YYYY-MM-DD]
 recess --json memories context --student <kid-id>
 recess --json memories log --student <kid-id> --date 2026-08-12
 recess --json rocky get --student <kid-id>
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
-into the confirmed request. A guardian cannot target another family, inspect frozen/deleted
+into the confirmed request. Applet generation is 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
 device-authorization flow. `memories context` and `memories log` read only the tutor repository's
 spine, rules, reminders, and session logs; private guide remarks are never returned. The CLI does

package/dist/auth.js

@@ -4,12 +4,16 @@ import { randomBytes } from "node:crypto";
 import { clearPendingDeviceAuth, updateStoredConfig } from "./config.js";
 import { apiError, CliError } from "./errors.js";
 function openBrowser(url) {
+    // Windows goes through rundll32, not `cmd /c start`: cmd treats `&` (and the
+    // `%`-encoded redirect_uri) as metacharacters and chops the URL at the first
+    // `&`, so the browser only ever received `?client_id=…` and the OAuth page
+    // rejected it. rundll32 takes the URL as a single, unparsed argument.
     const command = process.platform === "darwin"
         ? "open"
         : process.platform === "win32"
-            ? "cmd"
+            ? "rundll32"
             : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
     const child = spawn(command, args, { detached: true, stdio: "ignore" });
     child.unref();
 }

package/dist/cli.js

@@ -176,10 +176,16 @@ Usage:
     [--confirm --approval-token TOKEN]
   recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
     --delta TEXT [--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]
+    [--confirm --approval-token TOKEN]
   recess [--json] todos create --student <kid-id> --title TEXT
     [--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 generate-applet <todo-id> --student <kid-id>
+    [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
   recess [--json] memories context --student <kid-id>
   recess [--json] memories log --student <kid-id> --date YYYY-MM-DD
   recess [--json] rocky get --student <kid-id>
@@ -366,6 +372,8 @@ async function writeCommand(parsed, preview, execute) {
 const GOAL_WORKSPACE_WRITE_MAX_FILES = 1_000;
 const GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
 const GOAL_PDF_UPLOAD_MAX_BYTES = 1024 * 1024 * 1024;
+const GOAL_QUEUE_MAX_ENTRIES = 500;
+const URL_QUEUE_DESCRIPTION_POINTER = "Skill queue managed by the system.";
 function approvalTokenFor(preview) {
     return createHash("sha256").update(JSON.stringify(preview)).digest("hex");
 }
@@ -691,6 +699,61 @@ async function readJsonFile(filePath, label) {
     }
     return parsed;
 }
+function parseGoalQueueEntries(value, label) {
+    if (!Array.isArray(value)) {
+        throw new CliError("invalid_arguments", `${label} must be a JSON array of queue entries.`);
+    }
+    if (value.length > GOAL_QUEUE_MAX_ENTRIES) {
+        throw new CliError("invalid_arguments", `${label} has ${value.length} entries; the maximum is ${GOAL_QUEUE_MAX_ENTRIES}.`);
+    }
+    return value.map((raw, index) => parseGoalQueueEntry(raw, `${label}[${index}]`));
+}
+function parseGoalQueueEntry(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new CliError("invalid_arguments", `${label} must be an object with title and url.`);
+    }
+    const record = value;
+    const { title, url } = record;
+    if (typeof title !== "string" || !title.trim()) {
+        throw new CliError("invalid_arguments", `${label}.title is required.`);
+    }
+    if (typeof url !== "string" || !/^https:\/\//i.test(url.trim())) {
+        throw new CliError("invalid_arguments", `${label}.url must be an https URL.`);
+    }
+    const entry = { title: title.trim(), url: url.trim() };
+    if (record.completed !== undefined) {
+        if (typeof record.completed !== "boolean") {
+            throw new CliError("invalid_arguments", `${label}.completed must be a boolean.`);
+        }
+        entry.completed = record.completed;
+    }
+    if (record.sourceMeta !== undefined) {
+        if (!record.sourceMeta ||
+            typeof record.sourceMeta !== "object" ||
+            Array.isArray(record.sourceMeta)) {
+            throw new CliError("invalid_arguments", `${label}.sourceMeta must be an object.`);
+        }
+        const meta = record.sourceMeta;
+        const sourceMeta = {};
+        for (const key of [
+            "permacode",
+            "skillId",
+            "section",
+            "subjectKey",
+            "planKey",
+        ]) {
+            const raw = meta[key];
+            if (raw === undefined)
+                continue;
+            if (typeof raw !== "string") {
+                throw new CliError("invalid_arguments", `${label}.sourceMeta.${key} must be a string.`);
+            }
+            sourceMeta[key] = raw;
+        }
+        entry.sourceMeta = sourceMeta;
+    }
+    return entry;
+}
 function contentLibrarySubmitItem(value, label) {
     const record = typeof value === "string"
         ? { url: value }
@@ -1175,6 +1238,20 @@ function flagItemDateMs(parsed) {
     }
     return ms;
 }
+function flagDateOnly(parsed, name) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return undefined;
+    const parsedDate = /^\d{4}-\d{2}-\d{2}$/.test(raw)
+        ? new Date(`${raw}T00:00:00.000Z`)
+        : null;
+    if (!parsedDate ||
+        Number.isNaN(parsedDate.getTime()) ||
+        parsedDate.toISOString().slice(0, 10) !== raw) {
+        throw new CliError("invalid_arguments", `--${name} must be a valid YYYY-MM-DD date.`);
+    }
+    return raw;
+}
 const DAY_MS = 24 * 60 * 60 * 1000;
 // The cohort event routes take zoneless local wall-clock datetimes
 // (interpreted in the cohort's timezone server-side).
@@ -3321,7 +3398,72 @@ export async function runCommand(argv) {
                 body: patch,
             }));
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|files|pdf.");
+        if (verb === "queue") {
+            const subverb = positional(parsed, 2, "queue action (get|set)");
+            const goalId = positional(parsed, 3, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            if (subverb === "get") {
+                return unwrap(await api.client.GET("/tutor/browser/students/goals/{goalId}/queue/", { params: { path: { goalId } } }));
+            }
+            if (subverb === "set") {
+                const entriesFile = flagString(parsed, "entries-file", {
+                    required: true,
+                });
+                const delta = flagString(parsed, "delta", { required: true });
+                const replaceDescriptionPointer = hasFlag(parsed, "replace-description-pointer");
+                const { absolutePath, parsed: rawEntries } = await readJsonValue(entriesFile, "Queue entries file");
+                const entries = parseGoalQueueEntries(rawEntries, "Queue entries file");
+                const goal = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                    params: { path: { userId: studentId } },
+                })).goals.find((candidate) => candidate.id === goalId);
+                if (!goal) {
+                    throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+                }
+                const current = unwrap(await api.client.GET("/tutor/browser/students/goals/{goalId}/queue/", { params: { path: { goalId } } }));
+                const currentUrls = new Set(current.queue.map((item) => item.url));
+                const proposedUrls = new Set(entries.map((entry) => entry.url));
+                const preview = {
+                    action: "replace a goal's URL skill queue for a managed student",
+                    target: { goalId, studentUserId: studentId },
+                    request: {
+                        entriesFile: absolutePath,
+                        entryCount: entries.length,
+                        delta,
+                        replaceDescriptionPointer,
+                        expectedUpdatedAt: goal.updatedAt,
+                    },
+                    details: {
+                        currentQueue: current.queue.map((item) => ({
+                            moduleRef: item.moduleRef,
+                            url: item.url,
+                            completedAt: item.completedAt,
+                        })),
+                        added: entries
+                            .filter((entry) => !currentUrls.has(entry.url))
+                            .map((entry) => entry.url),
+                        removed: current.queue
+                            .filter((item) => !proposedUrls.has(item.url))
+                            .map((item) => item.url),
+                        note: "Replaces the entire EXTERNAL_URL queue. Completion is preserved for unchanged URLs; WORKSPACE modules are untouched. Daily generation mints the head entry for a flag-on kid.",
+                    },
+                };
+                requirePreviewBoundConfirmation(parsed, preview);
+                const body = {
+                    delta,
+                    expectedUpdatedAt: goal.updatedAt,
+                    queue: entries,
+                    ...(replaceDescriptionPointer
+                        ? { description: URL_QUEUE_DESCRIPTION_POINTER }
+                        : {}),
+                };
+                return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+                    params: { path: { goalId } },
+                    body,
+                }));
+            }
+            throw new CliError("invalid_arguments", "Use goals queue get|set.");
+        }
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {
@@ -3423,7 +3565,49 @@ export async function runCommand(argv) {
                 body,
             }));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit.");
+        if (verb === "generate-applet") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const targetDueDateISO = flagDateOnly(parsed, "due-date");
+            const [todo, learningAnalysis] = await Promise.all([
+                api.client.GET("/tutor/browser/todos/{id}/", {
+                    params: { path: { id: todoId } },
+                }),
+                api.client.GET("/tutor/students/{studentId}/todos/{todoId}/learning-analysis", {
+                    params: { path: { studentId, todoId } },
+                }),
+            ]);
+            const currentTodo = unwrap(todo);
+            if (currentTodo.userId !== studentId) {
+                throw new CliError("not_found", "The todo does not belong to the requested student.");
+            }
+            const analysis = unwrap(learningAnalysis).analysis;
+            if (!analysis) {
+                throw new CliError("not_found", "This todo does not have a learning analysis to generate an applet from.");
+            }
+            const preview = {
+                action: "generate an applet from a student's todo analysis",
+                target: {
+                    studentUserId: studentId,
+                    todoId,
+                    todoTitle: currentTodo.title,
+                    analysisId: analysis.id,
+                },
+                request: {
+                    targetDueDateISO: targetDueDateISO ?? null,
+                },
+                details: {
+                    dueDate: targetDueDateISO ?? "tomorrow in the student's timezone",
+                    versionRouting: "The server evaluates applet-gen-v2 for this student and uses v1 when the flag is off or its evaluation fails.",
+                },
+            };
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
+                params: { path: { analysisId: analysis.id } },
+                body: targetDueDateISO ? { targetDueDateISO } : {},
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use todos create|edit|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });

package/package.json

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