ais6-app 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,21 @@
 # ais6-app
 
-Check an AI System 6 app the way a desk checks it before installing it.
+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

package/README.zh-CN.md

@@ -1,12 +1,20 @@
+<!-- canonical-source: packages/ais6-app/README.md -->
+<!-- source-sha256: 246087a9156aa7044435339b6056107420709aba7633d78c2507709caddb1ab1 -->
+
+> 英文版为准；本说明仅供人类参考。
+
 # ais6-app
 
-按 AI System 6 桌面在安装前的检查方式，检查你的 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。
 
 | 检查 | 看什么 |

package/bin/ais6-app.mjs

@@ -2,12 +2,14 @@
 // 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];
@@ -18,6 +20,8 @@ if (!command || command === "--help" || command === "-h" || command === "help")
 
 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
@@ -33,9 +37,34 @@ 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 valueOf = (flag) => { const index = args.indexOf(flag); return index >= 0 ? String(args[index + 1] || "") : ""; };
 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)) || ".");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ais6-app",
-  "version": "0.1.0",
-  "description": "Check an AI System 6 app the way a desk checks it before installing it.",
+  "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": {
@@ -11,11 +11,13 @@
     ".": "./src/index.mjs",
     "./manifest": "./src/manifest.mjs",
     "./boundary": "./src/boundary.mjs",
-    "./publish": "./src/publish.mjs"
+    "./publish": "./src/publish.mjs",
+    "./create": "./src/create.mjs"
   },
   "files": [
     "bin",
     "src",
+    "template",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"

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/index.mjs

@@ -2,3 +2,4 @@ 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/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) __YEAR__ __AUTHOR__
+
+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/template/README.md

@@ -0,0 +1,40 @@
+# __NAME__
+
+An app for AI System 6, made from the `ais6-app create` template
+(TypeScript + Preact). It runs in a window of the desk, and on its own page.
+
+[中文说明](README.zh-CN.md)
+
+## Run it
+
+```bash
+npm install
+npm run dev        # its own page, with the kit's standalone adapter
+npm run check      # types, lint, tests, build, then ais6-app check
+```
+
+`npm run build` writes `dist/`, the folder a desk installs.
+
+## Where things are
+
+| Path | What it holds |
+| --- | --- |
+| `public/app.manifest.json` | id, version, window, capabilities, menus, the window title in both languages |
+| `public/ais6-bridge.js`, `public/kit.css` | the app kit: the bridge client and the shared controls. Do not edit; update them from the kit |
+| `src/bridge/` | the one connection to the desk, typed |
+| `src/strings/` | every string, in English and Chinese; a missing key does not compile |
+| `src/ui/`, `src/styles/` | the window's content, drawn with the kit's classes and tokens |
+
+## Rules a desk enforces
+
+- Everything outside the frame goes through the bridge: no `window.parent`,
+  no desk globals, no `localStorage` of your own.
+- The version in `app.manifest.json`, `package.json` and `APP_VERSION` in
+  `src/bridge/bridge.ts` is one number. Raise all three together.
+- A capability or service the manifest does not list is refused.
+
+The full SDK: https://aisystem6.aaronlau.me/sdk/
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/template/README.zh-CN.md

@@ -0,0 +1,37 @@
+# __NAME_ZH__
+
+一个 AI System 6 应用，由 `ais6-app create` 模板生成（TypeScript + Preact）。它在桌面的窗口里运行，也能在自己的页面上单独运行。
+
+[English](README.md)
+
+## 运行
+
+```bash
+npm install
+npm run dev        # 独立页面，由套件的独立适配器应答
+npm run check      # 类型、lint、测试、构建，最后跑 ais6-app check
+```
+
+`npm run build` 生成 `dist/`，也就是桌面安装的文件夹。
+
+## 文件在哪里
+
+| 路径 | 内容 |
+| --- | --- |
+| `public/app.manifest.json` | id、版本、窗口、能力、菜单，以及两种语言的窗口标题 |
+| `public/ais6-bridge.js`、`public/kit.css` | 应用套件：桥接客户端和共用控件。不要改，从套件更新 |
+| `src/bridge/` | 与桌面之间唯一的连接，带类型 |
+| `src/strings/` | 所有文字，英文和中文各一份；少一个键就编译不过 |
+| `src/ui/`、`src/styles/` | 窗口内容，用套件的类和令牌绘制 |
+
+## 桌面会检查的规则
+
+- 框架之外的一切都经过桥接：不碰 `window.parent`，不碰桌面的全局对象，不自己用 `localStorage`。
+- `app.manifest.json`、`package.json` 和 `src/bridge/bridge.ts` 里的 `APP_VERSION` 是同一个版本号，要一起改。
+- 清单没列出的能力或服务一律拒绝。
+
+完整 SDK：https://aisystem6.aaronlau.me/sdk/
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/template/biome.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "files": {
+    "includes": ["**", "!dist", "!node_modules", "!public", "!**/*.md"]
+  },
+  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 120 },
+  "linter": { "enabled": true, "rules": { "preset": "recommended" } }
+}

package/template/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__NAME__</title>
+    <link rel="stylesheet" href="./kit.css" />
+    <script src="./ais6-bridge.js"></script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__APP_ID__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -b",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm run test && npm run build && ais6-app check ."
+  },
+  "dependencies": {
+    "preact": "11.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.7",
+    "@preact/preset-vite": "2.10.6",
+    "ais6-app": "^__CHECKER_VERSION__",
+    "typescript": "7.0.2",
+    "vite": "8.3.8",
+    "vitest": "5.1.0"
+  }
+}