recess-cli 3.10.0 → 3.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -41,9 +41,19 @@ async function withInteractiveAdmissionStage(args) {
41
41
  terminal.close();
42
42
  }
43
43
  }
44
- const argv = await withInteractiveAdmissionStage(process.argv.slice(2));
44
+ const typedArgv = await withInteractiveAdmissionStage(process.argv.slice(2));
45
+ const typedFlags = parseArgs(typedArgv).flags;
46
+ // JSON is the default for agents and pipes: stdout is not a terminal, or
47
+ // RECESS_CLI_JSON=1. --pretty / --no-json force human output; --json forces
48
+ // JSON. Implicit JSON is passed on as --json so commands that render
49
+ // differently for humans (tuition-plans) see one consistent mode.
50
+ const forceHuman = typedFlags.has("pretty") || typedFlags.has("no-json");
51
+ const explicitJson = typedFlags.has("json") || process.env.RECESS_CLI_JSON === "1";
52
+ const json = !forceHuman &&
53
+ (explicitJson || !process.stdout.isTTY) &&
54
+ typedArgv[0] !== "ui";
55
+ const argv = json && !typedFlags.has("json") ? [...typedArgv, "--json"] : typedArgv;
45
56
  const parsedArgv = parseArgs(argv);
46
- const json = parsedArgv.flags.has("json");
47
57
  const cliVersion = await readCliVersion();
48
58
  setRequestCliVersion(cliVersion);
49
59
  // The interactive console owns the terminal, so it runs before the JSON
@@ -74,7 +84,11 @@ try {
74
84
  const acknowledgement = { ok: true, data: delivery };
75
85
  process.stdout.write(`${json ? JSON.stringify(acknowledgement) : JSON.stringify(acknowledgement.data, null, 2)}\n`);
76
86
  }
77
- else if (typeof data === "object" && data && "help" in data && !json) {
87
+ else if (typeof data === "object" &&
88
+ data &&
89
+ "help" in data &&
90
+ !(json && explicitJson)) {
91
+ // Help stays readable text unless JSON was asked for by name.
78
92
  process.stdout.write(`${String(data.help)}\n`);
79
93
  }
80
94
  else if (json) {
package/dist/safety.js CHANGED
@@ -1,7 +1,26 @@
1
+ import { flagString } from "./args.js";
1
2
  import { CliError } from "./errors.js";
2
3
  export function requireConfirmation(confirmed, preview) {
3
4
  if (confirmed)
4
5
  return;
5
- throw new CliError("confirmation_required", "This action is a live write. Review the preview, obtain explicit human approval, then rerun with --confirm.", 2, { preview, requiredFlag: "--confirm" });
6
+ const next = typeof preview.details?.next === "string" ? preview.details.next : null;
7
+ throw new CliError("confirmation_required", next
8
+ ? `This action is a live write. Review the preview, obtain explicit human approval, then run \`${next}\`.`
9
+ : "This action is a live write. Review the preview, obtain explicit human approval, then rerun with --confirm.", 2, { preview, requiredFlag: "--confirm", ...(next ? { next } : {}) });
10
+ }
11
+ const OPERATION_KEY_PATTERN = /^op_[0-9a-f]{32}_([0-9a-f]{64})$/;
12
+ /**
13
+ * The approval token a preview-bound write checks is the operation key's
14
+ * suffix (`op_<random>_<fingerprint>`), so `--operation-key` alone carries it.
15
+ * An explicit `--approval-token` is still accepted, but must agree with the key.
16
+ */
17
+ export function resolveApprovalToken(parsed) {
18
+ const explicit = flagString(parsed, "approval-token");
19
+ const key = flagString(parsed, "operation-key");
20
+ const derived = key ? OPERATION_KEY_PATTERN.exec(key)?.[1] : undefined;
21
+ if (explicit !== undefined && derived !== undefined && explicit !== derived) {
22
+ throw new CliError("approval_mismatch", "--approval-token does not match --operation-key. Drop --approval-token: it is the operation key's suffix and is derived automatically.", 2, { requiredFlag: "--operation-key", expectedApprovalToken: derived });
23
+ }
24
+ return explicit ?? derived;
6
25
  }
7
26
  //# sourceMappingURL=safety.js.map
package/dist/ui/app.js CHANGED
@@ -1,4 +1,4 @@
1
- import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
1
+ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { Box, Text, useApp, useInput } from "ink";
3
3
  import { useCallback, useEffect, useState } from "react";
4
4
  const REFRESH_MS = 30_000;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.10.0",
3
+ "version": "3.12.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -40,7 +40,7 @@
40
40
  "devDependencies": {
41
41
  "@types/node": "^24.10.0",
42
42
  "@types/react": "^19.2.18",
43
- "@typescript/native-preview": "7.0.0-dev.20251015.1",
43
+ "@typescript/native-preview": "7.0.0-dev.20260707.2",
44
44
  "esbuild": "^0.28.2",
45
45
  "openapi-typescript": "^7.8.0",
46
46
  "oxlint": "^1.28.0",
@@ -50,7 +50,7 @@
50
50
  "@tryrecess/typescript-config": "0.0.0"
51
51
  },
52
52
  "scripts": {
53
- "build": "tsc",
53
+ "build": "tsgo",
54
54
  "client:generate": "node scripts/generate-api-types.mjs",
55
55
  "typecheck": "tsgo --noEmit",
56
56
  "format": "oxfmt --ignore-path .oxfmtignore --check",
@@ -5,154 +5,89 @@ description: Route Recess CLI work to the correct permission-scoped skill and us
5
5
 
6
6
  # Recess CLI
7
7
 
8
- Use the installed `recess` command for Recess work. This small skill is shared by every CLI user. It intentionally contains no family-specific advice, staff procedures, incident notes, billing rules, or internal implementation vocabulary.
8
+ Use the installed `recess` command. This shared router holds no family advice, staff procedures,
9
+ or internal implementation vocabulary.
9
10
 
10
11
  ## Start here
11
12
 
12
13
  ```bash
13
14
  command -v recess
14
- recess --json doctor --reason "Verify CLI connectivity, identity, and scope"
15
+ recess --json doctor
15
16
  ```
16
17
 
17
- `doctor` reports the active API origin, authenticated user, and CLI scope. Do not assume a role from the request. Use the scope returned by the server.
18
+ `doctor` reports the API origin, signed-in user, and CLI scope. Use that scope, never a role
19
+ inferred from the request. Scope `village_home` may use only `village build|library|objects|render`
20
+ on the user's own home; it cannot fetch skill catalogs or call other Recess routes.
18
21
 
19
- If the reported scope is `village_home`, use only `recess village build`, `village library`, `village objects`, and `village render`. That session is intentionally unable to fetch the guardian or admin skill catalogs or call ordinary Recess API routes; Village applies the user's own-home and object-ownership checks to every build or read.
20
-
21
- Then load the guidance for the purpose of the work:
22
+ Load the audience skill's `SKILL.md`, then only the reference it routes you to:
22
23
 
23
24
  ```bash
24
- # Parent or guardian work: kids, schedules, goals, todos, progress, memory, Rocky
25
- recess --json skills guardian get recess-family --all-references --reason "Load family workflow guidance"
26
-
27
- # Research, author, validate, or apply a goal or reusable goal template
28
- recess --json skills guardian get recess-goal-authoring --all-references --reason "Load goal authoring guidance"
29
-
30
- # Staff-only school operations
31
- recess --json skills admin get recess-admin --all-references --reason "Load staff operations guidance"
25
+ # Parent or guardian: kids, schedules, goals, todos, progress, memory, Rocky
26
+ recess --json skills guardian get recess-family
27
+ # Research, author, or apply a goal or reusable goal template
28
+ recess --json skills guardian get recess-goal-authoring
29
+ # Staff operations (full_admin), then the one playbook its table names
30
+ recess --json skills admin get recess-admin
31
+ recess --json skills admin get recess-admin --reference billing
32
32
  ```
33
33
 
34
- 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.
34
+ `skills guardian list` / `skills admin list` when unsure. Never substitute one audience for the
35
+ other; a guardian session cannot fetch the admin catalog. Catalogs cache for about an hour;
36
+ `--refresh` after a known skill edit.
35
37
 
36
- 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.
38
+ Syntax: `recess help` (noun index), `recess help <noun>` (commands, summaries, notes),
39
+ `help --all`, or `recess agent-context [noun]` (compact JSON). Discovery is local; `doctor` and
40
+ `auth status` are the live checks. Unknown commands or flags and extra arguments fail explicitly.
37
41
 
38
42
  ## Authentication
39
43
 
40
- - Workstation: `recess --json auth login` opens Recess SSO.
41
- - Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
42
- Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
43
- grants family-only access, not staff access. Kids cannot approve.
44
- - Sessions default to 12 hours. Admins can use `auth login --duration 30d` locally or
45
- `auth request --duration 30d` remotely; only an admin can approve a 30-day request. `auth status` and `doctor` recheck the live user role and permissions;
46
- discovery stays local and may reflect the minted scope until the next login.
47
- - Current CLIs hold a short-lived access token plus a refresh token and renew automatically; a
48
- revoked sign-in, a disabled account, or changed access ends the session at the next request
49
- (`auth_required` — sign in again). `auth logout` revokes the sign-in server-side and clears it.
50
- - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.
44
+ - Workstation: `recess auth login` opens Recess SSO.
45
+ - Headless: `auth request`, a human signed in to Recess approves the printed URL, then `auth poll`.
46
+ The session takes the **approver's** scope; kids cannot approve.
47
+ - Sessions last 12 hours; admins may use `--duration 30d` (only an admin approves a 30-day request).
48
+ Tokens renew automatically; a revoked sign-in or changed access ends the session with
49
+ `auth_required`. `auth logout` revokes and clears it.
50
+ - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the origin before acting.
51
51
 
52
- Never print or paste session cookies, refresh tokens, device codes, or config-file contents.
52
+ Never print or paste cookies, refresh tokens, device codes, or config-file contents.
53
53
 
54
54
  ## Agent contract
55
55
 
56
- With the local binary, always pass `--json`. Stdout contains one object:
56
+ Output is one JSON object (the default when stdout is not a terminal; `--json` forces it):
57
+ `{"ok":true,"data":…}` exit 0; `{"ok":false,"error":{code,message,details}}` exit 1;
58
+ `confirmation_required` exit 2 with `details.preview`, `operationKey`, and `next`.
57
59
 
58
- - Success: `{"ok":true,"data":{...}}`, exit 0.
59
- - Failure: `{"ok":false,"error":{"code":"...","message":"...","details":{...}}}`, exit 1.
60
- - Write awaiting approval: `confirmation_required`, exit 2, with `details.preview` and `details.requiredFlag`.
61
-
62
- Every command-driven Recess API call except `auth` requires `--reason "..."`: a specific,
63
- human-readable purpose from 1 to 1024 characters. The server records it in the CLI request audit
64
- ledger. Reuse the invocation's same reason across its preflight and execution requests. The
65
- human-only `recess ui` console is exempt.
60
+ `--reason "…"` is the audit-log purpose (1–1024 characters, never shown to families). Writes
61
+ require it and fail before any network call without it; reads default it. Text a family or record
62
+ sees has its own flag (`--message`, `--refund-reason`, `--cancel-reason`, …; see `help <noun>`).
66
63
 
67
64
  Every write is two-step:
68
65
 
69
- 1. Run without `--confirm`.
70
- 2. Show the human the complete preview, including `preview.details`.
71
- 3. Ask for explicit approval of that exact action.
72
- 4. Rerun the unchanged command with `--confirm --operation-key <operationKey>`. If the preview includes an `approvalToken`, pass it unchanged too.
73
-
74
- Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request. If a confirmed invocation is interrupted, retry the unchanged command with the same operation key; never mint a new one for an uncertain write. Inspect recovery state with `recess --json jobs get <operation-key>`.
75
-
76
- ### Hosted MCP transport
77
-
78
- Use the connector's individually named tools and their discovered argument schemas, for example
79
- `recess_students_todos({student:"…",reason:"…"})`. Discovery replaces CLI help. OAuth supplies the
80
- live user and consented scopes; never ask for cookies, local paths or profiles.
81
-
82
- Preview writes with named arguments and `reason`, show `error.details.preview`, then confirm
83
- through the same tool with **only** `{confirm:true,operationKey:"…"}`. Stored arguments and source
84
- bytes are restored server-side. Changed input or consequences require a new preview. Retain the
85
- key on interruption and inspect `recess_jobs_get`; never start a replacement for an uncertain
86
- write. `confirmation_required` is normal control flow in the returned `structuredContent`.
87
-
88
- Supply JSON/text directly, workspaces as file bundles with `baseRevision`, and binaries as
89
- `{name,content,encoding}` or scoped `{uploadHandle}` references created by `recess_upload_create`.
90
- Upload bytes to its signed URL(s); size/hash verification happens before use. Download returned
91
- bundles/authorized URLs. `/mcp/legacy` temporarily retains `recess_exec({command,input?})` for
92
- 30 days after rollout. Refresh connector metadata and consent for expanded capabilities.
93
-
94
- ## Building Studio apps (`recess apps`)
95
-
96
- Guides and guardians build Recess Studio apps in their own editor and publish them with the CLI; Studio never
97
- prompts a model for them.
98
-
99
- - `recess --json apps init <dir> --reason "..."` writes the locked scaffold plus `AGENTS.md` (the
100
- runtime + template contract, pedagogy, and design rules). Read `AGENTS.md` before editing.
101
- - Edit only `skill.js`, `model.js`, `model.css`, `params.schema.json`, `params.json`. Locked files
102
- fail validation if changed.
103
- - Write `contract.json` (the BuildContract from `AGENTS.md`) and `manifest.json`
104
- (`{title, description, template?}`) before validating.
105
- - `recess --json apps validate [dir] --reason "..."` runs Studio's deterministic validation on the
106
- uploaded files and returns `report.failReasons`; fix every reason and rerun. Nothing is published.
107
- - `recess --json apps publish [dir] --reason "..."` validates, then the independent reviewer judges
108
- the app; on pass it becomes the current version at `appUrl`. `REJECTED` carries the reviewer's
109
- findings — fix them and publish again. Both commands wait for the result (`--no-wait` to return the
110
- build id and poll with `apps status`).
111
- - `recess --json apps pull <project-id> [dir]` downloads a project you own to keep editing it.
112
- - A published `appUrl` is also a valid goal queue entry (`goals queue set`, or a template's
113
- external practice queue): each app becomes one module. Build interactive content this way rather
114
- than linking a chat artifact the kid cannot open inside Recess.
115
- - `recess --json apps standards "<words or notation>"` finds the CCSS standard for `manifest.json`
116
- (`"grade 4 adding fractions"` → `4.NF.B.3a`…); guides rarely know the codes, look them up.
117
-
118
- Hosted authoring keeps those same contracts with named tools:
119
-
120
- - `recess_apps_scaffold` returns instructions, editable files, and an optional `forTodo` brief.
121
- - Supply `appBundle` (files, contract, manifest) to `recess_apps_validate`; preview and confirm,
122
- then keep its project/version/build IDs and poll `recess_apps_status`.
123
- - Before editing an existing project, call `recess_apps_pull` and preserve its `baseVersion`.
124
- - `recess_apps_preview` previews creation of a temporary capability URL. Preview and confirm
125
- `recess_apps_publish` for the exact project/version; it reviews that validated version.
126
- - Use `assign` and optional `due` on publication for recoverable publish-and-assign, or use
127
- `recess_apps_assign` separately. A pending build retains the same operation key for retry.
128
-
129
- Two ways in. If the guide names a kid or a todo, pull the analysis first and build against it;
130
- otherwise build from their description:
131
-
132
- - `recess --json students todos --student <kid-id> [--analyzed]` lists the kid's recent todos with
133
- CCSS tags and `analyzed` (a forensic analysis exists); `recess --json students analysis --todo <id>`
134
- returns it pruned for building — patterns with `instanceKey`, root cause, prescriptions, the
135
- standard, grade band, interests. No name, no frames.
136
- - `recess --json apps init <dir> --for-todo <todo-id>` writes the scaffold plus `brief.md` (that
137
- analysis as an assignment) and remembers the kid. Build to the brief: remediate mode, items the
138
- kid would miss the observed way, `template.misconceptions` = the pattern keys.
139
- - `recess --json apps publish --assign <kid-id> [--due YYYY-MM-DD]` publishes and, on `COMPLETE`,
140
- creates the kid's todo (linked to the source todo when init used `--for-todo`). A rejected build
141
- assigns nothing. `recess --json apps assign [dir] --student <kid-id>` assigns an already-published
142
- app.
66
+ 1. Run it without `--confirm`; it previews and exits 2.
67
+ 2. Show the human the complete preview, including `details`, and get explicit approval of that
68
+ exact action.
69
+ 3. Run `recess confirm <operationKey>` (the preview's `next`): it replays the stored command from
70
+ the same machine and directory within 24 hours. Equivalent: rerun the unchanged command with
71
+ `--confirm --operation-key KEY`.
72
+
73
+ Version fences (`--expected-version`, `--expected-updated-at`) are optional: the preview pins the
74
+ current state, so a change before confirm is refused. `stale_*` errors name the current revision
75
+ and how to refresh: re-read, preview again, get fresh approval. Any changed target, payload, file,
76
+ amount, recipient, or consequence needs a new preview. Never infer approval from the request. After
77
+ an interruption, retry the same key; never mint a new one for an uncertain write. Inspect with
78
+ `recess jobs get <operation-key>`.
143
79
 
144
80
  ## Shared constraints
145
81
 
146
- - Use high-level CLI commands. The raw escape hatch is GET-only:
147
- `recess --json request get /path --reason "Inspect the exact API resource needed for this task"`.
148
- - Resolve names to exact IDs before writes. Stop on ambiguous matches.
149
- - Money uses integer cents.
150
- - Keep dates in the exact format required by command help.
151
- - Treat a 401 or `auth_required` as an authentication problem. A transport-level `fetch failed` is a network/sandbox problem, not proof that the session expired.
152
- - Use `profile list|save|use` or global `--profile` for named environments. `--deliver file:<path>` atomically stores one JSON envelope locally; authenticated webhook delivery is intentionally unavailable.
153
- - `feedback submit` records CLI friction under an operation key and optionally forwards it when an upstream endpoint is configured.
154
- - Run scoped help for syntax; load the audience skill for workflow meaning.
82
+ - The raw escape hatch is GET-only: `recess request get /path`.
83
+ - Resolve names to exact IDs before writes (`--student` also takes an exact roster name). Stop on
84
+ ambiguous matches.
85
+ - Money is integer cents; dates use the exact format `help` shows.
86
+ - A 401 or `auth_required` is an auth problem; `fetch failed` is a network or sandbox problem.
87
+ - `profile list|save|use` or `--profile` selects environments. `--deliver file:<path>` stores the
88
+ JSON envelope locally. `feedback submit` records CLI friction.
155
89
 
156
90
  ## Updating this shared skill
157
91
 
158
- `recess setup --skill-only` reinstalls this shared router and may pull a compatible server copy. The npm package deliberately ships only this skill. Guardian and admin skills are fetched after authentication and cached locally for about one hour; use `--refresh` after a known skill edit.
92
+ `recess setup --skill-only` reinstalls this router and may pull a compatible server copy. The npm
93
+ package ships only this skill; guardian and admin skills are fetched after authentication.
@@ -1,4 +1,4 @@
1
1
  {
2
- "version": "3.3.0",
3
- "minCliVersion": "3.2.0"
2
+ "version": "3.4.0",
3
+ "minCliVersion": "3.11.0"
4
4
  }