tands 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tabs & Spaces
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# tands
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Developer tools for [Tabs & Spaces](https://tabsandspaces.dev) apps. Node 22 or later.
+
+```sh
+npx tands new team-notes          # a small, working app to start from
+cd team-notes && npm start         # your app, on http://localhost:5480
+npx tands dev                      # a local workspace for it, on http://localhost:5470
+```
+
+- **`tands new <folder>`** makes an app with a Custom tab, data, an action and an event. No
+  dependencies and no build step: the SDK comes built, in plain JavaScript.
+- **`tands check [manifest]`** checks a manifest (a file, or its address) as a workspace would.
+- **`tands dev [manifest address]`** stands in for a workspace: your tab as someone you choose,
+  real tokens signed with its own keys, your data in memory, your events and your actions.
+
+For your own build, the SDK is [`@tabs-and-spaces/sdk`](https://www.npmjs.com/package/@tabs-and-spaces/sdk).
+
+Docs: **https://developer.tabsandspaces.dev/tools/**
+
+MIT licensed.
+
+---
+
+In the Tabs & Spaces repository (`packages/cli`), run it as `yarn tands`. `build.mjs` bundles it
+into `dist/tands.js` and builds the SDK into `dist/sdk/` for `tands new` to copy into apps.

package/dist/sdk/tands-sdk-server.js

@@ -0,0 +1,137 @@
+// ../sdk/src/server.ts
+var TokenError = class extends Error {
+};
+async function fetchKeys(deploymentUrl, fetcher = fetch) {
+  const response = await fetcher(new URL("/api/apps/keys", deploymentUrl));
+  if (!response.ok) throw new TokenError(`Couldn't fetch the keys (${response.status}).`);
+  const body = await response.json();
+  return body.keys ?? [];
+}
+var decode = (part) => {
+  const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+};
+var json = (part) => {
+  try {
+    return JSON.parse(new TextDecoder().decode(decode(part)));
+  } catch {
+    throw new TokenError("That isn't a token.");
+  }
+};
+async function verifyToken(token, {
+  keys,
+  audience,
+  issuer,
+  now = Date.now()
+}) {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new TokenError("That isn't a token.");
+  const [headerPart, payloadPart, signaturePart] = parts;
+  const header = json(headerPart);
+  if (header.alg !== "EdDSA") throw new TokenError("Unexpected signing algorithm.");
+  const jwk = keys.find((key2) => key2.kid === header.kid && key2.crv === "Ed25519");
+  if (!jwk) throw new TokenError("Signed with a key we don't know.");
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    { kty: jwk.kty, crv: jwk.crv, x: jwk.x },
+    { name: "Ed25519" },
+    false,
+    ["verify"]
+  );
+  const valid = await crypto.subtle.verify(
+    { name: "Ed25519" },
+    key,
+    decode(signaturePart),
+    new TextEncoder().encode(`${headerPart}.${payloadPart}`)
+  );
+  if (!valid) throw new TokenError("The signature doesn't match.");
+  const payload = json(payloadPart);
+  if (payload.aud !== audience) throw new TokenError("It's meant for another app.");
+  if (issuer !== void 0 && payload.iss !== issuer) {
+    throw new TokenError("It's from another deployment.");
+  }
+  if (typeof payload.exp !== "number" || payload.exp * 1e3 <= now) {
+    throw new TokenError("It has expired.");
+  }
+  return {
+    context: payload.ctx,
+    issuer: String(payload.iss),
+    expiresAt: new Date(payload.exp * 1e3),
+    action: typeof payload.act === "string" ? payload.act : null
+  };
+}
+function dataClient({ dataKey, dataUrl }, fetcher = fetch) {
+  async function data(request) {
+    const response = await fetcher(dataUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${dataKey}` },
+      body: JSON.stringify(request)
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new DataError(
+        body?.error?.message ?? `It answered ${response.status}.`,
+        body?.error?.code ?? null
+      );
+    }
+    return body?.result;
+  }
+  return {
+    data,
+    /**
+     * Reports something that happened in your app (M9 slice 5), as your
+     * manifest's `events` declare it, for the person and place of the action.
+     * One from an agent's action starts no trigger (no loops).
+     */
+    async emit(name, fields = {}) {
+      const response = await fetcher(dataUrl.replace(/\/data$/, "/events"), {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${dataKey}` },
+        body: JSON.stringify({ name, data: fields })
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => null);
+        throw new DataError(
+          body?.error?.message ?? `It answered ${response.status}.`,
+          body?.error?.code ?? null
+        );
+      }
+    },
+    values(scope) {
+      return {
+        get: async (key) => (await data({ op: "values.get", scope, key })).value,
+        set: async (key, value) => {
+          await data({ op: "values.set", scope, key, value });
+        },
+        delete: async (key) => (await data({ op: "values.delete", scope, key })).deleted,
+        list: async () => (await data({ op: "values.list", scope })).values
+      };
+    },
+    collection(name) {
+      return {
+        list: async (options = {}) => await data({ op: "records.list", collection: name, ...options }),
+        get: async (id) => (await data({ op: "records.get", collection: name, id })).record,
+        create: async (fields) => (await data({ op: "records.create", collection: name, data: fields })).record,
+        update: async (id, fields) => (await data({ op: "records.update", collection: name, id, data: fields })).record,
+        delete: async (id) => {
+          await data({ op: "records.delete", collection: name, id });
+        }
+      };
+    }
+  };
+}
+var DataError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+export {
+  DataError,
+  TokenError,
+  dataClient,
+  fetchKeys,
+  verifyToken
+};

package/dist/sdk/tands-sdk.js

@@ -0,0 +1,203 @@
+// ../sdk/src/protocol.ts
+var PROTOCOL_VERSION = 1;
+var isRecord = (value) => typeof value === "object" && value !== null;
+function readAppMessage(data) {
+  if (!isRecord(data) || data.tands !== PROTOCOL_VERSION) return null;
+  if (data.type === "hello") return { tands: 1, type: "hello" };
+  if (data.type === "token" && typeof data.id === "string" && data.id.length <= 64) {
+    return { tands: 1, type: "token", id: data.id };
+  }
+  if (data.type === "data" && typeof data.id === "string" && data.id.length <= 64 && isRecord(data.request) && typeof data.request.op === "string") {
+    return { tands: 1, type: "data", id: data.id, request: data.request };
+  }
+  if (data.type === "event" && typeof data.id === "string" && data.id.length <= 64 && typeof data.name === "string" && data.name.length <= 40 && (data.data === void 0 || isRecord(data.data))) {
+    return {
+      tands: 1,
+      type: "event",
+      id: data.id,
+      name: data.name,
+      data: data.data ?? {}
+    };
+  }
+  return null;
+}
+function readHostMessage(data) {
+  if (!isRecord(data) || data.tands !== PROTOCOL_VERSION) return null;
+  const theme = data.theme === "dark" ? "dark" : "light";
+  switch (data.type) {
+    case "context":
+      return isRecord(data.context) && typeof data.token === "string" && typeof data.expiresAt === "string" ? {
+        tands: 1,
+        type: "context",
+        context: data.context,
+        token: data.token,
+        expiresAt: data.expiresAt,
+        theme
+      } : null;
+    case "token":
+      return typeof data.id === "string" && typeof data.token === "string" && typeof data.expiresAt === "string" ? { tands: 1, type: "token", id: data.id, token: data.token, expiresAt: data.expiresAt } : null;
+    case "data":
+      return typeof data.id === "string" ? { tands: 1, type: "data", id: data.id, result: data.result } : null;
+    case "error":
+      return typeof data.message === "string" ? {
+        tands: 1,
+        type: "error",
+        message: data.message,
+        ...typeof data.id === "string" ? { id: data.id } : {},
+        ...typeof data.code === "string" ? { code: data.code } : {}
+      } : null;
+    case "theme":
+      return { tands: 1, type: "theme", theme };
+    default:
+      return null;
+  }
+}
+
+// ../sdk/src/client.ts
+var WorkspaceError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var REFRESH_MS = 6e4;
+function connect({ timeoutMs = 1e4, window: win = window } = {}) {
+  return new Promise((resolve, reject) => {
+    const parent = win.parent;
+    if (!parent || parent === win) {
+      reject(new Error("This page isn't open in a Tabs & Spaces workspace."));
+      return;
+    }
+    let hostOrigin = null;
+    let context = null;
+    let current = { token: "", expiresAt: 0 };
+    let theme = "light";
+    let counter = 0;
+    const themeListeners = /* @__PURE__ */ new Set();
+    const waiting = /* @__PURE__ */ new Map();
+    let pending = null;
+    const send = (message) => parent.postMessage(message, hostOrigin ?? "*");
+    const timer = setTimeout(() => {
+      win.removeEventListener("message", listen);
+      reject(new Error("The workspace didn't answer."));
+    }, timeoutMs);
+    function listen(event) {
+      if (event.source !== parent) return;
+      if (hostOrigin && event.origin !== hostOrigin) return;
+      const message = readHostMessage(event.data);
+      if (!message) return;
+      switch (message.type) {
+        case "context":
+          if (context) return;
+          hostOrigin = event.origin;
+          context = message.context;
+          theme = message.theme;
+          current = { token: message.token, expiresAt: Date.parse(message.expiresAt) };
+          clearTimeout(timer);
+          resolve(connection);
+          return;
+        case "token": {
+          const waiter = waiting.get(message.id);
+          if (!waiter) return;
+          waiting.delete(message.id);
+          current = { token: message.token, expiresAt: Date.parse(message.expiresAt) };
+          waiter.resolve(message.token);
+          return;
+        }
+        case "data": {
+          const waiter = waiting.get(message.id);
+          if (!waiter) return;
+          waiting.delete(message.id);
+          waiter.resolve(message.result);
+          return;
+        }
+        case "error": {
+          const waiter = message.id ? waiting.get(message.id) : void 0;
+          if (!waiter || !message.id) return;
+          waiting.delete(message.id);
+          waiter.reject(new WorkspaceError(message.message, message.code ?? null));
+          return;
+        }
+        case "theme":
+          theme = message.theme;
+          for (const listener of themeListeners) listener(theme);
+          return;
+      }
+    }
+    function ask(message) {
+      return new Promise((ok, fail) => {
+        const id = `r${++counter}`;
+        waiting.set(id, { resolve: ok, reject: fail });
+        send(message(id));
+      });
+    }
+    const data = (request) => ask((id) => ({ tands: 1, type: "data", id, request }));
+    const connection = {
+      get context() {
+        return context;
+      },
+      get theme() {
+        return theme;
+      },
+      token() {
+        if (current.expiresAt - Date.now() > REFRESH_MS) return Promise.resolve(current.token);
+        pending ??= new Promise((ok, fail) => {
+          const id = `t${++counter}`;
+          waiting.set(id, { resolve: ok, reject: fail });
+          send({ tands: 1, type: "token", id });
+        }).finally(() => {
+          pending = null;
+        });
+        return pending;
+      },
+      data,
+      async emit(name, fields = {}) {
+        await ask((id) => ({ tands: 1, type: "event", id, name, data: fields }));
+      },
+      values(scope) {
+        return {
+          get: async (key) => (await data({ op: "values.get", scope, key })).value,
+          set: async (key, value) => {
+            await data({ op: "values.set", scope, key, value });
+          },
+          delete: async (key) => (await data({ op: "values.delete", scope, key })).deleted,
+          list: async () => (await data({ op: "values.list", scope })).values
+        };
+      },
+      collection(name) {
+        return {
+          list: async (options = {}) => await data({
+            op: "records.list",
+            collection: name,
+            ...options
+          }),
+          get: async (id) => (await data({ op: "records.get", collection: name, id })).record,
+          create: async (fields) => (await data({ op: "records.create", collection: name, data: fields })).record,
+          update: async (id, fields) => (await data({ op: "records.update", collection: name, id, data: fields })).record,
+          delete: async (id) => {
+            await data({ op: "records.delete", collection: name, id });
+          }
+        };
+      },
+      onTheme(listener) {
+        themeListeners.add(listener);
+        return () => themeListeners.delete(listener);
+      },
+      close() {
+        win.removeEventListener("message", listen);
+        for (const waiter of waiting.values()) waiter.reject(new Error("Closed."));
+        waiting.clear();
+      }
+    };
+    win.addEventListener("message", listen);
+    send({ tands: 1, type: "hello" });
+  });
+}
+export {
+  PROTOCOL_VERSION,
+  WorkspaceError,
+  connect,
+  readAppMessage,
+  readHostMessage
+};