recess-cli 1.3.2 → 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,6 +92,21 @@ 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

package/dist/cli.js

@@ -113,6 +113,12 @@ 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]
@@ -456,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 —
@@ -1057,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.3.2",
+  "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; 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.
+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.3
+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.2
+minCliVersion: 1.3.3
 ---
 
 # Recess CLI (`recess`)
@@ -209,6 +209,19 @@ 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]
@@ -486,3 +499,4 @@ Dated, newest last. Add an entry every time reality surprises you.
 - 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.