recess-cli 2.7.0 → 2.9.0

package/dist/api.js

@@ -19,16 +19,19 @@ export class RecessAdminApi {
     clientTag;
     client;
     villageSessionPromise;
-    constructor(config, reason, clientTag = RECESS_CLIENT_CLI) {
+    constructor(config, reason, clientTag = RECESS_CLIENT_CLI, clientOverride, fetchOverride) {
         this.config = config;
         this.reason = reason;
         this.clientTag = clientTag;
-        this.client = createClient({
-            baseUrl: config.apiOrigin,
-            headers: config.sessionCookie
-                ? { cookie: config.sessionCookie }
-                : undefined,
-        });
+        this.client =
+            clientOverride ??
+                createClient({
+                    baseUrl: config.apiOrigin,
+                    headers: config.sessionCookie
+                        ? { cookie: config.sessionCookie }
+                        : undefined,
+                    ...(fetchOverride ? { fetch: fetchOverride } : {}),
+                });
         const requestReason = this.reason;
         const requestClientTag = this.clientTag;
         this.client.use({
@@ -162,7 +165,9 @@ export class RecessAdminApi {
     async uploadMapTestScores(studentId, pdf, fileName) {
         this.requireAuth();
         const formData = new FormData();
-        formData.append("file", new Blob([pdf], { type: "application/pdf" }), fileName);
+        const pdfBody = new Uint8Array(pdf.byteLength);
+        pdfBody.set(pdf);
+        formData.append("file", new Blob([pdfBody.buffer], { type: "application/pdf" }), fileName);
         const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
         applyIdempotencyHeaders(headers);
         const response = await fetch(new URL(`/tutor/students/${encodeURIComponent(studentId)}/map-test-scores/upload`, this.config.apiOrigin), {

package/dist/args.js

@@ -32,7 +32,6 @@ const BOOLEAN_FLAGS = new Set([
     "starter-only",
     "unlink",
     "visual-only",
-    "version",
     "wait",
 ]);
 export function parseArgs(args) {

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 }));
@@ -229,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")) {
@@ -249,6 +251,7 @@ async function writeCommand(parsed, preview, execute) {
             action: preview.action,
             fingerprint,
             target: preview.target,
+            ...(preview.action.startsWith("mastery.") ? { preview } : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -696,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");
@@ -914,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) {
@@ -1551,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
@@ -1576,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") {
@@ -1701,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") {
@@ -1772,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";
@@ -2536,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 });
@@ -3127,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");
@@ -3146,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") {
@@ -3171,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.");
@@ -3258,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 },
@@ -3267,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 } : {}),
@@ -3289,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");
@@ -3362,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,
@@ -3376,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)) {
@@ -3402,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,
@@ -4239,8 +4402,25 @@ export async function runCommand(argv) {
     }
     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
@@ -4278,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 } : {}),
                     },
                 },
@@ -4641,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/.");
         }
@@ -4970,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