adb-unlock 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MusiCode1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# adb-unlock
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Inject a **known** pattern / PIN / password into a **remote** Android device over
+**ADB or SSH**, dismissing the lock screen without touching it.
+
+Pattern coordinates are derived **live from the accessibility tree**
+(`uiautomator dump`), not hardcoded — so it works across resolutions and OEM skins
+(stock `lockPatternView`, OneUI / OxygenOS `colorLockPatternView`), and even when the
+touchscreen is dead (`input` injects above the hardware layer).
+
+> For **your own** devices. Wrong attempts count toward the lockout; when root is
+> available the tool runs a `locksettings verify` pre-check and stops if the stored
+> value is wrong. See also [prior art](./docs/prior-art.md) — this idea exists in
+> other forms; the differentiators here are dynamic coordinates + SSH transport.
+
+🔢 **Landing page** with a pattern → digit-sequence converter: `web/` (SvelteKit).
+
+## Install / run
+
+```bash
+npx adb-unlock -s <serial> --pattern
+```
+
+Everything is passed via flags (no positional); the default transport is **adb**.
+Requires `adb` and/or `ssh` on PATH. No install needed via `npx`.
+
+## Usage
+
+```bash
+# ADB (default), explicit serial like `adb -s`; a bare --pattern prompts hidden
+npx adb-unlock -s 10.0.0.5:5555 --pattern
+
+# ANDROID_SERIAL env (adb's native var) is honored
+ANDROID_SERIAL=10.0.0.5:5555 npx adb-unlock --pattern 583
+
+# SSH transport (e.g. Termux over a VPN) — selected by --ssh
+npx adb-unlock --ssh my-tablet-alias --pin
+
+# Registry entry from devices.json (also default --bw-item)
+npx adb-unlock --device my-tablet
+
+# List connected adb devices
+npx adb-unlock --list
+
+# Recon only / remove the lock (needs root)
+npx adb-unlock -s SERIAL --pattern 583 --dry-run
+npx adb-unlock -s SERIAL --remove-lock
+```
+
+### Pattern numbering
+
+Dots are numbered **1-9 by position**, left-to-right, top-to-bottom
+(1 = top-left, 9 = bottom-right) — the same order Android's grid uses. This is **not**
+the order you drew them. The landing page converter turns a drawn pattern into this
+sequence for you.
+
+### Device selection
+
+Everything is a flag — there is no positional argument.
+
+- **ADB (default):** `-s` / `--serial`, or `$ANDROID_SERIAL`. With multiple devices
+  connected and no serial, the tool lists them and asks you to choose (same as `adb`).
+- **SSH:** `--ssh <alias>` selects the ssh transport.
+- **Registry:** `--device <name>` looks the device up in `devices.json` (and is the
+  default `--bw-item`).
+
+## Credential sources (in priority order)
+
+1. Direct flag with a value: `--pattern 583` / `--pin 4721` / `--password hunter2`.
+2. Bare flag → hidden prompt: `--pattern` (nothing printed, nothing in shell history).
+3. Bitwarden (optional): an item per device with hidden fields
+   `screen-lock-pattern` / `screen-lock-pin` / `screen-lock-password`
+   (needs the `bw-mcp-cli` wrapper and an unlocked vault).
+
+## Device registry (optional) — `devices.json`
+
+Non-secret: transport + connection + shell wrapper. See `devices.json.example`.
+Path from `--devices`, or `$ADB_UNLOCK_DEVICES`, or `./devices.json`.
+
+## Transports
+
+| transport | how |
+|---|---|
+| `ssh`  | `ssh <alias> "<wrap> sh"` |
+| `adb`  | `adb -s <serial> shell "<wrap> sh"` (auto-runs `adb connect` for `ip:port` serials) |
+| `adb` via a jump host | `ssh <host> "[pct exec <ct> --] adb -s <serial> shell <wrap> sh"` |
+
+`<wrap>` = `su -c` (root), `$HOME/rish -c` (Shizuku), or none — chosen by `--via`
+(default `auto`). Root is needed only for the `verify` pre-check and `--remove-lock`.
+
+## Safety
+
+- Wrong pattern/PIN attempts count toward the 5-try lockout — root `locksettings verify`
+  pre-check stops before injecting a wrong value (`--no-verify` to skip).
+- Never injects during an active call (unless `--force`).
+- Confirms success via `isKeyguardShowing=false`, not assumption.
+- The credential is never printed or written to disk; `logcat` is cleared afterward.
+
+## Architecture
+
+Functional core / imperative shell: `src/core/` is pure (grid math, script builders,
+output parsing, transport argv) with unit tests; `src/shell/` does IO (`child_process`
+for ssh/adb, Bitwarden, hidden prompt); `src/cli.ts` orchestrates.
+
+```bash
+npm test        # vitest on core/
+npm run build   # esbuild -> dist/cli.js
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+import { setTimeout as sleep } from "node:timers/promises";
+import { readFileSync, existsSync } from "node:fs";
+
+// src/core/bouncer.ts
+var PATTERN_IDS = ["lockPatternView", "colorLockPatternView", "oplusos_kgd_security_pattern_view"];
+function squarish(b) {
+  const w = b[2] - b[0], h = b[3] - b[1];
+  return w > 0 && h > 0 && Math.abs(w - h) <= 0.25 * Math.max(w, h);
+}
+function patternGridFromDump(xml) {
+  const cands = [];
+  for (const m of xml.matchAll(/<node\b[^>]*>/g)) {
+    const s = m[0];
+    const rid = (/resource-id="([^"]*)"/.exec(s)?.[1] ?? "").toLowerCase();
+    const desc = /content-desc="([^"]*)"/.exec(s)?.[1] ?? "";
+    const isGrid = rid.endsWith("lockpatternview");
+    const hit = isGrid || PATTERN_IDS.some((p) => rid.endsWith(p.toLowerCase())) || desc.toLowerCase().includes("pattern") || desc.includes("\u05EA\u05D1\u05E0\u05D9\u05EA");
+    if (!hit) continue;
+    const b = /bounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/.exec(s);
+    if (b) cands.push({ grid: isGrid, b: [Number(b[1]), Number(b[2]), Number(b[3]), Number(b[4])] });
+  }
+  return cands.find((c) => c.grid && squarish(c.b))?.b ?? cands.find((c) => squarish(c.b))?.b ?? null;
+}
+function patternPoints(b) {
+  const [L, T, R, B] = b;
+  const w = (R - L) / 3, h = (B - T) / 3;
+  const pts = {};
+  for (let d = 1; d <= 9; d++) {
+    const i = d - 1, c = i % 3, r = Math.floor(i / 3);
+    pts[d] = [Math.trunc(L + (c + 0.5) * w), Math.trunc(T + (r + 0.5) * h)];
+  }
+  return pts;
+}
+function parsePatternDigits(cred) {
+  return [...cred].filter((c) => c >= "1" && c <= "9").map(Number);
+}
+function buildPatternGesture(points, digits) {
+  const lines = [];
+  digits.forEach((d, k) => {
+    const [x, y] = points[d];
+    lines.push(`input motionevent ${k === 0 ? "DOWN" : "MOVE"} ${x} ${y}`);
+    lines.push("sleep 0.08");
+  });
+  const [lx, ly] = points[digits[digits.length - 1]];
+  lines.push(`input motionevent UP ${lx} ${ly}`);
+  return lines;
+}
+function buildTextEntry(text) {
+  const esc = text.replace(/ /g, "%s");
+  return [`input text '${esc}'`, "sleep 0.3", "input keyevent KEYCODE_ENTER"];
+}
+var PROBE = {
+  pattern: "lockpatternview",
+  text: "passwordentry|pinentry|numpadkey|keyguard_pin|keyguard_password"
+};
+function raiseLoopScript(size, kind = "pattern") {
+  const x = size ? Math.round(size.w / 2) : 600;
+  const y1 = size ? Math.round(size.h * 0.8) : 1600;
+  const y2 = size ? Math.round(size.h * 0.2) : 400;
+  const check = `uiautomator dump /sdcard/.au.xml >/dev/null 2>&1; grep -qiE '${PROBE[kind]}' /sdcard/.au.xml && break`;
+  return [
+    "for i in 1 2 3 4; do",
+    "  input keyevent KEYCODE_WAKEUP; sleep 0.4",
+    "  wm dismiss-keyguard; sleep 1.0",
+    `  ${check}`,
+    `  input swipe ${x} ${y1} ${x} ${y2} 150; sleep 0.8`,
+    `  ${check}`,
+    "  sleep 0.3",
+    "done",
+    ""
+  ].join("\n");
+}
+
+// src/core/recon.ts
+function reconScript() {
+  return [
+    "echo KG=$(dumpsys window 2>/dev/null | grep -m1 -o 'isKeyguardShowing=[a-z]*')",
+    "echo CALL=$(dumpsys telephony.registry 2>/dev/null | grep -m1 -o 'mCallState=[0-9]*')",
+    "echo SIZE=$(wm size 2>/dev/null | grep -m1 -o '[0-9]*x[0-9]*' | head -1)",
+    "echo TOP=$(dumpsys activity activities 2>/dev/null | grep -m1 -o 'topResumedActivity=[^ ]*')"
+  ].join("\n") + "\n";
+}
+function parseRecon(out) {
+  const kg = /isKeyguardShowing=([a-z]*)/.exec(out)?.[1] ?? "";
+  const call = /mCallState=([0-9]*)/.exec(out)?.[1] ?? "0";
+  const size = /SIZE=([0-9x]*)/.exec(out)?.[1] ?? "";
+  const top = /TOP=(\S*)/.exec(out)?.[1] ?? "";
+  return { keyguard: kg === "true", call: !(call === "" || call === "0"), size, top };
+}
+function parseSize(size) {
+  const m = /^(\d+)x(\d+)$/.exec(size);
+  return m ? { w: Number(m[1]), h: Number(m[2]) } : null;
+}
+
+// src/core/credential.ts
+var CRED_FIELDS = {
+  pattern: "screen-lock-pattern",
+  pin: "screen-lock-pin",
+  password: "screen-lock-password"
+};
+function resolveCredentialType(fields, requested) {
+  if (requested) {
+    const v = fields[CRED_FIELDS[requested]];
+    if (!v) throw new Error(`item has no field '${CRED_FIELDS[requested]}'`);
+    return { type: requested, value: v };
+  }
+  for (const t of ["pattern", "pin", "password"]) {
+    const v = fields[CRED_FIELDS[t]];
+    if (v) return { type: t, value: v };
+  }
+  throw new Error("no screen-lock field (screen-lock-pattern/-pin/-password) in item");
+}
+
+// src/core/schema.ts
+var TRANSPORTS = ["ssh", "adb"];
+var VIAS = ["auto", "root", "rish", "none"];
+function parseRegistry(raw) {
+  const data = JSON.parse(raw);
+  if (typeof data !== "object" || data === null) throw new Error("devices.json is not an object");
+  for (const [k, v] of Object.entries(data)) {
+    if (v.transport && !TRANSPORTS.includes(v.transport)) throw new Error(`${k}: invalid transport`);
+    if (v.via && !VIAS.includes(v.via)) throw new Error(`${k}: invalid via`);
+  }
+  return data;
+}
+
+// src/shell/exec.ts
+import { spawnSync } from "node:child_process";
+
+// src/core/transport.ts
+function chooseWrap(d, via) {
+  switch (via) {
+    case "root":
+      return "su -c";
+    case "rish":
+      return "$HOME/rish -c";
+    case "none":
+      return "";
+    default:
+      return d.root ? "su -c" : d.rish ? "$HOME/rish -c" : "";
+  }
+}
+function remoteShell(wrap) {
+  return wrap ? `${wrap} sh` : "sh";
+}
+function buildInvocation(name, profile, wrap, opts = {}) {
+  const transport = opts.transport ?? profile.transport ?? "ssh";
+  const remote = remoteShell(wrap);
+  if (transport === "adb") {
+    const serial = opts.serial ?? profile.adb?.serial;
+    const target = serial ? ["-s", serial] : [];
+    if (profile.adb?.sshHost) {
+      const pct = profile.adb.ct ? `pct exec ${profile.adb.ct} -- ` : "";
+      const s = serial ? `-s ${serial} ` : "";
+      return ["ssh", "-o", "ConnectTimeout=12", profile.adb.sshHost, `${pct}adb ${s}shell ${remote}`];
+    }
+    return ["adb", ...target, "shell", remote];
+  }
+  const alias = profile.ssh ?? name;
+  return ["ssh", "-o", "ConnectTimeout=12", alias, remote];
+}
+function buildAdbConnect(profile, opts = {}) {
+  const transport = opts.transport ?? profile.transport ?? "ssh";
+  if (transport !== "adb") return null;
+  const serial = opts.serial ?? profile.adb?.serial;
+  if (!serial || !serial.includes(":")) return null;
+  if (profile.adb?.sshHost) {
+    const pct = profile.adb.ct ? `pct exec ${profile.adb.ct} -- ` : "";
+    return ["ssh", "-o", "ConnectTimeout=12", profile.adb.sshHost, `${pct}adb connect ${serial}`];
+  }
+  return ["adb", "connect", serial];
+}
+
+// src/shell/exec.ts
+var Device = class {
+  constructor(name, profile, opts = {}) {
+    this.name = name;
+    this.profile = profile;
+    this.opts = opts;
+  }
+  name;
+  profile;
+  opts;
+  wrap = "";
+  _root = false;
+  get root() {
+    return this._root;
+  }
+  spawn(argv, script) {
+    const r = spawnSync(argv[0], argv.slice(1), {
+      input: script,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024
+    });
+    return (r.stdout ?? "") + (r.stderr ?? "");
+  }
+  runWith(wrap, script) {
+    return this.spawn(buildInvocation(this.name, this.profile, wrap, this.opts), script);
+  }
+  sh(script, o) {
+    return this.runWith(o?.asRoot ? "su -c" : this.wrap, script);
+  }
+  detect() {
+    const conn = buildAdbConnect(this.profile, this.opts);
+    if (conn) this.spawn(conn);
+    const out = this.runWith(
+      "",
+      "su -c id 2>/dev/null\ntest -x $HOME/rish && echo RISH=yes || echo RISH=no\n"
+    );
+    this._root = /uid=0/.test(out);
+    const rish = /RISH=yes/.test(out);
+    const via = this.profile.via ?? "auto";
+    if (via === "root" && !this._root) throw new Error(`${this.name}: via=root but no root access`);
+    this.wrap = chooseWrap({ root: this._root, rish }, via);
+  }
+  cleanLogcat() {
+    try {
+      this.sh("logcat -c\n", { asRoot: this.root });
+    } catch {
+    }
+  }
+};
+function adbDevices() {
+  const r = spawnSync("adb", ["devices", "-l"], { encoding: "utf8" });
+  return (r.stdout ?? "") + (r.stderr ?? "");
+}
+function adbSerials() {
+  const out = adbDevices();
+  const res = [];
+  for (const line of out.split("\n").slice(1)) {
+    const m = /^(\S+)\s+(device|unauthorized|offline)\b/.exec(line.trim());
+    if (m) res.push({ serial: m[1], state: m[2] });
+  }
+  return res;
+}
+
+// src/shell/bitwarden.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+function bwUnlocked() {
+  try {
+    const r = spawnSync2("bw-mcp-cli", ["status"], { encoding: "utf8" });
+    return JSON.parse(r.stdout ?? "{}").status === "unlocked";
+  } catch {
+    return false;
+  }
+}
+function bwItemFields(name) {
+  const r = spawnSync2("bw-mcp-cli", ["get", "item", name], { encoding: "utf8" });
+  if (r.status !== 0 || !r.stdout) throw new Error(`bitwarden item '${name}' not found`);
+  const item = JSON.parse(r.stdout);
+  const fields = {};
+  for (const f of item.fields ?? []) fields[f.name] = f.value;
+  return fields;
+}
+
+// src/shell/prompt.ts
+async function promptHidden(label) {
+  process.stderr.write(label);
+  const stdin = process.stdin;
+  stdin.setRawMode?.(true);
+  stdin.resume();
+  let buf = "";
+  for await (const chunk of stdin) {
+    for (const ch of chunk.toString("utf8")) {
+      if (ch === "\n" || ch === "\r") {
+        stdin.setRawMode?.(false);
+        stdin.pause();
+        process.stderr.write("\n");
+        return buf;
+      } else if (ch === "\x7F" || ch === "\b") {
+        buf = buf.slice(0, -1);
+      } else if (ch === "") {
+        process.exit(130);
+      } else {
+        buf += ch;
+      }
+    }
+  }
+  stdin.setRawMode?.(false);
+  return buf;
+}
+
+// src/cli.ts
+var ASK = "\0ASK";
+function log(m) {
+  process.stderr.write(m + "\n");
+}
+function die(m) {
+  log("\u2717 " + m);
+  process.exit(1);
+}
+function preprocess(argv) {
+  const creds = /* @__PURE__ */ new Set(["--pattern", "--pin", "--password"]);
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (creds.has(a)) {
+      const next = argv[i + 1];
+      out.push(next === void 0 || next.startsWith("-") ? `${a}=${ASK}` : a);
+    } else out.push(a);
+  }
+  return out;
+}
+function loadRegistry(path) {
+  const p = path || process.env.ADB_UNLOCK_DEVICES || "devices.json";
+  return existsSync(p) ? parseRegistry(readFileSync(p, "utf8")) : {};
+}
+async function resolveCredential(values, label, bwItem) {
+  for (const t of ["pattern", "pin", "password"]) {
+    const v = values[t];
+    if (v !== void 0) {
+      const val = v === ASK ? await promptHidden(`${t} for ${label} (hidden): `) : v;
+      if (!val) die("empty credential");
+      return { type: t, value: val, source: "direct" };
+    }
+  }
+  if (!bwItem) {
+    die("no credential given. pass --pattern/--pin/--password, or --bw-item/--device for Bitwarden.");
+  }
+  if (!bwUnlocked()) die("bitwarden vault is locked. unlock it, or pass a credential directly.");
+  const fields = bwItemFields(bwItem);
+  const r = resolveCredentialType(fields, values.type);
+  return { ...r, source: "bitwarden" };
+}
+function verifyCredential(dev, cred) {
+  const out = dev.sh(`locksettings verify --old '${cred}'
+`, { asRoot: true });
+  dev.cleanLogcat();
+  return out.includes("verified successfully");
+}
+function removeLock(dev, cred) {
+  const out = dev.sh(`locksettings clear --old '${cred}'
+`, { asRoot: true });
+  dev.cleanLogcat();
+  const chk = dev.sh(
+    "locksettings get-disabled 2>/dev/null; dumpsys lock_settings 2>/dev/null | grep -m1 CredentialType\n",
+    { asRoot: true }
+  );
+  return chk.includes("NONE") || /success/i.test(out);
+}
+async function injectPattern(dev, cred, dry, size) {
+  const raise = raiseLoopScript(size ?? void 0, "pattern");
+  const xml = dev.sh(raise + "cat /sdcard/.au.xml; rm -f /sdcard/.au.xml\n");
+  const bounds = patternGridFromDump(xml);
+  if (!bounds) die("no pattern grid in the accessibility tree (did the bouncer show? maybe the lock is not a pattern)");
+  const digits = parsePatternDigits(cred);
+  if (digits.length < 4) die("pattern shorter than 4 dots \u2014 probably a wrong value");
+  log(`  grid: bounds=[${bounds.join(",")}]  pattern-dots=${digits.length}`);
+  if (dry) return;
+  dev.sh(raise + "rm -f /sdcard/.au.xml\n" + buildPatternGesture(patternPoints(bounds), digits).join("\n") + "\n");
+  await sleep(1e3);
+}
+async function injectText(dev, cred, dry, size) {
+  const raise = raiseLoopScript(size ?? void 0, "text");
+  if (dry) {
+    dev.sh(raise + "rm -f /sdcard/.au.xml\n");
+    log("  (dry-run: no text entered)");
+    return;
+  }
+  dev.sh(raise + "rm -f /sdcard/.au.xml\n" + buildTextEntry(cred).join("\n") + "\n");
+  await sleep(1e3);
+}
+var HELP = `adb-unlock \u2014 inject a known pattern/PIN/password into a remote Android device
+
+Usage: adb-unlock [options]        (everything via flags; default transport: adb)
+
+Credential (one of; a bare flag prompts hidden):
+  --pattern [VALUE]   pattern as position digits 1-9 (keypad order, 1=top-left)
+  --pin [VALUE]       numeric PIN
+  --password [VALUE]  text password
+  --type TYPE         when reading from Bitwarden: pattern|pin|password
+
+Device / transport:
+  --transport adb|ssh        default adb (ssh is implied by --ssh)
+  -s, --serial SERIAL        adb device serial (also env ANDROID_SERIAL)
+  --ssh ALIAS                ssh host alias (selects ssh transport)
+  -d, --device NAME          registry key in devices.json; also default --bw-item
+  --via auto|root|rish|none  shell wrapper on device (default auto)
+  --list                     list connected adb devices and exit
+
+Other:
+  --bw-item NAME     Bitwarden item name (default: --device value)
+  --devices PATH     device registry JSON (default ./devices.json or $ADB_UNLOCK_DEVICES)
+  --no-verify        skip the root locksettings-verify pre-check
+  --force            inject even during an active call
+  --dry-run          recon only, no injection
+  --remove-lock      remove the lock entirely (needs root)
+  -h, --help
+
+Requires 'adb' and/or 'ssh' on PATH. Credential never printed; logcat cleared after.`;
+async function main() {
+  const { values } = parseArgs({
+    args: preprocess(process.argv.slice(2)),
+    allowPositionals: false,
+    options: {
+      type: { type: "string" },
+      ssh: { type: "string" },
+      via: { type: "string" },
+      transport: { type: "string" },
+      serial: { type: "string", short: "s" },
+      device: { type: "string", short: "d" },
+      "bw-item": { type: "string" },
+      devices: { type: "string" },
+      pattern: { type: "string" },
+      pin: { type: "string" },
+      password: { type: "string" },
+      "no-verify": { type: "boolean" },
+      "remove-lock": { type: "boolean" },
+      force: { type: "boolean" },
+      "dry-run": { type: "boolean" },
+      list: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help) {
+    console.log(HELP);
+    return;
+  }
+  if (values.list) {
+    process.stdout.write(adbDevices());
+    return;
+  }
+  const deviceKey = values.device;
+  const registry = loadRegistry(values.devices);
+  const profile = { ...deviceKey ? registry[deviceKey] ?? {} : {} };
+  if (values.ssh) profile.ssh = values.ssh;
+  if (values.via) profile.via = values.via;
+  const serial = values.serial ?? process.env.ANDROID_SERIAL ?? profile.adb?.serial;
+  const effTransport = values.transport ?? profile.transport ?? (serial ? "adb" : profile.ssh ? "ssh" : "adb");
+  if (effTransport === "ssh" && !profile.ssh) {
+    die("ssh transport needs an alias \u2014 pass --ssh <alias> (or --device with ssh in devices.json).");
+  }
+  if (effTransport === "adb" && !serial) {
+    const devs = adbSerials().filter((d) => d.state === "device");
+    if (devs.length > 1) {
+      die("multiple adb devices connected \u2014 choose one with -s/--serial (or $ANDROID_SERIAL):\n  " + devs.map((d) => d.serial).join("\n  "));
+    }
+  }
+  const label = deviceKey ?? serial ?? profile.ssh ?? "(adb)";
+  const bwItem = values["bw-item"] ?? profile.bw_item ?? deviceKey;
+  const { type, value: cred, source } = await resolveCredential(values, label, bwItem);
+  log(`device: ${label}  \xB7  transport=${effTransport}  \xB7  type=${type}  \xB7  source=${source}`);
+  const dev = new Device(label, profile, { transport: effTransport, serial });
+  dev.detect();
+  log(`  root=${dev.root ? "yes" : "no"}  wrap=${dev.wrap || "none"}`);
+  const st = parseRecon(dev.sh(reconScript()));
+  log(`  keyguard=${st.keyguard ? "shown" : "dismissed"}  call=${st.call ? "active" : "none"}  size=${st.size}  top=${st.top}`);
+  if (st.call && !values.force) die("active call on device \u2014 not injecting blind. end the call or use --force.");
+  if (!st.keyguard && !values["remove-lock"]) {
+    log("\u2713 device already unlocked (keyguard dismissed).");
+    return;
+  }
+  if (dev.root && !values["no-verify"]) {
+    if (verifyCredential(dev, cred)) log("  \u2713 credential verified via locksettings");
+    else die(`credential (${source}) failed verify on device \u2014 stopping before injection (lockout risk).`);
+  }
+  if (values["remove-lock"] && !dev.root) die("--remove-lock needs root, none available.");
+  if (st.keyguard) {
+    const size = parseSize(st.size);
+    if (type === "pattern") await injectPattern(dev, cred, !!values["dry-run"], size);
+    else await injectText(dev, cred, !!values["dry-run"], size);
+    dev.cleanLogcat();
+    if (values["dry-run"]) {
+      log("\u2713 dry-run done (nothing injected).");
+      return;
+    }
+    const st2 = parseRecon(dev.sh(reconScript()));
+    if (st2.keyguard) die("injection did not dismiss the keyguard. check the lock type and value.");
+    log(`\u2713 unlocked \u2014 keyguard dismissed, top=${st2.top}`);
+  }
+  if (values["remove-lock"]) {
+    if (removeLock(dev, cred)) log("\u2713 lock removed (locksettings clear).");
+    else die("remove-lock not confirmed \u2014 check manually.");
+  }
+}
+main().catch((e) => die(e instanceof Error ? e.message : String(e)));

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "adb-unlock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Inject a known pattern / PIN / password into a remote Android device (ADB or SSH) to dismiss the lock screen without touching it — coordinates derived live from the accessibility tree.",
+  "type": "module",
+  "bin": { "adb-unlock": "dist/cli.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=dist/cli.js --banner:js='#!/usr/bin/env node'",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["android", "adb", "unlock", "pattern", "pin", "lockscreen", "uiautomator", "cli", "scrcpy"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/MusiCode1/adb-unlock.git" },
+  "homepage": "https://github.com/MusiCode1/adb-unlock#readme",
+  "bugs": { "url": "https://github.com/MusiCode1/adb-unlock/issues" },
+  "devDependencies": {
+    "@types/node": "latest",
+    "esbuild": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  }
+}