recess-cli 2.2.0 → 2.4.0

package/dist/command-schema.js

@@ -1,5 +1,5 @@
 import { CliError } from "./errors.js";
-export const AGENT_CONTEXT_SCHEMA_VERSION = "3";
+export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
     "all-references",
     "apply",
@@ -50,6 +50,185 @@ const GLOBAL_FLAG_TYPES = {
     profile: "string",
     reason: "string",
 };
+const LOCAL_COMMAND_NOUNS = new Set([
+    "--version",
+    "agent-context",
+    "auth",
+    "doctor",
+    "feedback",
+    "jobs",
+    "profile",
+    "setup",
+]);
+const AUTHENTICATED_COMMAND_PREFIXES = [
+    "village build",
+    "village library",
+    "village objects",
+    "village render",
+];
+const FAMILY_AI_COMMANDS = new Set([
+    "content-library search",
+    "goal-templates apply",
+    "goal-templates apply-starter",
+    "goal-templates capture-snapshot",
+    "goal-templates create",
+    "goal-templates get",
+    "goal-templates list",
+    "goal-templates snapshot-files",
+    "goal-templates validate-spec",
+    "goals archive",
+    "goals create",
+    "goals edit",
+    "goals files checkout",
+    "goals files init",
+    "goals files list",
+    "goals files push",
+    "goals files read",
+    "goals files write",
+    "goals list",
+    "goals pdf upload",
+    "goals queue get",
+    "goals queue set",
+    "goals unarchive",
+    "memories context",
+    "memories log",
+    "onboarding pairing-code",
+    "request get",
+    "rocky get",
+    "rocky set",
+    "skills guardian get",
+    "skills guardian list",
+    "students list",
+    "students schedule",
+    "students today",
+    "students xp-history",
+    "todos create",
+    "todos edit",
+]);
+const STAFF_COMMANDS = new Set([
+    "cohorts email",
+    "cohorts end",
+    "cohorts get",
+    "cohorts parent-emails",
+    "cohorts pause-billing",
+    "cohorts resume-billing",
+    "cohorts search",
+    "enrollments create",
+    "enrollments register-cohort",
+    "enrollments unregister-cohort",
+    "events add",
+    "events cancel",
+    "events get",
+    "events reschedule",
+    "events set-status",
+    "events take-attendance",
+    "goal-templates delete",
+    "goal-templates set-metadata",
+    "goal-templates versions",
+    "goals complete",
+    "goals undo-completion",
+    "onboarding active-tutors",
+    "onboarding attest",
+    "onboarding clear-for-cohort",
+    "onboarding cohort-options",
+    "onboarding comms",
+    "onboarding contracts",
+    "onboarding doctor",
+    "onboarding extract",
+    "onboarding family",
+    "onboarding generate-summaries",
+    "onboarding intake-session",
+    "onboarding intake-session-create",
+    "onboarding ixl-preview",
+    "onboarding kids",
+    "onboarding lifecycle-prompts",
+    "onboarding mark-reviewed",
+    "onboarding next",
+    "onboarding orientation-attendance",
+    "onboarding orientation-sessions",
+    "onboarding provision-ixl",
+    "onboarding provision-math-academy",
+    "onboarding queue",
+    "onboarding readiness",
+    "onboarding register-cohort",
+    "onboarding remove-ixl",
+    "onboarding review",
+    "onboarding reviews",
+    "onboarding seed-feed",
+    "onboarding send-comms",
+    "onboarding send-contract",
+    "onboarding set-intake",
+    "onboarding set-kid-grade",
+    "onboarding set-primary-tutor",
+    "onboarding starter-coverage",
+    "onboarding status",
+    "onboarding timeline",
+    "payout invoices get",
+    "payout invoices list",
+    "payout invoices set-status",
+    "payout items add",
+    "payout items delete",
+    "payout items edit",
+    "payout payruns list",
+    "payout recipients list",
+    "registrations approve",
+    "registrations deny",
+    "school codes get",
+    "school codes list",
+    "school create",
+    "school credit-transactions",
+    "school families",
+    "school family-search",
+    "school kid-slots",
+    "school list",
+    "school logo-upload",
+    "school partner-family",
+    "school representatives add",
+    "school representatives list",
+    "school representatives remove",
+    "school representatives search",
+    "school update",
+    "store-items list",
+    "students upload-map-scores",
+    "todos complete",
+    "todos delete",
+    "todos generate-applet",
+    "users get",
+    "users tier list-tiers",
+]);
+/**
+ * Classify the command itself, not the target passed to it. Target-level
+ * family, assignment, ownership, and feature-flag checks remain server-owned.
+ * A newly added command fails closed to admin-only discovery until its CLI
+ * audience is classified here.
+ */
+function commandAccess(path) {
+    const key = path.join(" ");
+    if (LOCAL_COMMAND_NOUNS.has(path[0]))
+        return "local";
+    if (AUTHENTICATED_COMMAND_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix} `))) {
+        return "authenticated";
+    }
+    if (FAMILY_AI_COMMANDS.has(key))
+        return "family_ai";
+    if (STAFF_COMMANDS.has(key))
+        return "staff";
+    return "admin";
+}
+export function commandIsAvailable(command, scope) {
+    if (command.access === "local")
+        return true;
+    if (!scope)
+        return false;
+    if (command.access === "authenticated")
+        return true;
+    if (command.access === "family_ai")
+        return scope !== "village_home";
+    if (command.access === "staff") {
+        return scope === "guide_students" || scope === "full_admin";
+    }
+    return scope === "full_admin";
+}
 function usageBlocks(help) {
     const lines = help.split("\n");
     const blocks = [];
@@ -161,6 +340,7 @@ export function buildCommandSchema(help) {
             usage,
             flags,
             positionals,
+            access: commandAccess(path),
         }));
     });
 }
@@ -172,20 +352,50 @@ export function findCommandSchema(commands, positionals) {
         .filter((command) => pathStartsWith(positionals, command.path))
         .sort((left, right) => right.path.length - left.path.length)[0];
 }
-export function scopedHelp(help, commands, scope) {
-    if (scope.length === 0)
-        return help;
-    const matches = commands.filter((command) => pathStartsWith(command.path, scope));
+export function scopedHelp(_help, commands, scope, context) {
+    const matches = commands.filter((command) => pathStartsWith(command.path, scope) &&
+        commandIsAvailable(command, context.scope));
     if (matches.length === 0) {
         throw new CliError("unknown_command", `Unknown command scope: ${scope.join(" ")}. Run \`recess --help\` for available commands.`);
     }
+    const uniqueUsages = Array.from(new Map(matches.map((command) => [command.usage, command])).values());
+    const accessLabel = context.scope
+        ? context.role
+        : context.source === "unavailable"
+            ? "session unavailable (local and authentication commands only)"
+            : "signed out (local and authentication commands only)";
     return [
-        `recess ${scope.join(" ")} — command help`,
+        scope.length > 0
+            ? `recess ${scope.join(" ")} — command help`
+            : "recess — safe Recess administration and family AI tools",
+        "",
+        `Access: ${accessLabel}`,
+        "Key: ◇ shared command   ◆ admin-only command",
         "",
         "Usage:",
-        ...Array.from(new Set(matches.map((command) => `  ${command.usage}`))),
+        ...uniqueUsages.flatMap((command) => wrapUsage(command.usage, command.access === "admin" ? "◆" : "◇")),
+        "",
+        "Run `recess help <noun> [verb]` for a focused list.",
     ].join("\n");
 }
+function wrapUsage(usage, icon, width = 100) {
+    const firstPrefix = `  ${icon} `;
+    const continuationPrefix = "    ";
+    const output = [];
+    let current = firstPrefix;
+    for (const word of usage.split(/\s+/)) {
+        const separator = current.trim().length === 1 ? "" : " ";
+        if (current.length > firstPrefix.length &&
+            current.length + separator.length + word.length > width) {
+            output.push(current);
+            current = `${continuationPrefix}${word}`;
+            continue;
+        }
+        current += `${separator}${word}`;
+    }
+    output.push(current);
+    return output;
+}
 export function validateInvocation(parsed, commands) {
     const command = findCommandSchema(commands, parsed.positionals);
     if (!command) {
@@ -232,14 +442,18 @@ export function agentContext(commands, options) {
     return {
         schema_version: AGENT_CONTEXT_SCHEMA_VERSION,
         cli_version: options.cliVersion,
+        session: options.discovery,
         commands: Object.fromEntries(commands
-            .filter((command) => command.path[0] !== "--version")
+            .filter((command) => command.path[0] !== "--version" &&
+            commandIsAvailable(command, options.discovery.scope))
             .map((command) => [
             command.path.join(" "),
             {
                 usage: command.usage,
                 flags: command.flags,
                 positionals: command.positionals,
+                access: command.access,
+                admin_only: command.access === "admin",
             },
         ])),
         global_flags: {

package/dist/commands/onboarding.js

@@ -48,6 +48,75 @@ function summaryPreview(text, max = 600) {
         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] ?? "";
@@ -97,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", {