recess-cli 2.0.0 → 2.2.0

package/dist/commands/onboarding.js

@@ -0,0 +1,797 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagNumber, flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { assertChoice, flagBooleanValue, flagIdList, flagInteger, flagIsoInstant, positional, readJsonFile, } from "./shared.js";
+const ONBOARDING_STAGES = [
+    "LEGACY",
+    "PROVISIONED",
+    "PARENT_CONFIRMED",
+    "CLEARED_FOR_COHORT",
+    "COMPLETE",
+];
+const ONBOARDING_STAGE_SIDE_EFFECTS = {
+    LEGACY: "the pre-onboarding baseline",
+    PROVISIONED: "kid accounts provisioned, awaiting parent confirmation",
+    PARENT_CONFIRMED: "parent has confirmed setup",
+    CLEARED_FOR_COHORT: "unlocks cohort registration for school families",
+    COMPLETE: "onboarding finished",
+};
+const ONBOARDING_ACCOUNT_STATES = [
+    "ACTIVE",
+    "PENDING_PAYMENT",
+    "PAUSED",
+    "BOOTED",
+];
+const ONBOARDING_CONDITIONS = [
+    "app_downloaded",
+    "tutor_met",
+    "goals_loaded",
+    "ma_diagnostic",
+];
+const ONBOARDING_COMMS_STATUSES = ["RESERVED", "SENT", "FAILED"];
+const LIFECYCLE_PROMPT_KINDS = [
+    "TWO_WEEK_REVIEW",
+    "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)}…`;
+}
+export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
+    const noun = parsed.positionals[0] ?? "";
+    const verb = parsed.positionals[1] ?? "";
+    if (noun === "onboarding") {
+        if (verb === "status") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                params: { path: { familyId } },
+            }));
+        }
+        if (verb === "queue") {
+            const partnerSlug = flagString(parsed, "school");
+            return unwrap(await api.client.GET("/admin/onboarding/queue", {
+                params: { query: partnerSlug ? { partnerSlug } : {} },
+            }));
+        }
+        if (verb === "kids") {
+            const timePeriodDays = flagNumber(parsed, "time-period-days");
+            const cohortId = flagString(parsed, "cohort");
+            const limit = flagNumber(parsed, "limit");
+            const stageFilterRaw = flagString(parsed, "stage-filter");
+            const stageFilter = stageFilterRaw
+                ? assertChoice(stageFilterRaw, ["all", "scheduled", "oriented", "course", "converted", "lost"], "--stage-filter")
+                : undefined;
+            return unwrap(await api.client.GET("/admin/onboarding/kids/", {
+                params: {
+                    query: {
+                        ...(timePeriodDays !== undefined ? { timePeriodDays } : {}),
+                        ...(cohortId ? { cohortId } : {}),
+                        ...(limit !== undefined ? { limit } : {}),
+                        ...(stageFilter ? { stageFilter } : {}),
+                    },
+                },
+            }));
+        }
+        if (verb === "timeline") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/timeline", {
+                params: { path: { familyId } },
+            }));
+        }
+        if (verb === "readiness") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/readiness", { params: { path: { familyId } } }));
+        }
+        if (verb === "active-tutors") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/active-tutors", { params: { path: { familyId } } }));
+        }
+        if (verb === "meetings") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/meetings", {
+                params: { path: { familyId } },
+            }));
+        }
+        if (verb === "cohort-options") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid");
+            return unwrap(await api.client.GET("/admin/onboarding/cohort-options", {
+                params: {
+                    query: { familyId, ...(kidUserId ? { kidUserId } : {}) },
+                },
+            }));
+        }
+        if (verb === "comms") {
+            const partnerSlug = flagString(parsed, "school");
+            const statusRaw = flagString(parsed, "status");
+            const status = statusRaw
+                ? assertChoice(statusRaw, ONBOARDING_COMMS_STATUSES, "--status")
+                : undefined;
+            const kind = flagString(parsed, "kind");
+            const limit = flagInteger(parsed, "limit", { min: 1, max: 200 });
+            const cursor = flagString(parsed, "cursor");
+            return unwrap(await api.client.GET("/admin/onboarding/comms", {
+                params: {
+                    query: {
+                        ...(partnerSlug ? { partnerSlug } : {}),
+                        ...(status ? { status } : {}),
+                        ...(kind ? { kind } : {}),
+                        ...(limit !== undefined ? { limit } : {}),
+                        ...(cursor ? { cursor } : {}),
+                    },
+                },
+            }));
+        }
+        if (verb === "lifecycle-prompts") {
+            return unwrap(await api.client.GET("/admin/onboarding/lifecycle-prompts"));
+        }
+        if (verb === "orientation-sessions") {
+            return unwrap(await api.client.GET("/admin/onboarding/orientation-sessions/"));
+        }
+        if (verb === "ixl-preview") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/kids/{kidUserId}/provision/ixl/preview", { params: { path: { familyId, kidUserId } } }));
+        }
+        if (verb === "intake-session") {
+            const familyId = positional(parsed, 2, "family ID");
+            // A true read: look up the family's current IN_PROGRESS intake session
+            // WITHOUT minting one (get.family-intake-session.ts). Merely viewing a
+            // family must not create a blank session — use intake-session-create to
+            // mint one. A 404 means "none yet" and is a clean result, not an error.
+            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,
+                        familyId,
+                        message: "No intake session for this family yet.",
+                    };
+                }
+                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
+            // IN_PROGRESS session when none exists (post.family-intake-session.ts,
+            // freshIfFinished), so it is a write and goes through the confirmation
+            // gate like every other mutating command.
+            return writeCommand(parsed, {
+                action: "create the family's parent intake session (mints a blank IN_PROGRESS session if none exists)",
+                target: { familyId },
+                request: {},
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake-session", { params: { path: { familyId } } })));
+        }
+        if (verb === "set-stage") {
+            const familyId = positional(parsed, 2, "family ID");
+            const stage = assertChoice(flagString(parsed, "stage", { required: true }), ONBOARDING_STAGES, "--stage");
+            // Read the current stage first so the preview can name the transition and
+            // warn when it moves progress backward (re-locks capabilities).
+            const current = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                params: { path: { familyId } },
+            }));
+            const from = current.onboardingStage;
+            const backward = ONBOARDING_STAGES.indexOf(stage) < ONBOARDING_STAGES.indexOf(from);
+            const body = { stage };
+            return writeCommand(parsed, {
+                action: `${backward ? "MOVE BACKWARD — re-locks progress: " : ""}set onboarding stage to ${stage} — ${ONBOARDING_STAGE_SIDE_EFFECTS[stage]}`,
+                target: { familyId, from },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/stage", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-account-state") {
+            const familyId = positional(parsed, 2, "family ID");
+            const state = assertChoice(flagString(parsed, "state", { required: true }), ONBOARDING_ACCOUNT_STATES, "--state");
+            const note = flagString(parsed, "note");
+            const lockout = state === "PAUSED" || state === "BOOTED"
+                ? " — locks the family out of paid capabilities"
+                : "";
+            const body = { state, ...(note !== undefined ? { note } : {}) };
+            return writeCommand(parsed, {
+                action: `set account state to ${state}${lockout}`,
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/account-state", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-primary-tutor") {
+            const familyId = positional(parsed, 2, "family ID");
+            const tutorUserId = flagString(parsed, "tutor");
+            const clear = hasFlag(parsed, "clear");
+            if ((tutorUserId && clear) || (!tutorUserId && !clear)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --tutor <user-id> or --clear.");
+            }
+            const body = { tutorUserId: clear ? null : tutorUserId };
+            return writeCommand(parsed, {
+                action: clear
+                    ? "clear the family's primary tutor"
+                    : "set the family's primary tutor (requires an active assignment in this family)",
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/primary-tutor", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "attest") {
+            const familyId = positional(parsed, 2, "family ID");
+            const condition = assertChoice(flagString(parsed, "condition", { required: true }), ONBOARDING_CONDITIONS, "--condition");
+            const revoke = hasFlag(parsed, "revoke");
+            const note = flagString(parsed, "note");
+            const body = {
+                condition,
+                attested: !revoke,
+                ...(note !== undefined ? { note } : {}),
+            };
+            return writeCommand(parsed, {
+                action: revoke
+                    ? `REVOKE attestation ${condition}`
+                    : `attest ${condition}`,
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/attest", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "clear-for-cohort") {
+            const familyId = positional(parsed, 2, "family ID");
+            return writeCommand(parsed, {
+                action: "clear the family for cohort placement after the server rechecks stage, account, kids, goals, tutor, and attestations",
+                target: { familyId },
+                request: {},
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/clear-for-cohort", { params: { path: { familyId } } })));
+        }
+        if (verb === "register-cohort") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const eventSeriesId = flagString(parsed, "cohort", { required: true });
+            const body = { kidUserId, eventSeriesId };
+            return writeCommand(parsed, {
+                action: "register the kid in an eligible school cohort (staff placement may occur before the normal family-stage gate)",
+                target: { familyId, kidUserId, eventSeriesId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/register-cohort", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-kid-grade") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const grade = flagInteger(parsed, "grade", { min: 1, max: 12 });
+            const clear = hasFlag(parsed, "clear");
+            if ((grade !== undefined && clear) || (grade === undefined && !clear)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --grade 1..12 or --clear.");
+            }
+            const body = { currentGrade: clear ? null : grade };
+            return writeCommand(parsed, {
+                action: clear
+                    ? "clear the kid's current grade back to uncollected"
+                    : `set the kid's current grade to ${grade}`,
+                target: { familyId, kidUserId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/kids/{kidUserId}/grade", { params: { path: { familyId, kidUserId } }, body })));
+        }
+        if (verb === "seed-feed") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            return writeCommand(parsed, {
+                action: "seed the kid's feed interests from the newest populated family intake that contains this kid",
+                target: { familyId, kidUserId },
+                request: {},
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/kids/{kidUserId}/seed-feed", { params: { path: { familyId, kidUserId } } })));
+        }
+        if (verb === "generate-summaries") {
+            const familyId = positional(parsed, 2, "family ID");
+            return writeCommand(parsed, {
+                action: "regenerate the current intake's parent narrative summaries with AI (can take about 30 seconds)",
+                target: { familyId },
+                request: {},
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake/generate-summaries", { params: { path: { familyId } } })));
+        }
+        if (verb === "provision-math-academy") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const grade = flagInteger(parsed, "grade", { min: 1, max: 12 });
+            const body = grade === undefined ? {} : { grade };
+            return writeCommand(parsed, {
+                action: "provision or reconnect the kid's Math Academy account (vendor write; cannot be automatically undone)",
+                target: { familyId, kidUserId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/kids/{kidUserId}/provision/math-academy", { params: { path: { familyId, kidUserId } }, body })));
+        }
+        if (verb === "provision-ixl") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const credentialsFile = flagString(parsed, "credentials-file");
+            const body = credentialsFile
+                ? await readJsonFile(credentialsFile, "IXL credentials file")
+                : undefined;
+            const password = typeof body?.password === "string" ? body.password : undefined;
+            const safeRequest = body
+                ? {
+                    ...body,
+                    ...(password
+                        ? {
+                            password: "[redacted]",
+                            passwordSha256: createHash("sha256")
+                                .update(password)
+                                .digest("hex"),
+                        }
+                        : {}),
+                }
+                : {};
+            return writeCommand(parsed, {
+                action: "add or restore the kid in the IXL roster and optionally store the supplied login",
+                target: { familyId, kidUserId },
+                request: safeRequest,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/kids/{kidUserId}/provision/ixl", {
+                params: { path: { familyId, kidUserId } },
+                ...(body ? { body } : {}),
+            })));
+        }
+        if (verb === "remove-ixl") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            return writeCommand(parsed, {
+                action: "remove the kid from the next IXL roster snapshot (stored login is retained)",
+                target: { familyId, kidUserId },
+                request: {},
+            }, async () => unwrap(await api.client.DELETE("/admin/onboarding/families/{familyId}/kids/{kidUserId}/provision/ixl", { params: { path: { familyId, kidUserId } } })));
+        }
+        if (verb === "ixl-sync") {
+            const apply = hasFlag(parsed, "apply");
+            if (!apply) {
+                return unwrap(await api.client.POST("/admin/onboarding/ixl/sync", {
+                    body: { dryRun: true },
+                }));
+            }
+            return writeCommand(parsed, {
+                action: "UPLOAD the complete current IXL roster snapshot (learners omitted from it are deactivated by the vendor)",
+                target: { vendor: "IXL" },
+                request: { dryRun: false },
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/ixl/sync", {
+                body: { dryRun: false },
+            })));
+        }
+        if (verb === "send-comms") {
+            const subjectKey = flagString(parsed, "subject", { required: true });
+            const kind = flagString(parsed, "kind", { required: true });
+            const body = { subjectKey, kind };
+            return writeCommand(parsed, {
+                action: "send the selected onboarding lifecycle communication now (timing bypass only; rollout and preference gates still apply)",
+                target: { subjectKey },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/comms/send-now", {
+                body,
+            })));
+        }
+        if (verb === "send-welcome" || verb === "send-payment-email") {
+            const familyId = positional(parsed, 2, "family ID");
+            const resend = hasFlag(parsed, "resend");
+            const payment = verb === "send-payment-email";
+            return writeCommand(parsed, {
+                action: `${resend ? "RE-SEND" : "send"} the family's ${payment ? "enrollment payment" : "plan-ready welcome"} email`,
+                target: { familyId },
+                request: { resend },
+            }, async () => {
+                if (payment) {
+                    return unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/send-payment-email", { params: { path: { familyId } }, body: { resend } }));
+                }
+                return unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/send-welcome", { params: { path: { familyId } }, body: { resend } }));
+            });
+        }
+        if (verb === "send-recommendations") {
+            const familyId = positional(parsed, 2, "family ID");
+            const courseIds = flagIdList(parsed, "courses");
+            if (courseIds.length < 1 || courseIds.length > 8) {
+                throw new CliError("invalid_arguments", "--courses must contain from 1 through 8 comma-separated course IDs.");
+            }
+            const resend = hasFlag(parsed, "resend");
+            const body = { courseIds, resend };
+            return writeCommand(parsed, {
+                action: `${resend ? "RE-SEND" : "send"} the family's class recommendations email and unlock Explore`,
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/send-recommendations", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-lifecycle-prompt") {
+            const kind = assertChoice(positional(parsed, 2, "lifecycle prompt kind"), LIFECYCLE_PROMPT_KINDS, "prompt kind");
+            const enabled = flagBooleanValue(parsed, "enabled");
+            const delayDays = flagInteger(parsed, "delay-days", {
+                min: 0,
+                max: 365,
+            });
+            const windowDays = flagInteger(parsed, "window-days", {
+                min: 1,
+                max: 730,
+            });
+            const snoozeDays = flagInteger(parsed, "snooze-days", {
+                min: 0,
+                max: 90,
+            });
+            const maxPrompts = flagInteger(parsed, "max-prompts", {
+                min: 1,
+                max: 20,
+            });
+            const body = {
+                ...(enabled !== undefined ? { enabled } : {}),
+                ...(delayDays !== undefined ? { delayDays } : {}),
+                ...(windowDays !== undefined ? { windowDays } : {}),
+                ...(snoozeDays !== undefined ? { snoozeDays } : {}),
+                ...(maxPrompts !== undefined ? { maxPrompts } : {}),
+            };
+            if (Object.keys(body).length === 0) {
+                throw new CliError("invalid_arguments", "Pass at least one lifecycle prompt field to update.");
+            }
+            return writeCommand(parsed, {
+                action: "change the live family lifecycle prompt schedule (exact-admin; affects future prompts)",
+                target: { kind },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/lifecycle-prompts/{kind}", { params: { path: { kind } }, body })));
+        }
+        if (verb === "override-lifecycle-prompt") {
+            const kind = assertChoice(positional(parsed, 2, "lifecycle prompt kind"), LIFECYCLE_PROMPT_KINDS, "prompt kind");
+            const familyId = positional(parsed, 3, "family ID");
+            const action = assertChoice(flagString(parsed, "action", { required: true }), ["delay", "skip", "clear"], "--action");
+            const days = flagInteger(parsed, "days", { min: 1, max: 365 });
+            if ((action === "delay" && days === undefined) ||
+                (action !== "delay" && days !== undefined)) {
+                throw new CliError("invalid_arguments", action === "delay"
+                    ? "--days is required when --action is delay."
+                    : "--days is accepted only when --action is delay.");
+            }
+            const body = { action, ...(days !== undefined ? { days } : {}) };
+            return writeCommand(parsed, {
+                action: `${action} the ${kind} lifecycle prompt for this family${days === undefined ? "" : ` by ${days} day(s)`}`,
+                target: { kind, familyId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/lifecycle-prompts/{kind}/families/{familyId}/override", { params: { path: { kind, familyId } }, body })));
+        }
+        if (verb === "orientation-create") {
+            const startsAt = flagIsoInstant(parsed, "starts-at", {
+                required: true,
+            });
+            const endsAt = flagIsoInstant(parsed, "ends-at");
+            const capacity = flagInteger(parsed, "capacity", { min: 0, max: 1000 });
+            if (endsAt && Date.parse(endsAt) <= Date.parse(startsAt)) {
+                throw new CliError("invalid_arguments", "--ends-at must be later than --starts-at.");
+            }
+            const body = {
+                startsAt,
+                ...(endsAt ? { endsAt } : {}),
+                ...(capacity !== undefined ? { capacity } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "schedule a new family orientation session",
+                target: { startsAt },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/orientation-sessions/", {
+                body,
+            })));
+        }
+        if (verb === "orientation-set-status") {
+            const sessionId = positional(parsed, 2, "orientation session ID");
+            const status = assertChoice(flagString(parsed, "status", { required: true }), ["CANCELED", "COMPLETED"], "--status");
+            const body = { status };
+            return writeCommand(parsed, {
+                action: `${status === "CANCELED" ? "cancel" : "complete"} the orientation session (canceled sessions cannot be reopened)`,
+                target: { sessionId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/orientation-sessions/{sessionId}/", { params: { path: { sessionId } }, body })));
+        }
+        if (verb === "orientation-attendance") {
+            const sessionId = positional(parsed, 2, "orientation session ID");
+            const familyId = flagString(parsed, "family", { required: true });
+            const attended = flagBooleanValue(parsed, "attended");
+            if (attended === undefined) {
+                throw new CliError("invalid_arguments", "Missing required --attended true|false.");
+            }
+            const body = { familyId, attended };
+            return writeCommand(parsed, {
+                action: attended
+                    ? "mark the family as having attended this orientation session"
+                    : "clear the family's orientation attendance mark",
+                target: { sessionId, familyId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/orientation-sessions/{sessionId}/attendance/", { params: { path: { sessionId } }, body })));
+        }
+        if (verb === "meeting-reschedule") {
+            const meetingId = positional(parsed, 2, "meeting ID");
+            const start = flagIsoInstant(parsed, "starts-at", { required: true });
+            const reason = flagString(parsed, "note");
+            const body = { start, ...(reason ? { reason } : {}) };
+            return writeCommand(parsed, {
+                action: "reschedule the Cal.com booking (provisional until its webhook settles; do not blindly retry an ambiguous outcome)",
+                target: { meetingId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/meetings/{meetingId}/reschedule", { params: { path: { meetingId } }, body })));
+        }
+        if (verb === "meeting-cancel") {
+            const meetingId = positional(parsed, 2, "meeting ID");
+            const reason = flagString(parsed, "reason", { required: true }).trim();
+            if (!reason) {
+                throw new CliError("invalid_arguments", "--reason must not be empty.");
+            }
+            const body = { reason };
+            return writeCommand(parsed, {
+                action: "cancel the Cal.com booking and email the family the supplied reason (provisional until its webhook settles)",
+                target: { meetingId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/meetings/{meetingId}/cancel", { params: { path: { meetingId } }, body })));
+        }
+        if (verb === "set-intake") {
+            const familyId = positional(parsed, 2, "family ID");
+            const sessionId = flagString(parsed, "session", { required: true });
+            const dataRaw = flagString(parsed, "data", { required: true });
+            const expectedUpdatedAt = flagString(parsed, "expected-updated-at");
+            let collectedData;
+            try {
+                collectedData = JSON.parse(dataRaw);
+            }
+            catch {
+                throw new CliError("invalid_arguments", "--data must be valid JSON for the intake collectedData object.");
+            }
+            if (expectedUpdatedAt !== undefined &&
+                Number.isNaN(Date.parse(expectedUpdatedAt))) {
+                throw new CliError("invalid_arguments", "--expected-updated-at must be an ISO-8601 timestamp (the intake-session read's updatedAt).");
+            }
+            const collected = collectedData;
+            // The preview must do ZERO network so an offline preview stays honest
+            // (admin-cli offline-preview contract). The optimistic-concurrency token
+            // is resolved only on --confirm, inside the execute closure below — so a
+            // plain preview never reaches out. Strict mode (--expected-updated-at)
+            // shows the pinned token in the preview; the default fetches it at confirm.
+            const previewRequest = {
+                sessionId,
+                collectedData: collected,
+                ...(expectedUpdatedAt !== undefined ? { expectedUpdatedAt } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "write structured parent intake data for the family",
+                target: { familyId, sessionId },
+                request: previewRequest,
+            }, async () => {
+                // Resolve the CAS token now (only reached on --confirm):
+                // - strict mode: pin the operator-supplied token. A stale one 409s
+                //   (unwrap → CliError → non-zero exit), protecting a parent's
+                //   concurrent confirm-flow autosave.
+                // - default: fetch the CURRENT token and warn that edits made since
+                //   the preview are unprotected. The CLI is a last-resort admin tool;
+                //   pragmatic default + honest warning + strict opt-in.
+                let token = expectedUpdatedAt;
+                if (token === undefined) {
+                    const current = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/intake-session", { params: { path: { familyId } } }));
+                    token = current.updatedAt;
+                    process.stderr.write("Warning: using current session token; edits made since your preview are not protected — pass --expected-updated-at for strict CAS.\n");
+                }
+                const body = {
+                    sessionId,
+                    collectedData: collected,
+                    expectedUpdatedAt: token,
+                };
+                return unwrap(await api.client.PUT("/admin/onboarding/families/{familyId}/intake", { params: { path: { familyId } }, body }));
+            });
+        }
+        if (verb === "extract") {
+            const familyId = positional(parsed, 2, "family ID");
+            const sessionId = flagString(parsed, "session", { required: true });
+            const transcriptFile = flagString(parsed, "transcript-file");
+            const granolaRef = flagString(parsed, "granola");
+            if ((transcriptFile && granolaRef) || (!transcriptFile && !granolaRef)) {
+                throw new CliError("invalid_arguments", "Pass exactly one source: --transcript-file <path> or --granola <ref>.");
+            }
+            let transcript;
+            if (transcriptFile) {
+                try {
+                    transcript = await fs.readFile(path.resolve(transcriptFile), "utf8");
+                }
+                catch (error) {
+                    throw new CliError("invalid_arguments", `Could not read transcript file ${transcriptFile}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            const body = {
+                sessionId,
+                ...(transcript !== undefined ? { transcript } : {}),
+                ...(granolaRef ? { granolaRef } : {}),
+            };
+            // Keep raw transcript PII out of the confirmation preview (it prints to
+            // stderr, agent logs, and approval records); the full body still goes to
+            // the API on --confirm.
+            const previewRequest = transcript !== undefined && transcriptFile
+                ? {
+                    sessionId,
+                    path: path.resolve(transcriptFile),
+                    byteCount: Buffer.byteLength(transcript, "utf8"),
+                    sha256Prefix: createHash("sha256")
+                        .update(transcript)
+                        .digest("hex")
+                        .slice(0, 12),
+                }
+                : { sessionId, ...(granolaRef ? { granolaRef } : {}) };
+            return writeCommand(parsed, {
+                action: "extract intake from transcript via Claude and merge into session",
+                target: {
+                    familyId,
+                    sessionId,
+                    source: transcriptFile ? "transcript" : "granola",
+                },
+                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.");
+}
+//# sourceMappingURL=onboarding.js.map