recess-cli 3.25.0 → 3.26.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") {
@@ -302,6 +302,16 @@ const FAMILY_AI_COMMANDS = new Set([
302
302
  "tutor-templates unassign",
303
303
  ]);
304
304
  const STAFF_COMMANDS = new Set([
305
+ "challenge-of-the-week bench add",
306
+ "challenge-of-the-week bench list",
307
+ "challenge-of-the-week bench move",
308
+ "challenge-of-the-week bench remove",
309
+ "challenge-of-the-week clear",
310
+ "challenge-of-the-week list",
311
+ "challenge-of-the-week note",
312
+ "challenge-of-the-week queue",
313
+ "challenge-of-the-week show",
314
+ "challenge-of-the-week swap",
305
315
  "students mastery",
306
316
  "apps link",
307
317
  "apps links",
@@ -383,6 +393,11 @@ const STAFF_COMMANDS = new Set([
383
393
  "payout items edit",
384
394
  "payout payruns list",
385
395
  "payout recipients list",
396
+ "placement give",
397
+ "placement questions",
398
+ "placement results",
399
+ "placement show",
400
+ "placement sync-mastery",
386
401
  "registrations approve",
387
402
  "registrations deny",
388
403
  "school codes get",
@@ -403,6 +418,7 @@ const STAFF_COMMANDS = new Set([
403
418
  "store-items list",
404
419
  "students upload-map-scores",
405
420
  "students issue-email",
421
+ "students goblins",
406
422
  "students web-todos",
407
423
  "students flashcards",
408
424
  "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
@@ -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,16 @@ 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] challenge-of-the-week list [--past N] [--ahead N]
637
+ recess [--json] challenge-of-the-week show <week>
638
+ recess [--json] challenge-of-the-week queue <template> --week <week> [--note TEXT] [--confirm]
639
+ recess [--json] challenge-of-the-week swap <template> --week <week> [--note TEXT] [--confirm]
640
+ recess [--json] challenge-of-the-week note --week <week> (--note TEXT | --clear) [--confirm]
641
+ recess [--json] challenge-of-the-week clear --week <week> [--confirm]
642
+ recess [--json] challenge-of-the-week bench list
643
+ recess [--json] challenge-of-the-week bench add <template> [--position N] [--confirm]
644
+ recess [--json] challenge-of-the-week bench move <template> --position N [--confirm]
645
+ recess [--json] challenge-of-the-week bench remove <template> [--confirm]
630
646
  recess [--json] goals notes list --student <goal-owner-id> --goal <goal-id>
631
647
  recess [--json] goals notes get --student <goal-owner-id> --goal <goal-id>
632
648
  [--lesson <item-key|module-ref>]
@@ -775,6 +791,14 @@ them. --focus is that adult's own instructions for the daily summary (what to
775
791
  cover and how). A recipient with no phone number receives nothing, so check
776
792
  "users phone get" too.
777
793
 
794
+ "students goblins" rosters a kid into Goblins (issuing their Recess email first)
795
+ in one class per course: --course usa-3rd..usa-8th, usa-algebra-1, usa-geometry,
796
+ usa-algebra-2 or pre-calculus; without it the kid's profile grade picks one. A
797
+ new kid takes a Goblins seat and keeps it. status eligible means a todo whose
798
+ url is https://app.goblins.com/?skill=<topic> signs them straight into problems
799
+ on that topic; unlicensed means no seat is free yet (rerun later). Never paste a
800
+ /handoff/ link into a todo: it works once and expires.
801
+
778
802
  Onboarding notes: "status" and "intake-session" are reads — "intake-session"
779
803
  looks up the current IN_PROGRESS session without creating one (prints a "none
780
804
  yet" result when absent). "intake-session-create" is the explicit write that
@@ -1017,6 +1041,13 @@ server when the served bundle's minCliVersion allows — an older binary keeps t
1017
1041
  bundled copy, and an unreachable server is not an error. "doctor" reports whether
1018
1042
  a newer skill exists and names the command; it never writes.
1019
1043
 
1044
+ "challenge-of-the-week" runs the weekly pick every kid sees (ADMIN and GUIDE). <week> is
1045
+ this, next, last, or a Monday YYYY-MM-DD (weeks run Monday to Sunday, Pacific). <template> is a
1046
+ goal template id or slug; only kid-visible (PUBLIC, library-listed), joinable challenges can be
1047
+ picked or benched. Empty weeks fill from the bench once the first queued week has started (the
1048
+ top of the bench at Monday 00:00 PT). This week can be swapped, never cleared; past weeks cannot
1049
+ change. --note is at most 80 characters.
1050
+
1020
1051
  Writes preview and exit 2 until confirmed after explicit human approval. Every
1021
1052
  preview includes an operationKey. Simplest confirm: "recess confirm <operation-key>"
1022
1053
  replays the stored preview. Equivalently, rerun the same command with --confirm
@@ -1103,6 +1134,7 @@ export const COMMAND_SUMMARIES = {
1103
1134
  "students texts set-guardian": "Change one adult's SMS frequency, focus, or on/off.",
1104
1135
  "students upload-map-scores": "Upload a NWEA MAP score report PDF for a kid.",
1105
1136
  "students issue-email": "Issue a Recess email address for a kid.",
1137
+ "students goblins": "Roster a kid into Goblins so their Goblins todos sign them straight in.",
1106
1138
  "students web-todos": "Show or set whether a kid's todos run on web (off: they open in the desktop app).",
1107
1139
  "students flashcards": "Show or set whether a kid gets a daily flashcard review todo.",
1108
1140
  "students interests": "List, add, or remove a kid's interests (Rocky, the feed, and reading/writing passages use them).",
@@ -1244,6 +1276,11 @@ export const COMMAND_SUMMARIES = {
1244
1276
  "channels members remove": "Remove members from a channel (soft).",
1245
1277
  "tuition-plans generate": "Compute a tuition plan sheet (web URL, optional PDF); stores nothing.",
1246
1278
  "tuition-plans states": "List states supported by tuition plans.",
1279
+ "placement give": "Give a kid the math or reading placement quest as a todo.",
1280
+ "placement show": "One kid's placement answers, mistakes, timing and sounds check.",
1281
+ "placement results": "Kids' placement quest results beside their latest MAP score.",
1282
+ "placement questions": "The placement quest question bank with answers and misconceptions.",
1283
+ "placement sync-mastery": "Record a finished placement's answers in the kid's mastery graphs.",
1247
1284
  "cohorts get": "Read a cohort and its events.",
1248
1285
  "cohorts schedule get": "Read a cohort's recurring schedule.",
1249
1286
  "cohorts schedule set": "Change a cohort's recurring schedule from a date.",
@@ -1444,6 +1481,16 @@ export const COMMAND_SUMMARIES = {
1444
1481
  "library-books list": "List books in the shared library.",
1445
1482
  "library-books get": "Read one library book: status, pages, chapters.",
1446
1483
  "library-books add": "Add a web search result to the book library.",
1484
+ "challenge-of-the-week list": "List Challenge of the Week picks: past, this week, upcoming, and the bench.",
1485
+ "challenge-of-the-week show": "Read one week's Challenge of the Week pick and note.",
1486
+ "challenge-of-the-week queue": "Queue a challenge for an empty week, with an optional note for kids.",
1487
+ "challenge-of-the-week swap": "Replace a week's Challenge of the Week pick.",
1488
+ "challenge-of-the-week note": "Set or clear the note kids see under a week's pick.",
1489
+ "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.",
1490
+ "challenge-of-the-week bench list": "List the bench that fills empty weeks, top first.",
1491
+ "challenge-of-the-week bench add": "Add a challenge to the bench.",
1492
+ "challenge-of-the-week bench move": "Move a bench challenge to a position.",
1493
+ "challenge-of-the-week bench remove": "Take a challenge off the bench.",
1447
1494
  "goals notes list": "List Rocky's per-kid notes on a goal.",
1448
1495
  "goals notes get": "Read the goal's or one lesson's note.",
1449
1496
  "goals notes set": "Write Rocky's note for this kid on a lesson (never the lesson itself).",
@@ -1483,6 +1530,7 @@ export const NOUN_SUMMARIES = {
1483
1530
  kid: "One of your kids: today, goals, profile, texts, logins, pods.",
1484
1531
  channels: "Community channels and their members.",
1485
1532
  "tuition-plans": "Compute tuition plan sheets (stores nothing).",
1533
+ placement: "Give placement quests, one kid's results, results vs MAP, question bank, mastery sync.",
1486
1534
  feed: "Post messages to users' feeds.",
1487
1535
  dms: "Send Recess chat DMs as yourself.",
1488
1536
  events: "Class events: list, attendance, cancel, reschedule, add.",
@@ -1502,6 +1550,7 @@ export const NOUN_SUMMARIES = {
1502
1550
  rocky: "A kid's Rocky personality settings; free Rocky grants and budgets.",
1503
1551
  "tutor-templates": "Tutor templates and their assignment to kids.",
1504
1552
  "library-books": "Book library: search the web, add books, read status.",
1553
+ "challenge-of-the-week": "Challenge of the Week: queue weekly picks and the bench (ADMIN, GUIDE).",
1505
1554
  mastery: "Mastery graphs and the content linked to them.",
1506
1555
  };
1507
1556
  //# 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.26.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {