recess-cli 3.51.0 → 3.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -157,6 +157,196 @@ async function resolveSessionRole(api) {
157
157
  * `goals archive`, which frees an open-goal slot and writes a different audit
158
158
  * row. */
159
159
  const EDITABLE_GOAL_STATUSES = ["ACTIVE", "PAUSED"];
160
+ /**
161
+ * A goal's place on the kid's day (`Goal.required`), keyed by `--value`. The
162
+ * deltas are the history lines the staff page's Core toggle writes, so a goal's
163
+ * change log reads the same from either surface.
164
+ */
165
+ const GOAL_PLACEMENTS = {
166
+ on: {
167
+ required: true,
168
+ label: "Core",
169
+ delta: "Moved to Core",
170
+ consequence: (kid) => `Core: part of ${kid}'s day; ${kid} can't leave it.`,
171
+ },
172
+ off: {
173
+ required: false,
174
+ label: "optional",
175
+ delta: "Locked until core is done",
176
+ consequence: (kid) => `Optional: its to-dos open after core work and never count as behind; ${kid} can leave it, and the parent can pause it but not remove it.`,
177
+ },
178
+ };
179
+ function setRequiredCommand(studentUserId, goalId, placement) {
180
+ return `recess goals set-required --student ${studentUserId} --goal ${goalId} --value ${placement} --reason "<why>"`;
181
+ }
182
+ /** The staff page's Core toggle (an /admin route). */
183
+ async function patchGoalPlacement(api, goalId, placement, expectedUpdatedAt) {
184
+ const { required, delta } = GOAL_PLACEMENTS[placement];
185
+ return unwrap(await api.client.PATCH("/admin/browser/students/goals/{goalId}/", {
186
+ params: { path: { goalId } },
187
+ body: {
188
+ required,
189
+ delta,
190
+ ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
191
+ },
192
+ }));
193
+ }
194
+ /**
195
+ * Refuse before the preview, so nobody approves a write that a session other
196
+ * than full-admin cannot complete.
197
+ */
198
+ async function assertFullAdminSession(api, command) {
199
+ const session = unwrap(await api.client.GET("/auth/admin-cli/session/"));
200
+ if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin") {
201
+ throw new CliError("forbidden", session.user.role === "GUARDIAN"
202
+ ? `\`${command}\` needs a full-admin session. A parent makes their own kid's challenge optional with \`recess kid set-goal-required\`.`
203
+ : `Only a full-admin CLI session can run \`${command}\`.`, 1, { sessionRole: session.user.role, cliScope: session.cliScope });
204
+ }
205
+ }
206
+ /** The server's apply runs four units at a time; the follow-up matches it. */
207
+ const APPLY_FAN_OUT = 4;
208
+ async function mapWithLimit(items, limit, task) {
209
+ const results = [];
210
+ let next = 0;
211
+ const worker = async () => {
212
+ while (next < items.length) {
213
+ const index = next++;
214
+ results[index] = await task(items[index]);
215
+ }
216
+ };
217
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
218
+ return results;
219
+ }
220
+ /** Each kid's first name and goal places (`required` reads null as Core). */
221
+ async function readKidGoals(api, studentIds) {
222
+ const ids = [...new Set(studentIds)];
223
+ const kids = await mapWithLimit(ids, APPLY_FAN_OUT, async (studentId) => {
224
+ try {
225
+ const [list, detail] = await Promise.all([
226
+ api.client
227
+ .GET("/tutor/browser/students/{userId}/goals/", {
228
+ params: { path: { userId: studentId } },
229
+ })
230
+ .then(unwrap),
231
+ api.client
232
+ .GET("/tutor/students/{studentId}", {
233
+ params: { path: { studentId } },
234
+ })
235
+ .then(unwrap),
236
+ ]);
237
+ return {
238
+ firstName: detail.student.firstName,
239
+ goals: new Map(list.goals.map((goal) => [
240
+ goal.id,
241
+ { required: goal.required, status: goal.status },
242
+ ])),
243
+ };
244
+ }
245
+ catch (error) {
246
+ return { error: error instanceof Error ? error.message : String(error) };
247
+ }
248
+ });
249
+ return new Map(ids.map((id, index) => [id, kids[index]]));
250
+ }
251
+ function kidFirstName(unit, kids) {
252
+ const kid = kids.get(unit.studentUserId);
253
+ return (kid && "firstName" in kid && kid.firstName) || unit.studentName;
254
+ }
255
+ /**
256
+ * Where a goal this apply did not create stands. Under `--optional` such a
257
+ * goal is reported, never patched: it may be a guide's deliberate Core goal.
258
+ */
259
+ function existingGoalPlace(goalId, kid) {
260
+ if (!kid)
261
+ return { error: "The kid's goals were not read." };
262
+ if ("error" in kid)
263
+ return { error: kid.error };
264
+ const goal = kid.goals.get(goalId);
265
+ if (!goal || goal.status === "COMPLETED")
266
+ return "closed";
267
+ return goal.required ? "core" : "optional";
268
+ }
269
+ /** The `--optional` line each preview row shows. */
270
+ function optionalPreviewPlacement(unit, kids) {
271
+ const kid = kidFirstName(unit, kids);
272
+ if (unit.action === "created")
273
+ return GOAL_PLACEMENTS.off.consequence(kid);
274
+ if (!unit.goalId)
275
+ return undefined;
276
+ const place = existingGoalPlace(unit.goalId, kids.get(unit.studentUserId));
277
+ if (place === "core")
278
+ return `Already on ${kid} and Core. This apply leaves it Core and reports it as not optional.`;
279
+ if (place === "optional")
280
+ return `Already on ${kid} and optional.`;
281
+ return undefined;
282
+ }
283
+ /**
284
+ * `goal-templates apply --optional`: set each goal the apply created to
285
+ * optional, then check every other goal the results name. Nothing throws
286
+ * here; each row says where its goal stands and, when it is not optional,
287
+ * the command that fixes it.
288
+ */
289
+ async function makeAppliedGoalsOptional(api, results) {
290
+ const notCreated = results.filter((unit) => unit.action !== "created" && unit.goalId);
291
+ const kids = await readKidGoals(api, notCreated.map((unit) => unit.studentUserId));
292
+ return mapWithLimit(results, APPLY_FAN_OUT, async (unit) => {
293
+ if (!unit.goalId) {
294
+ return {
295
+ ...unit,
296
+ optional: {
297
+ status: "unchanged",
298
+ reason: "No goal was created.",
299
+ },
300
+ };
301
+ }
302
+ const goalId = unit.goalId;
303
+ const fix = setRequiredCommand(unit.studentUserId, goalId, "off");
304
+ const failed = (error) => ({
305
+ ...unit,
306
+ optional: { status: "failed", error, fix },
307
+ });
308
+ if (unit.action !== "created") {
309
+ const place = existingGoalPlace(goalId, kids.get(unit.studentUserId));
310
+ if (typeof place === "object")
311
+ return failed(`Could not read this goal's place: ${place.error}`);
312
+ if (place === "core")
313
+ return {
314
+ ...unit,
315
+ required: true,
316
+ optional: {
317
+ status: "still_core",
318
+ reason: unit.action === "skipped_existing"
319
+ ? "It was already on the kid, so this apply did not change it."
320
+ : "The apply reported an error but left this goal in place.",
321
+ fix,
322
+ },
323
+ };
324
+ return {
325
+ ...unit,
326
+ ...(place === "optional" ? { required: false } : {}),
327
+ optional: {
328
+ status: "unchanged",
329
+ reason: place === "optional"
330
+ ? "It was already optional."
331
+ : "It is archived or no longer on the kid's list.",
332
+ },
333
+ };
334
+ }
335
+ try {
336
+ const goal = await patchGoalPlacement(api, goalId, "off");
337
+ return goal.required
338
+ ? failed("The server still reports this goal as Core.")
339
+ : {
340
+ ...unit,
341
+ required: goal.required,
342
+ optional: { status: "set" },
343
+ };
344
+ }
345
+ catch (error) {
346
+ return failed(error instanceof Error ? error.message : String(error));
347
+ }
348
+ });
349
+ }
160
350
  /**
161
351
  * Reject bad enum values in a goal patch file *before* the preview is built.
162
352
  *
@@ -5530,6 +5720,12 @@ export async function executeRecessCommand(argv, options = {}) {
5530
5720
  const answersFile = flagString(parsed, "answers-file");
5531
5721
  if (isRemote && answersFile)
5532
5722
  throw new CliError("remote_flag_unavailable", "--answers-file is not available over the hosted CLI; pass --student.");
5723
+ const optional = hasFlag(parsed, "optional");
5724
+ if (isRemote && optional)
5725
+ throw new CliError("remote_flag_unavailable", "--optional is not available over the hosted CLI.");
5726
+ if (optional) {
5727
+ await assertFullAdminSession(api, "goal-templates apply --optional");
5728
+ }
5533
5729
  const students = await resolveStudentList();
5534
5730
  if (!answersFile && students.length === 0) {
5535
5731
  throw new CliError("invalid_arguments", "Pass --student <kid-id-or-name> and/or --answers-file <path>. `goal-templates answers-template <id>` prints the answers shape.");
@@ -5550,10 +5746,16 @@ export async function executeRecessCommand(argv, options = {}) {
5550
5746
  // `--dry-run` is a read: it resolves the whole plan and writes nothing,
5551
5747
  // so it does not gate. Run it, read the per-student results, then confirm.
5552
5748
  if (hasFlag(parsed, "dry-run")) {
5553
- return unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
5749
+ const planned = unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
5554
5750
  params: { path: { id } },
5555
5751
  body: { answers, dryRun: true },
5556
5752
  }));
5753
+ return optional
5754
+ ? {
5755
+ ...planned,
5756
+ optional: "The real run makes each goal it creates optional, and reports any goal it names that is still Core.",
5757
+ }
5758
+ : planned;
5557
5759
  }
5558
5760
  // The real consequence — which students get which goals, which are
5559
5761
  // skipped as already-existing, and what coverage is missing — is only
@@ -5567,10 +5769,15 @@ export async function executeRecessCommand(argv, options = {}) {
5567
5769
  ...totals,
5568
5770
  [result.action]: (totals[result.action] ?? 0) + 1,
5569
5771
  }), {});
5772
+ const kids = optional
5773
+ ? await readKidGoals(api, preflight.results.map((result) => result.studentUserId))
5774
+ : new Map();
5570
5775
  const preview = {
5571
- action: "apply a goal template to students (creates goals and todos)",
5776
+ action: optional
5777
+ ? "apply a goal template to students as optional challenges (creates goals and todos)"
5778
+ : "apply a goal template to students (creates goals and todos)",
5572
5779
  target: { templateId: id, students: preflight.results.length },
5573
- request: { answers },
5780
+ request: { answers, ...(optional ? { optional: true } : {}) },
5574
5781
  details: {
5575
5782
  ...(students.some((student) => student.name)
5576
5783
  ? {
@@ -5588,20 +5795,45 @@ export async function executeRecessCommand(argv, options = {}) {
5588
5795
  goalTitle: result.goalTitle,
5589
5796
  todoTitle: result.todoTitle,
5590
5797
  warnings: result.warnings,
5798
+ ...(optional
5799
+ ? { placement: optionalPreviewPlacement(result, kids) }
5800
+ : {}),
5591
5801
  })),
5592
5802
  missingCoverage: preflight.missingCoverage,
5593
5803
  templateVersion: preflight.templateVersion,
5594
5804
  note: "Counts come from the backend's own dry run. `skipped_existing` items are idempotent — re-applying does not duplicate them.",
5805
+ ...(optional
5806
+ ? {
5807
+ optional: "Each goal this creates is set optional right after it is created, in this same operation. A goal already on the kid keeps its place; if it is Core, the run reports it with the command that makes it optional.",
5808
+ }
5809
+ : {}),
5595
5810
  },
5596
5811
  };
5597
- const apply = async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
5598
- params: { path: { id } },
5599
- body: {
5600
- answers,
5601
- dryRun: false,
5602
- expectedTemplateVersion: preflight.templateVersion,
5603
- },
5604
- }));
5812
+ const apply = async () => {
5813
+ const applied = unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
5814
+ params: { path: { id } },
5815
+ body: {
5816
+ answers,
5817
+ dryRun: false,
5818
+ expectedTemplateVersion: preflight.templateVersion,
5819
+ },
5820
+ }));
5821
+ if (!optional)
5822
+ return applied;
5823
+ const results = await makeAppliedGoalsOptional(api, applied.results);
5824
+ const notOptional = results.flatMap((unit) => unit.optional.status === "failed"
5825
+ ? [{ unit, why: unit.optional.error, fix: unit.optional.fix }]
5826
+ : unit.optional.status === "still_core"
5827
+ ? [{ unit, why: unit.optional.reason, fix: unit.optional.fix }]
5828
+ : []);
5829
+ if (notOptional.length > 0) {
5830
+ throw new CliError("optional_not_set", `The apply finished, but ${notOptional.length} goal(s) are still Core, not optional. Do not apply again. Run each fix below; for a goal that was already on the kid, check first that it is not a guide's deliberate Core goal:\n${notOptional.map(({ unit, why, fix }) => `- ${fix} (${unit.studentName}, goal ${unit.goalId}: ${why})`).join("\n")}`, 1, {
5831
+ applied: { ...applied, results },
5832
+ notOptional: notOptional.map(({ unit }) => unit),
5833
+ });
5834
+ }
5835
+ return { ...applied, results };
5836
+ };
5605
5837
  // Hosted (Parent Rocky's power-parent lane): the operation store's
5606
5838
  // preview → confirm, not the local approval ledger.
5607
5839
  return isRemote
@@ -5846,6 +6078,67 @@ export async function executeRecessCommand(argv, options = {}) {
5846
6078
  params: { path: { goalId } },
5847
6079
  })));
5848
6080
  }
6081
+ if (verb === "set-required") {
6082
+ const student = await studentFlag(api, parsed, { required: true });
6083
+ const studentId = student.id;
6084
+ const goalId = flagString(parsed, "goal", { required: true });
6085
+ const placement = assertChoice(flagString(parsed, "value", { required: true }).trim().toLowerCase(), ["on", "off"], "--value");
6086
+ await assertFullAdminSession(api, "goals set-required");
6087
+ const [goals, detail] = await Promise.all([
6088
+ api.client
6089
+ .GET("/tutor/browser/students/{userId}/goals/", {
6090
+ params: { path: { userId: studentId } },
6091
+ })
6092
+ .then(unwrap),
6093
+ api.client
6094
+ .GET("/tutor/students/{studentId}", {
6095
+ params: { path: { studentId } },
6096
+ })
6097
+ .then(unwrap),
6098
+ ]);
6099
+ const current = goals.goals.find((goal) => goal.id === goalId);
6100
+ if (!current) {
6101
+ throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
6102
+ }
6103
+ if (current.status === "COMPLETED") {
6104
+ throw new CliError("goal_not_open", `Goal ${goalId} ("${current.title}") is archived, so it has no place on the kid's day to change.`);
6105
+ }
6106
+ const target = GOAL_PLACEMENTS[placement];
6107
+ if (current.required === target.required) {
6108
+ throw new CliError(placement === "on" ? "already_core" : "already_optional", `Goal ${goalId} ("${current.title}") is already ${target.label}.`);
6109
+ }
6110
+ const kid = detail.student.firstName ?? student.name ?? "the kid";
6111
+ const preview = {
6112
+ action: `make ${kid}'s challenge "${current.title}" ${target.label}`,
6113
+ target: {
6114
+ goalId,
6115
+ studentUserId: studentId,
6116
+ title: current.title,
6117
+ status: current.status,
6118
+ required: current.required,
6119
+ },
6120
+ request: {
6121
+ required: target.required,
6122
+ delta: target.delta,
6123
+ expectedUpdatedAt: current.updatedAt,
6124
+ },
6125
+ details: {
6126
+ ...resolvedStudentDetails(student),
6127
+ consequence: target.consequence(kid),
6128
+ undo: setRequiredCommand(studentId, goalId, placement === "on" ? "off" : "on"),
6129
+ },
6130
+ };
6131
+ return previewBoundWrite(parsed, preview, async () => {
6132
+ const goal = await patchGoalPlacement(api, goalId, placement, current.updatedAt);
6133
+ return {
6134
+ goalId: goal.id,
6135
+ studentUserId: studentId,
6136
+ title: goal.title,
6137
+ required: goal.required,
6138
+ updatedAt: goal.updatedAt,
6139
+ };
6140
+ });
6141
+ }
5849
6142
  if (verb === "list") {
5850
6143
  const student = await studentFlag(api, parsed, { required: true });
5851
6144
  const userId = student.id;
@@ -6371,7 +6664,7 @@ export async function executeRecessCommand(argv, options = {}) {
6371
6664
  }
6372
6665
  throw new CliError("invalid_arguments", "Use goals queue get|set.");
6373
6666
  }
6374
- throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|complete-module|launch-todo|queue|files|pdf|video.");
6667
+ throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|set-required|complete|undo-completion|move-module|complete-module|launch-todo|queue|files|pdf|video.");
6375
6668
  }
6376
6669
  if (noun === "channels") {
6377
6670
  return runChannelsCommand({ parsed, api, writeCommand });
@@ -6581,6 +6874,91 @@ export async function executeRecessCommand(argv, options = {}) {
6581
6874
  request: {},
6582
6875
  }, async () => unwrap(await api.client.POST("/admin/browser/students/{userId}/issued-email/", { params: { path: { userId: studentId } } })));
6583
6876
  }
6877
+ if (verb === "main-book") {
6878
+ const file = flagString(parsed, "file");
6879
+ if (file) {
6880
+ const { absolutePath, parsed: rows } = await readJsonValue(file, "Books file");
6881
+ if (!Array.isArray(rows) || rows.length === 0) {
6882
+ throw new CliError("invalid_arguments", `Books file must be a JSON array of { student, title, author?, libraryBookId?, goalId? } (${absolutePath}).`);
6883
+ }
6884
+ const books = [];
6885
+ for (const [index, row] of rows.entries()) {
6886
+ const entry = row && typeof row === "object" && !Array.isArray(row)
6887
+ ? row
6888
+ : {};
6889
+ const text = (key) => {
6890
+ const value = entry[key];
6891
+ return typeof value === "string" && value.trim()
6892
+ ? value.trim()
6893
+ : undefined;
6894
+ };
6895
+ const student = text("student");
6896
+ if (!student ||
6897
+ !(text("title") || text("libraryBookId") || text("goalId"))) {
6898
+ throw new CliError("invalid_arguments", `Row ${index + 1} needs a student and a title, libraryBookId or goalId (${absolutePath}).`);
6899
+ }
6900
+ books.push({
6901
+ kidId: (await resolveStudentReference(api, student)).id,
6902
+ student,
6903
+ title: text("title"),
6904
+ author: text("author"),
6905
+ libraryBookId: text("libraryBookId"),
6906
+ goalId: text("goalId"),
6907
+ });
6908
+ }
6909
+ return writeCommand(parsed, {
6910
+ action: "set the main book for several kids (each kid's current main book is marked finished)",
6911
+ target: { students: books.length },
6912
+ request: { books },
6913
+ details: {
6914
+ consequence: "Each kid's writing prompts draw on their new book from now on.",
6915
+ },
6916
+ }, async () => {
6917
+ const results = [];
6918
+ for (const { student, ...body } of books) {
6919
+ const res = await api.client.PUT("/ela/book", { body });
6920
+ results.push(res.data
6921
+ ? { student, ok: true, title: res.data.title }
6922
+ : {
6923
+ student,
6924
+ ok: false,
6925
+ error: res.error
6926
+ ?.message ?? `HTTP ${res.response.status}`,
6927
+ });
6928
+ }
6929
+ return {
6930
+ set: results.filter((result) => result.ok).length,
6931
+ failed: results.filter((result) => !result.ok).length,
6932
+ results,
6933
+ };
6934
+ });
6935
+ }
6936
+ const student = await studentFlag(api, parsed, { required: true });
6937
+ const title = flagString(parsed, "title");
6938
+ const author = flagString(parsed, "author");
6939
+ const libraryBookId = flagString(parsed, "library-book");
6940
+ const goalId = flagString(parsed, "goal");
6941
+ if (!title && !libraryBookId && !goalId) {
6942
+ return unwrap(await api.client.GET("/ela/book", {
6943
+ params: { query: { kidId: student.id } },
6944
+ }));
6945
+ }
6946
+ const body = {
6947
+ kidId: student.id,
6948
+ ...(title ? { title } : {}),
6949
+ ...(author ? { author } : {}),
6950
+ ...(libraryBookId ? { libraryBookId } : {}),
6951
+ ...(goalId ? { goalId } : {}),
6952
+ };
6953
+ return writeCommand(parsed, {
6954
+ action: "set a kid's main book (their current main book is marked finished)",
6955
+ target: { studentUserId: student.id },
6956
+ request: body,
6957
+ details: {
6958
+ consequence: "The kid's writing prompts draw on this book from now on.",
6959
+ },
6960
+ }, async () => unwrap(await api.client.PUT("/ela/book", { body })));
6961
+ }
6584
6962
  if (verb === "goblins") {
6585
6963
  const studentId = flagString(parsed, "student", { required: true });
6586
6964
  const search = flagString(parsed, "search");
@@ -6662,7 +7040,7 @@ export async function executeRecessCommand(argv, options = {}) {
6662
7040
  return { studentId, flashcardReviewEnabled: on };
6663
7041
  });
6664
7042
  }
6665
- throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|map-reports|issue-email|goblins|web-todos|flashcards.");
7043
+ throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|map-reports|issue-email|main-book|goblins|web-todos|flashcards.");
6666
7044
  }
6667
7045
  if (noun === "todos") {
6668
7046
  if (verb === "create") {
@@ -600,6 +600,7 @@ const STAFF_COMMANDS = new Set([
600
600
  "students map-reports upload",
601
601
  "students map-reports delete",
602
602
  "students issue-email",
603
+ "students main-book",
603
604
  "students goblins",
604
605
  "students web-todos",
605
606
  "students flashcards",
package/dist/help.js CHANGED
@@ -90,6 +90,9 @@ Usage:
90
90
  recess [--json] students map-reports delete --student <kid-id> --report <report-id>
91
91
  [--confirm]
92
92
  recess [--json] students issue-email --student <kid-id> [--confirm]
93
+ recess [--json] students main-book [--student <kid-id>]
94
+ [--title TEXT] [--author TEXT] [--library-book <book-id>] [--goal <goal-id>]
95
+ [--file </path/to/books.json>] [--confirm]
93
96
  recess [--json] students goblins --student <kid-id> [--course <slug>] [--search TEXT]
94
97
  [--confirm]
95
98
  recess [--json] students web-todos --student <kid-id> [--on|--off] [--confirm]
@@ -671,7 +674,7 @@ Usage:
671
674
  recess [--json] goal-templates answers-template <template-id|slug>
672
675
  [--student <kid-id-or-name>]
673
676
  recess [--json] goal-templates apply <template-id> [--student <kid-id-or-name>]
674
- [--answers-file <path>] [--dry-run] [--confirm --approval-token TOKEN]
677
+ [--answers-file <path>] [--optional] [--dry-run] [--confirm --approval-token TOKEN]
675
678
  recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
676
679
  [--answers-file <path>] [--confirm]
677
680
  recess [--json] goals list --student <kid-id> [--query <text>] [--include-archived]
@@ -692,6 +695,8 @@ Usage:
692
695
  [--confirm --approval-token TOKEN]
693
696
  recess [--json] goals unarchive <goal-id> --student <kid-id>
694
697
  [--confirm --approval-token TOKEN]
698
+ recess [--json] goals set-required --student <kid-id> --goal <goal-id> --value on|off
699
+ [--confirm --approval-token TOKEN]
695
700
  recess [--json] goals move-module <module-ref> --student <kid-id> --goal <goal-id>
696
701
  (--to-end | --position <n>) [--confirm --approval-token TOKEN]
697
702
  recess [--json] goals complete-module <module-ref> --student <kid-id> --goal <goal-id>
@@ -841,6 +846,12 @@ converted back, so "validate-spec" against the same file until it passes, then
841
846
  "create". "create" runs a real server-side validation before its gate, so the
842
847
  preview shows the handler/goalShape/step keys the SERVER resolved. "apply" runs
843
848
  the backend's own dryRun before the gate and previews the per-student outcome.
849
+ "apply --optional" (full-admin) then makes each goal it created optional in the
850
+ same operation. If that fails, or a goal it names was already on the kid and is
851
+ Core (never patched: it may be a guide's), it exits optional_not_set with fixes.
852
+ "goals set-required" (full-admin) is the staff page's Core toggle for any kid's
853
+ open goal: on = Core (part of the day; the kid can't leave it), off = optional
854
+ (unlocks after core work, never behind, the kid can leave it).
844
855
  "set-metadata", "delete", "patch-spec" and "set-policy" take an optional
845
856
  --expected-version; omitted, the current version is read and pinned into the
846
857
  preview, so a change before confirm is refused. A stale one 409s STALE_WRITE.
@@ -934,6 +945,15 @@ them. --focus is that adult's own instructions for the daily summary (what to
934
945
  cover and how). A recipient with no phone number receives nothing, so check
935
946
  "users phone get" too.
936
947
 
948
+ "students main-book" takes --student or --file. With only --student it shows
949
+ the kid's main book (it still needs --reason, as the command can write). Add --title
950
+ (and --author), --library-book or --goal to set it; the book they had is marked
951
+ finished. --library-book links our library copy, so prompts know the story;
952
+ --goal links the kid's reading goal, so its finished parts count as readings.
953
+ --file takes a JSON array of { student, title, author?, libraryBookId?, goalId? }
954
+ (student is an ID or exact roster name) and sets every kid in one confirm; the
955
+ result lists each kid as set or failed.
956
+
937
957
  "students goblins" rosters a kid into Goblins (issuing their Recess email first)
938
958
  in one class per course: --course usa-3rd..usa-8th, usa-algebra-1, usa-geometry,
939
959
  usa-algebra-2 or pre-calculus; without it the kid's profile grade picks one. A
@@ -1307,6 +1327,7 @@ export const COMMAND_SUMMARIES = {
1307
1327
  "students map-reports upload": "File a full MAP report PDF (e.g. Learning Statements) beside that season's scores for parents, the kid, and guides.",
1308
1328
  "students map-reports delete": "Remove a filed MAP report PDF.",
1309
1329
  "students issue-email": "Issue a Recess email address for a kid.",
1330
+ "students main-book": "Show or set the main book a kid is reading, which their writing draws on; --file sets many kids at once.",
1310
1331
  "students goblins": "Roster a kid into Goblins so their Goblins todos sign them straight in.",
1311
1332
  "students web-todos": "Show or set whether a kid's todos run on web (off: they open in the desktop app).",
1312
1333
  "students flashcards": "Show or set whether a kid gets a daily flashcard review todo.",
@@ -1699,6 +1720,7 @@ export const COMMAND_SUMMARIES = {
1699
1720
  "goals complete": "Mark a goal complete.",
1700
1721
  "goals undo-completion": "Reopen a completed goal.",
1701
1722
  "goals archive": "Archive a goal.",
1723
+ "goals set-required": "Put a kid's goal in Core (on) or make it optional (off), any family.",
1702
1724
  "goals unarchive": "Unarchive a goal.",
1703
1725
  "goals move-module": "Reorder a module in a goal's queue.",
1704
1726
  "goals complete-module": "Mark a module done so the goal moves on.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.51.0",
3
+ "version": "3.52.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {