@glassly/miniapp-cli 0.1.0-beta.3
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 +248 -0
- package/package.json +49 -0
- package/schema/miniapp.schema.json +269 -0
- package/src/api.ts +10 -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/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 +376 -0
- package/src/manifest.ts +412 -0
- package/src/pack.ts +131 -0
- package/src/permission-hints.ts +40 -0
- package/src/permission.ts +142 -0
- package/src/qr.test.ts +81 -0
- package/src/qr.ts +119 -0
- package/src/regenerate-schema.ts +6 -0
- package/src/release.ts +265 -0
- package/src/schema.test.ts +64 -0
- package/src/schema.ts +258 -0
package/README.md
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# @glassly/miniapp-cli
|
|
2
|
+
|
|
3
|
+
Build tooling for Glassly miniapps: the dev server, the packer, manifest
|
|
4
|
+
validation, and the `miniapp.json` JSON Schema. Pairs with
|
|
5
|
+
[`@glassly/miniapp`](../../mobile/modules/miniapp).
|
|
6
|
+
|
|
7
|
+
This package has no binary of its own. The `glassly` command from
|
|
8
|
+
[`@glassly/cli`](../cli) wraps every function here as a
|
|
9
|
+
subcommand, which is what the rest of this document describes:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
glassly <command>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Projects also import it directly: `build.ts` uses
|
|
16
|
+
`@glassly/miniapp-cli/build-helpers`, and `miniapp.json` points its `$schema` at
|
|
17
|
+
`node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json`. That is why it
|
|
18
|
+
stays a dev dependency next to `@glassly/cli`.
|
|
19
|
+
|
|
20
|
+
## Commands at a glance
|
|
21
|
+
|
|
22
|
+
| Command | What it does |
|
|
23
|
+
| ------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
24
|
+
| [`dev`](#dev) | Starts the dev server with hot reload, prints a QR to load it on a phone |
|
|
25
|
+
| [`release`](#release) | Builds, packs, and serves a QR to install the release on a phone over LAN |
|
|
26
|
+
| [`pack`](#pack) | Validates the manifest and zips `dist/` into `<pkg>-<version>.zip` |
|
|
27
|
+
| [`manifest`](#manifest) | Interactive top-level wizard for editing `miniapp.json` |
|
|
28
|
+
| [`permission list \| add \| remove`](#permission) | Object-verb manifest edits for permissions |
|
|
29
|
+
| [`hardware list \| add \| remove`](#hardware) | Object-verb manifest edits for hardware requirements |
|
|
30
|
+
| [`schema print`](#schema) | Prints the canonical `miniapp.json` JSON Schema to stdout |
|
|
31
|
+
|
|
32
|
+
Run `glassly --help` to print the same list.
|
|
33
|
+
|
|
34
|
+
## `dev`
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
glassly dev
|
|
38
|
+
glassly dev --qr lg # QR size: sm | md | lg (default md); -q also works
|
|
39
|
+
glassly dev --qr-output ./qr.png # also write the QR as a PNG, kept after exit
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
What it does:
|
|
43
|
+
|
|
44
|
+
1. Reads + validates `miniapp.json` (hard-fails on bad permissions / hardware types so you don't have to debug it on the phone).
|
|
45
|
+
2. Runs the project's `build.ts` so `dist/background/index.js` and `dist/ui/*` are current.
|
|
46
|
+
3. Picks the first free adjacent port pair starting at `port`: one for static files and the next for the dev sidecar.
|
|
47
|
+
4. Starts a static server that serves `miniapp.json`, `icon.png`, and project files.
|
|
48
|
+
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.
|
|
49
|
+
6. Detects the LAN IP, builds a `miniapp://dev?url=…&name=…&package=…&dev=<sidecarPort>` URL, and prints a terminal QR + the raw URL.
|
|
50
|
+
7. Watches for LAN-IP changes (Wi-Fi switch) every 2s and reprints the QR.
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
On the phone, open the Glassly App → **Settings → Miniapp Developer Settings → Scan Miniapp QR Code**. That settings row only appears with debug mode on. Phone and laptop must be on the same Wi-Fi.
|
|
55
|
+
|
|
56
|
+
Both `dev` and `release` take the same QR flags. `--qr` / `-q` sizes the terminal QR (`small|medium|large`, or `sm|md|lg`; default `medium`). `--qr-output <path>` also writes a PNG. Without it the CLI still writes a PNG to a temp path and deletes it on exit; pass `--qr-output` when you want to keep the file.
|
|
57
|
+
|
|
58
|
+
`dev` is live and temporary. Keep the CLI and computer running because the
|
|
59
|
+
Glassly App loads the runtime bundle from that LAN server. Dev miniapps are keyed
|
|
60
|
+
by their manifest package name, so you can scan and test several side by side;
|
|
61
|
+
rescanning the same package updates only that entry. The Glassly App caches each
|
|
62
|
+
entry's name and icon. Use `bun run release` when you need an installed miniapp
|
|
63
|
+
that works without the computer.
|
|
64
|
+
|
|
65
|
+
`Ctrl+C` stops the server, the sidecar, and the IP watcher.
|
|
66
|
+
|
|
67
|
+
## `release`
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
glassly release
|
|
71
|
+
glassly release --no-cache # force rebuild even if cache is fresh
|
|
72
|
+
glassly release --qr lg # QR size: sm | md | lg (default md); -q also works
|
|
73
|
+
glassly release --qr-output ./qr.png
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
Flow:
|
|
79
|
+
|
|
80
|
+
1. Validates `miniapp.json`.
|
|
81
|
+
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.
|
|
82
|
+
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/`.
|
|
83
|
+
4. **Pack.** Calls the same logic as `glassly pack`: validates the manifest, copies `miniapp.json` + `icon.png` into `dist/`, zips to `build/<packageName>-<version>.zip`. Prints size + duration.
|
|
84
|
+
5. **Serve.** Picks a free port between 6789 and 6798. Hosts the bundle, manifest, and icon over HTTP on `0.0.0.0`:
|
|
85
|
+
- `GET /miniapp.json`
|
|
86
|
+
- `GET /icon.png`
|
|
87
|
+
- `GET /bundle.zip`
|
|
88
|
+
- `GET /__host_release/health`
|
|
89
|
+
6. Prints a `miniapp://release?url=<lan-base>&package=…&version=…&name=…` URL + QR.
|
|
90
|
+
7. Stays up so multiple devices can install. Each `/bundle.zip` fetch logs `✓ Install #N: <name>@<version> → <remote>`.
|
|
91
|
+
|
|
92
|
+
`Ctrl+C` to stop the server.
|
|
93
|
+
|
|
94
|
+
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: it runs offline, persists across restarts, and needs no laptop after install.
|
|
95
|
+
|
|
96
|
+
> **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.
|
|
97
|
+
|
|
98
|
+
## `pack`
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
glassly pack
|
|
102
|
+
glassly pack --no-build # zip dist/ as-is, skip the build
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Produces a distributable ZIP. Use this when you want the artifact only; `release` calls `pack` internally.
|
|
106
|
+
|
|
107
|
+
Steps:
|
|
108
|
+
|
|
109
|
+
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/`.
|
|
110
|
+
2. Verifies `dist/` exists.
|
|
111
|
+
3. Validates `miniapp.json`.
|
|
112
|
+
4. Copies `miniapp.json` and `icon.png` into `dist/`.
|
|
113
|
+
5. Runs the system `zip -r` command to produce `build/<packageName>-<version>.zip` and prints the absolute path.
|
|
114
|
+
|
|
115
|
+
`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`.
|
|
116
|
+
|
|
117
|
+
The resulting ZIP is the artifact you'd upload to the miniapp store.
|
|
118
|
+
|
|
119
|
+
> 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.
|
|
120
|
+
|
|
121
|
+
## `manifest`
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
glassly manifest
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Interactive top-level wizard for `miniapp.json` (Clack-based). Loop:
|
|
128
|
+
|
|
129
|
+
- Edit permissions: add, remove
|
|
130
|
+
- Edit hardware requirements: add, remove
|
|
131
|
+
- Show current manifest: pretty-prints the JSON
|
|
132
|
+
- Done: exits
|
|
133
|
+
|
|
134
|
+
Persists after every confirmed change, so `Ctrl+C` never loses a saved edit.
|
|
135
|
+
|
|
136
|
+
The wizard shares its mutation backend (`manifest-mutate.ts`) with the object-verb commands below; behavior and validation are identical.
|
|
137
|
+
|
|
138
|
+
## `permission`
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
glassly permission list
|
|
142
|
+
glassly permission add [TYPE]
|
|
143
|
+
glassly permission remove [TYPE]
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`add` / `remove` are interactive when called without `TYPE` (Clack select prompts) and non-interactive when `TYPE` is provided.
|
|
147
|
+
|
|
148
|
+
Allowed `TYPE` values: `MICROPHONE`, `CAMERA`, `CALENDAR`, `LOCATION`, `BACKGROUND_LOCATION`, `READ_NOTIFICATIONS`, `POST_NOTIFICATIONS`, `API_KEYS`, `MEMORY`, `AI`, `SPEAKERS`, `DISPLAY_MIRROR`, `MANAGE_MINIAPPS`, `PLATFORM_SETTINGS`.
|
|
149
|
+
|
|
150
|
+
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). The Glassly App asks for every declared permission when the miniapp launches: required ones first (declining keeps it closed), then optional ones (`"required": false`) in one skippable alert.
|
|
151
|
+
|
|
152
|
+
## `hardware`
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
glassly hardware list
|
|
156
|
+
glassly hardware add [TYPE] [LEVEL]
|
|
157
|
+
glassly hardware remove [TYPE]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Allowed `TYPE` values: `CAMERA`, `DISPLAY`, `MICROPHONE`, `SPEAKER`, `IMU`, `BUTTON`, `LIGHT`, `WIFI`.
|
|
161
|
+
Allowed `LEVEL` values: `REQUIRED`, `OPTIONAL`.
|
|
162
|
+
|
|
163
|
+
- `REQUIRED`: glasses without this hardware can't run the app (hidden in the store / launcher on incompatible devices).
|
|
164
|
+
- `OPTIONAL`: glasses without this hardware still run the app, in a degraded state.
|
|
165
|
+
|
|
166
|
+
Add is interactive when called without `TYPE` / `LEVEL`. Non-interactive form requires both.
|
|
167
|
+
|
|
168
|
+
> 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, so don't declare it.
|
|
169
|
+
|
|
170
|
+
## `schema`
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
glassly schema print
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Prints the canonical `miniapp.json` JSON Schema to stdout. Useful for piping into IDE config or for validation in CI.
|
|
177
|
+
|
|
178
|
+
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.
|
|
179
|
+
|
|
180
|
+
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 (`@glassly/create-miniapp`) injects this `$schema` line into new projects automatically.
|
|
181
|
+
|
|
182
|
+
> `glassly schema regenerate` exists too but is package-internal: it rewrites the published schema file from the in-source allowed-values lists (`bun run build` here does the same). Authors don't need it.
|
|
183
|
+
|
|
184
|
+
## `miniapp.json` shape
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json",
|
|
189
|
+
"packageName": "com.glassly.example",
|
|
190
|
+
"version": "1.0.0",
|
|
191
|
+
"name": "Glassly Example",
|
|
192
|
+
"description": "…",
|
|
193
|
+
"icon": "icon.png",
|
|
194
|
+
"port": 3000,
|
|
195
|
+
"type": "standard",
|
|
196
|
+
"sdkVersion": "0.3.0",
|
|
197
|
+
"minHostVersion": "0.3.0",
|
|
198
|
+
"entry": {
|
|
199
|
+
"background": "background/index.js",
|
|
200
|
+
"ui": "ui/index.html"
|
|
201
|
+
},
|
|
202
|
+
"permissions": [{"type": "MICROPHONE", "description": "Listen for what to caption."}],
|
|
203
|
+
"hardwareRequirements": [
|
|
204
|
+
{"type": "DISPLAY", "level": "REQUIRED"},
|
|
205
|
+
{"type": "MICROPHONE", "level": "REQUIRED"}
|
|
206
|
+
],
|
|
207
|
+
"actions": [
|
|
208
|
+
{
|
|
209
|
+
"id": "start_caption",
|
|
210
|
+
"description": "Start live captions on the glasses. Use when the user asks to caption a conversation.",
|
|
211
|
+
"visibility": "public",
|
|
212
|
+
"parameters": {"type": "object", "properties": {"language": {"type": "string"}}}
|
|
213
|
+
}
|
|
214
|
+
]
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Required: `packageName`, `version`, `name`, `hardwareRequirements`. Everything else is optional.
|
|
219
|
+
|
|
220
|
+
| Field | What it does |
|
|
221
|
+
| --- | --- |
|
|
222
|
+
| `entry` | Two-layer bundle entry points. `background` (required if present) is the always-running JSContext entry, e.g. `background/index.js`; `ui` is the on-demand WebView entry HTML. Pure-background miniapps omit `ui`. |
|
|
223
|
+
| `type` | `"standard"` (default, ships a UI WebView), `"background"` (JSContext only), or `"dashboard"` (can hold the dashboard role: one dashboard runs at a time and gets the display overlay slot; grants no privileges by itself). |
|
|
224
|
+
| `alwaysOn` | Boolean, default `false`. Start at host launch and keep the background running when its switcher card is dismissed. The wearer can override this default and explicitly stop the miniapp. |
|
|
225
|
+
| `sdkVersion` | Semver of the `@glassly/miniapp` SDK this bundle targets. |
|
|
226
|
+
| `minHostVersion` | Lowest Glassly App version that can run this bundle; the app reports its release family version (0.3.0 today). The Glassly Miniapp Store won't install or update a release whose `minHostVersion` is above the running Glassly App, and says so on its card and page. |
|
|
227
|
+
| `actions` | Actions other miniapps can discover and invoke via `session.actions`, mapping 1:1 onto MCP tools. Each needs `id` (lowercase, `^[a-z][a-z0-9_]*$`, ≤64 chars) and an AI-facing `description`; `visibility` is `"public"` (default) or `"system"` (system miniapps such as the AI assistant only), and `parameters` is a JSON Schema for the input. |
|
|
228
|
+
|
|
229
|
+
> `sdkVersion` and `minHostVersion` are validated against the schema. Only the
|
|
230
|
+
> Store enforces `minHostVersion`; the runtime does not check either at launch
|
|
231
|
+
> (the host's `checkManifestVersions` gate exists and is never called).
|
|
232
|
+
|
|
233
|
+
`packageName` must be reverse-DNS (`^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$`).
|
|
234
|
+
|
|
235
|
+
`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.
|
|
236
|
+
|
|
237
|
+
The CLI's allowed-value lists are mirrored by hand from `@glassly/engine` and `@glassly/miniapp` to keep the tooling dependency-light so `glassly` starts fast. Drift is caught at validation time, not import time.
|
|
238
|
+
|
|
239
|
+
## File map
|
|
240
|
+
|
|
241
|
+
- Command implementations (exported from `src/api.ts`, wired to subcommands by `@glassly/cli`): `src/{dev,release,pack,permission,hardware,schema,manifest-wizard}.ts`
|
|
242
|
+
- Manifest validation + allowed-value lists: `src/manifest.ts`
|
|
243
|
+
- Manifest mutation backend (shared by wizard + object-verb commands): `src/manifest-mutate.ts`
|
|
244
|
+
- Manifest read/write helpers: `src/manifest-format.ts`
|
|
245
|
+
- Permission/hardware human-readable hints: `src/permission-hints.ts`
|
|
246
|
+
- Dev sidecar WebSocket server: `src/dev-server.ts`
|
|
247
|
+
- QR rendering: `src/qr.ts`
|
|
248
|
+
- Generated JSON Schema: `schema/miniapp.schema.json` (regenerated via `schema regenerate`)
|
package/package.json
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@glassly/miniapp-cli",
|
|
3
|
+
"version": "0.1.0-beta.3",
|
|
4
|
+
"description": "Build tooling for Glassly miniapps: dev server, packer, manifest validation, and JSON Schema. The `glassly` command that drives it ships in @glassly/cli.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"publishConfig": {
|
|
7
|
+
"access": "public",
|
|
8
|
+
"tag": "dev"
|
|
9
|
+
},
|
|
10
|
+
"exports": {
|
|
11
|
+
".": "./src/api.ts",
|
|
12
|
+
"./build-helpers": "./src/build-helpers.ts",
|
|
13
|
+
"./lan": "./src/lan.ts",
|
|
14
|
+
"./package.json": "./package.json"
|
|
15
|
+
},
|
|
16
|
+
"scripts": {
|
|
17
|
+
"build": "bun src/regenerate-schema.ts",
|
|
18
|
+
"prepare": "bun src/regenerate-schema.ts"
|
|
19
|
+
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@clack/prompts": "^1.2.0",
|
|
22
|
+
"jszip": "^3.10.1",
|
|
23
|
+
"qrcode": "^1.5.4",
|
|
24
|
+
"typescript": "^5.0.0"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@types/qrcode": "^1.5.5",
|
|
28
|
+
"bun-types": "1.3.14"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"src",
|
|
32
|
+
"schema"
|
|
33
|
+
],
|
|
34
|
+
"keywords": [
|
|
35
|
+
"glassly",
|
|
36
|
+
"glassly",
|
|
37
|
+
"miniapp",
|
|
38
|
+
"cli"
|
|
39
|
+
],
|
|
40
|
+
"repository": {
|
|
41
|
+
"type": "git",
|
|
42
|
+
"url": "git+https://github.com/tetramo-labs/glassly.git",
|
|
43
|
+
"directory": "sdk/miniapp-cli"
|
|
44
|
+
},
|
|
45
|
+
"homepage": "https://github.com/tetramo-labs/glassly/tree/dev/sdk/miniapp-cli#readme",
|
|
46
|
+
"bugs": {
|
|
47
|
+
"url": "https://github.com/tetramo-labs/glassly/issues"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,269 @@
|
|
|
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
|
+
"tagline": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"maxLength": 80,
|
|
38
|
+
"description": "One line shown under the name in the Glassly Miniapp Store"
|
|
39
|
+
},
|
|
40
|
+
"tags": {
|
|
41
|
+
"type": "array",
|
|
42
|
+
"maxItems": 5,
|
|
43
|
+
"uniqueItems": true,
|
|
44
|
+
"description": "Store tags used as filter chips. Known tags: productivity, communication, navigation, ai, games, developer, media. Other lowercase slugs are accepted.",
|
|
45
|
+
"items": {
|
|
46
|
+
"type": "string",
|
|
47
|
+
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
|
|
48
|
+
"maxLength": 32
|
|
49
|
+
}
|
|
50
|
+
},
|
|
51
|
+
"icon": {
|
|
52
|
+
"type": "string",
|
|
53
|
+
"description": "Path or URL to the app icon (e.g. icon.png)"
|
|
54
|
+
},
|
|
55
|
+
"port": {
|
|
56
|
+
"type": "integer",
|
|
57
|
+
"minimum": 1,
|
|
58
|
+
"maximum": 65535,
|
|
59
|
+
"description": "Port the dev server listens on (default 3000)"
|
|
60
|
+
},
|
|
61
|
+
"sdkVersion": {
|
|
62
|
+
"type": "string",
|
|
63
|
+
"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."
|
|
64
|
+
},
|
|
65
|
+
"minHostVersion": {
|
|
66
|
+
"type": "string",
|
|
67
|
+
"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."
|
|
68
|
+
},
|
|
69
|
+
"entry": {
|
|
70
|
+
"type": "object",
|
|
71
|
+
"description": "Two-layer bundle entry points. Background is the always-running JSContext entry; UI is the on-demand WebView entry.",
|
|
72
|
+
"additionalProperties": false,
|
|
73
|
+
"required": [
|
|
74
|
+
"background"
|
|
75
|
+
],
|
|
76
|
+
"properties": {
|
|
77
|
+
"background": {
|
|
78
|
+
"type": "string",
|
|
79
|
+
"description": "Path to the background bundle, relative to the bundle root (e.g. background/index.js). Required for V2+ two-layer bundles."
|
|
80
|
+
},
|
|
81
|
+
"ui": {
|
|
82
|
+
"type": "string",
|
|
83
|
+
"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."
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
"type": {
|
|
88
|
+
"type": "string",
|
|
89
|
+
"enum": [
|
|
90
|
+
"standard",
|
|
91
|
+
"background",
|
|
92
|
+
"dashboard"
|
|
93
|
+
],
|
|
94
|
+
"description": "Miniapp type. 'standard' includes a UI WebView; 'background' is JSContext-only; 'dashboard' is a standard app that can hold the dashboard role (one dashboard runs at a time, and the host hands the running one the overlay slot). Defaults to 'standard'."
|
|
95
|
+
},
|
|
96
|
+
"alwaysOn": {
|
|
97
|
+
"type": "boolean",
|
|
98
|
+
"description": "Always On miniapp: the host starts it at launch and its background task keeps running after its app switcher card is swiped away. The wearer can still stop it or turn Always On off from the home grid."
|
|
99
|
+
},
|
|
100
|
+
"permissions": {
|
|
101
|
+
"type": "array",
|
|
102
|
+
"description": "Phone permissions the miniapp needs to declare",
|
|
103
|
+
"items": {
|
|
104
|
+
"type": "object",
|
|
105
|
+
"required": [
|
|
106
|
+
"type"
|
|
107
|
+
],
|
|
108
|
+
"additionalProperties": false,
|
|
109
|
+
"properties": {
|
|
110
|
+
"type": {
|
|
111
|
+
"type": "string",
|
|
112
|
+
"enum": [
|
|
113
|
+
"MICROPHONE",
|
|
114
|
+
"CAMERA",
|
|
115
|
+
"CALENDAR",
|
|
116
|
+
"LOCATION",
|
|
117
|
+
"BACKGROUND_LOCATION",
|
|
118
|
+
"READ_NOTIFICATIONS",
|
|
119
|
+
"DISPLAY_MIRROR",
|
|
120
|
+
"POST_NOTIFICATIONS",
|
|
121
|
+
"API_KEYS",
|
|
122
|
+
"MEMORY",
|
|
123
|
+
"AI",
|
|
124
|
+
"SPEAKERS",
|
|
125
|
+
"MANAGE_MINIAPPS",
|
|
126
|
+
"PLATFORM_SETTINGS"
|
|
127
|
+
],
|
|
128
|
+
"description": "Permission type"
|
|
129
|
+
},
|
|
130
|
+
"required": {
|
|
131
|
+
"type": "boolean",
|
|
132
|
+
"description": "If false, the permission is optional: asked at launch after the required ones, and the miniapp opens without it. Defaults to true."
|
|
133
|
+
},
|
|
134
|
+
"description": {
|
|
135
|
+
"type": "string",
|
|
136
|
+
"description": "User-facing reason this permission is needed (shown in OS prompts)"
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
},
|
|
141
|
+
"hardwareRequirements": {
|
|
142
|
+
"type": "array",
|
|
143
|
+
"description": "Glasses hardware capabilities the miniapp needs",
|
|
144
|
+
"items": {
|
|
145
|
+
"type": "object",
|
|
146
|
+
"required": [
|
|
147
|
+
"type",
|
|
148
|
+
"level"
|
|
149
|
+
],
|
|
150
|
+
"additionalProperties": false,
|
|
151
|
+
"properties": {
|
|
152
|
+
"type": {
|
|
153
|
+
"type": "string",
|
|
154
|
+
"enum": [
|
|
155
|
+
"CAMERA",
|
|
156
|
+
"DISPLAY",
|
|
157
|
+
"MICROPHONE",
|
|
158
|
+
"SPEAKER",
|
|
159
|
+
"IMU",
|
|
160
|
+
"BUTTON",
|
|
161
|
+
"LIGHT",
|
|
162
|
+
"WIFI"
|
|
163
|
+
],
|
|
164
|
+
"description": "Hardware capability type"
|
|
165
|
+
},
|
|
166
|
+
"level": {
|
|
167
|
+
"type": "string",
|
|
168
|
+
"enum": [
|
|
169
|
+
"REQUIRED",
|
|
170
|
+
"OPTIONAL"
|
|
171
|
+
],
|
|
172
|
+
"description": "REQUIRED hides the app on glasses without it; OPTIONAL still lets it run"
|
|
173
|
+
},
|
|
174
|
+
"description": {
|
|
175
|
+
"type": "string",
|
|
176
|
+
"description": "How the miniapp uses this hardware"
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
"actions": {
|
|
182
|
+
"type": "array",
|
|
183
|
+
"description": "Actions other miniapps can discover and invoke via session.actions. Maps 1:1 onto MCP tools.",
|
|
184
|
+
"items": {
|
|
185
|
+
"type": "object",
|
|
186
|
+
"required": [
|
|
187
|
+
"id",
|
|
188
|
+
"description"
|
|
189
|
+
],
|
|
190
|
+
"additionalProperties": false,
|
|
191
|
+
"properties": {
|
|
192
|
+
"id": {
|
|
193
|
+
"type": "string",
|
|
194
|
+
"pattern": "^[a-z][a-z0-9_]*$",
|
|
195
|
+
"maxLength": 64,
|
|
196
|
+
"description": "Unique-within-app action id (lowercase, starts with a letter)."
|
|
197
|
+
},
|
|
198
|
+
"description": {
|
|
199
|
+
"type": "string",
|
|
200
|
+
"description": "AI-facing contract -- say when to use the action."
|
|
201
|
+
},
|
|
202
|
+
"visibility": {
|
|
203
|
+
"type": "string",
|
|
204
|
+
"enum": [
|
|
205
|
+
"public",
|
|
206
|
+
"system"
|
|
207
|
+
],
|
|
208
|
+
"description": "Who may invoke this action: \"public\" (default -- any installed miniapp) or \"system\" (system miniapps such as the AI assistant only)."
|
|
209
|
+
},
|
|
210
|
+
"parameters": {
|
|
211
|
+
"type": "object",
|
|
212
|
+
"description": "JSON-Schema input descriptor (the MCP inputSchema subset).",
|
|
213
|
+
"properties": {
|
|
214
|
+
"type": {
|
|
215
|
+
"const": "object"
|
|
216
|
+
},
|
|
217
|
+
"properties": {
|
|
218
|
+
"type": "object",
|
|
219
|
+
"additionalProperties": {
|
|
220
|
+
"type": "object",
|
|
221
|
+
"properties": {
|
|
222
|
+
"type": {
|
|
223
|
+
"type": "string",
|
|
224
|
+
"enum": [
|
|
225
|
+
"string",
|
|
226
|
+
"number",
|
|
227
|
+
"boolean",
|
|
228
|
+
"array"
|
|
229
|
+
]
|
|
230
|
+
},
|
|
231
|
+
"description": {
|
|
232
|
+
"type": "string"
|
|
233
|
+
},
|
|
234
|
+
"enum": {
|
|
235
|
+
"type": "array"
|
|
236
|
+
},
|
|
237
|
+
"items": {
|
|
238
|
+
"type": "object",
|
|
239
|
+
"properties": {
|
|
240
|
+
"type": {
|
|
241
|
+
"type": "string",
|
|
242
|
+
"enum": [
|
|
243
|
+
"string",
|
|
244
|
+
"number",
|
|
245
|
+
"boolean"
|
|
246
|
+
]
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
},
|
|
253
|
+
"required": {
|
|
254
|
+
"type": "array",
|
|
255
|
+
"items": {
|
|
256
|
+
"type": "string"
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
},
|
|
261
|
+
"outputSchema": {
|
|
262
|
+
"type": "object",
|
|
263
|
+
"description": "JSON-Schema descriptor for the structured action result (MCP outputSchema)."
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
package/src/api.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export { buildProduction } from './build.js';
|
|
2
|
+
export { dev, type DevAttestationInput, type DevOptions } from './dev.js';
|
|
3
|
+
export { pack, type PackOptions } from './pack.js';
|
|
4
|
+
export { release, type ReleaseOptions } from './release.js';
|
|
5
|
+
export { runManifestWizard } from './manifest-wizard.js';
|
|
6
|
+
export { addPermissionCmd, listPermissionsCmd, removePermissionCmd } from './permission.js';
|
|
7
|
+
export { addHardwareCmd, listHardwareCmd, removeHardwareCmd } from './hardware.js';
|
|
8
|
+
export { regenerateSchemaFile, schemaPrint } from './schema.js';
|
|
9
|
+
export { type QRSize } from './qr.js';
|
|
10
|
+
export { getLanIp, getMdnsHostname, pickLanIp, scoreLanIface } from './lan.js';
|
|
@@ -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
|
+
})
|