recess-cli 2.7.0 → 2.9.0

package/dist/command-schema.js

@@ -1,6 +1,7 @@
 import { CliError } from "./errors.js";
 export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
+    "allow-possible-duplicate",
     "all-references",
     "analyzed",
     "apply",
@@ -56,6 +57,70 @@ const GLOBAL_FLAG_TYPES = {
     profile: "string",
     reason: "string",
 };
+export const RECESS_MCP_SCOPES = {
+    templatesRead: "recess:goal-templates:read",
+    templatesWrite: "recess:goal-templates:write",
+    appsRead: "recess:apps:read",
+    appsWrite: "recess:apps:write",
+    studentContextRead: "recess:students:read",
+    todoAssign: "recess:todos:assign",
+};
+const REMOTE_COMMAND_SCOPES = new Map([
+    ["goal-templates list", [RECESS_MCP_SCOPES.templatesRead]],
+    ["goal-templates get", [RECESS_MCP_SCOPES.templatesRead]],
+    ["goal-templates validate-spec", [RECESS_MCP_SCOPES.templatesWrite]],
+    ["goal-templates create", [RECESS_MCP_SCOPES.templatesWrite]],
+    ["skills guardian get", [RECESS_MCP_SCOPES.templatesRead]],
+    ["doctor", []],
+    ["help", []],
+    ["agent-context", []],
+    [
+        "apps scaffold",
+        [RECESS_MCP_SCOPES.appsRead, RECESS_MCP_SCOPES.studentContextRead],
+    ],
+    ["apps standards", [RECESS_MCP_SCOPES.appsRead]],
+    ["apps list", [RECESS_MCP_SCOPES.appsRead]],
+    [
+        "apps pull",
+        [RECESS_MCP_SCOPES.appsRead, RECESS_MCP_SCOPES.studentContextRead],
+    ],
+    ["apps preview", [RECESS_MCP_SCOPES.appsRead]],
+    ["apps status", [RECESS_MCP_SCOPES.appsRead]],
+    ["apps validate", [RECESS_MCP_SCOPES.appsWrite]],
+    ["apps publish", [RECESS_MCP_SCOPES.appsWrite]],
+    ["apps assign", [RECESS_MCP_SCOPES.appsRead, RECESS_MCP_SCOPES.todoAssign]],
+    ["students list", [RECESS_MCP_SCOPES.studentContextRead]],
+    ["students todos", [RECESS_MCP_SCOPES.studentContextRead]],
+    ["students analysis", [RECESS_MCP_SCOPES.studentContextRead]],
+]);
+const REMOTE_USAGE = new Map([
+    ["goal-templates validate-spec", "recess goal-templates validate-spec"],
+    [
+        "goal-templates create",
+        "recess goal-templates create [--coin-amount N] [--confirm --operation-key <key>]",
+    ],
+    ["apps scaffold", "recess apps scaffold [--for-todo <todo-id>]"],
+    [
+        "apps validate",
+        "recess apps validate (input.appBundle) [--confirm --operation-key <key>]",
+    ],
+    ["apps pull", "recess apps pull <project-id>"],
+    ["apps preview", "recess apps preview <project-id> --version <number>"],
+    [
+        "apps publish",
+        "recess apps publish <project-id> --version <number> [--confirm --operation-key <key>]",
+    ],
+    [
+        "apps assign",
+        "recess apps assign <project-id> --student <kid-id> [--due YYYY-MM-DD] [--confirm --operation-key <key>]",
+    ],
+]);
+const REMOTE_CONFIRMATION_COMMANDS = new Set([
+    "goal-templates create",
+    "apps validate",
+    "apps publish",
+    "apps assign",
+]);
 const LOCAL_COMMAND_NOUNS = new Set([
     "--version",
     "agent-context",
@@ -112,6 +177,15 @@ const FAMILY_AI_COMMANDS = new Set([
     "todos edit",
 ]);
 const STAFF_COMMANDS = new Set([
+    "apps assign",
+    "apps list",
+    "apps preview",
+    "apps publish",
+    "apps pull",
+    "apps scaffold",
+    "apps standards",
+    "apps status",
+    "apps validate",
     "cohorts email",
     "cohorts end",
     "cohorts get",
@@ -197,6 +271,8 @@ const STAFF_COMMANDS = new Set([
     "school update",
     "store-items list",
     "students upload-map-scores",
+    "students todos",
+    "students analysis",
     "todos complete",
     "todos delete",
     "todos restore",
@@ -324,6 +400,11 @@ function positionalBounds(usage) {
             optional += 1;
             continue;
         }
+        // `[<url>...]`: zero or more positionals (commands that also accept --file).
+        if (/^\[<[^,>]+>\.\.\.\]$/.test(token)) {
+            variadic = true;
+            continue;
+        }
         if (token.startsWith("--") ||
             token.startsWith("[") ||
             token.startsWith("(")) {
@@ -350,13 +431,26 @@ export function buildCommandSchema(help) {
             },
         ]));
         const positionals = positionalBounds(usage);
-        return commandPath(usage).map((path) => ({
-            path,
-            usage,
-            flags,
-            positionals,
-            access: commandAccess(path),
-        }));
+        return commandPath(usage).map((path) => {
+            const pathKey = path.join(" ");
+            const remoteFlags = {};
+            if (pathKey === "apps preview" || pathKey === "apps publish") {
+                remoteFlags.version = {
+                    type: "string",
+                    repeatable: false,
+                    required: false,
+                };
+            }
+            return {
+                path,
+                usage,
+                flags: { ...flags, ...remoteFlags },
+                positionals,
+                access: commandAccess(path),
+                remoteCapable: REMOTE_COMMAND_SCOPES.has(pathKey),
+                oauthScopes: REMOTE_COMMAND_SCOPES.get(pathKey) ?? [],
+            };
+        });
     });
 }
 function pathStartsWith(path, prefix) {
@@ -367,11 +461,32 @@ 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, context) {
+function remoteUsage(command) {
+    const path = command.path.join(" ");
+    const usage = (REMOTE_USAGE.get(path) ?? command.usage)
+        .replace(/^recess\s+(?:\[--json\]\s+)?/, "")
+        .replace(" (input.appBundle)", "");
+    if (path === "help" || path === "agent-context")
+        return usage;
+    return `${usage} --reason TEXT`;
+}
+const REMOTE_HELP_NOTES = [
+    "Send one command string; omit recess and --json. Quote values containing spaces.",
+    "Every command except help and agent-context requires --reason TEXT (1–1024 characters).",
+    "For writes, provide the reason in the preview; confirm using only the command, --confirm, and --operation-key.",
+    "Supply app source as input.appBundle when calling apps validate.",
+    "Guides and admins can create reusable goal templates. First load skills guardian get recess-goal-authoring --all-references; use input.template (the complete template document) for goal-templates validate-spec and create, without --file. Preview the full template, then confirm with only goal-templates create --confirm --operation-key <key>.",
+    'Example: students todos --student "Student Name" --date today --reason "Show today\'s todos at the user\'s request"',
+    "Student names must match exactly (ignoring case and extra spaces) within your roster; use an ID to disambiguate.",
+    "--date today uses the student's timezone; an explicit YYYY-MM-DD selects that calendar date. Omit --date for recent todos.",
+    "Results include the resolved date/timezone and pagination. If hasMore, repeat with --cursor nextCursor and the same filters; use the resolved date when paging today.",
+    "Report recorded todo statuses only. These results do not establish account creation, complete activity history, or whether work happened outside Recess.",
+];
+export function scopedHelp(_help, commands, scope, context, options = {}) {
     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.`);
+        throw new CliError("unknown_command", `Unknown command scope: ${scope.join(" ")}. Run \`${options.remoteOnly ? "help" : "recess --help"}\` for available commands.`);
     }
     const uniqueUsages = Array.from(new Map(matches.map((command) => [command.usage, command])).values());
     const accessLabel = context.scope
@@ -388,11 +503,17 @@ export function scopedHelp(_help, commands, scope, context) {
         "Key: ◇ shared command   ◆ admin-only command",
         "",
         "Usage:",
-        ...uniqueUsages.flatMap((command) => wrapUsage(command.usage, command.access === "admin" ? "◆" : "◇")),
+        ...uniqueUsages.flatMap((command) => wrapUsage(options.remoteOnly ? remoteUsage(command) : command.usage, command.access === "admin" ? "◆" : "◇")),
         "",
-        "Run `recess help <noun> [verb]` for a focused list.",
+        options.remoteOnly
+            ? "Run `help <noun> [verb]` for a focused list."
+            : "Run `recess help <noun> [verb]` for a focused list.",
+        ...(options.remoteOnly ? ["", ...REMOTE_HELP_NOTES] : []),
     ].join("\n");
 }
+export function remoteCommands(commands) {
+    return commands.filter((command) => command.remoteCapable);
+}
 function wrapUsage(usage, icon, width = 100) {
     const firstPrefix = `  ${icon} `;
     const continuationPrefix = "    ";
@@ -411,7 +532,7 @@ function wrapUsage(usage, icon, width = 100) {
     output.push(current);
     return output;
 }
-export function validateInvocation(parsed, commands) {
+export function validateInvocation(parsed, commands, options = {}) {
     const command = findCommandSchema(commands, parsed.positionals);
     if (!command) {
         const scope = parsed.positionals.join(" ");
@@ -422,7 +543,14 @@ export function validateInvocation(parsed, commands) {
             .map((candidate) => candidate.path.join(" "));
         throw new CliError("unknown_command", `Unknown command: ${scope || "(none)"}.`, 1, suggestions.length > 0 ? { suggestions } : undefined);
     }
-    const allowed = new Set([...Object.keys(command.flags), ...GLOBAL_FLAGS]);
+    const usage = options.remote ? remoteUsage(command) : command.usage;
+    const remoteConfirmation = options.remote && REMOTE_CONFIRMATION_COMMANDS.has(command.path.join(" "));
+    const allowed = new Set([
+        ...Object.keys(command.flags),
+        ...GLOBAL_FLAGS,
+        ...(remoteConfirmation ? ["confirm"] : []),
+    ].filter((flag) => !options.remote ||
+        !["json", "profile", "deliver", "file"].includes(flag)));
     const unknown = Array.from(parsed.flags.keys()).filter((name) => name !== "version" && !allowed.has(name));
     if (unknown.length > 0) {
         const validFlags = Array.from(allowed)
@@ -430,25 +558,27 @@ export function validateInvocation(parsed, commands) {
             .map((name) => `--${name}`);
         throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
             .map((name) => `--${name}`)
-            .join(", ")}.`, 1, { usage: command.usage, validFlags });
+            .join(", ")}.`, 1, { usage, validFlags });
     }
     const duplicate = Array.from(parsed.occurrences).find(([name, count]) => count > 1 && !command.flags[name]?.repeatable);
     if (duplicate) {
-        throw new CliError("duplicate_flag", `--${duplicate[0]} may only be passed once.`, 1, { usage: command.usage });
+        throw new CliError("duplicate_flag", `--${duplicate[0]} may only be passed once.`, 1, { usage });
     }
     const positionalCount = parsed.positionals.length;
     if (positionalCount < command.positionals.min ||
         (command.positionals.max !== null &&
             positionalCount > command.positionals.max)) {
-        throw new CliError("invalid_arguments", `Wrong number of positional arguments for ${command.path.join(" ")}.`, 1, { usage: command.usage });
+        throw new CliError("invalid_arguments", `Wrong number of positional arguments for ${command.path.join(" ")}.`, 1, { usage });
     }
     for (const [name, value] of parsed.flags) {
-        const type = command.flags[name]?.type ?? GLOBAL_FLAG_TYPES[name];
+        const type = command.flags[name]?.type ??
+            GLOBAL_FLAG_TYPES[name] ??
+            (remoteConfirmation && name === "confirm" ? "boolean" : undefined);
         if (type === "boolean" && value !== true) {
-            throw new CliError("invalid_arguments", `--${name} is a boolean flag and does not take a value.`, 1, { usage: command.usage });
+            throw new CliError("invalid_arguments", `--${name} is a boolean flag and does not take a value.`, 1, { usage });
         }
         if (type === "string" && value === true) {
-            throw new CliError("invalid_arguments", `--${name} requires a value.`, 1, { usage: command.usage });
+            throw new CliError("invalid_arguments", `--${name} requires a value.`, 1, { usage });
         }
     }
     return command;
@@ -459,33 +589,65 @@ export function agentContext(commands, options) {
         cli_version: options.cliVersion,
         session: options.discovery,
         commands: Object.fromEntries(commands
+            .filter((command) => !options.remoteOnly || command.remoteCapable)
             .filter((command) => command.path[0] !== "--version" &&
             commandIsAvailable(command, options.discovery.scope))
             .map((command) => [
             command.path.join(" "),
             {
-                usage: command.usage,
-                flags: command.flags,
+                usage: options.remoteOnly ? remoteUsage(command) : command.usage,
+                flags: options.remoteOnly &&
+                    REMOTE_CONFIRMATION_COMMANDS.has(command.path.join(" "))
+                    ? {
+                        ...Object.fromEntries(Object.entries(command.flags).filter(([name]) => !["json", "file"].includes(name))),
+                        confirm: {
+                            type: "boolean",
+                            repeatable: false,
+                            required: false,
+                        },
+                    }
+                    : options.remoteOnly
+                        ? Object.fromEntries(Object.entries(command.flags).filter(([name]) => !["json", "file"].includes(name)))
+                        : command.flags,
                 positionals: command.positionals,
                 access: command.access,
                 admin_only: command.access === "admin",
+                remote_capable: command.remoteCapable,
+                oauth_scopes: command.oauthScopes,
             },
         ])),
-        global_flags: {
-            "--json": { type: "boolean" },
-            "--profile": { type: "string" },
-            "--operation-key": { type: "string" },
-            "--reason": {
-                type: "string",
-                required_for: "every Recess API request except authentication",
-                max_length: 1024,
+        global_flags: options.remoteOnly
+            ? {
+                "--operation-key": { type: "string" },
+                "--reason": {
+                    type: "string",
+                    required_for: "every Recess API request",
+                    max_length: 1024,
+                },
+                "--help": { type: "boolean" },
+            }
+            : {
+                "--json": { type: "boolean" },
+                "--profile": { type: "string" },
+                "--operation-key": { type: "string" },
+                "--reason": {
+                    type: "string",
+                    required_for: "every Recess API request except authentication",
+                    max_length: 1024,
+                },
+                "--deliver": { type: "enum", values: ["stdout", "file:<path>"] },
+                "--help": { type: "boolean" },
             },
-            "--deliver": { type: "enum", values: ["stdout", "file:<path>"] },
-            "--help": { type: "boolean" },
-        },
+        ...(options.remoteOnly ? { instructions: REMOTE_HELP_NOTES } : {}),
         available_profiles: options.availableProfiles,
-        jobs: { commands: ["jobs list", "jobs get", "jobs prune"] },
-        feedback: { upstream_configured: options.feedbackUpstreamConfigured },
+        ...(options.remoteOnly
+            ? {}
+            : {
+                jobs: { commands: ["jobs list", "jobs get", "jobs prune"] },
+                feedback: {
+                    upstream_configured: options.feedbackUpstreamConfigured,
+                },
+            }),
     };
 }
 //# sourceMappingURL=command-schema.js.map