recess-cli 1.0.1 → 1.3.0

package/README.md

@@ -13,7 +13,7 @@ recess setup
 
 `setup` installs the bundled skill for both Codex and Claude and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
 
-Publishing is a manual GitHub Action (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR, then run the workflow. It publishes with `pnpm`, not `npm`, because the manifest uses the workspace `catalog:` protocol for `openapi-fetch` and only pnpm rewrites it to a real range in the tarball.
+Publishing rides the production deploy (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR to `staging`, and it publishes when `staging` promotes to `production`. A production deploy that did not bump the version is a no-op — a `gate` job checks the version against npm first. The same workflow is still dispatchable by hand for out-of-band releases. pnpm packs the CLI so the workspace `catalog:` dependency becomes a real range; npm publishes that tarball through the `admin-cli-publish.yml` OIDC trusted publisher configured on npmjs.com.
 
 ## Install (from a checkout — CLI development)
 
@@ -25,7 +25,7 @@ pnpm --dir apps/admin-cli run client:generate
 pnpm --dir apps/admin-cli run install-persistent
 ```
 
-`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops).
+`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops, onboarding, and goal authoring).
 
 ## One-time SSO setup
 
@@ -92,4 +92,57 @@ human explicitly approves the exceptional `--allow-strand` override.
 
 MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing tutor-dashboard extraction route.
 
-See `recess --help` for the complete P0 command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.
+## Authoring learning content
+
+```bash
+recess --json skills get os-v2-goal-template-builder --all-references
+recess --json goal-templates validate-spec --file ./template.json   # iterate; writes nothing
+recess --json goal-templates create --file ./template.json          # preview, exit 2
+recess --json goal-templates create --file ./template.json --confirm
+recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
+recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
+recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md
+recess --json mesa files list --student <kid-id> --goal <goal-id>
+```
+
+## Keeping the agent skill current
+
+```bash
+recess --json --version          # {cliVersion, skillVersion}
+recess --json doctor             # .skill reports whether a newer bundle exists
+recess --json setup --skill-only # bundled copy, then the served upgrade
+```
+
+The CLI's own agent skill is **both** bundled in this package and served from
+`GET /admin/cli-skill/`. The bundled copy is the floor — it works offline, before a session exists,
+and always matches the installed binary; `postinstall` refreshes it on every `npm install -g`. The
+served copy is the upgrade: wording and Gotcha edits reach installed CLIs on the next deploy instead
+of the next npm release, fenced by the bundle's `minCliVersion` so an older binary keeps its bundled
+copy rather than reading a skill written for a newer one. An unreachable server is never an error.
+
+`skills` (plural, a different thing) serves the in-product tutor skills — the same documents the `recess.gg/ai` agent loads —
+read-only over your admin session from the **private** `packages/skills` submodule. They are
+deliberately **not** bundled into this package, which is published publicly on npm: one source of
+truth, and a skills-repo update reaches CLI agents with no CLI release. Load
+`os-v2-goal-template-builder` before authoring; a spec that passes `validate-spec` is structurally
+valid, not good. Responses cache under `~/.recess-cli/skills-cache/` (`--refresh` re-fetches).
+
+Every template created here is `setupMode: DETERMINISTIC_WORKFLOW` and **cannot be converted back**,
+so the confirmation gate is load-bearing. `create` runs a real server-side validation before the
+gate, so `preview.details` carries the handler, goal shape, wizard step keys, and spec inventory the
+*server* resolved rather than a client-side guess; `apply` runs the backend's own `dryRun` and
+previews the per-student outcome. `set-metadata` and `delete` require `--expected-version` from
+`get`; a stale value 409s `STALE_WRITE` without writing. `set-metadata` cannot send a
+`setupWorkflowSpec` at all. Use `patch-spec` with a JSON array of bounded JSON-Pointer operations;
+it always runs the backend's guarded preview first and requires the preview's exact loss token in
+addition to `--confirm` when protected template data would be removed.
+
+MODULE_BACKED BLUEPRINT content is authored as a local workspace tree, batch-upserted to a named
+Mesa draft, then attached with `capture-snapshot`. Both mutations run server previews before the
+confirmation gate. Mesa upserts are compare-and-set against the previewed repo change; capture is
+fenced to both that source change and the template version. Direct live-goal `modules/` and
+`state/` writes are blocked because those files have database projections.
+
+See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/args.js

@@ -1,23 +1,45 @@
 import { CliError } from "./errors.js";
+/**
+ * Flags that may legitimately appear more than once. Reading one through
+ * `flagString` still yields the LAST value, which is why every consumer of a
+ * repeatable flag must use `flagList` instead.
+ */
+export const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
 const BOOLEAN_FLAGS = new Set([
+    "all-references",
     "allow-strand",
     "cancel-subscriptions",
     "archived",
     "confirm",
+    "dry-run",
     "full",
     "help",
     "immediate",
+    "include-deleted",
     "mirrored",
     "no-collision",
     "json",
+    "refresh",
     "restore",
     "revoke",
     "send-email",
+    "spec-only",
+    "starter-only",
     "visual-only",
 ]);
 export function parseArgs(args) {
     const positionals = [];
     const flags = new Map();
+    const repeated = new Map();
+    const record = (name, value) => {
+        if (!REPEATABLE_FLAGS.has(name))
+            return;
+        const existing = repeated.get(name);
+        if (existing)
+            existing.push(value);
+        else
+            repeated.set(name, [value]);
+    };
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
         if (!value.startsWith("--")) {
@@ -26,7 +48,10 @@ export function parseArgs(args) {
         }
         const equalsAt = value.indexOf("=");
         if (equalsAt > 2) {
-            flags.set(value.slice(2, equalsAt), value.slice(equalsAt + 1));
+            const name = value.slice(2, equalsAt);
+            const flagValue = value.slice(equalsAt + 1);
+            flags.set(name, flagValue);
+            record(name, flagValue);
             continue;
         }
         const name = value.slice(2);
@@ -37,13 +62,29 @@ export function parseArgs(args) {
         const next = args[index + 1];
         if (next && !next.startsWith("--")) {
             flags.set(name, next);
+            record(name, next);
             index += 1;
         }
         else {
             flags.set(name, true);
         }
     }
-    return { positionals, flags };
+    return { positionals, flags, repeated };
+}
+/**
+ * Every value given for a repeatable flag, in order.
+ *
+ * Returns `[]` when the flag is absent, so a caller distinguishes "none given"
+ * from "given empty" by checking length rather than by a null dance.
+ */
+export function flagList(parsed, name) {
+    if (!REPEATABLE_FLAGS.has(name)) {
+        // A wiring defect, not a user error: reading a non-repeatable flag as a
+        // list would silently return [] however many times it was passed.
+        throw new CliError("invalid_arguments", `--${name} is not declared repeatable; add it to REPEATABLE_FLAGS.`);
+    }
+    const values = parsed.repeated.get(name) ?? [];
+    return values.map((value) => value.trim()).filter(Boolean);
 }
 export function flagString(parsed, name, options = {}) {
     const value = parsed.flags.get(name);