kamoji-dev 0.1.0 → 0.1.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 +30 -11
- package/package.json +7 -2
- package/src/check.js +8 -207
- package/src/cli.js +38 -16
- package/src/core/bytes.js +112 -0
- package/src/core/check.js +222 -0
- package/src/core/dev.js +398 -0
- package/src/core/protocol.js +749 -0
- package/src/dev.js +14 -266
- package/src/logfilter.js +35 -0
- package/src/protocol.js +28 -555
package/README.md
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
Develop [Kamoji Mini Apps](https://docs.kamoji.bot/docs/apps) on your own Kamoji: edit the files in
|
|
4
4
|
your editor, save, and the mini app is checked, installed over Bluetooth and reopened on Kamoji's
|
|
5
|
-
screen within seconds
|
|
6
|
-
CPU budget warnings
|
|
5
|
+
screen within seconds; a save sends only the files that changed (firmware 0.3.3). Your app's log
|
|
6
|
+
(`print()` lines, Lua errors, CPU budget warnings) streams into the same terminal: over the USB
|
|
7
|
+
cable when one is plugged in (crashes too), else over Bluetooth (firmware 0.3.3).
|
|
7
8
|
|
|
8
9
|
```sh
|
|
9
10
|
npm i -g kamoji-dev
|
|
@@ -13,7 +14,8 @@ kamoji dev ./my-app
|
|
|
13
14
|
or without installing: `npx kamoji-dev dev ./my-app`.
|
|
14
15
|
|
|
15
16
|
Needs Node.js 20 or newer, a computer with Bluetooth LE (macOS, Windows 10+, Linux) and a Kamoji
|
|
16
|
-
with firmware 0.3.0 or newer (mini apps from 0.1.80
|
|
17
|
+
with firmware 0.3.0 or newer (mini apps from 0.1.80; 0.3.3 for changed-files reloads and the log
|
|
18
|
+
over Bluetooth).
|
|
17
19
|
|
|
18
20
|
## Before you start
|
|
19
21
|
|
|
@@ -34,17 +36,18 @@ with firmware 0.3.0 or newer (mini apps from 0.1.80).
|
|
|
34
36
|
|
|
35
37
|
| Command | What it does |
|
|
36
38
|
|---|---|
|
|
37
|
-
| `kamoji dev <folder>` | Check, install and open the mini app; then again on every save (400 ms after the last change). Keys while it runs: Enter = install again, `o` = open, `s` = screenshot, `b` = restart Kamoji, `q` = quit |
|
|
39
|
+
| `kamoji dev <folder>` | Check, install and open the mini app; then again on every save (400 ms after the last change), sending only the changed files. Keys while it runs: Enter = install again (every file), `o` = open, `s` = screenshot, `b` = restart Kamoji, `q` = quit |
|
|
38
40
|
| `kamoji install <folder>` | Check, install and open once (exit code 0 = on screen) |
|
|
39
41
|
| `kamoji check <folder>` | Only check the folder, like the Mini Apps store does (`--json` for tools) |
|
|
40
42
|
| `kamoji apps` | List the mini apps on Kamoji, with their mode numbers and sizes |
|
|
41
43
|
| `kamoji shot` | Save a screenshot (over USB when plugged in, else Bluetooth) to `./kamoji-shots` |
|
|
42
|
-
| `kamoji logs` | Kamoji's USB
|
|
44
|
+
| `kamoji logs` | Kamoji's log: USB, or over Bluetooth without a cable or with `--ble` (`--app <id>` to follow one app, `--verbose` for every USB line) |
|
|
43
45
|
| `kamoji forget` | Kamoji forgets this computer, and the key is deleted |
|
|
44
46
|
|
|
45
47
|
Options: `--device KMJ-XXXX` (several Kamoji nearby; the last four characters are enough),
|
|
46
48
|
`--port /dev/cu.usbmodemXXXX` (USB port, found by itself otherwise), `--ble` (no USB log even with a
|
|
47
|
-
cable), `--
|
|
49
|
+
cable: the app log comes over Bluetooth), `--ble-logs` (the app log over Bluetooth even with a cable;
|
|
50
|
+
USB then adds only crashes and resets), `--usb` (require the cable), `--out DIR` (screenshots), `--reboot` (restart Kamoji by itself
|
|
48
51
|
when the mini app's Bluetooth services need it), `--no-lua`, `--verbose`.
|
|
49
52
|
|
|
50
53
|
What you see:
|
|
@@ -59,8 +62,21 @@ What you see:
|
|
|
59
62
|
10:02:16 [entered] [my-app] entered in 118 ms: 4 bindings, Lua 2311 bytes
|
|
60
63
|
10:02:17 [print] tick 1
|
|
61
64
|
10:02:19 [warn] [my-app] main.lua: main.lua:12: attempt to perform arithmetic on a nil value
|
|
65
|
+
10:02:31 Updated my-app: 1 file changed (main.lua, 0.4 KB) in 0.6 s.
|
|
66
|
+
10:02:31 my-app is on screen (mode 7, 0.8 s after the first byte).
|
|
62
67
|
```
|
|
63
68
|
|
|
69
|
+
### Firmware 0.3.3 and older
|
|
70
|
+
|
|
71
|
+
| | Firmware 0.3.3 or newer | Older firmware |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| A save | Only the changed and new files are sent, removed ones deleted (`APP_FILES`, `APP_EDIT`, `APP_DELETE`). The app's `config.json` and `data/` are never deleted. Same files already there: `Nothing changed` | Every file (a note says so once) |
|
|
74
|
+
| Log without a USB cable | Over Bluetooth (`APP_LOG`): `print()`, lifecycle, warnings, Lua errors, at most 20 lines a second (`Kamoji dropped N log line(s)` otherwise). Crashes and resets need the cable | None (a note says so once) |
|
|
75
|
+
| Finding Kamoji | Fast for 30 s after a boot or a disconnect | Up to 30 s on Wi-Fi |
|
|
76
|
+
|
|
77
|
+
Whenever Kamoji can't do a changed-files update (the app isn't on it yet, it answers an error, a
|
|
78
|
+
line of the file list got lost), the tool sends every file instead; Enter always does.
|
|
79
|
+
|
|
64
80
|
## What it checks before sending
|
|
65
81
|
|
|
66
82
|
The store's rules (manifest `id`, `version`, `api_version` 1, known `permissions` / `features` /
|
|
@@ -77,9 +93,11 @@ are never sent. The full table is in `spec/VALIDATION.md` of the source.
|
|
|
77
93
|
The same Bluetooth commands as the Kamoji app's **Install from file**
|
|
78
94
|
([Sideloading](https://docs.kamoji.bot/docs/apps/sideloading#bluetooth-install-protocol)):
|
|
79
95
|
`APP_PUT` + `ASSET_DATA` per file, `APP_COMMIT`, then `SET_MODE` to the app's mode (from
|
|
80
|
-
`APPS_LIST`).
|
|
81
|
-
|
|
82
|
-
|
|
96
|
+
`APPS_LIST`). From firmware 0.3.3 a save of an installed app starts with `APP_FILES` (the md5 and
|
|
97
|
+
size of every installed file) and `APP_EDIT` (Kamoji stages a copy of it), then sends only what
|
|
98
|
+
changed and commits the same way; older firmware gets every file (unchanged saves are skipped). The
|
|
99
|
+
app's settings (`config.json`) and `data/` stay. A mini app that is on screen restarts with the new
|
|
100
|
+
version. Bluetooth is slow-ish: about 3-15 KB/s depending on the
|
|
83
101
|
computer, so a 10 KB app reloads in 1-3 s.
|
|
84
102
|
|
|
85
103
|
Over USB the tool only reads: Kamoji has no install over USB (that would mean rewriting its whole
|
|
@@ -102,13 +120,14 @@ The Python tool in the Kamoji repositories (`kamoji_dev.py`) uses the same files
|
|
|
102
120
|
| needs firmware … or newer | Update Kamoji in the Kamoji app |
|
|
103
121
|
| Kamoji is out of storage space | Remove a mini app in the Kamoji app (Apps) |
|
|
104
122
|
| its Bluetooth services go live after a restart | Press `b` (or run with `--reboot`) |
|
|
105
|
-
|
|
|
123
|
+
| This firmware sends no app log over Bluetooth | Update Kamoji to 0.3.3, or plug in a USB-C **data** cable; `--port` if several boards are plugged in |
|
|
124
|
+
| This firmware installs whole mini apps only | Nothing to do (every file is sent); update Kamoji to 0.3.3 for faster reloads |
|
|
106
125
|
|
|
107
126
|
## Development
|
|
108
127
|
|
|
109
128
|
```sh
|
|
110
129
|
npm test # node:test, fake Kamoji, no device needed
|
|
111
|
-
node spec/make-conversation.mjs # after changing the protocol: re-record spec/conversation
|
|
130
|
+
node spec/make-conversation.mjs # after changing the protocol: re-record spec/conversation*.json
|
|
112
131
|
```
|
|
113
132
|
|
|
114
133
|
Bluetooth is [@stoprocent/noble](https://github.com/stoprocent/noble) (maintained, prebuilt for
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kamoji-dev",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Develop Kamoji Mini Apps on your own Kamoji: check, install over Bluetooth and reload on every save, with the USB log and screenshots.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -18,7 +18,12 @@
|
|
|
18
18
|
"scripts": {
|
|
19
19
|
"test": "node --test test/*.test.js"
|
|
20
20
|
},
|
|
21
|
-
"keywords": [
|
|
21
|
+
"keywords": [
|
|
22
|
+
"kamoji",
|
|
23
|
+
"mini-apps",
|
|
24
|
+
"ble",
|
|
25
|
+
"esp32"
|
|
26
|
+
],
|
|
22
27
|
"homepage": "https://docs.kamoji.bot/docs/apps",
|
|
23
28
|
"license": "MIT",
|
|
24
29
|
"dependencies": {
|
package/src/check.js
CHANGED
|
@@ -1,54 +1,13 @@
|
|
|
1
1
|
// Reading a mini app folder and checking it before it is sent: the rules and their ids are in
|
|
2
|
-
// spec/VALIDATION.md (shared with the Python worker/rig/kamoji_dev.py of kamoji-cms).
|
|
3
|
-
//
|
|
4
|
-
// Copied from kamoji-cms src/utils/appBundle.ts (APP_ID_RE, SEMVER_RE, APP_PERMISSIONS, APP_FEATURES,
|
|
5
|
-
// APP_PLATFORMS, BUNDLE_LIMITS, checkAppPath) because this package is published on its own: keep both
|
|
6
|
-
// in step when the store's rules change.
|
|
2
|
+
// spec/VALIDATION.md (shared with the Python worker/rig/kamoji_dev.py of kamoji-cms). The rules themselves
|
|
3
|
+
// are in core/check.js (shared with the web IDE); this file reads the folder and runs the Lua compiler.
|
|
7
4
|
import fs from 'node:fs'
|
|
8
5
|
import path from 'node:path'
|
|
9
6
|
import { spawnSync } from 'node:child_process'
|
|
7
|
+
import { checkFiles, isJunk } from './core/check.js'
|
|
10
8
|
import { md5Hex } from './protocol.js'
|
|
11
9
|
|
|
12
|
-
export
|
|
13
|
-
export const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
|
|
14
|
-
export const VERSION_RE = /^v?\d+(\.\d+){1,3}(-[0-9A-Za-z.-]+)?$/
|
|
15
|
-
export const APP_PERMISSIONS = [
|
|
16
|
-
'sensors.imu', 'sensors.light', 'sensors.mic', 'sensors.env', 'sensors.obd', 'events.drive', 'events.device',
|
|
17
|
-
'touch', 'net.http', 'net.mqtt', 'net.phone', 'phone.navigation', 'ble.gatt',
|
|
18
|
-
]
|
|
19
|
-
export const APP_FEATURES = ['gyro', 'temperature', 'light', 'microphone', 'fft', 'wifi', 'ble', 'gatt', 'mqtt', 'http', 'time', 'rgb_leds']
|
|
20
|
-
export const APP_PLATFORMS = ['android', 'ios']
|
|
21
|
-
export const PARAM_TYPES = ['number', 'bool', 'string', 'enum', 'color', 'secret']
|
|
22
|
-
export const WIDGET_TYPES = ['label', 'rect', 'circle', 'arc', 'bar', 'line', 'polyline', 'bitmap', 'chart', 'image']
|
|
23
|
-
export const ALIGNS = ['center', 'top_left', 'top_mid', 'top_right', 'left_mid', 'right_mid', 'bottom_left', 'bottom_mid', 'bottom_right']
|
|
24
|
-
export const LIMITS = { maxTotalBytes: 2 * 1024 * 1024, maxFiles: 64, maxPathBytes: 63, maxDepth: 3, maxManifestBytes: 16384 }
|
|
25
|
-
|
|
26
|
-
const SKIP_NAMES = new Set(['.DS_Store', 'Thumbs.db', '__MACOSX', 'node_modules', '4913'])
|
|
27
|
-
|
|
28
|
-
/** Files an editor or the OS leaves next to the real ones: never sent. */
|
|
29
|
-
export function isJunk(name) {
|
|
30
|
-
return (
|
|
31
|
-
name.startsWith('.') || SKIP_NAMES.has(name) || name.endsWith('~') || /\.(swp|swo|swx|tmp)$/i.test(name) ||
|
|
32
|
-
/^#.*#$/.test(name)
|
|
33
|
-
)
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
/** Same as the store's checkAppPath: an error message, or null. */
|
|
37
|
-
export function checkAppPath(p) {
|
|
38
|
-
if (!p) return 'empty path'
|
|
39
|
-
if (p.startsWith('/') || /^[a-zA-Z]:/.test(p)) return `absolute path not allowed: ${p}`
|
|
40
|
-
if (p.includes('\\')) return `backslash in path: ${p}`
|
|
41
|
-
if (/[\x00-\x1f\x7f]/.test(p)) return `control character in path: ${JSON.stringify(p)}`
|
|
42
|
-
const segments = p.split('/')
|
|
43
|
-
for (const s of segments) {
|
|
44
|
-
if (s === '') return `empty path segment: ${p}`
|
|
45
|
-
if (s === '..' || s === '.') return `relative segment not allowed: ${p}`
|
|
46
|
-
if (s.startsWith('.')) return `names starting with "." are not allowed: ${p}`
|
|
47
|
-
}
|
|
48
|
-
if (Buffer.byteLength(p, 'utf8') > LIMITS.maxPathBytes) return `path longer than ${LIMITS.maxPathBytes} bytes: ${p}`
|
|
49
|
-
if (segments.length > LIMITS.maxDepth) return `path deeper than ${LIMITS.maxDepth} levels: ${p}`
|
|
50
|
-
return null
|
|
51
|
-
}
|
|
10
|
+
export * from './core/check.js'
|
|
52
11
|
|
|
53
12
|
/**
|
|
54
13
|
* Every file of the folder that would be sent: [{path, data, md5}] sorted by path, plus what was skipped.
|
|
@@ -77,20 +36,6 @@ export function readAppFolder(folder) {
|
|
|
77
36
|
return { files, skipped }
|
|
78
37
|
}
|
|
79
38
|
|
|
80
|
-
/** Version compare like the firmware checks: 0.3.10 > 0.3.9, a release after its -rc. */
|
|
81
|
-
export function compareVersions(a, b) {
|
|
82
|
-
const parse = (v) => {
|
|
83
|
-
const m = /^v?(\d+(?:\.\d+)*)(?:-(.*))?$/.exec(String(v ?? '').trim())
|
|
84
|
-
if (!m) return [[0, 0, 0, 0], '']
|
|
85
|
-
const nums = [...m[1].split('.').map(Number), 0, 0, 0, 0].slice(0, 4)
|
|
86
|
-
return [nums, m[2] ?? '~']
|
|
87
|
-
}
|
|
88
|
-
const [na, pa] = parse(a)
|
|
89
|
-
const [nb, pb] = parse(b)
|
|
90
|
-
for (let i = 0; i < 4; i++) if (na[i] !== nb[i]) return na[i] < nb[i] ? -1 : 1
|
|
91
|
-
return pa === pb ? 0 : pa < pb ? -1 : 1
|
|
92
|
-
}
|
|
93
|
-
|
|
94
39
|
let luacCache
|
|
95
40
|
/** The Lua compiler on this computer: { cmd, version: '5.4' | '5.5' | … } or null. */
|
|
96
41
|
export function findLuac() {
|
|
@@ -118,159 +63,15 @@ function checkLua(file, add) {
|
|
|
118
63
|
return true
|
|
119
64
|
}
|
|
120
65
|
|
|
121
|
-
function checkLayout(file, add) {
|
|
122
|
-
let layout
|
|
123
|
-
try {
|
|
124
|
-
layout = JSON.parse(file.data.toString('utf8').replace(/^/, ''))
|
|
125
|
-
} catch (e) {
|
|
126
|
-
add('error', 'layout-json', `not valid JSON: ${e.message}`, file.path)
|
|
127
|
-
return
|
|
128
|
-
}
|
|
129
|
-
let widgets
|
|
130
|
-
if (Array.isArray(layout)) widgets = layout
|
|
131
|
-
else if (layout && typeof layout === 'object' && Array.isArray(layout.widgets)) widgets = layout.widgets
|
|
132
|
-
else {
|
|
133
|
-
add('error', 'layout-shape', 'must be an array of widgets, or an object with a "widgets" array', file.path)
|
|
134
|
-
return
|
|
135
|
-
}
|
|
136
|
-
widgets.forEach((w, i) => {
|
|
137
|
-
const where = `${file.path} widget ${i + 1}`
|
|
138
|
-
if (!w || typeof w !== 'object' || Array.isArray(w)) {
|
|
139
|
-
add('warning', 'widget-type', 'not an object (skipped by Kamoji)', where)
|
|
140
|
-
return
|
|
141
|
-
}
|
|
142
|
-
if (!WIDGET_TYPES.includes(w.type))
|
|
143
|
-
add('warning', 'widget-type', `type ${JSON.stringify(w.type)} is not a widget Kamoji draws (${WIDGET_TYPES.join(', ')})`, where)
|
|
144
|
-
if (w.align !== undefined && !ALIGNS.includes(w.align)) add('warning', 'align', `align ${JSON.stringify(w.align)} is not one of ${ALIGNS.join(', ')}`, where)
|
|
145
|
-
for (const [k, v] of Object.entries(w)) {
|
|
146
|
-
if (typeof v === 'string' && v.split('{{').length - 1 > v.split('}}').length - 1)
|
|
147
|
-
add('warning', 'binding-braces', `"${k}" opens {{ without closing }}`, where)
|
|
148
|
-
}
|
|
149
|
-
})
|
|
150
|
-
if (!Array.isArray(layout) && layout.on !== undefined) {
|
|
151
|
-
if (!layout.on || typeof layout.on !== 'object' || Array.isArray(layout.on)) add('error', 'layout-on', '"on" must be an object', file.path)
|
|
152
|
-
else
|
|
153
|
-
for (const [k, v] of Object.entries(layout.on))
|
|
154
|
-
if (typeof v !== 'string') add('error', 'layout-on', `"on.${k}" must be a string of Lua statements`, file.path)
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
function checkManifest(m, folderName, add) {
|
|
159
|
-
const where = 'manifest.json'
|
|
160
|
-
if (typeof m.id !== 'string' || !APP_ID_RE.test(m.id))
|
|
161
|
-
add('error', 'id', '"id": lowercase letters, digits and "-", starting with a letter or digit, 2 to 40 characters', where)
|
|
162
|
-
else if (folderName && m.id !== folderName)
|
|
163
|
-
add('warning', 'id-folder', `"id" is "${m.id}" but the folder is "${folderName}" (the store and Kamoji use the id as the folder name)`, where)
|
|
164
|
-
if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version))
|
|
165
|
-
add('error', 'version', '"version" must be a version like 1.0.0 (the store needs it)', where)
|
|
166
|
-
if (m.api_version !== 1) add('error', 'api-version', '"api_version" must be 1', where)
|
|
167
|
-
const perms = m.permissions
|
|
168
|
-
if (perms !== undefined) {
|
|
169
|
-
if (!Array.isArray(perms)) add('error', 'permissions', '"permissions" must be an array', where)
|
|
170
|
-
else {
|
|
171
|
-
const unknown = perms.filter((p) => !APP_PERMISSIONS.includes(p))
|
|
172
|
-
if (unknown.length) add('error', 'permissions', `unknown permissions: ${unknown.join(', ')} (known: ${APP_PERMISSIONS.join(', ')})`, where)
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
if (m.features !== undefined) {
|
|
176
|
-
if (!Array.isArray(m.features)) add('error', 'features', '"features" must be an array', where)
|
|
177
|
-
else {
|
|
178
|
-
const unknown = m.features.filter((f) => !APP_FEATURES.includes(f))
|
|
179
|
-
if (unknown.length) add('error', 'features', `unknown features: ${unknown.join(', ')} (known: ${APP_FEATURES.join(', ')})`, where)
|
|
180
|
-
}
|
|
181
|
-
}
|
|
182
|
-
if (m.platforms !== undefined) {
|
|
183
|
-
if (!Array.isArray(m.platforms) || m.platforms.length === 0) add('error', 'platforms', '"platforms" must be a non-empty array', where)
|
|
184
|
-
else {
|
|
185
|
-
const unknown = m.platforms.filter((p) => !APP_PLATFORMS.includes(p))
|
|
186
|
-
if (unknown.length) add('error', 'platforms', `unknown platforms: ${unknown.join(', ')}`, where)
|
|
187
|
-
}
|
|
188
|
-
}
|
|
189
|
-
if (m.min_firmware !== undefined && (typeof m.min_firmware !== 'string' || !VERSION_RE.test(m.min_firmware)))
|
|
190
|
-
add('error', 'min-firmware', '"min_firmware" must be a version string like "0.3.0"', where)
|
|
191
|
-
const has = (p) => Array.isArray(perms) && perms.includes(p)
|
|
192
|
-
if (m.ble !== undefined && !has('ble.gatt')) add('error', 'ble-permission', '"ble" needs the "ble.gatt" permission (Kamoji refuses the install)', where)
|
|
193
|
-
if (m.http !== undefined && !has('net.http')) add('warning', 'http-permission', '"http" without the "net.http" permission: http is nil in Lua', where)
|
|
194
|
-
if ((m.ble !== undefined || m.http !== undefined) &&
|
|
195
|
-
(typeof m.min_firmware !== 'string' || compareVersions(m.min_firmware, '0.3.0') < 0))
|
|
196
|
-
add('warning', 'min-firmware-030', '"ble" and "http" need firmware 0.3.0: set "min_firmware": "0.3.0"', where)
|
|
197
|
-
if (m.params !== undefined) {
|
|
198
|
-
if (!Array.isArray(m.params)) add('error', 'params', '"params" must be an array', where)
|
|
199
|
-
else {
|
|
200
|
-
const seen = new Set()
|
|
201
|
-
m.params.forEach((p, i) => {
|
|
202
|
-
const at = `params[${i}]`
|
|
203
|
-
if (!p || typeof p !== 'object' || Array.isArray(p)) return add('error', 'params', `${at} must be an object`, where)
|
|
204
|
-
if (typeof p.key !== 'string' || !p.key) add('error', 'params', `${at} needs a "key"`, where)
|
|
205
|
-
else if (seen.has(p.key)) add('error', 'params', `${at}: key "${p.key}" is used twice`, where)
|
|
206
|
-
else seen.add(p.key)
|
|
207
|
-
const type = p.type ?? 'string'
|
|
208
|
-
if (!PARAM_TYPES.includes(type)) add('error', 'params', `${at}: type ${JSON.stringify(type)} is not one of ${PARAM_TYPES.join(', ')}`, where)
|
|
209
|
-
if (type === 'enum' && (!Array.isArray(p.options) || p.options.length === 0))
|
|
210
|
-
add('error', 'params', `${at}: an enum needs "options"`, where)
|
|
211
|
-
})
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
|
-
}
|
|
215
|
-
|
|
216
66
|
/**
|
|
217
67
|
* Check a folder. Returns { problems:[{level,id,message,where}], errors, warnings, manifest, appId, files, skipped, bytes }.
|
|
218
68
|
* @param {{lua?: boolean}} [opts] lua: false skips the Lua compiler
|
|
219
69
|
*/
|
|
220
70
|
export function checkApp(folder, opts = {}) {
|
|
221
|
-
const problems = []
|
|
222
|
-
const add = (level, id, message, where) => problems.push({ level, id, message, where })
|
|
223
71
|
const folderName = path.basename(path.resolve(folder))
|
|
224
72
|
const { files, skipped } = readAppFolder(folder)
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
}
|
|
230
|
-
if (files.length > LIMITS.maxFiles) add('error', 'too-many-files', `${files.length} files (at most ${LIMITS.maxFiles})`)
|
|
231
|
-
const bytes = files.reduce((n, f) => n + f.data.length, 0)
|
|
232
|
-
if (bytes > LIMITS.maxTotalBytes) add('error', 'too-large', `${Math.ceil(bytes / 1024)} KB (at most 2 MB)`)
|
|
233
|
-
|
|
234
|
-
let manifest = null
|
|
235
|
-
const mf = files.find((f) => f.path === 'manifest.json')
|
|
236
|
-
if (!mf) add('error', 'manifest-missing', 'no manifest.json at the root of the folder')
|
|
237
|
-
else if (mf.data.length > LIMITS.maxManifestBytes) add('error', 'manifest-size', `manifest.json is ${mf.data.length} bytes (at most 16 KB)`, 'manifest.json')
|
|
238
|
-
else {
|
|
239
|
-
try {
|
|
240
|
-
manifest = JSON.parse(mf.data.toString('utf8').replace(/^/, ''))
|
|
241
|
-
if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
|
|
242
|
-
manifest = null
|
|
243
|
-
add('error', 'manifest-json', 'manifest.json must be a JSON object', 'manifest.json')
|
|
244
|
-
}
|
|
245
|
-
} catch (e) {
|
|
246
|
-
add('error', 'manifest-json', `not valid JSON: ${e.message}`, 'manifest.json')
|
|
247
|
-
}
|
|
248
|
-
if (manifest) checkManifest(manifest, folderName, add)
|
|
249
|
-
}
|
|
250
|
-
const layout = files.find((f) => f.path === 'layout.json')
|
|
251
|
-
if (layout) checkLayout(layout, add)
|
|
252
|
-
if (opts.lua !== false) {
|
|
253
|
-
const luaFiles = files.filter((f) => f.path.endsWith('.lua'))
|
|
254
|
-
if (luaFiles.length) {
|
|
255
|
-
let ran = false
|
|
256
|
-
for (const f of luaFiles) ran = checkLua(f, add) || ran
|
|
257
|
-
if (!ran) add('info', 'lua-missing', 'no Lua compiler (luac5.4 / luac) found: Lua is checked by Kamoji only')
|
|
258
|
-
}
|
|
259
|
-
}
|
|
260
|
-
const appId = manifest && typeof manifest.id === 'string' && APP_ID_RE.test(manifest.id) ? manifest.id : null
|
|
261
|
-
return {
|
|
262
|
-
problems,
|
|
263
|
-
errors: problems.filter((p) => p.level === 'error'),
|
|
264
|
-
warnings: problems.filter((p) => p.level === 'warning'),
|
|
265
|
-
manifest,
|
|
266
|
-
appId,
|
|
267
|
-
files,
|
|
268
|
-
skipped,
|
|
269
|
-
bytes,
|
|
270
|
-
}
|
|
271
|
-
}
|
|
272
|
-
|
|
273
|
-
/** The md5 of the whole set (paths + contents): unchanged files are not sent again. */
|
|
274
|
-
export function bundleHash(files) {
|
|
275
|
-
return md5Hex(Buffer.from(files.map((f) => `${f.path}\0${f.md5}`).join('\n')))
|
|
73
|
+
return checkFiles(
|
|
74
|
+
{ files, skipped, folderName },
|
|
75
|
+
opts.lua === false ? {} : { luaCheck: checkLua, luaMissing: 'no Lua compiler (luac5.4 / luac) found: Lua is checked by Kamoji only' },
|
|
76
|
+
)
|
|
276
77
|
}
|
package/src/cli.js
CHANGED
|
@@ -20,22 +20,24 @@ Usage:
|
|
|
20
20
|
kamoji check <folder> only check the folder (manifest, layout, Lua) like the Mini Apps store
|
|
21
21
|
kamoji apps list the mini apps on Kamoji
|
|
22
22
|
kamoji shot save a screenshot of Kamoji's screen
|
|
23
|
-
kamoji logs show Kamoji's
|
|
23
|
+
kamoji logs show Kamoji's log (USB; over Bluetooth without a cable, or with --ble)
|
|
24
24
|
kamoji forget make Kamoji forget this computer, and delete its key
|
|
25
25
|
|
|
26
26
|
Options:
|
|
27
27
|
--device KMJ-XXXX which Kamoji (needed when several are near)
|
|
28
28
|
--port PATH USB serial port for the log (default: found by itself)
|
|
29
|
-
--ble Bluetooth only: no USB log even with a cable
|
|
29
|
+
--ble Bluetooth only: no USB log even with a cable (the app log comes over Bluetooth)
|
|
30
|
+
--ble-logs the app log over Bluetooth even with a USB cable (USB then adds crashes and resets)
|
|
30
31
|
--usb require the USB cable (log and screenshots over USB)
|
|
31
32
|
--out DIR where screenshots go (default: ./kamoji-shots)
|
|
32
33
|
--reboot restart Kamoji by itself when the app's Bluetooth services need it
|
|
33
|
-
--app ID (logs)
|
|
34
|
+
--app ID (logs) only this app's lines
|
|
34
35
|
--verbose every USB log line, and more detail
|
|
35
36
|
--no-lua don't run luac
|
|
36
37
|
--json (check) print the result as JSON
|
|
37
38
|
|
|
38
|
-
While "kamoji dev" runs
|
|
39
|
+
While "kamoji dev" runs (a save sends only the changed files; Enter sends every file):
|
|
40
|
+
Enter = install again, o = open, s = screenshot, b = restart Kamoji, q = quit.
|
|
39
41
|
|
|
40
42
|
Before you start: disconnect the Kamoji app on your phone (Kamoji takes one Bluetooth connection at
|
|
41
43
|
a time). The first time, keep the computer right next to Kamoji: it then trusts this computer (key in
|
|
@@ -45,6 +47,7 @@ const OPTIONS = {
|
|
|
45
47
|
device: { type: 'string' },
|
|
46
48
|
port: { type: 'string' },
|
|
47
49
|
ble: { type: 'boolean' },
|
|
50
|
+
'ble-logs': { type: 'boolean' },
|
|
48
51
|
usb: { type: 'boolean' },
|
|
49
52
|
out: { type: 'string' },
|
|
50
53
|
reboot: { type: 'boolean' },
|
|
@@ -74,8 +77,10 @@ const keyStore = (board) => {
|
|
|
74
77
|
return { key: k.key, created: k.created }
|
|
75
78
|
}
|
|
76
79
|
|
|
80
|
+
export const NO_CABLE_BLE_LOG = 'No USB cable: the app log comes over Bluetooth (plug in a cable for crashes and resets).'
|
|
81
|
+
|
|
77
82
|
/** The USB serial log, when there is (or must be) one. */
|
|
78
|
-
async function openSerial(a, ui, onLine) {
|
|
83
|
+
async function openSerial(a, ui, onLine, { quiet = false } = {}) {
|
|
79
84
|
if (a.ble) return null
|
|
80
85
|
let port = a.port && a.port !== 'auto' ? a.port : null
|
|
81
86
|
try {
|
|
@@ -89,7 +94,7 @@ async function openSerial(a, ui, onLine) {
|
|
|
89
94
|
return null
|
|
90
95
|
} else if (a.usb) throw new KamojiError('usb', 'No Kamoji on USB.', 'Plug it in with a USB-C data cable, or pass --port.')
|
|
91
96
|
else {
|
|
92
|
-
|
|
97
|
+
if (!quiet) ui.info(NO_CABLE_BLE_LOG)
|
|
93
98
|
return null
|
|
94
99
|
}
|
|
95
100
|
}
|
|
@@ -158,7 +163,13 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
158
163
|
keys: keyStore,
|
|
159
164
|
reboot: !!a.reboot,
|
|
160
165
|
lua: !a['no-lua'],
|
|
166
|
+
bleLogs: !!a['ble-logs'],
|
|
161
167
|
})
|
|
168
|
+
// The app log over Bluetooth (firmware 0.3.3) when there is no USB log, or with --ble-logs.
|
|
169
|
+
const useSerial = async (onLine) => {
|
|
170
|
+
dev.serial = await openSerial(a, ui, onLine)
|
|
171
|
+
if (!dev.serial) dev.bleLogs = true
|
|
172
|
+
}
|
|
162
173
|
const shotsDir = path.resolve(a.out ?? 'kamoji-shots')
|
|
163
174
|
let code = 0
|
|
164
175
|
const stop = async (c) => {
|
|
@@ -171,9 +182,16 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
171
182
|
})
|
|
172
183
|
try {
|
|
173
184
|
if (cmd === 'logs') {
|
|
174
|
-
if (a.ble) throw new KamojiError('usb', 'kamoji logs reads the USB log: drop --ble.')
|
|
175
185
|
dev.appId = a.app ?? null
|
|
176
|
-
dev.
|
|
186
|
+
dev.reopen = false
|
|
187
|
+
if (!a.ble) dev.serial = await openSerial(a, ui, (l) => dev.logLine(l), { quiet: true })
|
|
188
|
+
if (!dev.serial || a['ble-logs']) {
|
|
189
|
+
if (!dev.serial && !a.ble) ui.info('No USB cable: Kamoji\'s app log over Bluetooth (crashes and resets need the cable).')
|
|
190
|
+
dev.bleLogs = true
|
|
191
|
+
dev.watching = true // reconnect when the link drops
|
|
192
|
+
await dev.connect()
|
|
193
|
+
if (dev.notes.has('no-ble-log')) throw new KamojiError('unsupported', 'No log over Bluetooth on this firmware.', 'Plug in a USB-C data cable and run kamoji logs again.')
|
|
194
|
+
}
|
|
177
195
|
if (!dev.appId && !a.verbose) ui.info('Showing app lines, errors and crashes; add --verbose for every line, --app <id> to follow one app.')
|
|
178
196
|
await new Promise(() => undefined) // until Ctrl-C
|
|
179
197
|
}
|
|
@@ -183,11 +201,11 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
183
201
|
for (const app of list.apps)
|
|
184
202
|
ui.info(
|
|
185
203
|
`${app.ok ? `mode ${String(list.modes[app.id]).padEnd(3)}` : 'cannot run'} ${app.id} ${app.version} ${app.name}` +
|
|
186
|
-
`${app.bytes !== undefined ? ` ${kb(app.bytes)}` : ''}${app.reason ? ` (${app.reason})` : ''}`,
|
|
204
|
+
`${app.bytes === null ? ' ? KB' : app.bytes !== undefined ? ` ${kb(app.bytes)}` : ''}${app.reason ? ` (${app.reason})` : ''}`,
|
|
187
205
|
)
|
|
188
206
|
if (!list.apps.length) ui.info('No mini apps on this Kamoji.')
|
|
189
207
|
} else if (cmd === 'shot') {
|
|
190
|
-
dev.serial = await openSerial(a, ui, () => undefined)
|
|
208
|
+
dev.serial = await openSerial(a, ui, () => undefined, { quiet: true })
|
|
191
209
|
await dev.screenshot(shotsDir)
|
|
192
210
|
} else if (cmd === 'forget') {
|
|
193
211
|
await dev.connect()
|
|
@@ -196,11 +214,11 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
196
214
|
deleteKey(dev.conn.board)
|
|
197
215
|
ui.ok(left >= 0 ? `Kamoji forgot this computer (${left} trusted device(s) left); key deleted.` : 'Kamoji did not know this key; key deleted.')
|
|
198
216
|
} else if (cmd === 'install' || (cmd === 'dev' && a.once)) {
|
|
199
|
-
|
|
217
|
+
await useSerial((l) => dev.logLine(l))
|
|
200
218
|
code = (await dev.deploy({ force: true })) ? 0 : 1
|
|
201
|
-
if (code === 0 && dev.serial) await new Promise((r) => setTimeout(r, 3000)) // the app's first log lines
|
|
219
|
+
if (code === 0 && (dev.serial || dev.logsOn !== null)) await new Promise((r) => setTimeout(r, 3000)) // the app's first log lines
|
|
202
220
|
} else if (cmd === 'dev') {
|
|
203
|
-
code = await watchLoop(dev, a, ui, folder, shotsDir)
|
|
221
|
+
code = await watchLoop(dev, a, ui, folder, shotsDir, useSerial)
|
|
204
222
|
}
|
|
205
223
|
} catch (e) {
|
|
206
224
|
if (e instanceof KamojiError) ui.error(e.message, e.hint)
|
|
@@ -210,13 +228,16 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
210
228
|
await stop(code)
|
|
211
229
|
}
|
|
212
230
|
|
|
213
|
-
async function watchLoop(dev, a, ui, folder, shotsDir) {
|
|
231
|
+
async function watchLoop(dev, a, ui, folder, shotsDir, useSerial) {
|
|
214
232
|
const { Reloader, watchFolder } = await import('./watch.js')
|
|
215
233
|
dev.watching = true
|
|
216
|
-
|
|
234
|
+
await useSerial((l) => dev.logLine(l))
|
|
235
|
+
let full = false
|
|
217
236
|
const reload = new Reloader(async () => {
|
|
218
237
|
try {
|
|
219
|
-
|
|
238
|
+
const all = full
|
|
239
|
+
full = false
|
|
240
|
+
await dev.deploy({ full: all })
|
|
220
241
|
} catch (e) {
|
|
221
242
|
if (e instanceof KamojiError) ui.error(e.message, e.hint)
|
|
222
243
|
else ui.error(e?.message ?? String(e))
|
|
@@ -240,6 +261,7 @@ async function watchLoop(dev, a, ui, folder, shotsDir) {
|
|
|
240
261
|
try {
|
|
241
262
|
if (k === '' || k === 'r') {
|
|
242
263
|
dev.lastHash = null
|
|
264
|
+
full = true // Enter: every file, not only the changed ones
|
|
243
265
|
await reload.fire()
|
|
244
266
|
} else if (k === 'o') {
|
|
245
267
|
await dev.connect()
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// Bytes without Node's Buffer, so the protocol core runs in a browser too (the web IDE on
|
|
2
|
+
// developer.kamoji.bot). Node's Buffer is a Uint8Array, so everything here takes Buffers as well.
|
|
3
|
+
|
|
4
|
+
const enc = new TextEncoder()
|
|
5
|
+
const dec = new TextDecoder()
|
|
6
|
+
|
|
7
|
+
/** @param {string} s @returns {Uint8Array} */
|
|
8
|
+
export const utf8 = (s) => enc.encode(s)
|
|
9
|
+
/** @param {Uint8Array} b @returns {string} */
|
|
10
|
+
export const fromUtf8 = (b) => dec.decode(b)
|
|
11
|
+
|
|
12
|
+
/** @param {Uint8Array} b @returns {string} lowercase hex */
|
|
13
|
+
export function toHex(b) {
|
|
14
|
+
let s = ''
|
|
15
|
+
for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, '0')
|
|
16
|
+
return s
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** @param {string} hex @returns {Uint8Array} (stops at the first non-hex pair, like Buffer.from(hex, 'hex')) */
|
|
20
|
+
export function fromHex(hex) {
|
|
21
|
+
const out = new Uint8Array(Math.floor(hex.length / 2))
|
|
22
|
+
let n = 0
|
|
23
|
+
for (; n < out.length; n++) {
|
|
24
|
+
const v = parseInt(hex.substr(n * 2, 2), 16)
|
|
25
|
+
if (Number.isNaN(v) || !/^[0-9a-fA-F]{2}$/.test(hex.substr(n * 2, 2))) break
|
|
26
|
+
out[n] = v
|
|
27
|
+
}
|
|
28
|
+
return out.subarray(0, n)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** @param {string} b64 @returns {Uint8Array} */
|
|
32
|
+
export function fromBase64(b64) {
|
|
33
|
+
const bin = atob(b64.replace(/[^A-Za-z0-9+/=]/g, ''))
|
|
34
|
+
const out = new Uint8Array(bin.length)
|
|
35
|
+
for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
|
|
36
|
+
return out
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** @param {Uint8Array[]} parts */
|
|
40
|
+
export function concat(parts) {
|
|
41
|
+
const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
|
|
42
|
+
let o = 0
|
|
43
|
+
for (const p of parts) {
|
|
44
|
+
out.set(p, o)
|
|
45
|
+
o += p.length
|
|
46
|
+
}
|
|
47
|
+
return out
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// ------------------------------------------------------------------ MD5 (RFC 1321)
|
|
51
|
+
// The install protocol names every file by its md5; WebCrypto has no MD5.
|
|
52
|
+
|
|
53
|
+
const S = [7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
|
|
54
|
+
4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21]
|
|
55
|
+
const K = Array.from({ length: 64 }, (_, i) => Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32) >>> 0)
|
|
56
|
+
|
|
57
|
+
/** @param {Uint8Array|string} input (a string is UTF-8) @returns {string} lowercase hex */
|
|
58
|
+
export function md5Hex(input) {
|
|
59
|
+
const data = typeof input === 'string' ? utf8(input) : input
|
|
60
|
+
const len = data.length
|
|
61
|
+
const padded = new Uint8Array(((len + 8) >>> 6 << 6) + 64)
|
|
62
|
+
padded.set(data)
|
|
63
|
+
padded[len] = 0x80
|
|
64
|
+
const dv = new DataView(padded.buffer)
|
|
65
|
+
dv.setUint32(padded.length - 8, (len * 8) >>> 0, true)
|
|
66
|
+
dv.setUint32(padded.length - 4, Math.floor(len / 0x20000000), true)
|
|
67
|
+
let a0 = 0x67452301
|
|
68
|
+
let b0 = 0xefcdab89
|
|
69
|
+
let c0 = 0x98badcfe
|
|
70
|
+
let d0 = 0x10325476
|
|
71
|
+
const M = new Uint32Array(16)
|
|
72
|
+
for (let off = 0; off < padded.length; off += 64) {
|
|
73
|
+
for (let i = 0; i < 16; i++) M[i] = dv.getUint32(off + i * 4, true)
|
|
74
|
+
let A = a0
|
|
75
|
+
let B = b0
|
|
76
|
+
let C = c0
|
|
77
|
+
let D = d0
|
|
78
|
+
for (let i = 0; i < 64; i++) {
|
|
79
|
+
let F
|
|
80
|
+
let g
|
|
81
|
+
if (i < 16) {
|
|
82
|
+
F = (B & C) | (~B & D)
|
|
83
|
+
g = i
|
|
84
|
+
} else if (i < 32) {
|
|
85
|
+
F = (D & B) | (~D & C)
|
|
86
|
+
g = (5 * i + 1) % 16
|
|
87
|
+
} else if (i < 48) {
|
|
88
|
+
F = B ^ C ^ D
|
|
89
|
+
g = (3 * i + 5) % 16
|
|
90
|
+
} else {
|
|
91
|
+
F = C ^ (B | ~D)
|
|
92
|
+
g = (7 * i) % 16
|
|
93
|
+
}
|
|
94
|
+
F = (F + A + K[i] + M[g]) >>> 0
|
|
95
|
+
A = D
|
|
96
|
+
D = C
|
|
97
|
+
C = B
|
|
98
|
+
B = (B + ((F << S[i]) | (F >>> (32 - S[i])))) >>> 0
|
|
99
|
+
}
|
|
100
|
+
a0 = (a0 + A) >>> 0
|
|
101
|
+
b0 = (b0 + B) >>> 0
|
|
102
|
+
c0 = (c0 + C) >>> 0
|
|
103
|
+
d0 = (d0 + D) >>> 0
|
|
104
|
+
}
|
|
105
|
+
const out = new Uint8Array(16)
|
|
106
|
+
const ov = new DataView(out.buffer)
|
|
107
|
+
ov.setUint32(0, a0, true)
|
|
108
|
+
ov.setUint32(4, b0, true)
|
|
109
|
+
ov.setUint32(8, c0, true)
|
|
110
|
+
ov.setUint32(12, d0, true)
|
|
111
|
+
return toHex(out)
|
|
112
|
+
}
|