recess-cli 1.7.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # Recess CLI
 
-`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate, and goal-content commands. It uses the web-server OpenAPI document, authenticates through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
+`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate, and goal-content commands; GUIDE accounts receive that same student surface for the students they hold an ACTIVE tutor assignment to — not their wider class roster. It uses the web-server OpenAPI document, authenticates through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
 
 ## Install (no checkout needed)
 
@@ -47,6 +47,38 @@ recess --json auth login
 recess --json doctor
 ```
 
+## Testing against a local server
+
+`auth login` opens production SSO, so local iteration uses the env-cookie hatch instead:
+
+```bash
+export RECESS_CLI_API_ORIGIN=http://localhost:5068
+export RECESS_CLI_COOKIE='recess.auth-token=<signed-value>'
+recess --json doctor
+```
+
+To mint `<signed-value>`: sign `{sub, role, cliScope}` with the server's `JWT_SECRET` (audience = `CLIENT_ORIGIN`), then sign THAT string with `cookie.signerFactory(COOKIE_SECRET)` from `@fastify/cookie`. Two traps, both silent:
+
+- `@fastify/jwt` reads the auth cookie with `signed: true`, so a **bare JWT is rejected as "missing token"** before it is ever verified — the `@fastify/cookie` signature is not optional.
+- A **stored identity from a previous `auth login` does not describe an env-cookie session** (it may even be a different person on a different environment). Commands that branch on role ask the server whenever `authSource !== "config"`.
+
+Real SSO against a local server instead needs an `OAuthClient` row in the local database with `approved && adminCliEnabled` and redirect `http://127.0.0.1:8765/callback`, passed via `RECESS_CLI_OAUTH_CLIENT_ID`.
+
+## Interactive console (`recess ui`)
+
+```bash
+recess ui
+```
+
+A terminal console for the human half of the job: roster on the left (live-session dot, today's
+todo bar, XP, active goals), detail on the right (today's numbers, what they're working on right
+now, recent daily summaries). Refreshes every 30s. Keys: `↑↓`/`jk` move, `/` filter, `r` refresh,
+`q` quit. It is scope-aware — an ADMIN sees every student, a GUIDE sees the students they are
+actively assigned to.
+
+`ui` deliberately never touches the `--json` path: agents parse stdout, so the TUI runs before the
+JSON envelope and writes only to the terminal.
+
 ## JSON contract
 
 With `--json`, stdout contains only one JSON object.

package/dist/cli.js

@@ -148,7 +148,9 @@ Usage:
     [--confirm-destructive-changes --destructive-change-token TOKEN]
   recess [--json] goal-templates set-metadata <template-id> --expected-version N
     [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
-    [--sort-order N] [--kind SIMPLE|BLUEPRINT] [--agent-instructions-file <path>]
+    [--sort-order N] [--is-starter true|false]
+    [--setup-audience KID_FRIENDLY|PARENT_SETUP] [--kind SIMPLE|BLUEPRINT]
+    [--agent-instructions-file <path>]
     [--output-template-file <path>] [--confirm]
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
   recess [--json] goal-templates snapshot-files <template-id> [--path P]
@@ -2659,6 +2661,11 @@ export async function runCommand(argv) {
             const tags = flagString(parsed, "tags");
             const kind = flagString(parsed, "kind");
             const sortOrder = flagNumber(parsed, "sort-order");
+            const isStarterRaw = flagString(parsed, "is-starter");
+            const setupAudienceRaw = flagString(parsed, "setup-audience");
+            const isStarter = isStarterRaw === undefined
+                ? undefined
+                : assertChoice(isStarterRaw, ["true", "false"], "--is-starter") === "true";
             const body = {
                 expectedVersion,
                 ...(flagString(parsed, "title")
@@ -2682,6 +2689,12 @@ export async function runCommand(argv) {
                     }
                     : {}),
                 ...(sortOrder === undefined ? {} : { sortOrder }),
+                ...(isStarter === undefined ? {} : { isStarter }),
+                ...(setupAudienceRaw
+                    ? {
+                        setupAudience: assertChoice(setupAudienceRaw, GOAL_TEMPLATE_SETUP_AUDIENCES, "--setup-audience"),
+                    }
+                    : {}),
                 ...(kind
                     ? { kind: assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind") }
                     : {}),
@@ -2701,7 +2714,7 @@ export async function runCommand(argv) {
             // shape that caused the template incident; editing an existing spec goes
             // through the guarded /ai patch path with its destructive-change token.
             if (Object.keys(body).length === 1) {
-                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --kind, --agent-instructions-file, --output-template-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
@@ -3024,6 +3037,19 @@ export async function runCommand(argv) {
     }
     if (noun === "students") {
         if (verb === "list") {
+            // A guide has no family — their roster is the students they are
+            // actively assigned to, which the tutor surface already scopes. The
+            // stored identity is absent on an env-cookie session, so fall back to
+            // asking the server who this session belongs to.
+            // The stored identity only describes a `auth login` session; an
+            // env-cookie session may belong to someone else entirely, so ask the
+            // server rather than trusting a stale login.
+            const role = api.config.authSource === "config"
+                ? api.config.user?.role
+                : (await api.client.GET("/auth/admin-cli/session/")).data?.user.role;
+            if (role === "GUIDE") {
+                return unwrap(await api.client.GET("/tutor/students", {}));
+            }
             return unwrap(await api.client.GET("/family/kids", {
                 params: { query: { includeSelf: "false" } },
             }));

package/dist/index.js

@@ -1,9 +1,26 @@
 #!/usr/bin/env node
 import { runCommand } from "./cli.js";
 import { CliError } from "./errors.js";
-const json = process.argv.slice(2).includes("--json");
+const argv = process.argv.slice(2);
+const json = argv.includes("--json");
+// The interactive console owns the terminal, so it runs before the JSON
+// envelope machinery rather than through it.
+if (argv[0] === "ui") {
+    const { runUi } = await import("./ui/index.js");
+    try {
+        await runUi();
+        process.exit(0);
+    }
+    catch (error) {
+        const cliError = error instanceof CliError
+            ? error
+            : new CliError("unexpected_error", error instanceof Error ? error.message : String(error));
+        process.stderr.write(`Error: ${cliError.message}\n`);
+        process.exit(cliError.exitCode);
+    }
+}
 try {
-    const data = await runCommand(process.argv.slice(2));
+    const data = await runCommand(argv);
     if (typeof data === "object" && data && "help" in data && !json) {
         process.stdout.write(`${String(data.help)}\n`);
     }

package/dist/ui/app.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text, useApp, useInput } from "ink";
+import { useCallback, useEffect, useState } from "react";
+const REFRESH_MS = 30_000;
+function relative(iso) {
+    if (!iso)
+        return "never";
+    const deltaMin = Math.round((Date.now() - new Date(iso).getTime()) / 60_000);
+    if (deltaMin < 1)
+        return "just now";
+    if (deltaMin < 60)
+        return `${deltaMin}m ago`;
+    const hours = Math.round(deltaMin / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+/** done/total as a compact bar — the fastest read on "is today on track". */
+function todoBar(done, total) {
+    if (total === 0)
+        return "·".repeat(5);
+    const filled = Math.round((done / total) * 5);
+    return "█".repeat(filled) + "░".repeat(5 - filled);
+}
+export function App({ api }) {
+    const { exit } = useApp();
+    const [session, setSession] = useState(null);
+    const [rows, setRows] = useState([]);
+    const [summaries, setSummaries] = useState(null);
+    const [cursor, setCursor] = useState(0);
+    const [filter, setFilter] = useState("");
+    const [filtering, setFiltering] = useState(false);
+    const [error, setError] = useState(null);
+    const [loadedAt, setLoadedAt] = useState(null);
+    const visible = rows.filter((r) => filter ? r.name.toLowerCase().includes(filter.toLowerCase()) : true);
+    const selected = visible[Math.min(cursor, visible.length - 1)];
+    const loadRoster = useCallback(async () => {
+        try {
+            const [sessionRes, rosterRes] = await Promise.all([
+                api.client.GET("/auth/admin-cli/session/"),
+                api.client.GET("/tutor/students", {}),
+            ]);
+            const s = sessionRes.data;
+            if (s) {
+                setSession({
+                    role: s.user.role,
+                    cliScope: s.cliScope,
+                    name: [s.user.firstName, s.user.lastName].filter(Boolean).join(" "),
+                });
+            }
+            const items = (rosterRes.data?.items ?? []);
+            setRows(items);
+            setLoadedAt(new Date());
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+        }
+    }, [api]);
+    useEffect(() => {
+        void loadRoster();
+        const timer = setInterval(() => void loadRoster(), REFRESH_MS);
+        return () => clearInterval(timer);
+    }, [loadRoster]);
+    // Detail is fetched per selection rather than up front: a roster of 40
+    // students would otherwise fire 40 requests nobody asked for.
+    useEffect(() => {
+        let cancelled = false;
+        setSummaries(null);
+        if (!selected)
+            return;
+        void (async () => {
+            try {
+                const res = await api.client.GET("/tutor/students/{studentId}/daily-summaries", { params: { path: { studentId: selected.userId } } });
+                if (cancelled)
+                    return;
+                const data = res.data;
+                setSummaries(data?.items?.slice(0, 3) ?? []);
+            }
+            catch {
+                if (!cancelled)
+                    setSummaries([]);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [api, selected?.userId]);
+    useInput((input, key) => {
+        if (filtering) {
+            if (key.return || key.escape) {
+                setFiltering(false);
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setFilter((f) => f.slice(0, -1));
+                return;
+            }
+            if (input)
+                setFilter((f) => f + input);
+            return;
+        }
+        if (input === "q" || key.escape)
+            exit();
+        if (input === "r")
+            void loadRoster();
+        if (input === "/") {
+            setFilter("");
+            setFiltering(true);
+        }
+        if (key.downArrow || input === "j") {
+            setCursor((c) => Math.min(c + 1, Math.max(visible.length - 1, 0)));
+        }
+        if (key.upArrow || input === "k")
+            setCursor((c) => Math.max(c - 1, 0));
+    });
+    const liveCount = rows.filter((r) => r.liveSession).length;
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "cyan", children: "recess" }), _jsxs(Text, { dimColor: true, children: [" ", session
+                                        ? `${session.name} · ${session.role} · ${session.cliScope}`
+                                        : "connecting…"] })] }), _jsxs(Text, { dimColor: true, children: [rows.length, " students", liveCount > 0 ? ` · ${liveCount} live` : "", loadedAt ? ` · ${loadedAt.toLocaleTimeString()}` : ""] })] }), error ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "red", children: error }) })) : null, _jsxs(Box, { marginTop: 1, children: [_jsxs(Box, { flexDirection: "column", width: "55%", children: [_jsxs(Text, { dimColor: true, children: ["STUDENT".padEnd(22), "TODAY".padEnd(8), "XP".padEnd(6), "GOALS"] }), visible.length === 0 ? (_jsx(Text, { dimColor: true, children: rows.length === 0 ? "no students in scope" : "no match" })) : null, visible.map((row, index) => {
+                                const active = row.userId === selected?.userId;
+                                return (_jsxs(Text, { inverse: active, color: row.liveSession ? "green" : undefined, children: [`${row.liveSession ? "●" : " "} ${row.name}`
+                                            .slice(0, 21)
+                                            .padEnd(22), `${todoBar(row.todosToday.done, row.todosToday.total)}`.padEnd(8), `${row.todayXp}`.padEnd(6), `${row.activeGoalCount}`] }, row.userId));
+                            })] }), _jsx(Box, { flexDirection: "column", width: "45%", paddingLeft: 2, children: selected ? (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: selected.name }), _jsxs(Text, { dimColor: true, children: ["last active ", relative(selected.lastActiveAt)] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: ["todos today", " ", _jsxs(Text, { bold: true, children: [selected.todosToday.done, "/", selected.todosToday.total] }), "   ", "xp ", _jsx(Text, { bold: true, children: selected.todayXp })] }), _jsxs(Text, { children: ["active goals ", _jsx(Text, { bold: true, children: selected.activeGoalCount }), "   ", "modules done", " ", _jsx(Text, { bold: true, children: selected.modulesCompleted })] })] }), selected.liveSession ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "green", children: ["\u25CF working on ", selected.liveSession.todoTitle, " (", relative(selected.liveSession.startedAt), ")"] }) })) : null, _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "RECENT SUMMARIES" }), summaries === null ? _jsx(Text, { dimColor: true, children: "loading\u2026" }) : null, summaries?.length === 0 ? _jsx(Text, { dimColor: true, children: "none" }) : null, summaries?.map((s) => (_jsxs(Text, { children: [(s.summaryDate ?? "").slice(0, 10), " ", _jsx(Text, { dimColor: true, children: s.status ?? "" }), " ", (s.smsNotification ?? "").slice(0, 40)] }, s.id)))] })] })) : (_jsx(Text, { dimColor: true, children: "select a student" })) })] }), _jsx(Box, { marginTop: 1, children: filtering ? (_jsxs(Text, { children: ["filter: ", _jsx(Text, { bold: true, children: filter }), _jsx(Text, { dimColor: true, children: " (enter to apply, esc to stop)" })] })) : (_jsxs(Text, { dimColor: true, children: ["\u2191\u2193/jk move \u00B7 / filter", filter ? ` (${filter})` : "", " \u00B7 r refresh \u00B7 q quit"] })) })] }));
+}
+//# sourceMappingURL=app.js.map

package/dist/ui/index.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { RecessAdminApi } from "../api.js";
+import { resolveConfig } from "../config.js";
+import { CliError } from "../errors.js";
+import { App } from "./app.js";
+/**
+ * The interactive console. Kept off the JSON path on purpose: agents parse
+ * stdout, so the TUI is only reachable through its own command and never
+ * writes an envelope.
+ */
+export async function runUi() {
+    const config = await resolveConfig();
+    if (!config.sessionCookie) {
+        throw new CliError("auth_required", "No Recess CLI session found. Run `recess auth login`.");
+    }
+    const api = new RecessAdminApi(config);
+    const instance = render(_jsx(App, { api: api }));
+    await instance.waitUntilExit();
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {
@@ -26,11 +26,15 @@
     "access": "public"
   },
   "dependencies": {
-    "openapi-fetch": "^0.14.0"
+    "ink": "^7.1.1",
+    "openapi-fetch": "^0.14.0",
+    "react": "^19.2.8"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",
+    "@types/react": "^19.2.18",
     "@typescript/native-preview": "7.0.0-dev.20251015.1",
+    "esbuild": "^0.28.2",
     "openapi-typescript": "^7.8.0",
     "oxlint": "^1.28.0",
     "oxlint-tsgolint": "^0.6.0",