recess-cli 2.0.0 → 2.2.0

package/README.md

@@ -1,6 +1,13 @@
 # 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; 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` plus the preview's operation key 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. KID accounts receive only
+authenticated Village home building. 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` plus the preview's operation key after human approval.
 
 ## Install (no checkout needed)
 
@@ -40,7 +47,7 @@ Create an approved `OAuthClient` row in each Recess environment. This remains a
 
 The production row ID (`c7e34138-18f9-45b1-a2fb-26a4e3a6d739`) is the CLI's built-in default, so production login needs no client-ID setup. `--client-id`, `RECESS_CLI_OAUTH_CLIENT_ID`, and a stored client ID remain overrides for local/staging clients. The web-server decodes the assertion audience, loads that exact `OAuthClient`, and requires both `approved` and `adminCliEnabled`; there is no separate server environment allowlist. Production redirect validation is exact, so a different callback port must also be explicitly registered.
 
-The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family.
+The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family. A KID session has `village_home` scope: application-level and shared-auth fences permit only session inspection and Village assertion minting, denying every other backend route.
 
 ```bash
 recess --json auth login
@@ -156,6 +163,10 @@ current status, purchase count, and lack of feed-publication side effects in the
 it refuses non-Village item IDs. After approval, rerun the unchanged command with `--confirm` and
 the preview's `--operation-key`. The
 separate `village models` commands edit the Village island's reusable models and placements.
+`village build cmd` sends one confirmed command through Village's ordinary authenticated command
+dispatcher. `village library search|get`, `village objects list|get`, and `village render` use the
+same scoped Village identity and are own-home-only outside ADMIN. `village worlds
+export|import|promote` moves or promotes data-built worlds through the fixed admin bridge.
 
 ## Authoring learning content
 

package/dist/api.js

@@ -18,6 +18,7 @@ export class RecessAdminApi {
     reason;
     clientTag;
     client;
+    villageSessionPromise;
     constructor(config, reason, clientTag = RECESS_CLIENT_CLI) {
         this.config = config;
         this.reason = reason;
@@ -91,6 +92,28 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    async villageCommand(worldId, command) {
+        const result = await this.villageScopedRequest("/api/cli/command", {
+            method: "POST",
+            body: { worldId, command },
+        });
+        if (result &&
+            typeof result === "object" &&
+            "ok" in result &&
+            result.ok === false) {
+            const reason = "reason" in result && typeof result.reason === "string"
+                ? result.reason
+                : "Village rejected the command.";
+            throw new CliError("village_command_rejected", reason, 1, result);
+        }
+        return result;
+    }
+    async villageRead(path) {
+        if (!path.startsWith("/api/cli/") || path.startsWith("//")) {
+            throw new CliError("invalid_arguments", "Village read paths must stay under /api/cli/.");
+        }
+        return this.villageScopedRequest(path);
+    }
     async uploadVillageModel(worldId, file, fileName, metadata) {
         this.requireAuth();
         const form = new FormData();
@@ -142,6 +165,63 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    villageSession() {
+        this.requireAuth();
+        this.villageSessionPromise ??= (async () => {
+            const assertionResult = await this.client.POST("/auth/admin-cli/village-assertion/");
+            const signed = unwrap(assertionResult);
+            const exchangeResponse = await fetch(new URL("/api/auth/cli/exchange", signed.villageOrigin), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ assertion: signed.assertion }),
+            });
+            const exchangeBody = await readResponseBody(exchangeResponse);
+            if (!exchangeResponse.ok) {
+                throw apiError(exchangeResponse.status, exchangeBody);
+            }
+            const token = exchangeBody &&
+                typeof exchangeBody === "object" &&
+                "token" in exchangeBody &&
+                typeof exchangeBody.token === "string"
+                ? exchangeBody.token
+                : null;
+            if (!token) {
+                throw new CliError("invalid_response", "Village assertion exchange returned no scoped token.");
+            }
+            return { villageOrigin: signed.villageOrigin, token };
+        })();
+        return this.villageSessionPromise;
+    }
+    async villageScopedRequest(path, options = {}) {
+        const { villageOrigin, token } = await this.villageSession();
+        const response = await fetch(new URL(path, villageOrigin), {
+            method: options.method ?? "GET",
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(options.body === undefined
+                    ? {}
+                    : { "content-type": "application/json" }),
+            },
+            ...(options.body === undefined
+                ? {}
+                : { body: JSON.stringify(options.body) }),
+        });
+        const body = await readResponseBody(response);
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
 }
 export function unwrap(result) {
     if (!result.response.ok || result.data === undefined) {