recess-cli 2.7.0 → 2.8.0

package/dist/help.js

@@ -1,7 +1,17 @@
 export const HELP = `recess — safe Recess administration and family AI tools
 
 Usage:
+  recess [--json] mastery graphs [--domain <slug>]
+  recess [--json] mastery get <graph-id> [--kind seed|draft|release]
+  recess [--json] mastery edit <graph-id> [--kind seed|draft|release]
+    [--file <graph.json> | --instruction TEXT] [--node <node-id>] [--confirm]
+  recess [--json] mastery publish <draft-id> --expected-active-release <release-id-or-none> [--confirm]
+  recess [--json] mastery links --graph <release-id> [--node <node-id>] [--cursor <link-id>]
+  recess [--json] mastery link <content-id> --type applet|goal --graph <release-id>
+    [--node <node-id>] [--confirm]
+  recess [--json] mastery unlink <link-id> [--confirm]
   recess [--json] --version
+  recess [--json] help [noun] [verb]
   recess [--json] agent-context
   recess [--json] setup [--skill-only]
   recess [--json] doctor
@@ -39,10 +49,11 @@ Usage:
     --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] students list
+  recess [--json] students list [--scope mine|family]
   recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
   recess [--json] students schedule --student <kid-id> [--days 14]
-  recess [--json] students todos --student <kid-id> [--limit 30] [--analyzed]
+  recess [--json] students todos --student <id-or-name> [--date <today-or-YYYY-MM-DD>]
+    [--limit 30] [--cursor <todo-id>] [--analyzed]
   recess [--json] students analysis --todo <todo-id>
   recess [--json] students xp-history --student <kid-id>
     [--range week|month|quarter|year]
@@ -55,6 +66,7 @@ Usage:
     --method refund|credit|tokens [--full | --amount-cents N]
     [--who-pays guide|recess] [--reason TEXT] [--confirm]
   recess [--json] apps init <dir> [--for-todo <todo-id>] [--force]
+  recess [--json] apps scaffold [--for-todo <todo-id>]
   recess [--json] apps preview [dir] [--port N]
   recess [--json] apps primitives list
   recess [--json] apps primitives publish <file.js> --name <kebab-name> [--description TEXT]
@@ -301,12 +313,12 @@ Usage:
     --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>]
+  recess [--json] content-library set-stage [<gem-id-or-url>...] [--file <path>]
     --stage review|polishing|live|archived [--wait] [--timeout 900] [--confirm]
-  recess [--json] content-library submit <url...> [--file <path>]
+  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]
-    [--wait] [--timeout 900] [--confirm]
+    [--lane web-toys|mechanics|explorables|data-stories|sims|maps-scale|sound-art|puzzles|wonder|idea-games|makers|drills]
+    [--allow-possible-duplicate] [--wait] [--timeout 900] [--confirm]
   recess [--json] skills guardian list [--query TEXT] [--category TEXT]
   recess [--json] skills guardian get <skill-name>
     [--reference NAME | --all-references] [--refresh]

package/dist/upload-names.js

@@ -0,0 +1,19 @@
+// A mirror of `apps/web-server/src/services/os-v2/upload-names.ts` — the one
+// rule for what a goal workspace stores an upload under (PROD-983). Read that
+// module for why the rule is what it is; change it there first, then here.
+//
+// A copy, not an import, because `recess-cli` is published to npm from this
+// directory's own `tsc` output and every workspace package it could import the
+// rule from is private, so a `workspace:*` dependency would leave
+// `npm i -g recess-cli` unable to resolve it. `skills-cache.ts` and
+// `skill-update.ts` mirror web-server code for the same reason.
+/**
+ * The name a workspace stores an upload under: safe for a Mesa path, stable,
+ * idempotent, and total — never empty, never `.` or `..`, never a path
+ * separator, never a dotfile.
+ */
+export function sanitizeWorkspaceUploadName(original) {
+    const cleaned = original.replace(/^\.+/, "").replace(/[^a-zA-Z0-9._-]/g, "_");
+    return cleaned || "file";
+}
+//# sourceMappingURL=upload-names.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {
@@ -9,6 +9,13 @@
     "directory": "apps/admin-cli"
   },
   "type": "module",
+  "exports": {
+    "./engine": {
+      "development": "./src/engine.ts",
+      "types": "./src/engine.ts",
+      "default": "./dist/engine.js"
+    }
+  },
   "bin": {
     "recess": "dist/index.js"
   },

package/skill/recess-cli/SKILL.md

@@ -50,7 +50,7 @@ Never print or paste session cookies, device codes, or config-file contents.
 
 ## Agent contract
 
-Always pass `--json`. Stdout contains one object:
+With the local binary, always pass `--json`. Stdout contains one object:
 
 - Success: `{"ok":true,"data":{...}}`, exit 0.
 - Failure: `{"ok":false,"error":{"code":"...","message":"...","details":{...}}}`, exit 1.
@@ -70,6 +70,21 @@ Every write is two-step:
 
 Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request. If a confirmed invocation is interrupted, retry the unchanged command with the same operation key; never mint a new one for an uncertain write. Inspect recovery state with `recess --json jobs get <operation-key>`.
 
+### Hosted MCP transport
+
+When this skill is reached through the hosted Recess connector, use its only tool,
+`recess_exec({argv,input?})`. `argv` starts with the command noun, omits both `recess` and `--json`,
+and still carries `--reason`. The CLI envelope is returned in MCP `structuredContent`; a
+`confirmation_required` envelope is expected control flow, while other failures are tool errors.
+Start with `argv:["agent-context"]` or `argv:["help","apps"]` for the remote-only catalog. OAuth
+already supplies the live user and scopes: never ask for cookies, profiles, local paths, or
+`--deliver`.
+
+Hosted writes stage the exact argv and structured payload on the server. Preview without
+`--confirm`, show the human `error.details.preview`, then confirm with the same command path plus
+`--confirm --operation-key <key>` and **omit `input`**. The server executes the stored bytes; changed
+source, flags, project/version, or operation keys require a fresh preview.
+
 ## Building Studio apps (`recess apps`)
 
 Guides build Recess Studio apps in their own editor and publish them with the CLI; Studio never
@@ -91,6 +106,21 @@ prompts a model for them.
 - `recess --json apps standards "<words or notation>"` finds the CCSS standard for `manifest.json`
   (`"grade 4 adding fractions"` → `4.NF.B.3a`…); guides rarely know the codes, look them up.
 
+Hosted authoring keeps those same contracts but carries no folder:
+
+- `apps scaffold [--for-todo <id>]` returns authoring instructions, the five editable starter
+  files, fork guidance, and an optional learner brief. It performs no write.
+- Generate `input.appBundle` with exactly `skill.js`, `model.js`, `model.css`,
+  `params.schema.json`, and `params.json`, plus `contract` and `manifest`. Preview and confirm
+  `apps validate`; keep the returned project/version/build IDs and poll `apps status <build-id>`.
+- Fix findings in the bundle. For an existing project, first `apps pull <project-id>` and preserve
+  its `baseVersion`; a stale version is a conflict, never an overwrite.
+- `apps preview <project-id> --version <n>` returns the short-lived capability URL.
+  Preview/confirm `apps publish <project-id> --version <n>`, then poll its build. Publication sends
+  no source and reviews exactly that validated version.
+- After publication, preview/confirm `apps assign <project-id> --student <id> [--due YYYY-MM-DD]`.
+  Assignment is intentionally separate from hosted publish.
+
 Two ways in. If the guide names a kid or a todo, pull the analysis first and build against it;
 otherwise build from their description:
 

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

@@ -1,4 +1,4 @@
 {
-  "version": "2.5.0",
-  "minCliVersion": "2.4.0"
+  "version": "2.6.0",
+  "minCliVersion": "2.6.1"
 }