recess-cli 3.51.0 → 3.53.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") {
@@ -54,6 +54,7 @@ export const FAMILY_REMOTE_READS = [
54
54
  "kid logins",
55
55
  "kid map-scores",
56
56
  "kid evidence",
57
+ "kid rooms",
57
58
  "kid screenshots",
58
59
  "kid send-screenshot",
59
60
  "kid moments",
@@ -313,6 +314,7 @@ const FAMILY_COMMANDS = new Set([
313
314
  "kid logins",
314
315
  "kid map-scores",
315
316
  "kid evidence",
317
+ "kid rooms",
316
318
  "kid screenshots",
317
319
  "kid send-screenshot",
318
320
  "kid moments",
@@ -600,6 +602,7 @@ const STAFF_COMMANDS = new Set([
600
602
  "students map-reports upload",
601
603
  "students map-reports delete",
602
604
  "students issue-email",
605
+ "students main-book",
603
606
  "students goblins",
604
607
  "students web-todos",
605
608
  "students flashcards",
@@ -865,13 +865,19 @@ export async function runFamilyCommand({ parsed, api, writeCommand, }) {
865
865
  const kid = hasFlag(parsed, "student")
866
866
  ? await resolveFamilyKid(api, parsed)
867
867
  : kids[0];
868
- const body = { text, ...(ask ? { ask } : {}), studentId: kid.id };
868
+ const eventId = flagUuid(parsed, "event");
869
+ const body = {
870
+ text,
871
+ ...(ask ? { ask } : {}),
872
+ studentId: kid.id,
873
+ ...(eventId ? { eventId } : {}),
874
+ };
869
875
  return writeCommand(parsed, {
870
- action: `message ${kidName(kid)}'s guide: "${text.slice(0, 120)}"`,
876
+ action: `message ${eventId ? `the teacher of ${kidName(kid)}'s class` : `${kidName(kid)}'s guide`}: "${text.slice(0, 120)}"`,
871
877
  target: { family: "@me", ...kidTarget(kid) },
872
878
  request: body,
873
879
  details: {
874
- consequence: "The guide gets a support ticket, plus a message on Slack and in your chat with them in the Recess app, and answers there. It can't be unsent.",
880
+ consequence: `${eventId ? "The class's teacher" : "The guide"} gets a support ticket, plus a message on Slack and in your chat with them in the Recess app, and answers there. It can't be unsent.`,
875
881
  },
876
882
  }, async () => unwrap(await api.client.POST("/parent-v2/message-guide/", { body })));
877
883
  }
@@ -1878,6 +1884,35 @@ export async function runKidCommand({ parsed, api, writeCommand, }) {
1878
1884
  },
1879
1885
  }));
1880
1886
  }
1887
+ if (verb === "rooms") {
1888
+ const sessionId = flagUuid(parsed, "session");
1889
+ const search = flagString(parsed, "search")?.trim();
1890
+ if (!sessionId) {
1891
+ if (hasFlag(parsed, "ask") || hasFlag(parsed, "page"))
1892
+ throw new CliError("invalid_arguments", "--ask and --page read one room: pass --session (ids from kid rooms).");
1893
+ const days = flagInteger(parsed, "days", { min: 1, max: 60 });
1894
+ return unwrap(await api.client.GET("/parent-v2/kid/{kidId}/rooms/", {
1895
+ params: {
1896
+ path: { kidId },
1897
+ query: { ...(days ? { days } : {}), ...(search ? { search } : {}) },
1898
+ },
1899
+ }));
1900
+ }
1901
+ const ask = flagString(parsed, "ask")?.trim();
1902
+ if (ask && search)
1903
+ throw new CliError("invalid_arguments", "Pass --ask or --search, not both.");
1904
+ const page = flagInteger(parsed, "page", { min: 1, max: 500 });
1905
+ return unwrap(await api.client.GET("/parent-v2/kid/{kidId}/rooms/{sessionId}/", {
1906
+ params: {
1907
+ path: { kidId, sessionId },
1908
+ query: {
1909
+ ...(page ? { page } : {}),
1910
+ ...(search ? { search } : {}),
1911
+ ...(ask ? { ask } : {}),
1912
+ },
1913
+ },
1914
+ }));
1915
+ }
1881
1916
  if (verb === "screenshots") {
1882
1917
  const todoId = flagUuid(parsed, "todo", { required: true });
1883
1918
  const frames = flagString(parsed, "frames")?.trim();
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]
@@ -243,7 +246,8 @@ Usage:
243
246
  recess [--json] family memory rewrite --in family|me --text TEXT [--confirm]
244
247
  recess [--json] family memory forget --in journal|family|me --line TEXT
245
248
  [--date YYYY-MM-DD] [--confirm]
246
- recess [--json] family message-guide --text TEXT [--ask TEXT] [--student <kid>] [--confirm]
249
+ recess [--json] family message-guide --text TEXT [--ask TEXT] [--student <kid>] [--event <event-id>]
250
+ [--confirm]
247
251
  recess [--json] family report-bug --text TEXT [--summary TEXT] [--kind bug|request] [--student <kid>]
248
252
  [--todo <todo-id>] [--confirm]
249
253
  recess [--json] kid today --student <kid> [--date YYYY-MM-DD]
@@ -300,6 +304,8 @@ Usage:
300
304
  [--confirm]
301
305
  recess [--json] kid set-goal-coins --student <kid> --goal <goal-id> --value 0-20|default [--confirm]
302
306
  recess [--json] kid evidence --student <kid> --todo <todo-id> [--search TEXT]
307
+ recess [--json] kid rooms --student <kid> [--days 1-60] [--session <session-id>] [--page N]
308
+ [--search TEXT] [--ask TEXT]
303
309
  recess [--json] kid screenshots --student <kid> --todo <todo-id> [--frames 269,280]
304
310
  recess [--json] kid send-screenshot --student <kid> --todo <todo-id> --frames 269,280
305
311
  [--caption TEXT] [--confirm]
@@ -671,7 +677,7 @@ Usage:
671
677
  recess [--json] goal-templates answers-template <template-id|slug>
672
678
  [--student <kid-id-or-name>]
673
679
  recess [--json] goal-templates apply <template-id> [--student <kid-id-or-name>]
674
- [--answers-file <path>] [--dry-run] [--confirm --approval-token TOKEN]
680
+ [--answers-file <path>] [--optional] [--dry-run] [--confirm --approval-token TOKEN]
675
681
  recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
676
682
  [--answers-file <path>] [--confirm]
677
683
  recess [--json] goals list --student <kid-id> [--query <text>] [--include-archived]
@@ -692,6 +698,8 @@ Usage:
692
698
  [--confirm --approval-token TOKEN]
693
699
  recess [--json] goals unarchive <goal-id> --student <kid-id>
694
700
  [--confirm --approval-token TOKEN]
701
+ recess [--json] goals set-required --student <kid-id> --goal <goal-id> --value on|off
702
+ [--confirm --approval-token TOKEN]
695
703
  recess [--json] goals move-module <module-ref> --student <kid-id> --goal <goal-id>
696
704
  (--to-end | --position <n>) [--confirm --approval-token TOKEN]
697
705
  recess [--json] goals complete-module <module-ref> --student <kid-id> --goal <goal-id>
@@ -841,6 +849,12 @@ converted back, so "validate-spec" against the same file until it passes, then
841
849
  "create". "create" runs a real server-side validation before its gate, so the
842
850
  preview shows the handler/goalShape/step keys the SERVER resolved. "apply" runs
843
851
  the backend's own dryRun before the gate and previews the per-student outcome.
852
+ "apply --optional" (full-admin) then makes each goal it created optional in the
853
+ same operation. If that fails, or a goal it names was already on the kid and is
854
+ Core (never patched: it may be a guide's), it exits optional_not_set with fixes.
855
+ "goals set-required" (full-admin) is the staff page's Core toggle for any kid's
856
+ open goal: on = Core (part of the day; the kid can't leave it), off = optional
857
+ (unlocks after core work, never behind, the kid can leave it).
844
858
  "set-metadata", "delete", "patch-spec" and "set-policy" take an optional
845
859
  --expected-version; omitted, the current version is read and pinned into the
846
860
  preview, so a change before confirm is refused. A stale one 409s STALE_WRITE.
@@ -934,6 +948,15 @@ them. --focus is that adult's own instructions for the daily summary (what to
934
948
  cover and how). A recipient with no phone number receives nothing, so check
935
949
  "users phone get" too.
936
950
 
951
+ "students main-book" takes --student or --file. With only --student it shows
952
+ the kid's main book (it still needs --reason, as the command can write). Add --title
953
+ (and --author), --library-book or --goal to set it; the book they had is marked
954
+ finished. --library-book links our library copy, so prompts know the story;
955
+ --goal links the kid's reading goal, so its finished parts count as readings.
956
+ --file takes a JSON array of { student, title, author?, libraryBookId?, goalId? }
957
+ (student is an ID or exact roster name) and sets every kid in one confirm; the
958
+ result lists each kid as set or failed.
959
+
937
960
  "students goblins" rosters a kid into Goblins (issuing their Recess email first)
938
961
  in one class per course: --course usa-3rd..usa-8th, usa-algebra-1, usa-geometry,
939
962
  usa-algebra-2 or pre-calculus; without it the kid's profile grade picks one. A
@@ -1307,6 +1330,7 @@ export const COMMAND_SUMMARIES = {
1307
1330
  "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
1331
  "students map-reports delete": "Remove a filed MAP report PDF.",
1309
1332
  "students issue-email": "Issue a Recess email address for a kid.",
1333
+ "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
1334
  "students goblins": "Roster a kid into Goblins so their Goblins todos sign them straight in.",
1311
1335
  "students web-todos": "Show or set whether a kid's todos run on web (off: they open in the desktop app).",
1312
1336
  "students flashcards": "Show or set whether a kid gets a daily flashcard review todo.",
@@ -1414,7 +1438,7 @@ export const COMMAND_SUMMARIES = {
1414
1438
  "family memory save": "Save one line to Rocky's family notes, with your name (at once).",
1415
1439
  "family memory rewrite": "Replace family.md or your own notes whole, tidied (at once).",
1416
1440
  "family memory forget": "Forget one exact line of the family notes (at once).",
1417
- "family message-guide": "Message your kid's guide (a support ticket; Rocky tells them in the app and on Slack); the person for anything. --text is the full note, kept on the ticket; --ask is what the guide is sent: who asked, what they want and the one fact the guide needs, in a line or two (200 characters). Always pass --ask.",
1441
+ "family message-guide": "Message your kid's guide (a support ticket; Rocky tells them in the app and on Slack); the person for anything. --text is the full note, kept on the ticket; --ask is what the guide is sent: who asked, what they want and the one fact the guide needs, in a line or two (200 characters). Always pass --ask. --event (a class session, from kid schedule, attendance or rooms) sends it to that class's teachers instead of the kid's guide: for a question about one class.",
1418
1442
  "family report-bug": "Report a bug, or a request (--kind request: something missing, or what you think of Rocky), to the Recess team (at once; not a change).",
1419
1443
  "family remind": "Have Rocky text you a reminder (applies at once).",
1420
1444
  "family reminders": "Your upcoming text-me reminders.",
@@ -1471,6 +1495,7 @@ export const COMMAND_SUMMARIES = {
1471
1495
  "kid set-challenge-order": "Set the order a kid's challenges run in; their to-dos follow it (at once).",
1472
1496
  "kid set-goal-coins": "Coins each of one challenge's to-dos pays, 0-20 or default, fixed (at once; tutors too).",
1473
1497
  "kid evidence": "What one to-do's session record shows: analysis, stretches, frame numbers.",
1498
+ "kid rooms": "The live rooms and classes a kid was in, and what was said: --session reads one's transcript a page at a time, --search the lines around a word, --ask an answer from the whole class.",
1474
1499
  "kid screenshots": "Links to up to five session screenshots of one to-do.",
1475
1500
  "kid send-screenshot": "Show a parent session screenshots: pictures on a Rocky text, links elsewhere.",
1476
1501
  "kid create-challenge": "A private fixed challenge: the same to-do on set days, optionally limited (at once; accounts that can create challenges).",
@@ -1699,6 +1724,7 @@ export const COMMAND_SUMMARIES = {
1699
1724
  "goals complete": "Mark a goal complete.",
1700
1725
  "goals undo-completion": "Reopen a completed goal.",
1701
1726
  "goals archive": "Archive a goal.",
1727
+ "goals set-required": "Put a kid's goal in Core (on) or make it optional (off), any family.",
1702
1728
  "goals unarchive": "Unarchive a goal.",
1703
1729
  "goals move-module": "Reorder a module in a goal's queue.",
1704
1730
  "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.53.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {