recess-cli 1.6.0 → 1.7.0

package/README.md

@@ -128,6 +128,8 @@ recess --json goals pdf upload --student <kid-id> --draft <draft-slug> --source-
 recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
 recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
 recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md
+recess --json goals create --student <kid-id> --draft <draft-slug> --title "..." \
+  --description-file ./goal.md --enable-applet-follow-ups
 recess --json goals files list --student <kid-id> --goal <goal-id>
 ```
 
@@ -183,10 +185,11 @@ previews the per-student outcome. `set-metadata` and `delete` require `--expecte
 it always runs the backend's guarded preview first and requires the preview's exact loss token in
 addition to `--confirm` when protected template data would be removed.
 
-MODULE_BACKED BLUEPRINT content is authored as a local workspace tree, batch-upserted to a named
-goal draft, then attached with `capture-snapshot`. Both mutations run server previews before the
-confirmation gate. Goal-content upserts are compare-and-set against the previewed revision; capture is
-fenced to both that source change and the template version. Direct live-goal `modules/` and
-`state/` writes are blocked because those files have database projections.
+Module-backed content is authored as a local workspace tree and batch-upserted to a named goal
+draft. For a personal one-off goal, `goals create --draft` validates and materializes that draft
+directly. For reusable content, attach it to a BLUEPRINT with `capture-snapshot`. Every mutation
+runs a server preview before the confirmation gate and is compare-and-set against the previewed
+revision. Direct live-goal `modules/` and `state/` writes remain blocked because those files have
+database projections.
 
 See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/args.js

@@ -12,6 +12,8 @@ const BOOLEAN_FLAGS = new Set([
     "archived",
     "confirm",
     "dry-run",
+    "disable-applet-follow-ups",
+    "enable-applet-follow-ups",
     "full",
     "help",
     "immediate",

package/dist/cli.js

@@ -153,7 +153,7 @@ Usage:
   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>
-    (--source-goal <goal-id> | --source-draft <draft-slug> --student <kid-id>)
+    (--source-goal <goal-id> | --source-draft <draft-slug> --student <goal-owner-id>)
     [--dry-run] [--confirm]
   recess [--json] goal-templates apply <template-id> --answers-file <path>
     [--dry-run] [--confirm --approval-token TOKEN]
@@ -162,7 +162,9 @@ Usage:
   recess [--json] goals list --student <kid-id>
   recess [--json] goals create --student <kid-id> --title TEXT
     (--description TEXT | --description-file <path>) [--target-date <iso>]
-    [--schedule TEXT] [--confirm]
+    [--schedule TEXT] [--draft <draft-slug>
+      (--enable-applet-follow-ups | --disable-applet-follow-ups)]
+    [--confirm --approval-token TOKEN]
   recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
     --delta TEXT [--confirm --approval-token TOKEN]
   recess [--json] todos create --student <kid-id> --title TEXT
@@ -174,13 +176,13 @@ Usage:
   recess [--json] rocky get --student <kid-id>
   recess [--json] rocky set --student <kid-id> --patch-file <path/patch.json>
     --expected-updated-at ISO|none [--confirm]
-  recess [--json] goals files list --student <kid-id> --goal <goal-id>
-  recess [--json] goals files read --student <kid-id> --goal <goal-id> --path P
-  recess [--json] goals files write --student <kid-id>
+  recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
+  recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
+  recess [--json] goals files write --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>)
     (--source-dir <local-dir> | --source-file <local-file> --path P)
     [--message TEXT] [--confirm --approval-token TOKEN]
-  recess [--json] goals pdf upload --student <kid-id>
+  recess [--json] goals pdf upload --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
     [--path uploads/name.pdf] [--message TEXT]
     [--confirm --approval-token TOKEN]
@@ -191,6 +193,13 @@ 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
 standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetches).
+For goal workspace and PDF commands, --student names the goal owner. A
+full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
+family_ai sessions remain limited to managed KID profiles.
+"goals create --draft" materializes that validated draft directly as a personal
+module-backed goal; it does not create or apply a reusable template. Its preview
+is bound to the exact workspace revision, hash, module inventory, and applet
+follow-up choice.
 Every template created here is setupMode DETERMINISTIC_WORKFLOW and CANNOT be
 converted back, so "validate-spec" against the same file until it passes, then
 "create". "create" runs a real server-side validation before its gate, so the
@@ -2901,6 +2910,65 @@ export async function runCommand(argv) {
                 throw new CliError("invalid_arguments", "--target-date must be an ISO 8601 datetime.");
             }
             const schedule = flagString(parsed, "schedule");
+            const draftSlug = flagString(parsed, "draft");
+            const enablesAppletFollowUps = hasFlag(parsed, "enable-applet-follow-ups");
+            const disablesAppletFollowUps = hasFlag(parsed, "disable-applet-follow-ups");
+            if (draftSlug && enablesAppletFollowUps === disablesAppletFollowUps) {
+                throw new CliError("invalid_arguments", "A module-backed goal requires exactly one of --enable-applet-follow-ups or --disable-applet-follow-ups.");
+            }
+            if (!draftSlug && (enablesAppletFollowUps || disablesAppletFollowUps)) {
+                throw new CliError("invalid_arguments", "Applet follow-up flags are used with --draft for direct module-backed goals.");
+            }
+            if (draftSlug) {
+                const body = {
+                    studentUserId: userId,
+                    draftSlug,
+                    title,
+                    description,
+                    enableAppletFollowUps: enablesAppletFollowUps,
+                    ...(targetDate ? { targetDate } : {}),
+                    ...(schedule ? { schedule } : {}),
+                };
+                const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
+                    body: { ...body, dryRun: true },
+                }));
+                if (preflight.action !== "preview_module_goal_create") {
+                    throw new CliError("unexpected_response", "Direct module goal creation did not return a preview; no goal was created.");
+                }
+                const preview = {
+                    action: "create a module-backed goal directly from a validated draft workspace",
+                    target: preflight.target,
+                    request: {
+                        title,
+                        descriptionChars: description.length,
+                        descriptionSha256: createHash("sha256")
+                            .update(description)
+                            .digest("hex"),
+                        targetDate: targetDate ?? null,
+                        schedule: schedule ?? null,
+                        enableAppletFollowUps: enablesAppletFollowUps,
+                    },
+                    details: {
+                        currentChangeId: preflight.currentChangeId,
+                        workspaceSha256: preflight.workspaceSha256,
+                        fileCount: preflight.fileCount,
+                        sizeBytes: preflight.sizeBytes,
+                        modules: preflight.modules,
+                        warnings: preflight.warnings,
+                        currentGoalCount: preflight.currentGoalCount,
+                        goalLimit: preflight.goalLimit,
+                        note: "Creates a personal module-backed goal directly. It does not create, capture, or apply a reusable template. After success, Recess removes the draft only when no newer Mesa edit has landed; otherwise it preserves the draft.",
+                    },
+                };
+                requirePreviewBoundConfirmation(parsed, preview);
+                return unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
+                    body: {
+                        ...body,
+                        dryRun: false,
+                        expectedWorkspaceChangeId: preflight.currentChangeId,
+                    },
+                }));
+            }
             const body = {
                 title,
                 description,
@@ -2917,7 +2985,7 @@ export async function runCommand(argv) {
                     schedule: schedule ?? null,
                 },
                 details: {
-                    note: "Creates a description-only goal with no modules or course workspace. For a module-backed course, apply a BLUEPRINT template instead. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
+                    note: "Creates a description-only goal with no modules or course workspace. Pass --draft to create a personal module-backed goal directly. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
                 },
             }, async () => unwrap(await api.client.POST("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },

package/package.json

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