recess-cli 2.1.0 → 2.3.0

package/dist/commands/onboarding.js

@@ -37,6 +37,86 @@ const LIFECYCLE_PROMPT_KINDS = [
     "TWO_WEEK_CHECK_IN",
     "TWO_MONTH_TESTIMONIAL",
 ];
+// device-pairing.ts PAIRING_TTL_MS — the code dies 5 minutes after it is
+// minted, so the confirm step is what starts the clock, not the preview.
+const PAIRING_CODE_TTL_MINUTES = 5;
+function personName(firstName, lastName, fallback) {
+    return [firstName, lastName].filter(Boolean).join(" ") || fallback;
+}
+function summaryPreview(text, max = 600) {
+    if (!text)
+        return null;
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * The mission-control queue rule → the CLI command(s) that perform it, with
+ * real ids substituted where the action carries them. Placeholders stay in
+ * angle brackets where a human choice remains (a template, a cohort, a
+ * transcript). Suggestions only: every write below still previews and demands
+ * its own --confirm when actually run.
+ */
+function suggestedCommandsForQueueAction(action, familyId) {
+    const slug = action.partnerSlug ?? "<institution-slug>";
+    const invite = action.inviteId ?? "<code-id>";
+    const kid = (action.kids.find((row) => row.activeGoalCount === 0) ?? action.kids[0])
+        ?.id ?? "<kid-id>";
+    switch (action.key) {
+        case "invite_waiting":
+            return [
+                `recess school codes get ${invite} --school ${slug}`,
+                `recess school codes resend ${invite} --school ${slug}`,
+            ];
+        case "invite_expired":
+            return [
+                `recess school codes replace ${invite} --school ${slug} --data-file <invite.json>`,
+            ];
+        case "parked":
+            return [`recess onboarding set-account-state ${familyId} --state ACTIVE`];
+        case "start_intake":
+            return [`recess onboarding intake-session-create ${familyId}`];
+        case "fill_intake":
+            return [
+                `recess onboarding extract ${familyId} --session <session-id> --granola <ref>`,
+                `recess onboarding set-intake ${familyId} --session <session-id> --data <json>`,
+            ];
+        case "send_welcome":
+            return [`recess onboarding send-welcome ${familyId}`];
+        case "nudge_confirm":
+            return [
+                `recess onboarding send-comms --subject family:${familyId} --kind confirm_nudge_1`,
+            ];
+        case "load_goals":
+            return [
+                `recess goal-templates list --starter-only`,
+                `recess goal-templates apply-starter <template-id> --student ${kid}`,
+            ];
+        case "assign_tutor":
+            return [
+                `recess onboarding active-tutors ${familyId}`,
+                `recess onboarding set-primary-tutor ${familyId} --tutor <user-id>`,
+            ];
+        case "attest":
+            return [
+                `recess onboarding attest ${familyId} --condition <app_downloaded|tutor_met|goals_loaded|ma_diagnostic>`,
+            ];
+        case "clear_for_cohort":
+            return [`recess onboarding clear-for-cohort ${familyId}`];
+        case "register_cohort":
+            return [
+                `recess onboarding cohort-options ${familyId} --kid ${kid}`,
+                `recess onboarding register-cohort ${familyId} --kid ${kid} --cohort <event-series-id>`,
+            ];
+        case "at_risk":
+            return [
+                `recess onboarding readiness ${familyId}`,
+                `recess onboarding timeline ${familyId}`,
+            ];
+        case "mark_complete":
+            return [`recess onboarding set-stage ${familyId} --stage COMPLETE`];
+        default:
+            return [];
+    }
+}
 export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
     const noun = parsed.positionals[0] ?? "";
     const verb = parsed.positionals[1] ?? "";
@@ -86,6 +166,123 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
             const familyId = positional(parsed, 2, "family ID");
             return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/active-tutors", { params: { path: { familyId } } }));
         }
+        if (verb === "family") {
+            const familyId = positional(parsed, 2, "family ID");
+            // The whole family on one screen: status + readiness + the queue's next
+            // action + the current intake session + active tutors, in parallel.
+            // `status` is the required backbone (a missing family fails the command);
+            // the flag-gated reads degrade to a labeled `unavailable` instead of
+            // failing the view — the doctor command is the tool for "why".
+            const soft = async (read) => {
+                try {
+                    return await read();
+                }
+                catch (error) {
+                    return {
+                        unavailable: error instanceof CliError ? error.message : String(error),
+                    };
+                }
+            };
+            const [status, readiness, nextAction, intakeSession, activeTutors] = await Promise.all([
+                api.client
+                    .GET("/admin/onboarding/families/{familyId}/status", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/readiness", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/next-action", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+                soft(async () => {
+                    try {
+                        return await api.rawGet(`/admin/onboarding/families/${encodeURIComponent(familyId)}/intake-session`);
+                    }
+                    catch (error) {
+                        if (error instanceof CliError &&
+                            typeof error.details === "object" &&
+                            error.details !== null &&
+                            error.details.status === 404) {
+                            return { intakeSession: null };
+                        }
+                        throw error;
+                    }
+                }),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/active-tutors", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+            ]);
+            return {
+                familyId,
+                status,
+                readiness,
+                nextAction,
+                intakeSession,
+                activeTutors,
+            };
+        }
+        if (verb === "next") {
+            const familyId = positional(parsed, 2, "family ID");
+            const result = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/next-action", { params: { path: { familyId } } }));
+            const action = result.action;
+            return {
+                ...result,
+                // The queue rule mapped to the command that performs it, with real ids
+                // substituted where the action carries them — so "what's next" arrives
+                // holding "and here is how", instead of making the agent re-derive the
+                // funnel from documentation. Every suggested write still previews and
+                // requires its own --confirm.
+                suggestedCommands: action === null
+                    ? []
+                    : suggestedCommandsForQueueAction(action, familyId),
+            };
+        }
+        if (verb === "doctor") {
+            // --family is a flag rather than an optional positional: the schema
+            // derives positional bounds from the usage line, which cannot express
+            // optionality.
+            const familyId = flagString(parsed, "family");
+            return unwrap(await api.client.GET("/admin/onboarding/doctor", {
+                params: { query: familyId ? { familyId } : {} },
+            }));
+        }
+        if (verb === "starter-coverage") {
+            // The read-only pre-flip gate (same evaluation as the runbook's
+            // check-starter-coverage script). `ok: false` = do not flip the flag.
+            return unwrap(await api.client.GET("/admin/onboarding/starter-coverage"));
+        }
+        if (verb === "backfill-trackers") {
+            // WS-H over the wire. Without --apply this is the read-only census
+            // (dry-run POST, same precedent as `goal-templates apply --dry-run`).
+            // With --apply, the census is re-taken as the preview — the runbook's
+            // "fresh dry run on the identical predicate immediately before
+            // applying" — and the confirmed write re-derives every conjunct under a
+            // per-guardian lock server-side anyway.
+            if (!hasFlag(parsed, "apply")) {
+                return unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", {
+                    body: { apply: false },
+                }));
+            }
+            const census = unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", {
+                body: { apply: false },
+            }));
+            return writeCommand(parsed, {
+                action: "apply the WS-H guardian-tracker backfill: stamp parentOnboardingCompletedAt for the arm-1 (crash-between-commits) school guardians below",
+                target: { repairableCount: census.repairable.length },
+                request: { apply: true },
+                details: {
+                    freshCensus: census,
+                    authority: "The census is a photograph; the server re-derives every conjunct under a per-guardian lock at write time and skips anyone who no longer qualifies. Exact-ADMIN only.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", { body: { apply: true } })));
+        }
         if (verb === "meetings") {
             const familyId = positional(parsed, 2, "family ID");
             return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/meetings", {
@@ -156,6 +353,26 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 throw error;
             }
         }
+        if (verb === "reviews") {
+            const familyId = positional(parsed, 2, "family ID");
+            // The family workspace's review card: the handoff session(s) for this
+            // family. get.reviews.ts binds the family scope to the canonical (oldest)
+            // guardian — the same one the intake commands operate on — so a
+            // two-guardian family never surfaces the other guardian's session.
+            // `guardianMissing: true` with an empty list means the family has no
+            // guardian at all, not that no session was ever started.
+            return unwrap(await api.client.GET("/ai/onboarding/reviews", {
+                params: { query: { familyId } },
+            }));
+        }
+        if (verb === "review") {
+            const sessionId = positional(parsed, 2, "onboarding session ID");
+            // The full handoff record behind the workspace's handoff page: summary,
+            // collected data, artifacts, progress. Read this before mark-reviewed.
+            return unwrap(await api.client.GET("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            }));
+        }
         if (verb === "intake-session-create") {
             const familyId = positional(parsed, 2, "family ID");
             // The explicit create: get-or-create the intake session. Mints a blank
@@ -616,6 +833,149 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 request: previewRequest,
             }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake-extract", { params: { path: { familyId } }, body })));
         }
+        if (verb === "contracts") {
+            const kidUserId = flagString(parsed, "kid");
+            // The route takes no filter: it returns the newest 100 contracts across
+            // ALL families (get.contracts.ts), so --kid narrows client-side and a
+            // contract older than that window is simply not in the window.
+            const result = unwrap(await api.client.GET("/admin/enrollment-contracts/"));
+            if (!kidUserId)
+                return result;
+            return {
+                ...result,
+                contracts: result.contracts.filter((contract) => contract.studentUserId === kidUserId),
+                scope: "newest 100 contracts across all families, filtered by --kid",
+            };
+        }
+        if (verb === "send-contract") {
+            const kidUserId = positional(parsed, 2, "kid user ID");
+            const tuitionCents = flagInteger(parsed, "tuition-cents", { min: 0 });
+            const parentEmail = flagString(parsed, "parent-email");
+            const partnerName = flagString(parsed, "partner-name");
+            const partnerEmail = flagString(parsed, "partner-email");
+            // Read-only preflight. Three things the approver must see before a legal
+            // document goes out under someone's name: that this id is the intended
+            // KID, that a live contract is not already out with the parent (the
+            // workspace hides its button in that case — here --resend is the explicit
+            // override), and who the signature request will actually reach.
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId: kidUserId } },
+            }));
+            if (user.role !== "KID") {
+                throw new CliError("invalid_arguments", `User ${kidUserId} has role ${user.role}; an enrollment contract is sent for a kid.`);
+            }
+            if (!user.familyId) {
+                throw new CliError("invalid_arguments", `Kid ${kidUserId} has no family, so there is no guardian to sign.`);
+            }
+            const familyId = user.familyId;
+            const [contracts, status] = await Promise.all([
+                unwrap(await api.client.GET("/admin/enrollment-contracts/")),
+                unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                    params: { path: { familyId } },
+                })),
+            ]);
+            const live = contracts.contracts.find((contract) => contract.studentUserId === kidUserId &&
+                contract.status !== "DECLINED" &&
+                contract.status !== "VOIDED");
+            if (live && !hasFlag(parsed, "resend")) {
+                throw new CliError("invalid_arguments", `Contract ${live.id} for this kid is already ${live.status} (sent ${live.sentAt}). Sending again originates a SECOND Documenso document to the parent — pass --resend if that is what you mean.`);
+            }
+            const body = {
+                studentUserId: kidUserId,
+                ...(tuitionCents !== undefined ? { tuitionCents } : {}),
+                ...(parentEmail ? { parentEmail } : {}),
+                ...(partnerName ? { partnerName } : {}),
+                ...(partnerEmail ? { partnerEmail } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "originate the two-signer WonderED enrollment contract (partner signs first, then the parent) and email the signature request",
+                target: { kidUserId, familyId, familyName: status.familyName },
+                request: body,
+                details: {
+                    student: personName(user.firstName, user.lastName, kidUserId),
+                    // The send resolves the family's OLDEST guardian; this is the
+                    // family's predicted parent email (the oldest EMAIL-BEARING
+                    // guardian), so the two can differ when the oldest guardian has no
+                    // email — which is the case the route 400s on. --parent-email pins
+                    // the signer either way.
+                    parentEmailPredicted: status.welcome.recipientEmail,
+                    ...(parentEmail ? { parentEmailOverride: parentEmail } : {}),
+                    tuition: tuitionCents === undefined
+                        ? "resolved server-side from the family's newest ACCEPTED quote (the send 400s when no accepted quote covers this kid) — pass --tuition-cents to pin the amount in this approval"
+                        : `$${(tuitionCents / 100).toFixed(2)}`,
+                    partnerSigner: partnerName || partnerEmail
+                        ? { partnerName, partnerEmail }
+                        : "the WONDERED_SIGNATORY_* env pair",
+                    ...(live
+                        ? {
+                            resend: `Overriding live contract ${live.id} (${live.status}); this creates a SECOND document, it does not replace the first.`,
+                        }
+                        : {}),
+                    note: "Contracts normally auto-send when onboarding finalizes (enrollment-contract-autosend.ts). This command is for families priced after the fact, or whose auto-send was skipped for want of an accepted quote.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/enrollment-contracts/send/", { body })));
+        }
+        if (verb === "mark-reviewed") {
+            const sessionId = positional(parsed, 2, "onboarding session ID");
+            // Read-only preflight: the human approving this signs their name to a
+            // specific family's handoff, so the preview must carry the summary they
+            // are attesting to — and post.review.ts accepts ONLY HANDED_OFF, so
+            // refuse the states it would reject before the gate, not after approval.
+            const session = unwrap(await api.client.GET("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            }));
+            if (session.status !== "HANDED_OFF" && session.status !== "REVIEWED") {
+                throw new CliError("invalid_arguments", `Onboarding session ${sessionId} is ${session.status}; only a HANDED_OFF session can be marked reviewed. A COMPLETED session still needs the parent confirmation that creates the kid accounts.`);
+            }
+            const reviewer = session.reviewer
+                ? personName(session.reviewer.firstName, session.reviewer.lastName, session.reviewer.id)
+                : null;
+            return writeCommand(parsed, {
+                action: "mark the parent onboarding handoff as reviewed by you",
+                target: { sessionId, familyId: session.familyId },
+                request: {},
+                details: {
+                    status: session.status,
+                    parent: personName(session.parent.firstName, session.parent.lastName, session.parent.email ?? session.parent.id),
+                    handoffSentAt: session.handoffSentAt,
+                    // The stamp attests to THIS text; show it with the approval ask.
+                    handoffSummary: summaryPreview(session.handoffSummary),
+                    fullRecord: `recess --json onboarding review ${sessionId}`,
+                    ...(session.status === "REVIEWED"
+                        ? {
+                            note: `Already reviewed by ${reviewer ?? "another admin"} at ${session.handoffReviewedAt ?? "an unrecorded time"}. Confirming is a first-reviewer-wins no-op that preserves that attribution.`,
+                        }
+                        : {}),
+                },
+            }, async () => unwrap(await api.client.POST("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            })));
+        }
+        if (verb === "pairing-code") {
+            const kidUserId = positional(parsed, 2, "kid user ID");
+            // Read-only preflight: name the exact kid whose account this code signs
+            // in, and refuse a non-KID before the gate (the backend enforces the
+            // same rule, and an admin can pair ANY kid — there is no family fence to
+            // catch a mistyped id).
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId: kidUserId } },
+            }));
+            if (user.role !== "KID") {
+                throw new CliError("invalid_arguments", `User ${kidUserId} has role ${user.role}; pairing codes can only be issued for kids.`);
+            }
+            return writeCommand(parsed, {
+                action: "issue a single-use device-pairing code that signs this kid into a new device",
+                target: { kidUserId, familyId: user.familyId },
+                request: { kidUserId },
+                details: {
+                    kid: personName(user.firstName, user.lastName, kidUserId),
+                    expiresInMinutes: PAIRING_CODE_TTL_MINUTES,
+                    credential: "The result is a live sign-in credential (token, shortCode, pairingUrl). Read it to the family for the device in front of them; never paste it into a ticket, log, or shared channel.",
+                },
+            }, async () => unwrap(await api.client.POST("/auth/device-pairing/generate/", {
+                body: { kidUserId },
+            })));
+        }
         throw new CliError("invalid_arguments", "Unknown onboarding command. Run `recess onboarding --help` for the current command list.");
     }
     throw new CliError("invalid_arguments", "Unknown onboarding command.");