recess-cli 2.3.0 → 2.5.0

package/dist/command-schema.js

@@ -1,8 +1,10 @@
 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",
+    "analyzed",
     "apply",
+    "allow-billing",
     "allow-strand",
     "archived",
     "cancel-subscriptions",
@@ -11,6 +13,8 @@ const BOOLEAN_FLAGS = new Set([
     "confirm-destructive-changes",
     "disable-applet-follow-ups",
     "dry-run",
+    "force",
+    "no-wait",
     "enable-applet-follow-ups",
     "full",
     "help",
@@ -30,7 +34,9 @@ const BOOLEAN_FLAGS = new Set([
     "spec-only",
     "starter-only",
     "supersede",
+    "unlink",
     "visual-only",
+    "whole-family",
     "wait",
 ]);
 const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
@@ -50,6 +56,188 @@ 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 link-math-academy",
+    "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",
+    "village events",
+    "village link-event",
+]);
+/**
+ * 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 = [];
@@ -128,8 +316,13 @@ function positionalBounds(usage) {
     const rest = usage.replace(/^recess\s+(?:\[--json\]\s+)?/, "");
     const tokens = rest.split(/\s+/);
     let count = 0;
+    let optional = 0;
     let variadic = false;
     for (const token of tokens) {
+        if (/^\[[a-z][a-z0-9-]*\]$/.test(token)) {
+            optional += 1;
+            continue;
+        }
         if (token.startsWith("--") ||
             token.startsWith("[") ||
             token.startsWith("(")) {
@@ -139,7 +332,7 @@ function positionalBounds(usage) {
         if (/^<[^,>]+\.\.\.>$/.test(token))
             variadic = true;
     }
-    return { min: count, max: variadic ? null : count };
+    return { min: count, max: variadic ? null : count + optional };
 }
 export function buildCommandSchema(help) {
     return usageBlocks(help).flatMap((usage) => {
@@ -161,6 +354,7 @@ export function buildCommandSchema(help) {
             usage,
             flags,
             positionals,
+            access: commandAccess(path),
         }));
     });
 }
@@ -172,20 +366,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 +456,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: {