recess-cli 2.3.0 → 2.5.0

package/README.md

@@ -22,6 +22,29 @@ recess setup --reason "Install and update the Recess agent skill"
 
 Publishing rides the production deploy (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR to `staging`, and it publishes when `staging` promotes to `production`. A production deploy that did not bump the version is a no-op — a `gate` job checks the version against npm first. The same workflow is still dispatchable by hand for out-of-band releases. pnpm packs the CLI so the workspace `catalog:` dependency becomes a real range; npm then publishes that tarball through the workflow's OIDC trusted-publishing path. The registry-side publisher must be configured as described in `docs/codebase/admin-cli.md`.
 
+## Building Studio apps with your agent
+
+```bash
+recess apps init my-applet --reason "New applet"      # scaffold + AGENTS.md (the contract your agent follows)
+# build it in your editor with Claude Code / Codex / Cursor, then:
+recess --json apps validate my-applet --reason "Check it"   # Studio's validation, nothing published
+recess --json apps publish my-applet --reason "Ship it"     # validation + independent review → live at appUrl
+recess --json apps list --reason "See my apps"
+recess apps pull <project-id> my-applet --reason "Keep editing"
+```
+
+Guides and staff only. The app folder keeps its project id in `.recess/app.json`, so publishing again updates the same app.
+
+For a specific kid, start from their session instead of a blank description:
+
+```bash
+recess --json students todos --student <kid-id> --analyzed --reason "What did they struggle with"
+recess --json students analysis --todo <todo-id> --reason "Read the analysis"
+recess apps init fix-it --for-todo <todo-id> --reason "Build for this gap"   # scaffold + brief.md
+recess --json apps publish fix-it --assign <kid-id> --due 2026-09-01 --reason "Ship it to the kid"
+recess --json apps standards "grade 4 adding fractions" --reason "Find the code"
+```
+
 ## Install (from a checkout — CLI development)
 
 From the monolith root:
@@ -111,7 +134,7 @@ Error or write preview:
 
 Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
 
-`recess --json agent-context` returns the canonical command/flag/positional schema. `recess --json help payout recipients` returns scoped help. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
+`recess --json agent-context` returns the canonical command/flag/positional schema filtered to the scope claim already stored in the current CLI session. Bare help, scoped help, and `agent-context` make no API request; real commands still go through server authorization, while `auth status` and `doctor` perform live session checks. `recess --json help payout recipients` returns scoped help, and human help marks exact-admin commands with `◆`. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
 
 Every command-driven request to the Recess API except `auth` requires `--reason "..."`: a
 non-empty, human-readable purpose of at most 1024 characters. The CLI sends it as
@@ -249,6 +272,7 @@ recess --json students schedule --student <kid-id> --days 30 --reason "Review th
 recess --json students xp-history --student <kid-id> --range month --reason "Review recent XP history"
 recess --json goals list --student <kid-id> --reason "Review the student's goals"
 recess --json todos create --student <kid-id> --title "Read chapter 4" --reason "Add the assigned reading"
+recess --json todos complete <todo-id> --xp 35 --reason "Complete the todo with a 35 XP total reward"
 recess --json goals delete <goal-id> --student <kid-id> --reason "Remove this obsolete goal"
 recess --json todos delete <todo-id> --reason "Remove this disposable todo"
 recess --json todos generate-applet <todo-id> --student <kid-id> --reason "Generate this todo's applet"
@@ -258,7 +282,9 @@ recess --json rocky get --student <kid-id> --reason "Inspect the student's Rocky
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
-into the confirmed request. Applet generation is staff-only: it resolves the todo's latest learning
+into the confirmed request. `todos complete` is staff-only; `--xp` is the target total XP for the
+todo, so its preview reports prior credit and the new delta before the normal completion and reward
+side effects run. Applet generation is also staff-only: it resolves the todo's latest learning
 analysis, defaults the generated todo to tomorrow in the student's timezone, and lets the server
 select v1 or v2 for that student. A guardian cannot target another family, inspect frozen/deleted
 template history, choose todo rewards/completion/internal fields, or use the ADMIN-only

package/dist/args.js

@@ -30,6 +30,7 @@ const BOOLEAN_FLAGS = new Set([
     "skill-only",
     "spec-only",
     "starter-only",
+    "unlink",
     "visual-only",
     "version",
     "wait",

package/dist/cli.js

@@ -8,8 +8,10 @@ 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 { runApplicationsCommand } from "./commands/applications.js";
+import { runAppsCommand } from "./commands/apps.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
 import { runSchoolCommand } from "./commands/school.js";
+import { runVillageEventsCommand } from "./commands/village-events.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
 import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
@@ -91,6 +93,69 @@ async function sessionStatus(config) {
     }
     return { ...result.data, authSource: config.authSource };
 }
+const DISCOVERY_ROLE_BY_SCOPE = {
+    full_admin: "ADMIN",
+    family_ai: "GUARDIAN",
+    guide_students: "GUIDE",
+    village_home: "KID",
+};
+/**
+ * Command discovery is intentionally local: the signed session cookie already
+ * carries the role, CLI scope, and expiry minted at login. Decoding those
+ * unverified claims is safe here because they only hide or reveal help text;
+ * every real command still sends the cookie to the server for authorization.
+ */
+function resolveCommandDiscovery(config) {
+    const signedOut = {
+        scope: null,
+        role: null,
+        source: "signed_out",
+    };
+    const unavailable = {
+        scope: null,
+        role: null,
+        source: "unavailable",
+    };
+    if (!config.sessionCookie)
+        return signedOut;
+    try {
+        const separator = config.sessionCookie.indexOf("=");
+        if (separator < 1)
+            return unavailable;
+        const cookieValue = decodeURIComponent(config.sessionCookie.slice(separator + 1).split(";", 1)[0]);
+        const payloadSegment = cookieValue.split(".")[1];
+        if (!payloadSegment)
+            return unavailable;
+        const value = JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return unavailable;
+        }
+        const claim = value;
+        if (typeof claim.exp !== "number" || !Number.isFinite(claim.exp)) {
+            return unavailable;
+        }
+        if (claim.exp * 1000 <= Date.now()) {
+            return signedOut;
+        }
+        const scope = typeof claim.cliScope === "string" &&
+            Object.hasOwn(DISCOVERY_ROLE_BY_SCOPE, claim.cliScope)
+            ? claim.cliScope
+            : claim.role === "ADMIN" && claim.adminCli === true
+                ? "full_admin"
+                : null;
+        if (!scope || claim.role !== DISCOVERY_ROLE_BY_SCOPE[scope]) {
+            return unavailable;
+        }
+        return {
+            scope,
+            role: DISCOVERY_ROLE_BY_SCOPE[scope],
+            source: "session_claim",
+        };
+    }
+    catch {
+        return unavailable;
+    }
+}
 async function doctor(config, reason) {
     const checks = {
         config: {
@@ -806,6 +871,10 @@ const SCHOOL_TIER_OPTIONS = [
     { id: "platform", name: "Platform Only", defaultClassSlots: 0 },
 ];
 const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
+// Roles `users restore` may hand back. ADMIN and MODERATOR are absent on
+// purpose — a CLI session must never be able to mint staff; promotion has its
+// own paths. The server's POST /admin/users/change-role/ enforces the same set.
+const RESTORABLE_ROLES = ["KID", "GUARDIAN", "GUIDE", "PROGRAM"];
 const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
 const GOAL_TEMPLATE_KINDS = ["SIMPLE", "BLUEPRINT"];
 const GOAL_TEMPLATE_SETUP_AUDIENCES = ["KID_FRIENDLY", "PARENT_SETUP"];
@@ -1510,19 +1579,28 @@ export async function runCommand(argv) {
                 .map((name) => `--${name}`)
                 .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
         }
-        return { help: scopedHelp(HELP, commands, []) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, [], discovery) };
     }
     if (noun === "help" || hasFlag(parsed, "help")) {
         const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
-        return { help: scopedHelp(HELP, commands, scope) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, scope, discovery) };
     }
     validateInvocation(parsed, commands);
     if (noun === "agent-context") {
-        const profiles = await listProfiles();
+        const [profiles, config] = await Promise.all([
+            listProfiles(),
+            resolveConfig(flagString(parsed, "profile")),
+        ]);
+        const discovery = resolveCommandDiscovery(config);
         return agentContext(commands, {
             cliVersion: await readCliVersion(),
             availableProfiles: profiles.profiles.map((profile) => profile.name),
             feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+            discovery,
         });
     }
     if (noun === "profile") {
@@ -1888,8 +1966,11 @@ export async function runCommand(argv) {
             }
             throw new CliError("invalid_arguments", "Use village worlds export|import|promote.");
         }
+        if (verb === "events" || verb === "link-event") {
+            return runVillageEventsCommand({ parsed, api, writeCommand }, verb);
+        }
         if (verb !== "models") {
-            throw new CliError("invalid_arguments", "Use village build …, village library …, village objects …, village worlds …, village models …, or village render …");
+            throw new CliError("invalid_arguments", "Use village build …, village library …, village objects …, village worlds …, village models …, village events, village link-event …, or village render …");
         }
         const action = positional(parsed, 2, "Village model action");
         if (action === "list") {
@@ -2187,6 +2268,140 @@ export async function runCommand(argv) {
             params: { path: { userId } },
         }));
     }
+    if (noun === "users" && (verb === "lock" || verb === "unlock")) {
+        const userId = positional(parsed, 2, "user ID");
+        const locking = verb === "lock";
+        const profile = unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+        const target = profile.user;
+        // Mirrors the recess.gg/ai admin Lock/Unlock buttons exactly: a KID is
+        // locked together with its GUARDIANs (an unlocked kid under a locked
+        // guardian is not actually unlocked), anyone else is treated as the
+        // guardian side alone.
+        const guardians = (target.family?.users ?? []).filter((member) => member.role === "GUARDIAN");
+        const kidIds = target.role === "KID" ? [target.id] : [];
+        const guardianIds = target.role === "KID"
+            ? guardians.map((member) => member.id)
+            : [target.id];
+        const isUnlocked = (attributes) => (attributes ?? []).some((attribute) => attribute.attribute === "FLAG_ACCOUNT_UNLOCKED");
+        const describe = (member) => ({
+            id: member.id,
+            name: [member.firstName, member.lastName].filter(Boolean).join(" "),
+            role: member.role,
+            unlockedNow: isUnlocked(member.attributes),
+        });
+        const affected = [
+            ...(target.role === "KID" ? [describe(target)] : []),
+            ...(target.role === "KID" ? guardians.map(describe) : [describe(target)]),
+        ];
+        const preview = {
+            userId: target.id,
+            name: [target.firstName, target.lastName].filter(Boolean).join(" "),
+            role: target.role,
+            familyId: target.familyId,
+            accountUnlockedNow: target.role === "KID"
+                ? isUnlocked(target.attributes) &&
+                    guardians.every((member) => isUnlocked(member.attributes))
+                : isUnlocked(target.attributes),
+            accountUnlockedAfter: !locking,
+            kidIds,
+            guardianIds,
+            affected,
+        };
+        if (target.role === "KID" && guardianIds.length === 0) {
+            throw new CliError("invalid_arguments", `${preview.name || target.id} has no GUARDIAN in their family, so ${verb}ing the kid alone would leave the account in a mixed state. Resolve the family's guardians first.`, 1, { preview });
+        }
+        const body = { kidIds, guardianIds };
+        return writeCommand(parsed, {
+            action: locking
+                ? "lock the account: revoke the kid and guardian access roles, drop the kid from their Recess channels, and clear FLAG_ACCOUNT_UNLOCKED"
+                : "unlock the account: grant the kid and guardian access roles, restore the kid's Recess channel memberships, and set FLAG_ACCOUNT_UNLOCKED (the kid's clients are notified live)",
+            target: { userId: target.id, kidIds, guardianIds },
+            request: body,
+            details: preview,
+        }, async () => unwrap(await api.client.POST(locking ? "/admin/users/lock/" : "/admin/users/unlock/", { body })));
+    }
+    if (noun === "users" && (verb === "disable" || verb === "restore")) {
+        const userId = positional(parsed, 2, "user ID");
+        const disabling = verb === "disable";
+        // Restoring is one person at a time on purpose: DISABLED does not record
+        // what the account used to be, so the caller must name the role. --family
+        // would have to guess one per member.
+        const wholeFamily = disabling && hasFlag(parsed, "whole-family");
+        const role = disabling
+            ? "DISABLED"
+            : assertChoice(flagString(parsed, "role", { required: true }).toUpperCase(), RESTORABLE_ROLES, "--role");
+        // Server-resolved preflight (admin-cli.md C3): who else is in the family,
+        // who is already DISABLED, and who still has billable enrollments. It reads
+        // through findUnique, so it also resolves an already-disabled target — that
+        // is what makes a rerun (and every restore) previewable.
+        const state = unwrap(await api.client.GET("/admin/users/{userId}/role-preflight/", {
+            params: { path: { userId } },
+        }));
+        const describe = (member) => ({
+            id: member.id,
+            name: [member.firstName, member.lastName].filter(Boolean).join(" "),
+            role: member.role,
+            email: member.email,
+            billableEnrollments: member.billableEnrollments,
+            // Informational: a role change does NOT revoke these. Stripping access
+            // roles is what `users lock` does — run it alongside a disable when the
+            // account should also lose its grants.
+            accessRoles: member.accessRoles,
+        });
+        const candidates = wholeFamily ? state.members : [state.target];
+        const skipped = [];
+        const acting = [];
+        for (const member of candidates) {
+            const entry = describe(member);
+            if (member.id === state.actorId) {
+                skipped.push({ ...entry, reason: "this is your own account" });
+                continue;
+            }
+            if (member.role === "ADMIN" || member.role === "MODERATOR") {
+                skipped.push({
+                    ...entry,
+                    reason: `${member.role} accounts are never role-changed from the CLI`,
+                });
+                continue;
+            }
+            if (disabling && member.disabled) {
+                skipped.push({ ...entry, reason: "already DISABLED" });
+                continue;
+            }
+            if (!disabling && !member.disabled) {
+                skipped.push({ ...entry, reason: `already ${member.role}` });
+                continue;
+            }
+            acting.push(entry);
+        }
+        const preview = {
+            userId,
+            family: state.family,
+            role,
+            [disabling ? "disabling" : "restoring"]: acting,
+            skipped,
+        };
+        if (acting.length === 0) {
+            throw new CliError("no_op", `Nothing to ${verb}: every candidate was skipped. See preview.skipped for why.`, 1, { preview });
+        }
+        const billing = acting.filter((member) => member.billableEnrollments > 0);
+        if (disabling && billing.length > 0 && !hasFlag(parsed, "allow-billing")) {
+            throw new CliError("billable_enrollments", `${billing
+                .map((member) => `${member.name} (${member.billableEnrollments})`)
+                .join(", ")} still hold ACTIVE or PAST_DUE enrollments. Cancel billing first, or rerun with --allow-billing to orphan those paid seats deliberately.`, 1, { preview });
+        }
+        const body = { userIds: acting.map((member) => member.id), role };
+        return writeCommand(parsed, {
+            action: disabling
+                ? `disable ${acting.length} account(s): set User.role to DISABLED, which hides them from every dashboard, search, chat, and todo query, and purges their coherent-feed personal data. Soft and reversible via users restore — this is NOT a GDPR erasure`
+                : `restore ${acting.length} account(s) from DISABLED to ${role}`,
+            target: { userId, userIds: body.userIds, family: state.family },
+            request: body,
+            details: preview,
+        }, async () => unwrap(await api.client.POST("/admin/users/change-role/", { body })));
+    }
     if (noun === "guides" && verb === "create") {
         const email = flagString(parsed, "email", { required: true })
             .trim()
@@ -2323,6 +2538,9 @@ export async function runCommand(argv) {
     if (noun === "applications" || noun === "quotes") {
         return runApplicationsCommand({ parsed, api, writeCommand });
     }
+    if (noun === "apps") {
+        return runAppsCommand({ parsed, api, writeCommand });
+    }
     if (noun === "school") {
         return runSchoolCommand({ parsed, api, writeCommand });
     }
@@ -4029,6 +4247,25 @@ export async function runCommand(argv) {
                 },
             }));
         }
+        if (verb === "todos") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const limit = flagNumber(parsed, "limit");
+            return unwrap(await api.client.GET("/studio/students/{studentId}/todos", {
+                params: {
+                    path: { studentId },
+                    query: {
+                        ...(limit === undefined ? {} : { limit }),
+                        ...(hasFlag(parsed, "analyzed") ? { analyzed: true } : {}),
+                    },
+                },
+            }));
+        }
+        if (verb === "analysis") {
+            const todoId = flagString(parsed, "todo", { required: true });
+            return unwrap(await api.client.GET("/studio/todos/{todoId}/analysis", {
+                params: { path: { todoId } },
+            }));
+        }
         if (verb === "xp-history") {
             const kidId = flagString(parsed, "student", { required: true });
             const range = flagString(parsed, "range");
@@ -4042,7 +4279,7 @@ export async function runCommand(argv) {
                 },
             }));
         }
-        throw new CliError("invalid_arguments", "Use students list|today|schedule|xp-history|upload-map-scores.");
+        throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|upload-map-scores.");
     }
     if (noun === "todos") {
         if (verb === "create") {
@@ -4070,6 +4307,7 @@ export async function runCommand(argv) {
             const todoId = positional(parsed, 2, "todo ID");
             const patchFile = flagString(parsed, "patch-file", { required: true });
             const body = (await readJsonFile(patchFile, "Todo patch file"));
+            const sessionRole = await resolveSessionRole(api);
             const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
                 params: { path: { id: todoId } },
             }));
@@ -4082,8 +4320,73 @@ export async function runCommand(argv) {
                     expectedUpdatedAt: current.updatedAt,
                     patch: body,
                 },
+                details: sessionRole === "ADMIN"
+                    ? {
+                        writeRoute: "/admin/todos/{id} (staff route; supports the full typed todo patch)",
+                    }
+                    : {
+                        writeRoute: "/tutor/browser/todos/{id} (family-scoped field allowlist)",
+                    },
+            };
+            return previewBoundWrite(parsed, preview, async () => sessionRole === "ADMIN"
+                ? unwrap(await api.client.PATCH("/admin/todos/{id}", {
+                    params: { path: { id: todoId } },
+                    body: body,
+                }))
+                : unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+                    params: { path: { id: todoId } },
+                    body,
+                })));
+        }
+        if (verb === "complete") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const targetXp = flagNumber(parsed, "xp");
+            if (targetXp === undefined ||
+                !Number.isInteger(targetXp) ||
+                targetXp <= 0) {
+                throw new CliError("invalid_arguments", "--xp must be a positive integer. It is the target total XP credited for this todo; prior awards count toward that total.");
+            }
+            const [currentResponse, detailsResponse] = await Promise.all([
+                api.client.GET("/tutor/browser/todos/{id}/", {
+                    params: { path: { id: todoId } },
+                }),
+                api.client.GET("/admin/todos/{id}/details", {
+                    params: { path: { id: todoId } },
+                }),
+            ]);
+            const current = unwrap(currentResponse);
+            const completionXpAwarded = unwrap(detailsResponse).totalXpAwarded ?? 0;
+            if (current.status === "COMPLETED") {
+                throw new CliError("already_completed", `Todo ${todoId} ("${current.title}") is already completed with ${completionXpAwarded} completion XP credited.`);
+            }
+            const body = {
+                status: "COMPLETED",
+                xpReward: targetXp,
+                expectedUpdatedAt: current.updatedAt,
+            };
+            const newXp = Math.max(0, targetXp - completionXpAwarded);
+            const preview = {
+                action: "complete a todo through the staff reward path and set its total credited XP target",
+                target: {
+                    todoId,
+                    studentUserId: current.userId,
+                    studentName: [current.user.firstName, current.user.lastName]
+                        .filter(Boolean)
+                        .join(" ") || null,
+                    title: current.title,
+                    status: current.status,
+                    goal: current.goal,
+                },
+                request: body,
+                details: {
+                    alreadyAwardedXp: completionXpAwarded,
+                    targetTotalXp: targetXp,
+                    newlyAwardedXp: newXp,
+                    configuredCoinReward: current.reward,
+                    note: `The XP ledger is delta-guarded: this writes at most ${newXp} new XP so the todo reaches ${targetXp} total. Completion also claims any unawarded portion of the todo's configured ${current.reward}-coin reward, replaces its active completion analysis with a manual-completion record, records completion activity, may complete a linked goal module and its configured rewards, and may notify the parent through the normal completion pipeline.`,
+                },
             };
-            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/admin/todos/{id}", {
                 params: { path: { id: todoId } },
                 body,
             })));
@@ -4156,7 +4459,7 @@ export async function runCommand(argv) {
                 body: targetDueDateISO ? { targetDueDateISO } : {},
             })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|delete|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|complete|delete|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });