recess-cli 3.0.0 → 3.2.0

package/dist/command-schema.js

@@ -2,6 +2,8 @@ import { CliError } from "./errors.js";
 export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
     "allow-possible-duplicate",
+    "allow-state-modification",
+    "allow-assigned-edits",
     "all-references",
     "analyzed",
     "apply",
@@ -27,6 +29,7 @@ const BOOLEAN_FLAGS = new Set([
     "mirrored",
     "no-collision",
     "no-invite",
+    "open",
     "refresh",
     "resend",
     "restore",
@@ -139,6 +142,15 @@ const AUTHENTICATED_COMMAND_PREFIXES = [
     "village render",
 ];
 const FAMILY_AI_COMMANDS = new Set([
+    "apps assign",
+    "apps list",
+    "apps preview",
+    "apps publish",
+    "apps pull",
+    "apps scaffold",
+    "apps standards",
+    "apps status",
+    "apps validate",
     "chat-logs by-todo",
     "chat-logs get",
     "chat-logs list",
@@ -161,6 +173,7 @@ const FAMILY_AI_COMMANDS = new Set([
     "goals files read",
     "goals files write",
     "goals list",
+    "goals move-module",
     "goals pdf upload",
     "goals queue get",
     "goals queue set",
@@ -179,6 +192,10 @@ const FAMILY_AI_COMMANDS = new Set([
     "students xp-history",
     "todos create",
     "todos edit",
+    "tutor-templates assign",
+    "tutor-templates get",
+    "tutor-templates list",
+    "tutor-templates unassign",
 ]);
 const STAFF_COMMANDS = new Set([
     "cohorts schedule get",
@@ -191,15 +208,6 @@ const STAFF_COMMANDS = new Set([
     "memories history",
     "memories revision",
     "memories restore",
-    "apps assign",
-    "apps list",
-    "apps preview",
-    "apps publish",
-    "apps pull",
-    "apps scaffold",
-    "apps standards",
-    "apps status",
-    "apps validate",
     "cohorts email",
     "cohorts end",
     "cohorts get",
@@ -291,6 +299,9 @@ const STAFF_COMMANDS = new Set([
     "todos delete",
     "todos restore",
     "todos generate-applet",
+    "tutor-templates create",
+    "tutor-templates delete",
+    "tutor-templates update",
     "users get",
     "users tier list-tiers",
     "village events",

package/dist/commands/apps.js

@@ -358,13 +358,22 @@ async function submit(ctx, dir, dryRun) {
     const manifest = await readManifest(dir);
     const link = await readAppLink(dir);
     const name = flagString(ctx.parsed, "name") ?? manifest.title ?? path.basename(dir);
+    // --open ships the folder's frame as written: Studio skips the locked-scaffold check and the
+    // guide's own shell, styles and screens are what the kid gets. Plain apps already own every file.
+    const open = hasFlag(ctx.parsed, "open");
+    if (open && !manifest.template) {
+        throw new CliError("invalid_arguments", "--open is for template apps (manifest.template); a plain app already ships every file as written.");
+    }
+    const template = manifest.template
+        ? { ...manifest.template, ...(open ? { scaffold: false } : {}) }
+        : undefined;
     const body = {
         ...(link?.projectId ? { projectId: link.projectId } : {}),
         name,
         ...(manifest.description ? { description: manifest.description } : {}),
         files,
         contract,
-        ...(manifest.template ? { template: manifest.template } : {}),
+        ...(template ? { template } : {}),
         ...(manifest.primitives?.length ? { primitives: manifest.primitives } : {}),
         dryRun,
     };

package/dist/commands/goal-curriculum.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { flagInteger, positional } from "./shared.js";
+/** Selection files only supply explicit IDs; they never expand a filter into a mutation. */
+export async function readAssignmentSelection(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > 1024 * 1024) {
+        throw new CliError("invalid_arguments", "The assignment selection must be a regular JSON file no larger than 1 MiB.");
+    }
+    const bytes = await fs.readFile(absolutePath);
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The assignment selection must contain valid JSON.");
+    }
+    if (!document ||
+        typeof document !== "object" ||
+        Array.isArray(document) ||
+        Object.keys(document).length !== 1 ||
+        !("todoIds" in document) ||
+        !Array.isArray(document.todoIds) ||
+        !document.todoIds.every((id) => typeof id === "string")) {
+        throw new CliError("invalid_arguments", 'The selection file must contain exactly {"todoIds":["assignment-uuid", ...]}.');
+    }
+    return {
+        todoIds: document.todoIds,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+async function readResolutions(filePath) {
+    const absolutePath = path.resolve(filePath);
+    let bytes;
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile() || stat.size > 1024 * 1024) {
+            throw new CliError("invalid_arguments", "The resolution file must be a regular JSON file no larger than 1 MiB.");
+        }
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `File not found: ${absolutePath}`);
+        }
+        throw error;
+    }
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The resolution file must contain valid JSON.");
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        throw new CliError("invalid_arguments", "The resolution file must contain a JSON object.");
+    }
+    // The backend validates document version, choices, conflict IDs, and whether
+    // each choice is supported by the current three-way comparison.
+    return {
+        document: document,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+export async function runGoalCurriculumCommand({ parsed, api, resolveTemplateId, previewBoundWrite, recoverExecutedPreview, }) {
+    const verb = positional(parsed, 2, "curriculum operation");
+    const [id, session] = await Promise.all([
+        resolveTemplateId(positional(parsed, 3, "template ID or slug")),
+        api.client.GET("/auth/admin-cli/session/").then(unwrap),
+    ]);
+    if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin") {
+        throw new CliError("forbidden", "Curriculum updates require a full-admin session.");
+    }
+    const environment = {
+        actorId: session.user.id,
+        apiOrigin: api.config.apiOrigin,
+    };
+    if (verb === "status" || verb === "retry") {
+        const jobId = flagString(parsed, "job", { required: true });
+        if (verb === "status") {
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                params: { path: { id, jobId } },
+            }));
+        }
+        const requestPreview = {
+            action: "resume the previously approved curriculum job",
+            target: { templateId: id, jobId, ...environment },
+            request: {},
+        };
+        const receipt = await recoverExecutedPreview(requestPreview);
+        const preview = receipt ?? {
+            ...requestPreview,
+            details: {
+                job: unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                    params: { path: { id, jobId } },
+                })),
+                note: "Resumes this job's stored scope and resolutions. Completed goals are not replayed; stale goals require a new preview.",
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/jobs/{jobId}/retry", {
+            params: { path: { id, jobId } },
+            body: {},
+        })));
+    }
+    const goalIds = flagString(parsed, "goals", { required: true })
+        .split(",")
+        .map((value) => value.trim());
+    if (goalIds.some((value) => !value) ||
+        new Set(goalIds).size !== goalIds.length) {
+        throw new CliError("invalid_arguments", "--goals must list distinct, nonempty goal IDs.");
+    }
+    if (verb === "backlog") {
+        const dueBefore = flagString(parsed, "due-before");
+        return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/backlog", {
+            params: {
+                path: { id },
+                query: { goalIds: goalIds.join(","), dueBefore },
+            },
+        }));
+    }
+    const targetVersion = flagInteger(parsed, "version", {
+        required: true,
+        min: 1,
+    });
+    const filePath = flagString(parsed, "resolutions-file", {
+        required: verb === "validate-resolutions",
+    });
+    const resolutionFile = filePath ? await readResolutions(filePath) : undefined;
+    const body = {
+        goalIds,
+        targetVersion,
+        resolutions: resolutionFile?.document ?? { version: 1, resolutions: [] },
+    };
+    const requestPreview = {
+        action: verb === "reverse"
+            ? "merge a prior template curriculum version into the selected student goals"
+            : "merge the selected template curriculum version into the selected student goals",
+        target: { templateId: id, goalIds, ...environment },
+        request: { ...body, resolutionFile: resolutionFile?.file ?? null },
+    };
+    const receipt = verb === "apply" || verb === "reverse"
+        ? await recoverExecutedPreview(requestPreview)
+        : null;
+    const comparison = receipt
+        ? receipt.details?.comparison
+        : unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/preview", {
+            params: { path: { id } },
+            body,
+        }));
+    if (verb === "preview" || verb === "validate-resolutions") {
+        return { ...comparison, resolutionFile: resolutionFile?.file ?? null };
+    }
+    if (verb !== "apply" && verb !== "reverse") {
+        throw new CliError("invalid_arguments", "Use curriculum backlog|preview|validate-resolutions|apply|status|retry|reverse.");
+    }
+    const preview = receipt ?? {
+        ...requestPreview,
+        details: {
+            comparison,
+            note: "Only the exact selected goals are included. Unresolved conflicts block their goal. Assignments and earned history remain protected; reverse updates preserve changes made since the earlier version.",
+        },
+    };
+    return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/apply", {
+        params: { path: { id } },
+        body: {
+            ...body,
+            fingerprint: comparison.fingerprint,
+            operationKey: flagString(parsed, "operation-key", {
+                required: true,
+            }),
+        },
+    })));
+}
+//# sourceMappingURL=goal-curriculum.js.map

package/dist/help.js

@@ -28,8 +28,8 @@ Usage:
   recess [--json] jobs prune [--older-than-days 30]
   recess [--json] feedback list [--limit 20]
   recess [--json] feedback submit <text> [--confirm]
-  recess [--json] auth login [--client-id ID] [--callback-port 8765]
-  recess [--json] auth request [--label TEXT]
+  recess [--json] auth login [--client-id ID] [--callback-port 8765] [--duration 12h|30d]
+  recess [--json] auth request [--label TEXT] [--duration 12h|30d]
   recess [--json] auth poll [--timeout 300]
   recess [--json] auth status|logout
   recess [--json] users search <name-or-id> [--limit 10]
@@ -78,8 +78,8 @@ Usage:
   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 validate [dir] [--name TEXT] [--open] [--no-wait]
+  recess [--json] apps publish [dir] [--name TEXT] [--open] [--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]
@@ -339,6 +339,29 @@ Usage:
     [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
     [--limit 20] [--cursor <id>]
   recess [--json] goal-templates get <template-id|slug> [--spec-only]
+  recess [--json] goal-templates policy <template-id|slug>
+  recess [--json] goal-templates set-policy <template-id|slug> --recipe KEY
+    [--target-modules N] [--required-modules N|all] --expected-version N
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates migrate-policy <template-id|slug> --students ID,ID
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates student-policy <template-id|slug> --goal ID
+    --file <path/edit.json> [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates retire-assignments <template-id|slug> --goal ID
+    [--todos ID,ID | --todos-file <path/selection.json>]
+    --retirement-reason TEXT [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum backlog <template-id|slug>
+    --goals ID,ID [--due-before YYYY-MM-DD]
+  recess [--json] goal-templates curriculum preview <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+  recess [--json] goal-templates curriculum validate-resolutions <template-id|slug>
+    --goals ID,ID --version N --resolutions-file <path/resolutions.json>
+  recess [--json] goal-templates curriculum apply|reverse <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum status <template-id|slug> --job ID
+  recess [--json] goal-templates curriculum retry <template-id|slug> --job ID
+    [--confirm --approval-token TOKEN]
   recess [--json] goal-templates versions <template-id> [--version N]
   recess [--json] goal-templates validate-spec --file <path/template.json>
   recess [--json] goal-templates create --file <path/template.json>
@@ -382,6 +405,8 @@ Usage:
     [--confirm --approval-token TOKEN]
   recess [--json] goals unarchive <goal-id> --student <kid-id>
     [--confirm --approval-token TOKEN]
+  recess [--json] goals move-module <module-ref> --student <kid-id> --goal <goal-id>
+    (--to-end | --position <n>) [--confirm --approval-token TOKEN]
   recess [--json] goals queue get <goal-id> --student <kid-id>
   recess [--json] goals queue set <goal-id> --student <kid-id>
     --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -412,6 +437,19 @@ Usage:
   recess [--json] rocky get --student <kid-id>
   recess [--json] rocky set --student <kid-id> --patch-file <path/patch.json>
     --expected-updated-at ISO|none [--confirm]
+  recess [--json] tutor-templates list [--q TEXT] [--subject TEXT] [--grade N]
+  recess [--json] tutor-templates get <slug>
+  recess [--json] tutor-templates assign <slug> [--student <kid-id>] [--confirm]
+  recess [--json] tutor-templates unassign <slug> [--student <kid-id>] [--confirm]
+  recess [--json] tutor-templates create --slug SLUG --title TEXT --summary TEXT
+    --subject TEXT --cadence TEXT --body-file <path.md> [--lessons-dir <dir>]
+    [--emoji TEXT] [--grade-min N] [--grade-max N]
+    [--visibility PUBLIC|STAFF] [--confirm]
+  recess [--json] tutor-templates update <slug> [--title TEXT] [--summary TEXT]
+    [--subject TEXT] [--cadence TEXT] [--body-file <path.md>]
+    [--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 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>
@@ -420,11 +458,13 @@ Usage:
     (--goal <goal-id> | --draft <draft-slug>)
     --output-dir <local-dir>
   recess [--json] goals files push --source-dir <local-checkout>
-    [--message TEXT] [--confirm --approval-token TOKEN]
+    [--message TEXT] [--allow-state-modification] [--allow-assigned-edits]
+    [--confirm --approval-token TOKEN]
   recess [--json] goals files write --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>)
     (--source-dir <local-dir> | --source-file <local-file> --path P)
-    [--message TEXT] [--confirm --approval-token TOKEN]
+    [--message TEXT] [--allow-state-modification] [--allow-assigned-edits]
+    [--confirm --approval-token TOKEN]
   recess [--json] goals pdf upload --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
     [--path uploads/name.pdf] [--message TEXT]
@@ -436,6 +476,14 @@ bundled into this npm package. Load os-v2-goal-template-builder and its
 references/deterministic-workflow-setup.md BEFORE authoring a template; that is
 the same guidance the recess.gg/ai agent follows, so there is exactly one
 standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetches).
+Goal file writes/pushes warn and refuse curriculum edits with unfinished assignments
+unless --allow-assigned-edits is supplied. This can change lessons while a student
+is working; assignments are not retired/completed and student answers are not merged.
+The flag requires a fresh preview and confirmation; revision checks still apply.
+Goal file writes/pushes require --allow-state-modification to modify state or
+student-work folders, or replace/delete an existing resources/artifacts file.
+Review the protected paths in the warning; the flag does not preserve answers
+automatically or bypass assignment/revision checks. Adding it needs a new preview.
 For goal workspace and PDF commands, --student names the goal owner. A
 full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
 family_ai sessions remain limited to managed KID profiles.
@@ -528,7 +576,8 @@ cannot call /admin; KID sessions cannot call any non-Village API command. For a
 cloud agent that has no local browser to open, "auth request" prints an approval URL; whoever
 opens it and approves in a signed-in web session grants THEIR OWN scope, so a guardian approving
 mints a family-scoped session and only an admin can mint a full-admin one. "auth poll" then
-collects the 12h session. Kids cannot approve. When it lapses, run "auth request" again for a
+collects the session. Sessions default to 12h; admins can request 30 days with --duration 30d
+on either login or request. Only admins can approve 30-day requests. Kids cannot approve. When it lapses, run "auth request" again for a
 fresh link. Both paths yield the same session.
 
 Skill notes: this CLI's own agent skill ships inside the npm package AND is served

package/package.json

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

package/skill/recess-cli/SKILL.md

@@ -41,7 +41,8 @@ For machine-readable discovery filtered to the current session's locally decoded
 - Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
   Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
   grants family-only access, not staff access. Kids cannot approve.
-- Sessions last 12 hours. `auth status` and `doctor` recheck the live user role and permissions;
+- Sessions default to 12 hours. Admins can use `auth login --duration 30d` locally or
+  `auth request --duration 30d` remotely; only an admin can approve a 30-day request. `auth status` and `doctor` recheck the live user role and permissions;
   discovery stays local and may reflect the minted scope until the next login.
 - `auth logout` clears the stored session.
 - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.
@@ -90,7 +91,7 @@ bundles/authorized URLs. `/mcp/legacy` temporarily retains `recess_exec({command
 
 ## Building Studio apps (`recess apps`)
 
-Guides build Recess Studio apps in their own editor and publish them with the CLI; Studio never
+Guides and guardians build Recess Studio apps in their own editor and publish them with the CLI; Studio never
 prompts a model for them.
 
 - `recess --json apps init <dir> --reason "..."` writes the locked scaffold plus `AGENTS.md` (the

package/skill/recess-cli/agents/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "3.0.0",
-  "minCliVersion": "3.0.0"
+  "version": "3.2.0",
+  "minCliVersion": "3.2.0"
 }