recess-cli 2.5.0 → 2.6.0

package/dist/commands/apps.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import http from "node:http";
 import path from "node:path";
 import { unwrap } from "../api.js";
 import { flagString, hasFlag } from "../args.js";
@@ -240,6 +241,7 @@ async function submit(ctx, dir, dryRun) {
         files,
         contract,
         ...(manifest.template ? { template: manifest.template } : {}),
+        ...(manifest.primitives?.length ? { primitives: manifest.primitives } : {}),
         dryRun,
     };
     const assignTo = flagString(ctx.parsed, "assign");
@@ -314,6 +316,9 @@ export async function runAppsCommand(ctx) {
         const scaffold = unwrap(await api.client.GET("/studio/scaffold"));
         const written = await writeFiles(dir, scaffold.files);
         await fs.writeFile(path.join(dir, "AGENTS.md"), agentsGuide(scaffold.docs));
+        if (scaffold.docs.forks) {
+            await fs.writeFile(path.join(dir, "FORKS.md"), scaffold.docs.forks);
+        }
         if (analysis) {
             await fs.writeFile(path.join(dir, BRIEF_FILE), briefFor(analysis));
             await writeAppLink(dir, {
@@ -337,6 +342,8 @@ export async function runAppsCommand(ctx) {
                 analysis
                     ? "Open the folder with your agent: brief.md is the assignment, AGENTS.md the contract."
                     : "Open the folder with your agent and describe what the app should teach (AGENTS.md has the contract).",
+                "Customizing the wrong-answer detour? FORKS.md explains the fork and how to shape it per misconception.",
+                'recess apps preview --reason "See it in my browser"',
                 'recess apps validate --reason "Check my app"',
                 analysis
                     ? `recess apps publish --assign ${analysis.todo.studentId} --reason "Ship it to the kid"`
@@ -344,6 +351,129 @@ export async function runAppsCommand(ctx) {
             ],
         };
     }
+    if (verb === "preview") {
+        const dir = resolveDir(ctx, 2);
+        const indexHtml = await fs
+            .readFile(path.join(dir, "index.html"), "utf8")
+            .catch(() => null);
+        if (!indexHtml) {
+            throw new CliError("invalid_arguments", `${dir} has no index.html. Run \`recess apps init\` first.`);
+        }
+        const scaffold = unwrap(await api.client.GET("/studio/scaffold"));
+        const importMap = scaffold.importMap;
+        const serveOrigin = scaffold.serveOrigin;
+        if (!importMap || !serveOrigin) {
+            throw new CliError("api_error", "This Recess server does not expose the preview import map yet.");
+        }
+        const port = Number(flagString(parsed, "port") ?? "4820");
+        const types = {
+            ".html": "text/html; charset=utf-8",
+            ".js": "text/javascript; charset=utf-8",
+            ".mjs": "text/javascript; charset=utf-8",
+            ".css": "text/css; charset=utf-8",
+            ".json": "application/json; charset=utf-8",
+            ".svg": "image/svg+xml",
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".webp": "image/webp",
+        };
+        const mapTag = `<script type="importmap">${JSON.stringify({ imports: importMap })}</script>`;
+        const server = http.createServer((req, res) => {
+            void (async () => {
+                const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+                if (urlPath.startsWith("/vendor/")) {
+                    const upstream = await fetch(`${serveOrigin}${urlPath}`).catch(() => null);
+                    if (!upstream || !upstream.ok) {
+                        res.writeHead(upstream?.status ?? 502).end();
+                        return;
+                    }
+                    res.writeHead(200, {
+                        "content-type": upstream.headers.get("content-type") ??
+                            "application/octet-stream",
+                        "cache-control": "no-store",
+                    });
+                    res.end(Buffer.from(await upstream.arrayBuffer()));
+                    return;
+                }
+                const rel = urlPath === "/" ? "index.html" : urlPath.slice(1);
+                const resolved = path.resolve(dir, rel);
+                if (resolved !== dir && !resolved.startsWith(dir + path.sep)) {
+                    res.writeHead(404).end();
+                    return;
+                }
+                const raw = await fs.readFile(resolved).catch(() => null);
+                if (raw === null) {
+                    res.writeHead(404).end("not found");
+                    return;
+                }
+                const type = types[path.extname(resolved).toLowerCase()] ??
+                    "application/octet-stream";
+                if (rel === "index.html") {
+                    let html = raw
+                        .toString("utf8")
+                        .replace(/<script\s+type="importmap">[\s\S]*?<\/script>/gi, "");
+                    html = html.includes("<head>")
+                        ? html.replace("<head>", `<head>\n${mapTag}`)
+                        : `${mapTag}\n${html}`;
+                    res.writeHead(200, {
+                        "content-type": type,
+                        "cache-control": "no-store",
+                    });
+                    res.end(html);
+                    return;
+                }
+                res.writeHead(200, {
+                    "content-type": type,
+                    "cache-control": "no-store",
+                });
+                res.end(raw);
+            })().catch(() => {
+                try {
+                    res.writeHead(500).end();
+                }
+                catch {
+                    /* response already gone */
+                }
+            });
+        });
+        await new Promise((ready) => server.listen(port, ready));
+        console.log(JSON.stringify({
+            ok: true,
+            data: {
+                url: `http://localhost:${port}/`,
+                dir,
+                note: "Serving until Ctrl-C. Vendor libraries proxy from the Studio origin; params.json is served from this folder.",
+            },
+        }));
+        await new Promise(() => {
+            /* serve until the human stops it */
+        });
+    }
+    if (verb === "primitives") {
+        const sub = parsed.positionals[2];
+        if (sub === "list") {
+            return unwrap(await api.client.GET("/studio/primitives"));
+        }
+        if (sub === "publish") {
+            const file = path.resolve(positional(parsed, 3, "primitive module file"));
+            const name = flagString(parsed, "name");
+            if (!name) {
+                throw new CliError("invalid_arguments", "--name <kebab-name> is required.");
+            }
+            const code = await fs.readFile(file, "utf8").catch(() => null);
+            if (code === null) {
+                throw new CliError("invalid_arguments", `${file} is not readable.`);
+            }
+            return unwrap(await api.client.POST("/studio/primitives", {
+                body: {
+                    name,
+                    description: flagString(parsed, "description") ?? "",
+                    code,
+                },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use: apps primitives list | apps primitives publish <file.js> --name <kebab-name> [--description TEXT].");
+    }
     if (verb === "standards") {
         const q = parsed.positionals.slice(2).join(" ").trim();
         if (!q) {
@@ -408,6 +538,6 @@ export async function runAppsCommand(ctx) {
             params: { path: { buildId } },
         }));
     }
-    throw new CliError("invalid_arguments", "Unknown apps command. Use: apps init <dir> [--for-todo <todo-id>] | apps standards <words> | apps list | apps pull <project-id> [dir] | apps validate [dir] | apps publish [dir] [--assign <student-id>] | apps assign [dir] --student <id> | apps status <build-id>.");
+    throw new CliError("invalid_arguments", "Unknown apps command. Use: apps init <dir> [--for-todo <todo-id>] | apps preview [dir] [--port N] | apps standards <words> | apps list | apps pull <project-id> [dir] | apps validate [dir] | apps publish [dir] [--assign <student-id>] | apps assign [dir] --student <id> | apps status <build-id> | apps primitives list | apps primitives publish <file.js> --name <kebab-name>.");
 }
 //# sourceMappingURL=apps.js.map

package/dist/help.js

@@ -55,6 +55,9 @@ Usage:
     --method refund|credit|tokens [--full | --amount-cents N]
     [--who-pays guide|recess] [--reason TEXT] [--confirm]
   recess [--json] apps init <dir> [--for-todo <todo-id>] [--force]
+  recess [--json] apps preview [dir] [--port N]
+  recess [--json] apps primitives list
+  recess [--json] apps primitives publish <file.js> --name <kebab-name> [--description TEXT]
   recess [--json] apps standards <query>
   recess [--json] apps list
   recess [--json] apps pull <project-id> [dir]

package/package.json

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