@glassly/miniapp-cli 0.1.0-dev.1 → 0.1.0-dev.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 +86 -59
- package/package.json +4 -7
- package/schema/miniapp.schema.json +28 -4
- package/src/api.ts +6 -0
- package/src/build.ts +1 -1
- package/src/dev-server.ts +12 -12
- package/src/dev.ts +4 -4
- package/src/hardware.ts +2 -2
- package/src/manifest-mutate.ts +3 -3
- package/src/manifest-wizard.ts +1 -1
- package/src/manifest.test.ts +54 -0
- package/src/manifest.ts +78 -6
- package/src/pack.ts +0 -6
- package/src/permission-hints.ts +4 -0
- package/src/permission.ts +1 -1
- package/src/regenerate-schema.ts +6 -0
- package/src/release.ts +6 -4
- package/src/schema.test.ts +10 -0
- package/src/schema.ts +32 -5
- package/src/index.ts +0 -127
package/README.md
CHANGED
|
@@ -1,11 +1,22 @@
|
|
|
1
|
-
# @glassly/miniapp-cli
|
|
1
|
+
# @glassly/miniapp-cli
|
|
2
2
|
|
|
3
|
-
|
|
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:
|
|
4
10
|
|
|
5
11
|
```
|
|
6
|
-
glassly
|
|
12
|
+
glassly <command>
|
|
7
13
|
```
|
|
8
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
|
+
|
|
9
20
|
## Commands at a glance
|
|
10
21
|
|
|
11
22
|
| Command | What it does |
|
|
@@ -18,14 +29,14 @@ glassly-miniapp <command>
|
|
|
18
29
|
| [`hardware list \| add \| remove`](#hardware) | Object-verb manifest edits for hardware requirements |
|
|
19
30
|
| [`schema print`](#schema) | Prints the canonical `miniapp.json` JSON Schema to stdout |
|
|
20
31
|
|
|
21
|
-
Run
|
|
22
|
-
|
|
23
|
-
---
|
|
32
|
+
Run `glassly --help` to print the same list.
|
|
24
33
|
|
|
25
34
|
## `dev`
|
|
26
35
|
|
|
27
36
|
```bash
|
|
28
|
-
glassly
|
|
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
|
|
29
40
|
```
|
|
30
41
|
|
|
31
42
|
What it does:
|
|
@@ -34,13 +45,15 @@ What it does:
|
|
|
34
45
|
2. Runs the project's `build.ts` so `dist/background/index.js` and `dist/ui/*` are current.
|
|
35
46
|
3. Picks the first free adjacent port pair starting at `port`: one for static files and the next for the dev sidecar.
|
|
36
47
|
4. Starts a static server that serves `miniapp.json`, `icon.png`, and project files.
|
|
37
|
-
5. Starts a **dev sidecar** on `port + 1
|
|
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.
|
|
38
49
|
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
|
|
50
|
+
7. Watches for LAN-IP changes (Wi-Fi switch) every 2s and reprints the QR.
|
|
40
51
|
|
|
41
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.
|
|
42
53
|
|
|
43
|
-
|
|
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.
|
|
44
57
|
|
|
45
58
|
`dev` is live and temporary. Keep the CLI and computer running because the
|
|
46
59
|
Glassly App loads the runtime bundle from that LAN server. Dev miniapps are keyed
|
|
@@ -51,13 +64,13 @@ that works without the computer.
|
|
|
51
64
|
|
|
52
65
|
`Ctrl+C` stops the server, the sidecar, and the IP watcher.
|
|
53
66
|
|
|
54
|
-
---
|
|
55
|
-
|
|
56
67
|
## `release`
|
|
57
68
|
|
|
58
69
|
```bash
|
|
59
|
-
glassly
|
|
60
|
-
glassly
|
|
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
|
|
61
74
|
```
|
|
62
75
|
|
|
63
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.
|
|
@@ -67,118 +80,106 @@ Flow:
|
|
|
67
80
|
1. Validates `miniapp.json`.
|
|
68
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.
|
|
69
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/`.
|
|
70
|
-
4. **Pack.** Calls the same logic as `glassly
|
|
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.
|
|
71
84
|
5. **Serve.** Picks a free port between 6789 and 6798. Hosts the bundle, manifest, and icon over HTTP on `0.0.0.0`:
|
|
72
85
|
- `GET /miniapp.json`
|
|
73
86
|
- `GET /icon.png`
|
|
74
87
|
- `GET /bundle.zip`
|
|
75
|
-
- `GET /
|
|
88
|
+
- `GET /__host_release/health`
|
|
76
89
|
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
|
|
90
|
+
7. Stays up so multiple devices can install. Each `/bundle.zip` fetch logs `✓ Install #N: <name>@<version> → <remote>`.
|
|
78
91
|
|
|
79
92
|
`Ctrl+C` to stop the server.
|
|
80
93
|
|
|
81
|
-
|
|
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.
|
|
82
95
|
|
|
83
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.
|
|
84
97
|
|
|
85
|
-
---
|
|
86
|
-
|
|
87
98
|
## `pack`
|
|
88
99
|
|
|
89
100
|
```bash
|
|
90
|
-
glassly
|
|
91
|
-
glassly
|
|
101
|
+
glassly pack
|
|
102
|
+
glassly pack --no-build # zip dist/ as-is, skip the build
|
|
92
103
|
```
|
|
93
104
|
|
|
94
|
-
Produces a distributable ZIP. Use this when you want the artifact only
|
|
105
|
+
Produces a distributable ZIP. Use this when you want the artifact only; `release` calls `pack` internally.
|
|
95
106
|
|
|
96
107
|
Steps:
|
|
97
108
|
|
|
98
|
-
1. Runs `<pm> run build` with `NODE_ENV=production` (same as `release`), so the zip always contains a production bundle
|
|
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/`.
|
|
99
110
|
2. Verifies `dist/` exists.
|
|
100
111
|
3. Validates `miniapp.json`.
|
|
101
112
|
4. Copies `miniapp.json` and `icon.png` into `dist/`.
|
|
102
113
|
5. Runs the system `zip -r` command to produce `build/<packageName>-<version>.zip` and prints the absolute path.
|
|
103
114
|
|
|
104
|
-
`build/` is self-ignoring
|
|
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`.
|
|
105
116
|
|
|
106
117
|
The resulting ZIP is the artifact you'd upload to the miniapp store.
|
|
107
118
|
|
|
108
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.
|
|
109
120
|
|
|
110
|
-
---
|
|
111
|
-
|
|
112
121
|
## `manifest`
|
|
113
122
|
|
|
114
123
|
```bash
|
|
115
|
-
glassly
|
|
124
|
+
glassly manifest
|
|
116
125
|
```
|
|
117
126
|
|
|
118
127
|
Interactive top-level wizard for `miniapp.json` (Clack-based). Loop:
|
|
119
128
|
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
129
|
+
- Edit permissions: add, remove
|
|
130
|
+
- Edit hardware requirements: add, remove
|
|
131
|
+
- Show current manifest: pretty-prints the JSON
|
|
132
|
+
- Done: exits
|
|
124
133
|
|
|
125
134
|
Persists after every confirmed change, so `Ctrl+C` never loses a saved edit.
|
|
126
135
|
|
|
127
|
-
The wizard shares its mutation backend (`manifest-mutate.ts`) with the object-verb commands below
|
|
128
|
-
|
|
129
|
-
---
|
|
136
|
+
The wizard shares its mutation backend (`manifest-mutate.ts`) with the object-verb commands below; behavior and validation are identical.
|
|
130
137
|
|
|
131
138
|
## `permission`
|
|
132
139
|
|
|
133
140
|
```bash
|
|
134
|
-
glassly
|
|
135
|
-
glassly
|
|
136
|
-
glassly
|
|
141
|
+
glassly permission list
|
|
142
|
+
glassly permission add [TYPE]
|
|
143
|
+
glassly permission remove [TYPE]
|
|
137
144
|
```
|
|
138
145
|
|
|
139
146
|
`add` / `remove` are interactive when called without `TYPE` (Clack select prompts) and non-interactive when `TYPE` is provided.
|
|
140
147
|
|
|
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).
|
|
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`.
|
|
144
149
|
|
|
145
|
-
|
|
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.
|
|
146
151
|
|
|
147
152
|
## `hardware`
|
|
148
153
|
|
|
149
154
|
```bash
|
|
150
|
-
glassly
|
|
151
|
-
glassly
|
|
152
|
-
glassly
|
|
155
|
+
glassly hardware list
|
|
156
|
+
glassly hardware add [TYPE] [LEVEL]
|
|
157
|
+
glassly hardware remove [TYPE]
|
|
153
158
|
```
|
|
154
159
|
|
|
155
160
|
Allowed `TYPE` values: `CAMERA`, `DISPLAY`, `MICROPHONE`, `SPEAKER`, `IMU`, `BUTTON`, `LIGHT`, `WIFI`.
|
|
156
161
|
Allowed `LEVEL` values: `REQUIRED`, `OPTIONAL`.
|
|
157
162
|
|
|
158
|
-
- `REQUIRED
|
|
159
|
-
- `OPTIONAL
|
|
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.
|
|
160
165
|
|
|
161
166
|
Add is interactive when called without `TYPE` / `LEVEL`. Non-interactive form requires both.
|
|
162
167
|
|
|
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
|
|
164
|
-
|
|
165
|
-
---
|
|
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.
|
|
166
169
|
|
|
167
170
|
## `schema`
|
|
168
171
|
|
|
169
172
|
```bash
|
|
170
|
-
glassly
|
|
173
|
+
glassly schema print
|
|
171
174
|
```
|
|
172
175
|
|
|
173
176
|
Prints the canonical `miniapp.json` JSON Schema to stdout. Useful for piping into IDE config or for validation in CI.
|
|
174
177
|
|
|
175
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.
|
|
176
179
|
|
|
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 (
|
|
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
|
+
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.
|
|
180
181
|
|
|
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.
|
|
182
183
|
|
|
183
184
|
## `miniapp.json` shape
|
|
184
185
|
|
|
@@ -191,27 +192,53 @@ The published schema file ships at `node_modules/@glassly/miniapp-cli/schema/min
|
|
|
191
192
|
"description": "…",
|
|
192
193
|
"icon": "icon.png",
|
|
193
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
|
+
},
|
|
194
202
|
"permissions": [{"type": "MICROPHONE", "description": "Listen for what to caption."}],
|
|
195
203
|
"hardwareRequirements": [
|
|
196
204
|
{"type": "DISPLAY", "level": "REQUIRED"},
|
|
197
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
|
+
}
|
|
198
214
|
]
|
|
199
215
|
}
|
|
200
216
|
```
|
|
201
217
|
|
|
202
218
|
Required: `packageName`, `version`, `name`, `hardwareRequirements`. Everything else is optional.
|
|
203
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
|
+
|
|
204
233
|
`packageName` must be reverse-DNS (`^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$`).
|
|
205
234
|
|
|
206
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.
|
|
207
236
|
|
|
208
|
-
The CLI's allowed-value lists are mirrored by hand from `@glassly/
|
|
209
|
-
|
|
210
|
-
---
|
|
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.
|
|
211
238
|
|
|
212
239
|
## File map
|
|
213
240
|
|
|
214
|
-
-
|
|
241
|
+
- Command implementations (exported from `src/api.ts`, wired to subcommands by `@glassly/cli`): `src/{dev,release,pack,permission,hardware,schema,manifest-wizard}.ts`
|
|
215
242
|
- Manifest validation + allowed-value lists: `src/manifest.ts`
|
|
216
243
|
- Manifest mutation backend (shared by wizard + object-verb commands): `src/manifest-mutate.ts`
|
|
217
244
|
- Manifest read/write helpers: `src/manifest-format.ts`
|
package/package.json
CHANGED
|
@@ -1,11 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@glassly/miniapp-cli",
|
|
3
|
-
"version": "0.1.0-dev.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.0-dev.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
5
|
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"glassly-miniapp": "./src/index.ts"
|
|
8
|
-
},
|
|
9
6
|
"publishConfig": {
|
|
10
7
|
"access": "public",
|
|
11
8
|
"tag": "dev"
|
|
@@ -17,8 +14,8 @@
|
|
|
17
14
|
"./package.json": "./package.json"
|
|
18
15
|
},
|
|
19
16
|
"scripts": {
|
|
20
|
-
"build": "bun src/
|
|
21
|
-
"prepare": "bun src/
|
|
17
|
+
"build": "bun src/regenerate-schema.ts",
|
|
18
|
+
"prepare": "bun src/regenerate-schema.ts"
|
|
22
19
|
},
|
|
23
20
|
"dependencies": {
|
|
24
21
|
"@clack/prompts": "^1.2.0",
|
|
@@ -32,6 +32,22 @@
|
|
|
32
32
|
"type": "string",
|
|
33
33
|
"description": "Short description shown in the store / dev tools"
|
|
34
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
|
+
},
|
|
35
51
|
"icon": {
|
|
36
52
|
"type": "string",
|
|
37
53
|
"description": "Path or URL to the app icon (e.g. icon.png)"
|
|
@@ -72,9 +88,14 @@
|
|
|
72
88
|
"type": "string",
|
|
73
89
|
"enum": [
|
|
74
90
|
"standard",
|
|
75
|
-
"background"
|
|
91
|
+
"background",
|
|
92
|
+
"dashboard"
|
|
76
93
|
],
|
|
77
|
-
"description": "Miniapp type. 'standard' includes a UI WebView; 'background' is JSContext-only. Defaults to 'standard'."
|
|
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."
|
|
78
99
|
},
|
|
79
100
|
"permissions": {
|
|
80
101
|
"type": "array",
|
|
@@ -95,17 +116,20 @@
|
|
|
95
116
|
"LOCATION",
|
|
96
117
|
"BACKGROUND_LOCATION",
|
|
97
118
|
"READ_NOTIFICATIONS",
|
|
119
|
+
"DISPLAY_MIRROR",
|
|
98
120
|
"POST_NOTIFICATIONS",
|
|
99
121
|
"API_KEYS",
|
|
100
122
|
"MEMORY",
|
|
101
123
|
"AI",
|
|
102
|
-
"SPEAKERS"
|
|
124
|
+
"SPEAKERS",
|
|
125
|
+
"MANAGE_MINIAPPS",
|
|
126
|
+
"PLATFORM_SETTINGS"
|
|
103
127
|
],
|
|
104
128
|
"description": "Permission type"
|
|
105
129
|
},
|
|
106
130
|
"required": {
|
|
107
131
|
"type": "boolean",
|
|
108
|
-
"description": "If false, the permission is optional
|
|
132
|
+
"description": "If false, the permission is optional: asked at launch after the required ones, and the miniapp opens without it. Defaults to true."
|
|
109
133
|
},
|
|
110
134
|
"description": {
|
|
111
135
|
"type": "string",
|
package/src/api.ts
CHANGED
|
@@ -1,4 +1,10 @@
|
|
|
1
1
|
export { buildProduction } from './build.js';
|
|
2
2
|
export { dev, type DevAttestationInput, type DevOptions } from './dev.js';
|
|
3
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';
|
|
4
10
|
export { getLanIp, getMdnsHostname, pickLanIp, scoreLanIface } from './lan.js';
|
package/src/build.ts
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* tree-shakes any `if (NODE_ENV === "development")` branches (dev panels,
|
|
8
8
|
* debug overlays) out of the bundle. Without this, `pack` would silently
|
|
9
9
|
* zip whatever mode the last build happened to be — usually a dev build
|
|
10
|
-
* left behind by `glassly
|
|
10
|
+
* left behind by `glassly dev`.
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
13
|
import {existsSync, readFileSync} from 'fs'
|
package/src/dev-server.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
// Sidecar dev server for `glassly
|
|
1
|
+
// Sidecar dev server for `glassly dev`. Runs on `userPort + 1`,
|
|
2
2
|
// alongside the static file server `dev.ts` boots on `userPort`. Hosts
|
|
3
|
-
// the `
|
|
3
|
+
// the `__host_dev` WebSocket multiplexed channel:
|
|
4
4
|
//
|
|
5
5
|
// laptop → phone : {type: "reload"} (UI WebView reload — filesystem watcher fired in src/ui)
|
|
6
6
|
// laptop → phone : {type: "respawn-bg"} (background JSContext respawn — filesystem watcher fired in src/background)
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
// `{type: "hello-ack"}`) so a phone connecting to the wrong sidecar (or an
|
|
11
11
|
// older one) can detect mismatch.
|
|
12
12
|
//
|
|
13
|
-
// Also exposes `/
|
|
13
|
+
// Also exposes `/__host_dev/bundle.zip` — a flat snapshot of the
|
|
14
14
|
// project (including `dist/`) the phone-side install pipeline downloads
|
|
15
15
|
// and unpacks into `lmas/<pkg>/dev-<ts>/`. `onBeforeBroadcast` is the
|
|
16
16
|
// hook that rebuilds `dist/` before each broadcast so the next zip
|
|
@@ -122,12 +122,12 @@ export function startDevSidecar(options: DevServerOptions): {stop: () => void; p
|
|
|
122
122
|
port: options.port,
|
|
123
123
|
fetch(req, srv) {
|
|
124
124
|
const url = new URL(req.url)
|
|
125
|
-
if (url.pathname === "/
|
|
125
|
+
if (url.pathname === "/__host_dev/health") {
|
|
126
126
|
return new Response(JSON.stringify({ok: true, protocol: PROTOCOL_VERSION}), {
|
|
127
127
|
headers: {"content-type": "application/json"},
|
|
128
128
|
})
|
|
129
129
|
}
|
|
130
|
-
if (url.pathname === "/
|
|
130
|
+
if (url.pathname === "/__host_dev/bundle.zip") {
|
|
131
131
|
// Snapshot of the project files for the phone-side bundle cache.
|
|
132
132
|
// Phone calls Composer.installMiniApp(this URL) to download + unzip
|
|
133
133
|
// into lmas/<pkg>/dev-<timestamp>/ — same path store-installed
|
|
@@ -149,7 +149,7 @@ export function startDevSidecar(options: DevServerOptions): {stop: () => void; p
|
|
|
149
149
|
})
|
|
150
150
|
})
|
|
151
151
|
}
|
|
152
|
-
if (url.pathname === "/
|
|
152
|
+
if (url.pathname === "/__host_dev") {
|
|
153
153
|
const upgraded = srv.upgrade(req, {
|
|
154
154
|
data: {packageName: null, remoteAddress: srv.requestIP(req)?.address ?? "unknown"},
|
|
155
155
|
})
|
|
@@ -182,11 +182,11 @@ export function startDevSidecar(options: DevServerOptions): {stop: () => void; p
|
|
|
182
182
|
case "log": {
|
|
183
183
|
const color = colorForLevel(parsed.level)
|
|
184
184
|
// Source-prefix lets devs tell UI ↔ background apart at a
|
|
185
|
-
// glance. UI cyan,
|
|
185
|
+
// glance. UI cyan, JSRuntime magenta.
|
|
186
186
|
const sourceTag =
|
|
187
187
|
parsed.source === "ui"
|
|
188
188
|
? `${COLOR.cyan}[UI]${COLOR.reset}`
|
|
189
|
-
: `${COLOR.magenta}[
|
|
189
|
+
: `${COLOR.magenta}[JSRuntime]${COLOR.reset}`
|
|
190
190
|
const tag = `${color}${parsed.level}${COLOR.reset}`
|
|
191
191
|
const body = formatLogArgs(parsed.args ?? [])
|
|
192
192
|
log(
|
|
@@ -264,7 +264,7 @@ export function startDevSidecar(options: DevServerOptions): {stop: () => void; p
|
|
|
264
264
|
suppressEventsUntil = Date.now() + 1_500
|
|
265
265
|
} catch (err) {
|
|
266
266
|
suppressEventsUntil = Date.now() + 1_500
|
|
267
|
-
log(`${COLOR.red}[
|
|
267
|
+
log(`${COLOR.red}[__host_dev] onBeforeBroadcast failed:${COLOR.reset} ${(err as Error).message}`)
|
|
268
268
|
}
|
|
269
269
|
}
|
|
270
270
|
const msg = JSON.stringify({type})
|
|
@@ -289,7 +289,7 @@ export function startDevSidecar(options: DevServerOptions): {stop: () => void; p
|
|
|
289
289
|
}, RELOAD_DEBOUNCE_MS)
|
|
290
290
|
})
|
|
291
291
|
|
|
292
|
-
log(`${COLOR.dim}[
|
|
292
|
+
log(`${COLOR.dim}[__host_dev]${COLOR.reset} sidecar listening on :${options.port}`)
|
|
293
293
|
|
|
294
294
|
return {
|
|
295
295
|
port: options.port,
|
|
@@ -418,7 +418,7 @@ export function listProjectFiles(rootDir: string): ProjectFile[] {
|
|
|
418
418
|
out.push({disk, entry: entryName})
|
|
419
419
|
if (out.length >= MAX_FILES) {
|
|
420
420
|
console.warn(
|
|
421
|
-
`[
|
|
421
|
+
`[__host_dev] dist file list truncated at ${MAX_FILES} entries — bundle may be incomplete`,
|
|
422
422
|
)
|
|
423
423
|
return out
|
|
424
424
|
}
|
|
@@ -446,7 +446,7 @@ export async function buildProjectZip(rootDir: string): Promise<Uint8Array> {
|
|
|
446
446
|
const buf = readFileSync(abs)
|
|
447
447
|
zip.file(entry, buf)
|
|
448
448
|
} catch (err) {
|
|
449
|
-
console.warn(`[
|
|
449
|
+
console.warn(`[__host_dev] failed to read ${disk}, skipping:`, err)
|
|
450
450
|
}
|
|
451
451
|
}
|
|
452
452
|
// STORE (no compression) — small project trees, deterministic, fast.
|
package/src/dev.ts
CHANGED
|
@@ -8,7 +8,7 @@ import { getLanIp, getMdnsHostname } from './lan.js';
|
|
|
8
8
|
|
|
9
9
|
const DEFAULT_DEV_PORT = 3000;
|
|
10
10
|
const DEV_PORT_SCAN_LIMIT = 50;
|
|
11
|
-
/** How often to re-check Wi-Fi / LAN IP while `glassly
|
|
11
|
+
/** How often to re-check Wi-Fi / LAN IP while `glassly dev` is running. */
|
|
12
12
|
const LAN_IP_POLL_MS = 2_000;
|
|
13
13
|
|
|
14
14
|
export interface DevAttestationInput {
|
|
@@ -63,7 +63,7 @@ function pickDevPort(start: number): number {
|
|
|
63
63
|
const end = start + DEV_PORT_SCAN_LIMIT - 1;
|
|
64
64
|
console.error(
|
|
65
65
|
`Error: no free adjacent dev port pair found between base ports ${start} and ${end}. ` +
|
|
66
|
-
'`glassly
|
|
66
|
+
'`glassly dev` needs one port for static files and the next port for live reload.',
|
|
67
67
|
);
|
|
68
68
|
process.exit(1);
|
|
69
69
|
}
|
|
@@ -80,7 +80,7 @@ async function runBuild(cwd: string): Promise<void> {
|
|
|
80
80
|
throw new Error(
|
|
81
81
|
'build.ts not found at project root. Two-layer miniapps emit ' +
|
|
82
82
|
'`dist/background/index.js` + `dist/ui/index.html` via a build.ts ' +
|
|
83
|
-
'script — see
|
|
83
|
+
'script — see miniapps/example-miniapp/build.ts for the canonical shape.',
|
|
84
84
|
);
|
|
85
85
|
}
|
|
86
86
|
const proc = Bun.spawn(['bun', 'run', 'build.ts'], {
|
|
@@ -196,7 +196,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
|
|
|
196
196
|
process.exit(1);
|
|
197
197
|
}
|
|
198
198
|
|
|
199
|
-
// Sidecar on userPort + 1 — hosts the `
|
|
199
|
+
// Sidecar on userPort + 1 — hosts the `__host_dev` WebSocket the
|
|
200
200
|
// phone uses for live reload + console-log forwarding. The
|
|
201
201
|
// `onBeforeBroadcast` hook rebuilds `dist/` before the phone is
|
|
202
202
|
// notified, so the next `bundle.zip` fetch ships current code.
|
package/src/hardware.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// `glassly
|
|
1
|
+
// `glassly hardware <action>` subcommand handlers. Mirrors permission.ts.
|
|
2
2
|
|
|
3
3
|
import * as p from "@clack/prompts"
|
|
4
4
|
import {ALLOWED_HARDWARE_LEVELS, ALLOWED_HARDWARE_TYPES} from "./manifest.js"
|
|
@@ -103,7 +103,7 @@ export async function addHardwareCmd(typeArg?: string, levelArg?: string): Promi
|
|
|
103
103
|
}
|
|
104
104
|
|
|
105
105
|
if (!level) {
|
|
106
|
-
console.error(`Missing level. Usage: glassly
|
|
106
|
+
console.error(`Missing level. Usage: glassly hardware add ${type} <REQUIRED|OPTIONAL>`)
|
|
107
107
|
process.exit(1)
|
|
108
108
|
}
|
|
109
109
|
|
package/src/manifest-mutate.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Pure manifest mutation helpers. No I/O. Returns new manifest objects.
|
|
2
2
|
//
|
|
3
3
|
// Used by the object-verb subcommands (`permission add`, `hardware add`, etc.)
|
|
4
|
-
// and the interactive `glassly
|
|
4
|
+
// and the interactive `glassly manifest` wizard. Both surfaces share
|
|
5
5
|
// these primitives so behavior is identical.
|
|
6
6
|
|
|
7
7
|
import {
|
|
@@ -56,7 +56,7 @@ export function addPermission(
|
|
|
56
56
|
if (existing.some((p) => p.type === validated)) {
|
|
57
57
|
throw new MutateError({
|
|
58
58
|
code: "duplicate",
|
|
59
|
-
message: `${validated} is already declared. Use 'glassly
|
|
59
|
+
message: `${validated} is already declared. Use 'glassly permission remove ${validated}' first if you want to update its description / required flag.`,
|
|
60
60
|
})
|
|
61
61
|
}
|
|
62
62
|
const entry: ManifestPermission = {type: validated}
|
|
@@ -97,7 +97,7 @@ export function addHardware(
|
|
|
97
97
|
if (existing.some((h) => h.type === validatedType)) {
|
|
98
98
|
throw new MutateError({
|
|
99
99
|
code: "duplicate",
|
|
100
|
-
message: `${validatedType} hardware requirement already declared. Use 'glassly
|
|
100
|
+
message: `${validatedType} hardware requirement already declared. Use 'glassly hardware remove ${validatedType}' first if you want to update its level / description.`,
|
|
101
101
|
})
|
|
102
102
|
}
|
|
103
103
|
const entry: ManifestHardwareRequirement = {type: validatedType, level: validatedLevel}
|
package/src/manifest-wizard.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// `glassly
|
|
1
|
+
// `glassly manifest` — interactive top-level wizard.
|
|
2
2
|
//
|
|
3
3
|
// Uses the same mutation backend as the object-verb subcommands, so behavior
|
|
4
4
|
// is identical. Loop-driven: read manifest, prompt for an action, mutate,
|
package/src/manifest.test.ts
CHANGED
|
@@ -207,6 +207,12 @@ describe('validateManifest', () => {
|
|
|
207
207
|
expect(errors.some((e) => e.includes('type'))).toBe(true);
|
|
208
208
|
});
|
|
209
209
|
|
|
210
|
+
test('type accepts "dashboard" miniapps and a boolean alwaysOn', () => {
|
|
211
|
+
expect(validateManifest({...minimalValid, type: 'dashboard', alwaysOn: true}).valid).toBe(true);
|
|
212
|
+
const {errors} = validateManifest({...minimalValid, alwaysOn: 'yes'});
|
|
213
|
+
expect(errors.some((e) => e.includes('alwaysOn'))).toBe(true);
|
|
214
|
+
});
|
|
215
|
+
|
|
210
216
|
test('type accepts "background" miniapps', () => {
|
|
211
217
|
const {valid} = validateManifest({...minimalValid, type: 'background'});
|
|
212
218
|
expect(valid).toBe(true);
|
|
@@ -319,4 +325,52 @@ describe('validateManifest', () => {
|
|
|
319
325
|
expect(errors.some((e) => e.includes('items.type'))).toBe(true);
|
|
320
326
|
});
|
|
321
327
|
});
|
|
328
|
+
describe('store fields (tagline, tags)', () => {
|
|
329
|
+
test('accepts a tagline and known tags', () => {
|
|
330
|
+
const {valid, errors} = validateManifest({
|
|
331
|
+
...minimalValid,
|
|
332
|
+
tagline: 'Read scripts on your glasses',
|
|
333
|
+
tags: ['productivity', 'ai'],
|
|
334
|
+
});
|
|
335
|
+
expect(valid).toBe(true);
|
|
336
|
+
expect(errors).toEqual([]);
|
|
337
|
+
});
|
|
338
|
+
|
|
339
|
+
test('accepts unknown slug tags', () => {
|
|
340
|
+
const {valid} = validateManifest({...minimalValid, tags: ['home-automation']});
|
|
341
|
+
expect(valid).toBe(true);
|
|
342
|
+
});
|
|
343
|
+
|
|
344
|
+
test('rejects a tagline over 80 characters', () => {
|
|
345
|
+
const {valid, errors} = validateManifest({...minimalValid, tagline: 'x'.repeat(81)});
|
|
346
|
+
expect(valid).toBe(false);
|
|
347
|
+
expect(errors.some((e) => e.includes('tagline must be 80'))).toBe(true);
|
|
348
|
+
});
|
|
349
|
+
|
|
350
|
+
test('rejects a blank or multi-line tagline', () => {
|
|
351
|
+
expect(validateManifest({...minimalValid, tagline: ' '}).valid).toBe(false);
|
|
352
|
+
expect(validateManifest({...minimalValid, tagline: 'a\nb'}).valid).toBe(false);
|
|
353
|
+
});
|
|
354
|
+
|
|
355
|
+
test('rejects more than five tags', () => {
|
|
356
|
+
const {errors} = validateManifest({...minimalValid, tags: ['a', 'b', 'c', 'd', 'e', 'f']});
|
|
357
|
+
expect(errors.some((e) => e.includes('5 entries or fewer'))).toBe(true);
|
|
358
|
+
});
|
|
359
|
+
|
|
360
|
+
test('rejects non-slug tags', () => {
|
|
361
|
+
const {errors} = validateManifest({...minimalValid, tags: ['Productivity', 'a b', '-lead']});
|
|
362
|
+
expect(errors.filter((e) => e.includes('lowercase slug')).length).toBe(3);
|
|
363
|
+
});
|
|
364
|
+
|
|
365
|
+
test('rejects duplicate tags and non-string entries', () => {
|
|
366
|
+
const {errors} = validateManifest({...minimalValid, tags: ['ai', 'ai', 3]});
|
|
367
|
+
expect(errors.some((e) => e.includes('duplicated'))).toBe(true);
|
|
368
|
+
expect(errors.some((e) => e.includes('tags[2] must be a string'))).toBe(true);
|
|
369
|
+
});
|
|
370
|
+
|
|
371
|
+
test('rejects a non-array tags value', () => {
|
|
372
|
+
const {errors} = validateManifest({...minimalValid, tags: 'ai'});
|
|
373
|
+
expect(errors.some((e) => e.includes('tags must be an array'))).toBe(true);
|
|
374
|
+
});
|
|
375
|
+
});
|
|
322
376
|
});
|
package/src/manifest.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
// Note: these enum string values must stay in sync with @glassly/
|
|
2
|
-
// We cannot depend on
|
|
1
|
+
// Note: these enum string values must stay in sync with @glassly/engine and
|
|
2
|
+
// @glassly/miniapp. We cannot depend on them here because this lightweight CLI package
|
|
3
3
|
// is intentionally dependency-minimal (so `bunx @glassly/miniapp-cli` starts
|
|
4
4
|
// fast). Mirror string lists manually; failing validations point authors at
|
|
5
5
|
// the allowed values directly.
|
|
@@ -18,11 +18,14 @@ export const ALLOWED_PERMISSIONS = [
|
|
|
18
18
|
'LOCATION',
|
|
19
19
|
'BACKGROUND_LOCATION',
|
|
20
20
|
'READ_NOTIFICATIONS',
|
|
21
|
+
'DISPLAY_MIRROR',
|
|
21
22
|
'POST_NOTIFICATIONS',
|
|
22
23
|
'API_KEYS',
|
|
23
24
|
'MEMORY',
|
|
24
25
|
'AI',
|
|
25
26
|
'SPEAKERS',
|
|
27
|
+
'MANAGE_MINIAPPS',
|
|
28
|
+
'PLATFORM_SETTINGS',
|
|
26
29
|
] as const;
|
|
27
30
|
|
|
28
31
|
export type AllowedPermission = (typeof ALLOWED_PERMISSIONS)[number];
|
|
@@ -106,6 +109,10 @@ export interface MiniappManifestV1 {
|
|
|
106
109
|
version: string;
|
|
107
110
|
name: string;
|
|
108
111
|
description?: string;
|
|
112
|
+
/** One line shown under the name in the store, max 80 characters. */
|
|
113
|
+
tagline?: string;
|
|
114
|
+
/** Store tags, lowercase slugs, max 5 (e.g. ["productivity", "ai"]). */
|
|
115
|
+
tags?: string[];
|
|
109
116
|
icon?: string;
|
|
110
117
|
port?: number;
|
|
111
118
|
permissions?: ManifestPermission[];
|
|
@@ -116,14 +123,72 @@ export interface MiniappManifestV1 {
|
|
|
116
123
|
minHostVersion?: string;
|
|
117
124
|
/** Two-layer bundle entry points. */
|
|
118
125
|
entry?: ManifestEntry;
|
|
119
|
-
/**
|
|
120
|
-
|
|
126
|
+
/**
|
|
127
|
+
* Miniapp shape — defaults to "standard" (background + on-demand UI).
|
|
128
|
+
* "dashboard" is a standard app that can hold the dashboard role: one
|
|
129
|
+
* dashboard runs at a time, and the host hands the running one the overlay slot.
|
|
130
|
+
*/
|
|
131
|
+
type?: "standard" | "background" | "dashboard";
|
|
132
|
+
/** Always On miniapp: started at launch, keeps running after its app switcher card is swiped away. The wearer can still stop it. */
|
|
133
|
+
alwaysOn?: boolean;
|
|
121
134
|
/** Actions other (system) miniapps can invoke via session.actions. */
|
|
122
135
|
actions?: ManifestAction[];
|
|
123
136
|
}
|
|
124
137
|
|
|
125
138
|
const ACTION_ID_RE = /^[a-z][a-z0-9_]*$/;
|
|
126
139
|
|
|
140
|
+
export const TAGLINE_MAX_LENGTH = 80;
|
|
141
|
+
export const TAGS_MAX_COUNT = 5;
|
|
142
|
+
export const TAG_MAX_LENGTH = 32;
|
|
143
|
+
export const TAG_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
144
|
+
|
|
145
|
+
/** Store tag slugs the Glassly App shows as filter chips. Unknown tags are accepted and stored. */
|
|
146
|
+
export const KNOWN_TAGS = [
|
|
147
|
+
'productivity',
|
|
148
|
+
'communication',
|
|
149
|
+
'navigation',
|
|
150
|
+
'ai',
|
|
151
|
+
'games',
|
|
152
|
+
'developer',
|
|
153
|
+
'media',
|
|
154
|
+
] as const;
|
|
155
|
+
|
|
156
|
+
export function validateTagline(tagline: unknown): string[] {
|
|
157
|
+
if (typeof tagline !== 'string') return ['tagline must be a string when set'];
|
|
158
|
+
if (!tagline.trim()) return ['tagline must not be blank when set'];
|
|
159
|
+
if (tagline.length > TAGLINE_MAX_LENGTH) {
|
|
160
|
+
return [`tagline must be ${TAGLINE_MAX_LENGTH} characters or fewer (got ${tagline.length})`];
|
|
161
|
+
}
|
|
162
|
+
if (/[\r\n]/.test(tagline)) return ['tagline must be a single line'];
|
|
163
|
+
return [];
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
export function validateTags(tags: unknown): string[] {
|
|
167
|
+
if (!Array.isArray(tags)) return ['tags must be an array of lowercase slug strings when set'];
|
|
168
|
+
const errors: string[] = [];
|
|
169
|
+
if (tags.length > TAGS_MAX_COUNT) {
|
|
170
|
+
errors.push(`tags must have ${TAGS_MAX_COUNT} entries or fewer (got ${tags.length})`);
|
|
171
|
+
}
|
|
172
|
+
const seen = new Set<string>();
|
|
173
|
+
tags.forEach((tag, i) => {
|
|
174
|
+
if (typeof tag !== 'string') {
|
|
175
|
+
errors.push(`tags[${i}] must be a string. Got: ${JSON.stringify(tag)}`);
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
if (!TAG_SLUG_RE.test(tag)) {
|
|
179
|
+
errors.push(
|
|
180
|
+
`tags[${i}]: "${tag}" must be a lowercase slug (letters, digits, single hyphens). Known tags: ${KNOWN_TAGS.join(', ')}`,
|
|
181
|
+
);
|
|
182
|
+
} else if (tag.length > TAG_MAX_LENGTH) {
|
|
183
|
+
errors.push(`tags[${i}] must be ${TAG_MAX_LENGTH} characters or fewer`);
|
|
184
|
+
} else if (seen.has(tag)) {
|
|
185
|
+
errors.push(`tags[${i}] "${tag}" is duplicated`);
|
|
186
|
+
}
|
|
187
|
+
seen.add(tag);
|
|
188
|
+
});
|
|
189
|
+
return errors;
|
|
190
|
+
}
|
|
191
|
+
|
|
127
192
|
function validateActionParameters(parameters: unknown, actionIndex: number, errors: string[]): void {
|
|
128
193
|
if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) {
|
|
129
194
|
errors.push(`actions[${actionIndex}].parameters must be a JSON-Schema object with "type": "object"`);
|
|
@@ -192,6 +257,9 @@ export function validateManifest(manifest: unknown): { valid: boolean; errors: s
|
|
|
192
257
|
errors.push('name must be a non-empty string');
|
|
193
258
|
}
|
|
194
259
|
|
|
260
|
+
if (m.tagline !== undefined) errors.push(...validateTagline(m.tagline));
|
|
261
|
+
if (m.tags !== undefined) errors.push(...validateTags(m.tags));
|
|
262
|
+
|
|
195
263
|
// permissions — optional array of {type, required?, description?}
|
|
196
264
|
if (m.permissions !== undefined) {
|
|
197
265
|
if (!Array.isArray(m.permissions)) {
|
|
@@ -289,11 +357,15 @@ export function validateManifest(manifest: unknown): { valid: boolean; errors: s
|
|
|
289
357
|
}
|
|
290
358
|
|
|
291
359
|
if (m.type !== undefined) {
|
|
292
|
-
if (m.type !== 'standard' && m.type !== 'background') {
|
|
293
|
-
errors.push('type must be "standard" or "
|
|
360
|
+
if (m.type !== 'standard' && m.type !== 'background' && m.type !== 'dashboard') {
|
|
361
|
+
errors.push('type must be "standard", "background" or "dashboard" when set');
|
|
294
362
|
}
|
|
295
363
|
}
|
|
296
364
|
|
|
365
|
+
if (m.alwaysOn !== undefined && typeof m.alwaysOn !== 'boolean') {
|
|
366
|
+
errors.push('alwaysOn must be a boolean when set');
|
|
367
|
+
}
|
|
368
|
+
|
|
297
369
|
// actions — optional array of {id, description, parameters?}. The MCP-shaped
|
|
298
370
|
// capability surface other (system) miniapps invoke via session.actions.
|
|
299
371
|
if (m.actions !== undefined) {
|
package/src/pack.ts
CHANGED
|
@@ -34,19 +34,16 @@ export async function pack(opts: PackOptions = {}): Promise<string> {
|
|
|
34
34
|
const manifestSrc = resolve(cwd, 'miniapp.json');
|
|
35
35
|
const iconSrc = resolve(cwd, 'icon.png');
|
|
36
36
|
|
|
37
|
-
// Verify dist/ exists
|
|
38
37
|
if (!existsSync(distDir)) {
|
|
39
38
|
console.error('Error: dist/ directory not found. Build your miniapp first.');
|
|
40
39
|
process.exit(1);
|
|
41
40
|
}
|
|
42
41
|
|
|
43
|
-
// Verify miniapp.json exists
|
|
44
42
|
if (!existsSync(manifestSrc)) {
|
|
45
43
|
console.error('Error: miniapp.json not found in current directory');
|
|
46
44
|
process.exit(1);
|
|
47
45
|
}
|
|
48
46
|
|
|
49
|
-
// Read and validate manifest
|
|
50
47
|
const manifestRaw = readFileSync(manifestSrc, 'utf-8');
|
|
51
48
|
let manifest: Record<string, unknown>;
|
|
52
49
|
try {
|
|
@@ -94,10 +91,8 @@ export async function pack(opts: PackOptions = {}): Promise<string> {
|
|
|
94
91
|
checkRelative('ui', entry.ui, false);
|
|
95
92
|
}
|
|
96
93
|
|
|
97
|
-
// Copy miniapp.json into dist/
|
|
98
94
|
copyFileSync(manifestSrc, join(distDir, 'miniapp.json'));
|
|
99
95
|
|
|
100
|
-
// Copy icon.png into dist/ if it exists
|
|
101
96
|
if (existsSync(iconSrc)) {
|
|
102
97
|
copyFileSync(iconSrc, join(distDir, 'icon.png'));
|
|
103
98
|
} else if (!opts.silent) {
|
|
@@ -117,7 +112,6 @@ export async function pack(opts: PackOptions = {}): Promise<string> {
|
|
|
117
112
|
}
|
|
118
113
|
const outputPath = resolve(outDir, outputName);
|
|
119
114
|
|
|
120
|
-
// Create ZIP using system zip command
|
|
121
115
|
const zipProc = Bun.spawn(['zip', '-r', outputPath, '.'], {
|
|
122
116
|
cwd: distDir,
|
|
123
117
|
stdout: opts.silent ? 'pipe' : 'inherit',
|
package/src/permission-hints.ts
CHANGED
|
@@ -9,11 +9,15 @@ const PERMISSION_HINTS: Record<AllowedPermission, string> = {
|
|
|
9
9
|
CALENDAR: "Required to receive calendar event subscriptions",
|
|
10
10
|
LOCATION: "Required for foreground location updates",
|
|
11
11
|
BACKGROUND_LOCATION: "Required for location updates while app is backgrounded",
|
|
12
|
+
DISPLAY_MIRROR: "Read the global glasses display, including other miniapps",
|
|
12
13
|
READ_NOTIFICATIONS: "Required to receive phone notifications",
|
|
13
14
|
POST_NOTIFICATIONS: "Required to post system notifications from the miniapp",
|
|
14
15
|
API_KEYS: "Required to read user-supplied provider API keys via session.keys.get()",
|
|
15
16
|
MEMORY: "Required to read/write the user's shared memory timeline via session.memory",
|
|
16
17
|
AI: "Required to run LLM completions via session.ai.complete()",
|
|
18
|
+
SPEAKERS: "Required to resolve enrolled speaker ids to display names via session.speakers",
|
|
19
|
+
MANAGE_MINIAPPS: "Required to list, start and stop other miniapps via session.miniapps",
|
|
20
|
+
PLATFORM_SETTINGS: "Required to read and write platform settings via session.settings",
|
|
17
21
|
}
|
|
18
22
|
|
|
19
23
|
const HARDWARE_HINTS: Record<AllowedHardwareType, string> = {
|
package/src/permission.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// `glassly
|
|
1
|
+
// `glassly permission <action>` subcommand handlers.
|
|
2
2
|
//
|
|
3
3
|
// Object-verb surface for the most common manifest edit. Both interactive
|
|
4
4
|
// (no type arg → clack prompts) and non-interactive (type arg given) flows.
|
package/src/release.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* `glassly
|
|
2
|
+
* `glassly release` — build a release and install it on a phone.
|
|
3
3
|
*
|
|
4
4
|
* Flow:
|
|
5
5
|
* 1. Detect package manager, run `<pm> run build` so the user's bundler
|
|
@@ -33,12 +33,14 @@ import {validateManifest} from './manifest.js'
|
|
|
33
33
|
|
|
34
34
|
const DEFAULT_PORT_START = 6789
|
|
35
35
|
const PORT_SCAN_LIMIT = 10
|
|
36
|
-
const HEALTH_PATH = '/
|
|
36
|
+
const HEALTH_PATH = '/__host_release/health'
|
|
37
37
|
const MANIFEST_PATH = '/miniapp.json'
|
|
38
38
|
const ICON_PATH = '/icon.png'
|
|
39
39
|
const BUNDLE_PATH = '/bundle.zip'
|
|
40
40
|
|
|
41
|
-
interface ReleaseOptions {
|
|
41
|
+
export interface ReleaseOptions {
|
|
42
|
+
/** Miniapp project root. Defaults to the current working directory. */
|
|
43
|
+
cwd?: string
|
|
42
44
|
noCache?: boolean
|
|
43
45
|
/** Terminal QR size (--qr/-q small|medium|large). Defaults to medium. */
|
|
44
46
|
qrSize?: QRSize
|
|
@@ -46,7 +48,7 @@ interface ReleaseOptions {
|
|
|
46
48
|
}
|
|
47
49
|
|
|
48
50
|
export async function release(opts: ReleaseOptions = {}): Promise<void> {
|
|
49
|
-
const cwd = process.cwd()
|
|
51
|
+
const cwd = resolve(opts.cwd ?? process.cwd())
|
|
50
52
|
|
|
51
53
|
// ---- 1. Validate manifest + read identity ---------------------------
|
|
52
54
|
const manifestPath = resolve(cwd, 'miniapp.json')
|
package/src/schema.test.ts
CHANGED
|
@@ -37,6 +37,16 @@ describe('generateSchema', () => {
|
|
|
37
37
|
expect(schema.properties.actions.items.properties.outputSchema.type).toBe('object');
|
|
38
38
|
});
|
|
39
39
|
|
|
40
|
+
test('store fields carry the validator limits', () => {
|
|
41
|
+
const schema = generateSchema() as any;
|
|
42
|
+
expect(schema.properties.tagline.maxLength).toBe(80);
|
|
43
|
+
expect(schema.properties.tags.maxItems).toBe(5);
|
|
44
|
+
const re = new RegExp(schema.properties.tags.items.pattern);
|
|
45
|
+
expect(re.test('productivity')).toBe(true);
|
|
46
|
+
expect(re.test('home-automation')).toBe(true);
|
|
47
|
+
expect(re.test('Productivity')).toBe(false);
|
|
48
|
+
});
|
|
49
|
+
|
|
40
50
|
test('top-level allows extras for forward-compat', () => {
|
|
41
51
|
const schema = generateSchema() as any;
|
|
42
52
|
expect(schema.additionalProperties).toBe(true);
|
package/src/schema.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
//
|
|
6
6
|
// Surface:
|
|
7
7
|
// - generateSchema(): returns the JSON Schema object
|
|
8
|
-
// - glassly
|
|
8
|
+
// - glassly schema print : prints the schema to stdout
|
|
9
9
|
//
|
|
10
10
|
// Authors point their IDE at the schema via $schema in miniapp.json:
|
|
11
11
|
// "$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json"
|
|
@@ -21,6 +21,10 @@ import {
|
|
|
21
21
|
ALLOWED_HARDWARE_TYPES,
|
|
22
22
|
ALLOWED_HARDWARE_LEVELS,
|
|
23
23
|
ALLOWED_ACTION_PARAM_TYPES,
|
|
24
|
+
KNOWN_TAGS,
|
|
25
|
+
TAGLINE_MAX_LENGTH,
|
|
26
|
+
TAGS_MAX_COUNT,
|
|
27
|
+
TAG_MAX_LENGTH,
|
|
24
28
|
} from './manifest.js';
|
|
25
29
|
|
|
26
30
|
const SCHEMA_ID = 'https://schemas.glassly.com/miniapp/v1.json';
|
|
@@ -53,6 +57,22 @@ export function generateSchema(): Record<string, unknown> {
|
|
|
53
57
|
type: 'string',
|
|
54
58
|
description: 'Short description shown in the store / dev tools',
|
|
55
59
|
},
|
|
60
|
+
tagline: {
|
|
61
|
+
type: 'string',
|
|
62
|
+
maxLength: TAGLINE_MAX_LENGTH,
|
|
63
|
+
description: 'One line shown under the name in the Glassly Miniapp Store',
|
|
64
|
+
},
|
|
65
|
+
tags: {
|
|
66
|
+
type: 'array',
|
|
67
|
+
maxItems: TAGS_MAX_COUNT,
|
|
68
|
+
uniqueItems: true,
|
|
69
|
+
description: `Store tags used as filter chips. Known tags: ${KNOWN_TAGS.join(', ')}. Other lowercase slugs are accepted.`,
|
|
70
|
+
items: {
|
|
71
|
+
type: 'string',
|
|
72
|
+
pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$',
|
|
73
|
+
maxLength: TAG_MAX_LENGTH,
|
|
74
|
+
},
|
|
75
|
+
},
|
|
56
76
|
icon: {
|
|
57
77
|
type: 'string',
|
|
58
78
|
description: 'Path or URL to the app icon (e.g. icon.png)',
|
|
@@ -89,8 +109,14 @@ export function generateSchema(): Record<string, unknown> {
|
|
|
89
109
|
},
|
|
90
110
|
type: {
|
|
91
111
|
type: 'string',
|
|
92
|
-
enum: ['standard', 'background'],
|
|
93
|
-
description:
|
|
112
|
+
enum: ['standard', 'background', 'dashboard'],
|
|
113
|
+
description:
|
|
114
|
+
"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'.",
|
|
115
|
+
},
|
|
116
|
+
alwaysOn: {
|
|
117
|
+
type: 'boolean',
|
|
118
|
+
description:
|
|
119
|
+
'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.',
|
|
94
120
|
},
|
|
95
121
|
permissions: {
|
|
96
122
|
type: 'array',
|
|
@@ -107,7 +133,8 @@ export function generateSchema(): Record<string, unknown> {
|
|
|
107
133
|
},
|
|
108
134
|
required: {
|
|
109
135
|
type: 'boolean',
|
|
110
|
-
description:
|
|
136
|
+
description:
|
|
137
|
+
'If false, the permission is optional: asked at launch after the required ones, and the miniapp opens without it. Defaults to true.',
|
|
111
138
|
},
|
|
112
139
|
description: {
|
|
113
140
|
type: 'string',
|
|
@@ -212,7 +239,7 @@ export function writeSchemaFile(absPath: string): void {
|
|
|
212
239
|
writeFileSync(absPath, generateSchemaString(), 'utf8');
|
|
213
240
|
}
|
|
214
241
|
|
|
215
|
-
/** CLI entry: `glassly
|
|
242
|
+
/** CLI entry: `glassly schema print` writes JSON to stdout. */
|
|
216
243
|
export function schemaPrint(): void {
|
|
217
244
|
process.stdout.write(generateSchemaString());
|
|
218
245
|
}
|
package/src/index.ts
DELETED
|
@@ -1,127 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env bun
|
|
2
|
-
|
|
3
|
-
import { dev } from './dev.js';
|
|
4
|
-
import { release } from './release.js';
|
|
5
|
-
import { pack } from './pack.js';
|
|
6
|
-
import { schemaPrint, regenerateSchemaFile } from './schema.js';
|
|
7
|
-
import { addPermissionCmd, listPermissionsCmd, removePermissionCmd } from './permission.js';
|
|
8
|
-
import { addHardwareCmd, listHardwareCmd, removeHardwareCmd } from './hardware.js';
|
|
9
|
-
import { runManifestWizard } from './manifest-wizard.js';
|
|
10
|
-
import type { QRSize } from './qr.js';
|
|
11
|
-
|
|
12
|
-
const subcommand = process.argv[2];
|
|
13
|
-
const subcommandArg = process.argv[3];
|
|
14
|
-
|
|
15
|
-
const QR_SIZES: Record<string, QRSize> = {
|
|
16
|
-
sm: 'small',
|
|
17
|
-
small: 'small',
|
|
18
|
-
md: 'medium',
|
|
19
|
-
medium: 'medium',
|
|
20
|
-
lg: 'large',
|
|
21
|
-
large: 'large',
|
|
22
|
-
};
|
|
23
|
-
|
|
24
|
-
function parseQrSize(): QRSize {
|
|
25
|
-
let raw: string | undefined;
|
|
26
|
-
for (let i = 0; i < process.argv.length; i++) {
|
|
27
|
-
const arg = process.argv[i];
|
|
28
|
-
if (arg === '--qr' || arg === '-q') raw = process.argv[i + 1];
|
|
29
|
-
else if (arg.startsWith('--qr=')) raw = arg.slice('--qr='.length);
|
|
30
|
-
}
|
|
31
|
-
if (raw === undefined) return 'medium';
|
|
32
|
-
const size = QR_SIZES[raw.toLowerCase()];
|
|
33
|
-
if (!size) {
|
|
34
|
-
console.error(`Invalid --qr size "${raw}" (expected small|medium|large or sm|md|lg)`);
|
|
35
|
-
process.exit(1);
|
|
36
|
-
}
|
|
37
|
-
return size;
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
function printUsage(): void {
|
|
41
|
-
console.log('Usage: glassly-miniapp <command>\n');
|
|
42
|
-
console.log('Commands:');
|
|
43
|
-
console.log(' dev Start dev server with hot reload and QR code (--qr/-q sm|md|lg, default md)');
|
|
44
|
-
console.log(' Options: --qr-output <path> write PNG QR to path');
|
|
45
|
-
console.log(' release Build, pack, and serve a QR to install on a phone (--qr/-q sm|md|lg, default md)');
|
|
46
|
-
console.log(' Options: --no-cache --qr-output <path>');
|
|
47
|
-
console.log(' pack Production-build and package miniapp into build/<pkg>-<version>.zip (--no-build to skip build)');
|
|
48
|
-
console.log(' manifest Edit miniapp.json interactively');
|
|
49
|
-
console.log(' permission list List declared permissions');
|
|
50
|
-
console.log(' permission add [TYPE] Add a permission (interactive without TYPE)');
|
|
51
|
-
console.log(' permission remove [TYPE] Remove a declared permission');
|
|
52
|
-
console.log(' hardware list List declared hardware requirements');
|
|
53
|
-
console.log(' hardware add [TYPE] [LEVEL] Add a hardware requirement');
|
|
54
|
-
console.log(' hardware remove [TYPE] Remove a declared hardware requirement');
|
|
55
|
-
console.log(' schema print Print the miniapp.json JSON Schema to stdout');
|
|
56
|
-
console.log(' schema regenerate Regenerate the published schema file (CLI internal)');
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
function flagValue(flag: string): string | undefined {
|
|
60
|
-
const idx = process.argv.indexOf(flag);
|
|
61
|
-
if (idx === -1) return undefined;
|
|
62
|
-
const value = process.argv[idx + 1];
|
|
63
|
-
if (!value || value.startsWith('-')) {
|
|
64
|
-
console.error(`Error: ${flag} requires a path argument`);
|
|
65
|
-
process.exit(1);
|
|
66
|
-
}
|
|
67
|
-
return value;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
switch (subcommand) {
|
|
71
|
-
case 'dev':
|
|
72
|
-
await dev({qrSize: parseQrSize(), qrOutput: flagValue('--qr-output')});
|
|
73
|
-
break;
|
|
74
|
-
case 'release':
|
|
75
|
-
await release({
|
|
76
|
-
noCache: process.argv.includes('--no-cache'),
|
|
77
|
-
qrSize: parseQrSize(),
|
|
78
|
-
qrOutput: flagValue('--qr-output'),
|
|
79
|
-
});
|
|
80
|
-
break;
|
|
81
|
-
case 'pack':
|
|
82
|
-
// Build with NODE_ENV=production before zipping, so `pack` never ships
|
|
83
|
-
// a stale dev-mode dist/ left behind by `dev`. `--no-build` zips dist/
|
|
84
|
-
// as-is for callers that manage the build themselves.
|
|
85
|
-
await pack({build: !process.argv.includes('--no-build')});
|
|
86
|
-
break;
|
|
87
|
-
case 'manifest':
|
|
88
|
-
await runManifestWizard();
|
|
89
|
-
break;
|
|
90
|
-
case 'permission':
|
|
91
|
-
if (subcommandArg === 'list') {
|
|
92
|
-
await listPermissionsCmd();
|
|
93
|
-
} else if (subcommandArg === 'add') {
|
|
94
|
-
await addPermissionCmd(process.argv[4]);
|
|
95
|
-
} else if (subcommandArg === 'remove') {
|
|
96
|
-
await removePermissionCmd(process.argv[4]);
|
|
97
|
-
} else {
|
|
98
|
-
console.error('Usage: glassly-miniapp permission <list|add|remove> [TYPE]');
|
|
99
|
-
process.exit(1);
|
|
100
|
-
}
|
|
101
|
-
break;
|
|
102
|
-
case 'hardware':
|
|
103
|
-
if (subcommandArg === 'list') {
|
|
104
|
-
await listHardwareCmd();
|
|
105
|
-
} else if (subcommandArg === 'add') {
|
|
106
|
-
await addHardwareCmd(process.argv[4], process.argv[5]);
|
|
107
|
-
} else if (subcommandArg === 'remove') {
|
|
108
|
-
await removeHardwareCmd(process.argv[4]);
|
|
109
|
-
} else {
|
|
110
|
-
console.error('Usage: glassly-miniapp hardware <list|add|remove> [TYPE] [LEVEL]');
|
|
111
|
-
process.exit(1);
|
|
112
|
-
}
|
|
113
|
-
break;
|
|
114
|
-
case 'schema':
|
|
115
|
-
if (subcommandArg === 'print') {
|
|
116
|
-
schemaPrint();
|
|
117
|
-
} else if (subcommandArg === 'regenerate') {
|
|
118
|
-
regenerateSchemaFile();
|
|
119
|
-
} else {
|
|
120
|
-
console.error('Usage: glassly-miniapp schema <print|regenerate>');
|
|
121
|
-
process.exit(1);
|
|
122
|
-
}
|
|
123
|
-
break;
|
|
124
|
-
default:
|
|
125
|
-
printUsage();
|
|
126
|
-
process.exit(subcommand ? 1 : 0);
|
|
127
|
-
}
|