@wyndlass/app-sdk 0.0.0 → 1.1.0

package/README.md

@@ -1,3 +1,214 @@
 # @wyndlass/app-sdk
 
-A placeholder. The first release of Wyndlass's app SDK is 1.0.0.
+Build your own apps for Wyndlass's screens. An app is a web component, written in TypeScript or React. You import it into your organization, a person reviews it, and layouts place it like any of Wyndlass's own apps.
+
+This package has:
+- the runtime Wyndlass's own apps are built on;
+- a React adapter;
+- two templates;
+- the command `wyndlass-app`, which previews, checks and packs an app;
+- a skill that builds, imports and schedules an app with your coding agent.
+
+It needs Node 20 or later. MIT licensed, © Northwynd Labs LLC.
+
+## Before you start
+
+- **Imported apps must be on** where you import: an Owner or Admin turns them on in the CMS, under **Settings**, **Imported apps**.
+- **To import an app,** you need a role that may add media at that place. A later version goes to the app where it already is, so it needs that role there.
+- **Versions are reviewed:** a person who may approve media approves an app's first version, and any later version that asks for more than the one before it.
+- **Screens play an approved version** only where their player can run imported apps. A screen whose player is too old leaves the app out, and plays the rest of the layout.
+
+## Start an app
+
+```sh
+npx @wyndlass/app-sdk create queue-board --template react --id com.example.queue-board
+cd queue-board
+npm install
+npm run preview
+```
+
+`create` makes a working app from a template:
+- `react`: a React component, rendered in the app's shadow root;
+- `vanilla`: TypeScript on `WyndlassApp`, with no framework.
+
+Each template is a small app with two pages: a heading and the time, then the weather. It has params of four kinds, says `ready()`, and shows the weather the screen kept while it asks again. The project has a README, an `AGENTS.md` for coding agents, and the scripts `preview`, `check`, `pack` and `typecheck`.
+
+The id is a reverse-domain name in your organization's own domain. Ids under `com.wyndlass.` are Wyndlass's, and are refused.
+
+## With a coding agent
+
+```sh
+npx @wyndlass/app-sdk skill install
+```
+
+It adds the skill `wyndlass-app` to the project's `.claude/skills/`, where Claude Code finds it. With `--user`, it goes in `~/.claude/skills/` instead, for every project. Running it again replaces the copy with this version's.
+
+Then ask your agent for the app you want. The skill:
+1. asks what the app shows and to whom, the screens' orientation, the data it needs, and its name and id;
+2. makes it from a template, and previews it with you in both orientations and in the CMS's frame;
+3. checks and packs it;
+4. imports, places and schedules it through the Wyndlass MCP, asking you before each.
+
+The agent never approves a version: a person does, in the CMS.
+
+## Preview it
+
+`npm run preview` (`wyndlass-app preview`) runs the app as screens run it, at `http://127.0.0.1:5199/`, on your computer only. The page is the same host Wyndlass's players run, with the same contract, deadline and error handling. It draws the app again whenever a source or `app.json` changes, and says why when a source doesn't build.
+
+Its controls:
+- **The screen:** its size (1920 × 1080, 1080 × 1920, 3840 × 2160, or any), its name, place and fields, the time zone and the locale.
+- **The app's params,** each shown while its `when` holds, as in the designer.
+- **The clock:** play, pause, seek, and speeds from 0.25× to 4×.
+- **Enter and exit,** with each preset and how long it lasts, and the app's pages.
+- **Data:** each data source's answer, from samples you can edit in the page. `--data <dir>` reads `<source>.json` there instead (the answer's `data`, or a whole answer). The preview reaches no data service. A source the definition doesn't declare gets no answer, as on a screen.
+- **Tables:** each file in `<dir>/tables/`, or one you add in the page. A file may be CSV (its header gives the columns), a JSON array of rows, or a snapshot. A `datatable` param chooses among them, and an app with `slots` is bound to the first.
+- **The people at the screen,** for an app that declares the `impressions` sensor: someone arrives, looks, or leaves.
+- **The player's controller,** for what `capabilities.player` allows. The page sends the app the player's events, each one editable. A command the app may give is answered "not applied", and one it may not is refused, as on a screen.
+
+**What a screen would report** is shown beside the app: how long it took to say it was ready, or that it was late, and each failure with its reason.
+
+**`npm run preview -- --frame`** runs the app in the frame the CMS gives every imported app: sandboxed, on an origin of its own, with no storage, cookies or parent page. An app that reaches for one of them works on screens but fails in the CMS's designer. Run it with `--frame` before you import.
+
+## Check and pack it
+
+- **`npm run check`** (`wyndlass-app check`) makes the checks Wyndlass makes when you import an app, and gives the same answer:
+  - the package's shape and limits;
+  - the definition against its schema and Wyndlass's rules;
+  - the module: ES2020, no imports, a default export.
+
+  It also warns, without refusing, of a module over 1 MiB and of a module that never calls `ready()`.
+- **`npm run pack`** (`wyndlass-app pack`) writes `dist/<id>-<version>.zip`, the package you import, after the checks. It writes nothing for an app Wyndlass would refuse.
+  - The module is one minified ES2020 file. CSS a source imports becomes text for `css()`, and images and fonts are inlined.
+  - The same sources give the same bytes, so importing a version again changes nothing.
+  - The source map is written beside the zip, never in it.
+
+## Import it
+
+**In the CMS:** under **Content**, **Library**, choose **Import an app**, choose the place it goes, and choose the zip. Wyndlass checks it, then says whether it is approved or held for review.
+
+**With the Wyndlass MCP**, from a coding agent, as the person who connected it. The MCP lists its import tools only while imported apps are on at the top of your organization.
+1. `app.prepareImport` at the place, with the zip's name and size, answers an address and headers for an hour.
+2. `npx wyndlass-app upload <address> dist/<id>-<version>.zip --header "<name>: <value>" …` PUTs the zip there. The command holds no token and signs in to nothing.
+3. `app.import` with the same place and the upload's id imports it.
+4. `app.list` shows when the version is checked, and whether it is approved, held, refused or rejected, with the reason.
+
+**Reviews:**
+- An app's first version is held until a person approves it in the CMS. So is a later version that asks for more than the newest approved one: control of the player, a new sensor, audio, or a new network host. Any other version is approved with its import.
+- Any version is also held where the place's **Media review** holds everything new, or holds media made with AI and the Assistant or one of your organization's agents imported it.
+- Agents never approve.
+- A held version can be placed and previewed, and reaches no screen. Screens keep playing the newest approved version meanwhile.
+- **A version never changes.** The same bytes again are answered with the version you have. Other bytes need a new `version` in `app.json`.
+
+**Place it:** in the designer, your organization's apps are under **Apps**, **Your apps**. Place one as you place Wyndlass's.
+
+## What an app is
+
+- **One ES2020 module,** whose default export is its element's class. The class extends `HTMLElement`, usually through `WyndlassApp`.
+  - The host defines it under a tag of its own: your definition's `element`, a hyphen and a suffix.
+  - It hands the element its context once, before the element joins the page. Nothing is left on the element for another app to read.
+- **A definition, `app.json`,** valid against `app-definition.schema.json` (in this package, as `@wyndlass/app-sdk/app-definition.schema.json`):
+  - `id`, `version`, `name` and `element`, which are required, and `description`;
+  - `params`: each of a kind the schema lists, such as `string`, `number`, `boolean`, `enum`, `color`, `font`, `media` or `datatable`, with its label, default, values, limits and help, and `when` it applies;
+  - `data`: the data sources it reads, from `weather`, `news`, `image` and `calendar`;
+  - `capabilities`: `player` (`read`, the default, or `control`), `sensors` (`impressions`), `audio`, and `network`, the hosts it reaches;
+  - `slots` and `animation`, for apps bound to a table's rows and for the enter and exit presets it takes.
+- **A package** is a zip of exactly those two, `app.json` and `app.js`. `pack` makes it.
+
+## The runtime
+
+```ts
+import { WyndlassApp, fit } from "@wyndlass/app-sdk";
+
+export default class QueueBoard extends WyndlassApp {
+  #number!: HTMLElement;
+
+  protected mount() {
+    this.css(`:host { display: grid; place-items: center; color: white; } b { font-size: ${fit(0.5, 0.3)}; }`);
+    this.#number = document.createElement("b");
+    this.root.append(this.#number);
+    this.ready();
+  }
+
+  protected draw() {
+    this.#number.textContent = String(this.prop("number", 7));
+  }
+}
+```
+
+- **`WyndlassApp`:** extend it, and write `mount()` (build the shadow DOM, once) and `draw(epochMs)` (draw that moment of the layout's clock). It gives:
+  - `prop(name, default)`, `font()` (the font param as CSS), `now()`, `startedAt()`, `timeZone` and `locale`;
+  - `css(text)`: styles for the shadow root, as a constructable stylesheet;
+  - `ready()`: says the app may be shown, once, within 5 s of its start;
+  - `--w` and `--h`: the box's size, for text sized to it with `fit`;
+  - the enter and exit presets (fade, scale, slide-up, slide-left), staggered over `staggered()`'s items and drawn on the host's clock;
+  - `paging()`, for an app that turns pages.
+- **What acts or reads for the app is a function taking it,** not a method of the element, so another app on the page can't use it:
+  - `data(this, source, params)`, the data service's answer;
+  - `kept(this, source, params)`, the answer the screen last kept, at once;
+  - `image(this, path)`, `snapshot(this, table)`, `controllerOf(this)` and `impressionsOf(this)`;
+  - `contextOf(this)`, for the rest.
+- **Helpers:** `fit`, `typographyCss`, `color` and `escape`, and the presets' curves `easingOf`, `cubicBezier` and `staggerTimes`.
+- **Types:**
+  - the contract's (`AppContext`, `DataAnswer`, `HookOptions` and the rest);
+  - the definition's (`AppDefinition`);
+  - each data source's answer, as a namespace (`weather`, `news`, `calendar`, `tables`).
+- **`@wyndlass/app-sdk/qr`:** `qrModules(text)`, a QR code's modules, made without the network.
+
+**Outside a host,** such as a unit test or a page of your own, an app still runs: the time is now, each prop is its default, `data` and `image` are refused as unavailable, and `ready()` does nothing.
+
+## React (`@wyndlass/app-sdk/react`)
+
+```tsx
+import { useEffect } from "react";
+import { reactApp, useApp, useData, useNow, usePaging } from "@wyndlass/app-sdk/react";
+import css from "./app.css";
+
+function Board() {
+  const app = useApp();
+  const now = useNow();
+  const page = usePaging(2, 8000);
+  const { answer, error } = useData("weather", { lat: 49.9, lon: -97.14 });
+  useEffect(() => { if (answer || error) app.ready(); }, [app, answer, error]);
+  // …
+}
+
+export default reactApp(Board, { css });
+```
+
+- **`reactApp(Component, { css })`** makes the element's class, the module's default export. The component renders in the app's shadow root, with `css` as its styles. React is a peer dependency, and `pack` bundles it.
+- **`useApp()`:** `prop(name, default)`, `ready()`, `timeZone`, `locale`, the screen's `place` and `screen`, and `preview`.
+- **`useNow()`:** the layout's clock, drawn again at each of its frames.
+- **`usePaging(count, ms)`:** the page showing now. It also tells the host the pages.
+- **`useData(source, params)`:** at once the answer the screen kept, then the service's, asked again every 10 minutes. `error` is set once an ask fails with nothing to show.
+- **`useSnapshot(table)`:** a data table's snapshot.
+
+The hooks reach the app's context through the SDK's own module, never through React's tree, so nothing another app could use hangs off the shadow root.
+
+## Limits
+
+- The zip: at most 6 MiB, holding only `app.json` (at most 256 KiB) and `app.js` (at most 5 MiB).
+- The module: ES2020, one file, importing nothing.
+- Data: only the sources your definition declares, from `weather`, `news`, `image` and `calendar`.
+
+## What screens do
+
+- **They draw on the layout's clock.** The time comes from `now()` (or `useNow()`), never `Date.now()`, so a seek or a pause draws the right moment.
+- **`ready()` within 5 s.** An app that isn't ready by then is shown as it is, and reported late.
+- **They catch every hook.** An app that throws three times in a minute is stopped and its box emptied. The screen reports why (`load`, `shape`, `unsupported`, `error`, `late` or `overran`), with the name of what was thrown, never its message.
+- **Each app paints only in its box.** What an app adds outside it is removed, and a dialog opens inside it. `alert`, `confirm`, `prompt`, `print` and `window.open` do nothing.
+- **A version that hangs the page twice in an hour** is held back on that screen until the screen's content next changes.
+- **Offline,** an app shows the answers the screen kept: `kept()` gives them at once.
+- **In the CMS,** an app runs in a sandboxed frame with no storage, cookies or parent page.
+
+So:
+- don't use `localStorage` for anything that matters;
+- keep secrets out of params and the module, since both can be read;
+- declare the network hosts truthfully: a person approves them.
+
+## Versions
+
+This package follows semver from 1.0.0. Its 1.x versions build apps on Player API 2, and a change a 1.x app couldn't survive would be a 2.0. A version on npm never changes: a broken one is deprecated, never replaced.
+
+## Licence
+
+MIT, © Northwynd Labs LLC. See `LICENSE`.

package/cli/app-package.mjs

@@ -0,0 +1,111 @@
+// Copied from protocol/scripts/lib/app-package.mjs by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+// The reference reader of a customer's app package (WP-0100 decisions 2 and 5): one zip of exactly app.json (the
+// definition) and app.js (one ES2020 module). It answers "valid" or the first check that fails, in the order core's
+// media worker runs them (after its malware scan): the zip, then the definition, then the module. test-vectors/
+// app-packages.json is checked against it, and core and WP-0101's `check` are held to the same vectors.
+import { inflateRawSync } from "node:zlib";
+import { parse } from "acorn";
+
+export const LIMITS = { zip: 6 * 1024 * 1024, definition: 256 * 1024, module: 5 * 1024 * 1024 };
+/** The data service's sources a customer's app may read (decision 7; Decision needed: Mike). */
+export const DATA_SOURCES = ["weather", "news", "image", "calendar"];
+const ENTRIES = ["app.json", "app.js"];
+
+/**
+ * The package's verdict: "valid", or the code of the first check that fails. `validateDefinition` is the definition's
+ * JSON Schema (app-definition.schema.json), compiled.
+ */
+export function checkAppPackage(bytes, validateDefinition) {
+  const zip = readZip(bytes);
+  if (typeof zip === "string") return zip;
+  const definition = checkDefinition(zip["app.json"], validateDefinition);
+  if (definition !== "valid") return definition;
+  return checkModule(zip["app.js"]);
+}
+
+/** The zip's two entries' bytes, or the code of what is wrong with it. */
+export function readZip(bytes) {
+  const b = Buffer.from(bytes);
+  if (b.length > LIMITS.zip) return "too-large";
+  // The end of central directory record: 22 bytes, then at most a 65,535-byte comment.
+  let end = -1;
+  for (let i = b.length - 22; i >= Math.max(0, b.length - 22 - 0xffff); i--) if (b.readUInt32LE(i) === 0x06054b50) { end = i; break; }
+  if (end < 0) return "not-a-zip";
+  const count = b.readUInt16LE(end + 10), size = b.readUInt32LE(end + 12), at = b.readUInt32LE(end + 16);
+  if (count === 0xffff || at === 0xffffffff || at + size > end) return "not-a-zip";
+  const entries = [];
+  for (let i = 0, p = at; i < count; i++) {
+    if (p + 46 > end || b.readUInt32LE(p) !== 0x02014b50) return "not-a-zip";
+    const flags = b.readUInt16LE(p + 8), method = b.readUInt16LE(p + 10);
+    const compressed = b.readUInt32LE(p + 20), declared = b.readUInt32LE(p + 24);
+    const nameLength = b.readUInt16LE(p + 28), extra = b.readUInt16LE(p + 30), comment = b.readUInt16LE(p + 32), local = b.readUInt32LE(p + 42);
+    entries.push({ name: b.subarray(p + 46, p + 46 + nameLength).toString("utf8"), flags, method, compressed, declared, local });
+    p += 46 + nameLength + extra + comment;
+  }
+  for (const e of entries) if (e.flags & 1) return "encrypted";
+  for (const e of entries) if (e.name.endsWith("/")) return "folder";
+  for (const e of entries) if (/[/\\]/.test(e.name) || e.name === ".." || e.name === ".") return "path";
+  const names = entries.map(e => e.name);
+  if (names.length !== ENTRIES.length || !ENTRIES.every(n => names.includes(n))) return "entries";
+  for (const e of entries) if (e.declared > (e.name === "app.json" ? LIMITS.definition : LIMITS.module)) return "too-large";
+  const out = {};
+  for (const e of entries) {
+    if (e.local + 30 > b.length || b.readUInt32LE(e.local) !== 0x04034b50) return "not-a-zip";
+    const start = e.local + 30 + b.readUInt16LE(e.local + 26) + b.readUInt16LE(e.local + 28);
+    const data = b.subarray(start, start + e.compressed);
+    if (data.length !== e.compressed) return "not-a-zip";
+    let unpacked;
+    if (e.method === 0) unpacked = data;
+    else if (e.method === 8) {
+      // At most one byte more than it says: enough to tell that it says too little.
+      try { unpacked = inflateRawSync(data, { maxOutputLength: e.declared + 1 }); }
+      catch (x) { if (x.code === "ERR_BUFFER_TOO_LARGE" || x.code === "ERR_OUT_OF_RANGE") return "size-mismatch"; return "not-a-zip"; }
+    } else return "not-a-zip";
+    if (unpacked.length !== e.declared) return "size-mismatch";
+    out[e.name] = unpacked;
+  }
+  return out;
+}
+
+/** The definition's verdict: UTF-8 JSON, its schema, then the rules a schema cannot say. */
+export function checkDefinition(bytes, validateDefinition) {
+  let d;
+  try { d = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); } catch { return "definition-json"; }
+  if (!d || typeof d !== "object" || Array.isArray(d)) return "definition-json";
+  if (!validateDefinition(d)) return "definition-schema";
+  if (d.id.startsWith("com.wyndlass.")) return "definition-id";
+  const params = d.params ?? {};
+  for (const [name, p] of Object.entries(params))
+    for (const other of Object.keys(p.when ?? {})) if (other === name || !Object.hasOwn(params, other)) return "definition-when";
+  for (const p of Object.values(params)) {
+    if (p.type !== "url") continue;
+    const values = [...(p.values ?? []).map(v => (v && typeof v === "object" ? v.value : v)), ...(p.default === undefined ? [] : [p.default])];
+    for (const v of values) if (typeof v !== "string" || !URL.canParse(v) || new URL(v).protocol !== "https:") return "definition-url";
+  }
+  if (d.capabilities?.peers === true) return "definition-peers";
+  for (const source of d.data ?? []) if (!DATA_SOURCES.includes(source)) return "definition-data";
+  return "valid";
+}
+
+/** The module's verdict: an ES2020 module that imports nothing and has a default export. */
+export function checkModule(bytes) {
+  let program;
+  try { program = parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes), { ecmaVersion: 2020, sourceType: "module" }); } catch { return "module-syntax"; }
+  let imports = false, defaultExport = false;
+  const visit = node => {
+    if (!node || typeof node.type !== "string") return;
+    if (node.type === "ImportDeclaration" || node.type === "ImportExpression" || node.type === "ExportAllDeclaration" || (node.type === "ExportNamedDeclaration" && node.source)) imports = true;
+    // export default …, or export { x as default }, as bundlers write it.
+    if (node.type === "ExportDefaultDeclaration") defaultExport = true;
+    if (node.type === "ExportNamedDeclaration" && !node.source && node.specifiers.some(s => (s.exported.name ?? s.exported.value) === "default")) defaultExport = true;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value === "object") visit(value);
+    }
+  };
+  visit(program);
+  if (imports) return "module-import";
+  if (!defaultExport) return "module-default";
+  return "valid";
+}

package/cli/commands.mjs

@@ -0,0 +1,133 @@
+// The CLI's commands (WP-0101 decision 5): create, check, pack, upload and skill install. Each returns what it says, as
+// lines, and throws CliError for a refusal. Nothing here signs in anywhere (decision 6): what touches Wyndlass goes
+// through the person's MCP client or the CMS, and upload only PUTs to an address it is given.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, MEANING, SDK_VERSION, packageOf, schemaErrors, verdict } from "./package.mjs";
+
+const sdk = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const TEMPLATES = ["vanilla", "react"];
+const ID = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
+
+/** A refusal's words: the code, what it means, and for a schema refusal, what the schema said. */
+function refusal(code, definition) {
+  const lines = [`refused (${code}): ${MEANING[code] ?? code}`];
+  if (code === "definition-schema" && definition) for (const e of schemaErrors(definition)) lines.push(`  ${e}`);
+  return lines;
+}
+
+/** Text files of a template get the app's values; the rest are copied as they are. */
+const TEXT = /\.(json|md|ts|tsx|css|gitignore|txt)$|^\.gitignore$/;
+
+/**
+ * create <dir>: a working app from a template, `vanilla` or `react` (decision 4). Its id must be one the import takes,
+ * never com.wyndlass.; its element is the id's last part, with "-app" when that has no hyphen. `sdk` is the version
+ * spec the project depends on (the SDK's own, ^x.y.z, unless a test gives a tarball).
+ */
+export function create(dir, { template = "vanilla", id, name, sdk: sdkSpec } = {}) {
+  if (!TEMPLATES.includes(template)) throw new CliError(`no template "${template}": ${TEMPLATES.join(" or ")}`);
+  const target = resolve(dir);
+  if (existsSync(target) && readdirSync(target).length) throw new CliError(`${dir} is not empty`);
+  const slug = basename(target).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^[^a-z]+|-+$/g, "") || "my-app";
+  const appId = id ?? `com.example.${slug}`;
+  if (!ID.test(appId)) throw new CliError(`"${appId}" is not an app id: a reverse-domain name in your organization's own domain, such as com.example.queue-board`);
+  if (appId.startsWith("com.wyndlass.")) throw new CliError("com.wyndlass. is Wyndlass's own: use your organization's own domain");
+  const last = appId.split(".").at(-1);
+  const element = last.includes("-") ? last : `${last}-app`;
+  const appName = name ?? last.split("-").map(w => w[0].toUpperCase() + w.slice(1)).join(" ");
+  const values = { __APP_ID__: appId, __APP_NAME__: appName, __ELEMENT__: element, __PACKAGE__: last, __SDK__: sdkSpec ?? `^${SDK_VERSION}` };
+  const from = join(sdk, "templates", template);
+  mkdirSync(target, { recursive: true });
+  cpSync(from, target, { recursive: true });
+  for (const file of walk(target)) {
+    if (!TEXT.test(basename(file))) continue;
+    const text = readFileSync(file, "utf8");
+    const filled = text.replace(/__(APP_ID|APP_NAME|ELEMENT|PACKAGE|SDK)__/g, k => values[k].replace(/"/g, "\\\""));
+    if (filled !== text) writeFileSync(file, filled);
+  }
+  // npm leaves a package's .gitignore out of what it publishes, so the template's is called gitignore.
+  if (existsSync(join(target, "gitignore"))) renameSync(join(target, "gitignore"), join(target, ".gitignore"));
+  return [`${appName} (${appId}), from the ${template} template, in ${relative(process.cwd(), target) || "."}.`,
+    "Next:", `  cd ${relative(process.cwd(), target) || "."}`, "  npm install", "  npm run check", "  npm run pack"];
+}
+
+function walk(dir) {
+  return readdirSync(dir).flatMap(n => {
+    const p = join(dir, n);
+    return statSync(p).isDirectory() ? walk(p) : [p];
+  });
+}
+
+/**
+ * check [dir|zip]: the checks core makes (decision 5), on a zip as it is, or on a project as pack would build it.
+ * Throws with the first refusal; returns the verdict and any warnings.
+ */
+export async function check(target = ".") {
+  const path = resolve(target);
+  if (!existsSync(path)) throw new CliError(`${target} does not exist`);
+  if (statSync(path).isFile()) {
+    const code = verdict(readFileSync(path));
+    if (code !== "valid") throw new CliError(refusal(code, null).join("\n"));
+    return [`${basename(path)}: Wyndlass takes it.`];
+  }
+  const p = await packageOf(path);
+  if (p.code !== "valid") throw new CliError([`${p.id} ${p.version}:`, ...refusal(p.code, p.definition)].join("\n"));
+  return [`${p.id} ${p.version}: Wyndlass takes it.`, ...p.warnings.map(w => `warning: ${w}`)];
+}
+
+/**
+ * pack [dir]: the package WP-0100 takes (decision 8), dist/<id>-<version>.zip, and its module's source map beside it,
+ * never inside. It checks first, and writes nothing for an app core would refuse.
+ */
+export async function pack(dir = ".") {
+  const path = resolve(dir);
+  const p = await packageOf(path);
+  if (p.code !== "valid") throw new CliError([`${p.id} ${p.version}: not packed.`, ...refusal(p.code, p.definition)].join("\n"));
+  const out = join(path, "dist");
+  mkdirSync(out, { recursive: true });
+  const file = join(out, `${p.id}-${p.version}.zip`);
+  writeFileSync(file, p.bytes);
+  writeFileSync(join(out, `${p.id}-${p.version}.js.map`), p.map);
+  return [`${relative(process.cwd(), file)}: ${p.bytes.length} bytes, ready to import.`, ...p.warnings.map(w => `warning: ${w}`)];
+}
+
+/**
+ * upload <url> <zip>: PUTs the zip to the address app.prepareImport gave, with the headers it gave (`k: v` each). It
+ * holds no token: the address is signed, for an hour.
+ */
+export async function upload(url, file, headers = []) {
+  if (!url || !file) throw new CliError("upload needs the address app.prepareImport gave, and the zip");
+  let address;
+  try { address = new URL(url); } catch { throw new CliError(`${url} is not an address`); }
+  if (address.protocol !== "https:" && address.hostname !== "127.0.0.1" && address.hostname !== "localhost") throw new CliError(`${url} is not an https address`);
+  const body = readFileSync(resolve(file));
+  const sent = {};
+  for (const h of headers) {
+    const at = h.indexOf(":");
+    if (at <= 0) throw new CliError(`"${h}" is not a header: name: value`);
+    sent[h.slice(0, at).trim()] = h.slice(at + 1).trim();
+  }
+  const res = await fetch(address, { method: "PUT", headers: sent, body }).catch(e => { throw new CliError(`the upload did not reach ${address.host}: ${e.cause?.code ?? e.message}`); });
+  if (!res.ok) throw new CliError(`the upload was refused: HTTP ${res.status}${res.status === 403 ? " (the address may have expired: ask for another)" : ""}`);
+  return [`${basename(file)}: uploaded (${body.length} bytes). Import it with app.import.`];
+}
+
+/** The skill for the customer's own coding agent (decision 12), in the package beside the CLI it describes. */
+export const SKILL = "wyndlass-app";
+
+/**
+ * skill install [--user]: the skill in the project's .claude/skills/wyndlass-app/ (the folder it runs in), or with --user
+ * in ~/.claude/skills/wyndlass-app/, where Claude Code finds it. An earlier copy is replaced whole, so a newer SDK's skill
+ * leaves none of an older one's files behind.
+ */
+export function skillInstall({ user = false, cwd = process.cwd(), home = homedir() } = {}) {
+  const target = join(user ? home : resolve(cwd), ".claude", "skills", SKILL);
+  const earlier = existsSync(target);
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(join(sdk, "skill", SKILL), target, { recursive: true });
+  return [`${earlier ? "Replaced" : "Installed"} the skill ${SKILL} (@wyndlass/app-sdk ${SDK_VERSION}) in ${user ? target : relative(cwd, target)}.`,
+    "Claude Code finds it there: ask it to build an app for your Wyndlass screens."];
+}

package/cli/main.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// wyndlass-app (WP-0101 decision 5): create, preview, check, pack and upload an app for Wyndlass's screens, and install
+// the skill that does it with a coding agent (decision 12). It signs in to nothing (decision 6).
+import { parseArgs } from "node:util";
+import { CliError, SDK_VERSION } from "./package.mjs";
+import { check, create, pack, skillInstall, TEMPLATES, upload } from "./commands.mjs";
+import { preview } from "./preview.mjs";
+
+const HELP = `wyndlass-app ${SDK_VERSION}: build apps for Wyndlass's screens.
+
+  create <dir> [--template ${TEMPLATES.join("|")}] [--id com.example.app] [--name "App name"]
+                     a working app to start from
+  preview [dir] [--port 5199] [--data <dir>] [--frame]
+                     the app as screens run it, on 127.0.0.1, drawn again as you change it;
+                     --frame runs it in the frame the CMS gives apps, on an origin of its own
+  check [dir|zip]    the checks Wyndlass makes on an imported app, on a project or a package
+  pack [dir]         dist/<id>-<version>.zip, the package to import, after check
+  upload <url> <zip> [--header "name: value" ...]
+                     PUT the package to the address app.prepareImport gave, with its headers
+  skill install [--user]
+                     the skill for a coding agent, in .claude/skills/wyndlass-app/ here, or with
+                     --user in ~/.claude/skills/; it replaces an earlier copy
+
+Importing, placing and scheduling go through the Wyndlass MCP (app.prepareImport, app.import) or the CMS.`;
+
+const [command, ...rest] = process.argv.slice(2);
+try {
+  let lines;
+  if (command === "create") {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true,
+      options: { template: { type: "string" }, id: { type: "string" }, name: { type: "string" }, sdk: { type: "string" } } });
+    if (positionals.length !== 1) throw new CliError("create needs one folder: wyndlass-app create <dir>");
+    lines = create(positionals[0], values);
+  } else if (command === "preview") {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true,
+      options: { port: { type: "string" }, data: { type: "string" }, frame: { type: "boolean" } } });
+    const port = values.port === undefined ? 5199 : Number(values.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new CliError(`"${values.port}" is not a port`);
+    const running = await preview(positionals[0] ?? ".", { port, data: values.data, frame: values.frame === true });
+    console.log(`The preview is at ${running.url} (on this computer only). Ctrl+C stops it.`);
+    if (running.frames) console.log(`The app runs in a frame on ${running.frames}, as in the CMS.`);
+    const stop = () => { void running.close().then(() => process.exit(0)); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    lines = [];
+  } else if (command === "check") {
+    const { positionals } = parseArgs({ args: rest, allowPositionals: true });
+    lines = await check(positionals[0]);
+  } else if (command === "pack") {
+    const { positionals } = parseArgs({ args: rest, allowPositionals: true });
+    lines = await pack(positionals[0]);
+  } else if (command === "upload") {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { header: { type: "string", multiple: true } } });
+    lines = await upload(positionals[0], positionals[1], values.header ?? []);
+  } else if (command === "skill") {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { user: { type: "boolean" } } });
+    if (positionals.length !== 1 || positionals[0] !== "install") throw new CliError("skill has one command: wyndlass-app skill install [--user]");
+    lines = skillInstall({ user: values.user === true });
+  } else if (!command || command === "help" || command === "--help" || command === "-h") {
+    lines = [HELP];
+  } else if (command === "--version" || command === "-v") {
+    lines = [SDK_VERSION];
+  } else {
+    throw new CliError(`no command "${command}"\n\n${HELP}`);
+  }
+  for (const line of lines) console.log(line);
+} catch (e) {
+  if (e instanceof CliError || e?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" || e?.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+    console.error(`wyndlass-app: ${e.message}`);
+    process.exit(1);
+  }
+  throw e;
+}