recess-cli 2.3.0 → 2.5.0

package/dist/commands/apps.js

@@ -0,0 +1,413 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { positional } from "./shared.js";
+const PROJECT_FILE = ".recess/app.json";
+const CONTRACT_FILE = "contract.json";
+const MANIFEST_FILE = "manifest.json";
+const BRIEF_FILE = "brief.md";
+const SKIP_DIRS = new Set([".recess", ".git", "node_modules"]);
+const MAX_FILE_BYTES = 512 * 1024;
+const TERMINAL = new Set(["COMPLETE", "FAILED", "REJECTED"]);
+async function readAppLink(dir) {
+    try {
+        const raw = await fs.readFile(path.join(dir, PROJECT_FILE), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeAppLink(dir, link) {
+    await fs.mkdir(path.join(dir, ".recess"), { recursive: true });
+    await fs.writeFile(path.join(dir, PROJECT_FILE), JSON.stringify(link, null, 2) + "\n");
+}
+/** Every text file under dir (relative, forward-slash paths); the CLI's own state stays out. */
+async function collectFiles(dir) {
+    const files = {};
+    async function walk(current, prefix) {
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(full, rel);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const stat = await fs.stat(full);
+            if (stat.size > MAX_FILE_BYTES) {
+                throw new CliError("invalid_arguments", `${rel} is larger than ${MAX_FILE_BYTES / 1024} KB; Studio apps are small text files.`);
+            }
+            files[rel] = await fs.readFile(full, "utf8");
+        }
+    }
+    await walk(dir, "");
+    if (!files["index.html"]) {
+        throw new CliError("invalid_arguments", `${dir} has no index.html. Run \`recess apps init\` first, or point --dir at the app.`);
+    }
+    return files;
+}
+async function writeFiles(dir, files) {
+    let count = 0;
+    for (const [rel, content] of Object.entries(files)) {
+        if (rel.includes("..") || path.isAbsolute(rel))
+            continue;
+        const full = path.join(dir, rel);
+        await fs.mkdir(path.dirname(full), { recursive: true });
+        await fs.writeFile(full, content);
+        count += 1;
+    }
+    return count;
+}
+function resolveDir(ctx, positionalIndex) {
+    const flag = flagString(ctx.parsed, "dir");
+    const fromPositional = ctx.parsed.positionals[positionalIndex];
+    return path.resolve(flag ?? fromPositional ?? ".");
+}
+async function readContract(dir) {
+    const raw = await fs
+        .readFile(path.join(dir, CONTRACT_FILE), "utf8")
+        .catch(() => null);
+    if (!raw) {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} is missing. Your agent writes the BuildContract there (see AGENTS.md in the app folder).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} is not valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} must be a JSON object (the BuildContract).`);
+    }
+    return parsed;
+}
+async function readManifest(dir) {
+    const raw = await fs
+        .readFile(path.join(dir, MANIFEST_FILE), "utf8")
+        .catch(() => null);
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${MANIFEST_FILE} is not valid JSON.`);
+    }
+}
+function slug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+function briefFor(data) {
+    const { todo, analysis } = data;
+    const misconceptions = analysis.patterns.map((p) => p.instanceKey ?? slug(p.name));
+    const lines = [
+        "# Build brief — remediation for a kid's todo",
+        "",
+        `Source todo: "${todo.title}" (${todo.id})${todo.completedAt ? `, completed ${todo.completedAt.slice(0, 10)}` : ""}`,
+        ...(todo.description ? [`Todo description: ${todo.description}`] : []),
+        ...(data.standards.length
+            ? [
+                "",
+                "## Standard(s)",
+                ...data.standards.map((s) => `- ${s.notation} — ${s.description}`),
+            ]
+            : [
+                "",
+                "## Standard(s)",
+                "- none mapped; pick one with `recess apps standards <words>`",
+            ]),
+        ...(data.gradeBand ? ["", `Grade band: ${data.gradeBand}`] : []),
+        ...(data.interests.length
+            ? [`Interests: ${data.interests.join(", ")}`]
+            : []),
+        "",
+        "## What went wrong (forensic analysis of the session)",
+        "",
+        ...(analysis.overallPerformance
+            ? [`Overall: ${analysis.overallPerformance}`, ""]
+            : []),
+        ...(analysis.rootCause ? [`Root cause: ${analysis.rootCause}`, ""] : []),
+        ...(analysis.summary ? [`Summary: ${analysis.summary}`, ""] : []),
+        "### Patterns",
+        ...(analysis.patterns.length
+            ? analysis.patterns.flatMap((p) => [
+                `- **${p.name}**${p.instanceKey ? ` (\`${p.instanceKey}\`)` : ""}: ${p.issue}`,
+                `  ${p.analysis}`,
+                ...(p.behavioralGap
+                    ? [
+                        `  Observed: ${p.behavioralGap.observed}`,
+                        `  Expected: ${p.behavioralGap.expected}`,
+                    ]
+                    : []),
+            ])
+            : ["- none recorded"]),
+        "",
+        "### Prescriptions",
+        ...(analysis.prescriptions.length
+            ? analysis.prescriptions.map((p) => `- ${p.type}: ${p.recommendation}`)
+            : ["- none recorded"]),
+        "",
+        "## Build against this",
+        "",
+        "- Mode: remediate. The app exists to close the gap above — every practice item must be one the kid",
+        "  would get wrong by the observed behaviour, and the fork must confront observed vs expected.",
+        `- In manifest.json declare template.misconceptions as ${JSON.stringify(misconceptions)} (match the`,
+        "  keys above; add more only if the model teaches them) and template.ccss as the standard.",
+        "- Theme items with the interests listed; never use the kid's name or anything from the session.",
+        "- The kid must never learn this app exists because of a mistake: no 'last time', 'you got',",
+        "  'let's fix your'. The confront intro shows a stranger's attempt ('Someone tried this'); the",
+        "  title and every line read like any other practice.",
+        "- Follow AGENTS.md for everything else (contract, no reveals, one reading per step).",
+        "",
+    ];
+    return lines.join("\n");
+}
+function agentsGuide(docs) {
+    return [
+        "# Building this Recess app",
+        "",
+        "If a brief.md sits next to this file, it is the assignment: build for that kid's gap first —",
+        "but the kid never hears about the gap: no copy that refers to their past work or a mistake.",
+        "",
+        "This folder is a Recess Studio app on the locked scaffold. Edit ONLY: skill.js, model.js,",
+        "model.css, params.schema.json, params.json. Never touch index.html, styles.css, shell.js,",
+        "widgets.js, engine.js, key.js — a modified locked file fails validation.",
+        "",
+        "Before publishing, write two files at the root:",
+        "- contract.json — the BuildContract described below (copy the shape in the template contract).",
+        '- manifest.json — { "title": "...", "description": "...", "template": { "ccss": "5.NF.A.1", "modes": ["prepare","remediate"], "misconceptions": ["..."] } }',
+        "",
+        'Then: `recess apps validate --reason "..."` (reports without publishing) and',
+        '`recess apps publish --reason "..."` (validation + independent review; on pass the app is live).',
+        "",
+        "---",
+        "",
+        docs.runtime ?? "",
+        "",
+        "---",
+        "",
+        docs.template ?? "",
+        "",
+        "---",
+        "",
+        docs.pedagogy ? `# Pedagogy\n\n${docs.pedagogy}` : "",
+        "",
+        "---",
+        "",
+        docs.design ? `# Design\n\n${docs.design}` : "",
+        "",
+    ].join("\n");
+}
+async function pollBuild(ctx, buildId, timeoutMs) {
+    const started = Date.now();
+    let delay = 3_000;
+    for (;;) {
+        const status = unwrap(await ctx.api.client.GET("/studio/builds/{buildId}", {
+            params: { path: { buildId } },
+        }));
+        if (TERMINAL.has(status.status))
+            return status;
+        if (Date.now() - started > timeoutMs) {
+            throw new CliError("timeout", `Build ${buildId} is still ${status.status} after ${Math.round(timeoutMs / 1000)}s; check later with \`recess apps status ${buildId}\`.`);
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 1.5, 15_000);
+    }
+}
+async function submit(ctx, dir, dryRun) {
+    const files = await collectFiles(dir);
+    const contract = await readContract(dir);
+    const manifest = await readManifest(dir);
+    const link = await readAppLink(dir);
+    const name = flagString(ctx.parsed, "name") ?? manifest.title ?? path.basename(dir);
+    const body = {
+        ...(link?.projectId ? { projectId: link.projectId } : {}),
+        name,
+        ...(manifest.description ? { description: manifest.description } : {}),
+        files,
+        contract,
+        ...(manifest.template ? { template: manifest.template } : {}),
+        dryRun,
+    };
+    const assignTo = flagString(ctx.parsed, "assign");
+    const due = flagString(ctx.parsed, "due");
+    if (assignTo && dryRun) {
+        throw new CliError("invalid_arguments", "--assign publishes; use `recess apps publish --assign <student-id>`.");
+    }
+    if (due && !/^\d{4}-\d{2}-\d{2}$/.test(due)) {
+        throw new CliError("invalid_arguments", "--due must be YYYY-MM-DD.");
+    }
+    const created = unwrap(await ctx.api.client.POST("/studio/imports", { body }));
+    await writeAppLink(dir, {
+        ...link,
+        projectId: created.projectId,
+        appUrl: created.appUrl,
+    });
+    const wait = !hasFlag(ctx.parsed, "no-wait");
+    if (!wait) {
+        if (assignTo) {
+            throw new CliError("invalid_arguments", "--assign needs the build result; drop --no-wait.");
+        }
+        return { ...created, dryRun };
+    }
+    const status = await pollBuild(ctx, created.buildId, 30 * 60 * 1000);
+    const result = {
+        projectId: created.projectId,
+        buildId: created.buildId,
+        appUrl: created.appUrl,
+        dryRun,
+        status: status.status,
+        report: status.report ?? null,
+        error: status.error ?? null,
+    };
+    if (!assignTo)
+        return result;
+    if (status.status !== "COMPLETE") {
+        return {
+            ...result,
+            assigned: null,
+            assignError: `Not assigned: the build ended ${status.status}. Fix the report and publish again.`,
+        };
+    }
+    const assigned = await assign(ctx, created.projectId, {
+        studentId: assignTo,
+        ...(due ? { dueDate: due } : {}),
+        ...(link?.forTodoId ? { sourceTodoId: link.forTodoId } : {}),
+    });
+    return { ...result, assigned };
+}
+async function assign(ctx, projectId, body) {
+    return unwrap(await ctx.api.client.POST("/studio/projects/{projectId}/assign", {
+        params: { path: { projectId } },
+        body,
+    }));
+}
+export async function runAppsCommand(ctx) {
+    const { parsed, api } = ctx;
+    const verb = parsed.positionals[1];
+    if (verb === "init") {
+        const dir = path.resolve(positional(parsed, 2, "app folder"));
+        await fs.mkdir(dir, { recursive: true });
+        const existing = await fs.readdir(dir);
+        if (existing.length > 0 && !hasFlag(parsed, "force")) {
+            throw new CliError("invalid_arguments", `${dir} is not empty. Use --force to write the scaffold over it.`);
+        }
+        const forTodo = flagString(parsed, "for-todo");
+        const analysis = forTodo
+            ? unwrap(await api.client.GET("/studio/todos/{todoId}/analysis", {
+                params: { path: { todoId: forTodo } },
+            }))
+            : null;
+        const scaffold = unwrap(await api.client.GET("/studio/scaffold"));
+        const written = await writeFiles(dir, scaffold.files);
+        await fs.writeFile(path.join(dir, "AGENTS.md"), agentsGuide(scaffold.docs));
+        if (analysis) {
+            await fs.writeFile(path.join(dir, BRIEF_FILE), briefFor(analysis));
+            await writeAppLink(dir, {
+                forTodoId: analysis.todo.id,
+                studentId: analysis.todo.studentId,
+            });
+        }
+        return {
+            dir,
+            filesWritten: written + (analysis ? 2 : 1),
+            ...(analysis
+                ? {
+                    brief: BRIEF_FILE,
+                    studentId: analysis.todo.studentId,
+                    standards: analysis.standards.map((s) => s.notation),
+                    misconceptions: analysis.analysis.patterns.map((p) => p.instanceKey ?? slug(p.name)),
+                }
+                : {}),
+            next: [
+                `cd ${dir}`,
+                analysis
+                    ? "Open the folder with your agent: brief.md is the assignment, AGENTS.md the contract."
+                    : "Open the folder with your agent and describe what the app should teach (AGENTS.md has the contract).",
+                'recess apps validate --reason "Check my app"',
+                analysis
+                    ? `recess apps publish --assign ${analysis.todo.studentId} --reason "Ship it to the kid"`
+                    : 'recess apps publish --reason "Ship my app"',
+            ],
+        };
+    }
+    if (verb === "standards") {
+        const q = parsed.positionals.slice(2).join(" ").trim();
+        if (!q) {
+            throw new CliError("invalid_arguments", 'Give words or a notation: recess apps standards "grade 4 adding fractions".');
+        }
+        return unwrap(await api.client.GET("/studio/standards", {
+            params: { query: { q } },
+        }));
+    }
+    if (verb === "assign") {
+        const dir = resolveDir(ctx, 2);
+        const link = await readAppLink(dir);
+        const studentId = flagString(parsed, "student") ?? link?.studentId;
+        if (!link?.projectId) {
+            throw new CliError("invalid_arguments", `${dir} has no published app yet; run \`recess apps publish\` first.`);
+        }
+        if (!studentId) {
+            throw new CliError("invalid_arguments", "--student <student-id> is required (or init the app with --for-todo).");
+        }
+        const due = flagString(parsed, "due");
+        if (due && !/^\d{4}-\d{2}-\d{2}$/.test(due)) {
+            throw new CliError("invalid_arguments", "--due must be YYYY-MM-DD.");
+        }
+        return assign(ctx, link.projectId, {
+            studentId,
+            ...(due ? { dueDate: due } : {}),
+            ...(link.forTodoId ? { sourceTodoId: link.forTodoId } : {}),
+        });
+    }
+    if (verb === "list") {
+        return unwrap(await api.client.GET("/studio/projects"));
+    }
+    if (verb === "pull") {
+        const projectId = positional(parsed, 2, "project id");
+        const dir = resolveDir(ctx, 3);
+        const project = unwrap(await api.client.GET("/studio/projects/{projectId}/files", {
+            params: { path: { projectId } },
+        }));
+        await fs.mkdir(dir, { recursive: true });
+        const written = await writeFiles(dir, project.files);
+        if (project.contract)
+            await fs.writeFile(path.join(dir, CONTRACT_FILE), JSON.stringify(project.contract, null, 2) + "\n");
+        await fs.writeFile(path.join(dir, MANIFEST_FILE), JSON.stringify({ title: project.name }, null, 2) + "\n");
+        await writeAppLink(dir, { projectId });
+        return {
+            dir,
+            projectId,
+            name: project.name,
+            versionNumber: project.versionNumber,
+            filesWritten: written,
+        };
+    }
+    if (verb === "validate") {
+        return submit(ctx, resolveDir(ctx, 2), true);
+    }
+    if (verb === "publish") {
+        return submit(ctx, resolveDir(ctx, 2), false);
+    }
+    if (verb === "status") {
+        const buildId = positional(parsed, 2, "build id");
+        return unwrap(await api.client.GET("/studio/builds/{buildId}", {
+            params: { path: { buildId } },
+        }));
+    }
+    throw new CliError("invalid_arguments", "Unknown apps command. Use: apps init <dir> [--for-todo <todo-id>] | apps standards <words> | apps list | apps pull <project-id> [dir] | apps validate [dir] | apps publish [dir] [--assign <student-id>] | apps assign [dir] --student <id> | apps status <build-id>.");
+}
+//# sourceMappingURL=apps.js.map

package/dist/commands/onboarding.js

@@ -503,6 +503,21 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 request: {},
             }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake/generate-summaries", { params: { path: { familyId } } })));
         }
+        if (verb === "link-math-academy") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const mathAcademyStudentId = flagInteger(parsed, "student-id", {
+                min: 1,
+            });
+            const body = mathAcademyStudentId === undefined ? {} : { mathAcademyStudentId };
+            return writeCommand(parsed, {
+                action: mathAcademyStudentId === undefined
+                    ? "link the kid to an existing Math Academy account using the saved login or a unique name match"
+                    : `link the kid to existing Math Academy student ${mathAcademyStudentId} after verifying that student exists`,
+                target: { familyId, kidUserId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/kids/{kidUserId}/link/math-academy", { params: { path: { familyId, kidUserId } }, body })));
+        }
         if (verb === "provision-math-academy") {
             const familyId = positional(parsed, 2, "family ID");
             const kidUserId = flagString(parsed, "kid", { required: true });

package/dist/commands/village-events.js

@@ -0,0 +1,150 @@
+import { unwrap } from "../api.js";
+import { flagString, hasFlag } from "../args.js";
+import { apiError, CliError } from "../errors.js";
+const NONE = "—";
+async function fetchTemplatesAndRooms(ctx) {
+    const [templatesResponse, rooms] = await Promise.all([
+        ctx.api.client.GET("/recess/event-templates-editable/"),
+        ctx.api.client.GET("/recess/village-rooms/"),
+    ]);
+    return {
+        templates: unwrap(templatesResponse).eventTemplates,
+        rooms: unwrap(rooms),
+    };
+}
+function schedule(template) {
+    if (template.singleEventDate)
+        return template.singleEventDate.slice(0, 10);
+    return template.rrule || NONE;
+}
+function renderColumns(rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column]))
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+/** `village events` — every editable Recess Hour template and its Town Center zone. */
+async function listEvents(ctx) {
+    const { templates, rooms } = await fetchTemplatesAndRooms(ctx);
+    const roomsById = new Map(rooms.map((room) => [room.id, room]));
+    const templateRows = templates.map((template) => {
+        const room = template.villageRoomId
+            ? roomsById.get(template.villageRoomId)
+            : undefined;
+        return {
+            id: template.id,
+            name: template.name,
+            status: template.status,
+            schedule: schedule(template),
+            villageRoomId: template.villageRoomId,
+            villageRoomName: room?.name ?? null,
+            joinUrl: template.joinUrl ?? null,
+        };
+    });
+    const unlinkedRooms = rooms
+        .filter((room) => !room.linkedTemplateId)
+        .map((room) => ({ id: room.id, name: room.name }));
+    if (hasFlag(ctx.parsed, "json")) {
+        return { templates: templateRows, unlinkedRooms };
+    }
+    const table = renderColumns([
+        ["TEMPLATE", "NAME", "STATUS", "SCHEDULE", "ZONE", "ZONE NAME", "URL"],
+        ...templateRows.map((row) => [
+            row.id,
+            row.name,
+            row.status,
+            row.schedule,
+            row.villageRoomId ?? NONE,
+            row.villageRoomName ?? (row.villageRoomId ? "(unknown zone)" : NONE),
+            row.joinUrl ?? NONE,
+        ]),
+    ]);
+    const unlinked = unlinkedRooms.length === 0
+        ? "  (none)"
+        : renderColumns(unlinkedRooms.map((room) => [`  ${room.id}`, room.name]));
+    return {
+        help: `${templates.length === 0 ? "No editable event templates." : table}\n\nUnlinked Town Center zones:\n${unlinked}`,
+    };
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** `village link-event --template <id> (--room <zoneId> | --unlink) [--url <https://…>]` */
+async function linkEvent(ctx) {
+    const { parsed, api, writeCommand } = ctx;
+    const templateId = flagString(parsed, "template", { required: true });
+    const roomId = flagString(parsed, "room");
+    const unlink = hasFlag(parsed, "unlink");
+    const url = flagString(parsed, "url");
+    if (url !== undefined && !isHttpUrl(url)) {
+        throw new CliError("invalid_arguments", "--url must be an http(s) URL (e.g. https://example.com/event).");
+    }
+    if (unlink === Boolean(roomId)) {
+        throw new CliError("invalid_arguments", "Pass exactly one of --room <zoneId> or --unlink.");
+    }
+    const { templates, rooms } = await fetchTemplatesAndRooms(ctx);
+    const template = templates.find((row) => row.id === templateId);
+    if (!template) {
+        throw new CliError("not_found", `No editable event template found for ${templateId}. Run \`recess village events\` to list them.`);
+    }
+    let room;
+    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 previousRoom = template.villageRoomId
+        ? rooms.find((row) => row.id === template.villageRoomId)
+        : undefined;
+    const body = {
+        villageRoomId: room ? room.id : null,
+        ...(url !== undefined ? { joinUrl: url } : {}),
+    };
+    return writeCommand(parsed, {
+        action: room
+            ? `Link template ${template.id} (${template.name}) → zone ${room.id} (${room.name}); zone will be renamed to the event title${url ? ` and its link set to ${url}` : ""}`
+            : `Unlink template ${template.id} (${template.name}) from zone ${template.villageRoomId ?? NONE}${previousRoom ? ` (${previousRoom.name})` : ""}`,
+        target: {
+            templateId: template.id,
+            templateName: template.name,
+            currentVillageRoomId: template.villageRoomId,
+        },
+        request: body,
+    }, async () => {
+        const result = await api.client.PATCH("/recess/event-templates/{id}/", {
+            params: { path: { id: template.id } },
+            body,
+        });
+        if (!result.response.ok) {
+            throw apiError(result.response.status, result.error);
+        }
+        return {
+            templateId: template.id,
+            templateName: template.name,
+            villageRoomId: body.villageRoomId,
+            villageRoomName: room?.name ?? null,
+            ...(url !== undefined ? { joinUrl: url } : {}),
+        };
+    });
+}
+export async function runVillageEventsCommand(ctx, verb) {
+    if (verb === "events")
+        return listEvents(ctx);
+    if (verb === "link-event")
+        return linkEvent(ctx);
+    throw new CliError("invalid_arguments", "Use village events or link-event.");
+}
+//# sourceMappingURL=village-events.js.map

package/dist/help.js

@@ -22,6 +22,10 @@ Usage:
   recess [--json] auth status|logout
   recess [--json] users search <name-or-id> [--limit 10]
   recess [--json] users get <user-id>
+  recess [--json] users lock <user-id> [--confirm]
+  recess [--json] users unlock <user-id> [--confirm]
+  recess [--json] users disable <user-id> [--whole-family] [--allow-billing] [--confirm]
+  recess [--json] users restore <user-id> --role kid|guardian|guide|program [--confirm]
   recess [--json] users tier list-tiers
   recess [--json] users tier get <kid-id>
   recess [--json] users tier preview <kid-id> --tier social|academics|lite|complete|platform
@@ -38,6 +42,8 @@ Usage:
   recess [--json] students list
   recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
   recess [--json] students schedule --student <kid-id> [--days 14]
+  recess [--json] students todos --student <kid-id> [--limit 30] [--analyzed]
+  recess [--json] students analysis --todo <todo-id>
   recess [--json] students xp-history --student <kid-id>
     [--range week|month|quarter|year]
   recess [--json] enrollments list --user <user-id>
@@ -48,6 +54,14 @@ Usage:
   recess [--json] invoices refund --invoice <id> --line-item <id>
     --method refund|credit|tokens [--full | --amount-cents N]
     [--who-pays guide|recess] [--reason TEXT] [--confirm]
+  recess [--json] apps init <dir> [--for-todo <todo-id>] [--force]
+  recess [--json] apps standards <query>
+  recess [--json] apps list
+  recess [--json] apps pull <project-id> [dir]
+  recess [--json] apps validate [dir] [--name TEXT] [--no-wait]
+  recess [--json] apps publish [dir] [--name TEXT] [--assign <kid-id>] [--due YYYY-MM-DD] [--no-wait]
+  recess [--json] apps assign [dir] --student <kid-id> [--due YYYY-MM-DD]
+  recess [--json] apps status <build-id>
   recess [--json] applications list [--status SUBMITTED|CLAIMED|ENROLLED|CLOSED]
     [--status-scope active|closed] [--disposition READY_TO_ENROLL|TRIAL|PENDING_FUNDING|NO]
     [--dispositioned true|false] [--quality QUALIFIED|NEEDS_NURTURE|UNKNOWN]
@@ -168,6 +182,8 @@ Usage:
   recess [--json] onboarding generate-summaries <family-id> [--confirm]
   recess [--json] onboarding provision-math-academy <family-id>
     --kid <kid-id> [--grade 1..12] [--confirm]
+  recess [--json] onboarding link-math-academy <family-id>
+    --kid <kid-id> [--student-id <math-academy-student-id>] [--confirm]
   recess [--json] onboarding provision-ixl <family-id>
     --kid <kid-id> [--credentials-file <credentials.json>] [--confirm]
   recess [--json] onboarding remove-ixl <family-id> --kid <kid-id> [--confirm]
@@ -270,6 +286,9 @@ Usage:
   recess [--json] village worlds export <world-id> [--out <bundle.json>] [--confirm]
   recess [--json] village worlds import <world-id> --file <bundle.json> [--confirm]
   recess [--json] village worlds promote <mirror-or-archive-id> [--confirm]
+  recess [--json] village events
+  recess [--json] village link-event --template <template-id>
+    [--room <zone-id>] [--unlink] [--url <https://…>] [--confirm]
   recess [--json] store-items list [--search TEXT]
     [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
     [--page 0] [--limit 20] [--sort-by name|price|createdAt|updatedAt|order]
@@ -344,6 +363,8 @@ Usage:
     [--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 complete <todo-id> --xp N
+    [--confirm --approval-token TOKEN]
   recess [--json] todos delete <todo-id>
     [--confirm --approval-token TOKEN]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>
@@ -413,6 +434,33 @@ monthly top-up cron and are exact-ADMIN on update); descriptive edits
 (name/slug/logo) are ordinary staff writes. "school kid-slots" is the raw
 slot override; "users tier set" is the tier-driven path.
 
+"users lock"/"users unlock" are the CLI twin of the Lock/Unlock buttons on
+recess.gg/ai/students/<kid-id>/admin. They act on the whole account, not one
+person: a KID target is locked or unlocked together with every GUARDIAN in
+their family, because an unlocked kid under a locked guardian is not actually
+unlocked. Unlock grants the kid and guardian access roles, restores the kid's
+Recess channel memberships, sets FLAG_ACCOUNT_UNLOCKED, and notifies the kid's
+live clients; lock is the exact inverse. Rerunning "unlock" on an already
+unlocked account is the "Refresh Unlock" button and is safe. The preview shows
+each affected person's current flag; "users get" is the read.
+
+"users disable" is the harder stop, and a different mechanism: it sets
+User.role to DISABLED, so the account stops resolving in every dashboard,
+search, chat, and todo query at the database layer, and its coherent-feed
+personal data is purged. "users lock" only strips access roles. Disabling is
+SOFT and reversible — "users restore <id> --role ..." puts the account back —
+and it is NOT a GDPR erasure; nothing is deleted. A read-only preflight resolves
+the whole family (including members already DISABLED, which ordinary reads hide)
+and each person's billable enrollments. "--whole-family" extends the disable to
+every member of the target's family; ADMIN/MODERATOR members, your own account,
+and anyone already in the destination role are listed under preview.skipped
+rather than silently dropped. A target holding an ACTIVE or PAST_DUE enrollment
+is refused until billing is cancelled or "--allow-billing" deliberately orphans
+the seat. Restore names the role explicitly because DISABLED does not record
+what the account was; ADMIN and MODERATOR are not restorable from the CLI.
+Note that after a disable "users get" and "users search" no longer resolve the
+account — the confirmed write's own response is the record of what changed.
+
 Onboarding notes: "status" and "intake-session" are reads — "intake-session"
 looks up the current IN_PROGRESS session without creating one (prints a "none
 yet" result when absent). "intake-session-create" is the explicit write that