recess-cli 1.3.0 → 1.3.3

package/README.md

@@ -13,7 +13,7 @@ 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.
 
-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 publishes that tarball through the `admin-cli-publish.yml` OIDC trusted publisher configured on npmjs.com.
+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`.
 
 ## Install (from a checkout — CLI development)
 
@@ -92,10 +92,26 @@ human explicitly approves the exceptional `--allow-strand` override.
 
 MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing tutor-dashboard extraction route.
 
+## Store catalog and Village
+
+Village store goods are main-Recess `StoreItem` rows, not Village-island database rows. List them
+and preview an availability change with:
+
+```bash
+recess --json store-items list --item-type VILLAGE_ITEM
+recess --json store-items set-status <store-item-id> --status INACTIVE
+```
+
+The status command resolves the exact `VILLAGE_ITEM` first and includes its name, catalog metadata,
+current status, purchase count, and lack of feed-publication side effects in the approval preview;
+it refuses non-Village item IDs. After approval, rerun the unchanged command with `--confirm`. The
+separate `village models` commands edit the Village island's reusable models and placements.
+
 ## Authoring learning content
 
 ```bash
 recess --json skills get os-v2-goal-template-builder --all-references
+recess --json content-library search "fractions through visual puzzles" --limit 8
 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

package/dist/cli.js

@@ -113,6 +113,13 @@ Usage:
   recess [--json] village models remove <placement-id> [--world village-1] [--confirm]
   recess [--json] village render --min-x N --min-z N --max-x N --max-z N
     [--world village-1]
+  recess [--json] store-items list [--search TEXT]
+    [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
+    [--page 0] [--limit 20] [--sort-by name|price|createdAt|updatedAt|order]
+    [--sort-order asc|desc]
+  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] skills list [--query TEXT] [--category TEXT]
   recess [--json] skills get <skill-name> [--reference NAME | --all-references]
     [--refresh]
@@ -128,7 +135,7 @@ Usage:
   recess [--json] goal-templates set-metadata <template-id> --expected-version N
     [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
     [--sort-order N] [--kind SIMPLE|BLUEPRINT] [--agent-instructions-file <path>]
-    [--confirm]
+    [--output-template-file <path>] [--confirm]
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
   recess [--json] goal-templates snapshot-files <template-id> [--path P]
   recess [--json] goal-templates capture-snapshot <template-id|slug>
@@ -455,6 +462,27 @@ const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
 const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
 const GOAL_TEMPLATE_KINDS = ["SIMPLE", "BLUEPRINT"];
 const GOAL_TEMPLATE_SETUP_AUDIENCES = ["KID_FRIENDLY", "PARENT_SETUP"];
+const STORE_ITEM_STATUSES = ["ACTIVE", "INACTIVE", "COMING_SOON"];
+const STORE_ITEM_TYPES = [
+    "PROFILE_RING",
+    "ANIMATED_COVER",
+    "PROFILE_STICKER",
+    "CLASS_PASS",
+    "GUIDE_MENTORSHIP",
+    "TOOL_CREDIT",
+    "MERCH_ITEM",
+    "STEAM_GAME",
+    "KID_PROFILE_PICTURE",
+    "WORLD_AVATAR_ITEM",
+    "VILLAGE_ITEM",
+];
+const STORE_ITEM_SORT_FIELDS = [
+    "name",
+    "price",
+    "createdAt",
+    "updatedAt",
+    "order",
+];
 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 —
@@ -1056,6 +1084,103 @@ export async function runCommand(argv) {
         }
         throw new CliError("invalid_arguments", "Use village models list|upload|publish|archive|place|move|remove.");
     }
+    if (noun === "store-items") {
+        if (verb === "list") {
+            const search = flagString(parsed, "search");
+            const rawStatus = flagString(parsed, "status");
+            const rawItemType = flagString(parsed, "item-type");
+            const page = flagNumber(parsed, "page") ?? 0;
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            const rawSortBy = flagString(parsed, "sort-by");
+            const rawSortOrder = flagString(parsed, "sort-order");
+            if (!Number.isInteger(page) || page < 0) {
+                throw new CliError("invalid_arguments", "--page must be a non-negative integer.");
+            }
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 100.");
+            }
+            const status = rawStatus
+                ? assertChoice(rawStatus, STORE_ITEM_STATUSES, "--status")
+                : undefined;
+            const itemType = rawItemType
+                ? assertChoice(rawItemType, STORE_ITEM_TYPES, "--item-type")
+                : undefined;
+            const sortBy = rawSortBy
+                ? assertChoice(rawSortBy, STORE_ITEM_SORT_FIELDS, "--sort-by")
+                : "order";
+            const sortOrder = rawSortOrder
+                ? assertChoice(rawSortOrder, ["asc", "desc"], "--sort-order")
+                : "asc";
+            return unwrap(await api.client.GET("/admin/store-items/", {
+                params: {
+                    query: {
+                        ...(search ? { search } : {}),
+                        ...(status ? { status } : {}),
+                        ...(itemType ? { itemType } : {}),
+                        page,
+                        limit,
+                        sortBy,
+                        sortOrder,
+                    },
+                },
+            }));
+        }
+        if (verb === "set-status") {
+            const storeItemId = positional(parsed, 2, "store item ID");
+            const status = assertChoice(flagString(parsed, "status", { required: true }), STORE_ITEM_STATUSES, "--status");
+            let page = 0;
+            let storeItem;
+            // Resolve the exact live row before the confirmation gate. Filtering at
+            // the API makes this command incapable of mutating non-Village catalog
+            // items, while the preview can name the row and its current state.
+            do {
+                const result = unwrap(await api.client.GET("/admin/store-items/", {
+                    params: {
+                        query: {
+                            itemType: "VILLAGE_ITEM",
+                            page,
+                            limit: 100,
+                            sortBy: "order",
+                            sortOrder: "asc",
+                        },
+                    },
+                }));
+                storeItem = result.items.find((item) => item.id === storeItemId);
+                if (storeItem || page + 1 >= result.totalPages)
+                    break;
+                page += 1;
+            } while (true);
+            if (!storeItem) {
+                throw new CliError("not_found", `No Village store item found for ${storeItemId}.`);
+            }
+            const metadata = storeItem.metadata &&
+                typeof storeItem.metadata === "object" &&
+                !Array.isArray(storeItem.metadata)
+                ? storeItem.metadata
+                : {};
+            const body = { status };
+            return writeCommand(parsed, {
+                action: `set Village store item status to ${status}`,
+                target: {
+                    storeItemId,
+                    name: storeItem.name,
+                    itemType: storeItem.itemType,
+                    villageKind: metadata.villageKind,
+                    catalogId: metadata.catalogId,
+                },
+                request: body,
+                details: {
+                    currentStatus: storeItem.status,
+                    purchaseCount: storeItem._count.purchases,
+                    publishesFeedActivity: false,
+                },
+            }, async () => unwrap(await api.client.PATCH("/admin/store-items/{id}", {
+                params: { path: { id: storeItemId } },
+                body,
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use store-items list or store-items set-status.");
+    }
     if (noun === "users" && verb === "search") {
         const query = parsed.positionals.slice(2).join(" ").trim();
         if (!query)
@@ -2072,6 +2197,19 @@ export async function runCommand(argv) {
         }
         throw new CliError("invalid_arguments", "Use skills list|get.");
     }
+    if (noun === "content-library") {
+        if (verb === "search") {
+            const query = positional(parsed, 2, "search query");
+            const limit = flagNumber(parsed, "limit") ?? 8;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 40) {
+                throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 40.");
+            }
+            return unwrap(await api.client.GET("/admin/content-library/search", {
+                params: { query: { q: query, limit } },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use content-library search.");
+    }
     if (noun === "goal-templates") {
         if (verb === "list") {
             const query = flagString(parsed, "query")?.toLowerCase();
@@ -2281,6 +2419,7 @@ export async function runCommand(argv) {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
             const agentInstructionsFile = flagString(parsed, "agent-instructions-file");
+            const outputTemplateFile = flagString(parsed, "output-template-file");
             const tags = flagString(parsed, "tags");
             const kind = flagString(parsed, "kind");
             const sortOrder = flagNumber(parsed, "sort-order");
@@ -2315,13 +2454,18 @@ export async function runCommand(argv) {
                         agentInstructions: await fs.readFile(path.resolve(agentInstructionsFile), "utf8"),
                     }
                     : {}),
+                ...(outputTemplateFile
+                    ? {
+                        outputTemplate: await fs.readFile(path.resolve(outputTemplateFile), "utf8"),
+                    }
+                    : {}),
             };
             // `setupWorkflowSpec` is unreachable from this command by construction.
             // The route still accepts one, but a wholesale spec replacement is the
             // 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, --category, --tags, --sort-order, --kind, --agent-instructions-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --kind, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "Safe Recess staff administration from the command line, for humans and coding agents.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: recess-cli
-description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, write a Mesa draft or goal workspace, capture a template snapshot, and read Mesa workspace or snapshot files.
+description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; edit the Recess Village map or manage store-catalog availability; search the curated Content Library; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, write a Mesa draft or goal workspace, capture a template snapshot, and read Mesa workspace or snapshot files.
 # Bundle version. Bump on every substantive edit; the CLI reports it and `doctor`
 # compares it against the served copy to tell an operator a refresh is available.
-version: 1.4.0
+version: 1.4.4
 # The lowest `recess` version this bundle is safe to install onto. Raise it ONLY
 # when the bundle documents a command, flag, or changed semantic that an older
 # binary does not have — an older CLI keeps its bundled copy instead of taking
 # this one. Prose, formatting, and Gotcha edits must NOT raise it; that is the
 # whole point of serving the bundle.
-minCliVersion: 1.3.0
+minCliVersion: 1.3.3
 ---
 
 # Recess CLI (`recess`)
@@ -209,10 +209,26 @@ recess --json onboarding attest <family-id> --condition app_downloaded|tutor_met
 recess --json onboarding set-intake <family-id> --session <id> --data <json> [--expected-updated-at <iso>] [--confirm]
 recess --json onboarding extract <family-id> --session <id> (--transcript-file <path> | --granola <ref>) [--confirm]
 
+# Recess Village map administration
+recess --json village render --min-x N --min-z N --max-x N --max-z N [--world village-1]
+recess --json village models list [--world village-1] [--query TEXT] [--archived]
+recess --json village models upload --file <model.glb> [--world village-1] [--name TEXT] [--confirm]
+recess --json village models publish|archive <model-id> [--world village-1] [--confirm]
+recess --json village models place <model-id> --x N --z N [--y N] [--rotation 0..3] [--world village-1] [--confirm]
+recess --json village models move <placement-id> --x N --z N [--y N] [--rotation 0..3] [--world village-1] [--confirm]
+recess --json village models remove <placement-id> [--world village-1] [--confirm]
+
+# Main Recess store catalog (status writes are restricted to Village goods)
+recess --json store-items list [--search TEXT] [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
+recess --json store-items set-status <village-store-item-id> --status ACTIVE|INACTIVE|COMING_SOON [--confirm]
+
 # Tutor skills — the authoring know-how (served, never bundled)
 recess --json skills list [--query TEXT] [--category TEXT]
 recess --json skills get <skill-name> [--reference NAME | --all-references] [--refresh]
 
+# Curated learning-resource research (read-only)
+recess --json content-library search <query> [--limit 8]
+
 # Learning content (reference/goal-authoring.md)
 recess --json goal-templates list [--query TEXT] [--kind SIMPLE|BLUEPRINT] [--starter-only]
 recess --json goal-templates get <id-or-slug> [--spec-only]
@@ -220,7 +236,7 @@ recess --json goal-templates versions <id-or-slug> [--version N]
 recess --json goal-templates validate-spec --file <path/template.json>
 recess --json goal-templates create --file <path/template.json> [--confirm]
 recess --json goal-templates patch-spec <id-or-slug> --expected-version N --patches-file <path/patches.json> [--confirm] [--confirm-destructive-changes --destructive-change-token TOKEN]
-recess --json goal-templates set-metadata <id-or-slug> --expected-version N [--title …] [--confirm]
+recess --json goal-templates set-metadata <id-or-slug> --expected-version N [--title …] [--agent-instructions-file <path>] [--output-template-file <path>] [--confirm]
 recess --json goal-templates delete <id-or-slug> --expected-version N [--confirm]
 recess --json goal-templates snapshot-files <id-or-slug> [--path P]
 recess --json goal-templates capture-snapshot <id-or-slug> (--source-goal <goal-id> | --source-draft <draft-slug> --student <kid-id>) [--dry-run] [--confirm]
@@ -318,7 +334,8 @@ the tool names do not:
 | `search_web`, `fetch_webpage` | your own web search / page fetch |
 | `spawn_subagents` | your own subagents. The five researcher prompts in `goal-creation`'s `subagent-tasks.md` (curriculum-map, platforms, resources, learning-paths, prerequisites) are usable almost verbatim — they are prompts, not tool calls |
 | `validate_urls` | check the URLs yourself before baking them into a spec. Do not skip this: a rotted queue URL is invisible until a kid clicks it |
-| `search_videos`, `search_books`, `recommend_videos`, `search_gem_library` | your own search. There is no CLI command for the gem library |
+| `search_gem_library` | `content-library search <query>` (same hybrid/vector + rerank funnel; no content or Pipeline writes) |
+| `search_videos`, `search_books`, `recommend_videos` | your own search |
 | `get_student_profile`, `read_memory`, `query_student_activity_sql` | **partial.** `users search`/`users get` give account context, `goals list` what is already authored, `mesa files` the workspace. There is **no** command for kid memory or activity SQL — for those, the separate `query-db` skill's read-only production access is the honest route, not a guess |
 | `search_standards`, `navigate_standards` | no CLI command |
 | `save_platform_research` | **no CLI command** — a researched platform profile can only be persisted from `recess.gg/ai`. Your research still informs the spec you write; it just does not get saved as a reusable profile |
@@ -479,3 +496,7 @@ Dated, newest last. Add an entry every time reality surprises you.
 - 2026-08-04 — A `Makefile install-persistent` copy is NOT the npm package: it synthesizes its own `package.json`. If that manifest lacks `version`, or `skill/` is not copied alongside `dist/`, then `--version` reports `0.0.0` and the `minCliVersion` fence **fails closed** — every served skill upgrade is silently refused with `cli_too_old`. Both are now copied; if you add another packaged artifact the CLI reads at runtime, add it to that target too.
 - 2026-08-04 — **`goal-templates patch-spec` performs a server preview even on a confirmed run.** The first POST is `dryRun:true`, never a write; it binds the current template version, before/after hashes, and protected removals. A destructive second POST is impossible without `--confirm-destructive-changes` and that fresh preview token. If the template or patch file changes, preview again and obtain new approval.
 - 2026-08-05 — **A deterministic MODULE_BACKED spec is not the course content.** `goal-templates create` can create a valid BLUEPRINT while `snapshot` remains null; Goal Preview stays empty and apply correctly says there is no valid snapshot. Build the complete tree locally, `mesa files write --draft … --source-dir …`, then `goal-templates capture-snapshot --source-draft … --student …`. Both writes server-preview first. Mesa writes are fenced to the previewed repo change; capture is fenced to that source change and the template version. Direct live-goal `modules/`/`state/` writes are deliberately blocked because those paths have DB projections.
+- 2026-08-05 — **The goal-audit GET cannot investigate an already-soft-deleted goal.** `request get /admin/browser/students/goals/<goal-id>/audit/` returns 404 because the handler's `ensureGoalAccess` calls `canManageGoal`, which requires `Goal.deletedAt: null` before it loads `GoalAuditLog`. The 404 is not evidence that the audit row is absent. Use the `query-db` skill's guarded read-only production query for deletion forensics.
+- 2026-08-05 — **`set-metadata --output-template-file` edits an AI_CHAT template's `outputTemplate`** (the goal-description payload DailyTodoGeneration consumes for description-only goals). Like `--agent-instructions-file`, it reads a local file and the server bumps the version + freezes a `GoalTemplateVersion` row. Editing a template never rewrites goals already created from it — the description was copied at goal-creation time; re-apply or edit live goals separately.
+- 2026-08-05 — **Content Library search now has a content/Pipeline-read-only CLI command.** `content-library search <query> [--limit 8]` calls the same hybrid/vector + rerank `/agent/search` funnel as Rocky's `search_gem_library`, returns the full fit/gist/coverage payload, and attributes the funnel's standard `offered` telemetry to `admin-cli`. It cannot inspect, ingest, file requests, curate, or edit the Pipeline; the permanent library token stays on the web server.
+- 2026-08-07 — **Village store goods do not live in the Village database.** They are ordinary main-Recess `StoreItem` rows with `itemType=VILLAGE_ITEM`; use `store-items list --item-type VILLAGE_ITEM` and the confirmation-gated `store-items set-status`, while `village models …` remains the separate Village-island map/model boundary. `set-status` refuses non-Village IDs and its live preflight names the item, current status, purchase count, and feed consequence before approval. A checked-in seed still owns fresh-database defaults, so an operational status edit does not replace updating that seed when the product default itself changes.