recess-cli 3.25.0 → 3.27.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
@@ -13,6 +13,7 @@ import { runAppsCommand } from "./commands/apps.js";
13
13
  import { runChannelsCommand } from "./commands/channels.js";
14
14
  import { runChatLogsCommand } from "./commands/chat-logs.js";
15
15
  import { runLibraryBooksCommand } from "./commands/library-books.js";
16
+ import { runChallengeOfTheWeekCommand } from "./commands/challenge-of-the-week.js";
16
17
  import { runDbCommand } from "./commands/db.js";
17
18
  import { runRoomsCommand } from "./commands/rooms.js";
18
19
  import { runDmsCommand } from "./commands/dms.js";
@@ -26,6 +27,7 @@ import { runReportsCommand } from "./commands/reports.js";
26
27
  import { runMasteryCommand } from "./commands/mastery.js";
27
28
  import { runOnboardingCommand } from "./commands/onboarding.js";
28
29
  import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
30
+ import { runPlacementCommand } from "./commands/placement.js";
29
31
  import { runRockyFreeCommand } from "./commands/rocky-free.js";
30
32
  import { runSchoolCommand } from "./commands/school.js";
31
33
  import { runVillageEventsCommand } from "./commands/village-events.js";
@@ -1256,6 +1258,18 @@ const STORE_ITEM_SORT_FIELDS = [
1256
1258
  "order",
1257
1259
  ];
1258
1260
  const CONTENT_LIBRARY_STAGES = ["review", "polish"];
1261
+ const GOBLINS_COURSES = [
1262
+ "usa-3rd",
1263
+ "usa-4th",
1264
+ "usa-5th",
1265
+ "usa-6th",
1266
+ "usa-7th",
1267
+ "usa-8th",
1268
+ "usa-algebra-1",
1269
+ "usa-geometry",
1270
+ "usa-algebra-2",
1271
+ "pre-calculus",
1272
+ ];
1259
1273
  const CONTENT_LIBRARY_RESOURCE_STAGES = [
1260
1274
  "review",
1261
1275
  "polishing",
@@ -6034,6 +6048,9 @@ export async function executeRecessCommand(argv, options = {}) {
6034
6048
  if (noun === "library-books") {
6035
6049
  return runLibraryBooksCommand({ parsed, api, writeCommand });
6036
6050
  }
6051
+ if (noun === "challenge-of-the-week") {
6052
+ return runChallengeOfTheWeekCommand({ parsed, api, writeCommand });
6053
+ }
6037
6054
  if (noun === "db") {
6038
6055
  return runDbCommand({ parsed, api, writeCommand });
6039
6056
  }
@@ -6055,6 +6072,9 @@ export async function executeRecessCommand(argv, options = {}) {
6055
6072
  if (noun === "reports") {
6056
6073
  return runReportsCommand({ parsed, api, writeCommand });
6057
6074
  }
6075
+ if (noun === "placement") {
6076
+ return runPlacementCommand({ parsed, api, writeCommand });
6077
+ }
6058
6078
  if (noun === "students") {
6059
6079
  if (verb === "list") {
6060
6080
  const requestedScope = flagString(parsed, "scope");
@@ -6206,6 +6226,23 @@ export async function executeRecessCommand(argv, options = {}) {
6206
6226
  request: {},
6207
6227
  }, async () => unwrap(await api.client.POST("/admin/browser/students/{userId}/issued-email/", { params: { path: { userId: studentId } } })));
6208
6228
  }
6229
+ if (verb === "goblins") {
6230
+ const studentId = flagString(parsed, "student", { required: true });
6231
+ const course = flagString(parsed, "course");
6232
+ if (course && !GOBLINS_COURSES.includes(course)) {
6233
+ throw new CliError("invalid_arguments", `--course must be one of ${GOBLINS_COURSES.join(", ")}.`);
6234
+ }
6235
+ return writeCommand(parsed, {
6236
+ action: "roster a kid into Goblins so their Goblins todos sign them in (takes a Goblins seat the kid keeps)",
6237
+ target: { studentUserId: studentId },
6238
+ request: course ? { course } : {},
6239
+ }, async () => unwrap(await api.client.POST("/admin/browser/students/{userId}/goblins/", {
6240
+ params: { path: { userId: studentId } },
6241
+ body: course
6242
+ ? { course: course }
6243
+ : {},
6244
+ })));
6245
+ }
6209
6246
  if (verb === "web-todos") {
6210
6247
  const studentId = flagString(parsed, "student", { required: true });
6211
6248
  const on = hasFlag(parsed, "on");
@@ -6264,7 +6301,7 @@ export async function executeRecessCommand(argv, options = {}) {
6264
6301
  return { studentId, flashcardReviewEnabled: on };
6265
6302
  });
6266
6303
  }
6267
- throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|issue-email|web-todos|flashcards.");
6304
+ throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|issue-email|goblins|web-todos|flashcards.");
6268
6305
  }
6269
6306
  if (noun === "todos") {
6270
6307
  if (verb === "create") {
@@ -280,6 +280,7 @@ const FAMILY_AI_COMMANDS = new Set([
280
280
  "goals queue set",
281
281
  "goals unarchive",
282
282
  "library-books add",
283
+ "library-books delete",
283
284
  "library-books get",
284
285
  "library-books list",
285
286
  "library-books search",
@@ -302,6 +303,16 @@ const FAMILY_AI_COMMANDS = new Set([
302
303
  "tutor-templates unassign",
303
304
  ]);
304
305
  const STAFF_COMMANDS = new Set([
306
+ "challenge-of-the-week bench add",
307
+ "challenge-of-the-week bench list",
308
+ "challenge-of-the-week bench move",
309
+ "challenge-of-the-week bench remove",
310
+ "challenge-of-the-week clear",
311
+ "challenge-of-the-week list",
312
+ "challenge-of-the-week note",
313
+ "challenge-of-the-week queue",
314
+ "challenge-of-the-week show",
315
+ "challenge-of-the-week swap",
305
316
  "students mastery",
306
317
  "apps link",
307
318
  "apps links",
@@ -383,6 +394,11 @@ const STAFF_COMMANDS = new Set([
383
394
  "payout items edit",
384
395
  "payout payruns list",
385
396
  "payout recipients list",
397
+ "placement give",
398
+ "placement questions",
399
+ "placement results",
400
+ "placement show",
401
+ "placement sync-mastery",
386
402
  "registrations approve",
387
403
  "registrations deny",
388
404
  "school codes get",
@@ -403,6 +419,7 @@ const STAFF_COMMANDS = new Set([
403
419
  "store-items list",
404
420
  "students upload-map-scores",
405
421
  "students issue-email",
422
+ "students goblins",
406
423
  "students web-todos",
407
424
  "students flashcards",
408
425
  "students notes add",
@@ -0,0 +1,303 @@
1
+ import { apiError, CliError } from "../errors.js";
2
+ import { flagString, hasFlag } from "../args.js";
3
+ import { flagInteger, positional } from "./shared.js";
4
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
5
+ const WEEK_KEY_RE = /^\d{4}-\d{2}-\d{2}$/;
6
+ const NOTE_MAX = 80;
7
+ // `@tryrecess/web-schema` GENERATED_CHALLENGE_TAG / LIBRARY_LISTED_TAG (this package does not
8
+ // depend on web-schema); the server's `publicChallengeLibraryWhere` is the rule this mirrors.
9
+ const GENERATED_CHALLENGE_TAG = "rocky-generated";
10
+ const LIBRARY_LISTED_TAG = "library-listed";
11
+ /**
12
+ * The staff routes answer `{ statusCode, error, message, code }`. Surface the machine `code`
13
+ * (lower-cased, like this file's own refusals: `week_locked`, `template_not_public`) and the
14
+ * server's message, instead of the bare HTTP status text the generic `unwrap` reports. A 404
15
+ * with no `code` is the app's unknown-route answer, which the routes give a caller without the
16
+ * `challenge-of-the-week` flag: say so instead of "not found".
17
+ */
18
+ function cotw(result) {
19
+ if (result.response.ok && result.data !== undefined)
20
+ return result.data;
21
+ const status = result.response.status;
22
+ const fallback = apiError(status, result.error);
23
+ const body = (result.error ?? {});
24
+ if (status === 404 && typeof body.code !== "string") {
25
+ throw new CliError("not_enabled", "Challenge of the Week isn't enabled for your account.", 1, { status, body: result.error });
26
+ }
27
+ throw new CliError(typeof body.code === "string" ? body.code.toLowerCase() : fallback.code, typeof body.message === "string" ? body.message : fallback.message, 1, { status, body: result.error });
28
+ }
29
+ /** `this` | `next` | `last` | a Monday `YYYY-MM-DD` → a week key. The server owns Pacific week
30
+ * math: the words resolve from its `currentWeekKey`, and a non-Monday answers NOT_A_MONDAY. */
31
+ async function resolveWeekKey(api, raw) {
32
+ if (WEEK_KEY_RE.test(raw))
33
+ return raw;
34
+ const offsets = { last: -1, this: 0, next: 1 };
35
+ const offset = offsets[raw];
36
+ if (offset === undefined) {
37
+ throw new CliError("invalid_arguments", "A week is this, next, last, or a Monday YYYY-MM-DD.");
38
+ }
39
+ const body = cotw(await api.client.GET("/admin/challenge-of-the-week/weeks", {
40
+ params: { query: { past: 1, ahead: 1 } },
41
+ }));
42
+ const current = body.weeks.findIndex((w) => w.weekKey === body.currentWeekKey);
43
+ const week = current < 0 ? undefined : body.weeks[current + offset];
44
+ if (!week) {
45
+ throw new CliError("invalid_arguments", `Could not resolve week ${raw}.`);
46
+ }
47
+ return week.weekKey;
48
+ }
49
+ /** A goal template by UUID (one read) or exact slug (the library's own `query` filter, then an
50
+ * exact slug match: a slug that is a substring of other titles still resolves to itself). */
51
+ async function resolveTemplate(api, ref) {
52
+ const notFound = () => new CliError("not_found", `No goal template with id or slug "${ref}".`);
53
+ if (UUID_RE.test(ref)) {
54
+ const result = await api.client.GET("/ai/goal-templates/{id}", {
55
+ params: { path: { id: ref } },
56
+ });
57
+ if (result.response.status === 404)
58
+ throw notFound();
59
+ return cotw(result);
60
+ }
61
+ const list = cotw(await api.client.GET("/ai/goal-templates/", {
62
+ params: { query: { view: "card", query: ref } },
63
+ }));
64
+ const match = list.items.find((t) => t.slug === ref);
65
+ if (!match)
66
+ throw notFound();
67
+ // The list hides deleted templates, so a match is live.
68
+ return { ...match, deletedAt: null };
69
+ }
70
+ /** Pickable = in the kids' library (`publicChallengeLibraryWhere`) AND joinable
71
+ * (DETERMINISTIC_WORKFLOW). Refused here, before any preview; the server's 422s
72
+ * (TEMPLATE_NOT_PUBLIC / TEMPLATE_NOT_JOINABLE) are the backstop. */
73
+ function assertPickable(t) {
74
+ const reason = t.deletedAt
75
+ ? "deleted"
76
+ : t.visibility !== "PUBLIC"
77
+ ? t.visibility
78
+ : t.tags.includes(GENERATED_CHALLENGE_TAG) &&
79
+ !t.tags.includes(LIBRARY_LISTED_TAG)
80
+ ? "not library-listed"
81
+ : null;
82
+ if (reason) {
83
+ throw new CliError("template_not_public", `${t.title} is not in the kids' library (${reason}). Publish it, or pick another.`);
84
+ }
85
+ if (t.setupMode !== "DETERMINISTIC_WORKFLOW") {
86
+ throw new CliError("template_not_joinable", `${t.title} has no Join for kids (setup mode ${t.setupMode}). Pick a challenge kids can join.`);
87
+ }
88
+ }
89
+ /** `--note`: trimmed, "" → null (no note), at most 80 characters; undefined = not given. */
90
+ function readNote(parsed) {
91
+ if ((parsed.occurrences.get("note") ?? 0) > 1) {
92
+ throw new CliError("invalid_arguments", "Pass --note once.");
93
+ }
94
+ const note = flagString(parsed, "note");
95
+ if (note === undefined)
96
+ return undefined;
97
+ const trimmed = note.trim();
98
+ if (trimmed.length > NOTE_MAX) {
99
+ throw new CliError("invalid_arguments", `--note is ${trimmed.length} characters; the limit is ${NOTE_MAX}.`);
100
+ }
101
+ return trimmed === "" ? null : trimmed;
102
+ }
103
+ async function readWeek(api, weekKey) {
104
+ return cotw(await api.client.GET("/admin/challenge-of-the-week/weeks/{weekKey}", {
105
+ params: { path: { weekKey } },
106
+ }));
107
+ }
108
+ /** The preflight read refuses what the server would 409, before a preview asks for approval. */
109
+ function assertWeekAccepts(verb, week) {
110
+ if (week.relation === "past") {
111
+ throw new CliError("week_in_past", `${week.weekKey} is in the past and cannot be changed.`);
112
+ }
113
+ if (verb === "queue" && week.pick) {
114
+ throw new CliError("week_already_picked", `${week.weekKey} already has ${week.pick.template.title}. Use swap to replace it.`);
115
+ }
116
+ if (verb === "clear" && week.relation === "current") {
117
+ throw new CliError("week_locked", "This week's pick cannot be cleared (kids would have none until Monday). Use swap.");
118
+ }
119
+ if (verb !== "queue" && !week.pick) {
120
+ throw new CliError("week_empty", verb === "clear"
121
+ ? `${week.weekKey} has no pick to clear.`
122
+ : `${week.weekKey} has no pick. Use queue.`);
123
+ }
124
+ }
125
+ function pickConsequence(week, title, swapping) {
126
+ if (week.relation === "current") {
127
+ const keep = swapping && week.pick
128
+ ? ` Kids who already joined ${week.pick.template.title} keep their 2x.`
129
+ : "";
130
+ return `Kids see ${title} as the Challenge of the Week now. Kids already in ${title} get their goal stamped for this week's 2x.${keep}`;
131
+ }
132
+ return `Kids see ${title} as the Challenge of the Week from Monday ${week.weekKey} 00:00 PT.`;
133
+ }
134
+ function benchOrder(titles) {
135
+ return `The bench becomes: ${titles.map((t, i) => `${i + 1}. ${t}`).join(", ") || "(empty)"}`;
136
+ }
137
+ const templateSummary = (t) => ({ slug: t.slug, title: t.title, visibility: t.visibility });
138
+ export async function runChallengeOfTheWeekCommand(context) {
139
+ const { parsed, api, writeCommand } = context;
140
+ const verb = parsed.positionals[1];
141
+ if (verb === "list") {
142
+ const past = flagInteger(parsed, "past", { min: 0, max: 12 }) ?? 0;
143
+ const ahead = flagInteger(parsed, "ahead", { min: 0, max: 26 }) ?? 8;
144
+ return cotw(await api.client.GET("/admin/challenge-of-the-week/weeks", {
145
+ params: { query: { past, ahead } },
146
+ }));
147
+ }
148
+ if (verb === "show") {
149
+ return readWeek(api, await resolveWeekKey(api, positional(parsed, 2, "week")));
150
+ }
151
+ if (verb === "queue" || verb === "swap") {
152
+ const note = readNote(parsed);
153
+ const template = await resolveTemplate(api, positional(parsed, 2, "template id or slug"));
154
+ assertPickable(template);
155
+ const weekKey = await resolveWeekKey(api, flagString(parsed, "week", { required: true }));
156
+ const week = await readWeek(api, weekKey);
157
+ assertWeekAccepts(verb, week);
158
+ const body = {
159
+ goalTemplateId: template.id,
160
+ ...(note === undefined ? {} : { note }),
161
+ };
162
+ return writeCommand(parsed, {
163
+ action: verb === "queue"
164
+ ? "queue a Challenge of the Week pick"
165
+ : "swap a Challenge of the Week pick",
166
+ target: { weekKey },
167
+ request: body,
168
+ details: {
169
+ template: templateSummary(template),
170
+ week: {
171
+ relation: week.relation,
172
+ currentPick: week.pick
173
+ ? {
174
+ slug: week.pick.template.slug,
175
+ title: week.pick.template.title,
176
+ source: week.pick.source,
177
+ }
178
+ : null,
179
+ benchWouldFill: week.benchFill?.slug ?? null,
180
+ },
181
+ // A swap without --note keeps the old pick's note: show it, since it was written
182
+ // for a different challenge.
183
+ noteAfter: note === undefined ? (week.pick?.note ?? null) : note,
184
+ consequence: pickConsequence(week, template.title, verb === "swap"),
185
+ },
186
+ }, async () => verb === "queue"
187
+ ? cotw(await api.client.POST("/admin/challenge-of-the-week/weeks/{weekKey}/queue", { params: { path: { weekKey } }, body }))
188
+ : cotw(await api.client.POST("/admin/challenge-of-the-week/weeks/{weekKey}/swap", { params: { path: { weekKey } }, body })));
189
+ }
190
+ if (verb === "note") {
191
+ const clearing = hasFlag(parsed, "clear");
192
+ const note = readNote(parsed);
193
+ if (clearing === (note !== undefined)) {
194
+ throw new CliError("invalid_arguments", "Pass exactly one of --note TEXT or --clear.");
195
+ }
196
+ const weekKey = await resolveWeekKey(api, flagString(parsed, "week", { required: true }));
197
+ const week = await readWeek(api, weekKey);
198
+ assertWeekAccepts("note", week);
199
+ const body = { note: clearing ? null : (note ?? null) };
200
+ return writeCommand(parsed, {
201
+ action: "set a Challenge of the Week note",
202
+ target: { weekKey },
203
+ request: body,
204
+ details: {
205
+ pick: week.pick?.template.title ?? null,
206
+ previousNote: week.pick?.note ?? null,
207
+ consequence: body.note
208
+ ? `Kids see this note under the Challenge of the Week for ${weekKey}.`
209
+ : `The Challenge of the Week for ${weekKey} shows no note.`,
210
+ },
211
+ }, async () => cotw(await api.client.PATCH("/admin/challenge-of-the-week/weeks/{weekKey}/note", { params: { path: { weekKey } }, body })));
212
+ }
213
+ if (verb === "clear") {
214
+ const weekKey = await resolveWeekKey(api, flagString(parsed, "week", { required: true }));
215
+ const week = await readWeek(api, weekKey);
216
+ assertWeekAccepts("clear", week);
217
+ const removes = week.pick.template;
218
+ return writeCommand(parsed, {
219
+ action: "clear a Challenge of the Week pick",
220
+ target: { weekKey },
221
+ request: {},
222
+ details: {
223
+ removes: { slug: removes.slug, title: removes.title },
224
+ consequence: `${weekKey} becomes empty. Unless someone queues it, the Monday 00:00 PT rollover fills it from the top of the bench, or it stays empty: empty weeks fill from the bench once the first queued week has started.`,
225
+ },
226
+ }, async () => cotw(await api.client.DELETE("/admin/challenge-of-the-week/weeks/{weekKey}", { params: { path: { weekKey } } })));
227
+ }
228
+ if (verb === "bench")
229
+ return runBench(context);
230
+ throw new CliError("invalid_arguments", "Use challenge-of-the-week list|show|queue|swap|note|clear|bench.");
231
+ }
232
+ async function runBench({ parsed, api, writeCommand, }) {
233
+ const verb = parsed.positionals[2];
234
+ const readBench = async () => cotw(await api.client.GET("/admin/challenge-of-the-week/bench"));
235
+ if (verb === "list")
236
+ return readBench();
237
+ if (verb !== "add" && verb !== "move" && verb !== "remove") {
238
+ throw new CliError("invalid_arguments", "Use challenge-of-the-week bench list|add|move|remove.");
239
+ }
240
+ const ref = positional(parsed, 3, "template id or slug");
241
+ const position = verb === "remove"
242
+ ? undefined
243
+ : flagInteger(parsed, "position", { required: verb === "move", min: 1 });
244
+ const { items } = await readBench();
245
+ // add resolves from the library (it must be pickable); move/remove from the bench itself, so a
246
+ // template that has since left the library can still be moved or taken off.
247
+ let template;
248
+ if (verb === "add") {
249
+ const resolved = await resolveTemplate(api, ref);
250
+ assertPickable(resolved);
251
+ if (items.some((b) => b.goalTemplateId === resolved.id)) {
252
+ throw new CliError("already_on_bench", `${resolved.title} is already on the bench. Use bench move.`);
253
+ }
254
+ template = resolved;
255
+ }
256
+ else {
257
+ const onBench = items.find((b) => b.goalTemplateId === ref || b.template.slug === ref);
258
+ if (!onBench) {
259
+ throw new CliError("not_on_bench", `"${ref}" is not on the bench.`);
260
+ }
261
+ template = onBench.template;
262
+ }
263
+ const titles = items
264
+ .filter((b) => b.goalTemplateId !== template.id)
265
+ .map((b) => b.template.title);
266
+ // The server's clamp: position 1..n (n = the bench without this template, plus one).
267
+ const at = Math.min(position ?? titles.length + 1, titles.length + 1) - 1;
268
+ const projected = verb === "remove"
269
+ ? titles
270
+ : [...titles.slice(0, at), template.title, ...titles.slice(at)];
271
+ const preview = {
272
+ action: {
273
+ add: "add a challenge to the Challenge of the Week bench",
274
+ move: "move a challenge on the Challenge of the Week bench",
275
+ remove: "remove a challenge from the Challenge of the Week bench",
276
+ }[verb],
277
+ target: { goalTemplateId: template.id },
278
+ request: position === undefined ? {} : { position },
279
+ details: {
280
+ template: templateSummary(template),
281
+ benchNow: items.map((b) => b.template.slug),
282
+ consequence: benchOrder(projected),
283
+ },
284
+ };
285
+ return writeCommand(parsed, preview, async () => {
286
+ if (verb === "add") {
287
+ return cotw(await api.client.POST("/admin/challenge-of-the-week/bench", {
288
+ body: {
289
+ goalTemplateId: template.id,
290
+ ...(position === undefined ? {} : { position }),
291
+ },
292
+ }));
293
+ }
294
+ if (verb === "move") {
295
+ return cotw(await api.client.PATCH("/admin/challenge-of-the-week/bench/{goalTemplateId}", {
296
+ params: { path: { goalTemplateId: template.id } },
297
+ body: { position: position },
298
+ }));
299
+ }
300
+ return cotw(await api.client.DELETE("/admin/challenge-of-the-week/bench/{goalTemplateId}", { params: { path: { goalTemplateId: template.id } } }));
301
+ });
302
+ }
303
+ //# sourceMappingURL=challenge-of-the-week.js.map
@@ -100,6 +100,24 @@ export async function runLibraryBooksCommand(context) {
100
100
  },
101
101
  }, async () => unwrap(await api.client.POST("/library-books/from-web", { body })));
102
102
  }
103
- throw new CliError("invalid_arguments", "Use library-books search|list|get|add.");
103
+ if (verb === "delete") {
104
+ const id = positional(parsed, 2, "library book ID");
105
+ const book = unwrap(await api.client.GET("/library-books/{id}", {
106
+ params: { path: { id } },
107
+ }));
108
+ return writeCommand(parsed, {
109
+ action: "delete a book from the shared library",
110
+ target: { id: book.id },
111
+ request: { id: book.id },
112
+ details: {
113
+ title: book.title,
114
+ author: book.author,
115
+ consequence: "Removes the book from the library; goals already built from it keep their chapters and PDF.",
116
+ },
117
+ }, async () => unwrap(await api.client.DELETE("/library-books/{id}", {
118
+ params: { path: { id: book.id } },
119
+ })));
120
+ }
121
+ throw new CliError("invalid_arguments", "Use library-books search|list|get|add|delete.");
104
122
  }
105
123
  //# sourceMappingURL=library-books.js.map
@@ -0,0 +1,176 @@
1
+ import { unwrap } from "../api.js";
2
+ import { flagString, hasFlag } from "../args.js";
3
+ import { CliError } from "../errors.js";
4
+ import { assertChoice, flagInteger } from "./shared.js";
5
+ const SUBJECTS = ["math", "reading"];
6
+ const show = (value) => value === null ? "-" : String(value);
7
+ export async function runPlacementCommand({ parsed, api, writeCommand, }) {
8
+ const verb = parsed.positionals[1];
9
+ if (verb !== "results" &&
10
+ verb !== "questions" &&
11
+ verb !== "sync-mastery" &&
12
+ verb !== "give" &&
13
+ verb !== "show") {
14
+ throw new CliError("invalid_arguments", "Use placement give|show|results|questions|sync-mastery.");
15
+ }
16
+ const json = hasFlag(parsed, "json");
17
+ if (verb === "show") {
18
+ const student = flagString(parsed, "student", { required: true });
19
+ const mastery = unwrap(await api.client.GET("/tutor/browser/students/{userId}/mastery/", {
20
+ params: { path: { userId: student } },
21
+ }));
22
+ const placements = mastery.subjects.map((subject) => ({
23
+ ...subject.placement,
24
+ subjectLabel: subject.label,
25
+ }));
26
+ if (json)
27
+ return { student, placements };
28
+ return {
29
+ help: placements
30
+ .map((p) => {
31
+ const status = p.completedAt
32
+ ? `placed ${p.label} on ${p.completedAt.slice(0, 10)}${p.rushed ? " (rushed: answered in a few seconds each)" : ""}`
33
+ : p.assignedAt
34
+ ? `quest given ${p.assignedAt.slice(0, 10)}, ${p.answeredCount} answered`
35
+ : "no placement quest yet";
36
+ const lines = [`${p.subjectLabel}: ${status}`];
37
+ if (p.gaps.length > 0)
38
+ lines.push(` Gaps: ${p.gaps.join(", ")}`);
39
+ if (p.results.length > 0) {
40
+ const right = p.results.filter((r) => r.correct).length;
41
+ lines.push(` ${right} of ${p.results.length} right`);
42
+ for (const r of p.results) {
43
+ lines.push(` ${r.correct ? "right" : "wrong"} [${r.grade}] ${r.prompt} (${r.seconds}s)`);
44
+ if (!r.correct)
45
+ lines.push(` picked ${r.chosen ?? "Not sure"}${r.misconception ? ` · ${r.misconception}` : ""}`);
46
+ }
47
+ }
48
+ const sounds = p.sounds;
49
+ if (sounds) {
50
+ lines.push(` Sounds: tapped ${sounds.tapCorrect} of ${sounds.tapAnswered} right${sounds.tapAnswered < sounds.tapTotal ? " (not finished)" : ""}`);
51
+ for (const miss of sounds.missed)
52
+ lines.push(` heard "${miss.word}"${miss.madeUp ? " (made up)" : ""}, picked ${miss.chosen ?? "Not sure"}${miss.misconception ? ` · ${miss.misconception}` : ""}`);
53
+ const read = sounds.readAloud;
54
+ lines.push(!read
55
+ ? " Read aloud: not done yet"
56
+ : read.skipped
57
+ ? " Read aloud: skipped, no microphone"
58
+ : ` Read aloud: ${read.wordsPerMinute} words a minute, ${Math.round((read.accuracy ?? 0) * 100)}% read right${read.misread.length ? `; missed or misread: ${read.misread.join(", ")}` : ""}`);
59
+ }
60
+ return lines.join("\n");
61
+ })
62
+ .join("\n\n"),
63
+ };
64
+ }
65
+ if (verb === "give") {
66
+ const student = flagString(parsed, "student", { required: true });
67
+ const subject = assertChoice(flagString(parsed, "subject", { required: true }), SUBJECTS, "--subject");
68
+ const result = await writeCommand(parsed, {
69
+ action: "give the kid the placement quest as a todo (a finished quest is retired so they start fresh; an open quest todo is reused)",
70
+ target: { student, subject },
71
+ request: { userId: student },
72
+ }, async () => unwrap(await api.client.POST("/admin/placement/{subject}/assign", {
73
+ params: { path: { subject } },
74
+ body: { userId: student },
75
+ })));
76
+ if (json)
77
+ return result;
78
+ return {
79
+ help: result.created
80
+ ? `Gave ${student} the ${subject} placement quest (todo ${result.todoId}).`
81
+ : `${student} already has an open ${subject} placement quest (todo ${result.todoId}).`,
82
+ };
83
+ }
84
+ if (verb === "sync-mastery") {
85
+ const attemptId = flagString(parsed, "attempt", { required: true });
86
+ const result = await writeCommand(parsed, {
87
+ action: "record this finished placement quest's answers in the kid's mastery graphs as assessment evidence (idempotent: answers already recorded are skipped)",
88
+ target: { attemptId },
89
+ request: {},
90
+ }, async () => unwrap(await api.client.POST("/admin/placement/attempts/{attemptId}/sync-mastery", { params: { path: { attemptId } }, body: {} })));
91
+ if (json)
92
+ return result;
93
+ const counts = Object.entries(result.questions);
94
+ return {
95
+ help: [
96
+ `Attempt ${result.attemptId}`,
97
+ ...(counts.length
98
+ ? counts.map(([status, count]) => ` ${status}: ${count}`)
99
+ : [" no questions"]),
100
+ `Updated skills: ${result.updatedSkills}`,
101
+ ].join("\n"),
102
+ };
103
+ }
104
+ const subject = assertChoice(flagString(parsed, "subject", { required: true }), SUBJECTS, "--subject");
105
+ if (verb === "results") {
106
+ const student = flagString(parsed, "student");
107
+ const result = unwrap(await api.client.GET("/admin/placement/{subject}", {
108
+ params: { path: { subject } },
109
+ }));
110
+ const attempts = student
111
+ ? result.attempts.filter((attempt) => attempt.userId === student)
112
+ : result.attempts;
113
+ if (json)
114
+ return { ...result, attempts };
115
+ if (attempts.length === 0) {
116
+ return {
117
+ help: student
118
+ ? `No ${subject} placement attempts for ${student}.`
119
+ : `No ${subject} placement attempts.`,
120
+ };
121
+ }
122
+ return {
123
+ help: attempts
124
+ .map((attempt) => {
125
+ const gap = attempt.estimatedRit !== null && attempt.mapRit !== null
126
+ ? attempt.estimatedRit - attempt.mapRit
127
+ : null;
128
+ const line = [
129
+ `${attempt.learner} (kid ${attempt.userId})`,
130
+ `attempt ${attempt.id}`,
131
+ attempt.status,
132
+ `${attempt.correctCount}/${attempt.answeredCount} correct of ${attempt.total}`,
133
+ `band ${show(attempt.band)}${attempt.bandLabel ? ` ${attempt.bandLabel}` : ""}`,
134
+ `est RIT ${show(attempt.estimatedRit)}`,
135
+ `MAP RIT ${show(attempt.mapRit)}`,
136
+ `gap ${gap === null ? "-" : gap > 0 ? `+${gap}` : String(gap)}`,
137
+ ].join(" ");
138
+ const misses = attempt.misses.map((miss) => ` miss [band ${miss.band}] ${miss.prompt}\n chose ${miss.chosen ?? "(no answer)"}${miss.misconception ? ` (${miss.misconception})` : ""}`);
139
+ return [line, ...misses].join("\n");
140
+ })
141
+ .join("\n\n"),
142
+ };
143
+ }
144
+ const band = flagInteger(parsed, "band", { min: 1, max: 10 });
145
+ const result = unwrap(await api.client.GET("/admin/placement/{subject}/questions", {
146
+ params: { path: { subject } },
147
+ }));
148
+ const questions = band === undefined
149
+ ? result.questions
150
+ : result.questions.filter((question) => question.band === band);
151
+ if (json)
152
+ return { ...result, questions };
153
+ if (questions.length === 0) {
154
+ return { help: `No ${subject} placement questions in band ${band}.` };
155
+ }
156
+ const labels = new Map(result.bands.map((entry) => [entry.band, entry]));
157
+ const seenPassages = new Set();
158
+ const blocks = questions.map((question) => {
159
+ const bandInfo = labels.get(question.band);
160
+ const lines = [
161
+ `${question.id} band ${question.band}${bandInfo ? ` ${bandInfo.label} (RIT ${bandInfo.rit})` : ""} ${question.standard}`,
162
+ ];
163
+ if (question.passage && !seenPassages.has(question.passage)) {
164
+ seenPassages.add(question.passage);
165
+ lines.push(...question.passage.split("\n").map((text) => ` | ${text}`));
166
+ }
167
+ lines.push(` ${question.prompt}`);
168
+ for (const choice of question.choices) {
169
+ const correct = choice.id === question.answerId;
170
+ lines.push(` ${correct ? "*" : " "} ${choice.id}. ${choice.text}${!correct && choice.misconception ? ` (${choice.misconception})` : ""}`);
171
+ }
172
+ return lines.join("\n");
173
+ });
174
+ return { help: [result.test, ...blocks].join("\n\n") };
175
+ }
176
+ //# sourceMappingURL=placement.js.map
package/dist/help.js CHANGED
@@ -79,6 +79,7 @@ Usage:
79
79
  recess [--json] students upload-map-scores --student <kid-id>
80
80
  --file </path/to/map-report.pdf> [--confirm]
81
81
  recess [--json] students issue-email --student <kid-id> [--confirm]
82
+ recess [--json] students goblins --student <kid-id> [--course <slug>] [--confirm]
82
83
  recess [--json] students web-todos --student <kid-id> [--on|--off] [--confirm]
83
84
  recess [--json] students flashcards --student <kid-id> [--on|--off] [--confirm]
84
85
  recess [--json] students notes add --student <kid-id> --text TEXT [--confirm]
@@ -300,6 +301,11 @@ Usage:
300
301
  [--cohort <cohort-id>] [--week YYYY-MM-DD] [--no-ai] [--out <dir>]
301
302
  recess [--json] reports parent-recap --student <student-id> [--week YYYY-MM-DD] [--no-ai] [--summary <file.json>] [--out <dir>]
302
303
  recess [--json] reports parent-recap publish --student <student-id> --week YYYY-MM-DD [--no-text] [--to <phone>] [--confirm]
304
+ recess [--json] placement give --student <kid-id> --subject math|reading [--confirm]
305
+ recess [--json] placement show --student <kid-id>
306
+ recess [--json] placement results --subject math|reading [--student <kid-id>]
307
+ recess [--json] placement questions --subject math|reading [--band <n>]
308
+ recess [--json] placement sync-mastery --attempt <attempt-id> [--confirm]
303
309
  recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
304
310
  recess [--json] cohorts schedule get <cohort-id>
305
311
  recess [--json] cohorts schedule set <cohort-id> --days <MO,WE> --time <09:30> [--timezone <zone>] --effective-date <YYYY-MM-DD> --notify none|parents [--confirm] [--approval-token <token>]
@@ -627,6 +633,17 @@ Usage:
627
633
  recess [--json] library-books add (--md5 <md5> --title TEXT [--author TEXT]
628
634
  --extension pdf|epub [--cover-url <url>] | --from-search N --query TEXT)
629
635
  [--confirm]
636
+ recess [--json] library-books delete <book-id> [--confirm]
637
+ recess [--json] challenge-of-the-week list [--past N] [--ahead N]
638
+ recess [--json] challenge-of-the-week show <week>
639
+ recess [--json] challenge-of-the-week queue <template> --week <week> [--note TEXT] [--confirm]
640
+ recess [--json] challenge-of-the-week swap <template> --week <week> [--note TEXT] [--confirm]
641
+ recess [--json] challenge-of-the-week note --week <week> (--note TEXT | --clear) [--confirm]
642
+ recess [--json] challenge-of-the-week clear --week <week> [--confirm]
643
+ recess [--json] challenge-of-the-week bench list
644
+ recess [--json] challenge-of-the-week bench add <template> [--position N] [--confirm]
645
+ recess [--json] challenge-of-the-week bench move <template> --position N [--confirm]
646
+ recess [--json] challenge-of-the-week bench remove <template> [--confirm]
630
647
  recess [--json] goals notes list --student <goal-owner-id> --goal <goal-id>
631
648
  recess [--json] goals notes get --student <goal-owner-id> --goal <goal-id>
632
649
  [--lesson <item-key|module-ref>]
@@ -775,6 +792,14 @@ them. --focus is that adult's own instructions for the daily summary (what to
775
792
  cover and how). A recipient with no phone number receives nothing, so check
776
793
  "users phone get" too.
777
794
 
795
+ "students goblins" rosters a kid into Goblins (issuing their Recess email first)
796
+ in one class per course: --course usa-3rd..usa-8th, usa-algebra-1, usa-geometry,
797
+ usa-algebra-2 or pre-calculus; without it the kid's profile grade picks one. A
798
+ new kid takes a Goblins seat and keeps it. status eligible means a todo whose
799
+ url is https://app.goblins.com/?skill=<topic> signs them straight into problems
800
+ on that topic; unlicensed means no seat is free yet (rerun later). Never paste a
801
+ /handoff/ link into a todo: it works once and expires.
802
+
778
803
  Onboarding notes: "status" and "intake-session" are reads — "intake-session"
779
804
  looks up the current IN_PROGRESS session without creating one (prints a "none
780
805
  yet" result when absent). "intake-session-create" is the explicit write that
@@ -1017,6 +1042,13 @@ server when the served bundle's minCliVersion allows — an older binary keeps t
1017
1042
  bundled copy, and an unreachable server is not an error. "doctor" reports whether
1018
1043
  a newer skill exists and names the command; it never writes.
1019
1044
 
1045
+ "challenge-of-the-week" runs the weekly pick every kid sees (ADMIN and GUIDE). <week> is
1046
+ this, next, last, or a Monday YYYY-MM-DD (weeks run Monday to Sunday, Pacific). <template> is a
1047
+ goal template id or slug; only kid-visible (PUBLIC, library-listed), joinable challenges can be
1048
+ picked or benched. Empty weeks fill from the bench once the first queued week has started (the
1049
+ top of the bench at Monday 00:00 PT). This week can be swapped, never cleared; past weeks cannot
1050
+ change. --note is at most 80 characters.
1051
+
1020
1052
  Writes preview and exit 2 until confirmed after explicit human approval. Every
1021
1053
  preview includes an operationKey. Simplest confirm: "recess confirm <operation-key>"
1022
1054
  replays the stored preview. Equivalently, rerun the same command with --confirm
@@ -1103,6 +1135,7 @@ export const COMMAND_SUMMARIES = {
1103
1135
  "students texts set-guardian": "Change one adult's SMS frequency, focus, or on/off.",
1104
1136
  "students upload-map-scores": "Upload a NWEA MAP score report PDF for a kid.",
1105
1137
  "students issue-email": "Issue a Recess email address for a kid.",
1138
+ "students goblins": "Roster a kid into Goblins so their Goblins todos sign them straight in.",
1106
1139
  "students web-todos": "Show or set whether a kid's todos run on web (off: they open in the desktop app).",
1107
1140
  "students flashcards": "Show or set whether a kid gets a daily flashcard review todo.",
1108
1141
  "students interests": "List, add, or remove a kid's interests (Rocky, the feed, and reading/writing passages use them).",
@@ -1244,6 +1277,11 @@ export const COMMAND_SUMMARIES = {
1244
1277
  "channels members remove": "Remove members from a channel (soft).",
1245
1278
  "tuition-plans generate": "Compute a tuition plan sheet (web URL, optional PDF); stores nothing.",
1246
1279
  "tuition-plans states": "List states supported by tuition plans.",
1280
+ "placement give": "Give a kid the math or reading placement quest as a todo.",
1281
+ "placement show": "One kid's placement answers, mistakes, timing and sounds check.",
1282
+ "placement results": "Kids' placement quest results beside their latest MAP score.",
1283
+ "placement questions": "The placement quest question bank with answers and misconceptions.",
1284
+ "placement sync-mastery": "Record a finished placement's answers in the kid's mastery graphs.",
1247
1285
  "cohorts get": "Read a cohort and its events.",
1248
1286
  "cohorts schedule get": "Read a cohort's recurring schedule.",
1249
1287
  "cohorts schedule set": "Change a cohort's recurring schedule from a date.",
@@ -1444,6 +1482,17 @@ export const COMMAND_SUMMARIES = {
1444
1482
  "library-books list": "List books in the shared library.",
1445
1483
  "library-books get": "Read one library book: status, pages, chapters.",
1446
1484
  "library-books add": "Add a web search result to the book library.",
1485
+ "library-books delete": "Remove a book from the book library.",
1486
+ "challenge-of-the-week list": "List Challenge of the Week picks: past, this week, upcoming, and the bench.",
1487
+ "challenge-of-the-week show": "Read one week's Challenge of the Week pick and note.",
1488
+ "challenge-of-the-week queue": "Queue a challenge for an empty week, with an optional note for kids.",
1489
+ "challenge-of-the-week swap": "Replace a week's Challenge of the Week pick.",
1490
+ "challenge-of-the-week note": "Set or clear the note kids see under a week's pick.",
1491
+ "challenge-of-the-week clear": "Empty a future week (this week can only be swapped). Empty weeks fill from the bench once the first queued week has started.",
1492
+ "challenge-of-the-week bench list": "List the bench that fills empty weeks, top first.",
1493
+ "challenge-of-the-week bench add": "Add a challenge to the bench.",
1494
+ "challenge-of-the-week bench move": "Move a bench challenge to a position.",
1495
+ "challenge-of-the-week bench remove": "Take a challenge off the bench.",
1447
1496
  "goals notes list": "List Rocky's per-kid notes on a goal.",
1448
1497
  "goals notes get": "Read the goal's or one lesson's note.",
1449
1498
  "goals notes set": "Write Rocky's note for this kid on a lesson (never the lesson itself).",
@@ -1483,6 +1532,7 @@ export const NOUN_SUMMARIES = {
1483
1532
  kid: "One of your kids: today, goals, profile, texts, logins, pods.",
1484
1533
  channels: "Community channels and their members.",
1485
1534
  "tuition-plans": "Compute tuition plan sheets (stores nothing).",
1535
+ placement: "Give placement quests, one kid's results, results vs MAP, question bank, mastery sync.",
1486
1536
  feed: "Post messages to users' feeds.",
1487
1537
  dms: "Send Recess chat DMs as yourself.",
1488
1538
  events: "Class events: list, attendance, cancel, reschedule, add.",
@@ -1501,7 +1551,8 @@ export const NOUN_SUMMARIES = {
1501
1551
  memories: "Kid memory files and the context Rocky sees.",
1502
1552
  rocky: "A kid's Rocky personality settings; free Rocky grants and budgets.",
1503
1553
  "tutor-templates": "Tutor templates and their assignment to kids.",
1504
- "library-books": "Book library: search the web, add books, read status.",
1554
+ "library-books": "Book library: search the web, add and delete books, read status.",
1555
+ "challenge-of-the-week": "Challenge of the Week: queue weekly picks and the bench (ADMIN, GUIDE).",
1505
1556
  mastery: "Mastery graphs and the content linked to them.",
1506
1557
  };
1507
1558
  //# sourceMappingURL=help.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.25.0",
3
+ "version": "3.27.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {