recess-cli 3.10.0 → 3.11.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/args.js +42 -10
- package/dist/cli.js +829 -130
- package/dist/command-schema.js +360 -109
- package/dist/commands/applications.js +10 -4
- package/dist/commands/channels.js +21 -1
- package/dist/commands/onboarding.js +6 -4
- package/dist/commands/safe-staff-operations.js +3 -2
- package/dist/commands/tuition-plans.js +43 -7
- package/dist/goal-authoring.js +774 -0
- package/dist/help.js +470 -36
- package/dist/index.js +17 -3
- package/dist/safety.js +20 -1
- package/dist/ui/app.js +1 -1
- package/package.json +3 -3
- package/skill/recess-cli/SKILL.md +56 -121
- package/skill/recess-cli/agents/version.json +2 -2
package/dist/index.js
CHANGED
|
@@ -41,9 +41,19 @@ async function withInteractiveAdmissionStage(args) {
|
|
|
41
41
|
terminal.close();
|
|
42
42
|
}
|
|
43
43
|
}
|
|
44
|
-
const
|
|
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" &&
|
|
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
|
-
|
|
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 {
|
|
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.
|
|
3
|
+
"version": "3.11.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.
|
|
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": "
|
|
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
|
|
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
|
|
15
|
+
recess --json doctor
|
|
15
16
|
```
|
|
16
17
|
|
|
17
|
-
`doctor` reports the
|
|
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
|
-
|
|
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
|
|
25
|
-
recess --json skills guardian get recess-family
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
41
|
-
- Headless
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
`
|
|
46
|
-
|
|
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
|
|
52
|
+
Never print or paste cookies, refresh tokens, device codes, or config-file contents.
|
|
53
53
|
|
|
54
54
|
## Agent contract
|
|
55
55
|
|
|
56
|
-
|
|
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
|
-
-
|
|
59
|
-
|
|
60
|
-
|
|
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 `
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
- Money
|
|
150
|
-
-
|
|
151
|
-
-
|
|
152
|
-
|
|
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
|
|
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.
|