recess-cli 2.9.0 → 3.0.0

package/README.md

@@ -9,6 +9,13 @@ authenticated Village home building. It uses the web-server OpenAPI document, au
 through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with
 `--confirm` plus the preview's operation key after human approval.
 
+## Version 3 changes
+
+`goals list` now shows ACTIVE and PAUSED goals by default. Add `--include-archived` to
+include COMPLETED goals (both archived and rewarded completions), and `--query` to search.
+Staff gain `cohorts schedule` and versioned `memories` file commands. Deploy their backend
+and database support before publishing this CLI; writes require a server preview.
+
 ## Install (no checkout needed)
 
 Published to npm as [`recess-cli`](https://www.npmjs.com/package/recess-cli). On any machine with Node 20+:

package/dist/args.js

@@ -19,6 +19,7 @@ const BOOLEAN_FLAGS = new Set([
     "help",
     "immediate",
     "include-deleted",
+    "include-archived",
     "mirrored",
     "no-invite",
     "no-collision",

package/dist/cli.js

@@ -9,8 +9,10 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
+import { runChatLogsCommand } from "./commands/chat-logs.js";
 import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
+import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
 import { runSchoolCommand } from "./commands/school.js";
 import { runVillageEventsCommand } from "./commands/village-events.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
@@ -251,7 +253,10 @@ async function localWriteCommand(parsed, preview, execute) {
             action: preview.action,
             fingerprint,
             target: preview.target,
-            ...(preview.action.startsWith("mastery.") ? { preview } : {}),
+            ...(preview.action.startsWith("mastery.") ||
+                preview.request.attendanceTakenAt
+                ? { preview }
+                : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -656,7 +661,12 @@ async function previewBoundWrite(parsed, preview, execute) {
         const result = await withIdempotencyContext(context, execute);
         await appendJobEvent({
             jobId: context.operationKey,
-            status: "completed",
+            status: typeof result === "object" &&
+                result !== null &&
+                "outcome" in result &&
+                result.outcome === "outcome_unknown"
+                ? "unknown"
+                : "completed",
             timestamp: new Date().toISOString(),
             action: preview.action,
             fingerprint: context.fingerprint,
@@ -2676,6 +2686,14 @@ export async function executeRecessCommand(argv, options = {}) {
     if (noun === "school") {
         return runSchoolCommand({ parsed, api, writeCommand });
     }
+    if (noun === "cohorts" && verb === "schedule")
+        return runScheduleCommand({ parsed, api, writeCommand: previewBoundWrite });
+    if (noun === "memories" && verb !== "context" && verb !== "log")
+        return runMemoryFilesCommand({
+            parsed,
+            api,
+            writeCommand: previewBoundWrite,
+        });
     if (noun === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
         if (!search)
@@ -3158,7 +3176,16 @@ export async function executeRecessCommand(argv, options = {}) {
                 excused: true,
             })),
         ];
-        const body = { attendanceTakenAt: new Date().toISOString(), attendance };
+        const operationKey = flagString(parsed, "operation-key");
+        const stored = operationKey ? await getJob(operationKey) : undefined;
+        const preparedAt = stored?.history.find((event) => event.preview?.request.attendanceTakenAt)?.preview?.request.attendanceTakenAt;
+        if (hasFlag(parsed, "confirm") && typeof preparedAt !== "string") {
+            throw new CliError("confirmation_required", "The saved attendance preview is unavailable. Request a new preview before confirming.");
+        }
+        const body = {
+            attendanceTakenAt: typeof preparedAt === "string" ? preparedAt : new Date().toISOString(),
+            attendance,
+        };
         return writeCommand(parsed, {
             action: "take attendance (non-excused absentees may trigger automatic 'we missed you' emails to parents)",
             target: { eventId },
@@ -4047,9 +4074,21 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
-            return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+            const result = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
             }));
+            const query = flagString(parsed, "query")?.toLocaleLowerCase();
+            return {
+                ...result,
+                goals: result.goals.filter((goal) => (goal.status === "ACTIVE" ||
+                    goal.status === "PAUSED" ||
+                    (hasFlag(parsed, "include-archived") &&
+                        goal.status === "COMPLETED")) &&
+                    (!query ||
+                        `${goal.title}\n${goal.description ?? ""}`
+                            .toLocaleLowerCase()
+                            .includes(query))),
+            };
         }
         if (verb === "create") {
             const requestedStudentId = flagString(parsed, "student");
@@ -4400,6 +4439,9 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|queue|files|pdf.");
     }
+    if (noun === "chat-logs") {
+        return runChatLogsCommand({ parsed, api, writeCommand });
+    }
     if (noun === "students") {
         if (verb === "list") {
             const requestedScope = flagString(parsed, "scope");

package/dist/command-schema.js

@@ -22,6 +22,7 @@ const BOOLEAN_FLAGS = new Set([
     "immediate",
     "keep-tokens",
     "include-deleted",
+    "include-archived",
     "json",
     "mirrored",
     "no-collision",
@@ -138,6 +139,9 @@ const AUTHENTICATED_COMMAND_PREFIXES = [
     "village render",
 ];
 const FAMILY_AI_COMMANDS = new Set([
+    "chat-logs by-todo",
+    "chat-logs get",
+    "chat-logs list",
     "content-library search",
     "goal-templates apply",
     "goal-templates apply-starter",
@@ -177,6 +181,16 @@ const FAMILY_AI_COMMANDS = new Set([
     "todos edit",
 ]);
 const STAFF_COMMANDS = new Set([
+    "cohorts schedule get",
+    "cohorts schedule set",
+    "cohorts schedule changes",
+    "cohorts schedule change",
+    "memories files",
+    "memories read",
+    "memories edit",
+    "memories history",
+    "memories revision",
+    "memories restore",
     "apps assign",
     "apps list",
     "apps preview",

package/dist/commands/chat-logs.js

@@ -0,0 +1,43 @@
+import { unwrap } from "../api.js";
+import { flagNumber, flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { positional } from "./shared.js";
+export async function runChatLogsCommand({ parsed, api, }) {
+    const verb = parsed.positionals[1];
+    if (verb === "list") {
+        const limit = flagNumber(parsed, "limit");
+        if (limit !== undefined &&
+            (!Number.isInteger(limit) || limit < 1 || limit > 500)) {
+            throw new CliError("invalid_arguments", "--limit must be an integer from 1 to 500.");
+        }
+        return unwrap(await api.client.GET("/ai/chat-logs", {
+            params: {
+                query: {
+                    studentId: flagString(parsed, "student", { required: true }),
+                    limit,
+                    cursor: flagString(parsed, "cursor"),
+                },
+            },
+        }));
+    }
+    const query = verb === "get"
+        ? { conversationId: positional(parsed, 2, "conversation ID") }
+        : { todoId: positional(parsed, 2, "todo ID") };
+    const messages = [];
+    let cursor;
+    const seenCursors = new Set();
+    do {
+        const page = unwrap(await api.client.GET("/ai/chat-logs/messages", {
+            params: { query: { ...query, limit: 500, cursor } },
+        }));
+        messages.push(...page.messages);
+        if (!page.nextCursor)
+            return { ...page, messages, complete: true };
+        if (seenCursors.has(page.nextCursor)) {
+            throw new CliError("pagination_error", "Chat-log pagination did not advance; no complete download was produced.");
+        }
+        seenCursors.add(page.nextCursor);
+        cursor = page.nextCursor;
+    } while (cursor);
+}
+//# sourceMappingURL=chat-logs.js.map

package/dist/commands/safe-staff-operations.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { appendJobEvent } from "../jobs.js";
+import { assertChoice, positional } from "./shared.js";
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function recoveryKey(ctx) {
+    if (!hasFlag(ctx.parsed, "confirm"))
+        return undefined;
+    const key = flagString(ctx.parsed, "operation-key");
+    const token = flagString(ctx.parsed, "approval-token");
+    if (key && (!token || !key.endsWith(`_${token}`)))
+        throw new CliError("approval_mismatch", "Recovery requires the original operation key and approval token.");
+    return key;
+}
+async function recovered(ctx, row, expectedInputHash) {
+    if (row.inputHash !== expectedInputHash)
+        throw new CliError("approval_mismatch", "This operation key belongs to different input. No operation was retried.");
+    await appendJobEvent({
+        jobId: row.operationKey,
+        status: row.outcome === "outcome_unknown" ? "unknown" : "completed",
+        timestamp: new Date().toISOString(),
+        action: "recover staff operation",
+        fingerprint: flagString(ctx.parsed, "approval-token"),
+        target: { apiOrigin: ctx.api.config.apiOrigin },
+        result: row,
+    });
+    return row;
+}
+export async function runScheduleCommand(ctx) {
+    const { api, parsed, writeCommand } = ctx;
+    const action = positional(parsed, 2, "schedule action");
+    const id = positional(parsed, 3, "cohort or change ID");
+    if (action === "change")
+        return unwrap(await api.client.GET("/admin/cohorts/schedule-changes/{changeId}", {
+            params: { path: { changeId: id } },
+        }));
+    const params = { path: { id } };
+    if (action === "get")
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/", { params }));
+    if (action === "changes")
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/changes", {
+            params: { ...params, query: { cursor: flagString(parsed, "cursor") } },
+        }));
+    if (action !== "set")
+        throw new CliError("invalid_arguments", "Use cohorts schedule get|set|changes|change.");
+    const input = {
+        days: flagString(parsed, "days", { required: true })
+            .split(",")
+            .map((d) => assertChoice(d.trim().toUpperCase(), ["MO", "TU", "WE", "TH", "FR", "SA", "SU"], "weekday")),
+        time: flagString(parsed, "time", { required: true }),
+        timezone: flagString(parsed, "timezone"),
+        effectiveDate: flagString(parsed, "effective-date", { required: true }),
+        notify: assertChoice(flagString(parsed, "notify", { required: true }), ["none", "parents"], "notify"),
+        reason: flagString(parsed, "reason", { required: true }).trim(),
+    };
+    const key = recoveryKey(ctx);
+    if (key) {
+        const history = unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/changes", {
+            params: { ...params, query: { operationKey: key } },
+        }));
+        if (history.changes[0])
+            return recovered(ctx, history.changes[0], hash({ id, input }));
+    }
+    const capability = unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/", { params }));
+    if (capability.capabilityVersion !== 1 || !capability.supported)
+        throw new CliError("unsupported_backend", capability.unsupportedReason ??
+            "Backend does not support safe schedule changes.");
+    const preview = unwrap(await api.client.POST("/admin/cohorts/{id}/schedule/preview", {
+        params,
+        body: input,
+    }));
+    return writeCommand(parsed, {
+        action: "change recurring cohort schedule",
+        target: { cohortId: id, apiOrigin: api.config.apiOrigin },
+        request: input,
+        details: preview,
+    }, async () => {
+        const result = unwrap(await api.client.POST("/admin/cohorts/{id}/schedule/apply", {
+            params,
+            body: {
+                ...input,
+                operationKey: flagString(parsed, "operation-key", {
+                    required: true,
+                }),
+                fingerprint: preview.fingerprint,
+            },
+        }));
+        return unwrap(await api.client.GET("/admin/cohorts/schedule-changes/{changeId}", {
+            params: { path: { changeId: result.id } },
+        }));
+    });
+}
+export async function runMemoryFilesCommand(ctx) {
+    const { parsed, api, writeCommand } = ctx;
+    const action = positional(parsed, 1, "memory action");
+    const studentId = flagString(parsed, "student", { required: true });
+    const params = { path: { studentId } };
+    if (action === "files")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files", {
+            params,
+        }));
+    const memoryPath = flagString(parsed, "path", { required: true });
+    if (action === "read")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/read", {
+            params: { ...params, query: { path: memoryPath } },
+        }));
+    if (action === "history")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/history", {
+            params: {
+                ...params,
+                query: { path: memoryPath, cursor: flagString(parsed, "cursor") },
+            },
+        }));
+    if (action === "revision")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/revision", {
+            params: {
+                ...params,
+                query: {
+                    path: memoryPath,
+                    revision: flagString(parsed, "revision", { required: true }),
+                },
+            },
+        }));
+    if (action !== "edit" && action !== "restore")
+        throw new CliError("invalid_arguments", "Use memories files|read|edit|history|revision|restore.");
+    let content;
+    let contentFile;
+    if (action === "edit") {
+        contentFile = path.resolve(flagString(parsed, "content-file", { required: true }));
+        const info = await fs.lstat(contentFile);
+        if (!info.isFile() ||
+            info.isSymbolicLink() ||
+            (await fs.realpath(contentFile)) !== contentFile)
+            throw new CliError("invalid_file", "Memory input must be a regular file without symlink components.");
+        content = new TextDecoder("utf-8", { fatal: true }).decode(await fs.readFile(contentFile));
+    }
+    const input = {
+        path: memoryPath,
+        content,
+        revision: action === "restore"
+            ? flagString(parsed, "revision", { required: true })
+            : undefined,
+        action,
+        reason: flagString(parsed, "reason", { required: true }).trim(),
+    };
+    const key = recoveryKey(ctx);
+    if (key) {
+        const result = unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/operation", { params: { ...params, query: { operationKey: key } } }));
+        if (result.operation)
+            return recovered(ctx, result.operation, hash({ studentId, input }));
+    }
+    const preview = unwrap(await api.client.POST("/tutor/students/{studentId}/memory-files/preview", {
+        params,
+        body: input,
+    }));
+    if (preview.capabilityVersion !== 1 || preview.writeSupported !== true)
+        throw new CliError("unsupported_backend", preview.writeUnsupportedReason ??
+            "Backend does not support safe staff memory edits and restores.");
+    return writeCommand(parsed, {
+        action: `${action} student memory file`,
+        target: { studentId, path: memoryPath, apiOrigin: api.config.apiOrigin },
+        request: { ...input, contentFile },
+        details: {
+            ...preview,
+            before: { ...preview.before, revision: undefined },
+        },
+    }, async () => unwrap(await api.client.POST("/tutor/students/{studentId}/memory-files/apply", {
+        params,
+        body: {
+            ...input,
+            expectedHash: preview.before.contentSha,
+            fingerprint: preview.fingerprint,
+            operationKey: flagString(parsed, "operation-key", {
+                required: true,
+            }),
+        },
+    })));
+}
+//# sourceMappingURL=safe-staff-operations.js.map

package/dist/help.js

@@ -51,6 +51,9 @@ Usage:
     --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
   recess [--json] students upload-map-scores --student <kid-id>
     --file </path/to/map-report.pdf> [--confirm]
+  recess [--json] chat-logs list --student <user-id> [--limit 100] [--cursor <cursor>]
+  recess [--json] chat-logs get <conversation-id>
+  recess [--json] chat-logs by-todo <todo-id>
   recess [--json] students list [--scope mine|family]
   recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
   recess [--json] students schedule --student <kid-id> [--days 14]
@@ -140,6 +143,10 @@ Usage:
     [--description TEXT] [--date YYYY-MM-DD] [--confirm]
   recess [--json] payout items delete <item-id> [--confirm]
   recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
+  recess [--json] cohorts schedule get <cohort-id>
+  recess [--json] cohorts schedule set <cohort-id> --days <MO,WE> --time <09:30> [--timezone <zone>] --effective-date <YYYY-MM-DD> --notify none|parents [--confirm] [--approval-token <token>]
+  recess [--json] cohorts schedule changes <cohort-id> [--cursor <cursor>]
+  recess [--json] cohorts schedule change <change-id>
   recess [--json] cohorts parent-emails <cohort-id>
   recess [--json] cohorts end <cohort-id> [--cancel-subscriptions] [--confirm]
   recess [--json] cohorts pause-billing <cohort-id> --weeks 1..6 [--confirm]
@@ -357,7 +364,7 @@ Usage:
     [--dry-run] [--confirm --approval-token TOKEN]
   recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
     [--answers-file <path>] [--confirm]
-  recess [--json] goals list --student <kid-id>
+  recess [--json] goals list --student <kid-id> [--query <text>] [--include-archived]
   recess [--json] goals create [--student <kid-id>] --title TEXT
     (--description TEXT | --description-file <path>) [--target-date <iso>]
     [--schedule TEXT] [(--draft <draft-slug> | --source-dir <local-checkout>)
@@ -392,6 +399,14 @@ Usage:
   recess [--json] todos generate-learning-analysis <todo-id> [--confirm]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>
     [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
+  recess [--json] memories files --student <kid-id>
+  recess [--json] memories read --student <kid-id> --path <path>
+  recess [--json] memories edit --student <kid-id> --path <path> --content-file <file> [--confirm] [--approval-token <token>]
+  recess [--json] memories history --student <kid-id> --path <path> [--cursor <cursor>]
+  recess [--json] memories revision --student <kid-id> --path <path> --revision <revision>
+  recess [--json] memories restore --student <kid-id> --path <path> --revision <revision> [--confirm] [--approval-token <token>]
+    Staff memory edit/restore publication is disabled pending recoverable immutable history.
+    Reads, history, and recovery of existing operations remain available.
   recess [--json] memories context --student <kid-id>
   recess [--json] memories log --student <kid-id> --date YYYY-MM-DD
   recess [--json] rocky get --student <kid-id>

package/package.json

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

package/skill/recess-cli/SKILL.md

@@ -72,18 +72,21 @@ Any changed target, payload, local file, server revision, amount, recipient, or
 
 ### Hosted MCP transport
 
-When this skill is reached through the hosted Recess connector, use its only tool,
-`recess_exec({argv,input?})`. `argv` starts with the command noun, omits both `recess` and `--json`,
-and still carries `--reason`. The CLI envelope is returned in MCP `structuredContent`; a
-`confirmation_required` envelope is expected control flow, while other failures are tool errors.
-Start with `argv:["agent-context"]` or `argv:["help","apps"]` for the remote-only catalog. OAuth
-already supplies the live user and scopes: never ask for cookies, profiles, local paths, or
-`--deliver`.
-
-Hosted writes stage the exact argv and structured payload on the server. Preview without
-`--confirm`, show the human `error.details.preview`, then confirm with the same command path plus
-`--confirm --operation-key <key>` and **omit `input`**. The server executes the stored bytes; changed
-source, flags, project/version, or operation keys require a fresh preview.
+Use the connector's individually named tools and their discovered argument schemas, for example
+`recess_students_todos({student:"…",reason:"…"})`. Discovery replaces CLI help. OAuth supplies the
+live user and consented scopes; never ask for cookies, local paths or profiles.
+
+Preview writes with named arguments and `reason`, show `error.details.preview`, then confirm
+through the same tool with **only** `{confirm:true,operationKey:"…"}`. Stored arguments and source
+bytes are restored server-side. Changed input or consequences require a new preview. Retain the
+key on interruption and inspect `recess_jobs_get`; never start a replacement for an uncertain
+write. `confirmation_required` is normal control flow in the returned `structuredContent`.
+
+Supply JSON/text directly, workspaces as file bundles with `baseRevision`, and binaries as
+`{name,content,encoding}` or scoped `{uploadHandle}` references created by `recess_upload_create`.
+Upload bytes to its signed URL(s); size/hash verification happens before use. Download returned
+bundles/authorized URLs. `/mcp/legacy` temporarily retains `recess_exec({command,input?})` for
+30 days after rollout. Refresh connector metadata and consent for expanded capabilities.
 
 ## Building Studio apps (`recess apps`)
 
@@ -106,20 +109,16 @@ prompts a model for them.
 - `recess --json apps standards "<words or notation>"` finds the CCSS standard for `manifest.json`
   (`"grade 4 adding fractions"` → `4.NF.B.3a`…); guides rarely know the codes, look them up.
 
-Hosted authoring keeps those same contracts but carries no folder:
-
-- `apps scaffold [--for-todo <id>]` returns authoring instructions, the five editable starter
-  files, fork guidance, and an optional learner brief. It performs no write.
-- Generate `input.appBundle` with exactly `skill.js`, `model.js`, `model.css`,
-  `params.schema.json`, and `params.json`, plus `contract` and `manifest`. Preview and confirm
-  `apps validate`; keep the returned project/version/build IDs and poll `apps status <build-id>`.
-- Fix findings in the bundle. For an existing project, first `apps pull <project-id>` and preserve
-  its `baseVersion`; a stale version is a conflict, never an overwrite.
-- `apps preview <project-id> --version <n>` returns the short-lived capability URL.
-  Preview/confirm `apps publish <project-id> --version <n>`, then poll its build. Publication sends
-  no source and reviews exactly that validated version.
-- After publication, preview/confirm `apps assign <project-id> --student <id> [--due YYYY-MM-DD]`.
-  Assignment is intentionally separate from hosted publish.
+Hosted authoring keeps those same contracts with named tools:
+
+- `recess_apps_scaffold` returns instructions, editable files, and an optional `forTodo` brief.
+- Supply `appBundle` (files, contract, manifest) to `recess_apps_validate`; preview and confirm,
+  then keep its project/version/build IDs and poll `recess_apps_status`.
+- Before editing an existing project, call `recess_apps_pull` and preserve its `baseVersion`.
+- `recess_apps_preview` previews creation of a temporary capability URL. Preview and confirm
+  `recess_apps_publish` for the exact project/version; it reviews that validated version.
+- Use `assign` and optional `due` on publication for recoverable publish-and-assign, or use
+  `recess_apps_assign` separately. A pending build retains the same operation key for retry.
 
 Two ways in. If the guide names a kid or a todo, pull the analysis first and build against it;
 otherwise build from their description:

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

@@ -1,4 +1,4 @@
 {
-  "version": "2.6.0",
-  "minCliVersion": "2.6.1"
+  "version": "3.0.0",
+  "minCliVersion": "3.0.0"
 }