recess-cli 3.19.0 → 3.19.2

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
@@ -7,6 +7,7 @@ import { CliError } from "./errors.js";
7
7
  export const REPEATABLE_FLAGS = new Set([
8
8
  "amount",
9
9
  "bill-date",
10
+ "due-date",
10
11
  "existing-kid",
11
12
  "kid",
12
13
  "staff-note",
package/dist/cli.js CHANGED
@@ -12,6 +12,7 @@ import { runApplicationsCommand } from "./commands/applications.js";
12
12
  import { runAppsCommand } from "./commands/apps.js";
13
13
  import { runChannelsCommand } from "./commands/channels.js";
14
14
  import { runChatLogsCommand } from "./commands/chat-logs.js";
15
+ import { runLibraryBooksCommand } from "./commands/library-books.js";
15
16
  import { runDbCommand } from "./commands/db.js";
16
17
  import { runRoomsCommand } from "./commands/rooms.js";
17
18
  import { runFeedCommand } from "./commands/feed.js";
@@ -1823,44 +1824,6 @@ function resolvedStudentDetails(student) {
1823
1824
  function goalTemplatePreviewUrl(webOrigin, templateId) {
1824
1825
  return new URL(`/challenges-v2/${encodeURIComponent(templateId)}`, webOrigin).toString();
1825
1826
  }
1826
- /**
1827
- * The classic-challenge fields passed as flags (`classic-create`/`-update`);
1828
- * only flags present land, so an update changes exactly what was sent. The
1829
- * server owns the real validation (`classic-challenge-source.ts`).
1830
- */
1831
- async function classicChallengeFlags(parsed) {
1832
- const instructionsFile = flagString(parsed, "instructions-file");
1833
- if (instructionsFile && flagString(parsed, "instructions") !== undefined) {
1834
- throw new CliError("invalid_arguments", "Pass --instructions or --instructions-file, not both.");
1835
- }
1836
- const instructions = instructionsFile
1837
- ? await fs.readFile(path.resolve(instructionsFile), "utf8")
1838
- : flagString(parsed, "instructions");
1839
- const integer = (flag, min, max) => {
1840
- const value = flagNumber(parsed, flag);
1841
- if (value !== undefined &&
1842
- (!Number.isInteger(value) || value < min || value > max)) {
1843
- throw new CliError("invalid_arguments", `--${flag} must be an integer from ${min} to ${max}.`);
1844
- }
1845
- return value;
1846
- };
1847
- const coinAmount = integer("coin-amount", 0, 1000);
1848
- const estimatedMinutes = integer("estimated-minutes", 5, 600);
1849
- const text = {
1850
- title: flagString(parsed, "title"),
1851
- description: flagString(parsed, "description"),
1852
- instructions,
1853
- submissionPrompt: flagString(parsed, "submission-prompt"),
1854
- gradeTag: flagString(parsed, "grade-tag"),
1855
- category: flagString(parsed, "category"),
1856
- imageUrl: flagString(parsed, "image-url"),
1857
- };
1858
- return {
1859
- ...Object.fromEntries(Object.entries(text).filter(([, value]) => value !== undefined)),
1860
- ...(coinAmount === undefined ? {} : { coinAmount }),
1861
- ...(estimatedMinutes === undefined ? {} : { estimatedMinutes }),
1862
- };
1863
- }
1864
1827
  /** Runs the template with Rocky as a kid would (staff only; ephemeral, never touches real todos). */
1865
1828
  function goalTemplatePlayTestUrl(webOrigin, templateId) {
1866
1829
  return new URL(`/challenges-v2/${encodeURIComponent(templateId)}?play=1`, webOrigin).toString();
@@ -4626,78 +4589,6 @@ export async function executeRecessCommand(argv, options = {}) {
4626
4589
  };
4627
4590
  });
4628
4591
  }
4629
- // Classic challenges: one photo-upload module a guide approves, authored
4630
- // from a few fields (`routes/ai/goal-templates/classic-routes.ts`).
4631
- if (verb === "classic-create") {
4632
- const fields = await classicChallengeFlags(parsed);
4633
- const { title, description, instructions, gradeTag, coinAmount } = fields;
4634
- if (!title ||
4635
- !description ||
4636
- !instructions ||
4637
- !gradeTag ||
4638
- coinAmount === undefined) {
4639
- throw new CliError("invalid_arguments", "classic-create needs --title, --description, --instructions (or --instructions-file), --grade-tag and --coin-amount.");
4640
- }
4641
- const body = {
4642
- ...fields,
4643
- title,
4644
- description,
4645
- instructions,
4646
- gradeTag,
4647
- coinAmount,
4648
- };
4649
- return writeCommand(parsed, {
4650
- action: "create a PRIVATE classic challenge (kid uploads photos; a guide approves from /challenges-v2/review)",
4651
- target: { title },
4652
- request: body,
4653
- details: {
4654
- note: "Starts PRIVATE. Card art is painted automatically when no --image-url is given. Publish with goal-templates set-metadata <id> --visibility PUBLIC once it looks right.",
4655
- },
4656
- }, async () => {
4657
- const created = unwrap(await api.client.POST("/ai/goal-templates/classic", { body }));
4658
- return {
4659
- ...created,
4660
- previewUrl: goalTemplatePreviewUrl(config.webOrigin, created.templateId),
4661
- };
4662
- });
4663
- }
4664
- if (verb === "classic-get" || verb === "classic-update") {
4665
- const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
4666
- const current = unwrap(await api.client.GET("/ai/goal-templates/{id}/classic", {
4667
- params: { path: { id } },
4668
- }));
4669
- if (verb === "classic-get") {
4670
- return {
4671
- ...current,
4672
- previewUrl: goalTemplatePreviewUrl(config.webOrigin, id),
4673
- };
4674
- }
4675
- const body = await classicChallengeFlags(parsed);
4676
- const changed = Object.keys(body);
4677
- if (changed.length === 0) {
4678
- throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --instructions/--instructions-file, --submission-prompt, --grade-tag, --coin-amount, --estimated-minutes, --category, --image-url).");
4679
- }
4680
- const before = {
4681
- ...current.source,
4682
- imageUrl: current.imageUrl,
4683
- };
4684
- return writeCommand(parsed, {
4685
- action: "edit a classic challenge (only the fields sent change; cuts a new version)",
4686
- target: {
4687
- templateId: id,
4688
- title: current.source.title,
4689
- version: current.version,
4690
- visibility: current.visibility,
4691
- },
4692
- request: body,
4693
- details: {
4694
- current: Object.fromEntries(changed.map((key) => [key, before[key] ?? null])),
4695
- },
4696
- }, async () => unwrap(await api.client.PUT("/ai/goal-templates/{id}/classic", {
4697
- params: { path: { id } },
4698
- body,
4699
- })));
4700
- }
4701
4592
  if (verb === "policy") {
4702
4593
  const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
4703
4594
  return unwrap(await api.client.GET("/ai/goal-templates/{id}/policy", {
@@ -5459,7 +5350,7 @@ export async function executeRecessCommand(argv, options = {}) {
5459
5350
  },
5460
5351
  })));
5461
5352
  }
5462
- throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|classic-create|classic-get|classic-update|patch-spec|set-metadata|generate-image|delete|snapshot-files|capture-snapshot|publish|answers-template|apply|apply-starter.");
5353
+ throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|generate-image|delete|snapshot-files|capture-snapshot|publish|answers-template|apply|apply-starter.");
5463
5354
  }
5464
5355
  if (noun === "goals" && (verb === "notes" || verb === "progress")) {
5465
5356
  const student = await studentFlag(api, parsed, { required: true });
@@ -6103,6 +5994,9 @@ export async function executeRecessCommand(argv, options = {}) {
6103
5994
  if (noun === "chat-logs") {
6104
5995
  return runChatLogsCommand({ parsed, api, writeCommand });
6105
5996
  }
5997
+ if (noun === "library-books") {
5998
+ return runLibraryBooksCommand({ parsed, api, writeCommand });
5999
+ }
6106
6000
  if (noun === "db") {
6107
6001
  return runDbCommand({ parsed, api, writeCommand });
6108
6002
  }
@@ -6834,6 +6728,9 @@ export async function executeRecessCommand(argv, options = {}) {
6834
6728
  : { kind: "draft", draftSlug: draftSlug };
6835
6729
  const message = flagString(parsed, "message") ??
6836
6730
  `recess-cli: attach textbook PDF ${fileName}`;
6731
+ const assignedEdits = hasFlag(parsed, "allow-assigned-edits")
6732
+ ? { allowAssignedEdits: true }
6733
+ : {};
6837
6734
  const placeholderManifest = JSON.stringify({
6838
6735
  kind: "pending-pdf-upload",
6839
6736
  fileName,
@@ -6841,6 +6738,7 @@ export async function executeRecessCommand(argv, options = {}) {
6841
6738
  sizeBytes: fileStat.size,
6842
6739
  });
6843
6740
  const body = {
6741
+ ...assignedEdits,
6844
6742
  studentUserId: studentId,
6845
6743
  target,
6846
6744
  message,
@@ -6862,6 +6760,7 @@ export async function executeRecessCommand(argv, options = {}) {
6862
6760
  action: "upload a textbook PDF and attach it to a student's goal",
6863
6761
  target: preflight.target,
6864
6762
  request: {
6763
+ ...assignedEdits,
6865
6764
  sourceFile: absolutePath,
6866
6765
  sourceSha256,
6867
6766
  sizeBytes: fileStat.size,
@@ -6870,6 +6769,7 @@ export async function executeRecessCommand(argv, options = {}) {
6870
6769
  },
6871
6770
  details: {
6872
6771
  ...resolvedStudentDetails(student),
6772
+ ...(preflight.warnings?.length ? { warnings: preflight.warnings } : {}),
6873
6773
  currentChangeId: preflight.currentChangeId,
6874
6774
  note: "The PDF is stored separately and the goal workspace receives a small verified reference, matching planner-authored textbook goals.",
6875
6775
  },
@@ -117,10 +117,6 @@ const FAMILY_AI_COMMANDS = new Set([
117
117
  "goal-templates apply",
118
118
  "goal-templates apply-starter",
119
119
  "goal-templates capture-snapshot",
120
- "goal-templates classic-create",
121
- // classic-get/-update: staff, or the author on their own PRIVATE draft.
122
- "goal-templates classic-get",
123
- "goal-templates classic-update",
124
120
  "goal-templates create",
125
121
  // set-metadata/delete/patch-spec: the server lets a non-staff author touch
126
122
  // only their own PRIVATE templates, plus unpublish (set-metadata
@@ -129,8 +125,9 @@ const FAMILY_AI_COMMANDS = new Set([
129
125
  "goal-templates get",
130
126
  "goal-templates list",
131
127
  "goal-templates patch-spec",
132
- // publish: the server allows staff or the author, and only while every kid
133
- // reading the course is one the caller manages.
128
+ // publish: the server allows staff or the author. A guardian or guide author
129
+ // reaches every kid on their own uncurated course; anyone else only while
130
+ // every kid reading it is one the caller manages.
134
131
  "goal-templates publish",
135
132
  "goal-templates set-metadata",
136
133
  "goal-templates snapshot-files",
@@ -157,6 +154,10 @@ const FAMILY_AI_COMMANDS = new Set([
157
154
  "goals queue get",
158
155
  "goals queue set",
159
156
  "goals unarchive",
157
+ "library-books add",
158
+ "library-books get",
159
+ "library-books list",
160
+ "library-books search",
160
161
  "memories context",
161
162
  "memories log",
162
163
  "onboarding pairing-code",
@@ -0,0 +1,105 @@
1
+ import { unwrap } from "../api.js";
2
+ import { flagNumber, flagString } from "../args.js";
3
+ import { CliError } from "../errors.js";
4
+ import { assertChoice, positional } from "./shared.js";
5
+ const MD5 = /^[0-9a-f]{32}$/i;
6
+ async function resolveAddBody({ parsed, api }) {
7
+ const fromSearch = flagNumber(parsed, "from-search");
8
+ if (fromSearch !== undefined) {
9
+ const conflicting = [
10
+ "md5",
11
+ "title",
12
+ "author",
13
+ "extension",
14
+ "cover-url",
15
+ ].filter((name) => parsed.flags.has(name));
16
+ if (conflicting.length > 0) {
17
+ throw new CliError("invalid_arguments", `--from-search cannot be combined with ${conflicting.map((name) => `--${name}`).join(", ")}.`);
18
+ }
19
+ if (!Number.isInteger(fromSearch) || fromSearch < 1) {
20
+ throw new CliError("invalid_arguments", "--from-search must be a 1-based result number from `library-books search`.");
21
+ }
22
+ const q = flagString(parsed, "query", { required: true });
23
+ const { web } = unwrap(await api.client.GET("/library-books/search", {
24
+ params: { query: { q } },
25
+ }));
26
+ const pick = web[fromSearch - 1];
27
+ if (!pick) {
28
+ throw new CliError("invalid_arguments", `Search for "${q}" returned ${web.length} web result(s); --from-search ${fromSearch} is out of range.`);
29
+ }
30
+ return {
31
+ body: {
32
+ md5: pick.md5,
33
+ title: pick.title,
34
+ author: pick.author,
35
+ extension: pick.extension,
36
+ coverUrl: pick.coverUrl,
37
+ },
38
+ alreadyInLibrary: pick.libraryBookId,
39
+ };
40
+ }
41
+ if (parsed.flags.has("query")) {
42
+ throw new CliError("invalid_arguments", "--query is only used with --from-search.");
43
+ }
44
+ const md5 = flagString(parsed, "md5", { required: true });
45
+ if (!MD5.test(md5)) {
46
+ throw new CliError("invalid_arguments", "--md5 must be 32 hex characters.");
47
+ }
48
+ const author = flagString(parsed, "author");
49
+ const coverUrl = flagString(parsed, "cover-url");
50
+ return {
51
+ body: {
52
+ md5: md5.toLowerCase(),
53
+ title: flagString(parsed, "title", { required: true }),
54
+ extension: assertChoice(flagString(parsed, "extension", { required: true }), ["pdf", "epub"], "--extension"),
55
+ ...(author === undefined ? {} : { author }),
56
+ ...(coverUrl === undefined ? {} : { coverUrl }),
57
+ },
58
+ alreadyInLibrary: null,
59
+ };
60
+ }
61
+ export async function runLibraryBooksCommand(context) {
62
+ const { parsed, api, writeCommand } = context;
63
+ const verb = parsed.positionals[1];
64
+ if (verb === "search") {
65
+ const q = positional(parsed, 2, "search query");
66
+ const result = unwrap(await api.client.GET("/library-books/search", {
67
+ params: { query: { q } },
68
+ }));
69
+ return {
70
+ ...result,
71
+ web: result.web.map((row, index) => ({ result: index + 1, ...row })),
72
+ };
73
+ }
74
+ if (verb === "list") {
75
+ const q = flagString(parsed, "q");
76
+ return unwrap(await api.client.GET("/library-books/", {
77
+ params: { query: q === undefined ? {} : { q } },
78
+ }));
79
+ }
80
+ if (verb === "get") {
81
+ const id = positional(parsed, 2, "library book ID");
82
+ const book = unwrap(await api.client.GET("/library-books/{id}", {
83
+ params: { path: { id } },
84
+ }));
85
+ const listed = unwrap(await api.client.GET("/library-books/", {
86
+ params: { query: { q: book.title.slice(0, 200) } },
87
+ }));
88
+ const challengeId = listed.items.find((item) => item.id === book.id)?.challengeId ?? null;
89
+ return { ...book, challengeId };
90
+ }
91
+ if (verb === "add") {
92
+ const { body, alreadyInLibrary } = await resolveAddBody(context);
93
+ return writeCommand(parsed, {
94
+ action: "add a book to the shared library from the web",
95
+ target: { md5: body.md5 },
96
+ request: body,
97
+ details: {
98
+ alreadyInLibrary,
99
+ consequence: "Creates a PROCESSING library book and queues download + processing; an md5 already in the library returns the existing book unchanged.",
100
+ },
101
+ }, async () => unwrap(await api.client.POST("/library-books/from-web", { body })));
102
+ }
103
+ throw new CliError("invalid_arguments", "Use library-books search|list|get|add.");
104
+ }
105
+ //# sourceMappingURL=library-books.js.map
package/dist/help.js CHANGED
@@ -451,15 +451,6 @@ Usage:
451
451
  recess [--json] goal-templates validate-spec --file <path/template.json>
452
452
  recess [--json] goal-templates create --file <path/template.json>
453
453
  [--coin-amount N] [--confirm]
454
- recess [--json] goal-templates classic-create --title TEXT --description TEXT
455
- (--instructions TEXT | --instructions-file <path.md>) --grade-tag "Grades 3-6"
456
- --coin-amount N [--submission-prompt TEXT] [--estimated-minutes N]
457
- [--category TEXT] [--image-url URL] [--confirm]
458
- recess [--json] goal-templates classic-get <template-id|slug>
459
- recess [--json] goal-templates classic-update <template-id|slug> [--title TEXT]
460
- [--description TEXT] [--instructions TEXT | --instructions-file <path.md>]
461
- [--grade-tag TEXT] [--coin-amount N] [--submission-prompt TEXT]
462
- [--estimated-minutes N] [--category TEXT] [--image-url URL] [--confirm]
463
454
  recess [--json] goal-templates patch-spec <template-id|slug> [--expected-version N]
464
455
  --patches-file <path/patches.json> [--confirm --approval-token TOKEN]
465
456
  [--confirm-destructive-changes --destructive-change-token TOKEN]
@@ -554,6 +545,12 @@ Usage:
554
545
  [--lessons-dir <dir>] [--emoji TEXT] [--grade-min N] [--grade-max N]
555
546
  [--visibility PUBLIC|STAFF] [--confirm]
556
547
  recess [--json] tutor-templates delete <slug> [--confirm]
548
+ recess [--json] library-books search <query>
549
+ recess [--json] library-books list [--q TEXT]
550
+ recess [--json] library-books get <book-id>
551
+ recess [--json] library-books add (--md5 <md5> --title TEXT [--author TEXT]
552
+ --extension pdf|epub [--cover-url <url>] | --from-search N --query TEXT)
553
+ [--confirm]
557
554
  recess [--json] goals notes list --student <goal-owner-id> --goal <goal-id>
558
555
  recess [--json] goals notes get --student <goal-owner-id> --goal <goal-id>
559
556
  [--lesson <item-key|module-ref>]
@@ -578,7 +575,7 @@ Usage:
578
575
  [--confirm --approval-token TOKEN]
579
576
  recess [--json] goals pdf upload --student <goal-owner-id>
580
577
  (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
581
- [--path uploads/name.pdf] [--message TEXT]
578
+ [--path uploads/name.pdf] [--message TEXT] [--allow-assigned-edits]
582
579
  [--confirm --approval-token TOKEN]
583
580
  recess [--json] goals video upload --source-file <local.mp4>
584
581
  [--confirm --approval-token TOKEN]
@@ -593,9 +590,10 @@ Shared courses: every kid on a template reads the course's latest published
593
590
  version, so "goal-templates publish" is the one way to change a lesson; it previews
594
591
  "affects N kids (M mid-lesson)". Per-kid tailoring is a note ("goals notes set"),
595
592
  never a lesson edit (a goal that owns its lessons takes "goals files push").
596
- Goal file writes/pushes warn and refuse curriculum edits with unfinished assignments
597
- unless --allow-assigned-edits is supplied. This can change lessons while a student
598
- is working; assignments are not retired/completed and student answers are not merged.
593
+ Goal file writes/pushes and PDF uploads warn and refuse curriculum edits with
594
+ unfinished assignments unless --allow-assigned-edits is supplied. This can change
595
+ lessons while a student is working; assignments are not retired/completed and
596
+ student answers are not merged.
599
597
  The flag requires a fresh preview and confirmation; revision checks still apply.
600
598
  Goal file writes/pushes require --allow-state-modification to modify state or
601
599
  student-work folders, or replace/delete an existing resources/artifacts file.
@@ -616,9 +614,6 @@ the backend's own dryRun before the gate and previews the per-student outcome.
616
614
  "set-metadata", "delete", "patch-spec" and "set-policy" take an optional
617
615
  --expected-version; omitted, the current version is read and pinned into the
618
616
  preview, so a change before confirm is refused. A stale one 409s STALE_WRITE.
619
- "classic-create" makes a single human-reviewed module (kid submits photos, a guide
620
- approves from /challenges-v2/review) from a few fields, as a PRIVATE draft; publish
621
- with "set-metadata <id> --visibility PUBLIC". Edit it with "classic-update", not patch-spec.
622
617
  --student on goal, todo, goal-file and template-apply commands takes an ID or an
623
618
  exact roster name. "answers-template" prints a fillable answers file for "apply". The spec is unreachable from "set-metadata"
624
619
  by design — an existing spec is edited only through the guarded /ai patch path.
@@ -1212,9 +1207,6 @@ export const COMMAND_SUMMARIES = {
1212
1207
  "goal-templates versions": "List a template's version history.",
1213
1208
  "goal-templates validate-spec": "Validate a template file (no write).",
1214
1209
  "goal-templates create": "Create a goal template from a file.",
1215
- "goal-templates classic-create": "Create a classic challenge: kid uploads photos, a guide approves (starts PRIVATE).",
1216
- "goal-templates classic-get": "Read a classic challenge's editable fields.",
1217
- "goal-templates classic-update": "Edit a classic challenge's fields (only those passed change).",
1218
1210
  "goal-templates patch-spec": "Patch a template's setup-workflow spec (own PRIVATE ones for guardians).",
1219
1211
  "goal-templates set-metadata": "Edit a template's title, art, tags, visibility (own PRIVATE ones for guardians, who may also unpublish their own: --visibility PRIVATE alone).",
1220
1212
  "goal-templates delete": "Delete a goal template (own PRIVATE ones for guardians).",
@@ -1263,6 +1255,10 @@ export const COMMAND_SUMMARIES = {
1263
1255
  "tutor-templates create": "Create a tutor template.",
1264
1256
  "tutor-templates update": "Update a tutor template.",
1265
1257
  "tutor-templates delete": "Delete a tutor template.",
1258
+ "library-books search": "Search the book library and the web for books.",
1259
+ "library-books list": "List books in the shared library.",
1260
+ "library-books get": "Read one library book: status, pages, chapters.",
1261
+ "library-books add": "Add a web search result to the book library.",
1266
1262
  "goals notes list": "List Rocky's per-kid notes on a goal.",
1267
1263
  "goals notes get": "Read the goal's or one lesson's note.",
1268
1264
  "goals notes set": "Write Rocky's note for this kid on a lesson (never the lesson itself).",
@@ -1317,6 +1313,7 @@ export const NOUN_SUMMARIES = {
1317
1313
  memories: "Kid memory files and the context Rocky sees.",
1318
1314
  rocky: "A kid's Rocky personality settings.",
1319
1315
  "tutor-templates": "Tutor templates and their assignment to kids.",
1316
+ "library-books": "Book library: search the web, add books, read status.",
1320
1317
  mastery: "Mastery graphs and the content linked to them.",
1321
1318
  };
1322
1319
  //# sourceMappingURL=help.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.19.0",
3
+ "version": "3.19.2",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {