recess-cli 2.3.0 → 2.4.0

package/README.md

@@ -111,7 +111,7 @@ Error or write preview:
 
 Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
 
-`recess --json agent-context` returns the canonical command/flag/positional schema. `recess --json help payout recipients` returns scoped help. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
+`recess --json agent-context` returns the canonical command/flag/positional schema filtered to the scope claim already stored in the current CLI session. Bare help, scoped help, and `agent-context` make no API request; real commands still go through server authorization, while `auth status` and `doctor` perform live session checks. `recess --json help payout recipients` returns scoped help, and human help marks exact-admin commands with `◆`. Unknown flags, duplicate non-repeatable flags, missing values, and extra positionals are errors instead of being silently ignored.
 
 Every command-driven request to the Recess API except `auth` requires `--reason "..."`: a
 non-empty, human-readable purpose of at most 1024 characters. The CLI sends it as
@@ -249,6 +249,7 @@ recess --json students schedule --student <kid-id> --days 30 --reason "Review th
 recess --json students xp-history --student <kid-id> --range month --reason "Review recent XP history"
 recess --json goals list --student <kid-id> --reason "Review the student's goals"
 recess --json todos create --student <kid-id> --title "Read chapter 4" --reason "Add the assigned reading"
+recess --json todos complete <todo-id> --xp 35 --reason "Complete the todo with a 35 XP total reward"
 recess --json goals delete <goal-id> --student <kid-id> --reason "Remove this obsolete goal"
 recess --json todos delete <todo-id> --reason "Remove this disposable todo"
 recess --json todos generate-applet <todo-id> --student <kid-id> --reason "Generate this todo's applet"
@@ -258,7 +259,9 @@ recess --json rocky get --student <kid-id> --reason "Inspect the student's Rocky
 ```
 
 All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
-into the confirmed request. Applet generation is staff-only: it resolves the todo's latest learning
+into the confirmed request. `todos complete` is staff-only; `--xp` is the target total XP for the
+todo, so its preview reports prior credit and the new delta before the normal completion and reward
+side effects run. Applet generation is also staff-only: it resolves the todo's latest learning
 analysis, defaults the generated todo to tomorrow in the student's timezone, and lets the server
 select v1 or v2 for that student. A guardian cannot target another family, inspect frozen/deleted
 template history, choose todo rewards/completion/internal fields, or use the ADMIN-only

package/dist/cli.js

@@ -91,6 +91,69 @@ async function sessionStatus(config) {
     }
     return { ...result.data, authSource: config.authSource };
 }
+const DISCOVERY_ROLE_BY_SCOPE = {
+    full_admin: "ADMIN",
+    family_ai: "GUARDIAN",
+    guide_students: "GUIDE",
+    village_home: "KID",
+};
+/**
+ * Command discovery is intentionally local: the signed session cookie already
+ * carries the role, CLI scope, and expiry minted at login. Decoding those
+ * unverified claims is safe here because they only hide or reveal help text;
+ * every real command still sends the cookie to the server for authorization.
+ */
+function resolveCommandDiscovery(config) {
+    const signedOut = {
+        scope: null,
+        role: null,
+        source: "signed_out",
+    };
+    const unavailable = {
+        scope: null,
+        role: null,
+        source: "unavailable",
+    };
+    if (!config.sessionCookie)
+        return signedOut;
+    try {
+        const separator = config.sessionCookie.indexOf("=");
+        if (separator < 1)
+            return unavailable;
+        const cookieValue = decodeURIComponent(config.sessionCookie.slice(separator + 1).split(";", 1)[0]);
+        const payloadSegment = cookieValue.split(".")[1];
+        if (!payloadSegment)
+            return unavailable;
+        const value = JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return unavailable;
+        }
+        const claim = value;
+        if (typeof claim.exp !== "number" || !Number.isFinite(claim.exp)) {
+            return unavailable;
+        }
+        if (claim.exp * 1000 <= Date.now()) {
+            return signedOut;
+        }
+        const scope = typeof claim.cliScope === "string" &&
+            Object.hasOwn(DISCOVERY_ROLE_BY_SCOPE, claim.cliScope)
+            ? claim.cliScope
+            : claim.role === "ADMIN" && claim.adminCli === true
+                ? "full_admin"
+                : null;
+        if (!scope || claim.role !== DISCOVERY_ROLE_BY_SCOPE[scope]) {
+            return unavailable;
+        }
+        return {
+            scope,
+            role: DISCOVERY_ROLE_BY_SCOPE[scope],
+            source: "session_claim",
+        };
+    }
+    catch {
+        return unavailable;
+    }
+}
 async function doctor(config, reason) {
     const checks = {
         config: {
@@ -1510,19 +1573,28 @@ export async function runCommand(argv) {
                 .map((name) => `--${name}`)
                 .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
         }
-        return { help: scopedHelp(HELP, commands, []) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, [], discovery) };
     }
     if (noun === "help" || hasFlag(parsed, "help")) {
         const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
-        return { help: scopedHelp(HELP, commands, scope) };
+        const config = await resolveConfig(flagString(parsed, "profile"));
+        const discovery = resolveCommandDiscovery(config);
+        return { help: scopedHelp(HELP, commands, scope, discovery) };
     }
     validateInvocation(parsed, commands);
     if (noun === "agent-context") {
-        const profiles = await listProfiles();
+        const [profiles, config] = await Promise.all([
+            listProfiles(),
+            resolveConfig(flagString(parsed, "profile")),
+        ]);
+        const discovery = resolveCommandDiscovery(config);
         return agentContext(commands, {
             cliVersion: await readCliVersion(),
             availableProfiles: profiles.profiles.map((profile) => profile.name),
             feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+            discovery,
         });
     }
     if (noun === "profile") {
@@ -4088,6 +4160,60 @@ export async function runCommand(argv) {
                 body,
             })));
         }
+        if (verb === "complete") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const targetXp = flagNumber(parsed, "xp");
+            if (targetXp === undefined ||
+                !Number.isInteger(targetXp) ||
+                targetXp <= 0) {
+                throw new CliError("invalid_arguments", "--xp must be a positive integer. It is the target total XP credited for this todo; prior awards count toward that total.");
+            }
+            const [currentResponse, detailsResponse] = await Promise.all([
+                api.client.GET("/tutor/browser/todos/{id}/", {
+                    params: { path: { id: todoId } },
+                }),
+                api.client.GET("/admin/todos/{id}/details", {
+                    params: { path: { id: todoId } },
+                }),
+            ]);
+            const current = unwrap(currentResponse);
+            const completionXpAwarded = unwrap(detailsResponse).totalXpAwarded ?? 0;
+            if (current.status === "COMPLETED") {
+                throw new CliError("already_completed", `Todo ${todoId} ("${current.title}") is already completed with ${completionXpAwarded} completion XP credited.`);
+            }
+            const body = {
+                status: "COMPLETED",
+                xpReward: targetXp,
+                expectedUpdatedAt: current.updatedAt,
+            };
+            const newXp = Math.max(0, targetXp - completionXpAwarded);
+            const preview = {
+                action: "complete a todo through the staff reward path and set its total credited XP target",
+                target: {
+                    todoId,
+                    studentUserId: current.userId,
+                    studentName: [current.user.firstName, current.user.lastName]
+                        .filter(Boolean)
+                        .join(" ") || null,
+                    title: current.title,
+                    status: current.status,
+                    goal: current.goal,
+                },
+                request: body,
+                details: {
+                    currentXpReward: current.xpReward,
+                    alreadyAwardedXp: completionXpAwarded,
+                    targetTotalXp: targetXp,
+                    newlyAwardedXp: newXp,
+                    configuredCoinReward: current.reward,
+                    note: `The XP ledger is delta-guarded: this writes at most ${newXp} new XP so the todo reaches ${targetXp} total. Completion also claims any unawarded portion of the todo's configured ${current.reward}-coin reward, replaces its active completion analysis with a manual-completion record, records completion activity, may complete a linked goal module and its configured rewards, and may notify the parent through the normal completion pipeline.`,
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/admin/todos/{id}", {
+                params: { path: { id: todoId } },
+                body,
+            })));
+        }
         if (verb === "delete") {
             const todoId = positional(parsed, 2, "todo ID");
             const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
@@ -4156,7 +4282,7 @@ export async function runCommand(argv) {
                 body: targetDueDateISO ? { targetDueDateISO } : {},
             })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|delete|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|complete|delete|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });

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/help.js

@@ -344,6 +344,8 @@ Usage:
     [--due-date YYYY-MM-DD] [--estimated-minutes N] [--url URL] [--confirm]
   recess [--json] todos edit <todo-id> --patch-file <path/patch.json>
     [--confirm --approval-token TOKEN]
+  recess [--json] todos complete <todo-id> --xp N
+    [--confirm --approval-token TOKEN]
   recess [--json] todos delete <todo-id>
     [--confirm --approval-token TOKEN]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -33,7 +33,7 @@ recess --json skills admin get recess-admin --all-references --reason "Load staf
 
 Use `skills guardian list` or `skills admin list` when the needed skill is not obvious. Never substitute one audience for the other. A guardian session cannot fetch the admin catalog; an admin may fetch either catalog.
 
-For machine-readable discovery, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
+For machine-readable discovery filtered to the current session's locally decoded CLI scope, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. These discovery commands make no API request; `auth status` and `doctor` are the live session checks. Human help uses `◇` for shared commands and `◆` for exact-admin commands. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
 
 ## Authentication
 
@@ -41,8 +41,9 @@ For machine-readable discovery, use `recess --json agent-context`; for a smaller
 - Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
   Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
   grants family-only access, not staff access. Kids cannot approve.
-- Sessions last 12 hours and are rechecked against the live user role and permissions.
-- `auth status` inspects the current session; `auth logout` clears the stored session.
+- Sessions last 12 hours. `auth status` and `doctor` recheck the live user role and permissions;
+  discovery stays local and may reflect the minted scope until the next login.
+- `auth logout` clears the stored session.
 - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.
 
 Never print or paste session cookies, device codes, or config-file contents.

package/skill/recess-cli/agents/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.4.0",
-  "minCliVersion": "2.1.0"
+  "version": "2.5.0",
+  "minCliVersion": "2.4.0"
 }