recess-cli 3.11.0 → 3.13.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/args.js CHANGED
@@ -5,8 +5,10 @@ import { CliError } from "./errors.js";
5
5
  * repeatable flag must use `flagList` instead.
6
6
  */
7
7
  export const REPEATABLE_FLAGS = new Set([
8
+ "amount",
8
9
  "bill-date",
9
10
  "kid",
11
+ "staff-note",
10
12
  "note",
11
13
  "unassign",
12
14
  ]);
@@ -16,6 +18,9 @@ export const REPEATABLE_FLAGS = new Set([
16
18
  * command schema types flags from it, so `command-schema.ts` imports this.
17
19
  */
18
20
  export const BOOLEAN_FLAGS = new Set([
21
+ "keep-plan",
22
+ "no-email",
23
+ "no-paywall",
19
24
  "all",
20
25
  "all-references",
21
26
  "allow-assigned-edits",
@@ -48,6 +53,7 @@ export const BOOLEAN_FLAGS = new Set([
48
53
  "json",
49
54
  "keep-tokens",
50
55
  "mirrored",
56
+ "no-ai",
51
57
  "no-collision",
52
58
  "no-invite",
53
59
  "no-join",
package/dist/cli.js CHANGED
@@ -7,6 +7,7 @@ import { flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
7
7
  import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
8
8
  import { clearStoredSession, withConfigLock, deleteProfile, listProfiles, resolveConfig, saveProfile, useProfile, } from "./config.js";
9
9
  import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
10
+ import { runAdmissionsCommand } from "./commands/admissions.js";
10
11
  import { runApplicationsCommand } from "./commands/applications.js";
11
12
  import { runAppsCommand } from "./commands/apps.js";
12
13
  import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
@@ -18,6 +19,7 @@ import { runFeedCommand } from "./commands/feed.js";
18
19
  import { runFamiliesCommand } from "./commands/families.js";
19
20
  import { runStudentsTextsCommand, runUsersPhoneCommand, } from "./commands/phone-and-texts.js";
20
21
  import { runTuitionPlansCommand } from "./commands/tuition-plans.js";
22
+ import { runReportsCommand } from "./commands/reports.js";
21
23
  import { runMasteryCommand } from "./commands/mastery.js";
22
24
  import { runOnboardingCommand } from "./commands/onboarding.js";
23
25
  import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
@@ -2995,6 +2997,9 @@ export async function executeRecessCommand(argv, options = {}) {
2995
2997
  required: true,
2996
2998
  }),
2997
2999
  ...(tierId ? { tierId } : {}),
3000
+ ...(status === "WITHDRAWN" && flagString(parsed, "effective-at")
3001
+ ? { effectiveAt: flagString(parsed, "effective-at") }
3002
+ : {}),
2998
3003
  };
2999
3004
  return writeCommand(parsed, {
3000
3005
  action: status === "WITHDRAWN"
@@ -3394,6 +3399,9 @@ export async function executeRecessCommand(argv, options = {}) {
3394
3399
  if (noun === "applications" || noun === "quotes") {
3395
3400
  return runApplicationsCommand({ parsed, api, writeCommand });
3396
3401
  }
3402
+ if (noun === "admissions") {
3403
+ return runAdmissionsCommand({ parsed, api, writeCommand });
3404
+ }
3397
3405
  if (noun === "apps") {
3398
3406
  return runAppsCommand({
3399
3407
  parsed,
@@ -5336,6 +5344,42 @@ export async function executeRecessCommand(argv, options = {}) {
5336
5344
  body: { ordinal },
5337
5345
  })));
5338
5346
  }
5347
+ // A module added to a live goal otherwise waits for the next daily run:
5348
+ // that run reuses any launch todo already dated today for the goal.
5349
+ if (verb === "launch-todo") {
5350
+ const goalId = positional(parsed, 2, "goal id");
5351
+ const student = await studentFlag(api, parsed, { required: true });
5352
+ const studentId = student.id;
5353
+ const moduleRef = flagString(parsed, "module");
5354
+ const dueDate = flagString(parsed, "due-date");
5355
+ if (dueDate && !/^\d{4}-\d{2}-\d{2}$/.test(dueDate)) {
5356
+ throw new CliError("invalid_arguments", "--due-date must be YYYY-MM-DD (the kid's local date).");
5357
+ }
5358
+ const preview = {
5359
+ action: "create a goal module's todo now",
5360
+ target: {
5361
+ studentUserId: studentId,
5362
+ goalId,
5363
+ moduleRef: moduleRef ?? "current module (first unfinished)",
5364
+ dueDate: dueDate ?? "today in the kid's timezone",
5365
+ },
5366
+ request: {
5367
+ ...(moduleRef ? { moduleRef } : {}),
5368
+ ...(dueDate ? { dueDate } : {}),
5369
+ },
5370
+ details: {
5371
+ ...resolvedStudentDetails(student),
5372
+ note: "Idempotent: if this module already has a todo for that date, it is returned instead of a second one.",
5373
+ },
5374
+ };
5375
+ return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/tutor/students/{studentId}/goals/{goalId}/launch-todo", {
5376
+ params: { path: { studentId, goalId } },
5377
+ body: {
5378
+ ...(moduleRef ? { moduleRef } : {}),
5379
+ ...(dueDate ? { dueDate } : {}),
5380
+ },
5381
+ })));
5382
+ }
5339
5383
  if (verb === "create") {
5340
5384
  const requestedStudent = await studentFlag(api, parsed);
5341
5385
  const requestedStudentId = requestedStudent?.id;
@@ -5694,7 +5738,7 @@ export async function executeRecessCommand(argv, options = {}) {
5694
5738
  }
5695
5739
  throw new CliError("invalid_arguments", "Use goals queue get|set.");
5696
5740
  }
5697
- throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|queue|files|pdf|video.");
5741
+ throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|launch-todo|queue|files|pdf|video.");
5698
5742
  }
5699
5743
  if (noun === "channels") {
5700
5744
  return runChannelsCommand({ parsed, api, writeCommand });
@@ -5720,6 +5764,9 @@ export async function executeRecessCommand(argv, options = {}) {
5720
5764
  if (noun === "tuition-plans") {
5721
5765
  return runTuitionPlansCommand({ parsed, api, writeCommand });
5722
5766
  }
5767
+ if (noun === "reports") {
5768
+ return runReportsCommand({ parsed, api, writeCommand });
5769
+ }
5723
5770
  if (noun === "students") {
5724
5771
  if (verb === "list") {
5725
5772
  const requestedScope = flagString(parsed, "scope");
@@ -5821,6 +5868,20 @@ export async function executeRecessCommand(argv, options = {}) {
5821
5868
  },
5822
5869
  }));
5823
5870
  }
5871
+ if (verb === "math-academy") {
5872
+ const studentId = flagString(parsed, "student", { required: true });
5873
+ const startDate = flagString(parsed, "from");
5874
+ const endDate = flagString(parsed, "to");
5875
+ return unwrap(await api.client.GET("/tutor/students/{studentId}/math-academy", {
5876
+ params: {
5877
+ path: { studentId },
5878
+ query: {
5879
+ ...(startDate ? { startDate } : {}),
5880
+ ...(endDate ? { endDate } : {}),
5881
+ },
5882
+ },
5883
+ }));
5884
+ }
5824
5885
  if (verb === "issue-email") {
5825
5886
  const studentId = flagString(parsed, "student", { required: true });
5826
5887
  return writeCommand(parsed, {
@@ -138,6 +138,7 @@ const FAMILY_AI_COMMANDS = new Set([
138
138
  "goals files push",
139
139
  "goals files read",
140
140
  "goals files write",
141
+ "goals launch-todo",
141
142
  "goals list",
142
143
  "goals move-module",
143
144
  "goals pdf upload",
@@ -154,6 +155,7 @@ const FAMILY_AI_COMMANDS = new Set([
154
155
  "skills guardian get",
155
156
  "skills guardian list",
156
157
  "students list",
158
+ "students math-academy",
157
159
  "students schedule",
158
160
  "students today",
159
161
  "students xp-history",
@@ -0,0 +1,357 @@
1
+ import { unwrap } from "../api.js";
2
+ import { flagList, flagString, hasFlag } from "../args.js";
3
+ import { CliError } from "../errors.js";
4
+ import { assertChoice, positional, renderColumns, } from "./shared.js";
5
+ import { parseTuitionPlanSpecFlags } from "./tuition-plans.js";
6
+ const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
7
+ const dollars = (cents) => `$${(cents / 100).toLocaleString("en-US", {
8
+ minimumFractionDigits: cents % 100 === 0 ? 0 : 2,
9
+ maximumFractionDigits: 2,
10
+ })}`;
11
+ const STEP_LABELS = {
12
+ ACCOUNT: "waiting for the parent to create the account",
13
+ SIGN: "waiting for the tuition plan signature",
14
+ CONSENT: "waiting for parental consent",
15
+ QUESTIONS: "waiting for the enrollment questions",
16
+ PAYMENT: "waiting for payment",
17
+ DONE: "done",
18
+ };
19
+ /** One packet as terminal text: who, where they are, and each kid's answers. */
20
+ function renderPacket(packet, admissionUrl) {
21
+ const when = (iso) => (iso ? iso.slice(0, 10) : "–");
22
+ const out = [
23
+ `ADMISSION PACKET ${packet.id}`,
24
+ `${packet.parentFirstName} ${packet.parentLastName} <${packet.parentEmail}>${packet.parentPhone ? ` · ${packet.parentPhone}` : ""} · ${packet.stateCode}`,
25
+ `${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.paywallCents ? ` · paywall ${dollars(packet.paywallCents)}` : " · no paywall"}`,
26
+ `Status: ${packet.status} (${STEP_LABELS[packet.step]})`,
27
+ packet.financialAidApplication
28
+ ? `Financial aid answers in the envelope: application ${packet.financialAidApplication.id} (${packet.financialAidApplication.createdAt.slice(0, 10)})`
29
+ : "No financial aid application attached (nothing to initial).",
30
+ "",
31
+ renderColumns([
32
+ [" Sent", when(packet.sentAt), `emails: ${packet.emailSendCount}`],
33
+ [
34
+ " Account",
35
+ when(packet.accountCreatedAt),
36
+ packet.familyId ? `family ${packet.familyId}` : "",
37
+ ],
38
+ [
39
+ " Signed",
40
+ when(packet.signedAt),
41
+ packet.chosenOptionId
42
+ ? `option ${packet.chosenOptionId}${packet.documensoEnvelopeId ? ` · documenso ${packet.documensoEnvelopeId}` : ""}`
43
+ : "",
44
+ ],
45
+ [" Consent", when(packet.consentedAt), ""],
46
+ [" Questions", when(packet.questionsCompletedAt), ""],
47
+ ...(packet.paywallCents ? [[" Paid", when(packet.paidAt), ""]] : []),
48
+ [" Complete", when(packet.completedAt), ""],
49
+ ]),
50
+ ];
51
+ if (packet.status === "VOIDED") {
52
+ out.push(`Voided ${when(packet.voidedAt)}: ${packet.voidReason ?? ""}`);
53
+ }
54
+ if (packet.agreedPlan?.length) {
55
+ out.push("", "Agreed plan (as signed):");
56
+ for (const kid of packet.agreedPlan) {
57
+ out.push(` ${kid.studentName}: ${kid.term.label}, ${kid.payment.label.toLowerCase()} · ${kid.term.startDate} to ${kid.term.endDate} (${kid.term.instructionalDays} days) · total ${dollars(kid.payment.totalCents)}${kid.payment.discountCents ? ` (saves ${dollars(kid.payment.discountCents)})` : ""}`);
58
+ for (const inst of kid.installments) {
59
+ out.push(` ${inst.label}: ${dollars(inst.amountCents)}${inst.award === "PENDING" ? " at most, set once the award is confirmed" : ""} · invoiced ${inst.invoiceDate} · due ${inst.dueDate}`);
60
+ }
61
+ }
62
+ }
63
+ if (packet.signedAt) {
64
+ out.push(packet.signedAgreementKey
65
+ ? `Signed agreement archived ${when(packet.signedAgreementAt)}: ${packet.signedAgreementKey}`
66
+ : packet.documensoEnvelopeId
67
+ ? "Signed agreement not archived yet (run `recess admissions archive-agreement <packet-id>`)."
68
+ : "Signed outside Documenso: no agreement file on record.");
69
+ }
70
+ out.push("", "Kids:");
71
+ for (const kid of packet.kids) {
72
+ out.push(` ${kid.firstName}${kid.lastName ? ` ${kid.lastName}` : ""}${kid.birthdate ? ` · born ${kid.birthdate}` : ""}${kid.grade ? ` · grade ${kid.grade}` : ""}${kid.gender ? ` · gender ${kid.gender}` : ""}${kid.ethnicity ? ` · ethnicity ${kid.ethnicity}` : ""}${kid.hispanicLatino ? ` · Hispanic/Latino ${kid.hispanicLatino}` : ""}${kid.kidUserId ? ` · user ${kid.kidUserId}` : ""}`);
73
+ if (kid.responses) {
74
+ for (const [key, value] of Object.entries(kid.responses)) {
75
+ const shown = Array.isArray(value)
76
+ ? value
77
+ .map((v) => typeof v === "object" && v && "fileName" in v
78
+ ? String(v.fileName)
79
+ : String(v))
80
+ .join("; ")
81
+ : String(value);
82
+ if (shown)
83
+ out.push(` ${key}: ${shown}`);
84
+ }
85
+ }
86
+ }
87
+ out.push("", `Plan spec: ${Object.entries(packet.planSpec)
88
+ .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join("|") : String(v)}`)
89
+ .join(" ")}`);
90
+ if (packet.staffNotes)
91
+ out.push(`Staff notes: ${packet.staffNotes}`);
92
+ if (admissionUrl)
93
+ out.push("", `Link: ${admissionUrl}`);
94
+ return out.join("\n");
95
+ }
96
+ const STATUSES = [
97
+ "SENT",
98
+ "ACCOUNT_CREATED",
99
+ "SIGNED",
100
+ "CONSENTED",
101
+ "QUESTIONS_DONE",
102
+ "COMPLETE",
103
+ "VOIDED",
104
+ ];
105
+ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
106
+ const verb = parsed.positionals[1];
107
+ const json = hasFlag(parsed, "json");
108
+ if (verb === "list") {
109
+ const status = flagString(parsed, "status");
110
+ const { packets } = unwrap(await api.client.GET("/admin/admissions/", {
111
+ params: {
112
+ query: {
113
+ ...(status
114
+ ? {
115
+ status: assertChoice(status.toUpperCase(), STATUSES, "--status"),
116
+ }
117
+ : {}),
118
+ ...(flagString(parsed, "email")
119
+ ? { email: flagString(parsed, "email") }
120
+ : {}),
121
+ limit: Number(flagString(parsed, "limit") ?? 50),
122
+ },
123
+ },
124
+ }));
125
+ if (json)
126
+ return { packets };
127
+ return {
128
+ help: packets.length
129
+ ? renderColumns([
130
+ ["ID", "Parent", "Kids", "State", "Status", "Step"],
131
+ ...packets.map((p) => [
132
+ p.id,
133
+ `${p.parentFirstName} ${p.parentLastName} <${p.parentEmail}>`,
134
+ p.kids.map((k) => k.firstName).join(", "),
135
+ p.stateCode,
136
+ p.status,
137
+ STEP_LABELS[p.step],
138
+ ]),
139
+ ])
140
+ : "No admission packets.",
141
+ };
142
+ }
143
+ if (verb === "get") {
144
+ const packetId = positional(parsed, 2, "packet ID");
145
+ const { packet } = unwrap(await api.client.GET("/admin/admissions/{packetId}", {
146
+ params: { path: { packetId } },
147
+ }));
148
+ return json ? { packet } : { help: renderPacket(packet) };
149
+ }
150
+ if (verb === "create") {
151
+ const parentName = flagString(parsed, "parent", { required: true })
152
+ .trim()
153
+ .split(/\s+/);
154
+ if (parentName.length < 2) {
155
+ throw new CliError("invalid_arguments", '--parent needs a first and last name, e.g. --parent "Jordan Rivera".');
156
+ }
157
+ const kids = flagList(parsed, "kid").map((raw) => {
158
+ // "First Last:YYYY-MM-DD[:grade]"; the last name is optional.
159
+ const [who, birthdate, grade] = raw.split(":").map((v) => v.trim());
160
+ const names = (who ?? "").split(/\s+/).filter(Boolean);
161
+ if (!names.length || (birthdate && !ISO_DATE.test(birthdate))) {
162
+ throw new CliError("invalid_arguments", `--kid takes "First Last:YYYY-MM-DD[:grade]", got "${raw}".`);
163
+ }
164
+ return {
165
+ firstName: names[0],
166
+ ...(names.length > 1 ? { lastName: names.slice(1).join(" ") } : {}),
167
+ ...(birthdate ? { birthdate } : {}),
168
+ ...(grade ? { grade } : {}),
169
+ };
170
+ });
171
+ if (!kids.length) {
172
+ throw new CliError("invalid_arguments", 'At least one --kid "First Last:YYYY-MM-DD[:grade]" is required.');
173
+ }
174
+ const enrollmentChoice = assertChoice(flagString(parsed, "enrollment", { required: true }), ["direct", "partner-school", "program"], "--enrollment");
175
+ const enrollment = enrollmentChoice === "partner-school"
176
+ ? "PARTNER_SCHOOL"
177
+ : enrollmentChoice === "program"
178
+ ? "PROGRAM"
179
+ : "DIRECT";
180
+ const partnerSchool = flagString(parsed, "partner-school")?.trim();
181
+ if (enrollment === "PARTNER_SCHOOL" && !partnerSchool) {
182
+ throw new CliError("invalid_arguments", "--enrollment partner-school needs --partner-school <slug|id>.");
183
+ }
184
+ const paywallRaw = flagString(parsed, "paywall")?.replace(/[$,]/g, "");
185
+ const paywall = paywallRaw === undefined ? undefined : Number(paywallRaw);
186
+ if (paywall !== undefined && (!Number.isFinite(paywall) || paywall <= 0)) {
187
+ throw new CliError("invalid_arguments", "--paywall must be a positive dollar amount (the family share to collect in the dashboard).");
188
+ }
189
+ const plan = parseTuitionPlanSpecFlags(parsed);
190
+ const warnings = [];
191
+ if (paywall !== undefined && enrollment === "PARTNER_SCHOOL") {
192
+ warnings.push("A paywall on a partner-school enrollment is unusual: the partner usually invoices.");
193
+ }
194
+ if (paywall !== undefined && plan.stateFunding === "true") {
195
+ warnings.push("A paywall on an ESA-funded plan is unusual: those invoices are paid later from the award.");
196
+ }
197
+ const staffNotes = flagList(parsed, "staff-note")
198
+ .map((n) => n.trim())
199
+ .filter(Boolean)
200
+ .join("\n");
201
+ const body = {
202
+ ...(flagString(parsed, "application")
203
+ ? { applicationId: flagString(parsed, "application") }
204
+ : {}),
205
+ ...(flagString(parsed, "financial-aid")
206
+ ? { financialAidApplicationId: flagString(parsed, "financial-aid") }
207
+ : {}),
208
+ institutionSlug: flagString(parsed, "school", { required: true }),
209
+ enrollment,
210
+ ...(partnerSchool ? { partnerSchool } : {}),
211
+ parentFirstName: parentName[0],
212
+ parentLastName: parentName.slice(1).join(" "),
213
+ parentEmail: flagString(parsed, "email", { required: true }),
214
+ ...(flagString(parsed, "phone")
215
+ ? { parentPhone: flagString(parsed, "phone") }
216
+ : {}),
217
+ state: flagString(parsed, "state", { required: true }).toUpperCase(),
218
+ ...(flagString(parsed, "tier")
219
+ ? { tierId: flagString(parsed, "tier") }
220
+ : {}),
221
+ kids,
222
+ plan: plan,
223
+ ...(paywall !== undefined
224
+ ? { paywallCents: Math.round(paywall * 100) }
225
+ : {}),
226
+ ...(staffNotes ? { staffNotes } : {}),
227
+ sendEmail: !hasFlag(parsed, "no-email"),
228
+ };
229
+ return writeCommand(parsed, {
230
+ action: `create an admission packet for ${body.parentEmail} (${kids.map((k) => k.firstName).join(", ")}) and ${body.sendEmail ? "email them the link" : "return the link without emailing"}`,
231
+ target: { parentEmail: body.parentEmail, school: body.institutionSlug },
232
+ request: body,
233
+ ...(warnings.length ? { details: { warnings } } : {}),
234
+ }, async () => {
235
+ const result = unwrap(await api.client.POST("/admin/admissions/", { body }));
236
+ if (json)
237
+ return result;
238
+ return {
239
+ help: [
240
+ renderPacket(result.packet, result.admissionUrl),
241
+ "",
242
+ `Tuition plan: ${result.plan.introduction}`,
243
+ ...result.plan.options.map((o) => ` ${o.id}: ${o.label} ${dollars(o.totalCents)}`),
244
+ "",
245
+ result.emailed
246
+ ? `Emailed ${result.packet.parentEmail}.`
247
+ : "Not emailed (--no-email); send the link yourself.",
248
+ ...warnings.map((w) => `Warning: ${w}`),
249
+ ].join("\n"),
250
+ };
251
+ });
252
+ }
253
+ if (verb === "resend") {
254
+ const packetId = positional(parsed, 2, "packet ID");
255
+ const sendEmail = !hasFlag(parsed, "no-email");
256
+ return writeCommand(parsed, {
257
+ action: `mint a new link for admission packet ${packetId} (the old link stops working)${sendEmail ? " and email it" : ""}`,
258
+ target: { packetId },
259
+ request: { sendEmail },
260
+ }, async () => {
261
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/resend", {
262
+ params: { path: { packetId } },
263
+ body: { sendEmail },
264
+ }));
265
+ return json
266
+ ? result
267
+ : { help: renderPacket(result.packet, result.admissionUrl) };
268
+ });
269
+ }
270
+ if (verb === "void") {
271
+ const packetId = positional(parsed, 2, "packet ID");
272
+ const reason = flagString(parsed, "reason", { required: true });
273
+ return writeCommand(parsed, {
274
+ action: `void admission packet ${packetId}`,
275
+ target: { packetId },
276
+ request: { reason },
277
+ }, async () => {
278
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/void", {
279
+ params: { path: { packetId } },
280
+ body: { reason },
281
+ }));
282
+ return json ? result : { help: renderPacket(result.packet) };
283
+ });
284
+ }
285
+ if (verb === "mark-signed") {
286
+ const packetId = positional(parsed, 2, "packet ID");
287
+ const optionId = flagString(parsed, "option", { required: true });
288
+ const note = flagString(parsed, "note");
289
+ return writeCommand(parsed, {
290
+ action: `mark admission packet ${packetId} as signed outside the dashboard (option ${optionId})`,
291
+ target: { packetId },
292
+ request: { optionId, ...(note ? { note } : {}) },
293
+ }, async () => {
294
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/mark-signed", {
295
+ params: { path: { packetId } },
296
+ body: { optionId, ...(note ? { note } : {}) },
297
+ }));
298
+ return json ? result : { help: renderPacket(result.packet) };
299
+ });
300
+ }
301
+ if (verb === "requote") {
302
+ const packetId = positional(parsed, 2, "packet ID");
303
+ // --keep-plan reopens the choice on the stored plan (e.g. the family
304
+ // wants monthly after signing pay in full); otherwise the plan flags
305
+ // replace it.
306
+ const keepPlan = hasFlag(parsed, "keep-plan");
307
+ const plan = keepPlan ? null : parseTuitionPlanSpecFlags(parsed);
308
+ const paywallRaw = flagString(parsed, "paywall")?.replace(/[$,]/g, "");
309
+ const paywall = paywallRaw === undefined ? undefined : Number(paywallRaw);
310
+ if (paywall !== undefined && (!Number.isFinite(paywall) || paywall <= 0)) {
311
+ throw new CliError("invalid_arguments", "--paywall must be a positive dollar amount; --no-paywall removes it.");
312
+ }
313
+ if (paywall !== undefined && hasFlag(parsed, "no-paywall")) {
314
+ throw new CliError("invalid_arguments", "Use --paywall DOLLARS or --no-paywall, not both.");
315
+ }
316
+ const note = flagString(parsed, "note")?.trim();
317
+ // Undefined keeps the packet's paywall; null removes it.
318
+ const paywallCents = paywall !== undefined
319
+ ? Math.round(paywall * 100)
320
+ : hasFlag(parsed, "no-paywall")
321
+ ? null
322
+ : undefined;
323
+ const body = {
324
+ ...(plan ? { plan: plan } : {}),
325
+ ...(paywallCents !== undefined ? { paywallCents } : {}),
326
+ ...(note ? { note } : {}),
327
+ };
328
+ return writeCommand(parsed, {
329
+ action: `requote admission packet ${packetId}: ${keepPlan ? "reopen the payment choice on the same plan" : "replace its tuition plan"}${paywallCents === null ? " and remove the paywall" : paywallCents ? ` and set the paywall to ${dollars(paywallCents)}` : ""}; the family signs again from the same link`,
330
+ target: { packetId },
331
+ request: body,
332
+ }, async () => {
333
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/requote", {
334
+ params: { path: { packetId } },
335
+ body,
336
+ }));
337
+ return json ? result : { help: renderPacket(result.packet) };
338
+ });
339
+ }
340
+ if (verb === "archive-agreement") {
341
+ const packetId = positional(parsed, 2, "packet ID");
342
+ return writeCommand(parsed, {
343
+ action: `copy admission packet ${packetId}'s signed agreement from Documenso into our storage`,
344
+ target: { packetId },
345
+ request: {},
346
+ }, async () => {
347
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/archive-agreement", { params: { path: { packetId } } }));
348
+ return json
349
+ ? result
350
+ : {
351
+ help: `${result.archived ? "Archived." : "Nothing to archive yet: the envelope is not complete, or the packet was signed outside Documenso."}\n\n${renderPacket(result.packet)}`,
352
+ };
353
+ });
354
+ }
355
+ throw new CliError("invalid_arguments", "Usage: recess admissions create|get|list|resend|void|mark-signed|requote|archive-agreement. See `recess help`.");
356
+ }
357
+ //# sourceMappingURL=admissions.js.map
@@ -0,0 +1,84 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { unwrap } from "../api.js";
4
+ import { flagString, hasFlag } from "../args.js";
5
+ import { CliError } from "../errors.js";
6
+ const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
7
+ /**
8
+ * `recess reports activity` — the weekly student activity report, generated on
9
+ * the server (GET /admin/activity-reports/) and written to a local folder: the
10
+ * summary PDF, the CSV bundle, and the per-student summaries JSON.
11
+ */
12
+ export async function runReportsCommand({ parsed, api, }) {
13
+ const verb = parsed.positionals[1];
14
+ if (verb !== "activity") {
15
+ throw new CliError("invalid_arguments", "Usage: recess reports activity --partner-school <slug|id> | --guide <name|email|id> | --cohort <cohort-id>. See `recess help`.");
16
+ }
17
+ const partnerSchool = flagString(parsed, "partner-school")?.trim();
18
+ const guide = flagString(parsed, "guide")?.trim();
19
+ const cohortId = flagString(parsed, "cohort")?.trim();
20
+ if ([partnerSchool, guide, cohortId].filter(Boolean).length !== 1) {
21
+ throw new CliError("invalid_arguments", "Pass exactly one of --partner-school, --guide, or --cohort.");
22
+ }
23
+ const weekStart = flagString(parsed, "week")?.trim();
24
+ if (weekStart && !ISO_DATE.test(weekStart)) {
25
+ throw new CliError("invalid_arguments", "--week must be the Monday of the week, as YYYY-MM-DD.");
26
+ }
27
+ const query = {
28
+ ...(partnerSchool ? { partnerSchool } : {}),
29
+ ...(guide ? { guide } : {}),
30
+ ...(cohortId ? { cohortId } : {}),
31
+ ...(weekStart ? { weekStart } : {}),
32
+ ai: hasFlag(parsed, "no-ai") ? "false" : "true",
33
+ };
34
+ const report = unwrap(await api.client.GET("/admin/activity-reports/", { params: { query } }));
35
+ const stem = `${report.slug}_${report.weekStart}`;
36
+ const dir = path.resolve(flagString(parsed, "out") ?? stem);
37
+ await fs.mkdir(dir, { recursive: true });
38
+ const files = [];
39
+ // Student data: write each file to a fresh 0600 temp file, then rename it
40
+ // over the destination. A plain writeFile keeps an existing file's looser
41
+ // mode and would follow a symlink planted at the destination.
42
+ const write = async (name, data) => {
43
+ const file = path.join(dir, name);
44
+ const tmp = path.join(dir, `.${name}.${process.pid}.${Date.now()}.tmp`);
45
+ try {
46
+ await fs.writeFile(tmp, data, { mode: 0o600, flag: "wx" });
47
+ await fs.rename(tmp, file);
48
+ }
49
+ catch (error) {
50
+ // Remove our (possibly partial) temp file; EEXIST means it isn't ours.
51
+ if (error.code !== "EEXIST") {
52
+ await fs.rm(tmp, { force: true });
53
+ }
54
+ throw error;
55
+ }
56
+ files.push(file);
57
+ };
58
+ await write(`${stem}_summary.pdf`, Buffer.from(report.pdfBase64, "base64"));
59
+ for (const [name, text] of Object.entries(report.csv))
60
+ await write(name, text);
61
+ if (report.summaries) {
62
+ await write(`${stem}_summaries.json`, `${JSON.stringify(report.summaries, null, 2)}\n`);
63
+ }
64
+ const result = {
65
+ title: report.title,
66
+ weekStart: report.weekStart,
67
+ weekEnd: report.weekEnd,
68
+ studentCount: report.studentCount,
69
+ groups: report.groups,
70
+ dir,
71
+ files,
72
+ };
73
+ if (hasFlag(parsed, "json"))
74
+ return result;
75
+ return {
76
+ help: [
77
+ `${report.title}: ${report.weekStart} to ${report.weekEnd}`,
78
+ `${report.studentCount} students${report.groups.length ? ` in ${report.groups.length} groups` : ""}${report.summaries ? "" : " (no AI summaries)"}`,
79
+ `Wrote ${files.length} files to ${dir}`,
80
+ ...files.map((f) => ` ${path.basename(f)}`),
81
+ ].join("\n"),
82
+ };
83
+ }
84
+ //# sourceMappingURL=reports.js.map
@@ -94,32 +94,16 @@ function renderPlan(plan, webUrl, pdfPath) {
94
94
  out.push(`PDF: ${pdfPath}`);
95
95
  return out.join("\n");
96
96
  }
97
- export async function runTuitionPlansCommand({ parsed, api, }) {
98
- const verb = parsed.positionals[1];
99
- if (verb === "states") {
100
- return unwrap(await api.client.GET("/admin/tuition-plans/states/"));
101
- }
102
- if (verb !== "generate") {
103
- throw new CliError("invalid_arguments", "Usage: recess tuition-plans generate|states. See `recess help`.");
104
- }
97
+ /**
98
+ * The tuition-plan flags that describe the plan itself (everything but who
99
+ * it is for): shared by `tuition-plans generate` and `admissions create`,
100
+ * which stores them as the packet's plan spec.
101
+ */
102
+ export function parseTuitionPlanSpecFlags(parsed) {
105
103
  const annual = Number(requiredFlag(parsed, "annual").replace(/[$,]/g, ""));
106
104
  if (!Number.isFinite(annual) || annual <= 0) {
107
105
  throw new CliError("invalid_arguments", "--annual must be a positive dollar amount (net of Recess financial aid).");
108
106
  }
109
- // The server owns the supported-state list; resolve against it so a bad
110
- // code fails with the valid choices.
111
- const { states } = unwrap(await api.client.GET("/admin/tuition-plans/states/"));
112
- const state = assertChoice(requiredFlag(parsed, "state", /^[A-Za-z]{2}$/).toUpperCase(), states.map((s) => s.code), "--state");
113
- const enrollment = assertChoice(requiredFlag(parsed, "enrollment"), ["direct", "partner-school"], "--enrollment") === "partner-school"
114
- ? "PARTNER_SCHOOL"
115
- : "DIRECT";
116
- const partnerSchool = flagString(parsed, "partner-school")?.trim();
117
- if (enrollment === "PARTNER_SCHOOL" && !partnerSchool) {
118
- throw new CliError("invalid_arguments", "--enrollment partner-school needs --partner-school <slug|id> (see `recess users enrollment list-partner-schools`).");
119
- }
120
- if (enrollment === "DIRECT" && partnerSchool) {
121
- throw new CliError("invalid_arguments", "--partner-school applies only with --enrollment partner-school.");
122
- }
123
107
  // Add-on overrides; omitted = the server's school-pricing defaults.
124
108
  const addOnFlag = (name, integer) => {
125
109
  const raw = flagString(parsed, name)?.trim().replace(/[$,]/g, "");
@@ -141,11 +125,6 @@ export async function runTuitionPlansCommand({ parsed, api, }) {
141
125
  ...(oneOnOnePrice !== undefined ? { oneOnOnePrice } : {}),
142
126
  ...(oneOnOneSessions !== undefined ? { oneOnOneSessions } : {}),
143
127
  };
144
- // Optional: without it the sheet leaves out the student's age.
145
- const dob = flagString(parsed, "dob")?.trim();
146
- if (dob && !ISO_DATE.test(dob)) {
147
- throw new CliError("invalid_arguments", "--dob must look like YYYY-MM-DD.");
148
- }
149
128
  // Omitted = the full matrix (full year + school year [+ custom with --end]) ×
150
129
  // (upfront + installments). A full year past July 1 drops out of the
151
130
  // default; asking for it explicitly is refused by the server.
@@ -175,6 +154,16 @@ export async function runTuitionPlansCommand({ parsed, api, }) {
175
154
  }
176
155
  return `${key}=${date}`;
177
156
  });
157
+ const amounts = flagList(parsed, "amount").map((raw) => {
158
+ const [key, dollars] = raw.split("=").map((v) => v.trim());
159
+ if (!key ||
160
+ !dollars ||
161
+ !/^[1-9]\d*$/.test(key) ||
162
+ !/^\$?\d[\d,]*(\.\d{1,2})?$/.test(dollars)) {
163
+ throw new CliError("invalid_arguments", `--amount takes N=DOLLARS (installment N's amount), got "${raw}".`);
164
+ }
165
+ return `${key}=${dollars.replace(/[$,]/g, "")}`;
166
+ });
178
167
  const even = hasFlag(parsed, "even-installments");
179
168
  // Award not yet known: --annual is the income-based price with no award.
180
169
  const esaUnknown = hasFlag(parsed, "esa-award-unknown");
@@ -198,40 +187,84 @@ export async function runTuitionPlansCommand({ parsed, api, }) {
198
187
  ...(esaScenarios ? { esaScenarios } : {}),
199
188
  ...(even ? { evenInstallments: "true" } : {}),
200
189
  ...(billDates.length ? { billDates: billDates.join(",") } : {}),
190
+ ...(amounts.length ? { amounts: amounts.join(",") } : {}),
201
191
  ...(endDate ? { endDate } : {}),
202
192
  ...(terms ? { terms: terms.join(",") } : {}),
203
193
  ...(payments ? { payments: payments.join(",") } : {}),
204
194
  };
205
- const query = {
206
- parentName: requiredFlag(parsed, "parent"),
207
- studentName: requiredFlag(parsed, "student"),
208
- ...(dob ? { studentDob: dob } : {}),
209
- state,
195
+ return {
210
196
  startDate: requiredFlag(parsed, "start", ISO_DATE),
211
197
  annualTuition: annual,
212
198
  stateFunding: hasFlag(parsed, "state-funding") ? "true" : "false",
213
- enrollment,
214
- ...(partnerSchool ? { partnerSchool } : {}),
215
199
  ...addOnQuery,
216
200
  ...subsetQuery,
217
201
  ...(notes.length ? { notes } : {}),
218
202
  };
219
- const plan = unwrap(await api.client.GET("/admin/tuition-plans/", { params: { query } }));
220
- const search = new URLSearchParams({
221
- parentName: query.parentName,
222
- studentName: query.studentName,
203
+ }
204
+ /** The query-string form of a plan spec, for the web deep link. */
205
+ export function planSpecSearchParams(spec) {
206
+ const search = new URLSearchParams();
207
+ for (const [key, value] of Object.entries(spec)) {
208
+ if (value === undefined || key === "notes")
209
+ continue;
210
+ if (key === "stateFunding" && value !== "true")
211
+ continue;
212
+ search.set(key, String(value));
213
+ }
214
+ for (const note of spec.notes ?? [])
215
+ search.append("notes", note);
216
+ return search;
217
+ }
218
+ export async function runTuitionPlansCommand({ parsed, api, }) {
219
+ const verb = parsed.positionals[1];
220
+ if (verb === "states") {
221
+ return unwrap(await api.client.GET("/admin/tuition-plans/states/"));
222
+ }
223
+ if (verb !== "generate") {
224
+ throw new CliError("invalid_arguments", "Usage: recess tuition-plans generate|states. See `recess help`.");
225
+ }
226
+ const spec = parseTuitionPlanSpecFlags(parsed);
227
+ // The server owns the supported-state list; resolve against it so a bad
228
+ // code fails with the valid choices.
229
+ const { states } = unwrap(await api.client.GET("/admin/tuition-plans/states/"));
230
+ const state = assertChoice(requiredFlag(parsed, "state", /^[A-Za-z]{2}$/).toUpperCase(), states.map((s) => s.code), "--state");
231
+ const enrollmentChoice = assertChoice(requiredFlag(parsed, "enrollment"), ["direct", "partner-school", "program"], "--enrollment");
232
+ const enrollment = enrollmentChoice === "partner-school"
233
+ ? "PARTNER_SCHOOL"
234
+ : enrollmentChoice === "program"
235
+ ? "PROGRAM"
236
+ : "DIRECT";
237
+ const partnerSchool = flagString(parsed, "partner-school")?.trim();
238
+ if (enrollment === "PARTNER_SCHOOL" && !partnerSchool) {
239
+ throw new CliError("invalid_arguments", "--enrollment partner-school needs --partner-school <slug|id> (see `recess users enrollment list-partner-schools`).");
240
+ }
241
+ if (enrollment !== "PARTNER_SCHOOL" && partnerSchool) {
242
+ throw new CliError("invalid_arguments", "--partner-school applies only with --enrollment partner-school.");
243
+ }
244
+ // Optional: without it the sheet leaves out the student's age.
245
+ const dob = flagString(parsed, "dob")?.trim();
246
+ if (dob && !ISO_DATE.test(dob)) {
247
+ throw new CliError("invalid_arguments", "--dob must look like YYYY-MM-DD.");
248
+ }
249
+ const query = {
250
+ parentName: requiredFlag(parsed, "parent"),
251
+ studentName: requiredFlag(parsed, "student"),
223
252
  ...(dob ? { studentDob: dob } : {}),
224
- state: query.state,
225
- startDate: query.startDate,
226
- annualTuition: String(annual),
227
- ...(query.stateFunding === "true" ? { stateFunding: "true" } : {}),
253
+ state,
228
254
  enrollment,
229
255
  ...(partnerSchool ? { partnerSchool } : {}),
230
- ...Object.fromEntries(Object.entries(addOnQuery).map(([k, v]) => [k, String(v)])),
231
- ...subsetQuery,
232
- });
233
- for (const note of notes)
234
- search.append("notes", note);
256
+ ...spec,
257
+ };
258
+ const plan = unwrap(await api.client.GET("/admin/tuition-plans/", { params: { query } }));
259
+ const search = planSpecSearchParams(spec);
260
+ search.set("parentName", query.parentName);
261
+ search.set("studentName", query.studentName);
262
+ if (dob)
263
+ search.set("studentDob", dob);
264
+ search.set("state", query.state);
265
+ search.set("enrollment", enrollment);
266
+ if (partnerSchool)
267
+ search.set("partnerSchool", partnerSchool);
235
268
  const webUrl = new URL(`/admin/tuition-plans?${search}`, api.config.webOrigin).toString();
236
269
  let pdfPath;
237
270
  const pdfFlag = flagString(parsed, "pdf");
@@ -12,8 +12,8 @@ function humanize(slug) {
12
12
  }
13
13
  /**
14
14
  * A module-backed workspace tree that passes the server's
15
- * `validateGoalBuilderWorkspaceFiles`: the seven top-level files, both state
16
- * files, content under each required directory, and complete module files
15
+ * `validateGoalBuilderWorkspaceFiles`: the files the runtime reads (`AGENTS.md`,
16
+ * `first-message.md`, `state/progress.json`) and complete module files
17
17
  * (summary, estimated time, the five required `##` sections). Every prose file
18
18
  * carries `SCAFFOLD_MARKER` so a push reports what is still generic.
19
19
  */
@@ -25,25 +25,7 @@ export function buildGoalWorkspaceScaffold(input) {
25
25
  title: `Module ${index + 1}`,
26
26
  }));
27
27
  const md = (body) => `${body.trim()}\n\n${SCAFFOLD_MARKER}\n`;
28
- const moduleList = modules
29
- .map((module) => `- ${module.ref}: ${module.title}`)
30
- .join("\n");
31
28
  return [
32
- {
33
- path: "README.md",
34
- content: md(`# ${title}
35
-
36
- State the outcome in one sentence: what the student can do when this path is finished.
37
-
38
- ## Sessions
39
-
40
- ${moduleList}
41
-
42
- ## Workspace contract
43
-
44
- - Module files under \`modules/\` are Rocky's runtime script for each session.
45
- - Durable progress lives in \`state/progress.json\`; student work lives under \`resources/\`.`),
46
- },
47
29
  {
48
30
  path: "AGENTS.md",
49
31
  content: md(`# Tutor Agent Instructions
@@ -64,77 +46,12 @@ You are Rocky, running **${title}** with one student.
64
46
 
65
47
  - Keep durable progress in \`state/progress.json\`.
66
48
  - Put student-facing work under \`resources/\`; student uploads arrive under \`uploads/\`.`),
67
- },
68
- {
69
- path: "goal-architecture.md",
70
- content: md(`# Goal Architecture
71
-
72
- ## Outcome
73
-
74
- Describe the finished state and why this sequence reaches it.
75
-
76
- ## Sequence
77
-
78
- ${moduleList}
79
-
80
- ## Completion
81
-
82
- The path completes when every module's completion criteria are met with visible student work.`),
83
49
  },
84
50
  {
85
51
  path: "first-message.md",
86
52
  content: md(`# First Message
87
53
 
88
54
  Write Rocky's opening line for the first session. Keep it to the goal's first session and make it agree with ${modules[0].ref} and \`AGENTS.md\`.`),
89
- },
90
- {
91
- path: "lesson-template.md",
92
- content: md(`# Lesson Template
93
-
94
- ## Warm start
95
-
96
- - Remind the student what today's session adds.
97
-
98
- ## Work loop
99
-
100
- 1. Student tries a small piece.
101
- 2. Tutor looks at the actual work.
102
- 3. One targeted question or hint.
103
- 4. Student revises or explains.
104
-
105
- ## Wrap
106
-
107
- - Update \`state/progress.json\` and decide whether the completion criteria are met.`),
108
- },
109
- {
110
- path: "final-assessment.md",
111
- content: md(`# Final Assessment
112
-
113
- ## Evidence to collect
114
-
115
- - The finished work from the last module.
116
- - The student's own explanation of what they learned.
117
-
118
- ## Completion bar
119
-
120
- Complete only when the student demonstrates the outcome on their own work without heavy prompting.`),
121
- },
122
- {
123
- path: "build-report.md",
124
- content: md(`# Build Report
125
-
126
- ## Sources
127
-
128
- - Record every source URL or uploaded-page anchor used.
129
-
130
- ## Validation checks
131
-
132
- - Required workspace files present.
133
- - Every module carries summary, estimated time, learning targets, tutor guidance, resources, completion criteria and state updates.
134
-
135
- ## Remaining risks
136
-
137
- - List anything still unverified.`),
138
55
  },
139
56
  {
140
57
  path: "state/progress.json",
@@ -145,34 +62,6 @@ Complete only when the student demonstrates the outcome on their own work withou
145
62
  lastTutorSummary: null,
146
63
  }, null, 2)}\n`,
147
64
  },
148
- {
149
- path: "state/student_profile.md",
150
- content: `# Student Profile
151
-
152
- - Grade: unknown
153
-
154
- Update this file when durable preferences, strengths, or supports become clear during tutoring.
155
- `,
156
- },
157
- {
158
- path: "research/notes.md",
159
- content: md(`# Research Notes
160
-
161
- Record the sources consulted and what each contributes.`),
162
- },
163
- { path: "resources/.keep", content: "" },
164
- { path: "uploads/.keep", content: "" },
165
- {
166
- path: "tutor-toolkit/tutoring-principles.md",
167
- content: `# Tutoring Principles
168
-
169
- 1. Find the floor before deep prompts.
170
- 2. Ask what the student notices before explaining.
171
- 3. Prefer scaffolding moves over explanation.
172
- 4. Praise specific evidence, not effort in general.
173
- 5. Keep completion tied to visible work.
174
- `,
175
- },
176
65
  ...modules.map((module, index) => ({
177
66
  path: module.path,
178
67
  content: md(`# Module ${module.ref}: ${module.title}
@@ -209,26 +98,8 @@ Where to start: name the exact page, app, file, or tab Rocky opens first, then t
209
98
  // ---------------------------------------------------------------------------
210
99
  // Local workspace validation (mirror of goal-builder-workspace-validation.ts)
211
100
  // ---------------------------------------------------------------------------
212
- const REQUIRED_TOP_LEVEL_FILES = [
213
- "README.md",
214
- "AGENTS.md",
215
- "goal-architecture.md",
216
- "first-message.md",
217
- "lesson-template.md",
218
- "final-assessment.md",
219
- "build-report.md",
220
- ];
221
- const REQUIRED_STATE_FILES = [
222
- "state/progress.json",
223
- "state/student_profile.md",
224
- ];
225
- const REQUIRED_PREFIXES = [
226
- "modules/",
227
- "research/",
228
- "resources/",
229
- "uploads/",
230
- "tutor-toolkit/",
231
- ];
101
+ // `state/progress.json` is optional: the server seeds it at create.
102
+ const REQUIRED_TOP_LEVEL_FILES = ["AGENTS.md", "first-message.md"];
232
103
  const READY_MODULE_REQUIREMENTS = [
233
104
  { label: "learning target", patterns: [/^Learning targets?\b/i] },
234
105
  {
@@ -373,6 +244,8 @@ function hasUnresolvedPlaceholder(path, content) {
373
244
  return !/\b(example|syntax|literal|placeholder|template|token|mustache)\b/.test(prose);
374
245
  });
375
246
  }
247
+ /** Mirror of the server's `SIDE_FILE_REFERENCE`: files voice Rocky never sees. */
248
+ const SIDE_FILE_REFERENCE = /\btutor-toolkit\/[\w./-]+\.\w+|\b(?:README|goal-architecture|lesson-template|final-assessment|build-report)\.md\b/g;
376
249
  const TEXT_EXTENSIONS = /\.(md|markdown|txt|json|html?|css|js|mjs|ts|csv|ya?ml|svg)$/i;
377
250
  /**
378
251
  * Mirrors the server's file, section, module and progress rules. File
@@ -382,21 +255,13 @@ export function validateGoalWorkspaceLocally(files) {
382
255
  const errors = [];
383
256
  const warnings = [];
384
257
  const byPath = new Map(files.map((file) => [file.path, file]));
385
- for (const required of [
386
- ...REQUIRED_TOP_LEVEL_FILES,
387
- ...REQUIRED_STATE_FILES,
388
- ]) {
258
+ for (const required of REQUIRED_TOP_LEVEL_FILES) {
389
259
  const file = byPath.get(required);
390
260
  if (!file)
391
261
  errors.push(`Missing required file: ${required}`);
392
262
  else if (!file.content.trim())
393
263
  errors.push(`Required file is empty: ${required}`);
394
264
  }
395
- for (const prefix of REQUIRED_PREFIXES) {
396
- if (!files.some((file) => file.path.startsWith(prefix))) {
397
- errors.push(`Missing required workspace directory content: ${prefix} (a ${prefix}.keep file is enough)`);
398
- }
399
- }
400
265
  const moduleRefs = new Map();
401
266
  for (const file of files) {
402
267
  if (!file.path.startsWith("modules/") || !file.path.endsWith(".md"))
@@ -448,6 +313,14 @@ export function validateGoalWorkspaceLocally(files) {
448
313
  else if (!moduleRefs.has(currentRef))
449
314
  errors.push(`state/progress.json current module ${currentRef} does not match a module file`);
450
315
  }
316
+ for (const file of files) {
317
+ if (file.path !== "AGENTS.md" &&
318
+ !(file.path.startsWith("modules/") && file.path.endsWith(".md")))
319
+ continue;
320
+ const cited = new Set(liveLines(file.content).flatMap((line) => [...line.matchAll(SIDE_FILE_REFERENCE)].map((match) => match[0])));
321
+ if (cited.size > 0)
322
+ warnings.push(`${file.path} sends Rocky to ${[...cited].join(", ")}; voice Rocky never sees side files (he can only ask a helper to look one up), so put what he needs during the lesson in AGENTS.md or the module itself`);
323
+ }
451
324
  const buildReport = byPath.get("build-report.md")?.content;
452
325
  if (buildReport &&
453
326
  !/\b(validation|self-coherence|checks?)\b/i.test(buildReport))
package/dist/help.js CHANGED
@@ -40,7 +40,7 @@ Usage:
40
40
  recess [--json] users school complete-action <user-id> <action-id> --note <text> [--confirm]
41
41
  recess [--json] users school status <user-id>
42
42
  recess [--json] users school history <user-id> [--limit 25] [--cursor <id>]
43
- recess [--json] users school withdraw <user-id> --note <text> --expected-updated-at <iso> [--confirm]
43
+ recess [--json] users school withdraw <user-id> --note <text> --expected-updated-at <iso> [--effective-at <iso>] [--confirm]
44
44
  recess [--json] users school restore <user-id> --tier <tier-id> --note <text> --expected-updated-at <iso> [--confirm]
45
45
  recess [--json] users enrollment history <user-id> [--limit 25] [--cursor <id>]
46
46
  recess [--json] users enrollment set-partner-school-cc <school-id-or-slug>
@@ -91,6 +91,8 @@ Usage:
91
91
  recess [--json] students analysis --todo <todo-id>
92
92
  recess [--json] students xp-history --student <kid-id>
93
93
  [--range week|month|quarter|year]
94
+ recess [--json] students math-academy --student <kid-id>
95
+ [--from YYYY-MM-DD] [--to YYYY-MM-DD]
94
96
  recess [--json] enrollments list --user <user-id>
95
97
  recess [--json] subscriptions list --family <family-id> [--kid <kid-id>]
96
98
  recess [--json] invoices list --subscription <subscription-id>
@@ -189,13 +191,33 @@ Usage:
189
191
  recess [--json] channels members set-role <channel-id> <user-id...> --role MEMBER|MODERATOR|ADMIN [--confirm]
190
192
  recess [--json] channels members remove <channel-id> <user-id...> [--confirm]
191
193
  recess [--json] tuition-plans generate --parent TEXT --student TEXT [--dob YYYY-MM-DD]
192
- --state XX --start YYYY-MM-DD --annual DOLLARS --enrollment direct|partner-school
194
+ --state XX --start YYYY-MM-DD --annual DOLLARS --enrollment direct|partner-school|program
193
195
  [--partner-school <slug|id>] [--force-direct] [--state-funding] [--elective-price DOLLARS]
194
196
  [--one-on-one-price DOLLARS] [--one-on-one-sessions N] [--end YYYY-MM-DD]
195
197
  [--terms full-year,school-year,custom] [--payments upfront,installments]
196
- [--note TEXT]... [--bill-date upfront|N=YYYY-MM-DD]... [--even-installments]
198
+ [--note TEXT]... [--bill-date upfront|N=YYYY-MM-DD]... [--amount N=DOLLARS]... [--even-installments]
197
199
  [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--pdf <path>] [--open]
198
200
  recess [--json] tuition-plans states
201
+ recess [--json] admissions create --school <institution-slug> --enrollment direct|partner-school|program
202
+ [--partner-school <slug|id>] --parent "First Last" --email EMAIL [--phone TEXT] --state XX
203
+ --kid "First Last:YYYY-MM-DD[:grade]" (repeat per child) [--application <application-id>]
204
+ [--financial-aid <financial-aid-application-id>|none]
205
+ [--tier complete] [--paywall DOLLARS] [--staff-note TEXT]... [--no-email]
206
+ --start YYYY-MM-DD --annual DOLLARS [--state-funding] [--end YYYY-MM-DD]
207
+ [--terms full-year,school-year,custom] [--payments upfront,installments] [--note TEXT]...
208
+ [--bill-date upfront|N=YYYY-MM-DD]... [--amount N=DOLLARS]... [--even-installments] [--force-direct]
209
+ [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--elective-price DOLLARS]
210
+ [--one-on-one-price DOLLARS] [--one-on-one-sessions N] [--confirm]
211
+ recess [--json] admissions get <packet-id>
212
+ recess [--json] admissions list [--status SENT|ACCOUNT_CREATED|SIGNED|CONSENTED|QUESTIONS_DONE|COMPLETE|VOIDED] [--email TEXT] [--limit N]
213
+ recess [--json] admissions resend <packet-id> [--no-email] [--confirm]
214
+ recess [--json] admissions void <packet-id> --reason TEXT [--confirm]
215
+ recess [--json] admissions mark-signed <packet-id> --option <term:payment> [--note TEXT] [--confirm]
216
+ recess [--json] admissions requote <packet-id> (--keep-plan | --start YYYY-MM-DD --annual DOLLARS [plan flags as in create])
217
+ [--paywall DOLLARS|--no-paywall] [--note TEXT] [--confirm]
218
+ recess [--json] admissions archive-agreement <packet-id> [--confirm]
219
+ recess [--json] reports activity [--partner-school <slug|id>] [--guide <name|email|id>]
220
+ [--cohort <cohort-id>] [--week YYYY-MM-DD] [--no-ai] [--out <dir>]
199
221
  recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
200
222
  recess [--json] cohorts schedule get <cohort-id>
201
223
  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>]
@@ -469,6 +491,8 @@ Usage:
469
491
  [--confirm --approval-token TOKEN]
470
492
  recess [--json] goals move-module <module-ref> --student <kid-id> --goal <goal-id>
471
493
  (--to-end | --position <n>) [--confirm --approval-token TOKEN]
494
+ recess [--json] goals launch-todo <goal-id> --student <kid-id> [--module <module-ref>]
495
+ [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
472
496
  recess [--json] goals queue get <goal-id> --student <kid-id>
473
497
  recess [--json] goals queue set <goal-id> --student <kid-id>
474
498
  --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -670,6 +694,17 @@ omitted for US; US ZIPs must be 12345 or 12345-6789. Each entry replaces the
670
694
  family's whole address. The preview is the server's dry run: before and after
671
695
  for every family that changes.
672
696
 
697
+ Activity-report notes: "reports activity" builds a weekly student activity report
698
+ on the server for exactly one audience: a partner school's enrolled kids
699
+ (--partner-school), a guide's academy roster grouped by core-academics cohort
700
+ (--guide takes a first name, full name, email, or id; an ambiguous name lists the
701
+ matches), or one cohort's registered kids (--cohort). --week is the Monday of the
702
+ week (default: the last full Mon-Sun week, US Eastern). It writes the summary PDF,
703
+ the CSVs, and the per-student AI summaries JSON to --out (default
704
+ ./<report>_<week>/). --no-ai skips the per-student summaries. Generation takes
705
+ 10-30 seconds; AI summaries name the student and quote their work, so review
706
+ them before sending a report outside Recess.
707
+
673
708
  Tuition-plan notes: "generate" computes a Recess Academy tuition plan (nothing is
674
709
  stored): a 180-instructional-day term at --annual (tuition net of Recess aid) and
675
710
  a term through the state's typical school-year end. Each is paid in full upfront
@@ -682,15 +717,19 @@ has them (AZ). It returns the /admin/tuition-plans web URL (--open opens it)
682
717
  and, with --pdf, writes the letterhead PDF to that path. "states" lists the
683
718
  supported states and their year-end dates. --enrollment partner-school
684
719
  (with --partner-school, e.g. wonder-ed) names the partner as the school of record
685
- and says tuition payments go to it, on the tuition page and the signing page. Florida students enroll through a
686
- partner institution: a direct Florida plan is refused unless --force-direct. Add-on prices default to
720
+ and says tuition payments go to it, on the tuition page and the signing page. --enrollment program
721
+ is the online learning program (main or supplemental): the agreement says Recess is not the
722
+ school of record and satisfies no attendance or reporting requirement. Florida students enroll through a
723
+ partner institution or the program: a direct Florida plan is refused unless --force-direct. Add-on prices default to
687
724
  $160/month per extra elective and $400 per 4 tutoring sessions; --elective-price,
688
725
  --one-on-one-price, and --one-on-one-sessions override them on this sheet.
689
726
  --end YYYY-MM-DD adds a custom term through that date (priced by school days).
690
727
  --terms and --payments pick a subset of the matrix (default: every term ×
691
728
  upfront + installments). Full-year and custom terms may not end after July 1:
692
729
  a full year that would is left out of the default and refused if asked for.
693
- --note TEXT (repeatable) prints a note on the sheet. --bill-date (repeatable)
730
+ --amount N=DOLLARS (repeatable) sets installment N's amount; the installments must
731
+ still add up to the plan total, and it cannot combine with --even-installments or
732
+ --esa-award-unknown. --note TEXT (repeatable) prints a note on the sheet. --bill-date (repeatable)
694
733
  moves an invoice date: upfront=YYYY-MM-DD for pay in full, N=YYYY-MM-DD for
695
734
  installment N in every term; due dates follow and dates must stay in order.
696
735
  --even-installments splits each installment plan evenly in whole dollars (any
@@ -709,6 +748,34 @@ start too late for approval (~30 days) to land in its quarter bills that quarter
709
748
  now with no award; every other payment shows "up to" its no-award amount. The
710
749
  agreement adds a clause that the plan is re-issued once the award is confirmed.
711
750
 
751
+ Admissions notes: an admission packet is the one link a school family gets to go
752
+ from "yes" to enrolled: create account, sign the tuition plan (and the partner
753
+ school's agreement) in the dashboard, give parental consent, answer the
754
+ enrollment questions per child, and pay if a paywall is set. "create" takes the
755
+ family (--parent, --email, --state, one --kid per child), how they enroll
756
+ (--school is the SCHOOL institution slug as in "applications enroll";
757
+ --enrollment partner-school needs --partner-school), and the tuition plan as the
758
+ same flags "tuition-plans generate" takes (--annual, --start, --state-funding,
759
+ --esa-award-unknown, ...; --note prints on the plan, --staff-note stays on the
760
+ packet). The plan is built once on create, so a bad spec fails there. --paywall
761
+ DOLLARS adds a card step at the end for that family share; leave it off for
762
+ partner-school and ESA-funded families (the CLI warns). --no-email returns the
763
+ link without sending it. The envelope opens with the family's financial aid answers
764
+ for them to initial as true; they come from --financial-aid, else the application's
765
+ aid form, else the newest aid form under the parent's email ("none" leaves it out). "resend" mints a new link (the old one dies) and emails
766
+ it. "get" prints the agreed plan as signed (each child's option, term and every
767
+ installment) and whether the signed agreement is archived in our storage; the
768
+ copy is taken when the envelope completes, and "archive-agreement" retries it.
769
+ "requote" replaces the tuition plan on a packet that has not been paid (same
770
+ plan flags as create, or --keep-plan to reopen the payment choice on the plan
771
+ as it is; --paywall/--no-paywall changes the family share): the Documenso
772
+ envelope is cancelled, the family signs again from the same link, and their
773
+ account, consent and answers stand (a completed packet completes again on its
774
+ own); paid packets need a refund first and voided ones a new packet. "mark-signed" records a signature taken outside the dashboard (or local
775
+ testing without Documenso) so the parent can continue. Status moves on its own:
776
+ the Documenso webhook marks SIGNED, each parent step advances it, and a packet
777
+ with no paywall completes when the questions are in.
778
+
712
779
  Payout notes: amounts are integer cents. "payout items add" without --date
713
780
  defaults the item date to the penultimate day of the invoice's cycle (its
714
781
  endDate minus one day) and shows the computed date in the preview.
@@ -825,6 +892,7 @@ export const COMMAND_SUMMARIES = {
825
892
  "students todos": "List a student's todos for a date (or recent), with statuses.",
826
893
  "students analysis": "Read the learning analysis for a completed todo.",
827
894
  "students xp-history": "Show a kid's XP history over a range.",
895
+ "students math-academy": "Show a linked kid's Math Academy course, league and task activity.",
828
896
  "enrollments list": "List a user's enrollments.",
829
897
  "subscriptions list": "List a family's Stripe subscriptions.",
830
898
  "invoices list": "List a subscription's invoices.",
@@ -1066,6 +1134,7 @@ export const COMMAND_SUMMARIES = {
1066
1134
  "goals archive": "Archive a goal.",
1067
1135
  "goals unarchive": "Unarchive a goal.",
1068
1136
  "goals move-module": "Reorder a module in a goal's queue.",
1137
+ "goals launch-todo": "Create a goal module's todo now.",
1069
1138
  "goals queue get": "Read a goal's module queue.",
1070
1139
  "goals queue set": "Replace a goal's module queue from JSON.",
1071
1140
  "todos create": "Create a todo for a kid.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.11.0",
3
+ "version": "3.13.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -26,6 +26,8 @@ Load the audience skill's `SKILL.md`, then only the reference it routes you to:
26
26
  recess --json skills guardian get recess-family
27
27
  # Research, author, or apply a goal or reusable goal template
28
28
  recess --json skills guardian get recess-goal-authoring
29
+ # Guide (guide_students): your students, class ops, Math Academy linking and activity
30
+ recess --json skills guardian get recess-guide
29
31
  # Staff operations (full_admin), then the one playbook its table names
30
32
  recess --json skills admin get recess-admin
31
33
  recess --json skills admin get recess-admin --reference billing