@aepyornis/fastboot.ts 0.0.13 → 0.0.15

package/mise.toml

@@ -1,2 +1,2 @@
 [tools]
-node = "22"
+node = "24"

package/package.json

@@ -1,24 +1,20 @@
 {
   "name": "@aepyornis/fastboot.ts",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Fastboot using WebUSB",
   "main": "src/index.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "esbuild src/index.ts --bundle --sourcemap --format=esm --platform=browser --target=chrome121 --outfile=dist/fastboot.js"
+    "type-check": "tsc --noEmit",
+    "build": "tsc --noEmit && esbuild src/index.ts --bundle --sourcemap --format=esm --platform=browser --target=chrome132 --outfile=dist/fastboot.js"
   },
   "keywords": [],
   "author": "Ziggy, Calyx Institute",
   "license": "MIT",
   "devDependencies": {
-    "@eslint/js": "^9.24.0",
     "@types/w3c-web-usb": "^1.0.10",
-    "esbuild": "^0.25.2",
-    "eslint": "^9.24.0",
-    "globals": "^16.0.0",
+    "esbuild": "^0.27.2",
     "prettier": "^3.5.3",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.29.1"
+    "typescript": "^5.8.3"
   },
   "dependencies": {
     "@zip.js/zip.js": "^2.7.60"

package/src/client.ts

@@ -1,7 +1,7 @@
-import { BlobWriter, Entry } from "@zip.js/zip.js"
+import { BlobWriter, type FileEntry } from "@zip.js/zip.js"
 import { IMAGES } from "./images"
 import { parseBlobHeader, splitBlob, fromRaw } from "./sparse"
-import { FastbootDevice, FastbootDeviceError } from "./device"
+import { FastbootDevice } from "./device"
 
 export class FastbootError extends Error {}
 
@@ -17,17 +17,21 @@ interface Logger {
   log(message: string): void
 }
 
+interface KeyValueDict {
+  [key: string]: string
+}
+
 // higher level API to interact with fastboot device
 // translates CLI commands to
 export class FastbootClient {
   fd: FastbootDevice
   logger: Logger
-  var_cache: Object
+  var_cache: KeyValueDict
 
   constructor(usb_device: USBDevice, logger: Logger = window.console) {
     this.fd = new FastbootDevice(usb_device, logger)
     this.logger = logger
-    this.var_cache = {}
+    this.var_cache = {} as KeyValueDict
   }
 
   async getVar(variable: string) {
@@ -72,7 +76,6 @@ export class FastbootClient {
   }
 
   async rebootFastboot() {
-    const serialNumber = this.fd.serialNumber
     this.logger.log("rebooting into fastboot")
     await this.fd.exec("reboot-fastboot")
     await new Promise((resolve) => setTimeout(resolve, 1000))
@@ -83,7 +86,7 @@ export class FastbootClient {
     partition: string,
     blob: Blob,
     slot: "current" | "other" | "a" | "b" = "current",
-    applyVbmeta: boolean = false,
+    applyVbmeta: boolean = false, // TODO: Implement flashing vbmeta
   ) {
     // add _a or _b
     //    !(await this.isUserspace()) ?
@@ -164,7 +167,11 @@ export class FastbootClient {
   }
 
   // run text, typically the contents of fastboot-info.txt
-  async fastbootInfo(entries: Entry[], text: string, wipe: boolean = false) {
+  async fastbootInfo(
+    entries: FileEntry[],
+    text: string,
+    wipe: boolean = false,
+  ) {
     const lines = text
       .split("\n")
       .map((x) => x.trim())
@@ -216,7 +223,12 @@ export class FastbootClient {
           this.logger.log(
             `flashing partition ${partition} with ${filename} from nested zip`,
           )
-          await this.doFlash(partition, blob, slot, applyVbmeta)
+          await this.doFlash(
+            partition!, // TODO: Assert this better
+            blob,
+            slot as "current" | "b" | "a" | "other" | undefined, // TODO: Assert this better
+            applyVbmeta,
+          )
           break
         }
         case "reboot":
@@ -236,7 +248,7 @@ export class FastbootClient {
           }
           break
         case "erase":
-          await this.erase(parts[0])
+          await this.erase(parts[0]!) // TODO: Should not assume parts to at least have 1 ele
           break
         default:
           throw new Error(`unknown command ${command}`)
@@ -244,7 +256,7 @@ export class FastbootClient {
     }
   }
 
-  async updateSuper(entries: Entry[], wipe: boolean) {
+  async updateSuper(entries: FileEntry[], wipe: boolean) {
     const superEmptyImage = entries.find(
       (e) => e.filename === "super_empty.img",
     )
@@ -255,7 +267,10 @@ export class FastbootClient {
     let superName = "super"
     try {
       superName = await this.getVar("super-partition-name")
-    } catch (err) {}
+    } catch (err) {
+      // TODO: Maybe log this error somewhere?
+      void err
+    }
 
     // fastboot-info does this
     // await this.rebootFastboot()
@@ -329,15 +344,15 @@ export class FastbootClient {
 
   // tested on bangkk only
   async getUnlockData() {
-    await client.fd.exec(`oem get_unlock_data`)
+    await this.fd.exec(`oem get_unlock_data`)
 
     let data = ""
 
-    for (let packet of client.fd.session.packets) {
-      if (packet.command) {
+    for (const packet of this.fd.session.packets) {
+      if ("command" in packet) {
         continue
       } else if (packet.status === "INFO") {
-        let message = packet.message.replace("(bootloader)", "").trim()
+        const message = packet.message?.replace("(bootloader)", "").trim()
         if (message === "Unlock data:") {
           continue
         } else {
@@ -363,13 +378,12 @@ export class FastbootClient {
     })
   }
 
-  static async findOrRequestDevice(serialNumber: string): Promise<Void> {
-    for (const device of (await navigator.usb.getDevices())) {
+  static async findOrRequestDevice(serialNumber: string): Promise<USBDevice> {
+    for (const device of await navigator.usb.getDevices()) {
       if (device.serialNumber === serialNumber) {
-	return device
+        return device
       }
     }
     return await FastbootClient.requestUsbDevice()
   }
-
 }

package/src/device.ts

@@ -9,7 +9,7 @@ type ResponsePacket = {
 }
 
 type FastbootSession = {
-  phase: 1 | 2 | 3 | 4 | 5
+  // phase: 1 | 2 | 3 | 4 | 5
   status: null | "OKAY" | "FAIL"
   packets: (CommandPacket | ResponsePacket)[]
 }
@@ -18,6 +18,15 @@ interface Logger {
   log(message: string): void
 }
 
+export class FastbootUsbConnectionError extends Error {
+  constructor(
+    message: string = "Could not find device in navigator.usb.getDevices()",
+  ) {
+    super(message)
+    this.name = "FastbootUsbConnectionError"
+  }
+}
+
 export class FastbootDeviceError extends Error {
   status: string
 
@@ -32,16 +41,22 @@ export class FastbootDeviceError extends Error {
 export class FastbootDevice {
   device: USBDevice
   serialNumber: string;
-  in: USBEndpoint
-  out: USBEndpoint
-  session: FastbootSession | null
+  in!: USBEndpoint
+  out!: USBEndpoint
+  session: FastbootSession
   sessions: FastbootSession[]
   logger: Logger
 
   constructor(device: USBDevice, logger: Logger = window.console) {
+    if (!device.serialNumber) {
+      throw new Error(
+        "Access to USBDevice#serialNumber is necessary but stored only in temporary memory.",
+      )
+    }
+
     this.device = device
-    this.serialNumber = this.device.serialNumber
-    this.session = null
+    this.serialNumber = device.serialNumber
+    this.session = { status: null, packets: [] }
     this.sessions = []
     this.logger = logger
     this.setup()
@@ -51,19 +66,19 @@ export class FastbootDevice {
   setup() {
     if (this.device.configurations.length > 1) {
       console.warn(
-        `device has ${device.configurations.length} configurations. Using the first one.`,
+        `device has ${this.device.configurations.length} configurations. Using the first one.`,
       )
     }
 
     // this.in = this.device.configurations[0].interfaces[0].alternate.endpoints[0]
     const endpoints =
-      this.device.configurations[0].interfaces[0].alternate.endpoints
+      this.device.configurations[0]?.interfaces[0]?.alternate.endpoints
 
-    if (endpoints.length !== 2) {
+    if (endpoints && endpoints.length !== 2) {
       throw new Error("USB Interface must have only 2 endpoints")
     }
 
-    for (const endpoint of endpoints) {
+    for (const endpoint of endpoints ?? []) {
       if (endpoint.direction === "in") {
         this.in = endpoint
       } else if (endpoint.direction === "out") {
@@ -84,49 +99,70 @@ export class FastbootDevice {
 
   // some commands (like "flashing lock") will disconnect the device
   // we have to re-assign this.device after it reconnects
-  async reconnect() {
+  async reconnect(): Promise<boolean> {
     const devices = await navigator.usb.getDevices()
     for (const device of devices) {
       if (device.serialNumber === this.serialNumber) {
+        this.logger.log(`reconnect: Found device ${device.serialNumber}`)
         this.device = device
         this.setup()
         await this.connect()
         return true
       }
     }
-    throw new Error("Could not find device in navigator.usb.getDevices()")
+    throw new FastbootUsbConnectionError()
   }
 
+  // The install requires reboots and it's important we pause the
+  // install and reset the usb device after it reconnects
   async waitForReconnect(): Promise<boolean> {
-    const devices = await navigator.usb.getDevices()
+    try {
+      this.logger.log("waitForReconnect try reconnect()")
+      return await this.reconnect()
+    } catch (e) {
+      console.error(e)
+      this.logger.log("waitForReconnect wait 3 seconds")
+      await new Promise((resolve) => setTimeout(resolve, 3000))
+    }
 
-    if (devices.some(device => device.serialNumber === this.serialNumber)) {
-      this.logger.log(`waitForReconnect: Found device ${this.serialNumber}`)
-      await this.reconnect()
-      return Promise.resolve(true)
-    } else {
-      this.logger.log(`waitForReconnect: Adding navigator.usb event listener`)
-      return new Promise((resolve, reject) => {
-	navigator.usb.addEventListener(
-          "connect",
-          async (event) => {
-            this.logger.log(
-              `waitForReconnect: Device connected ${event.device.productName}`,
-            )
-            try {
-              await this.reconnect()
-              resolve(true)
-            } catch (e) {
-              reject(e)
-            }
-          },
-          { once: true },
-	)
-      })
+    try {
+      return await this.reconnect()
+    } catch (e) {
+      if (e instanceof FastbootUsbConnectionError) {
+        this.logger.log("waitForReconnect wait 30 seconds")
+        await new Promise((resolve) => setTimeout(resolve, 30000))
+      } else {
+        throw e
+      }
+    }
+
+    // try once more then wait for navigator.usb connect event
+    try {
+      return await this.reconnect()
+    } catch (e) {
+      if (e instanceof FastbootUsbConnectionError) {
+        return new Promise((resolve, reject) => {
+          this.logger.log("adding navigator.usb connect listener")
+          navigator.usb.addEventListener(
+            "connect",
+            async () => {
+              try {
+                await this.reconnect()
+                resolve(true)
+              } catch (e) {
+                reject(e)
+              }
+            },
+            { once: true },
+          )
+        })
+      }
     }
+
+    return false // TODO: Assume that return false if all else fails
   }
 
-  async getPacket(): ResponsePacket {
+  async getPacket(): Promise<ResponsePacket> {
     this.logger.log(`receiving packet from endpoint ${this.in.endpointNumber}`)
     const inPacket = await this.device.transferIn(this.in.endpointNumber, 256)
     const inPacketText = new TextDecoder().decode(inPacket.data)
@@ -163,40 +199,39 @@ export class FastbootDevice {
     } while (["INFO", "TEXT"].includes(response.status))
   }
 
-  async sendCommand(text): ResponsePacket {
+  async sendCommand(text: string): Promise<ResponsePacket> {
     this.session.packets.push({ command: text } as CommandPacket)
     const outPacket = new TextEncoder().encode(text)
     this.logger.log(
       `transfering "${text}" to endpoint ${this.out.endpointNumber}`,
     )
-    const result: USBOutTransferResult = await this.device.transferOut(
-      this.out.endpointNumber,
-      outPacket,
-    )
+    await this.device.transferOut(this.out.endpointNumber, outPacket)
+
     await this.getPackets()
 
-    if (this.lastPacket.status === "FAIL") {
+    if (
+      this.lastPacket &&
+      "status" in this.lastPacket &&
+      this.lastPacket.status === "FAIL"
+    ) {
       this.session.status = "FAIL"
       throw new FastbootDeviceError(
         this.lastPacket.status,
-        this.lastPacket.message,
+        this.lastPacket.message ?? "",
       )
     } else {
-      return this.lastPacket
+      return this.lastPacket as ResponsePacket // TODO: Fix bad assertion
     }
   }
 
-  async exec(command): ResponsePacket {
+  async exec(command: string): Promise<ResponsePacket> {
     if (this.isActive) {
       throw new Error("fastboot device is busy")
     } else if (!this.device.opened) {
       await this.connect()
     }
 
-    if (this.session) {
-      this.sessions.push(this.session)
-    }
-
+    this.sessions.push(this.session)
     this.session = { status: null, packets: [] }
 
     return this.sendCommand(command)
@@ -204,22 +239,31 @@ export class FastbootDevice {
 
   async getVar(variable: string): Promise<string> {
     await this.exec(`getvar:${variable}`)
-    return this.lastPacket.message
+
+    if (this.lastPacket && "message" in this.lastPacket) {
+      return this.lastPacket.message ?? ""
+    }
+    return ""
   }
 
   get lastPacket() {
-    if (!this.session || this.session.packets.length === 0) {
+    if (this.session.packets.length === 0) {
       return null
+    } else {
+      return this.session.packets[this.session.packets.length - 1]
     }
-    return this.session.packets[this.session.packets.length - 1]
   }
 
   get isActive() {
-    if (!this.session || this.session.packets.length === 0) {
+    if (this.session.packets.length === 0) {
       return false
+    } else {
+      return (
+        this.lastPacket &&
+        "status" in this.lastPacket &&
+        !["FAIL", "OKAY"].includes(this.lastPacket.status)
+      )
     }
-
-    return !["FAIL", "OKAY"].includes(this.lastPacket.status)
   }
 
   // send buffer to phone

package/src/flasher.ts

@@ -3,7 +3,7 @@ import {
   BlobReader,
   BlobWriter,
   TextWriter,
-  Entry,
+  type FileEntry,
 } from "@zip.js/zip.js"
 import type { FastbootClient } from "./client"
 
@@ -21,15 +21,66 @@ type CommandName =
   | "continue"
   | "reboot"
   | "reboot-bootloader"
+  | "sleep"
+  | "oem"
   | "help"
 
+type SlotName = "current" | "other" | "a" | "b"
+
+type InstructionOptions = {
+  wipe?: boolean
+  setActive?: "other" | "a" | "b"
+  slot?: SlotName
+  skipReboot?: boolean
+  applyVbmeta?: boolean
+}
+
 type Instruction = {
   command: CommandName
   args: string[]
-  options: object
+  options: InstructionOptions
+}
+
+const COMMAND_NAMES: ReadonlySet<string> = new Set([
+  "update",
+  "flashall",
+  "flash",
+  "flashing",
+  "erase",
+  "format",
+  "getvar",
+  "set_active",
+  "boot",
+  "devices",
+  "continue",
+  "reboot",
+  "reboot-bootloader",
+  "sleep",
+  "oem",
+  "help",
+])
+
+function isCommandName(word: string): word is CommandName {
+  return COMMAND_NAMES.has(word)
+}
+
+function isFileEntry(entry: { directory: boolean }): entry is FileEntry {
+  return !entry.directory
+}
+
+function requireArg(
+  command: CommandName,
+  args: string[],
+  index: number,
+): string {
+  const value = args[index]
+  if (!value) {
+    throw new Error(`Missing argument ${index + 1} for ${command}`)
+  }
+  return value
 }
 
-function getEntry(entries: Entry[], filename: string): Entry {
+function getEntry(entries: FileEntry[], filename: string): FileEntry {
   const entry = entries.find(
     (e) => e.filename.split(/[\\/]/).pop() === filename,
   )
@@ -45,11 +96,14 @@ function parseInstruction(text: string): Instruction {
     text = text.slice(8).trim()
   }
 
-  let command: CommandName
-  const args = []
-  const options = {}
+  let command: CommandName | undefined
+  const args: string[] = []
+  const options: InstructionOptions = {}
 
-  const words = text.split(" ").map((x) => x.trim())
+  const words = text
+    .split(/\s+/)
+    .map((x) => x.trim())
+    .filter((x) => x !== "")
 
   for (const word of words) {
     if (word[0] === "-") {
@@ -58,15 +112,21 @@ function parseInstruction(text: string): Instruction {
       } else if (word === "--set-active=other") {
         options.setActive = "other"
       } else if (word === "--set-active=a" || word === "--set-active=b") {
-	options.setActive = word.slice(-1)
+        const slot = word.slice(-1)
+        if (slot === "a" || slot === "b") {
+          options.setActive = slot
+        }
       } else if (word === "--slot-other") {
         options.slot = "other"
       } else if (word.slice(0, 6) === "--slot") {
         const slot = word.split("=")[1]
+        if (!slot) {
+          throw new Error("--slot requires a value")
+        }
         if (!["current", "other", "a", "b"].includes(slot)) {
           throw new Error(`unknown slot: ${slot}`)
         }
-        options.slot = slot
+        options.slot = slot as SlotName
       } else if (word === "--skip-reboot") {
         options.skipReboot = true
       } else if (word === "--apply-vbmeta") {
@@ -78,10 +138,16 @@ function parseInstruction(text: string): Instruction {
       if (command) {
         args.push(word)
       } else {
+        if (!isCommandName(word)) {
+          throw new Error(`Unknown command: ${word}`)
+        }
         command = word
       }
     }
   }
+  if (!command) {
+    throw new Error("Missing command")
+  }
   return { command, args, options }
 }
 
@@ -96,7 +162,7 @@ function parseInstructions(text: string): Instruction[] {
 
 export class FastbootFlasher {
   client: FastbootClient
-  reader: ZipReader
+  reader: ZipReader<BlobReader>
 
   constructor(client: FastbootClient, blob: Blob) {
     this.client = client
@@ -106,7 +172,7 @@ export class FastbootFlasher {
   // parses and runs flash-all.sh. it ignores all shell commands
   // except fastboot or sleep
   async runFlashAll() {
-    const entries: Entry[] = await this.reader.getEntries()
+    const entries = (await this.reader.getEntries()).filter(isFileEntry)
     const flashAllSh = await getEntry(entries, "flash-all.sh").getData(
       new TextWriter(),
     )
@@ -121,16 +187,16 @@ export class FastbootFlasher {
     return this.run(instructions)
   }
 
-  async run(instructions: text) {
-    const entries: Entry[] = await this.reader.getEntries() // io with factory.zip
+  async run(instructions: string) {
+    const entries = (await this.reader.getEntries()).filter(isFileEntry) // io with factory.zip
     const commands: Instruction[] = parseInstructions(instructions)
 
     for (const command of commands) {
       this.client.logger.log(`‣ ${JSON.stringify(command)}`)
       if (command.command === "flash") {
-        const partition = command.args[0]
-        const filename = command.args[1]
-        const slot = command.options.slot || "current"
+        const partition = requireArg(command.command, command.args, 0)
+        const filename = requireArg(command.command, command.args, 1)
+        const slot = command.options.slot ?? "current"
         const entry = getEntry(entries, filename)
         const blob = await entry.getData(
           new BlobWriter("application/octet-stream"),
@@ -152,15 +218,19 @@ export class FastbootFlasher {
         }
         await this.client.rebootBootloader()
       } else if (command.command === "update") {
-        const nestedZipEntry = getEntry(entries, command.args[0])
+        const zipName = requireArg(command.command, command.args, 0)
+        const nestedZipEntry = getEntry(entries, zipName)
         const zipBlob = await nestedZipEntry.getData(
           new BlobWriter("application/zip"),
         )
         const zipReader = new ZipReader(new BlobReader(zipBlob))
-        const nestedEntries = await zipReader.getEntries()
+        const nestedEntries = (await zipReader.getEntries()).filter(isFileEntry)
         const fastbootInfoFile = nestedEntries.find(
           (e) => e.filename === "fastboot-info.txt",
         )
+        if (!fastbootInfoFile) {
+          throw new Error("fastboot-info.txt not found in nested zip")
+        }
         const fastbootInfoText = await fastbootInfoFile.getData(
           new TextWriter(),
         )
@@ -182,10 +252,12 @@ export class FastbootFlasher {
           throw new Error(`Unknown command`)
         }
       } else if (command.command === "getvar") {
-        const clientVar = await this.client.getVar(command.args[0])
-        this.client.logger(`getVar(${command.args[0]}) => ${clientVar}`)
+        const varName = requireArg(command.command, command.args, 0)
+        const clientVar = await this.client.getVar(varName)
+        this.client.logger.log(`getVar(${varName}) => ${clientVar}`)
       } else if (command.command === "erase") {
-        await this.client.erase(command.args[0])
+        const partition = requireArg(command.command, command.args, 0)
+        await this.client.erase(partition)
       } else if (command.command === "sleep") {
         const ms = command.args[0] ? parseInt(command.args[0]) * 1000 : 5000
         await new Promise((resolve) => setTimeout(resolve, ms))

package/src/sparse.ts

@@ -65,6 +65,12 @@ export interface SparseChunk {
   data: Blob | null // to be populated by consumer
 }
 
+export interface BlobHeader {
+  blobSize: number
+  totalBytes: number
+  isSparse: boolean
+}
+
 class BlobBuilder {
   private blob: Blob
   private type: string
@@ -221,6 +227,7 @@ export async function fromRaw(blob: Blob): Promise<Blob> {
     chunks.push({
       type: ChunkType.Raw,
       blocks: chunkSize / header.blockSize,
+      dataBytes: chunkSize,
       data: blob.slice(0, chunkSize),
     })
     blob = blob.slice(chunkSize)
@@ -370,7 +377,7 @@ export async function* splitBlob(blob: Blob, splitSize: number) {
   // Finish the final split if necessary
   if (
     splitChunks.length > 0 &&
-    (splitChunks.length > 1 || splitChunks[0].type !== ChunkType.Skip)
+    (splitChunks.length > 1 || splitChunks[0]?.type !== ChunkType.Skip)
   ) {
     const splitImage = await createImage(header, splitChunks)
     console.debug(
@@ -383,11 +390,7 @@ export async function* splitBlob(blob: Blob, splitSize: number) {
   }
 }
 
-export async function parseBlobHeader(blob: Blob): {
-  blobSize: number
-  totalBytes: number
-  isSparse: boolean
-} {
+export async function parseBlobHeader(blob: Blob): Promise<BlobHeader> {
   const FILE_HEADER_SIZE = 28
   const blobSize = blob.size
   let totalBytes = blobSize

package/tsconfig.json

@@ -1,14 +1,26 @@
 {
   "compilerOptions": {
-    "target": "es6",
-    "lib": ["es6", "dom"],
-    "module": "es6",
-    "sourceMap": true,
-    "allowJs": false,
+    /* Base Options: */
     "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "target": "es2022",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "moduleDetection": "force",
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+
+    /* Strictness */
     "strict": true,
-    "noEmit": true
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "sourceMap": true,
+    "declaration": true,
+    "module": "preserve",
+    "noEmit": true,
+
+    "lib": ["es2022", "dom", "dom.iterable"],
   },
   "include": ["src/**/*"],
   "exclude": []