recess-cli 3.9.0 → 3.11.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/api.js +4 -0
- package/dist/args.js +42 -10
- package/dist/cli.js +857 -131
- package/dist/command-schema.js +361 -109
- package/dist/commands/applications.js +10 -4
- package/dist/commands/channels.js +21 -1
- package/dist/commands/feed.js +82 -0
- package/dist/commands/onboarding.js +6 -4
- package/dist/commands/safe-staff-operations.js +3 -2
- package/dist/commands/tuition-plans.js +43 -7
- package/dist/goal-authoring.js +774 -0
- package/dist/help.js +474 -38
- package/dist/index.js +17 -3
- package/dist/safety.js +20 -1
- package/dist/ui/app.js +1 -1
- package/package.json +3 -3
- package/skill/recess-cli/SKILL.md +56 -121
- package/skill/recess-cli/agents/version.json +2 -2
|
@@ -0,0 +1,774 @@
|
|
|
1
|
+
import { unwrap } from "./api.js";
|
|
2
|
+
import { CliError } from "./errors.js";
|
|
3
|
+
// ---------------------------------------------------------------------------
|
|
4
|
+
// Scaffold
|
|
5
|
+
// ---------------------------------------------------------------------------
|
|
6
|
+
/** Marks scaffold prose so the local validator can say which files are still unwritten. */
|
|
7
|
+
export const SCAFFOLD_MARKER = "<!-- recess-scaffold: rewrite this file -->";
|
|
8
|
+
const SCAFFOLD_MODULE_PREFIX = "W1-M";
|
|
9
|
+
function humanize(slug) {
|
|
10
|
+
const words = slug.replace(/[-_]+/g, " ").trim();
|
|
11
|
+
return words ? words[0].toUpperCase() + words.slice(1) : "Learning path";
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
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
|
|
17
|
+
* (summary, estimated time, the five required `##` sections). Every prose file
|
|
18
|
+
* carries `SCAFFOLD_MARKER` so a push reports what is still generic.
|
|
19
|
+
*/
|
|
20
|
+
export function buildGoalWorkspaceScaffold(input) {
|
|
21
|
+
const title = input.title?.trim() || humanize(input.draftSlug);
|
|
22
|
+
const modules = Array.from({ length: input.moduleCount }, (_, index) => ({
|
|
23
|
+
ref: `${SCAFFOLD_MODULE_PREFIX}${index + 1}`,
|
|
24
|
+
path: `modules/${SCAFFOLD_MODULE_PREFIX}${index + 1}-module-${index + 1}.md`,
|
|
25
|
+
title: `Module ${index + 1}`,
|
|
26
|
+
}));
|
|
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
|
+
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
|
+
{
|
|
48
|
+
path: "AGENTS.md",
|
|
49
|
+
content: md(`# Tutor Agent Instructions
|
|
50
|
+
|
|
51
|
+
You are Rocky, running **${title}** with one student.
|
|
52
|
+
|
|
53
|
+
## Tutoring style
|
|
54
|
+
|
|
55
|
+
- Ask one focused question at a time; the student does the thinking.
|
|
56
|
+
- Look at real work before judging anything.
|
|
57
|
+
- When the student is stuck, drop one level: a smaller step or a worked half-example.
|
|
58
|
+
|
|
59
|
+
## Coaching rules for this path
|
|
60
|
+
|
|
61
|
+
- Write the runtime rules Rocky must follow in every session here.
|
|
62
|
+
|
|
63
|
+
## File discipline
|
|
64
|
+
|
|
65
|
+
- Keep durable progress in \`state/progress.json\`.
|
|
66
|
+
- 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
|
+
},
|
|
84
|
+
{
|
|
85
|
+
path: "first-message.md",
|
|
86
|
+
content: md(`# First Message
|
|
87
|
+
|
|
88
|
+
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
|
+
},
|
|
139
|
+
{
|
|
140
|
+
path: "state/progress.json",
|
|
141
|
+
content: `${JSON.stringify({
|
|
142
|
+
currentModuleRef: modules[0].ref,
|
|
143
|
+
completedModuleRefs: [],
|
|
144
|
+
course_status: "ready",
|
|
145
|
+
lastTutorSummary: null,
|
|
146
|
+
}, null, 2)}\n`,
|
|
147
|
+
},
|
|
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
|
+
...modules.map((module, index) => ({
|
|
177
|
+
path: module.path,
|
|
178
|
+
content: md(`# Module ${module.ref}: ${module.title}
|
|
179
|
+
|
|
180
|
+
Summary: One sentence on what the student makes or masters in this module.
|
|
181
|
+
Estimated time: 30 minutes
|
|
182
|
+
|
|
183
|
+
## Student-facing launch
|
|
184
|
+
|
|
185
|
+
Where to start: name the exact page, app, file, or tab Rocky opens first, then the first three moves in order. Offer choices as spoken either/or questions.
|
|
186
|
+
|
|
187
|
+
## Learning targets
|
|
188
|
+
|
|
189
|
+
- The skill this module builds, stated as something the student can do.
|
|
190
|
+
|
|
191
|
+
## Tutor guidance
|
|
192
|
+
|
|
193
|
+
- How Rocky runs this module, what to watch for, and how to respond when the student stalls or rushes.
|
|
194
|
+
|
|
195
|
+
## Resources and surfaces
|
|
196
|
+
|
|
197
|
+
- The exact links, apps, or workspace files this module uses.
|
|
198
|
+
|
|
199
|
+
## Completion criteria
|
|
200
|
+
|
|
201
|
+
- The visible work that proves the learning target${index === modules.length - 1 ? " and finishes the path" : ""}.
|
|
202
|
+
|
|
203
|
+
## State updates
|
|
204
|
+
|
|
205
|
+
- Keep the current step in \`state/progress.json\` current; \`complete_module\` records the completion.`),
|
|
206
|
+
})),
|
|
207
|
+
];
|
|
208
|
+
}
|
|
209
|
+
// ---------------------------------------------------------------------------
|
|
210
|
+
// Local workspace validation (mirror of goal-builder-workspace-validation.ts)
|
|
211
|
+
// ---------------------------------------------------------------------------
|
|
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
|
+
];
|
|
232
|
+
const READY_MODULE_REQUIREMENTS = [
|
|
233
|
+
{ label: "learning target", patterns: [/^Learning targets?\b/i] },
|
|
234
|
+
{
|
|
235
|
+
label: "tutor guidance or activity plan",
|
|
236
|
+
patterns: [
|
|
237
|
+
/^Tutor guidance\b/i,
|
|
238
|
+
/^Activity recipe\b/i,
|
|
239
|
+
/^Beat structure\b/i,
|
|
240
|
+
/^Sittings?\b/i,
|
|
241
|
+
/^Sitting plan\b/i,
|
|
242
|
+
],
|
|
243
|
+
},
|
|
244
|
+
{
|
|
245
|
+
label: "resources and surfaces",
|
|
246
|
+
patterns: [/^Resources(?: and surfaces)?\b/i],
|
|
247
|
+
},
|
|
248
|
+
{ label: "completion criteria", patterns: [/^Completion criteria\b/i] },
|
|
249
|
+
{ label: "state updates", patterns: [/^State updates\b/i] },
|
|
250
|
+
];
|
|
251
|
+
const SIMPLE_DAILY_TODO_GOAL_MODES = new Set([
|
|
252
|
+
"simple_daily_todos",
|
|
253
|
+
"legacy_daily_todos",
|
|
254
|
+
"simple_todo_goal",
|
|
255
|
+
]);
|
|
256
|
+
/** `goal-module-sync.ts` `moduleRefFromPath`: `W2-M1-basic-physics.md` → `W2-M1`. */
|
|
257
|
+
export function moduleRefFromPath(workspacePath) {
|
|
258
|
+
const fileName = workspacePath.split("/").pop() ?? workspacePath;
|
|
259
|
+
const match = fileName.match(/^([A-Za-z]\d+-[A-Za-z]\d+|[A-Za-z]\d+|\d{2,4})[-_. ]/);
|
|
260
|
+
return match?.[1]?.toUpperCase() ?? null;
|
|
261
|
+
}
|
|
262
|
+
/** Prose lines: HTML comments and fenced code removed (approximation of `readModuleMarkdown`). */
|
|
263
|
+
function liveLines(content) {
|
|
264
|
+
const withoutComments = content.replace(/<!--[\s\S]*?-->/g, "");
|
|
265
|
+
const lines = [];
|
|
266
|
+
let fence = null;
|
|
267
|
+
for (const line of withoutComments.split(/\r?\n/)) {
|
|
268
|
+
const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/)?.[1];
|
|
269
|
+
if (marker) {
|
|
270
|
+
if (!fence)
|
|
271
|
+
fence = marker[0];
|
|
272
|
+
else if (marker[0] === fence)
|
|
273
|
+
fence = null;
|
|
274
|
+
continue;
|
|
275
|
+
}
|
|
276
|
+
if (!fence)
|
|
277
|
+
lines.push(line);
|
|
278
|
+
}
|
|
279
|
+
return lines;
|
|
280
|
+
}
|
|
281
|
+
function headerLinePattern(label) {
|
|
282
|
+
const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
283
|
+
return new RegExp(`^(\\s*(?:[-*>]\\s+)*(#{1,6}\\s+)?(?:\\*\\*|__)?${escaped}(?:\\s*\\([^)]*\\))?\\s*(?::\\s*(?:\\*\\*|__)|(?:\\*\\*|__)\\s*:|:)\\s*)(.*?)\\s*$`, "i");
|
|
284
|
+
}
|
|
285
|
+
function headerField(lines, label) {
|
|
286
|
+
const pattern = headerLinePattern(label);
|
|
287
|
+
for (const line of lines) {
|
|
288
|
+
const match = line.match(pattern);
|
|
289
|
+
if (!match)
|
|
290
|
+
continue;
|
|
291
|
+
const raw = (match[2] ? match[3].replace(/\s+#+$/, "") : match[3])
|
|
292
|
+
.replace(/\s+/g, " ")
|
|
293
|
+
.trim();
|
|
294
|
+
if (!raw || /<[^<>\n]*>/.test(raw))
|
|
295
|
+
continue;
|
|
296
|
+
const value = raw.replace(/^`([^`]+)`$/, "$1").trim();
|
|
297
|
+
if (value)
|
|
298
|
+
return value;
|
|
299
|
+
}
|
|
300
|
+
return null;
|
|
301
|
+
}
|
|
302
|
+
function populatedSections(lines) {
|
|
303
|
+
const sections = [];
|
|
304
|
+
let current = null;
|
|
305
|
+
for (const line of lines) {
|
|
306
|
+
const heading = line.match(/^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/);
|
|
307
|
+
if (heading) {
|
|
308
|
+
const depth = heading[1].length;
|
|
309
|
+
if (depth <= 2) {
|
|
310
|
+
current = depth === 2 ? { text: heading[2], body: [] } : null;
|
|
311
|
+
if (current)
|
|
312
|
+
sections.push(current);
|
|
313
|
+
}
|
|
314
|
+
continue;
|
|
315
|
+
}
|
|
316
|
+
current?.body.push(line);
|
|
317
|
+
}
|
|
318
|
+
return sections
|
|
319
|
+
.filter((section) => section.body.some((line) => /\S/.test(line)))
|
|
320
|
+
.map((section) => section.text);
|
|
321
|
+
}
|
|
322
|
+
function moduleContentErrors(path, content) {
|
|
323
|
+
if (!content.trim())
|
|
324
|
+
return [`${path} is empty`];
|
|
325
|
+
const lines = liveLines(content);
|
|
326
|
+
const status = headerField(lines, "Materialization status") ??
|
|
327
|
+
headerField(lines, "Module status");
|
|
328
|
+
if (status && /^(planned-stub|planned|stub)$/i.test(status)) {
|
|
329
|
+
const missing = [];
|
|
330
|
+
const legacy = headerField(lines, "PDF/source");
|
|
331
|
+
if (!headerField(lines, "Mode"))
|
|
332
|
+
missing.push("Mode");
|
|
333
|
+
if (!headerField(lines, "Source PDF") && !legacy)
|
|
334
|
+
missing.push("Source PDF or PDF/source");
|
|
335
|
+
if (!headerField(lines, "Source pages") && !legacy)
|
|
336
|
+
missing.push("Source pages or PDF/source page range");
|
|
337
|
+
return missing.length
|
|
338
|
+
? [
|
|
339
|
+
`${path} is a planned curriculum stub but is missing ${missing.join(", ")}`,
|
|
340
|
+
]
|
|
341
|
+
: [];
|
|
342
|
+
}
|
|
343
|
+
const sections = populatedSections(lines);
|
|
344
|
+
const has = (patterns) => sections.some((text) => patterns.some((pattern) => pattern.test(text)));
|
|
345
|
+
const missing = [];
|
|
346
|
+
if (!headerField(lines, "Summary") && !has([/^Summary\b/i]))
|
|
347
|
+
missing.push("summary");
|
|
348
|
+
if (!(Number(headerField(lines, "Estimated time")?.match(/^\d+/)?.[0]) > 0))
|
|
349
|
+
missing.push("estimated time (`Estimated time: 30 minutes`)");
|
|
350
|
+
for (const requirement of READY_MODULE_REQUIREMENTS) {
|
|
351
|
+
if (!has(requirement.patterns))
|
|
352
|
+
missing.push(requirement.label);
|
|
353
|
+
}
|
|
354
|
+
const errors = missing.length
|
|
355
|
+
? [
|
|
356
|
+
`${path} is not a complete runtime module; missing ${missing.join(", ")}. Required: a Summary line or ## Summary, an Estimated time line, and populated ## Learning targets, ## Tutor guidance, ## Resources and surfaces, ## Completion criteria, ## State updates.`,
|
|
357
|
+
]
|
|
358
|
+
: [];
|
|
359
|
+
const itemKey = headerField(lines, "Item key");
|
|
360
|
+
if (itemKey && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(itemKey)) {
|
|
361
|
+
errors.push(`Invalid lesson Item key in ${path}`);
|
|
362
|
+
}
|
|
363
|
+
return errors;
|
|
364
|
+
}
|
|
365
|
+
function hasUnresolvedPlaceholder(path, content) {
|
|
366
|
+
const lines = path.endsWith(".md")
|
|
367
|
+
? liveLines(content).map((line) => line.replace(/`[^`]*`/g, ""))
|
|
368
|
+
: content.split(/\r?\n/);
|
|
369
|
+
return lines.some((line) => {
|
|
370
|
+
if (!/\{\{\s*[^{}\n]+\s*\}\}/.test(line))
|
|
371
|
+
return false;
|
|
372
|
+
const prose = line.replace(/\{\{\s*[^{}\n]+\s*\}\}/g, " ").toLowerCase();
|
|
373
|
+
return !/\b(example|syntax|literal|placeholder|template|token|mustache)\b/.test(prose);
|
|
374
|
+
});
|
|
375
|
+
}
|
|
376
|
+
const TEXT_EXTENSIONS = /\.(md|markdown|txt|json|html?|css|js|mjs|ts|csv|ya?ml|svg)$/i;
|
|
377
|
+
/**
|
|
378
|
+
* Mirrors the server's file, section, module and progress rules. File
|
|
379
|
+
* reference closure is not mirrored; the server checks it at create/capture.
|
|
380
|
+
*/
|
|
381
|
+
export function validateGoalWorkspaceLocally(files) {
|
|
382
|
+
const errors = [];
|
|
383
|
+
const warnings = [];
|
|
384
|
+
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
|
+
]) {
|
|
389
|
+
const file = byPath.get(required);
|
|
390
|
+
if (!file)
|
|
391
|
+
errors.push(`Missing required file: ${required}`);
|
|
392
|
+
else if (!file.content.trim())
|
|
393
|
+
errors.push(`Required file is empty: ${required}`);
|
|
394
|
+
}
|
|
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
|
+
const moduleRefs = new Map();
|
|
401
|
+
for (const file of files) {
|
|
402
|
+
if (!file.path.startsWith("modules/") || !file.path.endsWith(".md"))
|
|
403
|
+
continue;
|
|
404
|
+
const ref = moduleRefFromPath(file.path);
|
|
405
|
+
if (!ref) {
|
|
406
|
+
warnings.push(`${file.path} is not a module: its name does not start with a module ref (e.g. W1-M1-topic.md, M3-topic.md, 04-topic.md), so it will be silently ignored`);
|
|
407
|
+
continue;
|
|
408
|
+
}
|
|
409
|
+
moduleRefs.set(ref, [...(moduleRefs.get(ref) ?? []), file.path]);
|
|
410
|
+
errors.push(...moduleContentErrors(file.path, file.content));
|
|
411
|
+
}
|
|
412
|
+
for (const [ref, paths] of moduleRefs) {
|
|
413
|
+
if (paths.length > 1)
|
|
414
|
+
errors.push(`${paths.join(" and ")} both parse as module ${ref}; one would overwrite the other`);
|
|
415
|
+
}
|
|
416
|
+
let progress = null;
|
|
417
|
+
const progressFile = byPath.get("state/progress.json");
|
|
418
|
+
if (progressFile) {
|
|
419
|
+
try {
|
|
420
|
+
const parsed = JSON.parse(progressFile.content);
|
|
421
|
+
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
|
|
422
|
+
progress = parsed;
|
|
423
|
+
}
|
|
424
|
+
else {
|
|
425
|
+
errors.push("state/progress.json must contain a JSON object");
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
catch (error) {
|
|
429
|
+
errors.push(`state/progress.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
const mode = progress?.goalMode ?? progress?.goal_mode ?? progress?.mode;
|
|
433
|
+
const simpleDaily = typeof mode === "string" &&
|
|
434
|
+
SIMPLE_DAILY_TODO_GOAL_MODES.has(mode.trim().toLowerCase());
|
|
435
|
+
const rawCurrent = progress?.currentModuleRef ?? progress?.current_module;
|
|
436
|
+
const currentRef = typeof rawCurrent === "string" && rawCurrent.trim()
|
|
437
|
+
? rawCurrent.trim().toUpperCase()
|
|
438
|
+
: null;
|
|
439
|
+
if (moduleRefs.size === 0) {
|
|
440
|
+
if (simpleDaily)
|
|
441
|
+
warnings.push("Simple daily todo workspace has no parseable modules; it will not create launch todos");
|
|
442
|
+
else
|
|
443
|
+
errors.push("Workspace must include at least one parseable modules/*.md file");
|
|
444
|
+
}
|
|
445
|
+
else if (progress) {
|
|
446
|
+
if (!currentRef)
|
|
447
|
+
warnings.push("state/progress.json has no currentModuleRef or current_module");
|
|
448
|
+
else if (!moduleRefs.has(currentRef))
|
|
449
|
+
errors.push(`state/progress.json current module ${currentRef} does not match a module file`);
|
|
450
|
+
}
|
|
451
|
+
const buildReport = byPath.get("build-report.md")?.content;
|
|
452
|
+
if (buildReport &&
|
|
453
|
+
!/\b(validation|self-coherence|checks?)\b/i.test(buildReport))
|
|
454
|
+
warnings.push("build-report.md does not clearly describe validation checks performed");
|
|
455
|
+
const scaffolded = [];
|
|
456
|
+
for (const file of files) {
|
|
457
|
+
if (!TEXT_EXTENSIONS.test(file.path))
|
|
458
|
+
continue;
|
|
459
|
+
if (hasUnresolvedPlaceholder(file.path, file.content))
|
|
460
|
+
errors.push(`Unresolved placeholder marker in ${file.path}`);
|
|
461
|
+
if (file.content.includes(SCAFFOLD_MARKER))
|
|
462
|
+
scaffolded.push(file.path);
|
|
463
|
+
}
|
|
464
|
+
if (scaffolded.length > 0)
|
|
465
|
+
warnings.push(`${scaffolded.length} file(s) still carry scaffold text (remove the recess-scaffold marker once rewritten): ${scaffolded.join(", ")}`);
|
|
466
|
+
return {
|
|
467
|
+
source: "local",
|
|
468
|
+
ok: errors.length === 0,
|
|
469
|
+
errors,
|
|
470
|
+
warnings,
|
|
471
|
+
note: "Local check of required files, module sections, module filenames, and progress state. The server also checks file references when the draft is created or captured.",
|
|
472
|
+
};
|
|
473
|
+
}
|
|
474
|
+
/**
|
|
475
|
+
* Reads the server's draft `validation` (`{ok, baseChangeId, fileCount,
|
|
476
|
+
* errors, warnings, issues}`) from a workspace-files dry run, write, or init.
|
|
477
|
+
*/
|
|
478
|
+
export function serverWorkspaceValidation(response) {
|
|
479
|
+
const validation = response && typeof response === "object"
|
|
480
|
+
? response.validation
|
|
481
|
+
: undefined;
|
|
482
|
+
if (!validation || typeof validation !== "object")
|
|
483
|
+
return null;
|
|
484
|
+
const value = validation;
|
|
485
|
+
const list = (raw) => Array.isArray(raw)
|
|
486
|
+
? raw.map((entry) => typeof entry === "string" ? entry : JSON.stringify(entry))
|
|
487
|
+
: [];
|
|
488
|
+
const errors = list(value.errors);
|
|
489
|
+
const issues = Array.isArray(value.issues)
|
|
490
|
+
? value.issues.flatMap((entry) => {
|
|
491
|
+
if (!entry || typeof entry !== "object")
|
|
492
|
+
return [];
|
|
493
|
+
const issue = entry;
|
|
494
|
+
if (typeof issue.message !== "string")
|
|
495
|
+
return [];
|
|
496
|
+
return [
|
|
497
|
+
{
|
|
498
|
+
path: typeof issue.path === "string" ? issue.path : null,
|
|
499
|
+
rule: typeof issue.rule === "string" ? issue.rule : "unknown",
|
|
500
|
+
message: issue.message,
|
|
501
|
+
fix: typeof issue.fix === "string" ? issue.fix : null,
|
|
502
|
+
},
|
|
503
|
+
];
|
|
504
|
+
})
|
|
505
|
+
: undefined;
|
|
506
|
+
return {
|
|
507
|
+
source: "server",
|
|
508
|
+
ok: typeof value.ok === "boolean" ? value.ok : errors.length === 0,
|
|
509
|
+
errors,
|
|
510
|
+
warnings: list(value.warnings),
|
|
511
|
+
...(issues ? { issues } : {}),
|
|
512
|
+
...(typeof value.baseChangeId === "string"
|
|
513
|
+
? { baseChangeId: value.baseChangeId }
|
|
514
|
+
: {}),
|
|
515
|
+
...(typeof value.fileCount === "number"
|
|
516
|
+
? { fileCount: value.fileCount }
|
|
517
|
+
: {}),
|
|
518
|
+
};
|
|
519
|
+
}
|
|
520
|
+
// ---------------------------------------------------------------------------
|
|
521
|
+
// validate-spec error formatting
|
|
522
|
+
// ---------------------------------------------------------------------------
|
|
523
|
+
function issuePath(prefix, path) {
|
|
524
|
+
const parts = Array.isArray(path) ? path : [];
|
|
525
|
+
return parts.reduce((joined, part) => typeof part === "number"
|
|
526
|
+
? `${joined}[${part}]`
|
|
527
|
+
: `${joined}.${String(part)}`, prefix);
|
|
528
|
+
}
|
|
529
|
+
/**
|
|
530
|
+
* Turns a validate-spec failure into `path: message` lines. Reads a structured
|
|
531
|
+
* `errors`/`issues` array when the server sends one, and otherwise unpacks the
|
|
532
|
+
* Zod issue JSON embedded in the legacy `error` string.
|
|
533
|
+
*/
|
|
534
|
+
export function specValidationErrorLines(validation) {
|
|
535
|
+
if (!validation || typeof validation !== "object")
|
|
536
|
+
return [];
|
|
537
|
+
const value = validation;
|
|
538
|
+
const structured = Array.isArray(value.errors)
|
|
539
|
+
? value.errors
|
|
540
|
+
: Array.isArray(value.issues)
|
|
541
|
+
? value.issues
|
|
542
|
+
: null;
|
|
543
|
+
if (structured) {
|
|
544
|
+
return structured.map((entry) => {
|
|
545
|
+
if (typeof entry === "string")
|
|
546
|
+
return entry;
|
|
547
|
+
const issue = entry;
|
|
548
|
+
const where = typeof issue.path === "string"
|
|
549
|
+
? issue.path
|
|
550
|
+
: issuePath("", issue.path).replace(/^\./, "");
|
|
551
|
+
const message = typeof issue.message === "string" ? issue.message : "invalid";
|
|
552
|
+
return `${where || "(document)"}: ${message}`;
|
|
553
|
+
});
|
|
554
|
+
}
|
|
555
|
+
const error = typeof value.error === "string" ? value.error : null;
|
|
556
|
+
if (!error)
|
|
557
|
+
return [];
|
|
558
|
+
const start = error.indexOf("[");
|
|
559
|
+
if (start !== -1) {
|
|
560
|
+
try {
|
|
561
|
+
const issues = JSON.parse(error.slice(start));
|
|
562
|
+
if (Array.isArray(issues)) {
|
|
563
|
+
return issues.flatMap((issue) => {
|
|
564
|
+
const nested = issue.unionErrors?.flatMap((union) => union.issues ?? []);
|
|
565
|
+
const leaves = nested && nested.length > 0 ? nested : [issue];
|
|
566
|
+
return leaves.map((leaf) => `${issuePath("setupWorkflowSpec", leaf.path)}: ${leaf.message ?? "invalid"}`);
|
|
567
|
+
});
|
|
568
|
+
}
|
|
569
|
+
}
|
|
570
|
+
catch {
|
|
571
|
+
// Not Zod JSON; fall through to the message itself.
|
|
572
|
+
}
|
|
573
|
+
}
|
|
574
|
+
return [`setupWorkflowSpec: ${error}`];
|
|
575
|
+
}
|
|
576
|
+
function specSteps(spec) {
|
|
577
|
+
const steps = spec?.steps;
|
|
578
|
+
return Array.isArray(steps)
|
|
579
|
+
? steps.filter((step) => step &&
|
|
580
|
+
typeof step === "object" &&
|
|
581
|
+
typeof step.key === "string" &&
|
|
582
|
+
typeof step.kind === "string")
|
|
583
|
+
: [];
|
|
584
|
+
}
|
|
585
|
+
/** `subjectMatrixOptions`: skill-queue subjects or bundle recipes. */
|
|
586
|
+
function subjectKeys(spec) {
|
|
587
|
+
const handler = spec
|
|
588
|
+
?.handler;
|
|
589
|
+
const config = (handler?.config ?? {});
|
|
590
|
+
const entries = handler?.type === "EXTERNAL_SKILL_QUEUE_SETUP"
|
|
591
|
+
? config.subjects
|
|
592
|
+
: handler?.type === "GOAL_BUNDLE_SETUP"
|
|
593
|
+
? config.recipes
|
|
594
|
+
: undefined;
|
|
595
|
+
return (entries ?? [])
|
|
596
|
+
.map((entry) => entry.key)
|
|
597
|
+
.filter((key) => typeof key === "string");
|
|
598
|
+
}
|
|
599
|
+
export const STUDENT_PLACEHOLDER = "<kid-id>";
|
|
600
|
+
/**
|
|
601
|
+
* The answers JSON `apply-workflow` validates against `buildAnswersSchema`:
|
|
602
|
+
* `{ <student step>: [kidId], <select>: "value", <subject_matrix>: { kidId: [subjectKey] } }`.
|
|
603
|
+
* Required steps get a default or the first option; `placeholders` lists every
|
|
604
|
+
* value an author must still choose.
|
|
605
|
+
*/
|
|
606
|
+
export function buildAnswersTemplate(spec, studentIds) {
|
|
607
|
+
const students = studentIds.length > 0 ? studentIds : [STUDENT_PLACEHOLDER];
|
|
608
|
+
const keys = subjectKeys(spec);
|
|
609
|
+
const answers = {};
|
|
610
|
+
const placeholders = [];
|
|
611
|
+
const steps = [];
|
|
612
|
+
for (const step of specSteps(spec)) {
|
|
613
|
+
const required = step.required !== false;
|
|
614
|
+
const options = (step.options ?? []).map((option) => option.value);
|
|
615
|
+
steps.push({
|
|
616
|
+
key: step.key,
|
|
617
|
+
kind: step.kind,
|
|
618
|
+
label: step.label ?? null,
|
|
619
|
+
required,
|
|
620
|
+
...(step.availableWhen ? { availableWhen: step.availableWhen } : {}),
|
|
621
|
+
...(options.length ? { options } : {}),
|
|
622
|
+
...(step.kind === "subject_matrix" && keys.length
|
|
623
|
+
? { subjectKeys: keys }
|
|
624
|
+
: {}),
|
|
625
|
+
...(step.kind === "choice" && step.multi ? { multi: true } : {}),
|
|
626
|
+
...(step.kind === "number"
|
|
627
|
+
? { min: step.min ?? null, max: step.max ?? null }
|
|
628
|
+
: {}),
|
|
629
|
+
});
|
|
630
|
+
// Conditional steps depend on other answers; they are listed, not filled.
|
|
631
|
+
if (step.availableWhen)
|
|
632
|
+
continue;
|
|
633
|
+
let value;
|
|
634
|
+
switch (step.kind) {
|
|
635
|
+
case "student_multi_select":
|
|
636
|
+
value = students;
|
|
637
|
+
if (studentIds.length === 0)
|
|
638
|
+
placeholders.push(step.key);
|
|
639
|
+
break;
|
|
640
|
+
case "grade_select":
|
|
641
|
+
case "state_select":
|
|
642
|
+
case "schedule":
|
|
643
|
+
value = step.defaultValue ?? options[0];
|
|
644
|
+
if (step.defaultValue === undefined)
|
|
645
|
+
placeholders.push(step.key);
|
|
646
|
+
break;
|
|
647
|
+
case "choice":
|
|
648
|
+
value = step.multi ? options.slice(0, 1) : options[0];
|
|
649
|
+
placeholders.push(step.key);
|
|
650
|
+
break;
|
|
651
|
+
case "subject_matrix":
|
|
652
|
+
value = Object.fromEntries(students.map((student) => [student, keys.slice(0, 1)]));
|
|
653
|
+
placeholders.push(step.key);
|
|
654
|
+
break;
|
|
655
|
+
case "number":
|
|
656
|
+
value = step.policyField
|
|
657
|
+
? { mode: "inherit" }
|
|
658
|
+
: (step.defaultValue ?? step.min ?? 1);
|
|
659
|
+
if (!step.policyField && step.defaultValue === undefined)
|
|
660
|
+
placeholders.push(step.key);
|
|
661
|
+
break;
|
|
662
|
+
case "boolean":
|
|
663
|
+
value = step.defaultValue ?? false;
|
|
664
|
+
if (step.defaultValue === undefined)
|
|
665
|
+
placeholders.push(step.key);
|
|
666
|
+
break;
|
|
667
|
+
case "url":
|
|
668
|
+
value = "https://example.com/replace-me";
|
|
669
|
+
placeholders.push(step.key);
|
|
670
|
+
break;
|
|
671
|
+
case "book_pick":
|
|
672
|
+
value = "00000000-0000-0000-0000-000000000000";
|
|
673
|
+
placeholders.push(step.key);
|
|
674
|
+
break;
|
|
675
|
+
default:
|
|
676
|
+
continue;
|
|
677
|
+
}
|
|
678
|
+
if (!required && step.defaultValue === undefined) {
|
|
679
|
+
// Optional steps without a default stay out of the file.
|
|
680
|
+
const index = placeholders.indexOf(step.key);
|
|
681
|
+
if (index !== -1)
|
|
682
|
+
placeholders.splice(index, 1);
|
|
683
|
+
continue;
|
|
684
|
+
}
|
|
685
|
+
if (value !== undefined)
|
|
686
|
+
answers[step.key] = value;
|
|
687
|
+
}
|
|
688
|
+
return { answers, placeholders, steps };
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* Put the chosen students into the student step and re-key every
|
|
692
|
+
* subject_matrix to them: a flat array or a single placeholder key becomes
|
|
693
|
+
* `{ kidId: keys }` per student.
|
|
694
|
+
*/
|
|
695
|
+
export function applyStudentsToAnswers(spec, answers, studentIds) {
|
|
696
|
+
const next = { ...answers };
|
|
697
|
+
const steps = specSteps(spec);
|
|
698
|
+
const studentStep = steps.find((step) => step.kind === "student_multi_select");
|
|
699
|
+
if (studentIds.length > 0) {
|
|
700
|
+
if (!studentStep) {
|
|
701
|
+
throw new CliError("invalid_arguments", "This template's wizard has no student step, so --student cannot be applied. Use --answers-file only.");
|
|
702
|
+
}
|
|
703
|
+
next[studentStep.key] = studentIds;
|
|
704
|
+
for (const step of steps.filter((s) => s.kind === "subject_matrix")) {
|
|
705
|
+
const matrix = next[step.key];
|
|
706
|
+
if (matrix === undefined)
|
|
707
|
+
continue;
|
|
708
|
+
if (Array.isArray(matrix)) {
|
|
709
|
+
next[step.key] = Object.fromEntries(studentIds.map((student) => [student, matrix]));
|
|
710
|
+
continue;
|
|
711
|
+
}
|
|
712
|
+
if (matrix && typeof matrix === "object") {
|
|
713
|
+
const entries = Object.entries(matrix);
|
|
714
|
+
const keyed = entries.filter(([key]) => studentIds.includes(key));
|
|
715
|
+
if (keyed.length === 0 && entries.length === 1) {
|
|
716
|
+
next[step.key] = Object.fromEntries(studentIds.map((student) => [student, entries[0][1]]));
|
|
717
|
+
}
|
|
718
|
+
}
|
|
719
|
+
}
|
|
720
|
+
}
|
|
721
|
+
const missingRequired = steps
|
|
722
|
+
.filter((step) => step.required !== false &&
|
|
723
|
+
!step.availableWhen &&
|
|
724
|
+
!Object.prototype.hasOwnProperty.call(next, step.key))
|
|
725
|
+
.map((step) => step.key);
|
|
726
|
+
return { answers: next, missingRequired };
|
|
727
|
+
}
|
|
728
|
+
// ---------------------------------------------------------------------------
|
|
729
|
+
// Student resolution
|
|
730
|
+
// ---------------------------------------------------------------------------
|
|
731
|
+
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
732
|
+
/** `GET /tutor/students` row cap for a staff `search` (SEARCH_STUDENT_LIMIT in tutor/get.students.ts). */
|
|
733
|
+
const STAFF_SEARCH_LIMIT = 50;
|
|
734
|
+
const normalizeName = (name) => name.trim().replace(/\s+/g, " ").toLowerCase();
|
|
735
|
+
/**
|
|
736
|
+
* `--student` accepts a user ID or an exact (case/whitespace-insensitive)
|
|
737
|
+
* full name from the caller's roster. Several matches are an error that
|
|
738
|
+
* lists them; an ID is passed through without a request.
|
|
739
|
+
*/
|
|
740
|
+
export async function resolveStudentReference(api, value) {
|
|
741
|
+
const reference = value.trim();
|
|
742
|
+
if (UUID_RE.test(reference))
|
|
743
|
+
return { id: reference, name: null };
|
|
744
|
+
const wanted = normalizeName(reference);
|
|
745
|
+
const roster = unwrap(await api.client.GET("/tutor/students", {
|
|
746
|
+
params: { query: { scope: "mine" } },
|
|
747
|
+
})).items;
|
|
748
|
+
let matches = roster.filter((item) => normalizeName(item.name) === wanted);
|
|
749
|
+
if (matches.length === 0) {
|
|
750
|
+
// A staff roster is "mine" by default; search widens it to every student
|
|
751
|
+
// the server lets this session see, then the full name must still match.
|
|
752
|
+
const token = reference.split(/\s+/)[0];
|
|
753
|
+
const searched = unwrap(await api.client.GET("/tutor/students", {
|
|
754
|
+
params: { query: { search: token } },
|
|
755
|
+
}));
|
|
756
|
+
matches = searched.items.filter((item) => normalizeName(item.name) === wanted);
|
|
757
|
+
// A staff "all" search is capped and activity-ranked; a full page may
|
|
758
|
+
// hide a same-named kid, so it can never prove a name unique.
|
|
759
|
+
if (searched.scopeApplied === "all" &&
|
|
760
|
+
searched.items.length >= STAFF_SEARCH_LIMIT)
|
|
761
|
+
throw new CliError("ambiguous_student", `Too many students match "${token}" to be sure "${reference}" is unique. Retry with the kid's ID (\`students list\` or \`users search\` finds it).`, 1, {
|
|
762
|
+
truncated: true,
|
|
763
|
+
matches: matches.map(({ userId, name }) => ({ userId, name })),
|
|
764
|
+
});
|
|
765
|
+
}
|
|
766
|
+
const unique = [...new Map(matches.map((m) => [m.userId, m])).values()];
|
|
767
|
+
if (unique.length !== 1) {
|
|
768
|
+
throw new CliError(unique.length ? "ambiguous_student" : "student_not_found", unique.length
|
|
769
|
+
? `${unique.length} students are named "${reference}": ${unique.map((m) => `${m.name} (${m.userId})`).join(", ")}. Retry with the ID.`
|
|
770
|
+
: `No student named exactly "${reference}" is visible to this session. Use \`students list\` to find the ID.`, 1, { matches: unique.map(({ userId, name }) => ({ userId, name })) });
|
|
771
|
+
}
|
|
772
|
+
return { id: unique[0].userId, name: unique[0].name };
|
|
773
|
+
}
|
|
774
|
+
//# sourceMappingURL=goal-authoring.js.map
|