kamoji-dev 0.0.0-stage → 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/src/cli.js ADDED
@@ -0,0 +1,293 @@
1
+ // kamoji: develop Kamoji Mini Apps on your own Kamoji. See README.md.
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+ import readline from 'node:readline'
5
+ import { parseArgs } from 'node:util'
6
+ import { chooseKamoji, connect, loadNoble, poweredOn, scan } from './ble.js'
7
+ import { checkApp } from './check.js'
8
+ import { DevSession, kb, makeUi, printProblems } from './dev.js'
9
+ import { deleteKey, keyPath, loadOrCreateKey } from './keys.js'
10
+ import { KamojiError, Session } from './protocol.js'
11
+ import { SerialLog, findPorts } from './serial.js'
12
+
13
+ const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
14
+
15
+ export const HELP = `kamoji ${VERSION}: develop Kamoji Mini Apps on your own Kamoji
16
+
17
+ Usage:
18
+ kamoji dev <folder> check, install over Bluetooth and open the app, then again on every save
19
+ kamoji install <folder> check, install and open once
20
+ kamoji check <folder> only check the folder (manifest, layout, Lua) like the Mini Apps store
21
+ kamoji apps list the mini apps on Kamoji
22
+ kamoji shot save a screenshot of Kamoji's screen
23
+ kamoji logs show Kamoji's log (USB; over Bluetooth without a cable, or with --ble)
24
+ kamoji forget make Kamoji forget this computer, and delete its key
25
+
26
+ Options:
27
+ --device KMJ-XXXX which Kamoji (needed when several are near)
28
+ --port PATH USB serial port for the log (default: found by itself)
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)
31
+ --usb require the USB cable (log and screenshots over USB)
32
+ --out DIR where screenshots go (default: ./kamoji-shots)
33
+ --reboot restart Kamoji by itself when the app's Bluetooth services need it
34
+ --app ID (logs) only this app's lines
35
+ --verbose every USB log line, and more detail
36
+ --no-lua don't run luac
37
+ --json (check) print the result as JSON
38
+
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.
41
+
42
+ Before you start: disconnect the Kamoji app on your phone (Kamoji takes one Bluetooth connection at
43
+ a time). The first time, keep the computer right next to Kamoji: it then trusts this computer (key in
44
+ ${keyPath('KMJ-XXXX').replace(/KMJ-XXXX\.key$/, '<board>.key')}).`
45
+
46
+ const OPTIONS = {
47
+ device: { type: 'string' },
48
+ port: { type: 'string' },
49
+ ble: { type: 'boolean' },
50
+ 'ble-logs': { type: 'boolean' },
51
+ usb: { type: 'boolean' },
52
+ out: { type: 'string' },
53
+ reboot: { type: 'boolean' },
54
+ app: { type: 'string' },
55
+ verbose: { type: 'boolean', short: 'v' },
56
+ 'no-lua': { type: 'boolean' },
57
+ json: { type: 'boolean' },
58
+ once: { type: 'boolean' },
59
+ help: { type: 'boolean', short: 'h' },
60
+ version: { type: 'boolean' },
61
+ }
62
+
63
+ /** The Bluetooth connector used by DevSession. */
64
+ export function bleConnector(device, ui) {
65
+ return async ({ onDisconnect }) => {
66
+ const noble = await loadNoble()
67
+ await poweredOn(noble)
68
+ const seen = await scan(noble, { want: device, ms: device ? 30000 : 10000, ui })
69
+ const d = chooseKamoji(seen, device)
70
+ const link = await connect(d, { onDisconnect })
71
+ return { link, board: d.name ?? d.id, name: d.name, revision: d.revision, firmware: d.firmware }
72
+ }
73
+ }
74
+
75
+ const keyStore = (board) => {
76
+ const k = loadOrCreateKey(board)
77
+ return { key: k.key, created: k.created }
78
+ }
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
+
82
+ /** The USB serial log, when there is (or must be) one. */
83
+ async function openSerial(a, ui, onLine, { quiet = false } = {}) {
84
+ if (a.ble) return null
85
+ let port = a.port && a.port !== 'auto' ? a.port : null
86
+ try {
87
+ if (!port) {
88
+ const ports = await findPorts()
89
+ if (ports.length === 1) port = ports[0]
90
+ else if (ports.length > 1) {
91
+ const msg = `${ports.length} Espressif USB devices (${ports.join(', ')}): pass --port to pick one.`
92
+ if (a.usb) throw new KamojiError('usb', msg)
93
+ ui.warn(`${msg} No USB log for now.`)
94
+ return null
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.')
96
+ else {
97
+ if (!quiet) ui.info(NO_CABLE_BLE_LOG)
98
+ return null
99
+ }
100
+ }
101
+ const s = new SerialLog(port, { onLine })
102
+ await s.start()
103
+ ui.ok(`USB log from ${port}.`)
104
+ return s
105
+ } catch (e) {
106
+ if (a.usb || e instanceof KamojiError) throw e
107
+ ui.warn(`USB log unavailable (${e.message}).`)
108
+ return null
109
+ }
110
+ }
111
+
112
+ export async function main(argv = process.argv.slice(2)) {
113
+ let parsed
114
+ try {
115
+ parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true })
116
+ } catch (e) {
117
+ console.error(`${e.message}\n\n${HELP}`)
118
+ return 2
119
+ }
120
+ const a = parsed.values
121
+ const [cmd, folderArg] = parsed.positionals
122
+ if (a.version) {
123
+ console.log(VERSION)
124
+ return 0
125
+ }
126
+ if (a.help || !cmd || cmd === 'help') {
127
+ console.log(HELP)
128
+ return cmd || a.help ? 0 : 2
129
+ }
130
+ const ui = makeUi({ verbose: !!a.verbose })
131
+ const needsFolder = ['dev', 'install', 'check'].includes(cmd)
132
+ if (needsFolder && !folderArg) {
133
+ ui.error(`kamoji ${cmd} needs the mini app folder, e.g. kamoji ${cmd} ./my-app`)
134
+ return 2
135
+ }
136
+ const folder = folderArg ? path.resolve(folderArg) : null
137
+ if (folder && !fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory()) {
138
+ ui.error(`${folderArg} is not a folder.`, 'Give the folder that holds manifest.json (unzip a .zip first).')
139
+ return 2
140
+ }
141
+
142
+ if (cmd === 'check') {
143
+ const r = checkApp(folder, { lua: !a['no-lua'] })
144
+ if (a.json) console.log(JSON.stringify({ app: r.appId, bytes: r.bytes, files: r.files.length, problems: r.problems }, null, 2))
145
+ else {
146
+ printProblems(ui, r)
147
+ if (!r.errors.length) ui.ok(`${r.appId}: ${r.files.length} file(s), ${kb(r.bytes)}, ${r.warnings.length ? `${r.warnings.length} warning(s)` : 'no problems'}.`)
148
+ else ui.error(`${r.errors.length} problem(s).`)
149
+ }
150
+ return r.errors.length ? 1 : 0
151
+ }
152
+
153
+ if (!['dev', 'install', 'apps', 'shot', 'logs', 'forget'].includes(cmd)) {
154
+ ui.error(`unknown command "${cmd}"`)
155
+ console.log(HELP)
156
+ return 2
157
+ }
158
+
159
+ const dev = new DevSession({
160
+ folder,
161
+ ui,
162
+ connector: bleConnector(a.device, ui),
163
+ keys: keyStore,
164
+ reboot: !!a.reboot,
165
+ lua: !a['no-lua'],
166
+ bleLogs: !!a['ble-logs'],
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
+ }
173
+ const shotsDir = path.resolve(a.out ?? 'kamoji-shots')
174
+ let code = 0
175
+ const stop = async (c) => {
176
+ await dev.close().catch(() => undefined)
177
+ process.exit(c)
178
+ }
179
+ process.on('SIGINT', () => {
180
+ process.stdout.write('\n')
181
+ stop(130)
182
+ })
183
+ try {
184
+ if (cmd === 'logs') {
185
+ dev.appId = a.app ?? null
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
+ }
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.')
196
+ await new Promise(() => undefined) // until Ctrl-C
197
+ }
198
+ if (cmd === 'apps') {
199
+ await dev.connect()
200
+ const list = dev.lastList
201
+ for (const app of list.apps)
202
+ ui.info(
203
+ `${app.ok ? `mode ${String(list.modes[app.id]).padEnd(3)}` : 'cannot run'} ${app.id} ${app.version} ${app.name}` +
204
+ `${app.bytes === null ? ' ? KB' : app.bytes !== undefined ? ` ${kb(app.bytes)}` : ''}${app.reason ? ` (${app.reason})` : ''}`,
205
+ )
206
+ if (!list.apps.length) ui.info('No mini apps on this Kamoji.')
207
+ } else if (cmd === 'shot') {
208
+ dev.serial = await openSerial(a, ui, () => undefined, { quiet: true })
209
+ await dev.screenshot(shotsDir)
210
+ } else if (cmd === 'forget') {
211
+ await dev.connect()
212
+ const { key } = loadOrCreateKey(dev.conn.board)
213
+ const left = await dev.session.forget(key)
214
+ deleteKey(dev.conn.board)
215
+ ui.ok(left >= 0 ? `Kamoji forgot this computer (${left} trusted device(s) left); key deleted.` : 'Kamoji did not know this key; key deleted.')
216
+ } else if (cmd === 'install' || (cmd === 'dev' && a.once)) {
217
+ await useSerial((l) => dev.logLine(l))
218
+ code = (await dev.deploy({ force: true })) ? 0 : 1
219
+ if (code === 0 && (dev.serial || dev.logsOn !== null)) await new Promise((r) => setTimeout(r, 3000)) // the app's first log lines
220
+ } else if (cmd === 'dev') {
221
+ code = await watchLoop(dev, a, ui, folder, shotsDir, useSerial)
222
+ }
223
+ } catch (e) {
224
+ if (e instanceof KamojiError) ui.error(e.message, e.hint)
225
+ else ui.error(e?.stack ?? String(e))
226
+ code = 1
227
+ }
228
+ await stop(code)
229
+ }
230
+
231
+ async function watchLoop(dev, a, ui, folder, shotsDir, useSerial) {
232
+ const { Reloader, watchFolder } = await import('./watch.js')
233
+ dev.watching = true
234
+ await useSerial((l) => dev.logLine(l))
235
+ let full = false
236
+ const reload = new Reloader(async () => {
237
+ try {
238
+ const all = full
239
+ full = false
240
+ await dev.deploy({ full: all })
241
+ } catch (e) {
242
+ if (e instanceof KamojiError) ui.error(e.message, e.hint)
243
+ else ui.error(e?.message ?? String(e))
244
+ }
245
+ })
246
+ await reload.fire()
247
+ watchFolder(folder, () => reload.trigger())
248
+ ui.info(`Watching ${folder}: save a file to reload. Enter = install again, o = open, s = screenshot, b = restart Kamoji, q = quit.`)
249
+ // Keys: single keypresses in a terminal (no Enter needed); one line per command when stdin is a pipe
250
+ // (KAMOJI_KEYS, scripts and tests). q / Ctrl-C always quit, even during an install.
251
+ let busy = Promise.resolve()
252
+ const quit = async () => {
253
+ ui.info('Bye.')
254
+ await Promise.race([dev.close().catch(() => undefined), new Promise((r) => setTimeout(r, 2000))])
255
+ if (process.stdin.isTTY) process.stdin.setRawMode(false)
256
+ process.exit(0)
257
+ }
258
+ const handle = (k) => {
259
+ if (k === 'q') return quit()
260
+ busy = busy.then(async () => {
261
+ try {
262
+ if (k === '' || k === 'r') {
263
+ dev.lastHash = null
264
+ full = true // Enter: every file, not only the changed ones
265
+ await reload.fire()
266
+ } else if (k === 'o') {
267
+ await dev.connect()
268
+ await dev.open()
269
+ } else if (k === 's') await dev.screenshot(shotsDir)
270
+ else if (k === 'b') {
271
+ await dev.connect()
272
+ ui.info('Restarting Kamoji…')
273
+ await dev.restart()
274
+ } else ui.info('Enter = install again, o = open, s = screenshot, b = restart Kamoji, q = quit.')
275
+ } catch (e) {
276
+ ui.error(e?.message ?? String(e), e?.hint)
277
+ }
278
+ })
279
+ }
280
+ if (process.stdin.isTTY && !process.env.KAMOJI_KEYS) {
281
+ readline.emitKeypressEvents(process.stdin)
282
+ process.stdin.setRawMode(true)
283
+ process.stdin.on('keypress', (str, key) => {
284
+ if (key?.ctrl && (key.name === 'c' || key.name === 'd')) return void quit()
285
+ if (key?.name === 'return' || key?.name === 'enter') return void handle('')
286
+ if (typeof str === 'string' && str.length === 1) handle(str.toLowerCase())
287
+ })
288
+ } else if (process.env.KAMOJI_KEYS) {
289
+ const rl = readline.createInterface({ input: process.stdin })
290
+ rl.on('line', (line) => handle(line.trim().toLowerCase()))
291
+ }
292
+ return new Promise(() => undefined) // until q or Ctrl-C
293
+ }
@@ -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
+ }
@@ -0,0 +1,222 @@
1
+ // The checks of a mini app before it is sent: the rules and their ids are in ../../spec/VALIDATION.md
2
+ // (shared with the Python worker/rig/kamoji_dev.py of kamoji-cms). Environment-neutral: the command line
3
+ // (../check.js reads a folder and runs luac) and the web IDE on developer.kamoji.bot use it.
4
+ //
5
+ // Copied from kamoji-cms src/utils/appBundle.ts (APP_ID_RE, SEMVER_RE, APP_PERMISSIONS, APP_FEATURES,
6
+ // APP_PLATFORMS, BUNDLE_LIMITS, checkAppPath) because this package is published on its own: keep both
7
+ // in step when the store's rules change.
8
+ import { fromUtf8, md5Hex, utf8 } from './bytes.js'
9
+
10
+ export const APP_ID_RE = /^[a-z0-9][a-z0-9-]{1,39}$/
11
+ export const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
12
+ export const VERSION_RE = /^v?\d+(\.\d+){1,3}(-[0-9A-Za-z.-]+)?$/
13
+ export const APP_PERMISSIONS = [
14
+ 'sensors.imu', 'sensors.light', 'sensors.mic', 'sensors.env', 'sensors.obd', 'events.drive', 'events.device',
15
+ 'touch', 'net.http', 'net.mqtt', 'net.phone', 'phone.navigation', 'ble.gatt',
16
+ ]
17
+ export const APP_FEATURES = ['gyro', 'temperature', 'light', 'microphone', 'fft', 'wifi', 'ble', 'gatt', 'mqtt', 'http', 'time', 'rgb_leds']
18
+ export const APP_PLATFORMS = ['android', 'ios']
19
+ export const PARAM_TYPES = ['number', 'bool', 'string', 'enum', 'color', 'secret']
20
+ export const WIDGET_TYPES = ['label', 'rect', 'circle', 'arc', 'bar', 'line', 'polyline', 'bitmap', 'chart', 'image']
21
+ export const ALIGNS = ['center', 'top_left', 'top_mid', 'top_right', 'left_mid', 'right_mid', 'bottom_left', 'bottom_mid', 'bottom_right']
22
+ export const LIMITS = { maxTotalBytes: 2 * 1024 * 1024, maxFiles: 64, maxPathBytes: 63, maxDepth: 3, maxManifestBytes: 16384 }
23
+
24
+ const SKIP_NAMES = new Set(['.DS_Store', 'Thumbs.db', '__MACOSX', 'node_modules', '4913'])
25
+
26
+ /** Files an editor or the OS leaves next to the real ones: never sent. */
27
+ export function isJunk(name) {
28
+ return (
29
+ name.startsWith('.') || SKIP_NAMES.has(name) || name.endsWith('~') || /\.(swp|swo|swx|tmp)$/i.test(name) ||
30
+ /^#.*#$/.test(name)
31
+ )
32
+ }
33
+
34
+ /** Same as the store's checkAppPath: an error message, or null. */
35
+ export function checkAppPath(p) {
36
+ if (!p) return 'empty path'
37
+ if (p.startsWith('/') || /^[a-zA-Z]:/.test(p)) return `absolute path not allowed: ${p}`
38
+ if (p.includes('\\')) return `backslash in path: ${p}`
39
+ if (/[\x00-\x1f\x7f]/.test(p)) return `control character in path: ${JSON.stringify(p)}`
40
+ const segments = p.split('/')
41
+ for (const s of segments) {
42
+ if (s === '') return `empty path segment: ${p}`
43
+ if (s === '..' || s === '.') return `relative segment not allowed: ${p}`
44
+ if (s.startsWith('.')) return `names starting with "." are not allowed: ${p}`
45
+ }
46
+ if (utf8(p).length > LIMITS.maxPathBytes) return `path longer than ${LIMITS.maxPathBytes} bytes: ${p}`
47
+ if (segments.length > LIMITS.maxDepth) return `path deeper than ${LIMITS.maxDepth} levels: ${p}`
48
+ return null
49
+ }
50
+
51
+ /** Version compare like the firmware checks: 0.3.10 > 0.3.9, a release after its -rc. */
52
+ export function compareVersions(a, b) {
53
+ const parse = (v) => {
54
+ const m = /^v?(\d+(?:\.\d+)*)(?:-(.*))?$/.exec(String(v ?? '').trim())
55
+ if (!m) return [[0, 0, 0, 0], '']
56
+ const nums = [...m[1].split('.').map(Number), 0, 0, 0, 0].slice(0, 4)
57
+ return [nums, m[2] ?? '~']
58
+ }
59
+ const [na, pa] = parse(a)
60
+ const [nb, pb] = parse(b)
61
+ for (let i = 0; i < 4; i++) if (na[i] !== nb[i]) return na[i] < nb[i] ? -1 : 1
62
+ return pa === pb ? 0 : pa < pb ? -1 : 1
63
+ }
64
+
65
+ function checkLayout(file, add) {
66
+ let layout
67
+ try {
68
+ layout = JSON.parse(fromUtf8(file.data).replace(/^/, ''))
69
+ } catch (e) {
70
+ add('error', 'layout-json', `not valid JSON: ${e.message}`, file.path)
71
+ return
72
+ }
73
+ let widgets
74
+ if (Array.isArray(layout)) widgets = layout
75
+ else if (layout && typeof layout === 'object' && Array.isArray(layout.widgets)) widgets = layout.widgets
76
+ else {
77
+ add('error', 'layout-shape', 'must be an array of widgets, or an object with a "widgets" array', file.path)
78
+ return
79
+ }
80
+ widgets.forEach((w, i) => {
81
+ const where = `${file.path} widget ${i + 1}`
82
+ if (!w || typeof w !== 'object' || Array.isArray(w)) {
83
+ add('warning', 'widget-type', 'not an object (skipped by Kamoji)', where)
84
+ return
85
+ }
86
+ if (!WIDGET_TYPES.includes(w.type))
87
+ add('warning', 'widget-type', `type ${JSON.stringify(w.type)} is not a widget Kamoji draws (${WIDGET_TYPES.join(', ')})`, where)
88
+ if (w.align !== undefined && !ALIGNS.includes(w.align)) add('warning', 'align', `align ${JSON.stringify(w.align)} is not one of ${ALIGNS.join(', ')}`, where)
89
+ for (const [k, v] of Object.entries(w)) {
90
+ if (typeof v === 'string' && v.split('{{').length - 1 > v.split('}}').length - 1)
91
+ add('warning', 'binding-braces', `"${k}" opens {{ without closing }}`, where)
92
+ }
93
+ })
94
+ if (!Array.isArray(layout) && layout.on !== undefined) {
95
+ if (!layout.on || typeof layout.on !== 'object' || Array.isArray(layout.on)) add('error', 'layout-on', '"on" must be an object', file.path)
96
+ else
97
+ for (const [k, v] of Object.entries(layout.on))
98
+ if (typeof v !== 'string') add('error', 'layout-on', `"on.${k}" must be a string of Lua statements`, file.path)
99
+ }
100
+ }
101
+
102
+ function checkManifest(m, folderName, add) {
103
+ const where = 'manifest.json'
104
+ if (typeof m.id !== 'string' || !APP_ID_RE.test(m.id))
105
+ add('error', 'id', '"id": lowercase letters, digits and "-", starting with a letter or digit, 2 to 40 characters', where)
106
+ else if (folderName && m.id !== folderName)
107
+ 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)
108
+ if (typeof m.version !== 'string' || !SEMVER_RE.test(m.version))
109
+ add('error', 'version', '"version" must be a version like 1.0.0 (the store needs it)', where)
110
+ if (m.api_version !== 1) add('error', 'api-version', '"api_version" must be 1', where)
111
+ const perms = m.permissions
112
+ if (perms !== undefined) {
113
+ if (!Array.isArray(perms)) add('error', 'permissions', '"permissions" must be an array', where)
114
+ else {
115
+ const unknown = perms.filter((p) => !APP_PERMISSIONS.includes(p))
116
+ if (unknown.length) add('error', 'permissions', `unknown permissions: ${unknown.join(', ')} (known: ${APP_PERMISSIONS.join(', ')})`, where)
117
+ }
118
+ }
119
+ if (m.features !== undefined) {
120
+ if (!Array.isArray(m.features)) add('error', 'features', '"features" must be an array', where)
121
+ else {
122
+ const unknown = m.features.filter((f) => !APP_FEATURES.includes(f))
123
+ if (unknown.length) add('error', 'features', `unknown features: ${unknown.join(', ')} (known: ${APP_FEATURES.join(', ')})`, where)
124
+ }
125
+ }
126
+ if (m.platforms !== undefined) {
127
+ if (!Array.isArray(m.platforms) || m.platforms.length === 0) add('error', 'platforms', '"platforms" must be a non-empty array', where)
128
+ else {
129
+ const unknown = m.platforms.filter((p) => !APP_PLATFORMS.includes(p))
130
+ if (unknown.length) add('error', 'platforms', `unknown platforms: ${unknown.join(', ')}`, where)
131
+ }
132
+ }
133
+ if (m.min_firmware !== undefined && (typeof m.min_firmware !== 'string' || !VERSION_RE.test(m.min_firmware)))
134
+ add('error', 'min-firmware', '"min_firmware" must be a version string like "0.3.0"', where)
135
+ const has = (p) => Array.isArray(perms) && perms.includes(p)
136
+ if (m.ble !== undefined && !has('ble.gatt')) add('error', 'ble-permission', '"ble" needs the "ble.gatt" permission (Kamoji refuses the install)', where)
137
+ if (m.http !== undefined && !has('net.http')) add('warning', 'http-permission', '"http" without the "net.http" permission: http is nil in Lua', where)
138
+ if ((m.ble !== undefined || m.http !== undefined) &&
139
+ (typeof m.min_firmware !== 'string' || compareVersions(m.min_firmware, '0.3.0') < 0))
140
+ add('warning', 'min-firmware-030', '"ble" and "http" need firmware 0.3.0: set "min_firmware": "0.3.0"', where)
141
+ if (m.params !== undefined) {
142
+ if (!Array.isArray(m.params)) add('error', 'params', '"params" must be an array', where)
143
+ else {
144
+ const seen = new Set()
145
+ m.params.forEach((p, i) => {
146
+ const at = `params[${i}]`
147
+ if (!p || typeof p !== 'object' || Array.isArray(p)) return add('error', 'params', `${at} must be an object`, where)
148
+ if (typeof p.key !== 'string' || !p.key) add('error', 'params', `${at} needs a "key"`, where)
149
+ else if (seen.has(p.key)) add('error', 'params', `${at}: key "${p.key}" is used twice`, where)
150
+ else seen.add(p.key)
151
+ const type = p.type ?? 'string'
152
+ if (!PARAM_TYPES.includes(type)) add('error', 'params', `${at}: type ${JSON.stringify(type)} is not one of ${PARAM_TYPES.join(', ')}`, where)
153
+ if (type === 'enum' && (!Array.isArray(p.options) || p.options.length === 0))
154
+ add('error', 'params', `${at}: an enum needs "options"`, where)
155
+ })
156
+ }
157
+ }
158
+ }
159
+
160
+ /**
161
+ * Check the files of an app (read by the caller: a folder on disk, a zip, the web IDE's editor).
162
+ * Returns { problems:[{level,id,message,where}], errors, warnings, manifest, appId, files, skipped, bytes }.
163
+ * @param {{files:{path:string, data:Uint8Array, md5:string}[], skipped?:string[], folderName?:string|null}} app
164
+ * @param {{luaCheck?: null | ((file, add) => boolean), luaMissing?: string}} [opts] luaCheck: checks one .lua
165
+ * file and returns false when it could not (no compiler); null or absent skips the Lua check altogether.
166
+ * luaMissing: the info line when no file could be checked.
167
+ */
168
+ export function checkFiles({ files, skipped = [], folderName = null }, opts = {}) {
169
+ const problems = []
170
+ const add = (level, id, message, where) => problems.push({ level, id, message, where })
171
+ if (skipped.length) add('info', 'skipped', `not sent: ${skipped.join(', ')}`)
172
+ for (const f of files) {
173
+ const err = checkAppPath(f.path)
174
+ if (err) add('error', 'path', err, f.path)
175
+ }
176
+ if (files.length > LIMITS.maxFiles) add('error', 'too-many-files', `${files.length} files (at most ${LIMITS.maxFiles})`)
177
+ const bytes = files.reduce((n, f) => n + f.data.length, 0)
178
+ if (bytes > LIMITS.maxTotalBytes) add('error', 'too-large', `${Math.ceil(bytes / 1024)} KB (at most 2 MB)`)
179
+
180
+ let manifest = null
181
+ const mf = files.find((f) => f.path === 'manifest.json')
182
+ if (!mf) add('error', 'manifest-missing', 'no manifest.json at the root of the folder')
183
+ else if (mf.data.length > LIMITS.maxManifestBytes) add('error', 'manifest-size', `manifest.json is ${mf.data.length} bytes (at most 16 KB)`, 'manifest.json')
184
+ else {
185
+ try {
186
+ manifest = JSON.parse(fromUtf8(mf.data).replace(/^/, ''))
187
+ if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
188
+ manifest = null
189
+ add('error', 'manifest-json', 'manifest.json must be a JSON object', 'manifest.json')
190
+ }
191
+ } catch (e) {
192
+ add('error', 'manifest-json', `not valid JSON: ${e.message}`, 'manifest.json')
193
+ }
194
+ if (manifest) checkManifest(manifest, folderName, add)
195
+ }
196
+ const layout = files.find((f) => f.path === 'layout.json')
197
+ if (layout) checkLayout(layout, add)
198
+ if (opts.luaCheck) {
199
+ const luaFiles = files.filter((f) => f.path.endsWith('.lua'))
200
+ if (luaFiles.length) {
201
+ let ran = false
202
+ for (const f of luaFiles) ran = opts.luaCheck(f, add) || ran
203
+ if (!ran) add('info', 'lua-missing', opts.luaMissing ?? 'no Lua compiler found: Lua is checked by Kamoji only')
204
+ }
205
+ }
206
+ const appId = manifest && typeof manifest.id === 'string' && APP_ID_RE.test(manifest.id) ? manifest.id : null
207
+ return {
208
+ problems,
209
+ errors: problems.filter((p) => p.level === 'error'),
210
+ warnings: problems.filter((p) => p.level === 'warning'),
211
+ manifest,
212
+ appId,
213
+ files,
214
+ skipped,
215
+ bytes,
216
+ }
217
+ }
218
+
219
+ /** The md5 of the whole set (paths + contents): unchanged files are not sent again. */
220
+ export function bundleHash(files) {
221
+ return md5Hex(files.map((f) => `${f.path}\0${f.md5}`).join('\n'))
222
+ }