recess-cli 3.4.0 → 3.5.0

package/dist/api.js

@@ -167,6 +167,23 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    async uploadChannelImage(channelId, image, fileName, mimeType) {
+        this.requireAuth();
+        const formData = new FormData();
+        const arrayBuffer = image.buffer.slice(image.byteOffset, image.byteOffset + image.byteLength);
+        formData.append("file", new Blob([arrayBuffer], { type: mimeType }), fileName);
+        const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
+        const response = await fetch(new URL(`/admin/channels/${encodeURIComponent(channelId)}/image`, this.config.apiOrigin), {
+            method: "POST",
+            headers,
+            body: formData,
+        });
+        const body = await readResponseBody(response);
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
     async uploadMapTestScores(studentId, pdf, fileName) {
         this.requireAuth();
         const formData = new FormData();

package/dist/cli.js

@@ -10,7 +10,10 @@ import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, sc
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
 import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
+import { runChannelsCommand } from "./commands/channels.js";
 import { runChatLogsCommand } from "./commands/chat-logs.js";
+import { runRoomsCommand } from "./commands/rooms.js";
+import { runFamiliesCommand } from "./commands/families.js";
 import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
 import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
@@ -308,6 +311,7 @@ async function localWriteCommand(parsed, preview, execute) {
 const GOAL_WORKSPACE_WRITE_MAX_FILES = 1_000;
 const GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
 const GOAL_PDF_UPLOAD_MAX_BYTES = 1024 * 1024 * 1024;
+const GOAL_VIDEO_UPLOAD_MAX_BYTES = 500 * 1024 * 1024;
 const GOAL_QUEUE_MAX_ENTRIES = 500;
 const URL_QUEUE_DESCRIPTION_POINTER = "Skill queue managed by the system.";
 const RECESS_GIT_METADATA = "recess-workspace.json";
@@ -4259,6 +4263,7 @@ export async function executeRecessCommand(argv, options = {}) {
                 (!Number.isInteger(coinAmount) || coinAmount < 1)) {
                 throw new CliError("invalid_arguments", "--coin-amount must be a positive integer.");
             }
+            const visibility = flagString(parsed, "visibility");
             const isStarterRaw = flagString(parsed, "is-starter");
             const setupAudienceRaw = flagString(parsed, "setup-audience");
             const isStarter = isStarterRaw === undefined
@@ -4300,6 +4305,11 @@ export async function executeRecessCommand(argv, options = {}) {
                 ...(kind
                     ? { kind: assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind") }
                     : {}),
+                ...(visibility
+                    ? {
+                        visibility: assertChoice(visibility, ["PUBLIC", "PRIVATE", "STAFF_ONLY"], "--visibility"),
+                    }
+                    : {}),
                 ...(agentInstructionsFile
                     ? {
                         agentInstructions: await fs.readFile(path.resolve(agentInstructionsFile), "utf8"),
@@ -4316,7 +4326,7 @@ export async function executeRecessCommand(argv, options = {}) {
             // shape that caused the template incident; editing an existing spec goes
             // through the guarded /ai patch path with its destructive-change token.
             if (Object.keys(body).length === 1) {
-                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --image-url, --coin-amount, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --image-url, --coin-amount, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --visibility, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
@@ -4334,7 +4344,7 @@ export async function executeRecessCommand(argv, options = {}) {
             }));
             const prompt = flagString(parsed, "prompt");
             return writeCommand(parsed, {
-                action: "queue paid GPT-Image-2 art regeneration",
+                action: "queue paid challenge-art regeneration",
                 target: {
                     templateId: id,
                     slug: current.slug,
@@ -4342,7 +4352,7 @@ export async function executeRecessCommand(argv, options = {}) {
                 },
                 request: { prompt: prompt ?? null },
                 details: {
-                    costNote: "This queues one paid 1024×1024 GPT-Image-2 generation and replaces the template image when it finishes. New templates already generate art automatically.",
+                    costNote: "This queues one paid 1024×1024 challenge-art painting (the shared lane behind /challenges-v2, from the category's style reference; ~$0.02) and replaces the template image when it finishes. New templates already generate art automatically.",
                 },
             }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/generate-image", {
                 params: { path: { id } },
@@ -4557,7 +4567,29 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|generate-image|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
     }
-    if (noun === "goals" && verb !== "files" && verb !== "pdf") {
+    if (noun === "goals" && verb === "adaptations") {
+        const action = positional(parsed, 2, "goals adaptations action");
+        const studentId = flagString(parsed, "student", { required: true });
+        const goalId = flagString(parsed, "goal", { required: true });
+        if (action === "list") {
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/adaptations", { params: { path: { studentId, goalId } } }));
+        }
+        if (action === "diff") {
+            const runId = positional(parsed, 3, "adaptation run ID");
+            const path = flagString(parsed, "path");
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/adaptations/{runId}/diff", {
+                params: {
+                    path: { studentId, goalId, runId },
+                    query: path ? { path } : {},
+                },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use goals adaptations list|diff.");
+    }
+    if (noun === "goals" &&
+        verb !== "files" &&
+        verb !== "pdf" &&
+        verb !== "video") {
         if (verb === "complete" || verb === "undo-completion") {
             const goalId = positional(parsed, 2, "goal ID");
             const undo = verb === "undo-completion";
@@ -5049,11 +5081,20 @@ export async function executeRecessCommand(argv, options = {}) {
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|queue|files|pdf|video.");
+    }
+    if (noun === "channels") {
+        return runChannelsCommand({ parsed, api, writeCommand });
+    }
+    if (noun === "families") {
+        return runFamiliesCommand({ parsed, api, writeCommand });
     }
     if (noun === "chat-logs") {
         return runChatLogsCommand({ parsed, api, writeCommand });
     }
+    if (noun === "rooms") {
+        return runRoomsCommand({ parsed, api, writeCommand });
+    }
     if (noun === "students") {
         if (verb === "list") {
             const requestedScope = flagString(parsed, "scope");
@@ -5626,6 +5667,64 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         throw new CliError("invalid_arguments", "Use tutor-templates list|get|create|update|delete|assign|unassign.");
     }
+    if (noun === "goals" && verb === "video") {
+        const action = positional(parsed, 2, "goals video action");
+        if (action !== "upload") {
+            throw new CliError("invalid_arguments", "Use goals video upload.");
+        }
+        const sourceFile = flagString(parsed, "source-file", { required: true });
+        const absolutePath = path.resolve(sourceFile);
+        const fileStat = await fs.lstat(absolutePath).catch(() => null);
+        if (!fileStat?.isFile() || fileStat.isSymbolicLink()) {
+            throw new CliError("invalid_arguments", `--source-file is not a file: ${absolutePath}`);
+        }
+        if (!absolutePath.toLowerCase().endsWith(".mp4")) {
+            throw new CliError("invalid_arguments", "goals video upload accepts .mp4 files only (H.264 plays everywhere).");
+        }
+        if (fileStat.size <= 0 || fileStat.size > GOAL_VIDEO_UPLOAD_MAX_BYTES) {
+            throw new CliError("invalid_arguments", `Video size must be between 1 byte and ${GOAL_VIDEO_UPLOAD_MAX_BYTES} bytes.`);
+        }
+        const fileName = path.basename(absolutePath);
+        const sourceSha256 = await sha256File(absolutePath);
+        const preview = {
+            action: "publish a video at a public, unlisted URL",
+            target: { fileName },
+            request: {
+                sourceFile: absolutePath,
+                sourceSha256,
+                sizeBytes: fileStat.size,
+            },
+            details: {
+                note: "Anyone with the returned URL can watch it. Paste the URL into a goal module or template (with a short transcript so Rocky knows what it covers); Rocky opens it in the browser.",
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => {
+            const signed = unwrap(await api.client.POST("/os-v2-mesa/goal-videos/sign", {
+                body: { fileName, sizeBytes: fileStat.size },
+            }));
+            const bytes = await fs.readFile(absolutePath);
+            if (createHash("sha256").update(bytes).digest("hex") !== sourceSha256) {
+                throw new CliError("source_changed", "The video changed after approval; preview the current file again.");
+            }
+            const response = await fetch(signed.uploadUrl, {
+                method: "PUT",
+                headers: signed.uploadHeaders,
+                body: uploadBody(bytes),
+            });
+            if (!response.ok) {
+                throw new CliError("upload_failed", `Video upload failed with HTTP ${response.status}.`);
+            }
+            const done = unwrap(await api.client.POST("/os-v2-mesa/goal-videos/complete", {
+                body: { assetId: signed.assetId },
+            }));
+            return {
+                action: "upload_goal_video",
+                url: done.url,
+                fileName,
+                sizeBytes: fileStat.size,
+            };
+        });
+    }
     if (noun === "goals" && verb === "pdf") {
         const action = positional(parsed, 2, "goals pdf action");
         if (action !== "upload") {

package/dist/command-schema.js

@@ -26,10 +26,12 @@ const BOOLEAN_FLAGS = new Set([
     "keep-tokens",
     "include-deleted",
     "include-archived",
+    "include-left",
     "json",
     "mirrored",
     "no-collision",
     "no-invite",
+    "no-join",
     "open",
     "refresh",
     "resend",
@@ -165,6 +167,8 @@ const FAMILY_AI_COMMANDS = new Set([
     "goal-templates list",
     "goal-templates snapshot-files",
     "goal-templates validate-spec",
+    "goals adaptations diff",
+    "goals adaptations list",
     "goals archive",
     "goals create",
     "goals edit",
@@ -177,6 +181,7 @@ const FAMILY_AI_COMMANDS = new Set([
     "goals list",
     "goals move-module",
     "goals pdf upload",
+    "goals video upload",
     "goals queue get",
     "goals queue set",
     "goals unarchive",
@@ -200,6 +205,8 @@ const FAMILY_AI_COMMANDS = new Set([
     "tutor-templates unassign",
 ]);
 const STAFF_COMMANDS = new Set([
+    "rooms transcripts get",
+    "rooms transcripts search",
     "cohorts schedule get",
     "cohorts schedule set",
     "cohorts schedule changes",

package/dist/commands/apps.js

@@ -212,7 +212,7 @@ function agentsGuide(docs) {
         "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).",
+        "- contract.json — the BuildContract: copy the example in the contract.json section below.",
         '- manifest.json — { "title": "...", "description": "...", "template": { "ccss": "5.NF.A.1", "modes": ["prepare","remediate"], "misconceptions": ["..."] } }',
         "",
         'Then: `recess apps validate --reason "..."` (reports without publishing) and',
@@ -228,6 +228,10 @@ function agentsGuide(docs) {
         "",
         "---",
         "",
+        docs.contract ?? "",
+        "",
+        "---",
+        "",
         docs.pedagogy ? `# Pedagogy\n\n${docs.pedagogy}` : "",
         "",
         "---",

package/dist/commands/channels.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagNumber, flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { assertChoice, positional } from "./shared.js";
+// Runtime mirrors of the generated unions; `satisfies` fails the build if the
+// backend enums move.
+const CHANNEL_TYPES = [
+    "COMMUNITY",
+    "SYSTEM_GENERATED",
+    "COHORT_PARENT",
+    "DIRECT_MESSAGE",
+    "GROUP_MESSAGE",
+    "COURSE_REQUEST",
+    "RECESS_EVENT",
+    "LFG_GROUP",
+    "CHALLENGE_FINISHERS",
+    "RECESS",
+    "STREAMING",
+];
+const LIST_TYPES = [
+    ...CHANNEL_TYPES,
+    "WORLD",
+];
+const AUDIENCES = ["KID", "PARENT"];
+const STATUSES = [
+    "ACTIVE",
+    "HIDDEN",
+    "ARCHIVED",
+];
+const MEMBER_ROLES = [
+    "MEMBER",
+    "MODERATOR",
+    "ADMIN",
+];
+/** The type set post.channel-image.ts accepts, keyed by extension. */
+const IMAGE_MIME_BY_EXT = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+async function readChannelImage(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const mimeType = IMAGE_MIME_BY_EXT[path.extname(absolutePath).toLowerCase()];
+    if (!mimeType) {
+        throw new CliError("invalid_arguments", "The image must be a .png, .jpg, .jpeg, .gif, or .webp file.");
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `Image file does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    if (bytes.byteLength > MAX_IMAGE_BYTES) {
+        throw new CliError("invalid_arguments", "The image must be 10MB or smaller.");
+    }
+    return {
+        bytes,
+        fileName: path.basename(absolutePath),
+        mimeType,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
+export async function runChannelsCommand({ parsed, api, writeCommand, }) {
+    const verb = parsed.positionals[1];
+    if (verb === "list") {
+        const type = flagString(parsed, "type");
+        const audience = flagString(parsed, "audience");
+        const status = flagString(parsed, "status");
+        const limit = flagNumber(parsed, "limit");
+        if (limit !== undefined &&
+            (!Number.isInteger(limit) || limit < 1 || limit > 200)) {
+            throw new CliError("invalid_arguments", "--limit must be an integer from 1 to 200.");
+        }
+        const q = parsed.positionals.slice(2).join(" ").trim();
+        return unwrap(await api.client.GET("/admin/channels/", {
+            params: {
+                query: {
+                    ...(type ? { type: assertChoice(type, LIST_TYPES, "--type") } : {}),
+                    ...(audience
+                        ? { audience: assertChoice(audience, AUDIENCES, "--audience") }
+                        : {}),
+                    ...(status
+                        ? { status: assertChoice(status, STATUSES, "--status") }
+                        : {}),
+                    ...(q ? { q } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            },
+        }));
+    }
+    if (verb === "create") {
+        const name = flagString(parsed, "name", { required: true }).trim();
+        if (!name || name.length > 100) {
+            throw new CliError("invalid_arguments", "--name must be 1 to 100 characters.");
+        }
+        const type = assertChoice(flagString(parsed, "type") ?? "COMMUNITY", CHANNEL_TYPES, "--type");
+        const audienceFlag = flagString(parsed, "audience");
+        const audience = audienceFlag === undefined
+            ? undefined
+            : audienceFlag === "NONE"
+                ? null
+                : assertChoice(audienceFlag, AUDIENCES, "--audience");
+        const description = flagString(parsed, "description");
+        const joinAsAdmin = !hasFlag(parsed, "no-join");
+        const imagePath = flagString(parsed, "image");
+        const image = imagePath ? await readChannelImage(imagePath) : undefined;
+        const body = {
+            name,
+            type,
+            joinAsAdmin,
+            ...(audience !== undefined ? { audience } : {}),
+            ...(description !== undefined ? { description } : {}),
+        };
+        return writeCommand(parsed, {
+            action: type === "COMMUNITY"
+                ? `create a ${audience ?? "KID"}-audience community channel that ${audience === "PARENT" ? "guardians" : "kids"} can find and join from Browse`
+                : `create a standalone ${type} channel (not linked to any cohort, event, challenge, or course)`,
+            target: { name, type },
+            // The image's hash is in the approved request, so confirming with a
+            // different file fails the operation-key check.
+            request: image
+                ? {
+                    ...body,
+                    image: {
+                        fileName: image.fileName,
+                        mimeType: image.mimeType,
+                        bytes: image.bytes.byteLength,
+                        sha256: image.sha256,
+                    },
+                }
+                : body,
+            ...(joinAsAdmin
+                ? {}
+                : {
+                    details: {
+                        note: "You will not be a member; use channels join to enter it.",
+                    },
+                }),
+        }, async () => {
+            const channel = unwrap(await api.client.POST("/admin/channels/", { body }));
+            if (!image)
+                return channel;
+            try {
+                const uploaded = (await api.uploadChannelImage(channel.id, image.bytes, image.fileName, image.mimeType));
+                return { ...channel, imageUrl: uploaded.imageUrl };
+            }
+            catch (error) {
+                throw new CliError("partial_failure", `Channel ${channel.id} was created, but its image upload failed: ${error instanceof Error ? error.message : String(error)}. Retry with channels set-image ${channel.id} <path>.`, 1, { channel });
+            }
+        });
+    }
+    if (verb === "set-image") {
+        const channelId = positional(parsed, 2, "channel ID");
+        const imagePath = parsed.positionals[3];
+        const clear = hasFlag(parsed, "clear");
+        if (clear === Boolean(imagePath)) {
+            throw new CliError("invalid_arguments", "Pass an image path or --clear (not both).");
+        }
+        if (clear) {
+            return writeCommand(parsed, {
+                action: "remove the channel's image",
+                target: { channelId },
+                request: { clear: true },
+            }, async () => unwrap(await api.client.DELETE("/admin/channels/{channelId}/image", {
+                params: { path: { channelId } },
+            })));
+        }
+        const image = await readChannelImage(imagePath);
+        return writeCommand(parsed, {
+            action: "upload this image and set it as the channel's image",
+            target: { channelId },
+            request: {
+                fileName: image.fileName,
+                mimeType: image.mimeType,
+                bytes: image.bytes.byteLength,
+                sha256: image.sha256,
+            },
+        }, async () => api.uploadChannelImage(channelId, image.bytes, image.fileName, image.mimeType));
+    }
+    if (verb === "join") {
+        const channelId = positional(parsed, 2, "channel ID");
+        const body = { channelId };
+        return writeCommand(parsed, {
+            action: "join the channel yourself (rejoins if you left)",
+            target: { channelId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/channels/join/", { body })));
+    }
+    if (verb === "members") {
+        const action = parsed.positionals[2];
+        const channelId = positional(parsed, 3, "channel ID");
+        if (action === "list") {
+            return unwrap(await api.client.GET("/admin/channels/{channelId}/members", {
+                params: {
+                    path: { channelId },
+                    query: {
+                        includeLeft: hasFlag(parsed, "include-left") ? "true" : "false",
+                    },
+                },
+            }));
+        }
+        if (action === "add" || action === "set-role" || action === "remove") {
+            const userIds = parsed.positionals.slice(4);
+            if (userIds.length === 0) {
+                throw new CliError("invalid_arguments", "Pass at least one user ID.");
+            }
+            if (new Set(userIds).size !== userIds.length) {
+                throw new CliError("invalid_arguments", "User IDs must be unique.");
+            }
+            // Read-only preflight: the approval preview names the exact channel
+            // (and audience) people are entering or leaving. Only stable fields go
+            // in the preview, since the operation key is bound to its hash.
+            const current = unwrap(await api.client.GET("/admin/channels/{channelId}/members", {
+                params: { path: { channelId }, query: { includeLeft: "false" } },
+            }));
+            const channel = {
+                name: current.channel.name,
+                type: current.channel.type,
+                audience: current.channel.audience,
+                status: current.channel.status,
+            };
+            if (action === "remove") {
+                const active = new Set(current.members.map((m) => m.userId));
+                const notMembers = userIds.filter((id) => !active.has(id));
+                if (notMembers.length > 0) {
+                    throw new CliError("invalid_arguments", `Not active members of this channel: ${notMembers.join(", ")}`);
+                }
+                return writeCommand(parsed, {
+                    action: `remove ${userIds.length} member(s) from the channel (soft: they can be re-added; a LEFT notice posts in the channel)`,
+                    target: { channelId, userIds },
+                    request: { userIds },
+                    details: { channel },
+                }, async () => unwrap(await api.client.POST("/admin/channels/{channelId}/members/remove", { params: { path: { channelId } }, body: { userIds } })));
+            }
+            const role = assertChoice(flagString(parsed, "role", { required: action === "set-role" }) ??
+                "MEMBER", MEMBER_ROLES, "--role");
+            if (action === "set-role") {
+                const active = new Set(current.members.map((m) => m.userId));
+                const notMembers = userIds.filter((id) => !active.has(id));
+                if (notMembers.length > 0) {
+                    throw new CliError("invalid_arguments", `Not active members (use members add): ${notMembers.join(", ")}`);
+                }
+            }
+            const body = { userIds, role };
+            return writeCommand(parsed, {
+                action: action === "set-role"
+                    ? `set the channel role of ${userIds.length} member(s) to ${role}`
+                    : `add ${userIds.length} user(s) to the channel as ${role} (a JOINED notice posts for each new arrival)`,
+                target: { channelId, userIds },
+                request: body,
+                details: { channel },
+            }, async () => unwrap(await api.client.POST("/admin/channels/{channelId}/members", {
+                params: { path: { channelId } },
+                body,
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use channels members list|add|set-role|remove <channel-id> ...");
+    }
+    throw new CliError("invalid_arguments", "Use channels list|create|set-image|join or channels members list|add|set-role|remove.");
+}
+//# sourceMappingURL=channels.js.map

package/dist/commands/families.js

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { unwrap } from "../api.js";
+import { flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { readJsonValue } from "./shared.js";
+export async function runFamiliesCommand({ parsed, api, writeCommand, }) {
+    const verb = parsed.positionals[1];
+    if (verb === "set-addresses") {
+        const filePath = flagString(parsed, "file", { required: true });
+        const { absolutePath, raw, parsed: json, } = await readJsonValue(filePath, "Address file");
+        if (!Array.isArray(json) || json.length === 0) {
+            throw new CliError("invalid_arguments", `Address file must be a non-empty JSON array of {familyId, postalCode?, stateRegion?, city?, streetAddress?, country?, source} (${absolutePath}).`);
+        }
+        const entries = json;
+        const sha256 = createHash("sha256").update(raw).digest("hex");
+        // Read-only preflight: the server's dry run validates every entry and
+        // returns each family's current and proposed address for the approval.
+        const dryRun = unwrap(await api.client.POST("/admin/users/family-addresses/", {
+            body: { dryRun: true, entries },
+        }));
+        const changes = dryRun.results.filter((r) => r.changed);
+        return writeCommand(parsed, {
+            action: `set household addresses on ${changes.length} of ${entries.length} families (the rest already match)`,
+            target: { families: entries.length },
+            request: { file: absolutePath, sha256, entries: entries.length },
+            details: {
+                changes: changes.map((r) => ({
+                    familyId: r.familyId,
+                    before: r.before,
+                    after: r.after,
+                })),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/users/family-addresses/", {
+            body: { dryRun: false, entries },
+        })));
+    }
+    throw new CliError("invalid_arguments", "Use families set-addresses.");
+}
+//# sourceMappingURL=families.js.map

package/dist/commands/rooms.js

@@ -0,0 +1,70 @@
+import { unwrap } from "../api.js";
+import { flagNumber, flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { positional } from "./shared.js";
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+function dateFlag(parsed, name) {
+    const value = flagString(parsed, name);
+    if (value !== undefined && !DATE.test(value)) {
+        throw new CliError("invalid_arguments", `--${name} must be YYYY-MM-DD.`);
+    }
+    return value;
+}
+function intFlag(parsed, name, min, max) {
+    const value = flagNumber(parsed, name);
+    if (value !== undefined &&
+        (!Number.isInteger(value) || value < min || value > max)) {
+        throw new CliError("invalid_arguments", `--${name} must be an integer from ${min} to ${max}.`);
+    }
+    return value;
+}
+export async function runRoomsCommand({ parsed, api, }) {
+    const group = parsed.positionals[1];
+    const verb = parsed.positionals[2];
+    if (group !== "transcripts" || (verb !== "search" && verb !== "get")) {
+        throw new CliError("invalid_arguments", "Use `rooms transcripts search` or `rooms transcripts get <meeting-id>`.");
+    }
+    if (verb === "search") {
+        return unwrap(await api.client.GET("/voice/room-transcripts/", {
+            params: {
+                query: {
+                    roomName: flagString(parsed, "room"),
+                    startDate: dateFlag(parsed, "from"),
+                    endDate: dateFlag(parsed, "to"),
+                    query: flagString(parsed, "query"),
+                    limit: intFlag(parsed, "limit", 1, 20),
+                },
+            },
+        }));
+    }
+    const meetingId = positional(parsed, 3, "meeting ID");
+    const breakoutIndex = intFlag(parsed, "breakout", 0, 1000);
+    const query = flagString(parsed, "query");
+    const read = (offset) => api.client.GET("/voice/room-transcripts/{meetingId}", {
+        params: {
+            path: { meetingId },
+            query: { breakoutIndex, query, offset, maxChars: 30000 },
+        },
+    });
+    const first = unwrap(await read());
+    if (query || first.text === undefined)
+        return first;
+    let text = first.text;
+    let next = first.nextOffset ?? null;
+    while (next !== null) {
+        const page = unwrap(await read(next));
+        if (page.offset !== next || page.text === undefined) {
+            throw new CliError("pagination_error", "Transcript pagination did not advance; no complete download was produced.");
+        }
+        text += page.text;
+        next = page.nextOffset ?? null;
+    }
+    return {
+        ...first,
+        offset: 0,
+        nextOffset: null,
+        text,
+        complete: true,
+    };
+}
+//# sourceMappingURL=rooms.js.map

package/dist/help.js

@@ -67,6 +67,9 @@ Usage:
   recess [--json] chat-logs list --student <user-id> [--limit 100] [--cursor <cursor>]
   recess [--json] chat-logs get <conversation-id>
   recess [--json] chat-logs by-todo <todo-id>
+  recess [--json] rooms transcripts search [--room TEXT] [--from YYYY-MM-DD]
+    [--to YYYY-MM-DD] [--query TEXT] [--limit 10]
+  recess [--json] rooms transcripts get <meeting-id> [--breakout <n>] [--query TEXT]
   recess [--json] students list [--scope mine|family]
   recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
   recess [--json] students schedule --student <kid-id> [--days 14]
@@ -160,6 +163,17 @@ Usage:
   recess [--json] payout items edit <item-id> [--amount-cents N]
     [--description TEXT] [--date YYYY-MM-DD] [--confirm]
   recess [--json] payout items delete <item-id> [--confirm]
+  recess [--json] families set-addresses --file <json> [--confirm]
+  recess [--json] channels list [<query>...] [--type <channel-type>] [--audience KID|PARENT]
+    [--status ACTIVE|HIDDEN|ARCHIVED] [--limit 1..200]
+  recess [--json] channels create --name TEXT [--type <channel-type>]
+    [--audience KID|PARENT|NONE] [--description TEXT] [--image <path>] [--no-join] [--confirm]
+  recess [--json] channels set-image <channel-id> [path] [--clear] [--confirm]
+  recess [--json] channels join <channel-id> [--confirm]
+  recess [--json] channels members list <channel-id> [--include-left]
+  recess [--json] channels members add <channel-id> <user-id...> [--role MEMBER|MODERATOR|ADMIN] [--confirm]
+  recess [--json] channels members set-role <channel-id> <user-id...> --role MEMBER|MODERATOR|ADMIN [--confirm]
+  recess [--json] channels members remove <channel-id> <user-id...> [--confirm]
   recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
   recess [--json] cohorts schedule get <cohort-id>
   recess [--json] cohorts schedule set <cohort-id> --days <MO,WE> --time <09:30> [--timezone <zone>] --effective-date <YYYY-MM-DD> --notify none|parents [--confirm] [--approval-token <token>]
@@ -391,7 +405,7 @@ Usage:
     [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
     [--image-url URL] [--coin-amount N] [--sort-order N] [--is-starter true|false]
     [--setup-audience KID_FRIENDLY|PARENT_SETUP] [--kind SIMPLE|BLUEPRINT]
-    [--agent-instructions-file <path>]
+    [--visibility PUBLIC|PRIVATE|STAFF_ONLY] [--agent-instructions-file <path>]
     [--output-template-file <path>] [--confirm]
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
   recess [--json] goal-templates generate-image <template-id|slug>
@@ -468,6 +482,9 @@ Usage:
     [--lessons-dir <dir>] [--emoji TEXT] [--grade-min N] [--grade-max N]
     [--visibility PUBLIC|STAFF] [--confirm]
   recess [--json] tutor-templates delete <slug> [--confirm]
+  recess [--json] goals adaptations list --student <goal-owner-id> --goal <goal-id>
+  recess [--json] goals adaptations diff <run-id> --student <goal-owner-id>
+    --goal <goal-id> [--path P]
   recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
   recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
   recess [--json] goals files init --student <goal-owner-id> --draft <draft-slug>
@@ -487,6 +504,8 @@ Usage:
     (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
     [--path uploads/name.pdf] [--message TEXT]
     [--confirm --approval-token TOKEN]
+  recess [--json] goals video upload --source-file <local.mp4>
+    [--confirm --approval-token TOKEN]
 
 Authoring notes: "skills" serves the in-product tutor skills (the private
 packages/skills workspace package) read-only over your admin session — they are never
@@ -584,6 +603,25 @@ Class-ops notes: "events cancel" notifies families (chat + parent email blast +
 credit notes + Slack); "events set-status --status CANCELED" is a silent status
 change. Reschedule times are cohort-local wall-clock (zoneless).
 
+Channel notes: channel types are COMMUNITY (default), SYSTEM_GENERATED,
+COHORT_PARENT, DIRECT_MESSAGE, GROUP_MESSAGE, COURSE_REQUEST, RECESS_EVENT,
+LFG_GROUP, CHALLENGE_FINISHERS, RECESS, STREAMING; WORLD channels belong to
+apps/world and can only be listed. Guardians browse PARENT-audience COMMUNITY
+channels and kids browse KID ones; "create" defaults a COMMUNITY channel to KID
+and COHORT_PARENT to PARENT (--audience NONE clears it). Non-community types
+created here stand alone: nothing links them to a cohort, event, challenge, or
+course. "members add" also rejoins past members and applies --role to everyone
+named; kids are refused from PARENT-audience and COHORT_PARENT channels.
+"members remove" is soft (sets leftAt) and posts a LEFT notice. Images
+(--image, set-image) are .png/.jpg/.gif/.webp, 10MB max.
+
+Family address notes: "families set-addresses --file" takes a JSON array of
+{familyId, streetAddress?, city?, stateRegion?, postalCode?, country?, source},
+source one of PARENT|STAFF|APPLICATION|LIGHTFIELD|STRIPE. Country is ISO-2 and
+omitted for US; US ZIPs must be 12345 or 12345-6789. Each entry replaces the
+family's whole address. The preview is the server's dry run: before and after
+for every family that changes.
+
 Payout notes: amounts are integer cents. "payout items add" without --date
 defaults the item date to the penultimate day of the invoice's cycle (its
 endDate minus one day) and shows the computed date in the preview.

package/package.json

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