recess-cli 2.6.1 → 2.8.0

package/dist/cli.js

@@ -6,9 +6,10 @@ import { RecessAdminApi, unwrap, withIdempotencyContext } from "./api.js";
 import { flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
 import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
 import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, saveProfile, useProfile, } from "./config.js";
-import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
+import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
+import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
 import { runSchoolCommand } from "./commands/school.js";
 import { runVillageEventsCommand } from "./commands/village-events.js";
@@ -22,6 +23,7 @@ import { requireConfirmation } from "./safety.js";
 import { installSkill, isEphemeralInstall, readBundledSkillVersion, readCliVersion, } from "./setup.js";
 import { compareVersions, updateSkillFromServer } from "./skill-update.js";
 import { readSkillCache, writeSkillCache } from "./skills-cache.js";
+import { sanitizeWorkspaceUploadName } from "./upload-names.js";
 import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
 function requiredRequestReason(parsed) {
     return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
@@ -36,9 +38,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;
 }
@@ -232,7 +231,7 @@ async function skillStatus(config, reason) {
         };
     }
 }
-async function writeCommand(parsed, preview, execute) {
+async function localWriteCommand(parsed, preview, execute) {
     const fingerprint = approvalTokenFor(preview);
     const suppliedOperationKey = flagString(parsed, "operation-key");
     if (!hasFlag(parsed, "confirm")) {
@@ -252,6 +251,7 @@ async function writeCommand(parsed, preview, execute) {
             action: preview.action,
             fingerprint,
             target: preview.target,
+            ...(preview.action.startsWith("mastery.") ? { preview } : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -699,9 +699,6 @@ async function cleanupPlannerUpload(api, conversationId, signed, includeDelete)
             .catch(() => undefined);
     }
 }
-function safeGoalUploadName(fileName) {
-    return fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
 async function sha256File(absolutePath) {
     const handle = await fs.open(absolutePath, "r");
     const hash = createHash("sha256");
@@ -917,6 +914,8 @@ const CONTENT_LIBRARY_DISCOVERY_LANES = [
     "puzzles",
     "wonder",
     "idea-games",
+    "makers",
+    "drills",
 ];
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function parseGoalQueueEntries(value, label) {
@@ -1554,13 +1553,86 @@ function tierSlots(parsed) {
     }
     return slots;
 }
-export async function runCommand(argv) {
+function cliErrorShape(error) {
+    const cliError = error instanceof CliError
+        ? error
+        : new CliError("unexpected_error", error instanceof Error ? error.message : String(error));
+    return {
+        code: cliError.code,
+        message: cliError.message,
+        ...(cliError.details === undefined ? {} : { details: cliError.details }),
+    };
+}
+function remoteWriteCommand(argv, structuredInput, store) {
+    return async (parsed, preview, execute) => {
+        const fingerprint = approvalTokenFor({
+            ...preview,
+            details: {
+                ...preview.details,
+                command: parsed.positionals.join(" "),
+            },
+        });
+        const suppliedOperationKey = flagString(parsed, "operation-key");
+        if (!hasFlag(parsed, "confirm")) {
+            const operationKey = await store.stage({
+                argv,
+                structuredInput,
+                preview,
+                fingerprint,
+            });
+            requireConfirmation(false, {
+                ...preview,
+                details: {
+                    ...preview.details,
+                    operationKey,
+                    retry: "Confirm with the same command path plus --confirm --operation-key <operationKey>. The hosted service will execute the stored exact payload; do not retransmit structured input.",
+                },
+            });
+        }
+        if (!suppliedOperationKey) {
+            throw new CliError("confirmation_required", "A confirmed hosted write requires --operation-key from the preview.", 2, { preview, requiredFlag: "--operation-key" });
+        }
+        const begun = await store.begin(suppliedOperationKey, fingerprint);
+        if (begun.state === "completed")
+            return begun.result;
+        if (begun.state === "failed") {
+            throw new CliError(begun.error.code, begun.error.message, 1, begun.error.details);
+        }
+        try {
+            const result = await withIdempotencyContext({ operationKey: suppliedOperationKey, fingerprint }, execute);
+            await store.complete(suppliedOperationKey, result);
+            return result;
+        }
+        catch (error) {
+            await store.fail(suppliedOperationKey, cliErrorShape(error));
+            throw error;
+        }
+    };
+}
+export async function executeRecessCommand(argv, options = {}) {
     const parsed = parseArgs(argv);
     const [noun, verb] = parsed.positionals;
     const commands = buildCommandSchema(HELP);
+    const isRemote = options.transport === "remote";
+    if (isRemote &&
+        (!options.api || !options.config || !options.operationStore)) {
+        throw new CliError("remote_context_required", "Hosted execution requires injected API, configuration, and operation-store adapters.");
+    }
+    if (isRemote) {
+        const forbiddenTransportFlag = ["deliver", "profile", "json"].find((name) => hasFlag(parsed, name));
+        if (forbiddenTransportFlag) {
+            throw new CliError("remote_flag_unavailable", `--${forbiddenTransportFlag} is not available over hosted MCP.`);
+        }
+    }
+    const writeCommand = options.operationStore
+        ? remoteWriteCommand(argv, options.structuredInput, options.operationStore)
+        : localWriteCommand;
     // Before the help branch: `--version` parses as a FLAG, so `noun` is
     // undefined and `!noun` would return help instead. (Found by running it.)
-    if (noun === "version" || hasFlag(parsed, "version")) {
+    if (noun === "version" || (!noun && hasFlag(parsed, "version"))) {
+        if (isRemote) {
+            throw new CliError("remote_command_unavailable", "The version command is not exposed by the hosted Recess CLI.");
+        }
         const unknown = Array.from(parsed.flags.keys()).filter((name) => !["deliver", "json", "version"].includes(name));
         if (unknown.length > 0) {
             throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
@@ -1579,28 +1651,70 @@ export async function runCommand(argv) {
                 .map((name) => `--${name}`)
                 .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
         }
-        const config = await resolveConfig(flagString(parsed, "profile"));
-        const discovery = resolveCommandDiscovery(config);
-        return { help: scopedHelp(HELP, commands, [], discovery) };
+        const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
+        const discovery = options.discovery ?? resolveCommandDiscovery(config);
+        const visibleCommands = isRemote ? remoteCommands(commands) : commands;
+        return {
+            help: scopedHelp(HELP, visibleCommands, [], discovery, {
+                remoteOnly: isRemote,
+            }),
+        };
     }
     if (noun === "help" || hasFlag(parsed, "help")) {
         const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
-        const config = await resolveConfig(flagString(parsed, "profile"));
-        const discovery = resolveCommandDiscovery(config);
-        return { help: scopedHelp(HELP, commands, scope, discovery) };
+        const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
+        const discovery = options.discovery ?? resolveCommandDiscovery(config);
+        const visibleCommands = isRemote ? remoteCommands(commands) : commands;
+        return {
+            help: scopedHelp(HELP, visibleCommands, scope, discovery, {
+                remoteOnly: isRemote,
+            }),
+        };
+    }
+    validateInvocation(parsed, commands, { remote: isRemote });
+    if (isRemote) {
+        const command = findCommandSchema(commands, parsed.positionals);
+        if (!command?.remoteCapable) {
+            throw new CliError("remote_command_unavailable", `\`${parsed.positionals.join(" ")}\` is not exposed by the hosted Recess CLI. Use help or agent-context to discover the remote catalog.`);
+        }
+        if (options.structuredInput !== undefined &&
+            ![
+                "apps validate",
+                "goal-templates validate-spec",
+                "goal-templates create",
+            ].includes(command.path.join(" "))) {
+            throw new CliError("invalid_arguments", "Structured input is accepted only by hosted apps validate and goal-templates validate-spec/create.");
+        }
+        if ((noun === "goal-templates" || noun === "skills") &&
+            options.session?.user.role !== "GUIDE" &&
+            options.session?.user.role !== "ADMIN") {
+            throw new CliError("forbidden", "Hosted goal-template authoring requires a guide or admin.");
+        }
+        if (noun === "skills" &&
+            parsed.positionals[3] !== "recess-goal-authoring") {
+            throw new CliError("remote_command_unavailable", "Hosted skills only exposes recess-goal-authoring.");
+        }
+        const granted = options.grantedScopes ?? new Set();
+        const missing = command.oauthScopes.filter((scope) => !granted.has(scope));
+        if (missing.length > 0) {
+            throw new CliError("insufficient_scope", `This command requires OAuth scope${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}.`, 1, { requiredScopes: command.oauthScopes });
+        }
     }
-    validateInvocation(parsed, commands);
     if (noun === "agent-context") {
-        const [profiles, config] = await Promise.all([
-            listProfiles(),
-            resolveConfig(flagString(parsed, "profile")),
-        ]);
-        const discovery = resolveCommandDiscovery(config);
+        const [profiles, config] = isRemote
+            ? [{ profiles: [] }, options.config ?? (await resolveConfig(undefined))]
+            : await Promise.all([
+                listProfiles(),
+                options.config ?? resolveConfig(flagString(parsed, "profile")),
+            ]);
+        const discovery = options.discovery ?? resolveCommandDiscovery(config);
         return agentContext(commands, {
-            cliVersion: await readCliVersion(),
+            cliVersion: options.versions?.cliVersion ??
+                (isRemote ? "hosted" : await readCliVersion()),
             availableProfiles: profiles.profiles.map((profile) => profile.name),
             feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
             discovery,
+            remoteOnly: isRemote,
         });
     }
     if (noun === "profile") {
@@ -1704,8 +1818,17 @@ export async function runCommand(argv) {
             }));
         }
     }
-    const config = await resolveConfig(flagString(parsed, "profile"));
+    const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
     const requestReason = noun === "auth" ? undefined : requiredRequestReason(parsed);
+    if (noun === "doctor" && isRemote) {
+        return {
+            transport: "streamable-http-mcp",
+            resource: options.remoteResource ?? config.apiOrigin.replace(/\/$/, "") + "/mcp",
+            authenticated: true,
+            session: options.session ?? null,
+            scopes: Array.from(options.grantedScopes ?? []).sort(),
+        };
+    }
     if (noun === "doctor")
         return doctor(config, requestReason);
     if (noun === "setup") {
@@ -1775,7 +1898,7 @@ export async function runCommand(argv) {
         }
         throw new CliError("invalid_arguments", "Use auth login, request, poll, status, or logout.");
     }
-    const api = new RecessAdminApi(config, requestReason);
+    const api = options.api ?? new RecessAdminApi(config, requestReason);
     api.requireAuth();
     if (noun === "village") {
         const targetWorldId = flagString(parsed, "world") ?? "village-1";
@@ -2539,7 +2662,16 @@ export async function runCommand(argv) {
         return runApplicationsCommand({ parsed, api, writeCommand });
     }
     if (noun === "apps") {
-        return runAppsCommand({ parsed, api, writeCommand });
+        return runAppsCommand({
+            parsed,
+            api,
+            writeCommand,
+            transport: options.transport,
+            structuredInput: options.structuredInput,
+        });
+    }
+    if (noun === "mastery") {
+        return runMasteryCommand({ parsed, api, writeCommand });
     }
     if (noun === "school") {
         return runSchoolCommand({ parsed, api, writeCommand });
@@ -3130,7 +3262,7 @@ export async function runCommand(argv) {
         // infers whether `get` means guardian guidance or staff-only operations.
         const audience = assertChoice(verb, ["admin", "guardian"], "skill audience");
         const action = positional(parsed, 2, "skills action");
-        const refresh = hasFlag(parsed, "refresh");
+        const refresh = isRemote || hasFlag(parsed, "refresh");
         if (action === "list") {
             const query = flagString(parsed, "query");
             const category = flagString(parsed, "category");
@@ -3149,7 +3281,8 @@ export async function runCommand(argv) {
                     },
                 },
             }));
-            await writeSkillCache(config.apiOrigin, cacheKey, data);
+            if (!isRemote)
+                await writeSkillCache(config.apiOrigin, cacheKey, data);
             return { ...data, cached: false };
         }
         if (action === "get") {
@@ -3174,7 +3307,8 @@ export async function runCommand(argv) {
                     },
                 },
             }));
-            await writeSkillCache(config.apiOrigin, cacheKey, data);
+            if (!isRemote)
+                await writeSkillCache(config.apiOrigin, cacheKey, data);
             return { ...data, cached: false };
         }
         throw new CliError("invalid_arguments", "Use skills guardian list|get or skills admin list|get.");
@@ -3261,7 +3395,12 @@ export async function runCommand(argv) {
                 timeoutSeconds > 7200) {
                 throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 10 through 7200.");
             }
-            const body = { stage, items: input.items };
+            const allowPossibleDuplicate = hasFlag(parsed, "allow-possible-duplicate");
+            const body = {
+                stage,
+                items: input.items,
+                ...(allowPossibleDuplicate ? { allowPossibleDuplicate: true } : {}),
+            };
             const preview = {
                 action: "content-library.submit",
                 target: { stage, resourceCount: input.items.length },
@@ -3270,7 +3409,9 @@ export async function runCommand(argv) {
                     admission: stage === "polish"
                         ? "Starts automatic decoration; the island promotes each successful resource to LIVE after the polish and deterministic tail finish."
                         : "Holds each new resource in REVIEW until an admin approves it.",
-                    duplicateBehavior: "Existing URLs are returned as duplicates and are not overwritten.",
+                    duplicateBehavior: allowPossibleDuplicate
+                        ? "Exact duplicates and previously rejected URLs are still returned as duplicates; fuzzy possible-duplicate candidates are admitted to REVIEW for a curator to settle."
+                        : "Existing URLs are returned as duplicates and are not overwritten.",
                     deployOrderFence: "The server verifies the island's review/polish lifecycle capability before its first write.",
                     waitForLive: wait,
                     ...(wait ? { timeoutSeconds } : {}),
@@ -3292,6 +3433,21 @@ export async function runCommand(argv) {
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
+        const readTemplateDocument = async () => {
+            if (!isRemote) {
+                return readJsonFile(flagString(parsed, "file", { required: true }), "Template file");
+            }
+            const input = options.structuredInput;
+            const template = input?.template;
+            if (!input ||
+                Object.keys(input).some((key) => key !== "template") ||
+                !template ||
+                typeof template !== "object" ||
+                Array.isArray(template)) {
+                throw new CliError("invalid_arguments", "Supply the complete template document as input.template.");
+            }
+            return template;
+        };
         if (verb === "list") {
             const query = flagString(parsed, "query");
             const kind = flagString(parsed, "kind");
@@ -3365,7 +3521,7 @@ export async function runCommand(argv) {
             return version;
         }
         if (verb === "validate-spec") {
-            const document = parseGoalTemplateDocument(await readJsonFile(flagString(parsed, "file", { required: true }), "Template file"));
+            const document = parseGoalTemplateDocument(await readTemplateDocument());
             // A read-only validation: no gate, and iterating on it is the whole point.
             return {
                 slug: document.slug,
@@ -3379,8 +3535,10 @@ export async function runCommand(argv) {
             };
         }
         if (verb === "create") {
-            const filePath = flagString(parsed, "file", { required: true });
-            const authoredDocument = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            const filePath = isRemote
+                ? undefined
+                : flagString(parsed, "file", { required: true });
+            const authoredDocument = parseGoalTemplateDocument(await readTemplateDocument());
             const coinAmountOverride = flagNumber(parsed, "coin-amount");
             if (coinAmountOverride !== undefined &&
                 (!Number.isInteger(coinAmountOverride) || coinAmountOverride < 1)) {
@@ -3405,13 +3563,15 @@ export async function runCommand(argv) {
                 },
             }));
             if (!validation.valid) {
-                throw new CliError("invalid_spec", `The setupWorkflowSpec is invalid, so nothing was created: ${validation.error}`, 1, { file: path.resolve(filePath) });
+                throw new CliError("invalid_spec", `The setupWorkflowSpec is invalid, so nothing was created: ${validation.error}`, 1, filePath ? { file: path.resolve(filePath) } : { input: "template" });
             }
             return writeCommand(parsed, {
                 action: "create a NEW global goal template (DETERMINISTIC_WORKFLOW — this cannot be converted back)",
                 target: { slug: document.slug, title: document.title },
                 request: {
-                    file: path.resolve(filePath),
+                    ...(filePath
+                        ? { file: path.resolve(filePath) }
+                        : { template: document }),
                     kind: document.kind,
                     setupAudience: document.setupAudience,
                     category: document.category ?? null,
@@ -4086,7 +4246,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 +4264,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 +4274,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,12 +4398,29 @@ 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") {
-            // A guide has no family — their roster is the students they are
-            // actively assigned to, which the tutor surface already scopes. The
+            const requestedScope = flagString(parsed, "scope");
+            const scope = requestedScope
+                ? assertChoice(requestedScope, ["mine", "family"], "--scope")
+                : isRemote
+                    ? "mine"
+                    : undefined;
+            if (scope === "mine") {
+                return unwrap(await api.client.GET("/tutor/students", {
+                    params: { query: { scope: "mine" } },
+                }));
+            }
+            if (scope === "family") {
+                return unwrap(await api.client.GET("/family/kids", {
+                    params: { query: { includeSelf: "false" } },
+                }));
+            }
+            // A guide has no family — their roster is the tutor surface's, which the
+            // server scopes per surface (`STUDENT_SCOPE_POLICY_BY_SURFACE`: manual
+            // assignments plus live cohorts, never the institution roster). The
             // stored identity is absent on an env-cookie session, so fall back to
             // asking the server who this session belongs to.
             // The stored identity only describes a `auth login` session; an
@@ -4248,13 +4458,38 @@ export async function runCommand(argv) {
             }));
         }
         if (verb === "todos") {
-            const studentId = flagString(parsed, "student", { required: true });
+            const student = flagString(parsed, "student", { required: true });
+            const date = flagString(parsed, "date");
+            if (date !== undefined &&
+                date !== "today" &&
+                (!/^\d{4}-\d{2}-\d{2}$/.test(date) ||
+                    !Number.isFinite(Date.parse(`${date}T00:00:00.000Z`)) ||
+                    new Date(`${date}T00:00:00.000Z`).toISOString().slice(0, 10) !== date)) {
+                throw new CliError("invalid_arguments", "--date must be today or a valid YYYY-MM-DD calendar date.");
+            }
+            const cursor = flagString(parsed, "cursor");
             const limit = flagNumber(parsed, "limit");
+            let studentId = student;
+            if (!/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(student)) {
+                const roster = unwrap(await api.client.GET("/tutor/students", {
+                    params: { query: { scope: "mine" } },
+                }));
+                const normalize = (name) => name.trim().replace(/\s+/g, " ").toLowerCase();
+                const matches = roster.items.filter((item) => normalize(item.name) === normalize(student));
+                if (matches.length !== 1) {
+                    throw new CliError(matches.length ? "ambiguous_student" : "student_not_found", matches.length
+                        ? "Multiple students have that name. Ask which student, then retry with their ID."
+                        : "No exact name match in your roster. Use students list to find the student's ID.", 1, { matches: matches.map(({ userId, name }) => ({ userId, name })) });
+                }
+                studentId = matches[0].userId;
+            }
             return unwrap(await api.client.GET("/studio/students/{studentId}/todos", {
                 params: {
                     path: { studentId },
                     query: {
                         ...(limit === undefined ? {} : { limit }),
+                        ...(date === undefined ? {} : { date }),
+                        ...(cursor === undefined ? {} : { cursor }),
                         ...(hasFlag(parsed, "analyzed") ? { analyzed: true } : {}),
                     },
                 },
@@ -4397,7 +4632,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 +4646,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 +4772,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 });
@@ -4533,7 +4846,8 @@ export async function runCommand(argv) {
             throw new CliError("invalid_arguments", `PDF size must be between 1 byte and ${GOAL_PDF_UPLOAD_MAX_BYTES} bytes.`);
         }
         const fileName = path.basename(absolutePath);
-        const workspacePath = flagString(parsed, "path") ?? `uploads/${safeGoalUploadName(fileName)}`;
+        const workspacePath = flagString(parsed, "path") ??
+            `uploads/${sanitizeWorkspaceUploadName(fileName)}`;
         if (!workspacePath.startsWith("uploads/")) {
             throw new CliError("invalid_arguments", "Textbook PDFs must be attached under uploads/.");
         }
@@ -4862,4 +5176,7 @@ export async function runCommand(argv) {
     }
     throw new CliError("unknown_command", `Unknown command: ${parsed.positionals.join(" ")}\n\n${HELP}`);
 }
+export async function runCommand(argv) {
+    return executeRecessCommand(argv);
+}
 //# sourceMappingURL=cli.js.map