recess-cli 1.8.0 → 1.9.1

package/README.md

@@ -11,7 +11,7 @@ npm install -g recess-cli
 recess setup
 ```
 
-`setup` installs the bundled skill for both Codex and Claude and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
+`setup` installs the bundled skill in the Codex and Claude Code user directories, which Cursor also discovers for compatibility, and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
 
 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`.
 
@@ -151,6 +151,8 @@ separate `village models` commands edit the Village island's reusable models and
 ```bash
 recess --json skills guardian get recess-goal-authoring --all-references
 recess --json content-library search "fractions through visual puzzles" --limit 8
+recess --json content-library status <gem-id-or-url>
+recess --json content-library set-stage <gem-id-or-url...> --stage archived
 recess --json goal-templates validate-spec --file ./template.json   # iterate; writes nothing
 recess --json goal-templates create --file ./template.json          # preview, exit 2
 recess --json goal-templates create --file ./template.json --confirm
@@ -165,6 +167,27 @@ recess --json goals create --student <kid-id> --draft <draft-slug> --title "..."
 recess --json goals files list --student <kid-id> --goal <goal-id>
 ```
 
+ADMIN discovery batches use the same Content Library admission door as the dashboard. Omit
+`--confirm` to preview the exact payload first. An interactive run asks for Review or polish with
+Review preselected; JSON/non-interactive runs safely default to Review. Use `--stage polish` to
+start automatic decoration immediately:
+
+```bash
+recess --json content-library submit https://example.org/activity --stage review
+recess --json content-library submit --file ./gems.json
+recess --json content-library submit --file ./urls.txt --stage polish --confirm
+```
+
+JSON files are arrays of URL strings or `{ "url", "title"?, "summary"?, "lane"? }` objects;
+plain-text files contain one URL per line. The server checks that the deployed island understands
+the review/polish lifecycle before sending any item, and then writes with concurrency three.
+`content-library status` accepts an exact gem ID (including one returned by search) or URL and
+reports its Review/Polishing/Live/Archived stage plus metadata, cover, and search-index progress.
+`content-library set-stage` accepts one or many IDs/URLs (or a newline/JSON-string-array `--file`),
+previews every resolved current stage, and requires `--confirm`. It uses the same lifecycle as
+Manage: direct-to-Live routes unfinished gems through Polishing, and moving out of Polishing
+cancels that exact run first.
+
 ## Family AI operations
 
 ```bash
@@ -174,13 +197,16 @@ recess --json students schedule --student <kid-id> --days 30
 recess --json students xp-history --student <kid-id> --range month
 recess --json goals list --student <kid-id>
 recess --json todos create --student <kid-id> --title "Read chapter 4"
+recess --json todos generate-applet <todo-id> --student <kid-id> [--due-date YYYY-MM-DD]
 recess --json memories context --student <kid-id>
 recess --json memories log --student <kid-id> --date 2026-08-12
 recess --json rocky get --student <kid-id>
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
-into the confirmed request. A guardian cannot target another family, inspect frozen/deleted
+into the confirmed request. Applet generation is 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
 device-authorization flow. `memories context` and `memories log` read only the tutor repository's
 spine, rules, reminders, and session logs; private guide remarks are never returned. The CLI does

package/dist/cli.js

@@ -130,6 +130,13 @@ Usage:
   recess [--json] store-items set-status <village-store-item-id>
     --status ACTIVE|INACTIVE|COMING_SOON [--confirm]
   recess [--json] content-library search <query> [--limit 8]
+  recess [--json] content-library status <gem-id-or-url>
+  recess [--json] content-library set-stage <gem-id-or-url...> [--file <path>]
+    --stage review|polishing|live|archived [--confirm]
+  recess [--json] content-library submit <url...> [--file <path>]
+    [--stage review|polish] [--title TEXT] [--summary TEXT]
+    [--lane web-toys|mechanics|explorables|data-stories|sims|maps-scale|sound-art|puzzles|wonder|idea-games]
+    [--confirm]
   recess [--json] skills guardian list [--query TEXT] [--category TEXT]
   recess [--json] skills guardian get <skill-name>
     [--reference NAME | --all-references] [--refresh]
@@ -173,6 +180,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 generate-applet <todo-id> --student <kid-id>
+    [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
   recess [--json] memories context --student <kid-id>
   recess [--json] memories log --student <kid-id> --date YYYY-MM-DD
   recess [--json] rocky get --student <kid-id>
@@ -189,8 +198,8 @@ Usage:
     [--path uploads/name.pdf] [--message TEXT]
     [--confirm --approval-token TOKEN]
 
-Authoring notes: "skills" serves the in-product tutor skills (the PRIVATE
-packages/skills submodule) read-only over your admin session — they are never
+Authoring notes: "skills" serves the in-product tutor skills (the private
+packages/skills workspace package) read-only over your admin session — they are never
 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
@@ -629,6 +638,25 @@ const STORE_ITEM_SORT_FIELDS = [
     "updatedAt",
     "order",
 ];
+const CONTENT_LIBRARY_STAGES = ["review", "polish"];
+const CONTENT_LIBRARY_RESOURCE_STAGES = [
+    "review",
+    "polishing",
+    "live",
+    "archived",
+];
+const CONTENT_LIBRARY_DISCOVERY_LANES = [
+    "web-toys",
+    "mechanics",
+    "explorables",
+    "data-stories",
+    "sims",
+    "maps-scale",
+    "sound-art",
+    "puzzles",
+    "wonder",
+    "idea-games",
+];
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Read and parse a JSON file supplied by an authoring agent. Large payloads —
@@ -665,6 +693,215 @@ async function readJsonFile(filePath, label) {
     }
     return parsed;
 }
+function contentLibrarySubmitItem(value, label) {
+    const record = typeof value === "string"
+        ? { url: value }
+        : value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    if (!record) {
+        throw new CliError("invalid_arguments", `${label} must be a URL string or an object with url and optional title, summary, and lane.`);
+    }
+    const allowed = new Set(["url", "title", "summary", "lane"]);
+    const unknown = Object.keys(record).filter((key) => !allowed.has(key));
+    if (unknown.length) {
+        throw new CliError("invalid_arguments", `${label} has unsupported fields: ${unknown.join(", ")}.`);
+    }
+    const text = (key) => {
+        const raw = record[key];
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== "string" || !raw.trim()) {
+            throw new CliError("invalid_arguments", `${label}.${key} must be a non-empty string.`);
+        }
+        return raw.trim();
+    };
+    const rawUrl = text("url");
+    if (!rawUrl) {
+        throw new CliError("invalid_arguments", `${label}.url is required.`);
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${label}.url must be a valid http(s) URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new CliError("invalid_arguments", `${label}.url must be a valid http(s) URL.`);
+    }
+    if (url.toString().length > 2_000) {
+        throw new CliError("invalid_arguments", `${label}.url must be at most 2000 characters.`);
+    }
+    const title = text("title");
+    const summary = text("summary");
+    const laneRaw = text("lane");
+    const lane = laneRaw
+        ? assertChoice(laneRaw, CONTENT_LIBRARY_DISCOVERY_LANES, `${label}.lane`)
+        : undefined;
+    if (title && title.length > 500) {
+        throw new CliError("invalid_arguments", `${label}.title must be at most 500 characters.`);
+    }
+    if (summary && summary.length > 4_000) {
+        throw new CliError("invalid_arguments", `${label}.summary must be at most 4000 characters.`);
+    }
+    return {
+        url: url.toString(),
+        ...(title ? { title } : {}),
+        ...(summary ? { summary } : {}),
+        ...(lane ? { lane } : {}),
+    };
+}
+async function readContentLibrarySubmitItems(parsed) {
+    const items = parsed.positionals
+        .slice(2)
+        .map((url, index) => contentLibrarySubmitItem(url, `URL ${index + 1}`));
+    const filePath = flagString(parsed, "file");
+    let file;
+    if (filePath) {
+        const absolutePath = path.resolve(filePath);
+        let raw;
+        try {
+            raw = await fs.readFile(absolutePath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new CliError("invalid_arguments", `Content Library input file does not exist: ${absolutePath}`);
+            }
+            throw error;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new CliError("invalid_arguments", `Content Library input file is empty: ${absolutePath}`);
+        }
+        let entries;
+        if (trimmed.startsWith("[")) {
+            let parsedFile;
+            try {
+                parsedFile = JSON.parse(trimmed);
+            }
+            catch (error) {
+                throw new CliError("invalid_arguments", `Content Library input file is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!Array.isArray(parsedFile)) {
+                throw new CliError("invalid_arguments", `Content Library JSON input must be an array (${absolutePath}).`);
+            }
+            entries = parsedFile;
+        }
+        else {
+            entries = raw
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line && !line.startsWith("#"));
+        }
+        items.push(...entries.map((entry, index) => contentLibrarySubmitItem(entry, `File item ${index + 1}`)));
+        file = {
+            absolutePath,
+            sizeBytes: Buffer.byteLength(raw),
+            sha256: createHash("sha256").update(raw).digest("hex"),
+        };
+    }
+    if (items.length === 0) {
+        throw new CliError("invalid_arguments", "Pass at least one URL as an argument or through --file.");
+    }
+    if (items.length > 500) {
+        throw new CliError("invalid_arguments", "Content Library submit accepts at most 500 items per confirmed batch.");
+    }
+    const title = flagString(parsed, "title");
+    const summary = flagString(parsed, "summary");
+    const laneRaw = flagString(parsed, "lane");
+    if ((title || summary || laneRaw) && items.length !== 1) {
+        throw new CliError("invalid_arguments", "--title, --summary, and --lane apply to one URL only; use JSON objects in --file for per-item metadata.");
+    }
+    if (items.length === 1 && (title || summary || laneRaw)) {
+        items[0] = contentLibrarySubmitItem({
+            ...items[0],
+            ...(title ? { title } : {}),
+            ...(summary ? { summary } : {}),
+            ...(laneRaw ? { lane: laneRaw } : {}),
+        }, "Submitted item");
+    }
+    return { items, ...(file ? { file } : {}) };
+}
+function contentLibraryGemTarget(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL.`);
+    }
+    const target = value.trim();
+    if (UUID_RE.test(target))
+        return target;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL. Use content-library search to find a live gem's ID.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL.`);
+    }
+    if (url.toString().length > 2_000) {
+        throw new CliError("invalid_arguments", `${label} must be at most 2000 characters.`);
+    }
+    return url.toString();
+}
+async function readContentLibraryGemTargets(parsed) {
+    const gems = parsed.positionals
+        .slice(2)
+        .map((value, index) => contentLibraryGemTarget(value, `Gem ${index + 1}`));
+    const filePath = flagString(parsed, "file");
+    let file;
+    if (filePath) {
+        const absolutePath = path.resolve(filePath);
+        let raw;
+        try {
+            raw = await fs.readFile(absolutePath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw new CliError("invalid_arguments", `Content Library gem file does not exist: ${absolutePath}`);
+            }
+            throw error;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new CliError("invalid_arguments", `Content Library gem file is empty: ${absolutePath}`);
+        }
+        let entries;
+        if (trimmed.startsWith("[")) {
+            let parsedFile;
+            try {
+                parsedFile = JSON.parse(trimmed);
+            }
+            catch (error) {
+                throw new CliError("invalid_arguments", `Content Library gem file is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!Array.isArray(parsedFile)) {
+                throw new CliError("invalid_arguments", `Content Library gem JSON input must be an array (${absolutePath}).`);
+            }
+            entries = parsedFile;
+        }
+        else {
+            entries = raw
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line && !line.startsWith("#"));
+        }
+        gems.push(...entries.map((entry, index) => contentLibraryGemTarget(entry, `File gem ${index + 1}`)));
+        file = {
+            absolutePath,
+            sizeBytes: Buffer.byteLength(raw),
+            sha256: createHash("sha256").update(raw).digest("hex"),
+        };
+    }
+    if (gems.length === 0) {
+        throw new CliError("invalid_arguments", "Pass at least one gem ID or URL as an argument or through --file.");
+    }
+    if (gems.length > 500) {
+        throw new CliError("invalid_arguments", "Content Library set-stage accepts at most 500 gems per confirmed batch.");
+    }
+    return { gems, ...(file ? { file } : {}) };
+}
 async function readGoalTemplateSpecPatches(filePath) {
     const { absolutePath, raw, parsed } = await readJsonValue(filePath, "Goal-template patch file");
     if (!Array.isArray(parsed) || parsed.length === 0) {
@@ -940,6 +1177,20 @@ function flagItemDateMs(parsed) {
     }
     return ms;
 }
+function flagDateOnly(parsed, name) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return undefined;
+    const parsedDate = /^\d{4}-\d{2}-\d{2}$/.test(raw)
+        ? new Date(`${raw}T00:00:00.000Z`)
+        : null;
+    if (!parsedDate ||
+        Number.isNaN(parsedDate.getTime()) ||
+        parsedDate.toISOString().slice(0, 10) !== raw) {
+        throw new CliError("invalid_arguments", `--${name} must be a valid YYYY-MM-DD date.`);
+    }
+    return raw;
+}
 const DAY_MS = 24 * 60 * 60 * 1000;
 // The cohort event routes take zoneless local wall-clock datetimes
 // (interpreted in the cohort's timezone server-side).
@@ -2446,7 +2697,60 @@ export async function runCommand(argv) {
                 params: { query: { q: query, limit } },
             }));
         }
-        throw new CliError("invalid_arguments", "Use content-library search.");
+        if (verb === "status") {
+            const gem = contentLibraryGemTarget(positional(parsed, 2, "gem id or URL"), "Gem");
+            return unwrap(await api.client.GET("/admin/content-library/status", {
+                params: { query: { gem } },
+            }));
+        }
+        if (verb === "set-stage") {
+            const stage = assertChoice(flagString(parsed, "stage", { required: true }), CONTENT_LIBRARY_RESOURCE_STAGES, "--stage");
+            const input = await readContentLibraryGemTargets(parsed);
+            const preflightBody = {
+                gems: input.gems,
+                stage,
+                dryRun: true,
+            };
+            const preflight = unwrap(await api.client.POST("/admin/content-library/transition", {
+                body: preflightBody,
+            }));
+            const preview = {
+                action: "content-library.set-stage",
+                target: { stage, resourceCount: preflight.results.length },
+                request: { gems: input.gems, stage },
+                details: {
+                    resources: preflight.results,
+                    lifecycle: "Uses the same lifecycle as Manage. Direct-to-Live never bypasses unfinished polishing; leaving Polishing cancels its bound run before moving.",
+                    concurrency: 3,
+                    ...(input.file ? { inputFile: input.file } : {}),
+                },
+            };
+            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/transition", {
+                body: { gems: input.gems, stage, dryRun: false },
+            })));
+        }
+        if (verb === "submit") {
+            const stage = assertChoice(flagString(parsed, "stage") ?? "review", CONTENT_LIBRARY_STAGES, "--stage");
+            const input = await readContentLibrarySubmitItems(parsed);
+            const body = { stage, items: input.items };
+            const preview = {
+                action: "content-library.submit",
+                target: { stage, resourceCount: input.items.length },
+                request: body,
+                details: {
+                    admission: stage === "polish"
+                        ? "Starts automatic decoration; the island promotes each successful resource to LIVE after the polish and deterministic tail finish."
+                        : "Holds each new resource in REVIEW until an admin approves it.",
+                    duplicateBehavior: "Existing URLs are returned as duplicates and are not overwritten.",
+                    deployOrderFence: "The server verifies the island's review/polish lifecycle capability before its first write.",
+                    ...(input.file ? { inputFile: input.file } : {}),
+                },
+            };
+            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/submit", {
+                body,
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
         if (verb === "list") {
@@ -3135,7 +3439,49 @@ export async function runCommand(argv) {
                 body,
             }));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit.");
+        if (verb === "generate-applet") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const targetDueDateISO = flagDateOnly(parsed, "due-date");
+            const [todo, learningAnalysis] = await Promise.all([
+                api.client.GET("/tutor/browser/todos/{id}/", {
+                    params: { path: { id: todoId } },
+                }),
+                api.client.GET("/tutor/students/{studentId}/todos/{todoId}/learning-analysis", {
+                    params: { path: { studentId, todoId } },
+                }),
+            ]);
+            const currentTodo = unwrap(todo);
+            if (currentTodo.userId !== studentId) {
+                throw new CliError("not_found", "The todo does not belong to the requested student.");
+            }
+            const analysis = unwrap(learningAnalysis).analysis;
+            if (!analysis) {
+                throw new CliError("not_found", "This todo does not have a learning analysis to generate an applet from.");
+            }
+            const preview = {
+                action: "generate an applet from a student's todo analysis",
+                target: {
+                    studentUserId: studentId,
+                    todoId,
+                    todoTitle: currentTodo.title,
+                    analysisId: analysis.id,
+                },
+                request: {
+                    targetDueDateISO: targetDueDateISO ?? null,
+                },
+                details: {
+                    dueDate: targetDueDateISO ?? "tomorrow in the student's timezone",
+                    versionRouting: "The server evaluates applet-gen-v2 for this student and uses v1 when the flag is off or its evaluation fails.",
+                },
+            };
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
+                params: { path: { analysisId: analysis.id } },
+                body: targetDueDateISO ? { targetDueDateISO } : {},
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use todos create|edit|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });

package/dist/index.js

@@ -1,7 +1,43 @@
 #!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "./args.js";
 import { runCommand } from "./cli.js";
 import { CliError } from "./errors.js";
-const argv = process.argv.slice(2);
+async function withInteractiveAdmissionStage(args) {
+    const parsed = parseArgs(args);
+    if (parsed.flags.has("json") ||
+        parsed.flags.has("help") ||
+        parsed.flags.has("stage") ||
+        parsed.positionals[0] !== "content-library" ||
+        parsed.positionals[1] !== "submit" ||
+        !process.stdin.isTTY ||
+        !process.stderr.isTTY) {
+        return args;
+    }
+    const terminal = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    try {
+        while (true) {
+            const answer = (await terminal.question("Admission stage [Review/polish] (Review): "))
+                .trim()
+                .toLowerCase();
+            if (!answer || answer === "r" || answer === "review") {
+                return [...args, "--stage", "review"];
+            }
+            if (answer === "p" || answer === "polish") {
+                return [...args, "--stage", "polish"];
+            }
+            process.stderr.write("Choose Review or polish.\n");
+        }
+    }
+    finally {
+        terminal.close();
+    }
+}
+const argv = await withInteractiveAdmissionStage(process.argv.slice(2));
 const json = argv.includes("--json");
 // The interactive console owns the terminal, so it runs before the JSON
 // envelope machinery rather than through it.

package/dist/skills-cache.js

@@ -6,12 +6,12 @@ import { defaultConfigPath } from "./config.js";
  * On-disk cache for tutor skills fetched from `GET /admin/skills/*`.
  *
  * The skills are proprietary and live in the private `packages/skills`
- * submodule; `recess-cli` is published PUBLIC on npm, so they are fetched at
+ * workspace package; `recess-cli` is published PUBLIC on npm, so they are fetched at
  * runtime and never bundled. The cache exists so an authoring loop that reads
  * `os-v2-goal-template-builder` on every step does not re-fetch a ~40 KB
  * document each time — it is a latency cache, not a distribution channel:
  * entries live under the operator's 0700 config directory, and `--refresh`
- * bypasses them so a skills-repo update is always one flag away.
+ * bypasses them so a newly deployed skills update is always one flag away.
  *
  * Deliberately short-lived. A stale authoring standard is the failure this whole
  * design exists to prevent, so an entry older than the TTL is simply re-fetched.

package/package.json

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