recess-cli 2.6.0 → 2.7.0

package/README.md

@@ -274,7 +274,10 @@ 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 goals restore <goal-id> --student <kid-id> --reason "Restore this goal"
 recess --json todos delete <todo-id> --reason "Remove this disposable todo"
+recess --json todos restore <todo-id> --reason "Restore this todo"
+recess --json todos generate-learning-analysis <todo-id> --reason "Backfill this todo's missing learning analysis"
 recess --json todos generate-applet <todo-id> --student <kid-id> --reason "Generate this todo's applet"
 recess --json memories context --student <kid-id> --reason "Review durable tutor context"
 recess --json memories log --student <kid-id> --date 2026-08-12 --reason "Review the learning log for this date"
@@ -286,7 +289,12 @@ into the confirmed request. `todos complete` is staff-only; `--xp` is the target
 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
+select v1 or v2 for that student. Learning-analysis generation is ADMIN-only and queues the
+idempotent forensic pipeline from the latest completed Gemini analysis without rerunning completion
+or rewards. Goal and todo deletion is soft-only. Restoring a goal retains its Mesa workspace,
+rechecks open-goal capacity, and restores only linked todos sharing that deletion's tombstone;
+standalone todo restore uses the same preview-bound tombstone check. 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/cli.js

@@ -36,9 +36,6 @@ function requiredRequestReason(parsed) {
  * 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;
 }
@@ -4086,7 +4083,7 @@ export async function runCommand(argv) {
             // 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" });
+                throw new CliError("forbidden", "Deleting a goal is admin-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 } },
@@ -4104,7 +4101,7 @@ export async function runCommand(argv) {
                 },
                 request: { expectedUpdatedAt: current.updatedAt },
                 details: {
-                    note: "Soft-deletes the goal and its current/future dated todos. Historical todos and the deletion audit remain available.",
+                    note: "Soft-deletes the goal and its current/future dated todos. Historical todos, the deletion audit, and any Mesa workspace remain available; `goals restore` reverses this tombstone.",
                 },
             };
             return previewBoundWrite(parsed, preview, async () => {
@@ -4114,6 +4111,39 @@ export async function runCommand(argv) {
                 return { deleted: true, goalId, studentUserId: studentId };
             });
         }
+        if (verb === "restore") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const sessionRole = await resolveSessionRole(api);
+            if (sessionRole && sessionRole !== "ADMIN") {
+                throw new CliError("forbidden", "Restoring a deleted goal is admin-only.", 1, { sessionRole, requiredRole: "ADMIN" });
+            }
+            const state = unwrap(await api.client.GET("/admin/browser/students/goals/{goalId}/deletion-state/", { params: { path: { goalId } } }));
+            if (state.userId !== studentId) {
+                throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+            }
+            if (!state.deletedAt) {
+                throw new CliError("not_deleted", `Goal ${goalId} is not deleted.`);
+            }
+            if (!state.restorable) {
+                throw new CliError("restore_unavailable", state.restoreBlockedReason ?? "This goal cannot be restored safely.");
+            }
+            const body = { expectedDeletedAt: state.deletedAt };
+            const preview = {
+                action: "restore a soft-deleted goal for a managed student",
+                target: {
+                    goalId,
+                    studentUserId: studentId,
+                    title: state.title,
+                    status: state.status,
+                },
+                request: body,
+                details: {
+                    note: "Clears the goal tombstone and restores only linked todos that were tombstoned by the same goal deletion. Restoring an ACTIVE or PAUSED goal rechecks the student's open-goal capacity.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/admin/browser/students/goals/{goalId}/restore/", { params: { path: { goalId } }, body })));
+        }
         if (verb === "queue") {
             const subverb = positional(parsed, 2, "queue action (get|set)");
             const goalId = positional(parsed, 3, "goal ID");
@@ -4205,7 +4235,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|archive|unarchive|complete|undo-completion|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {
@@ -4397,7 +4427,7 @@ export async function runCommand(argv) {
                 params: { path: { id: todoId } },
             }));
             const preview = {
-                action: "permanently delete a todo for a managed student",
+                action: "soft-delete a todo for a managed student",
                 target: {
                     todoId,
                     studentUserId: current.userId,
@@ -4411,13 +4441,91 @@ export async function runCommand(argv) {
                     creationSource: current.creationSource,
                     creationSourceId: current.creationSourceId,
                     url: "url" in current ? current.url : null,
-                    note: "Hard-deletes this todo without awarding XP or running todo-completion side effects. This is permanent; use it only when the preview identifies a disposable todo with no work to preserve.",
+                    note: "Sets deletedAt without awarding XP or running todo-completion side effects. The todo, its work evidence, and related records remain available; `todos restore` reverses the tombstone.",
                 },
             };
             return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.DELETE("/admin/todos/{id}/", {
                 params: { path: { id: todoId } },
             })));
         }
+        if (verb === "restore") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const state = unwrap(await api.client.GET("/admin/todos/{id}/deletion-state", {
+                params: { path: { id: todoId } },
+            }));
+            if (!state.deletedAt) {
+                throw new CliError("not_deleted", `Todo ${todoId} is not deleted.`);
+            }
+            if (state.goal?.deletedAt) {
+                throw new CliError("restore_parent_goal", `Todo ${todoId} belongs to deleted goal ${state.goal.id}. Restore the goal instead so its deletion set is reversed together.`);
+            }
+            const body = { expectedDeletedAt: state.deletedAt };
+            const preview = {
+                action: "restore a soft-deleted todo for a managed student",
+                target: {
+                    todoId,
+                    studentUserId: state.userId,
+                    title: state.title,
+                    status: state.status,
+                    goalId: state.goal?.id ?? null,
+                },
+                request: body,
+                details: {
+                    dueDate: state.dueDate,
+                    note: "Clears deletedAt only when the tombstone still matches this preview. All preserved work evidence and related records become visible with the todo again.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/admin/todos/{id}/restore", {
+                params: { path: { id: todoId } },
+                body,
+            })));
+        }
+        if (verb === "generate-learning-analysis") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const sessionRole = await resolveSessionRole(api);
+            if (sessionRole !== "ADMIN") {
+                throw new CliError("forbidden", "Generating a learning analysis is admin-only.", 1, { sessionRole: sessionRole ?? null, requiredRole: "ADMIN" });
+            }
+            const [todoResponse, detailsResponse, geminiResponse] = 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 } },
+                }),
+                api.client.GET("/admin/todos/{id}/gemini-analysis", {
+                    params: { path: { id: todoId } },
+                }),
+            ]);
+            const currentTodo = unwrap(todoResponse);
+            const details = unwrap(detailsResponse);
+            const gemini = unwrap(geminiResponse);
+            const latestCompletedGeminiAnalysis = gemini.newPipelineAnalyses.find((analysis) => analysis.status === "completed");
+            if (!latestCompletedGeminiAnalysis) {
+                throw new CliError("not_found", "This todo does not have a completed Gemini analysis to use.");
+            }
+            const body = {
+                geminiAnalysisId: latestCompletedGeminiAnalysis.id,
+            };
+            const preview = {
+                action: "queue a learning analysis from a todo's latest completed Gemini analysis",
+                target: {
+                    todoId,
+                    studentUserId: currentTodo.userId,
+                    title: currentTodo.title,
+                    status: currentTodo.status,
+                },
+                request: body,
+                details: {
+                    existingLearningAnalysisId: details.learningAnalysis?.id ?? null,
+                    note: "The forensic learning pipeline is idempotent for this Gemini analysis. The command does not rerun completion or change rewards.",
+                },
+            };
+            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/learning-pipeline/{todoId}/start/", {
+                params: { path: { todoId } },
+                body,
+            })));
+        }
         if (verb === "generate-applet") {
             const todoId = positional(parsed, 2, "todo ID");
             const studentId = flagString(parsed, "student", { required: true });
@@ -4459,7 +4567,7 @@ export async function runCommand(argv) {
                 body: targetDueDateISO ? { targetDueDateISO } : {},
             })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|complete|delete|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|complete|delete|restore|generate-learning-analysis|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });

package/dist/command-schema.js

@@ -199,6 +199,7 @@ const STAFF_COMMANDS = new Set([
     "students upload-map-scores",
     "todos complete",
     "todos delete",
+    "todos restore",
     "todos generate-applet",
     "users get",
     "users tier list-tiers",

package/dist/commands/onboarding.js

@@ -152,6 +152,31 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 },
             }));
         }
+        if (verb === "rearm-kid-first-run") {
+            const kidUserId = positional(parsed, 2, "kid ID");
+            const preview = unwrap(await api.client.GET("/admin/onboarding/kids/{kidUserId}/first-run/rearm", { params: { path: { kidUserId } } }));
+            const body = {
+                expectedCompletedAt: preview.kidFirstRunCompletedAt,
+            };
+            return writeCommand(parsed, {
+                action: preview.alreadyEligible
+                    ? "leave the kid's native first-run onboarding rearmed (it is already eligible)"
+                    : "rearm the kid's Rocky-guided native first-run onboarding",
+                target: {
+                    kidUserId: preview.kid.id,
+                    familyId: preview.kid.familyId,
+                    name: personName(preview.kid.firstName, preview.kid.lastName, preview.kid.id),
+                    email: preview.kid.email,
+                },
+                request: body,
+                details: {
+                    currentKidFirstRunCompletedAt: preview.kidFirstRunCompletedAt,
+                    changes: ["User.kidFirstRunCompletedAt → null"],
+                    retained: "Profile, todos, goals, XP, family/enrollment state, and Village progress are unchanged. A partial prior first run resumes from its existing durable progress.",
+                    prerequisite: "The kid-onboarding feature flag must evaluate true for this kid separately.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/kids/{kidUserId}/first-run/rearm", { params: { path: { kidUserId } }, body })));
+        }
         if (verb === "timeline") {
             const familyId = positional(parsed, 2, "family ID");
             return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/timeline", {

package/dist/commands/village-events.js

@@ -2,6 +2,7 @@ import { unwrap } from "../api.js";
 import { flagString, hasFlag } from "../args.js";
 import { apiError, CliError } from "../errors.js";
 const NONE = "—";
+const WEEKDAYS = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
 async function fetchTemplatesAndRooms(ctx) {
     const [templatesResponse, rooms] = await Promise.all([
         ctx.api.client.GET("/recess/event-templates-editable/"),
@@ -17,6 +18,17 @@ function schedule(template) {
         return template.singleEventDate.slice(0, 10);
     return template.rrule || NONE;
 }
+function templateDays(template) {
+    if (template.singleEventDate)
+        return null;
+    const match = /BYDAY=([A-Z,]+)/.exec(template.rrule);
+    if (!match)
+        return null;
+    const days = match[1]
+        .split(",")
+        .filter((day) => WEEKDAYS.includes(day));
+    return days.length > 0 ? days : null;
+}
 function renderColumns(rows) {
     const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
     return rows
@@ -45,7 +57,7 @@ async function listEvents(ctx) {
         };
     });
     const unlinkedRooms = rooms
-        .filter((room) => !room.linkedTemplateId)
+        .filter((room) => room.bookings.length === 0)
         .map((room) => ({ id: room.id, name: room.name }));
     if (hasFlag(ctx.parsed, "json")) {
         return { templates: templateRows, unlinkedRooms };
@@ -97,14 +109,22 @@ async function linkEvent(ctx) {
         throw new CliError("not_found", `No editable event template found for ${templateId}. Run \`recess village events\` to list them.`);
     }
     let room;
+    let informationalBookings = [];
     if (roomId) {
         room = rooms.find((row) => row.id === roomId);
         if (!room) {
             throw new CliError("not_found", `No Village Town Center zone found for ${roomId}. Run \`recess village events\` to list linkable zones.`);
         }
-        if (room.linkedTemplateId && room.linkedTemplateId !== templateId) {
-            throw new CliError("invalid_arguments", `Zone ${room.id} (${room.name}) is already linked to template ${room.linkedTemplateId} (${room.linkedTemplateName ?? "unnamed"}). Unlink that template first.`);
+        const otherBookings = room.bookings.filter((booking) => booking.templateId !== templateId);
+        const days = templateDays(template);
+        const conflict = days
+            ? otherBookings.find((booking) => booking.days.some((day) => days.includes(day)))
+            : undefined;
+        if (conflict) {
+            throw new CliError("invalid_arguments", `Zone ${room.id} (${room.name}) is already linked to template ${conflict.templateId} (${conflict.name}). Unlink that template first.`);
         }
+        if (!days)
+            informationalBookings = otherBookings;
     }
     const previousRoom = template.villageRoomId
         ? rooms.find((row) => row.id === template.villageRoomId)
@@ -123,6 +143,9 @@ async function linkEvent(ctx) {
             currentVillageRoomId: template.villageRoomId,
         },
         request: body,
+        ...(informationalBookings.length > 0 && {
+            details: { bookings: informationalBookings },
+        }),
     }, async () => {
         const result = await api.client.PATCH("/recess/event-templates/{id}/", {
             params: { path: { id: template.id } },

package/dist/help.js

@@ -148,6 +148,7 @@ Usage:
   recess [--json] onboarding queue [--school <institution-slug>]
   recess [--json] onboarding kids [--time-period-days N] [--cohort <id>]
     [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
+  recess [--json] onboarding rearm-kid-first-run <kid-id> [--confirm]
   recess [--json] onboarding timeline <family-id>
   recess [--json] onboarding readiness <family-id>
   recess [--json] onboarding family <family-id>
@@ -352,6 +353,8 @@ Usage:
     --delta TEXT [--confirm --approval-token TOKEN]
   recess [--json] goals delete <goal-id> --student <kid-id>
     [--confirm --approval-token TOKEN]
+  recess [--json] goals restore <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
   recess [--json] goals complete <goal-id> [--confirm]
   recess [--json] goals undo-completion <goal-id> [--confirm]
   recess [--json] goals archive <goal-id> --student <kid-id>
@@ -370,6 +373,9 @@ Usage:
     [--confirm --approval-token TOKEN]
   recess [--json] todos delete <todo-id>
     [--confirm --approval-token TOKEN]
+  recess [--json] todos restore <todo-id>
+    [--confirm --approval-token TOKEN]
+  recess [--json] todos generate-learning-analysis <todo-id> [--confirm]
   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>

package/package.json

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