@markusylisiurunen/tau 0.3.31 → 0.3.33

package/dist/core/static/code_mode/nook/documentation.md

@@ -0,0 +1,214 @@
+The one-shot JavaScript runtime provides these globals:
+
+- `nook.skill()`: load the configured Nook deployment's version-matched app-authoring skill.
+- `nook.sites`: list, copy, deploy, and delete sites.
+- `nook.templates`: list, copy, save, and delete editable templates.
+- `nook.kv`: get, put, import, export, delete, and list per-site JSON KV entries.
+- `docs`: this agent-facing SDK document.
+- `console`: program output. Only text written through console methods is returned; return values are ignored.
+
+Top-level `await` is supported. Calls may run concurrently with `Promise.all`.
+
+Use absolute file system paths. Generated code has no direct filesystem, process, environment, network, credential, import, timer, or `fetch` access. Nook methods are the only platform capability.
+
+## App-authoring guidance
+
+`docs` describes this agent-facing management SDK. `nook.skill()` is separate and returns the configured Nook deployment's app-authoring guide, including its browser SDK and KV contract.
+
+When authoring or modifying a Nook app, print the skill before writing the app:
+
+```js
+console.log(await nook.skill());
+```
+
+## Sites
+
+### `nook.sites.list()`
+
+Return the configured target's sites as an array.
+
+```js
+const sites = await nook.sites.list();
+for (const site of sites) {
+  console.log(`${site.slug}: ${site.url} (${site.visibility ?? "not deployed"})`);
+}
+```
+
+Each site may contain:
+
+```js
+{
+  slug: string,
+  url: string,
+  createdAt?: string,
+  updatedAt?: string,
+  latestDeploymentId?: string,
+  visibility?: "private" | "public",
+  kv?: {
+    keyCount: number,
+    bytesUsed: number,
+    maxKeys: number,
+    maxBytes: number,
+  },
+}
+```
+
+### `nook.sites.copy(site, directory)`
+
+Copy the active deployment into an existing empty directory. The site slug must be a valid non-reserved Nook slug. Files are downloaded and verified against the deployment manifest before any file is written.
+
+```js
+const copied = await nook.sites.copy("demo", "/tmp/demo-source");
+console.log(`copied ${copied.fileCount} files to ${copied.directory}`);
+```
+
+The result contains `site`, `directory`, `deploymentId`, `visibility`, `fileCount`, and `byteCount`.
+
+### `nook.sites.deploy(site, directory, options)`
+
+Deploy a static directory as the site's new active deployment. `options.visibility` is required and must be `"private"` or `"public"`; visibility never defaults implicitly. The directory must contain a root `index.html` and satisfy Nook's path, file-count, and size limits.
+
+```js
+const deployed = await nook.sites.deploy("demo", "/tmp/demo-dist", {
+  visibility: "private",
+});
+console.log(`deployed ${deployed.url} as ${deployed.visibility}`);
+```
+
+The result contains `site`, `url`, `visibility`, `deploymentId`, `fileCount`, and `byteCount`.
+
+Build app artifacts before deploying. When creating a new app, put the complete working tree under a fresh temporary directory rather than scattering files into the project, then deploy its built static output directory.
+
+### `nook.sites.delete(site)`
+
+Delete a site and its managed state.
+
+```js
+const deleted = await nook.sites.delete("demo");
+console.log(`deleted ${deleted.site}: ${deleted.deleted}`);
+```
+
+## Templates
+
+### `nook.templates.list()`
+
+Return templates as an array.
+
+```js
+const templates = await nook.templates.list();
+for (const template of templates) {
+  console.log(`${template.name}: ${template.fileCount} files, revision ${template.revisionId}`);
+}
+```
+
+Each template contains `name`, `revisionId`, `createdAt`, `updatedAt`, `fileCount`, and `byteCount`.
+
+### `nook.templates.copy(name, directory)`
+
+Copy a verified template revision into an existing empty directory.
+
+```js
+const copied = await nook.templates.copy("starter", "/tmp/new-app");
+console.log(`copied ${copied.name} to ${copied.directory}`);
+```
+
+The result contains the template summary fields plus `directory`.
+
+### `nook.templates.save(name, directory)`
+
+Save a directory as the template's new active revision. Templates use the same path, file-count, and size validation as deployments but do not require `index.html`.
+
+```js
+const saved = await nook.templates.save("starter", "/tmp/app-source");
+console.log(`saved ${saved.name} revision ${saved.revisionId}`);
+```
+
+### `nook.templates.delete(name)`
+
+Delete a template.
+
+```js
+const deleted = await nook.templates.delete("starter");
+console.log(`deleted ${deleted.template}: ${deleted.deleted}`);
+```
+
+## Per-site KV
+
+KV values must be JSON-serializable. Keys must contain 1-256 characters.
+
+### `nook.kv.get(site, key)`
+
+Return the stored JSON value directly.
+
+```js
+const settings = await nook.kv.get("demo", "settings");
+console.log(`theme: ${settings.theme}`);
+```
+
+### `nook.kv.getToFile(site, key, file)`
+
+Write the stored JSON value to a file in the session execution environment. Parent directories are created as needed. Return `{ site, key, file, bytes }`.
+
+```js
+const saved = await nook.kv.getToFile("demo", "settings", "/tmp/settings.json");
+console.log(`wrote ${saved.bytes} bytes to ${saved.file}`);
+```
+
+### `nook.kv.put(site, key, value)`
+
+Store a JSON value and return `{ site, key }`.
+
+```js
+const stored = await nook.kv.put("demo", "settings", { theme: "dark" });
+console.log(`stored ${stored.site}/${stored.key}`);
+```
+
+### `nook.kv.putFromFile(site, key, file)`
+
+Parse a JSON file from the session execution environment, store its value, and return `{ site, key, file }`. Files are limited to the 64 KiB maximum size of a KV value.
+
+```js
+const stored = await nook.kv.putFromFile("demo", "settings", "/tmp/settings.json");
+console.log(`stored ${stored.site}/${stored.key} from ${stored.file}`);
+```
+
+### `nook.kv.delete(site, key)`
+
+Delete a value and return `{ site, key, deleted }`.
+
+```js
+const deleted = await nook.kv.delete("demo", "settings");
+console.log(`deleted: ${deleted.deleted}`);
+```
+
+### `nook.kv.list(site, options?)`
+
+Return matching key metadata as an array. `options.prefix` optionally filters keys.
+
+```js
+const keys = await nook.kv.list("demo", { prefix: "todos/" });
+for (const entry of keys) {
+  console.log(`${entry.key}: ${entry.sizeBytes} bytes, updated ${entry.updatedAt}`);
+}
+```
+
+Each entry contains `key`, `sizeBytes`, and `updatedAt`.
+
+## Common patterns
+
+List sites and templates concurrently:
+
+```js
+const [sites, templates] = await Promise.all([
+  nook.sites.list(),
+  nook.templates.list(),
+]);
+console.log(`sites: ${sites.map((site) => site.slug).join(", ") || "none"}`);
+console.log(`templates: ${templates.map((template) => template.name).join(", ") || "none"}`);
+```
+
+Copy, inspect or modify with filesystem tools in later calls, build with Bash, then deploy the built directory in a later Nook call. Do not deploy an editable source directory unless it is already the complete static artifact.
+
+## Output guidance
+
+Print only information needed for the task. Prefer concise labeled text over serialized response objects. Select relevant fields when possible; when all fields matter, flatten and label them compactly. Emit JSON only when the user explicitly requests JSON or another machine-readable result.

package/dist/core/static/code_mode/nook/sandbox_runner.mjs

@@ -0,0 +1,144 @@
+import { parentPort, workerData } from "node:worker_threads";
+import "ses";
+
+if (!parentPort) {
+  throw new Error("nook sandbox requires a parent port");
+}
+if (
+  typeof workerData !== "object" ||
+  workerData === null ||
+  typeof workerData.code !== "string" ||
+  typeof workerData.docs !== "string"
+) {
+  throw new Error("nook sandbox received invalid worker data");
+}
+
+lockdown();
+
+const pending = new Map();
+let nextRequestId = 1;
+
+parentPort.on("message", (message) => {
+  if (message?.type !== "response" || typeof message.id !== "number") return;
+  const request = pending.get(message.id);
+  if (!request) return;
+  pending.delete(message.id);
+  if (message.ok) {
+    request.resolve(message.value);
+    return;
+  }
+
+  const error = new Error(message.error?.message || "Nook request failed");
+  if (message.error?.name) error.name = message.error.name;
+  request.reject(error);
+});
+
+function requestNook(method, argsJson) {
+  if (typeof method !== "string" || typeof argsJson !== "string") {
+    return Promise.reject(new Error("invalid nook bridge request"));
+  }
+  const id = nextRequestId++;
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    parentPort.postMessage({ type: "request", id, method, argsJson });
+  });
+}
+
+function writeOutput(stream, text) {
+  if ((stream !== "stdout" && stream !== "stderr") || typeof text !== "string") {
+    throw new Error("invalid console bridge output");
+  }
+  const output = stream === "stderr" ? process.stderr : process.stdout;
+  output.write(text + "\n");
+}
+
+const compartment = new Compartment({
+  globals: {
+    _requestNook: harden(requestNook),
+    _writeOutput: harden(writeOutput),
+    docs: workerData.docs,
+  },
+  __options__: true,
+});
+
+compartment.evaluate(String.raw`
+(() => {
+  const requestNookBridge = _requestNook;
+  const writeOutputBridge = _writeOutput;
+  delete globalThis._requestNook;
+  delete globalThis._writeOutput;
+
+  function formatOutputValue(value) {
+    if (typeof value === "string") return value;
+    if (value instanceof Error) return value.stack || value.message;
+    try {
+      const serialized = JSON.stringify(value);
+      if (serialized !== undefined) return serialized;
+    } catch {}
+    return String(value);
+  }
+  function writeConsole(stream, values) {
+    writeOutputBridge(stream, values.map(formatOutputValue).join(" "));
+  }
+  Object.defineProperty(globalThis, "console", {
+    value: Object.freeze({
+      debug: (...values) => writeConsole("stdout", values),
+      error: (...values) => writeConsole("stderr", values),
+      info: (...values) => writeConsole("stdout", values),
+      log: (...values) => writeConsole("stdout", values),
+      warn: (...values) => writeConsole("stderr", values),
+    }),
+  });
+  function serializeArguments(args) {
+    return JSON.stringify(args, (_key, value) => {
+      if (
+        value === undefined ||
+        typeof value === "function" ||
+        typeof value === "symbol" ||
+        typeof value === "bigint" ||
+        (typeof value === "number" && !Number.isFinite(value))
+      ) {
+        throw new TypeError("Nook arguments must be JSON-serializable values");
+      }
+      return value;
+    });
+  }
+  function callNook(method, args) {
+    return requestNookBridge(method, serializeArguments(args));
+  }
+  Object.defineProperty(globalThis, "nook", {
+    value: Object.freeze({
+      skill: (...args) => callNook("skill", args),
+      sites: Object.freeze({
+        list: (...args) => callNook("sites.list", args),
+        copy: (...args) => callNook("sites.copy", args),
+        deploy: (...args) => callNook("sites.deploy", args),
+        delete: (...args) => callNook("sites.delete", args),
+      }),
+      templates: Object.freeze({
+        list: (...args) => callNook("templates.list", args),
+        copy: (...args) => callNook("templates.copy", args),
+        save: (...args) => callNook("templates.save", args),
+        delete: (...args) => callNook("templates.delete", args),
+      }),
+      kv: Object.freeze({
+        get: (...args) => callNook("kv.get", args),
+        getToFile: (...args) => callNook("kv.getToFile", args),
+        put: (...args) => callNook("kv.put", args),
+        putFromFile: (...args) => callNook("kv.putFromFile", args),
+        delete: (...args) => callNook("kv.delete", args),
+        list: (...args) => callNook("kv.list", args),
+      }),
+    }),
+  });
+})();
+`);
+
+try {
+  await compartment.evaluate("(async () => {\n" + workerData.code + "\n})()");
+} catch (error) {
+  writeOutput("stderr", error instanceof Error ? error.stack || error.message : String(error));
+  process.exitCode = 1;
+} finally {
+  parentPort.close();
+}

package/dist/core/static/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AAEhE,MAAM,mBAAmB,GAAG;IAC1B,0BAA0B,EAAE,uCAAuC;CAC3D,CAAC;AAIX,MAAM,UAAU,mBAAmB,CAAC,QAAwB;IAC1D,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAwB;IACvD,OAAO,YAAY,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB,EAAE,MAA8B;IAC3E,MAAM,oBAAoB,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC;SACrF,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACxB,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC3D,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAEjE,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SAC5C,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACrD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC9B,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,qCAAqC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC;SAClE,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC9B,IAAI,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,yCAAyC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AACpG,CAAC;AAED,MAAM,+BAA+B,GAAG,gBAAgB,CAAC,0BAA0B,CAAC,CAAC,IAAI,EAAE,CAAC;AAE5F,MAAM,UAAU,gCAAgC;IAC9C,OAAO,+BAA+B,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,IAElD;IACC,OAAO,mBAAmB,CAAC,+BAA+B,EAAE;QAC1D,sBAAsB,EAAE,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE;KAC1D,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AAEhE,MAAM,mBAAmB,GAAG;IAC1B,0BAA0B,EAAE,uCAAuC;CAC3D,CAAC;AAIX,MAAM,UAAU,mBAAmB,CAAC,QAAwB;IAC1D,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAwB;IACvD,OAAO,YAAY,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB,EAAE,MAA8B;IAC3E,MAAM,oBAAoB,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC;SACrF,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACxB,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC3D,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAEjE,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SAC5C,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACrD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC9B,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,qCAAqC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC;SAClE,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC9B,IAAI,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,yCAAyC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AACpG,CAAC;AAED,MAAM,+BAA+B,GAAG,gBAAgB,CAAC,0BAA0B,CAAC,CAAC,IAAI,EAAE,CAAC;AAE5F,MAAM,UAAU,gCAAgC;IAC9C,OAAO,+BAA+B,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,IAElD;IACC,OAAO,mBAAmB,CAAC,+BAA+B,EAAE;QAC1D,sBAAsB,EAAE,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE;KAC1D,CAAC,CAAC;AACL,CAAC"}