@glassly/miniapp-cli 0.1.0-dev.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +221 -0
- package/package.json +52 -0
- package/schema/miniapp.schema.json +245 -0
- package/src/api.ts +4 -0
- package/src/build-helpers.test.ts +104 -0
- package/src/build-helpers.ts +357 -0
- package/src/build.ts +67 -0
- package/src/dev-server.test.ts +138 -0
- package/src/dev-server.ts +454 -0
- package/src/dev.ts +348 -0
- package/src/hardware.ts +163 -0
- package/src/index.ts +127 -0
- package/src/lan.test.ts +84 -0
- package/src/lan.ts +161 -0
- package/src/manifest-format.ts +121 -0
- package/src/manifest-mutate.test.ts +191 -0
- package/src/manifest-mutate.ts +213 -0
- package/src/manifest-wizard.ts +218 -0
- package/src/manifest.test.ts +322 -0
- package/src/manifest.ts +340 -0
- package/src/pack.ts +137 -0
- package/src/permission-hints.ts +36 -0
- package/src/permission.ts +142 -0
- package/src/qr.test.ts +81 -0
- package/src/qr.ts +119 -0
- package/src/release.ts +263 -0
- package/src/schema.test.ts +54 -0
- package/src/schema.ts +231 -0
package/README.md
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# @glassly/miniapp-cli (`glassly-miniapp`)
|
|
2
|
+
|
|
3
|
+
Author-facing CLI for Glassly miniapps. Pairs with [`@glassly/miniapp`](../miniapp).
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
glassly-miniapp <command>
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Commands at a glance
|
|
10
|
+
|
|
11
|
+
| Command | What it does |
|
|
12
|
+
| ------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
13
|
+
| [`dev`](#dev) | Starts the dev server with hot reload, prints a QR to load it on a phone |
|
|
14
|
+
| [`release`](#release) | Builds, packs, and serves a QR to install the release on a phone over LAN |
|
|
15
|
+
| [`pack`](#pack) | Validates the manifest and zips `dist/` into `<pkg>-<version>.zip` |
|
|
16
|
+
| [`manifest`](#manifest) | Interactive top-level wizard for editing `miniapp.json` |
|
|
17
|
+
| [`permission list \| add \| remove`](#permission) | Object-verb manifest edits for permissions |
|
|
18
|
+
| [`hardware list \| add \| remove`](#hardware) | Object-verb manifest edits for hardware requirements |
|
|
19
|
+
| [`schema print`](#schema) | Prints the canonical `miniapp.json` JSON Schema to stdout |
|
|
20
|
+
|
|
21
|
+
Run with no args to print the same usage table.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## `dev`
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
glassly-miniapp dev
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
What it does:
|
|
32
|
+
|
|
33
|
+
1. Reads + validates `miniapp.json` (hard-fails on bad permissions / hardware types so you don't have to debug it on the phone).
|
|
34
|
+
2. Runs the project's `build.ts` so `dist/background/index.js` and `dist/ui/*` are current.
|
|
35
|
+
3. Picks the first free adjacent port pair starting at `port`: one for static files and the next for the dev sidecar.
|
|
36
|
+
4. Starts a static server that serves `miniapp.json`, `icon.png`, and project files.
|
|
37
|
+
5. Starts a **dev sidecar** on `port + 1` — a WebSocket the phone connects to for live reload + console-log forwarding back to your terminal. Failure here is non-fatal; the miniapp still runs without live reload.
|
|
38
|
+
6. Detects the LAN IP, builds a `miniapp://dev?url=…&name=…&package=…&dev=<sidecarPort>` URL, and prints a terminal QR + the raw URL.
|
|
39
|
+
7. Watches for LAN-IP changes (Wi-Fi switch) every 10s and reprints the QR.
|
|
40
|
+
|
|
41
|
+
Default `port` is `3000`; override the starting point with a `"port": <n>` field in `miniapp.json`. If that port or its sidecar neighbor is busy, `dev` scans upward until it finds a free adjacent pair.
|
|
42
|
+
|
|
43
|
+
**On the phone:** open the Glassly App → **Settings → Developer settings → Mini App Development → Scan Mini App QR Code**. Phone and laptop must be on the same Wi-Fi.
|
|
44
|
+
|
|
45
|
+
`dev` is live and temporary. Keep the CLI and computer running because the
|
|
46
|
+
Glassly App loads the runtime bundle from that LAN server. Dev miniapps are keyed
|
|
47
|
+
by their manifest package name, so you can scan and test several side by side;
|
|
48
|
+
rescanning the same package updates only that entry. The Glassly App caches each
|
|
49
|
+
entry's name and icon. Use `bun run release` when you need an installed miniapp
|
|
50
|
+
that works without the computer.
|
|
51
|
+
|
|
52
|
+
`Ctrl+C` stops the server, the sidecar, and the IP watcher.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## `release`
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
glassly-miniapp release
|
|
60
|
+
glassly-miniapp release --no-cache # force rebuild even if cache is fresh
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The all-in-one verb: build a release, pack it, and serve it behind a QR so you can install on as many phones as you like.
|
|
64
|
+
|
|
65
|
+
Flow:
|
|
66
|
+
|
|
67
|
+
1. Validates `miniapp.json`.
|
|
68
|
+
2. **Build cache.** Looks for `build/<packageName>-<version>.zip`. If it exists and every project source file (excluding `node_modules`, `dist`, `build`, `.git`) is older than the zip, reuses it. Otherwise rebuilds.
|
|
69
|
+
3. **Build.** Detects your package manager (`bun.lock` → `bun`, `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, else `npm`) and runs `<pm> run build`. Your `package.json` must define a `build` script that produces `dist/`.
|
|
70
|
+
4. **Pack.** Calls the same logic as `glassly-miniapp pack` — validates the manifest, copies `miniapp.json` + `icon.png` into `dist/`, zips to `build/<packageName>-<version>.zip`. Prints size + duration.
|
|
71
|
+
5. **Serve.** Picks a free port between 6789 and 6798. Hosts the bundle, manifest, and icon over HTTP on `0.0.0.0`:
|
|
72
|
+
- `GET /miniapp.json`
|
|
73
|
+
- `GET /icon.png`
|
|
74
|
+
- `GET /bundle.zip`
|
|
75
|
+
- `GET /__glassly_release/health`
|
|
76
|
+
6. Prints a `miniapp://release?url=<lan-base>&package=…&version=…&name=…` URL + QR.
|
|
77
|
+
7. Stays up so multiple devices can install. Each `/bundle.zip` fetch logs `✓ Install #N — <name>@<version> → <remote>`.
|
|
78
|
+
|
|
79
|
+
`Ctrl+C` to stop the server.
|
|
80
|
+
|
|
81
|
+
**On the phone:** the Glassly App's QR scanner branches on `miniapp://release` and uses the dev composer to download + install the bundle. The miniapp lands in `lmas/<package>/<version>/` and behaves like any installed local miniapp — runs offline, persists across restarts, no laptop required after install.
|
|
82
|
+
|
|
83
|
+
> **Why "release" and not "install":** `install` collides with package managers (`bun run install` is reserved). Naming the action after the artifact you're producing avoids that collision and matches Android's `installRelease` mental model.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## `pack`
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
glassly-miniapp pack
|
|
91
|
+
glassly-miniapp pack --no-build # zip dist/ as-is, skip the build
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Produces a distributable ZIP. Use this when you want the artifact only — `release` calls `pack` internally.
|
|
95
|
+
|
|
96
|
+
Steps:
|
|
97
|
+
|
|
98
|
+
1. Runs `<pm> run build` with `NODE_ENV=production` (same as `release`), so the zip always contains a production bundle — never a stale dev build left behind by `dev`. Pass `--no-build` to skip this and zip whatever is already in `dist/`.
|
|
99
|
+
2. Verifies `dist/` exists.
|
|
100
|
+
3. Validates `miniapp.json`.
|
|
101
|
+
4. Copies `miniapp.json` and `icon.png` into `dist/`.
|
|
102
|
+
5. Runs the system `zip -r` command to produce `build/<packageName>-<version>.zip` and prints the absolute path.
|
|
103
|
+
|
|
104
|
+
`build/` is self-ignoring — the CLI writes a `.gitignore` containing `*` into it on creation, so packed zips stay out of version control in any repo without touching the project's own `.gitignore`.
|
|
105
|
+
|
|
106
|
+
The resulting ZIP is the artifact you'd upload to the miniapp store.
|
|
107
|
+
|
|
108
|
+
> Requires the `zip` binary on `PATH` (preinstalled on macOS and most Linux distros). On Windows, install `zip` via WSL or use a Unix-like shell.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## `manifest`
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
glassly-miniapp manifest
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Interactive top-level wizard for `miniapp.json` (Clack-based). Loop:
|
|
119
|
+
|
|
120
|
+
- **Edit permissions** — add, remove
|
|
121
|
+
- **Edit hardware requirements** — add, remove
|
|
122
|
+
- **Show current manifest** — pretty-prints the JSON
|
|
123
|
+
- **Done** — exits
|
|
124
|
+
|
|
125
|
+
Persists after every confirmed change, so `Ctrl+C` never loses a saved edit.
|
|
126
|
+
|
|
127
|
+
The wizard shares its mutation backend (`manifest-mutate.ts`) with the object-verb commands below — behavior and validation are identical.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## `permission`
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
glassly-miniapp permission list
|
|
135
|
+
glassly-miniapp permission add [TYPE]
|
|
136
|
+
glassly-miniapp permission remove [TYPE]
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`add` / `remove` are interactive when called without `TYPE` (Clack select prompts) and non-interactive when `TYPE` is provided.
|
|
140
|
+
|
|
141
|
+
Allowed `TYPE` values: `MICROPHONE`, `CAMERA`, `CALENDAR`, `LOCATION`, `BACKGROUND_LOCATION`, `READ_NOTIFICATIONS`, `POST_NOTIFICATIONS`.
|
|
142
|
+
|
|
143
|
+
Adding a permission interactively prompts for an optional human-readable description (shown in the OS prompt when the user is asked to grant the permission).
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## `hardware`
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
glassly-miniapp hardware list
|
|
151
|
+
glassly-miniapp hardware add [TYPE] [LEVEL]
|
|
152
|
+
glassly-miniapp hardware remove [TYPE]
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Allowed `TYPE` values: `CAMERA`, `DISPLAY`, `MICROPHONE`, `SPEAKER`, `IMU`, `BUTTON`, `LIGHT`, `WIFI`.
|
|
156
|
+
Allowed `LEVEL` values: `REQUIRED`, `OPTIONAL`.
|
|
157
|
+
|
|
158
|
+
- `REQUIRED` — glasses without this hardware can't run the app (hidden in the store / launcher on incompatible devices).
|
|
159
|
+
- `OPTIONAL` — glasses without this hardware still run the app, in a degraded state.
|
|
160
|
+
|
|
161
|
+
Add is interactive when called without `TYPE` / `LEVEL`. Non-interactive form requires both.
|
|
162
|
+
|
|
163
|
+
> The `EXIST` hardware type is injected by the phone at runtime (every miniapp implicitly requires that glasses are present). It's intentionally not in the allowed-types list — don't declare it.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## `schema`
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
glassly-miniapp schema print
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Prints the canonical `miniapp.json` JSON Schema to stdout. Useful for piping into IDE config or for validation in CI.
|
|
174
|
+
|
|
175
|
+
The schema is generated from the same constants the validator uses (`ALLOWED_PERMISSIONS`, `ALLOWED_HARDWARE_TYPES`, `ALLOWED_HARDWARE_LEVELS`), so it can never drift from validation behavior.
|
|
176
|
+
|
|
177
|
+
The published schema file ships at `node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json` for editors that read `$schema` from `miniapp.json`. The scaffolder (`create-miniapp`) injects this `$schema` line into new projects automatically.
|
|
178
|
+
|
|
179
|
+
> `glassly-miniapp schema regenerate` exists too but is a CLI-internal command — it rewrites the published schema file from the in-source allowed-values lists. Authors don't need it.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## `miniapp.json` shape
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json",
|
|
188
|
+
"packageName": "com.glassly.example",
|
|
189
|
+
"version": "1.0.0",
|
|
190
|
+
"name": "Glassly Example",
|
|
191
|
+
"description": "…",
|
|
192
|
+
"icon": "icon.png",
|
|
193
|
+
"port": 3000,
|
|
194
|
+
"permissions": [{"type": "MICROPHONE", "description": "Listen for what to caption."}],
|
|
195
|
+
"hardwareRequirements": [
|
|
196
|
+
{"type": "DISPLAY", "level": "REQUIRED"},
|
|
197
|
+
{"type": "MICROPHONE", "level": "REQUIRED"}
|
|
198
|
+
]
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Required: `packageName`, `version`, `name`, `hardwareRequirements`. Everything else is optional.
|
|
203
|
+
|
|
204
|
+
`packageName` must be reverse-DNS (`^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$`).
|
|
205
|
+
|
|
206
|
+
`port` defaults to `3000` for `dev` and is ignored by `release` (which picks its own free port). For `dev`, this is the starting port; if the port or its sidecar neighbor is busy, the CLI scans upward until it finds a free adjacent pair.
|
|
207
|
+
|
|
208
|
+
The CLI's allowed-value lists are mirrored by hand from `@glassly/types` to keep the CLI dependency-light so `bunx glassly-miniapp` stays fast. Drift between the two is caught at validation time, not import time.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## File map
|
|
213
|
+
|
|
214
|
+
- Subcommand handlers: `src/{dev,release,pack,permission,hardware,schema,manifest-wizard}.ts`
|
|
215
|
+
- Manifest validation + allowed-value lists: `src/manifest.ts`
|
|
216
|
+
- Manifest mutation backend (shared by wizard + object-verb commands): `src/manifest-mutate.ts`
|
|
217
|
+
- Manifest read/write helpers: `src/manifest-format.ts`
|
|
218
|
+
- Permission/hardware human-readable hints: `src/permission-hints.ts`
|
|
219
|
+
- Dev sidecar WebSocket server: `src/dev-server.ts`
|
|
220
|
+
- QR rendering: `src/qr.ts`
|
|
221
|
+
- Generated JSON Schema: `schema/miniapp.schema.json` (regenerated via `schema regenerate`)
|
package/package.json
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@glassly/miniapp-cli",
|
|
3
|
+
"version": "0.1.0-dev.1",
|
|
4
|
+
"description": "Dev tools for Glassly miniapps",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"glassly-miniapp": "./src/index.ts"
|
|
8
|
+
},
|
|
9
|
+
"publishConfig": {
|
|
10
|
+
"access": "public",
|
|
11
|
+
"tag": "dev"
|
|
12
|
+
},
|
|
13
|
+
"exports": {
|
|
14
|
+
".": "./src/api.ts",
|
|
15
|
+
"./build-helpers": "./src/build-helpers.ts",
|
|
16
|
+
"./lan": "./src/lan.ts",
|
|
17
|
+
"./package.json": "./package.json"
|
|
18
|
+
},
|
|
19
|
+
"scripts": {
|
|
20
|
+
"build": "bun src/index.ts schema regenerate",
|
|
21
|
+
"prepare": "bun src/index.ts schema regenerate"
|
|
22
|
+
},
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@clack/prompts": "^1.2.0",
|
|
25
|
+
"jszip": "^3.10.1",
|
|
26
|
+
"qrcode": "^1.5.4",
|
|
27
|
+
"typescript": "^5.0.0"
|
|
28
|
+
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@types/qrcode": "^1.5.5",
|
|
31
|
+
"bun-types": "1.3.14"
|
|
32
|
+
},
|
|
33
|
+
"files": [
|
|
34
|
+
"src",
|
|
35
|
+
"schema"
|
|
36
|
+
],
|
|
37
|
+
"keywords": [
|
|
38
|
+
"glassly",
|
|
39
|
+
"glassly",
|
|
40
|
+
"miniapp",
|
|
41
|
+
"cli"
|
|
42
|
+
],
|
|
43
|
+
"repository": {
|
|
44
|
+
"type": "git",
|
|
45
|
+
"url": "git+https://github.com/tetramo-labs/glassly.git",
|
|
46
|
+
"directory": "sdk/miniapp-cli"
|
|
47
|
+
},
|
|
48
|
+
"homepage": "https://github.com/tetramo-labs/glassly/tree/dev/sdk/miniapp-cli#readme",
|
|
49
|
+
"bugs": {
|
|
50
|
+
"url": "https://github.com/tetramo-labs/glassly/issues"
|
|
51
|
+
}
|
|
52
|
+
}
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://schemas.glassly.com/miniapp/v1.json",
|
|
4
|
+
"title": "Glassly miniapp manifest",
|
|
5
|
+
"description": "Manifest schema for a Glassly miniapp (miniapp.json)",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": [
|
|
8
|
+
"packageName",
|
|
9
|
+
"version",
|
|
10
|
+
"name",
|
|
11
|
+
"hardwareRequirements"
|
|
12
|
+
],
|
|
13
|
+
"additionalProperties": true,
|
|
14
|
+
"properties": {
|
|
15
|
+
"$schema": {
|
|
16
|
+
"type": "string"
|
|
17
|
+
},
|
|
18
|
+
"packageName": {
|
|
19
|
+
"type": "string",
|
|
20
|
+
"pattern": "^[a-zA-Z][a-zA-Z0-9_]*(\\.[a-zA-Z][a-zA-Z0-9_]*)+$",
|
|
21
|
+
"description": "Reverse-DNS app identifier (e.g. com.example.app)"
|
|
22
|
+
},
|
|
23
|
+
"version": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"description": "Semver version string (e.g. 1.0.0)"
|
|
26
|
+
},
|
|
27
|
+
"name": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"description": "Human-readable app name"
|
|
30
|
+
},
|
|
31
|
+
"description": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"description": "Short description shown in the store / dev tools"
|
|
34
|
+
},
|
|
35
|
+
"icon": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"description": "Path or URL to the app icon (e.g. icon.png)"
|
|
38
|
+
},
|
|
39
|
+
"port": {
|
|
40
|
+
"type": "integer",
|
|
41
|
+
"minimum": 1,
|
|
42
|
+
"maximum": 65535,
|
|
43
|
+
"description": "Port the dev server listens on (default 3000)"
|
|
44
|
+
},
|
|
45
|
+
"sdkVersion": {
|
|
46
|
+
"type": "string",
|
|
47
|
+
"description": "Semver of the @glassly/miniapp SDK this bundle targets. Host refuses to spawn a miniapp whose sdkVersion is incompatible with the runtime it ships."
|
|
48
|
+
},
|
|
49
|
+
"minHostVersion": {
|
|
50
|
+
"type": "string",
|
|
51
|
+
"description": "Semver of the lowest Glassly Manager host version that can run this bundle. The host re-validates this on every install and after host upgrades; bundles that no longer meet the bar are disabled (not deleted) with a clear UI."
|
|
52
|
+
},
|
|
53
|
+
"entry": {
|
|
54
|
+
"type": "object",
|
|
55
|
+
"description": "Two-layer bundle entry points. Background is the always-running JSContext entry; UI is the on-demand WebView entry.",
|
|
56
|
+
"additionalProperties": false,
|
|
57
|
+
"required": [
|
|
58
|
+
"background"
|
|
59
|
+
],
|
|
60
|
+
"properties": {
|
|
61
|
+
"background": {
|
|
62
|
+
"type": "string",
|
|
63
|
+
"description": "Path to the background bundle, relative to the bundle root (e.g. background/index.js). Required for V2+ two-layer bundles."
|
|
64
|
+
},
|
|
65
|
+
"ui": {
|
|
66
|
+
"type": "string",
|
|
67
|
+
"description": "Path to the UI bundle entry HTML, relative to the bundle root (e.g. ui/index.html). Optional -- pure-background miniapps don't need a WebView."
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
"type": {
|
|
72
|
+
"type": "string",
|
|
73
|
+
"enum": [
|
|
74
|
+
"standard",
|
|
75
|
+
"background"
|
|
76
|
+
],
|
|
77
|
+
"description": "Miniapp type. 'standard' includes a UI WebView; 'background' is JSContext-only. Defaults to 'standard'."
|
|
78
|
+
},
|
|
79
|
+
"permissions": {
|
|
80
|
+
"type": "array",
|
|
81
|
+
"description": "Phone permissions the miniapp needs to declare",
|
|
82
|
+
"items": {
|
|
83
|
+
"type": "object",
|
|
84
|
+
"required": [
|
|
85
|
+
"type"
|
|
86
|
+
],
|
|
87
|
+
"additionalProperties": false,
|
|
88
|
+
"properties": {
|
|
89
|
+
"type": {
|
|
90
|
+
"type": "string",
|
|
91
|
+
"enum": [
|
|
92
|
+
"MICROPHONE",
|
|
93
|
+
"CAMERA",
|
|
94
|
+
"CALENDAR",
|
|
95
|
+
"LOCATION",
|
|
96
|
+
"BACKGROUND_LOCATION",
|
|
97
|
+
"READ_NOTIFICATIONS",
|
|
98
|
+
"POST_NOTIFICATIONS",
|
|
99
|
+
"API_KEYS",
|
|
100
|
+
"MEMORY",
|
|
101
|
+
"AI",
|
|
102
|
+
"SPEAKERS"
|
|
103
|
+
],
|
|
104
|
+
"description": "Permission type"
|
|
105
|
+
},
|
|
106
|
+
"required": {
|
|
107
|
+
"type": "boolean",
|
|
108
|
+
"description": "If false, the permission is optional. Defaults to required at runtime."
|
|
109
|
+
},
|
|
110
|
+
"description": {
|
|
111
|
+
"type": "string",
|
|
112
|
+
"description": "User-facing reason this permission is needed (shown in OS prompts)"
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
},
|
|
117
|
+
"hardwareRequirements": {
|
|
118
|
+
"type": "array",
|
|
119
|
+
"description": "Glasses hardware capabilities the miniapp needs",
|
|
120
|
+
"items": {
|
|
121
|
+
"type": "object",
|
|
122
|
+
"required": [
|
|
123
|
+
"type",
|
|
124
|
+
"level"
|
|
125
|
+
],
|
|
126
|
+
"additionalProperties": false,
|
|
127
|
+
"properties": {
|
|
128
|
+
"type": {
|
|
129
|
+
"type": "string",
|
|
130
|
+
"enum": [
|
|
131
|
+
"CAMERA",
|
|
132
|
+
"DISPLAY",
|
|
133
|
+
"MICROPHONE",
|
|
134
|
+
"SPEAKER",
|
|
135
|
+
"IMU",
|
|
136
|
+
"BUTTON",
|
|
137
|
+
"LIGHT",
|
|
138
|
+
"WIFI"
|
|
139
|
+
],
|
|
140
|
+
"description": "Hardware capability type"
|
|
141
|
+
},
|
|
142
|
+
"level": {
|
|
143
|
+
"type": "string",
|
|
144
|
+
"enum": [
|
|
145
|
+
"REQUIRED",
|
|
146
|
+
"OPTIONAL"
|
|
147
|
+
],
|
|
148
|
+
"description": "REQUIRED hides the app on glasses without it; OPTIONAL still lets it run"
|
|
149
|
+
},
|
|
150
|
+
"description": {
|
|
151
|
+
"type": "string",
|
|
152
|
+
"description": "How the miniapp uses this hardware"
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
},
|
|
157
|
+
"actions": {
|
|
158
|
+
"type": "array",
|
|
159
|
+
"description": "Actions other miniapps can discover and invoke via session.actions. Maps 1:1 onto MCP tools.",
|
|
160
|
+
"items": {
|
|
161
|
+
"type": "object",
|
|
162
|
+
"required": [
|
|
163
|
+
"id",
|
|
164
|
+
"description"
|
|
165
|
+
],
|
|
166
|
+
"additionalProperties": false,
|
|
167
|
+
"properties": {
|
|
168
|
+
"id": {
|
|
169
|
+
"type": "string",
|
|
170
|
+
"pattern": "^[a-z][a-z0-9_]*$",
|
|
171
|
+
"maxLength": 64,
|
|
172
|
+
"description": "Unique-within-app action id (lowercase, starts with a letter)."
|
|
173
|
+
},
|
|
174
|
+
"description": {
|
|
175
|
+
"type": "string",
|
|
176
|
+
"description": "AI-facing contract -- say when to use the action."
|
|
177
|
+
},
|
|
178
|
+
"visibility": {
|
|
179
|
+
"type": "string",
|
|
180
|
+
"enum": [
|
|
181
|
+
"public",
|
|
182
|
+
"system"
|
|
183
|
+
],
|
|
184
|
+
"description": "Who may invoke this action: \"public\" (default -- any installed miniapp) or \"system\" (system miniapps such as the AI assistant only)."
|
|
185
|
+
},
|
|
186
|
+
"parameters": {
|
|
187
|
+
"type": "object",
|
|
188
|
+
"description": "JSON-Schema input descriptor (the MCP inputSchema subset).",
|
|
189
|
+
"properties": {
|
|
190
|
+
"type": {
|
|
191
|
+
"const": "object"
|
|
192
|
+
},
|
|
193
|
+
"properties": {
|
|
194
|
+
"type": "object",
|
|
195
|
+
"additionalProperties": {
|
|
196
|
+
"type": "object",
|
|
197
|
+
"properties": {
|
|
198
|
+
"type": {
|
|
199
|
+
"type": "string",
|
|
200
|
+
"enum": [
|
|
201
|
+
"string",
|
|
202
|
+
"number",
|
|
203
|
+
"boolean",
|
|
204
|
+
"array"
|
|
205
|
+
]
|
|
206
|
+
},
|
|
207
|
+
"description": {
|
|
208
|
+
"type": "string"
|
|
209
|
+
},
|
|
210
|
+
"enum": {
|
|
211
|
+
"type": "array"
|
|
212
|
+
},
|
|
213
|
+
"items": {
|
|
214
|
+
"type": "object",
|
|
215
|
+
"properties": {
|
|
216
|
+
"type": {
|
|
217
|
+
"type": "string",
|
|
218
|
+
"enum": [
|
|
219
|
+
"string",
|
|
220
|
+
"number",
|
|
221
|
+
"boolean"
|
|
222
|
+
]
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
},
|
|
229
|
+
"required": {
|
|
230
|
+
"type": "array",
|
|
231
|
+
"items": {
|
|
232
|
+
"type": "string"
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
},
|
|
237
|
+
"outputSchema": {
|
|
238
|
+
"type": "object",
|
|
239
|
+
"description": "JSON-Schema descriptor for the structured action result (MCP outputSchema)."
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
}
|
package/src/api.ts
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import {describe, expect, test} from "bun:test"
|
|
2
|
+
|
|
3
|
+
import {findUnsupportedBackgroundApis} from "./build-helpers"
|
|
4
|
+
|
|
5
|
+
describe("background runtime guard", () => {
|
|
6
|
+
test("reports browser and Node globals with actionable replacements", () => {
|
|
7
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
8
|
+
import {readFile} from "node:fs/promises"
|
|
9
|
+
const started = performance.now()
|
|
10
|
+
document.querySelector("main")
|
|
11
|
+
const digest = crypto.subtle.digest("SHA-256", new Uint8Array())
|
|
12
|
+
void readFile
|
|
13
|
+
void started
|
|
14
|
+
void digest
|
|
15
|
+
`)
|
|
16
|
+
|
|
17
|
+
expect(findings.map(({api}) => api)).toEqual(["node:fs/promises", "performance", "document", "crypto.subtle"])
|
|
18
|
+
expect(findings.find(({api}) => api === "performance")?.replacement).toContain("Date.now()")
|
|
19
|
+
})
|
|
20
|
+
|
|
21
|
+
test("allows the documented background runtime and ordinary property names", () => {
|
|
22
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
23
|
+
interface Metrics { performance: number }
|
|
24
|
+
import type {Stats} from "node:fs"
|
|
25
|
+
import {type BufferEncoding} from "node:buffer"
|
|
26
|
+
export type {PathLike} from "node:fs"
|
|
27
|
+
export {type PathLike as FilePath} from "node:fs"
|
|
28
|
+
const metrics = {performance: Date.now()}
|
|
29
|
+
const bytes = new TextEncoder().encode("hello")
|
|
30
|
+
const id = crypto.randomUUID()
|
|
31
|
+
setTimeout(() => console.log(id, metrics.performance, bytes), 10)
|
|
32
|
+
void fetch("https://example.com", {headers: {"Content-Type": "application/json"}})
|
|
33
|
+
`)
|
|
34
|
+
|
|
35
|
+
expect(findings).toEqual([])
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
test("reports value re-exports from Node built-ins", () => {
|
|
39
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
40
|
+
export {readFile} from "node:fs/promises"
|
|
41
|
+
export * from "fs"
|
|
42
|
+
`)
|
|
43
|
+
|
|
44
|
+
expect(findings.map(({api}) => api)).toEqual(["node:fs/promises", "fs"])
|
|
45
|
+
})
|
|
46
|
+
|
|
47
|
+
test("allows public env values that the scaffold build inlines", () => {
|
|
48
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
49
|
+
const apiUrl = process.env.PUBLIC_API_URL
|
|
50
|
+
void fetch(apiUrl)
|
|
51
|
+
`)
|
|
52
|
+
|
|
53
|
+
expect(findings).toEqual([])
|
|
54
|
+
})
|
|
55
|
+
|
|
56
|
+
test("rejects process access that the scaffold cannot inline", () => {
|
|
57
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
58
|
+
const secret = process.env.API_SECRET
|
|
59
|
+
const env = process.env
|
|
60
|
+
void secret
|
|
61
|
+
void env
|
|
62
|
+
`)
|
|
63
|
+
|
|
64
|
+
expect(findings.map(({api}) => api)).toEqual(["process", "process"])
|
|
65
|
+
})
|
|
66
|
+
|
|
67
|
+
test("does not mistake local bindings for runtime globals", () => {
|
|
68
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
69
|
+
const location = {latitude: 1, longitude: 2}
|
|
70
|
+
const crypto = {subtle: "local"}
|
|
71
|
+
function report(performance: number) {
|
|
72
|
+
return {location, performance, subtle: crypto.subtle}
|
|
73
|
+
}
|
|
74
|
+
void report(1)
|
|
75
|
+
`)
|
|
76
|
+
|
|
77
|
+
expect(findings).toEqual([])
|
|
78
|
+
})
|
|
79
|
+
|
|
80
|
+
test("reports unsupported APIs accessed through global objects", () => {
|
|
81
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
82
|
+
globalThis.performance.now()
|
|
83
|
+
self.document.querySelector("main")
|
|
84
|
+
void globalThis.crypto.subtle
|
|
85
|
+
`)
|
|
86
|
+
|
|
87
|
+
expect(findings.map(({api}) => api)).toEqual([
|
|
88
|
+
"globalThis.performance",
|
|
89
|
+
"self.document",
|
|
90
|
+
"globalThis.crypto.subtle",
|
|
91
|
+
])
|
|
92
|
+
})
|
|
93
|
+
|
|
94
|
+
test("allows shadowed global-object names", () => {
|
|
95
|
+
const findings = findUnsupportedBackgroundApis(`
|
|
96
|
+
function read(globalThis: {performance: number}, self: {document: string}) {
|
|
97
|
+
return [globalThis.performance, self.document]
|
|
98
|
+
}
|
|
99
|
+
void read
|
|
100
|
+
`)
|
|
101
|
+
|
|
102
|
+
expect(findings).toEqual([])
|
|
103
|
+
})
|
|
104
|
+
})
|