ais6-app 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Lau
+
+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,40 @@
-# Temporary Holding Version
+# ais6-app
 
-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.
+Create an AI System 6 app, and check it the way a desk checks it before
+installing it.
+
+```
+npx ais6-app create my-app     # a new TypeScript + Preact app
+npx ais6-app check            # the app folder you are in
+npx ais6-app check path/to/app --build
+```
+
+`create` writes a working app into an empty folder: a typed bridge client,
+`public/app.manifest.json` with one window and a File menu, the kit files,
+strings in English and Chinese, Vitest tests, Biome, a README pair and an MIT
+licence. Options: `--id` (default: the folder name), `--name`, `--name-zh`,
+`--author`. `npm run check` in the new folder runs types, lint, tests, the
+build and `ais6-app check`; it passes before you change anything.
+
+It runs on a repository (source and build), on a built `dist/`, or on a
+vendored app tree, and prints one line per check: `OK`, `NO` (a desk would
+refuse the app) or `--` (a warning). The exit code is 0 when everything
+passes, 1 when something is refused, 2 for a usage error.
+
+| Check | What it looks at |
+|---|---|
+| manifest | id, version, protocol, kit range; each window's name, app, entry page, title, classes, capabilities (the closed set), services, menus, frame permissions; strings in English and Chinese |
+| kit | the bridge client `ais6-bridge.js` beside the manifest (and `kit.css`, as a warning) |
+| bridge only | no reach into the parent page, no desk globals, no `localStorage`, `sessionStorage`, `indexedDB`, cookies, `BroadcastChannel` or `SharedWorker` |
+| versions | the manifest, `package.json` and the version the code connects with agree (a mismatch makes the desk refuse the connection) |
+| repository | `README.md`, `README.zh-CN.md`, `LICENSE`, a build script |
+| safe to publish | no keys or tokens, no local machine paths, no private files (`.env`, keys, editor and agent folders) |
+
+Options: `--build` runs `npm run build` first; `--json` prints the result as
+JSON; `--own-storage idbfs` and `--engine-files a.js,b.js` apply the
+exceptions a desk grants a compiled engine.
+
+The same rules are imported by the AI System 6 desk's own pin, boundary and
+release checks, so an app that passes here passes there.
+
+Documentation: <https://aisystem6.aaronlau.me/sdk/>. Licence: MIT.

package/README.zh-CN.md

@@ -0,0 +1,33 @@
+<!-- canonical-source: packages/ais6-app/README.md -->
+<!-- source-sha256: 246087a9156aa7044435339b6056107420709aba7633d78c2507709caddb1ab1 -->
+
+> 英文版为准；本说明仅供人类参考。
+
+# ais6-app
+
+新建 AI System 6 app，并按桌面在安装前的检查方式检查它。
+
+```
+npx ais6-app create my-app     # 新建一个 TypeScript + Preact app
+npx ais6-app check            # 当前所在的 app 文件夹
+npx ais6-app check path/to/app --build
+```
+
+`create` 在空文件夹里写出一个能运行的 app：带类型的桥接客户端、只有一个窗口和「文件」菜单的 `public/app.manifest.json`、kit 文件、中英文字符串、Vitest 测试、Biome、README 中英两份和 MIT 许可证。选项：`--id`（默认用文件夹名）、`--name`、`--name-zh`、`--author`。在新文件夹里运行 `npm run check` 会依次跑类型、lint、测试、构建和 `ais6-app check`；什么都不改也能通过。
+
+可以对仓库（源码与构建）、构建好的 `dist/` 或已托管的 app 树运行，每项检查打印一行：`OK`、`NO`（桌面会拒绝这个 app）或 `--`（警告）。全部通过时退出码为 0，有项目被拒为 1，用法错误为 2。
+
+| 检查 | 看什么 |
+|---|---|
+| manifest | id、版本、协议、kit 范围；每个窗口的名称、所属 app、入口页、标题、class、能力（封闭集合）、服务、菜单、框权限；中英文字符串 |
+| kit | manifest 旁的桥接客户端 `ais6-bridge.js`（`kit.css` 缺少时只警告） |
+| 只经桥接 | 不伸手进父页面，不碰桌面全局，不用 `localStorage`、`sessionStorage`、`indexedDB`、cookie、`BroadcastChannel` 或 `SharedWorker` |
+| 版本 | manifest、`package.json` 与代码连接时声明的版本一致（不一致时桌面会拒绝连接） |
+| 仓库 | `README.md`、`README.zh-CN.md`、`LICENSE`、构建脚本 |
+| 可以发布 | 没有密钥或令牌、没有本机路径、没有私密文件（`.env`、密钥、编辑器与 agent 的文件夹） |
+
+选项：`--build` 先运行 `npm run build`；`--json` 以 JSON 输出；`--own-storage idbfs` 与 `--engine-files a.js,b.js` 套用桌面给编译引擎的例外。
+
+AI System 6 桌面自己的钉版、边界与发布检查导入的是同一套规则，所以在这里通过的 app，在桌面那里也会通过。
+
+文档：<https://aisystem6.aaronlau.me/sdk/>。许可证：MIT。

package/bin/ais6-app.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// ais6-app — check an AI System 6 app the way a desk checks it.
+//
+//   ais6-app check [dir] [--build] [--json] [--own-storage idbfs] [--engine-files a.js,b.js]
+//   ais6-app create <dir> [--id my-app] [--name "My App"] [--name-zh 我的应用] [--author "Name"]
+//
+// Exit code 0 when every check passes, 1 when one fails, 2 on a usage error.
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { runCheck } from "../src/check.mjs";
+import { createApp } from "../src/create.mjs";
+
+const args = process.argv.slice(2);
+const command = args[0];
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+if (!command || command === "--help" || command === "-h" || command === "help") {
+  console.log(`ais6-app ${version}
+
+Usage:
+  ais6-app check [dir] [--build] [--json]   check an app folder (default: .)
+  ais6-app create <dir> [--id] [--name] [--name-zh] [--author]
+                                            a new TypeScript + Preact app
+
+  --build                 run "npm run build" first and check the built dist/
+  --json                  print the result as JSON
+  --own-storage idbfs     storage the desk lets a compiled engine own
+  --engine-files a.js,b   generated engine files that are not read
+
+The checks: the manifest (ids, versions, protocol, kit range, windows,
+capabilities, services, strings in English and Chinese, frame permissions),
+the kit files, bridge-only access (no parent page, desk globals or desk
+storage), versions that agree (manifest, package.json, the code's connect),
+the repository files, and nothing unsafe to publish (keys, local paths,
+private files). Docs: https://aisystem6.aaronlau.me/sdk/`);
+  process.exit(command ? 0 : 2);
+}
+if (command === "--version" || command === "-v") { console.log(version); process.exit(0); }
+const valueOf = (flag) => { const index = args.indexOf(flag); return index >= 0 ? String(args[index + 1] || "") : ""; };
+
+if (command === "create") {
+  const named = new Set(["--id", "--name", "--name-zh", "--author"].map((flag) => valueOf(flag)).filter(Boolean));
+  const target = args.slice(1).find((arg) => !arg.startsWith("--") && !named.has(arg));
+  if (!target) { console.error("ais6-app create needs a folder: ais6-app create my-app"); process.exit(2); }
+  try {
+    const made = createApp(target, {
+      id: valueOf("--id") || undefined,
+      name: valueOf("--name") || undefined,
+      nameZh: valueOf("--name-zh") || undefined,
+      author: valueOf("--author") || undefined,
+    });
+    console.log(`Created ${made.id} (window ${made.window}) in ${made.dir}, ${made.files.length} files.
+
+Next:
+  cd ${target}
+  npm install
+  npm run dev       # the app on its own page
+  npm run check     # types, lint, tests, build and ais6-app check`);
+    process.exit(0);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+}
+if (command !== "check") { console.error(`unknown command "${command}"; try ais6-app --help`); process.exit(2); }
+
+const listOf = (flag) => valueOf(flag).split(",").map((part) => part.trim()).filter(Boolean);
+const flagValues = new Set(["--own-storage", "--engine-files"].map((flag) => valueOf(flag)).filter(Boolean));
+const dir = resolve(args.slice(1).find((arg) => !arg.startsWith("--") && !flagValues.has(arg)) || ".");
+const result = runCheck(dir, {
+  build: args.includes("--build"),
+  ownStorage: listOf("--own-storage"),
+  engineFiles: listOf("--engine-files"),
+  log: (line) => { if (!args.includes("--json")) console.log(line); },
+});
+if (args.includes("--json")) {
+  console.log(JSON.stringify({ ok: result.ok, sections: result.sections }, null, 2));
+} else {
+  for (const { name, problems, warnings = [] } of result.sections) {
+    if (!problems.length) console.log(`OK  ${name}`);
+    else for (const problem of problems) console.log(`NO  ${name}: ${problem}`);
+    for (const warning of warnings) console.log(`--  ${name}: ${warning}`);
+  }
+  console.log(result.ok ? "\nThis app passes every check a desk makes before installing it." : "\nFix the NO lines above; a desk would refuse this app.");
+}
+process.exit(result.ok ? 0 : 1);

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "ais6-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Create an AI System 6 app, and check it the way a desk checks it before installing it.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ais6-app": "bin/ais6-app.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./manifest": "./src/manifest.mjs",
+    "./boundary": "./src/boundary.mjs",
+    "./publish": "./src/publish.mjs",
+    "./create": "./src/create.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://aisystem6.aaronlau.me/sdk/publishing",
+  "keywords": [
+    "ai-system-6",
+    "app",
+    "checker",
+    "iframe",
+    "bridge"
+  ]
+}

package/src/boundary.mjs

@@ -0,0 +1,61 @@
+// An app reaches its desk through the bridge only. These are the reaches it
+// may not make: the parent page, the desk's globals and storage the desk owns.
+// The desk's boundary census imports the same rules.
+
+import { readFileSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { listFiles } from "./files.mjs";
+
+export const TEXT_EXTENSIONS = /\.(?:m?js|html?|svg|css|json)$/i;
+
+export const APP_SIDE_RULES = Object.freeze([
+  // Bare parent/top, or window/self/globalThis.parent|top — not Object3D.parent
+  // (three.js and similar scene-graph walks).
+  { id: "parent-or-top", pattern: /(?:(?:^|[^.\w$])(?:parent|top)|(?:window|self|globalThis)\s*\.\s*(?:parent|top))\s*\.\s*(?!postMessage\b)[A-Za-z_$]/, why: "reaches into the page that holds the frame; use the bridge" },
+  { id: "indexedDB", pattern: /\bindexedDB\b/, why: "the desk owns storage; use state.*" },
+  { id: "localStorage", pattern: /\blocalStorage\b/, why: "the desk owns storage; use state.*" },
+  { id: "sessionStorage", pattern: /\bsessionStorage\b/, why: "the desk owns storage; use state.*" },
+  { id: "desk-global", pattern: /AISystem6/, why: "names a desk global; use the bridge" },
+  { id: "cookie", pattern: /document\s*\.\s*cookie/, why: "cookies are the desk's" },
+  { id: "BroadcastChannel", pattern: /\bBroadcastChannel\b/, why: "talks past the bridge to other frames" },
+  { id: "SharedWorker", pattern: /\bSharedWorker\b/, why: "talks past the bridge to other frames" },
+]);
+
+// Storage an app may own by exception, when the desk's pin says so: a
+// compiled engine's own file system (Emscripten IDBFS). `page` excuses no
+// rule; it only lets the named engine files go unread.
+export const OWN_STORAGE = Object.freeze({ idbfs: Object.freeze(["indexedDB"]), page: Object.freeze([]) });
+
+/**
+ * App-side findings for every text file under `dir`: [{ file, line, rule, why }].
+ * `isBridgeClient(path, bytes)` says whether a file is a kit bridge client
+ * (which is the one file that may talk to the parent); `engineFiles` are
+ * generated engine glue that is not read.
+ */
+export function scanAppTree(dir, { ownStorage = [], engineFiles = [], isBridgeClient = defaultBridgeCheck, skip = [] } = {}) {
+  const engine = new Set(Array.isArray(engineFiles) ? engineFiles : []);
+  const excused = new Set((Array.isArray(ownStorage) ? ownStorage : []).flatMap((name) => OWN_STORAGE[name] || []));
+  const skipped = (rel) => skip.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+  const findings = [];
+  for (const file of listFiles(dir)) {
+    if (!TEXT_EXTENSIONS.test(file)) continue;
+    const rel = relative(dir, file).split(sep).join("/");
+    if (engine.has(rel) || skipped(rel)) continue;
+    const data = readFileSync(file);
+    if (file.endsWith(`${sep}ais6-bridge.js`) && isBridgeClient(rel, data)) continue;
+    data.toString("utf8").split("\n").forEach((text, index) => {
+      for (const rule of APP_SIDE_RULES) {
+        if (excused.has(rule.id)) continue;
+        if (rule.pattern.test(text)) findings.push({ file: rel, line: index + 1, rule: rule.id, why: rule.why });
+      }
+    });
+  }
+  return findings;
+}
+
+// Outside the desk: a file named ais6-bridge.js that announces itself as the
+// kit's bridge client (its header and its AIS6Bridge export).
+function defaultBridgeCheck(rel, data) {
+  const text = data.toString("utf8");
+  return /root\.AIS6Bridge\s*=\s*Object\.freeze\(/.test(text) && /protocol: PROTOCOL/.test(text);
+}

package/src/check.mjs

@@ -0,0 +1,103 @@
+// `ais6-app check`: everything a desk verifies before it installs an app,
+// run on the app's own folder. Works on a repository (source + build), on a
+// built `dist/`, or on a vendored tree.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { manifestProblems } from "./manifest.mjs";
+import { scanAppTree } from "./boundary.mjs";
+import { scanForPublishing } from "./publish.mjs";
+import { listFiles } from "./files.mjs";
+
+const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+
+/** Where the manifest and the served tree are, for a folder of any shape. */
+export function locate(dir) {
+  const repo = existsSync(join(dir, "package.json")) ? dir : null;
+  if (existsSync(join(dir, "dist", "app.manifest.json"))) return { repo, tree: join(dir, "dist"), manifest: join(dir, "dist", "app.manifest.json"), built: true };
+  if (existsSync(join(dir, "app.manifest.json"))) return { repo, tree: dir, manifest: join(dir, "app.manifest.json"), built: true };
+  if (existsSync(join(dir, "public", "app.manifest.json"))) return { repo, tree: dir, manifest: join(dir, "public", "app.manifest.json"), built: false };
+  return { repo, tree: null, manifest: null, built: false };
+}
+
+// The version the app's code hands to connect(), where it names one.
+function clientVersions(dir) {
+  const found = new Set();
+  for (const file of listFiles(dir, { ignore: ["node_modules", ".git", "dist", "tests", "test", "vendor", "assets"] })) {
+    if (!/\.(?:m?[jt]sx?)$/.test(file) || file.endsWith(`${sep}ais6-bridge.js`)) continue;
+    const text = readFileSync(file, "utf8");
+    for (const match of text.matchAll(/\b(?:APP_VERSION|VERSION)\s*=\s*["'](\d+\.\d+\.\d+[^"']*)["']/g)) found.add(match[1]);
+  }
+  return [...found];
+}
+
+/**
+ * Runs every check. Returns { sections: [{ name, problems: [string] }], ok }.
+ * `build: true` runs `npm run build` first when the folder is a repository.
+ */
+export function runCheck(dir, { build = false, ownStorage = [], engineFiles = [], log = () => {} } = {}) {
+  const sections = [];
+  const section = (name, problems, warnings = []) => sections.push({ name, problems, warnings });
+  if (build && existsSync(join(dir, "package.json"))) {
+    log("building (npm run build)…");
+    try {
+      execFileSync("npm", ["run", "build"], { cwd: dir, stdio: "pipe" });
+    } catch (error) {
+      section("build", [`npm run build failed: ${String(error.stderr || error.message).split("\n").filter(Boolean).slice(-3).join(" / ")}`]);
+      return { sections, ok: false };
+    }
+  }
+  const where = locate(dir);
+  if (!where.manifest) {
+    section("manifest", ["no app.manifest.json here, in dist/ or in public/"]);
+    return { sections, ok: false };
+  }
+  let manifest = null;
+  try { manifest = readJson(where.manifest); } catch (error) { section("manifest", [`app.manifest.json is not valid JSON: ${error.message}`]); }
+  if (manifest) {
+    const servedRoot = where.built ? where.tree : join(dir, "public");
+    const fileExists = (rel) => existsSync(join(servedRoot, rel)) || (!where.built && existsSync(join(dir, rel)));
+    const warnings = [];
+    section("manifest", manifestProblems(manifest, { fileExists, warnings }), warnings);
+  }
+
+  const kit = [];
+  const kitWarnings = [];
+  const kitRoot = where.built ? where.tree : join(dir, "public");
+  if (!existsSync(join(kitRoot, "ais6-bridge.js"))) kit.push("ais6-bridge.js is missing: copy the kit's bridge client next to the manifest");
+  if (!existsSync(join(kitRoot, "kit.css"))) kitWarnings.push("kit.css is not here: fine for an app that draws everything itself, otherwise copy the kit stylesheet");
+  section("kit", kit, kitWarnings);
+
+  const boundaryRoot = where.built ? where.tree : dir;
+  const findings = scanAppTree(boundaryRoot, { ownStorage, engineFiles, skip: where.built ? [] : ["node_modules", "dist", "tests", "test", "tools", "build"] });
+  section("bridge only", findings.map((hit) => `${hit.file}:${hit.line} ${hit.rule}: ${hit.why}`));
+
+  // A client that connects with another version than the manifest's is
+  // refused by the desk (version-mismatch) and falls back to standalone mode
+  // inside the frame: no state, no snapshots, no services.
+  const versions = [];
+  if (manifest) {
+    const wanted = String(manifest.version || "");
+    if (where.repo) {
+      const pkg = readJson(join(where.repo, "package.json"));
+      if (pkg.version && pkg.version !== wanted) versions.push(`package.json version ${pkg.version} is not the manifest's ${wanted}`);
+    }
+    for (const seen of clientVersions(where.repo || where.tree)) if (seen !== wanted) versions.push(`the code connects as version ${seen}, the manifest says ${wanted}`);
+  }
+  section("versions", versions);
+
+  if (where.repo) {
+    const repoProblems = [];
+    const pkg = readJson(join(where.repo, "package.json"));
+    for (const file of ["README.md", "README.zh-CN.md", "LICENSE"]) if (!existsSync(join(where.repo, file))) repoProblems.push(`${file} is missing`);
+    if (!pkg.scripts?.build) repoProblems.push("package.json has no build script");
+    section("repository", repoProblems);
+  }
+  const publishHits = scanForPublishing(where.repo || where.tree, { skipFiles: engineFiles });
+  const describe = (hit) => `${hit.file}${hit.line ? `:${hit.line}` : ""} ${hit.name}`;
+  section("safe to publish",
+    publishHits.filter((hit) => hit.kind !== "warning").map(describe),
+    publishHits.filter((hit) => hit.kind === "warning").map((hit) => `${describe(hit)}: say in LICENSES.md what it is`));
+  return { sections, ok: sections.every((entry) => entry.problems.length === 0), manifest, tree: where.tree && relative(dir, where.tree) || "." };
+}

package/src/create.mjs

@@ -0,0 +1,64 @@
+// `ais6-app create <dir>`: a new app from the TypeScript + Preact template,
+// ready to build and to pass `ais6-app check` before any change.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { ID_PATTERN } from "./manifest.mjs";
+
+const TEMPLATE = new URL("../template/", import.meta.url);
+// npm drops a published .gitignore, so the template ships it under another name.
+const RENAMES = { _gitignore: ".gitignore" };
+
+/** "word-count" → "wordCount": the window and app name the desk addresses. */
+export function windowNameFor(id) {
+  return id.replace(/-([a-z0-9])/g, (match, next) => next.toUpperCase());
+}
+
+/** "word-count" → "Word Count". */
+export function titleFor(id) {
+  return id.split("-").filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
+}
+
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) walk(path, out);
+    else out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Writes the template into `dir`. Returns { dir, id, window, files }.
+ * Throws with a plain sentence when the id is not one a desk accepts or the
+ * folder is not empty.
+ */
+export function createApp(target, { id, name, nameZh, author = "The authors", year = new Date().getFullYear() } = {}) {
+  const dir = resolve(target);
+  const appId = id || basename(dir);
+  if (!ID_PATTERN.test(appId)) throw new Error(`"${appId}" is not an app id a desk accepts: lower case letters, digits and dashes, starting with a letter (pass --id)`);
+  if (existsSync(dir) && readdirSync(dir).length) throw new Error(`${dir} is not empty; choose a new folder`);
+  const title = name || titleFor(appId);
+  const values = {
+    __APP_ID__: appId,
+    __WINDOW__: windowNameFor(appId),
+    __NAME__: title,
+    __NAME_ZH__: nameZh || title,
+    __AUTHOR__: author,
+    __YEAR__: String(year),
+    __CHECKER_VERSION__: JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version,
+  };
+  const root = TEMPLATE.pathname ? decodeURIComponent(TEMPLATE.pathname) : String(TEMPLATE);
+  const files = [];
+  for (const source of walk(root)) {
+    const rel = relative(root, source).split("/").map((part) => RENAMES[part] || part).join("/");
+    const out = join(dir, rel);
+    mkdirSync(join(out, ".."), { recursive: true });
+    const text = readFileSync(source, "utf8");
+    // The kit files are copied byte for byte; everything else gets the app's names.
+    const filled = /(^|\/)public\/(ais6-bridge\.js|kit\.css)$/.test(rel) ? text : text.replace(/__[A-Z_]+__/g, (key) => values[key] ?? key);
+    writeFileSync(out, filled);
+    files.push(rel);
+  }
+  return { dir, id: appId, window: values.__WINDOW__, files };
+}

package/src/files.mjs

@@ -0,0 +1,18 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Every file under `dir`, sorted, skipping the folders a build never ships. */
+export function listFiles(dir, { ignore = ["node_modules", ".git"] } = {}) {
+  const out = [];
+  const walk = (current) => {
+    for (const name of readdirSync(current).sort()) {
+      if (ignore.includes(name)) continue;
+      const full = join(current, name);
+      const stat = statSync(full);
+      if (stat.isDirectory()) walk(full);
+      else if (stat.isFile()) out.push(full);
+    }
+  };
+  if (existsSync(dir)) walk(dir);
+  return out;
+}

package/src/index.mjs

@@ -0,0 +1,5 @@
+export { runCheck, locate } from "./check.mjs";
+export { manifestProblems, allowProblems, kitRangeAllows, CAPABILITIES, FRAME_PERMISSIONS, PROTOCOLS, KIT_MAJOR, ID_PATTERN } from "./manifest.mjs";
+export { scanAppTree, APP_SIDE_RULES, OWN_STORAGE } from "./boundary.mjs";
+export { scanForPublishing, credentialPatterns, localPathPatterns, forbiddenPathPatterns } from "./publish.mjs";
+export { createApp, windowNameFor, titleFor } from "./create.mjs";

package/src/manifest.mjs

@@ -0,0 +1,120 @@
+// What a desk accepts in app.manifest.json (bridge protocol 1, kit 1). The
+// desk's own pin and verify steps import these, so an app that passes here
+// passes there.
+
+export const PROTOCOLS = Object.freeze([1]);
+export const KIT_MAJOR = 1;
+export const ID_PATTERN = /^[a-z][a-z0-9-]{1,40}$/;
+export const WINDOW_PATTERN = /^[a-z][A-Za-z0-9]{1,60}$/;
+export const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export const CLASS_LIST_PATTERN = /^[a-z][a-z0-9-]*(\s+[a-z][a-z0-9-]*)*$/;
+
+// The closed set of capabilities a window may declare. The desk's bridge host
+// keeps the same list (a contract asserts the two agree).
+export const CAPABILITIES = Object.freeze(["state", "files", "receipts", "intents", "snapshot", "model", "windows", "appearance", "access", "wake", "services", "context"]);
+
+// The iframe permissions a window may ask for (`allow`).
+export const FRAME_PERMISSIONS = Object.freeze(["fullscreen", "gamepad"]);
+
+/** ">=1 <2", "1", "^1": does a kit major satisfy the app's range? */
+export function kitRangeAllows(range, major = KIT_MAJOR) {
+  const text = String(range ?? "").trim();
+  if (!text) return false;
+  if (/^\^?\d+$/.test(text)) return Number(text.replace("^", "")) === major;
+  return text.split(/\s+/).every((part) => {
+    const match = /^(>=|<=|>|<|=)?(\d+)$/.exec(part);
+    if (!match) return false;
+    const value = Number(match[2]);
+    switch (match[1] || "=") {
+      case ">=": return major >= value;
+      case "<=": return major <= value;
+      case ">": return major > value;
+      case "<": return major < value;
+      default: return major === value;
+    }
+  });
+}
+
+/** The frame permission and status class rules alone (the desk's pin step). */
+export function allowProblems(manifest) {
+  const problems = [];
+  for (const entry of manifest?.windows || []) {
+    if (entry.statusClass !== undefined && !(typeof entry.statusClass === "string" && CLASS_LIST_PATTERN.test(entry.statusClass))) {
+      problems.push(`window ${entry.window}: statusClass must be class names`);
+    }
+    if (entry.allow === undefined) continue;
+    if (typeof entry.allow !== "string") { problems.push(`window ${entry.window}: allow must be a string`); continue; }
+    for (const token of entry.allow.split(";").map((part) => part.trim()).filter(Boolean)) {
+      if (!FRAME_PERMISSIONS.includes(token)) problems.push(`window ${entry.window}: allow "${token}" is not one of ${FRAME_PERMISSIONS.join(", ")}`);
+    }
+  }
+  return problems;
+}
+
+function menuKeys(items, keys = []) {
+  for (const item of Array.isArray(items) ? items : []) {
+    if (item?.labelKey) keys.push(item.labelKey);
+    if (item?.items) menuKeys(item.items, keys);
+  }
+  return keys;
+}
+
+/**
+ * Every problem a desk would refuse the manifest for, as plain sentences.
+ * `fileExists(path)` (optional) answers whether an entry page is present.
+ */
+export function manifestProblems(manifest, { fileExists, warnings = [] } = {}) {
+  const problems = [];
+  const fail = (message) => problems.push(message);
+  // A desk shows a key it does not find in the manifest from its own tables
+  // (close, cut, refresh…) and otherwise as the bare key: worth a warning, not
+  // a refusal.
+  const warn = (message) => warnings.push(message);
+  if (!manifest || typeof manifest !== "object") return ["the manifest is not a JSON object"];
+  if (!ID_PATTERN.test(String(manifest.id || ""))) fail(`id "${manifest.id ?? ""}" must be lower case letters, digits and dashes (2–41 characters, starting with a letter)`);
+  if (!VERSION_PATTERN.test(String(manifest.version || ""))) fail(`version "${manifest.version ?? ""}" must be a semantic version such as 1.0.0`);
+  if (!PROTOCOLS.includes(manifest.protocol)) fail(`protocol ${manifest.protocol} is not one this desk speaks (${PROTOCOLS.join(", ")})`);
+  if (!kitRangeAllows(manifest.kit)) fail(`kit range "${manifest.kit ?? ""}" does not include kit ${KIT_MAJOR}`);
+  const strings = manifest.strings || {};
+  const en = strings.en || {};
+  const zh = strings.zh || {};
+  if (!strings.en || !strings.zh) fail("strings must have both en and zh tables");
+  const enOnly = Object.keys(en).filter((key) => !(key in zh));
+  const zhOnly = Object.keys(zh).filter((key) => !(key in en));
+  if (enOnly.length) fail(`strings missing in zh: ${enOnly.join(", ")}`);
+  if (zhOnly.length) fail(`strings missing in en: ${zhOnly.join(", ")}`);
+  const windows = Array.isArray(manifest.windows) ? manifest.windows : [];
+  if (!windows.length) fail("windows must list at least one window");
+  const seen = new Set();
+  for (const win of windows) {
+    const name = String(win?.window || "");
+    const label = `window ${name || "(unnamed)"}`;
+    if (!WINDOW_PATTERN.test(name)) fail(`${label}: window must be a camelCase name`);
+    if (seen.has(name)) fail(`${label}: declared twice`);
+    seen.add(name);
+    if (!win.app || typeof win.app !== "string") fail(`${label}: app is required`);
+    if (!win.entry || typeof win.entry !== "string" || /^(?:[a-z]+:|\/)/i.test(win.entry) || win.entry.includes("..")) fail(`${label}: entry must be a page inside the app`);
+    else if (fileExists && !fileExists(win.entry.split(/[?#]/)[0])) fail(`${label}: entry ${win.entry} does not exist`);
+    if (!win.titleKey) fail(`${label}: titleKey is required`);
+    else if (!(win.titleKey in en)) warn(`${label}: titleKey ${win.titleKey} is not in the manifest's strings (the desk must already know it)`);
+    for (const key of ["windowClass", "paneClass", "frameClass"]) {
+      if (win[key] !== undefined && !(typeof win[key] === "string" && CLASS_LIST_PATTERN.test(win[key]))) fail(`${label}: ${key} must be class names`);
+    }
+    const caps = win.capabilities;
+    if (!Array.isArray(caps)) fail(`${label}: capabilities must be a list`);
+    else {
+      const unknown = caps.filter((cap) => !CAPABILITIES.includes(cap));
+      if (unknown.length) fail(`${label}: unknown capabilities ${unknown.join(", ")} (the closed set is ${CAPABILITIES.join(", ")})`);
+    }
+    if (win.services !== undefined) {
+      if (!Array.isArray(win.services) || win.services.some((service) => typeof service !== "string" || !service)) fail(`${label}: services must be a list of names`);
+      else if (win.services.length && !(caps || []).includes("services")) fail(`${label}: lists services but not the services capability`);
+    }
+    if (win.size !== undefined && (typeof win.size !== "object" || Array.isArray(win.size))) fail(`${label}: size must be { width, height }`);
+    if (win.menus !== undefined && !Array.isArray(win.menus)) fail(`${label}: menus must be a list`);
+    const missing = menuKeys(win.menus).filter((key) => !(key in en) && !/^(?:menu_[a-z]+|close|cut|copy|paste|clear|select_all|undo|redo)$/.test(key));
+    if (missing.length) warn(`${label}: menu labels not in the manifest's strings (the desk must already know them): ${[...new Set(missing)].join(", ")}`);
+  }
+  problems.push(...allowProblems(manifest));
+  return problems;
+}