recess-cli 1.3.2 → 1.4.0

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

@@ -28,6 +28,11 @@ Usage:
     [--slots N]
   recess [--json] users tier set <kid-id> --tier social|academics|lite|complete|platform
     [--slots N] --expected-updated-at <iso> [--allow-strand] [--confirm]
+  recess [--json] guides create --email <email> --first-name TEXT
+    [--last-name TEXT] [--no-invite] [--confirm]
+  recess [--json] guides invite --user <user-id> [--confirm]
+  recess [--json] guardians invite --family <family-id> --email <email>
+    --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
   recess [--json] students upload-map-scores --student <kid-id>
     --file </path/to/map-report.pdf> [--confirm]
   recess [--json] enrollments list --user <user-id>
@@ -113,6 +118,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 +467,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 +1089,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)
@@ -1150,6 +1279,96 @@ export async function runCommand(argv) {
             params: { path: { userId } },
         }));
     }
+    if (noun === "guides" && verb === "create") {
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "provision a GUIDE staff account and email its sign-in invite (outward email)"
+                : "provision a GUIDE staff account without sending the invite email",
+            target: { email },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/guides/", { body })));
+    }
+    if (noun === "guardians" && verb === "invite") {
+        const familyId = flagString(parsed, "family", { required: true });
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        // Read-only preflight: the approval preview must name the exact family
+        // this guardian is being granted over — a wrong family id hands a
+        // stranger full guardian access to someone's kids.
+        const family = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "invite a new GUARDIAN into an existing family and email the sign-in invite (outward email)"
+                : "add a new GUARDIAN to an existing family without sending the invite email",
+            target: { familyId, email },
+            request: body,
+            details: {
+                familyName: family.familyName,
+                kids: family.kids.map((kid) => kid.firstName),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/users/family/{familyId}/guardians/", {
+            params: { path: { familyId } },
+            body,
+        })));
+    }
+    if (noun === "guides" && verb === "invite") {
+        const userId = flagString(parsed, "user", { required: true });
+        // Read-only preflight: the approval preview must name the exact person
+        // about to receive an outward email, and refuse a non-guide before the
+        // gate rather than after approval (the backend enforces the same rule).
+        const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+        if (user.role !== "GUIDE") {
+            throw new CliError("invalid_arguments", `User ${userId} has role ${user.role}; only GUIDE accounts can be invited. Use guides create for a new guide.`);
+        }
+        if (!user.email) {
+            throw new CliError("invalid_arguments", `Guide ${userId} has no email address on file, so no invite can be sent.`);
+        }
+        return writeCommand(parsed, {
+            action: "send the guide sign-in invite email (outward email)",
+            target: { userId },
+            request: {},
+            details: {
+                to: user.email,
+                firstName: user.firstName,
+                lastName: user.lastName,
+                role: user.role,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/guides/{userId}/invite/", {
+            params: { path: { userId } },
+        })));
+    }
     if (noun === "students" && verb === "upload-map-scores") {
         const studentId = flagString(parsed, "student", { required: true });
         const pdf = await readMapScorePdf(flagString(parsed, "file", { required: true }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "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; provision a new GUIDE staff account and email its sign-in invite (or resend one); 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.5.0
 # 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.4.0
 ---
 
 # Recess CLI (`recess`)
@@ -51,6 +51,9 @@ Never infer approval from the original task, prior approval, urgency, or a succe
 | `invoices refund … --who-pays recess` | Recess absorbs the cost instead of the guide |
 | `cohorts end --cancel-subscriptions` | sets EVERY active enrollment's Stripe subscription to cancel at period end |
 | `cohorts email` | real outward email blast to families (include the recipient count from `cohorts parent-emails`) |
+| `guides create` | mints a staff-privileged GUIDE account (the `/admin` gate admits GUIDE) and by default emails the sign-in invite; quote the exact email address — the address IS the credential handle for passwordless login |
+| `guides invite` | real outward email to the previewed recipient telling them their account is live; quote `details.to` |
+| `guardians invite` | grants a new email address FULL guardian access over an existing family's kids and by default emails the sign-in invite; quote the previewed `details.familyName` + kid list and the exact email address |
 | `events cancel` | family-facing fan-out: chat messages, parent email blast, credit-owed notes, Slack |
 | `payout invoices set-status` to `OPEN`/`PAID`/`CANCELED` | moves real account balances; `--send-email` additionally emails the guide |
 | destructive `goal-templates patch-spec` | removes subjects, recipes, plans, queue items, source URLs, or missing-coverage records from a global template; quote the exact `details.safety.removed` inventory and hashes, then use the fresh token only after approval |
@@ -155,6 +158,14 @@ recess --json users tier set <kid-id> --tier <id> [--slots N] \
 recess --json enrollments list --user <user-id>
 recess --json enrollments get-for-subscription --subscription <id>
 
+# Guide staff accounts (ADMIN-only; both send outward email by default)
+recess --json guides create --email <email> --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
+recess --json guides invite --user <user-id> [--confirm]
+
+# Invite a guardian into an EXISTING family (ADMIN-only; outward email by default;
+# the preview names the family + kids — verify them before requesting approval)
+recess --json guardians invite --family <family-id> --email <email> --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
+
 # Billing & subscriptions (reference/billing.md)
 recess --json subscriptions list --family <family-id> [--kid <kid-id>]
 recess --json invoices list --subscription <subscription-id>
@@ -209,6 +220,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 +510,5 @@ 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.
+- 2026-08-11 — **An external bundle leaf does not infer its grade answer from `availableWhen`.** When an `EXTERNAL_SKILL_QUEUE_SETUP` recipe has grade-specific plans and the shared wizard step is not named `grade`, set `handler.config.gradeLevelStepKey` to that exact step key. The server preview can validate without this optional binding, but apply dry-run then returns `No plan matched subject="…"`. Compare the new leaf with a working grade-bound sibling and dry-run the exact answers before calling the template finished.