recess-cli 3.19.3 → 3.21.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
@@ -26,6 +26,7 @@ export const BOOLEAN_FLAGS = new Set([
26
26
  "custom-only",
27
27
  "no-agreement",
28
28
  "paywall-offline",
29
+ "override-aid-price",
29
30
  "no-email",
30
31
  "no-paywall",
31
32
  "no-text",
@@ -60,6 +61,7 @@ export const BOOLEAN_FLAGS = new Set([
60
61
  "include-archived",
61
62
  "include-deleted",
62
63
  "include-left",
64
+ "include-weekends",
63
65
  "json",
64
66
  "keep-tokens",
65
67
  "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>`.",
@@ -70,6 +70,22 @@ function renderAnswers(responses, questions) {
70
70
  }
71
71
  return lines;
72
72
  }
73
+ /** Which aid application the new packet carries and where its price came from. */
74
+ function aidLines(aid, priceSource) {
75
+ const how = {
76
+ explicit: "named with --financial-aid",
77
+ application: "the application's own aid form",
78
+ email: "matched by the parent's email",
79
+ };
80
+ return [
81
+ aid
82
+ ? `Financial aid: application ${aid.id} (${how[aid.matchedBy]}), ${aid.reviewed ? `reviewed${aid.determinedAnnualTuition !== null ? `, $${aid.determinedAnnualTuition.toLocaleString("en-US")}/yr after aid` : ""}` : "not reviewed yet"}.`
83
+ : "Financial aid: none attached.",
84
+ ...(priceSource === "aid_review"
85
+ ? ["Annual price taken from the aid review (no --annual given)."]
86
+ : []),
87
+ ];
88
+ }
73
89
  function renderPacket(packet, admissionUrl, questions = []) {
74
90
  const when = (iso) => (iso ? iso.slice(0, 10) : "–");
75
91
  const out = [
@@ -78,7 +94,7 @@ function renderPacket(packet, admissionUrl, questions = []) {
78
94
  `${packet.enrollmentType === "PARTNER_SCHOOL" ? `Through ${packet.partnerSchool?.name ?? "partner school"}` : packet.enrollmentType === "PROGRAM" ? "Online learning program" : "Direct enrollment"} · ${packet.institution.name} · tier ${packet.tierId}${packet.paywallOutOfBand ? ` · out-of-band paywall${packet.paywallCents ? ` ${dollars(packet.paywallCents)}` : " (the signed plan's first invoice)"}` : packet.paywallCents ? ` · paywall ${dollars(packet.paywallCents)}` : " · no paywall"}`,
79
95
  `Status: ${packet.status} (${STEP_LABELS[packet.step]})${packet.noAgreement ? " · no tuition agreement" : ""}`,
80
96
  packet.financialAidApplication
81
- ? `Financial aid answers in the envelope: application ${packet.financialAidApplication.id} (${packet.financialAidApplication.createdAt.slice(0, 10)})`
97
+ ? `Financial aid answers in the envelope: application ${packet.financialAidApplication.id} (${packet.financialAidApplication.createdAt.slice(0, 10)})${packet.financialAidApplication.determinedAnnualTuition !== null && packet.kids.length > 1 ? ` · reviewed at $${packet.financialAidApplication.determinedAnnualTuition.toLocaleString("en-US")}/yr for the family (the plan's annual is per child)` : packet.financialAidApplication.determinedAnnualTuition !== null ? ` · reviewed at $${packet.financialAidApplication.determinedAnnualTuition.toLocaleString("en-US")}/yr after aid${Number(packet.planSpec.annualTuition) === packet.financialAidApplication.determinedAnnualTuition || packet.noAgreement ? "" : ` (plan uses $${Number(packet.planSpec.annualTuition).toLocaleString("en-US")}${packet.financialAidApplication.reviewedAt && packet.financialAidApplication.reviewedAt > packet.planSetAt && !packet.paidAt ? ": the review changed since, requote to match" : ""})`}` : " · not reviewed"}`
82
98
  : "No financial aid application attached (nothing to initial).",
83
99
  "",
84
100
  renderColumns([
@@ -275,7 +291,10 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
275
291
  (flagString(parsed, "start") || flagString(parsed, "annual"))) {
276
292
  throw new CliError("invalid_arguments", "--no-agreement takes no tuition plan; drop --start/--annual and the other plan flags.");
277
293
  }
278
- const plan = noAgreement ? null : parseTuitionPlanSpecFlags(parsed);
294
+ // No --annual: the server prices the plan from the aid review.
295
+ const plan = noAgreement
296
+ ? null
297
+ : parseTuitionPlanSpecFlags(parsed, { annualOptional: true });
279
298
  const offline = hasFlag(parsed, "paywall-offline");
280
299
  if (noAgreement && offline) {
281
300
  throw new CliError("invalid_arguments", "--paywall-offline bills the signed plan's first invoice, so it needs an agreement. Use --paywall DOLLARS instead.");
@@ -301,6 +320,9 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
301
320
  ...(flagString(parsed, "financial-aid")
302
321
  ? { financialAidApplicationId: flagString(parsed, "financial-aid") }
303
322
  : {}),
323
+ ...(hasFlag(parsed, "override-aid-price")
324
+ ? { overrideAidPrice: true }
325
+ : {}),
304
326
  institutionSlug: flagString(parsed, "school", { required: true }),
305
327
  enrollment,
306
328
  ...(partnerSchool ? { partnerSchool } : {}),
@@ -326,7 +348,7 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
326
348
  sendEmail: !hasFlag(parsed, "no-email"),
327
349
  };
328
350
  return writeCommand(parsed, {
329
- action: `create an admission packet${noAgreement ? " without a tuition agreement" : ""} for ${body.parentEmail} (${kids.map((k) => k.firstName).join(", ")}) and ${body.sendEmail ? "email them the link" : "return the link without emailing"}`,
351
+ action: `create an admission packet${noAgreement ? " without a tuition agreement" : plan && plan.annualTuition === undefined ? " priced from the reviewed financial aid application" : ""} for ${body.parentEmail} (${kids.map((k) => k.firstName).join(", ")}) and ${body.sendEmail ? "email them the link" : "return the link without emailing"}`,
330
352
  target: { parentEmail: body.parentEmail, school: body.institutionSlug },
331
353
  request: body,
332
354
  ...(warnings.length ? { details: { warnings } } : {}),
@@ -347,10 +369,16 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
347
369
  "No tuition agreement: the parent goes from the account to consent.",
348
370
  ]),
349
371
  "",
372
+ ...aidLines(result.financialAid, result.priceSource),
350
373
  result.emailed
351
374
  ? `Emailed ${result.packet.parentEmail}.`
352
375
  : "Not emailed (--no-email); send the link yourself.",
353
376
  ...warnings.map((w) => `Warning: ${w}`),
377
+ ...(result.financialAid?.matchedBy === "email"
378
+ ? [
379
+ `Warning: the aid application was matched by email only (no aid form on the application). If it is the wrong one, void this packet and recreate it with --financial-aid <id> or --financial-aid none.`,
380
+ ]
381
+ : []),
354
382
  ].join("\n"),
355
383
  };
356
384
  });
@@ -413,7 +441,10 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
413
441
  if (keepPlan && dropAgreement) {
414
442
  throw new CliError("invalid_arguments", "Use --keep-plan, --no-agreement or new plan flags, not a mix.");
415
443
  }
416
- const plan = keepPlan || dropAgreement ? null : parseTuitionPlanSpecFlags(parsed);
444
+ // No --annual: the server takes the packet's reviewed aid price.
445
+ const plan = keepPlan || dropAgreement
446
+ ? null
447
+ : parseTuitionPlanSpecFlags(parsed, { annualOptional: true });
417
448
  const paywallRaw = flagString(parsed, "paywall")?.replace(/[$,]/g, "");
418
449
  const paywall = paywallRaw === undefined ? undefined : Number(paywallRaw);
419
450
  if (paywall !== undefined && (!Number.isFinite(paywall) || paywall <= 0)) {
@@ -437,6 +468,9 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
437
468
  const body = {
438
469
  ...(plan ? { plan: plan } : {}),
439
470
  ...(dropAgreement ? { noAgreement: true } : {}),
471
+ ...(hasFlag(parsed, "override-aid-price")
472
+ ? { overrideAidPrice: true }
473
+ : {}),
440
474
  ...(offlinePaywall
441
475
  ? { paywallOutOfBand: true }
442
476
  : paywallCents !== undefined
@@ -456,6 +490,57 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
456
490
  return json ? result : { help: await render(result.packet) };
457
491
  });
458
492
  }
493
+ if (verb === "attach-aid") {
494
+ // A financial aid form that arrived after the packet went out. The price
495
+ // is not changed here; when the review disagrees with the plan the packet
496
+ // is flagged for a requote, which also puts the aid answers in the envelope.
497
+ const packetId = positional(parsed, 2, "packet ID");
498
+ const raw = flagString(parsed, "financial-aid", { required: true }).trim();
499
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
500
+ if (raw !== "none" && !UUID.test(raw)) {
501
+ throw new CliError("invalid_arguments", "--financial-aid takes a financial aid application id, or none to detach.");
502
+ }
503
+ const financialAidApplicationId = raw === "none" ? null : raw;
504
+ return writeCommand(parsed, {
505
+ action: financialAidApplicationId
506
+ ? `attach financial aid application ${financialAidApplicationId} to admission packet ${packetId}`
507
+ : `detach the financial aid application from admission packet ${packetId}`,
508
+ target: { packetId },
509
+ request: { financialAidApplicationId },
510
+ }, async () => {
511
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/financial-aid", {
512
+ params: { path: { packetId } },
513
+ body: { financialAidApplicationId },
514
+ }));
515
+ if (json)
516
+ return result;
517
+ const p = result.packet;
518
+ const reviewed = p.financialAidApplication?.determinedAnnualTuition ?? null;
519
+ const annual = Number(p.planSpec.annualTuition);
520
+ const differs = reviewed !== null &&
521
+ p.kids.length === 1 &&
522
+ !p.noAgreement &&
523
+ Number.isFinite(annual) &&
524
+ annual !== reviewed;
525
+ return {
526
+ help: [
527
+ financialAidApplicationId ? "Attached." : "Detached.",
528
+ ...(result.resigning
529
+ ? [
530
+ "Signing had started, so the packet was requoted on its current plan: the family signs again with the new aid answers.",
531
+ ]
532
+ : []),
533
+ ...(differs
534
+ ? [
535
+ `The aid review ($${reviewed.toLocaleString("en-US")}/yr) differs from the plan ($${annual.toLocaleString("en-US")}/yr). Requote to match: recess admissions requote ${packetId} --start ... (leave out --annual to use the review).`,
536
+ ]
537
+ : []),
538
+ "",
539
+ await render(p),
540
+ ].join("\n"),
541
+ };
542
+ });
543
+ }
459
544
  if (verb === "archive-agreement") {
460
545
  const packetId = positional(parsed, 2, "packet ID");
461
546
  return writeCommand(parsed, {