recess-cli 3.19.3 → 3.20.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/README.md CHANGED
@@ -200,7 +200,7 @@ shows `capabilitiesLockedNow`/`capabilitiesLockedAfter`, the resolved class allo
200
200
  `slotsUsed`, and whether the change would strand registrations. Stranding is refused unless the
201
201
  human explicitly approves the exceptional `--allow-strand` override.
202
202
 
203
- MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing tutor-dashboard extraction route.
203
+ MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing `POST /tutor/students/{studentId}/map-test-scores/upload` extraction route.
204
204
 
205
205
  ## Store catalog and Village
206
206
 
package/dist/args.js CHANGED
@@ -60,6 +60,7 @@ export const BOOLEAN_FLAGS = new Set([
60
60
  "include-archived",
61
61
  "include-deleted",
62
62
  "include-left",
63
+ "include-weekends",
63
64
  "json",
64
65
  "keep-tokens",
65
66
  "mirrored",
package/dist/cli.js CHANGED
@@ -17,6 +17,7 @@ import { runDbCommand } from "./commands/db.js";
17
17
  import { runRoomsCommand } from "./commands/rooms.js";
18
18
  import { runFeedCommand } from "./commands/feed.js";
19
19
  import { runFamiliesCommand } from "./commands/families.js";
20
+ import { runFamilyCommand, runKidCommand } from "./commands/family.js";
20
21
  import { runStudentsTextsCommand, runUsersPhoneCommand, } from "./commands/phone-and-texts.js";
21
22
  import { hasCommunityHour, runUsersCommunityHourCommand, } from "./commands/community-hour.js";
22
23
  import { runTuitionPlansCommand } from "./commands/tuition-plans.js";
@@ -50,6 +51,8 @@ const CONFIRMATION_FLAGS = new Set([
50
51
  ]);
51
52
  /** A stale approval is not an approval; preview again after this. */
52
53
  const CONFIRM_REPLAY_TTL_MS = 24 * 60 * 60 * 1000;
54
+ // Guardian skills the hosted (remote) CLI may fetch; recess-api.ts mirrors this allowlist.
55
+ const HOSTED_SKILLS = ["recess-challenge-design", "recess-goal-authoring"];
53
56
  function replayableArgv(argv) {
54
57
  const kept = [];
55
58
  for (let index = 0; index < argv.length; index += 1) {
@@ -193,6 +196,7 @@ async function sessionStatus(config) {
193
196
  }
194
197
  const DISCOVERY_ROLE_BY_SCOPE = {
195
198
  full_admin: "ADMIN",
199
+ family: "GUARDIAN",
196
200
  family_ai: "GUARDIAN",
197
201
  guide_students: "GUIDE",
198
202
  village_home: "KID",
@@ -2138,6 +2142,13 @@ async function readAssignmentSelection(filePath) {
2138
2142
  },
2139
2143
  };
2140
2144
  }
2145
+ /** Hosted goal-template authoring and skills are guide/admin only (see below). */
2146
+ const HOSTED_STAFF_NOUNS = new Set(["goal-templates", "skills"]);
2147
+ /** The hosted catalog, minus nouns the hosted gate would refuse this role. */
2148
+ function hostedCommands(commands, discovery) {
2149
+ const staff = discovery.role === "GUIDE" || discovery.role === "ADMIN";
2150
+ return remoteCommands(commands).filter((command) => staff || !HOSTED_STAFF_NOUNS.has(command.path[0]));
2151
+ }
2141
2152
  export async function executeRecessCommand(argv, options = {}) {
2142
2153
  const parsed = parseArgs(argv);
2143
2154
  const [noun, verb] = parsed.positionals;
@@ -2193,7 +2204,9 @@ export async function executeRecessCommand(argv, options = {}) {
2193
2204
  }
2194
2205
  const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
2195
2206
  const discovery = options.discovery ?? resolveCommandDiscovery(config);
2196
- const visibleCommands = isRemote ? remoteCommands(commands) : commands;
2207
+ const visibleCommands = isRemote
2208
+ ? hostedCommands(commands, discovery)
2209
+ : commands;
2197
2210
  return {
2198
2211
  help: scopedHelp(HELP, visibleCommands, [], discovery, {
2199
2212
  remoteOnly: isRemote,
@@ -2205,7 +2218,9 @@ export async function executeRecessCommand(argv, options = {}) {
2205
2218
  const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
2206
2219
  const config = options.config ?? (await resolveConfig(flagString(parsed, "profile")));
2207
2220
  const discovery = options.discovery ?? resolveCommandDiscovery(config);
2208
- const visibleCommands = isRemote ? remoteCommands(commands) : commands;
2221
+ const visibleCommands = isRemote
2222
+ ? hostedCommands(commands, discovery)
2223
+ : commands;
2209
2224
  return {
2210
2225
  help: scopedHelp(HELP, visibleCommands, scope, discovery, {
2211
2226
  remoteOnly: isRemote,
@@ -2227,14 +2242,14 @@ export async function executeRecessCommand(argv, options = {}) {
2227
2242
  ].includes(command.path.join(" "))) {
2228
2243
  throw new CliError("invalid_arguments", "Structured input is accepted only by hosted apps validate and goal-templates validate-spec/create.");
2229
2244
  }
2230
- if ((noun === "goal-templates" || noun === "skills") &&
2245
+ if (HOSTED_STAFF_NOUNS.has(noun) &&
2231
2246
  options.session?.user.role !== "GUIDE" &&
2232
2247
  options.session?.user.role !== "ADMIN") {
2233
2248
  throw new CliError("forbidden", "Hosted goal-template authoring requires a guide or admin.");
2234
2249
  }
2235
2250
  if (noun === "skills" &&
2236
- parsed.positionals[3] !== "recess-goal-authoring") {
2237
- throw new CliError("remote_command_unavailable", "Hosted skills only exposes recess-goal-authoring.");
2251
+ !HOSTED_SKILLS.includes(parsed.positionals[3] ?? "")) {
2252
+ throw new CliError("remote_command_unavailable", `Hosted skills only exposes ${HOSTED_SKILLS.join(" and ")}.`);
2238
2253
  }
2239
2254
  const granted = options.grantedScopes ?? new Set();
2240
2255
  const missing = command.oauthScopes.filter((scope) => !granted.has(scope));
@@ -2250,7 +2265,7 @@ export async function executeRecessCommand(argv, options = {}) {
2250
2265
  options.config ?? resolveConfig(flagString(parsed, "profile")),
2251
2266
  ]);
2252
2267
  const discovery = options.discovery ?? resolveCommandDiscovery(config);
2253
- return agentContext(commands, {
2268
+ return agentContext(isRemote ? hostedCommands(commands, discovery) : commands, {
2254
2269
  cliVersion: options.versions?.cliVersion ??
2255
2270
  (isRemote ? "hosted" : await readCliVersion()),
2256
2271
  availableProfiles: profiles.profiles.map((profile) => profile.name),
@@ -5991,6 +6006,12 @@ export async function executeRecessCommand(argv, options = {}) {
5991
6006
  if (noun === "families") {
5992
6007
  return runFamiliesCommand({ parsed, api, writeCommand });
5993
6008
  }
6009
+ if (noun === "family") {
6010
+ return runFamilyCommand({ parsed, api, writeCommand });
6011
+ }
6012
+ if (noun === "kid") {
6013
+ return runKidCommand({ parsed, api, writeCommand });
6014
+ }
5994
6015
  if (noun === "chat-logs") {
5995
6016
  return runChatLogsCommand({ parsed, api, writeCommand });
5996
6017
  }
@@ -6165,7 +6186,38 @@ export async function executeRecessCommand(argv, options = {}) {
6165
6186
  return { studentId, webTodosEnabled: on };
6166
6187
  });
6167
6188
  }
6168
- throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|upload-map-scores|issue-email|web-todos.");
6189
+ if (verb === "flashcards") {
6190
+ const studentId = flagString(parsed, "student", { required: true });
6191
+ const on = hasFlag(parsed, "on");
6192
+ const off = hasFlag(parsed, "off");
6193
+ if (on && off) {
6194
+ throw new CliError("invalid_arguments", "Pass --on or --off, not both.");
6195
+ }
6196
+ if (!on && !off) {
6197
+ const profile = unwrap(await api.client.GET("/tutor/students/{studentId}/profile", {
6198
+ params: { path: { studentId } },
6199
+ }));
6200
+ return {
6201
+ studentId,
6202
+ flashcardReviewEnabled: profile.flashcardReviewEnabled,
6203
+ dailyReviewCap: profile.dailyReviewCap,
6204
+ };
6205
+ }
6206
+ return writeCommand(parsed, {
6207
+ action: on
6208
+ ? "turn a kid's daily flashcard review back on"
6209
+ : "stop giving a kid a daily flashcard review todo",
6210
+ target: { studentUserId: studentId },
6211
+ request: { flashcardReviewEnabled: on },
6212
+ }, async () => {
6213
+ unwrap(await api.client.PATCH("/tutor/students/{studentId}/profile", {
6214
+ params: { path: { studentId } },
6215
+ body: { flashcardReviewEnabled: on },
6216
+ }));
6217
+ return { studentId, flashcardReviewEnabled: on };
6218
+ });
6219
+ }
6220
+ throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|upload-map-scores|issue-email|web-todos|flashcards.");
6169
6221
  }
6170
6222
  if (noun === "todos") {
6171
6223
  if (verb === "create") {
@@ -22,7 +22,62 @@ export const RECESS_MCP_SCOPES = {
22
22
  appsWrite: "recess:apps:write",
23
23
  studentContextRead: "recess:students:read",
24
24
  todoAssign: "recess:todos:assign",
25
+ familyRead: "recess:family:read",
26
+ familyWrite: "recess:family:write",
25
27
  };
28
+ /** Parent-dashboard reads/writes parent Rocky runs in-process over hosted transport. */
29
+ const FAMILY_REMOTE_READS = [
30
+ "family account",
31
+ "family guardians",
32
+ "family kids",
33
+ "family schedule",
34
+ "family school-class-options",
35
+ "family school-classes",
36
+ "family today",
37
+ "family tutor",
38
+ "kid classes",
39
+ "kid cowork",
40
+ "kid feed-lock",
41
+ "kid friends",
42
+ "kid goal-note",
43
+ "kid goals",
44
+ "kid logins",
45
+ "kid map-scores",
46
+ "kid profile",
47
+ "kid reveal-login",
48
+ "kid texts",
49
+ "kid today",
50
+ "kid todo",
51
+ "kid xp",
52
+ ];
53
+ const FAMILY_REMOTE_WRITES = [
54
+ "family drop-class",
55
+ "family register-class",
56
+ "family restore-class",
57
+ "family set-name",
58
+ "family set-notifications",
59
+ "family set-phone",
60
+ "family set-timezone",
61
+ "family swap-class",
62
+ "kid add-login",
63
+ "kid add-todo",
64
+ "kid edit-login",
65
+ "kid end-session",
66
+ "kid excuse",
67
+ "kid friend-parent",
68
+ "kid goal-schedule",
69
+ "kid move-todo",
70
+ "kid pair-device",
71
+ "kid pause-goal",
72
+ "kid remove-login",
73
+ "kid resume-goal",
74
+ "kid set-feed-lock",
75
+ "kid set-goal-note",
76
+ "kid set-profile",
77
+ "kid set-rooms",
78
+ "kid set-texts",
79
+ "kid switch-cowork",
80
+ ];
26
81
  const REMOTE_COMMAND_SCOPES = new Map([
27
82
  ["goal-templates list", [RECESS_MCP_SCOPES.templatesRead]],
28
83
  ["goal-templates get", [RECESS_MCP_SCOPES.templatesRead]],
@@ -50,6 +105,14 @@ const REMOTE_COMMAND_SCOPES = new Map([
50
105
  ["students list", [RECESS_MCP_SCOPES.studentContextRead]],
51
106
  ["students todos", [RECESS_MCP_SCOPES.studentContextRead]],
52
107
  ["students analysis", [RECESS_MCP_SCOPES.studentContextRead]],
108
+ ...FAMILY_REMOTE_READS.map((path) => [
109
+ path,
110
+ [RECESS_MCP_SCOPES.familyRead],
111
+ ]),
112
+ ...FAMILY_REMOTE_WRITES.map((path) => [
113
+ path,
114
+ [RECESS_MCP_SCOPES.familyRead, RECESS_MCP_SCOPES.familyWrite],
115
+ ]),
53
116
  ]);
54
117
  const REMOTE_USAGE = new Map([
55
118
  ["goal-templates validate-spec", "recess goal-templates validate-spec"],
@@ -78,6 +141,7 @@ const REMOTE_CONFIRMATION_COMMANDS = new Set([
78
141
  "apps validate",
79
142
  "apps publish",
80
143
  "apps assign",
144
+ ...FAMILY_REMOTE_WRITES,
81
145
  ]);
82
146
  const LOCAL_COMMAND_NOUNS = new Set([
83
147
  "--version",
@@ -99,6 +163,67 @@ const AUTHENTICATED_COMMAND_PREFIXES = [
99
163
  "village objects",
100
164
  "village render",
101
165
  ];
166
+ /**
167
+ * Every guardian's `family` session: the parent dashboard's own settings and
168
+ * per-kid views, plus loading guardian skills. `family_ai` is a superset.
169
+ */
170
+ const FAMILY_COMMANDS = new Set([
171
+ "family account",
172
+ "family drop-class",
173
+ "family guardians",
174
+ "family kids",
175
+ "family register-class",
176
+ "family restore-class",
177
+ "family schedule",
178
+ "family school-class-options",
179
+ "family school-classes",
180
+ "family set-name",
181
+ "family set-notifications",
182
+ "family set-phone",
183
+ "family set-timezone",
184
+ "family swap-class",
185
+ "family today",
186
+ "family tutor",
187
+ "kid add-login",
188
+ "kid add-todo",
189
+ "kid classes",
190
+ "kid cowork",
191
+ "kid edit-login",
192
+ "kid end-session",
193
+ "kid excuse",
194
+ "kid feed-lock",
195
+ "kid friend-parent",
196
+ "kid friends",
197
+ "kid goal-note",
198
+ "kid goal-schedule",
199
+ "kid goals",
200
+ "kid logins",
201
+ "kid map-scores",
202
+ "kid move-todo",
203
+ "kid pair-device",
204
+ "kid pause-goal",
205
+ "kid profile",
206
+ "kid remove-login",
207
+ "kid resume-goal",
208
+ "kid reveal-login",
209
+ "kid set-feed-lock",
210
+ "kid set-goal-note",
211
+ "kid set-profile",
212
+ "kid set-rooms",
213
+ "kid set-texts",
214
+ "kid switch-cowork",
215
+ "kid texts",
216
+ "kid today",
217
+ "kid todo",
218
+ "kid xp",
219
+ "skills guardian get",
220
+ "skills guardian list",
221
+ ]);
222
+ /** Family-tier commands a guide also needs (`recess-guide` loads through these). */
223
+ const GUIDE_FAMILY_COMMANDS = new Set([
224
+ "skills guardian get",
225
+ "skills guardian list",
226
+ ]);
102
227
  const FAMILY_AI_COMMANDS = new Set([
103
228
  "apps assign",
104
229
  "apps list",
@@ -164,8 +289,6 @@ const FAMILY_AI_COMMANDS = new Set([
164
289
  "request get",
165
290
  "rocky get",
166
291
  "rocky set",
167
- "skills guardian get",
168
- "skills guardian list",
169
292
  "students list",
170
293
  "students math-academy",
171
294
  "students schedule",
@@ -277,6 +400,7 @@ const STAFF_COMMANDS = new Set([
277
400
  "students upload-map-scores",
278
401
  "students issue-email",
279
402
  "students web-todos",
403
+ "students flashcards",
280
404
  "students notes add",
281
405
  "students interests",
282
406
  "students todos",
@@ -306,6 +430,8 @@ function commandAccess(path) {
306
430
  if (AUTHENTICATED_COMMAND_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix} `))) {
307
431
  return "authenticated";
308
432
  }
433
+ if (FAMILY_COMMANDS.has(key))
434
+ return "family";
309
435
  if (FAMILY_AI_COMMANDS.has(key))
310
436
  return "family_ai";
311
437
  if (STAFF_COMMANDS.has(key))
@@ -319,8 +445,17 @@ export function commandIsAvailable(command, scope) {
319
445
  return false;
320
446
  if (command.access === "authenticated")
321
447
  return true;
322
- if (command.access === "family_ai")
323
- return scope !== "village_home";
448
+ if (command.access === "family") {
449
+ if (scope === "guide_students") {
450
+ return GUIDE_FAMILY_COMMANDS.has(command.path.join(" "));
451
+ }
452
+ return (scope === "family" || scope === "family_ai" || scope === "full_admin");
453
+ }
454
+ if (command.access === "family_ai") {
455
+ return (scope === "family_ai" ||
456
+ scope === "guide_students" ||
457
+ scope === "full_admin");
458
+ }
324
459
  if (command.access === "staff") {
325
460
  return scope === "guide_students" || scope === "full_admin";
326
461
  }
@@ -475,25 +610,62 @@ export function findCommandSchema(commands, positionals) {
475
610
  }
476
611
  function remoteUsage(command) {
477
612
  const path = command.path.join(" ");
478
- const usage = (REMOTE_USAGE.get(path) ?? command.usage)
613
+ const custom = REMOTE_USAGE.get(path);
614
+ let usage = (custom ?? command.usage)
479
615
  .replace(/^recess\s+(?:\[--json\]\s+)?/, "")
480
616
  .replace(" (input.appBundle)", "");
617
+ // Hosted writes confirm with the preview's operation key.
618
+ if (!custom && REMOTE_CONFIRMATION_COMMANDS.has(path)) {
619
+ usage = usage.replace("[--confirm]", "[--confirm --operation-key <key>]");
620
+ }
481
621
  if (path === "help" || path === "agent-context")
482
622
  return usage;
483
623
  return `${usage} --reason TEXT`;
484
624
  }
625
+ /** Hosted help notes; a `noun` note shows only when that noun is in the caller's catalog. */
485
626
  const REMOTE_HELP_NOTES = [
486
- "Send one command string; omit recess and --json. Quote values containing spaces.",
487
- "Every command except help and agent-context requires --reason TEXT (1–1024 characters).",
488
- "For writes, provide the reason in the preview; confirm using only the command, --confirm, and --operation-key.",
489
- "Supply app source as input.appBundle when calling apps validate.",
490
- "Guides and admins can create reusable goal templates. First load skills guardian get recess-goal-authoring --all-references; use input.template (the complete template document) for goal-templates validate-spec and create, without --file. Preview the full template, then confirm with only goal-templates create --confirm --operation-key <key>.",
491
- 'Example: students todos --student "Student Name" --date today --reason "Show today\'s todos at the user\'s request"',
492
- "Student names must match exactly (ignoring case and extra spaces) within your roster; use an ID to disambiguate.",
493
- "--date today uses the student's timezone; an explicit YYYY-MM-DD selects that calendar date. Omit --date for recent todos.",
494
- "Results include the resolved date/timezone and pagination. If hasMore, repeat with --cursor nextCursor and the same filters; use the resolved date when paging today.",
495
- "Report recorded todo statuses only. These results do not establish account creation, complete activity history, or whether work happened outside Recess.",
627
+ {
628
+ text: "Send one command string; omit recess and --json. Quote values containing spaces.",
629
+ },
630
+ {
631
+ text: "Every command except help and agent-context requires --reason TEXT (1–1024 characters).",
632
+ },
633
+ {
634
+ text: "For writes, provide the reason in the preview; confirm using only the command, --confirm, and --operation-key.",
635
+ },
636
+ {
637
+ text: "Supply app source as input.appBundle when calling apps validate.",
638
+ noun: "apps",
639
+ },
640
+ {
641
+ text: "Guides and admins can create reusable goal templates. First load skills guardian get recess-goal-authoring --all-references; use input.template (the complete template document) for goal-templates validate-spec and create, without --file. Preview the full template, then confirm with only goal-templates create --confirm --operation-key <key>.",
642
+ noun: "goal-templates",
643
+ },
644
+ {
645
+ text: 'Example: students todos --student "Student Name" --date today --reason "Show today\'s todos at the user\'s request"',
646
+ noun: "students",
647
+ },
648
+ {
649
+ text: "Student names must match exactly (ignoring case and extra spaces) within your roster; use an ID to disambiguate.",
650
+ noun: "students",
651
+ },
652
+ {
653
+ text: "--date today uses the student's timezone; an explicit YYYY-MM-DD selects that calendar date. Omit --date for recent todos.",
654
+ noun: "students",
655
+ },
656
+ {
657
+ text: "Results include the resolved date/timezone and pagination. If hasMore, repeat with --cursor nextCursor and the same filters; use the resolved date when paging today.",
658
+ noun: "students",
659
+ },
660
+ {
661
+ text: "Report recorded todo statuses only. These results do not establish account creation, complete activity history, or whether work happened outside Recess.",
662
+ noun: "students",
663
+ },
496
664
  ];
665
+ function remoteHelpNotes(visible) {
666
+ const nouns = new Set(visible.map((command) => command.path[0]));
667
+ return REMOTE_HELP_NOTES.filter((note) => !note.noun || nouns.has(note.noun)).map((note) => note.text);
668
+ }
497
669
  /**
498
670
  * Usage notes by noun, parsed from the prose after HELP's usage block.
499
671
  * A "<Label> notes:" paragraph attaches to NOTE_LABEL_NOUNS[label]; an
@@ -508,6 +680,8 @@ const NOTE_LABEL_NOUNS = {
508
680
  "Class-ops": ["events"],
509
681
  Channel: ["channels"],
510
682
  "Family address": ["families"],
683
+ "Family dashboard": ["family"],
684
+ "Kid dashboard": ["kid"],
511
685
  "Tuition-plan": ["tuition-plans"],
512
686
  Payout: ["payout"],
513
687
  Auth: ["auth"],
@@ -545,13 +719,15 @@ function unwrapParagraph(text) {
545
719
  const ACCESS_RANK = {
546
720
  local: 0,
547
721
  authenticated: 1,
548
- family_ai: 2,
549
- staff: 3,
550
- admin: 4,
722
+ family: 2,
723
+ family_ai: 3,
724
+ staff: 4,
725
+ admin: 5,
551
726
  };
552
727
  const ACCESS_NEEDS = {
553
728
  local: "no session",
554
729
  authenticated: "any signed-in session",
730
+ family: "a family session (any guardian), a family_ai session, or an admin",
555
731
  family_ai: "a family_ai session (a guardian with access:ai), a guide, or an admin",
556
732
  staff: "a staff session (guide or admin)",
557
733
  admin: "an admin session (full_admin)",
@@ -736,7 +912,10 @@ export function scopedHelp(help, commands, scope, context, options = {}) {
736
912
  ? ["", "Notes:", ...nounNotes.flatMap((text) => [text, ""])]
737
913
  : []),
738
914
  ...(options.remoteOnly
739
- ? ["", ...REMOTE_HELP_NOTES]
915
+ ? [
916
+ "",
917
+ ...remoteHelpNotes(commands.filter((command) => commandIsAvailable(command, context.scope))),
918
+ ]
740
919
  : scope.length === 0 && !compactRoot
741
920
  ? ["", ...notes.global.flatMap((text) => [text, ""])]
742
921
  : []),
@@ -913,7 +1092,7 @@ export function agentContext(commands, options) {
913
1092
  : "Compact catalog. `recess agent-context <noun>` adds usage and notes for one noun; `--full` returns every flag schema; `recess help <noun>` is the human view.",
914
1093
  }),
915
1094
  ...(remote
916
- ? { instructions: REMOTE_HELP_NOTES }
1095
+ ? { instructions: remoteHelpNotes(visible) }
917
1096
  : {
918
1097
  conventions: [
919
1098
  "--reason TEXT (1–1024 characters, audit-logged) is required on write: true commands; reads default it to `Read: <command>`.",