feat(cli)!: require an explicit app id for android/ios-device delivery

[V3RON]

Closes #63. Design agreed in this comment.

The problem

deliverAndroid emitted am start -a android.intent.action.VIEW -d '<link>' with no package. When more than one installed app declares the scheme — product flavors with applicationIdSuffix, a debug and a release build side by side, two projects sharing a generic scheme — Android shows the "Open with" chooser. am start still exits 0, so delivery reports delivered: true and appduct_wait_for_session blocks its whole timeout with nothing explaining why. Same failure signature as the ios-device loopback case §8 already guards against.

The change

Delivery to a target that resolves an app by identity now requires the app's id, and names it explicitly: am start … -d '<link>' -p <app-id>.

One per-invocation flag, one platform-keyed config block:

{ "scheme": "myapp", "appId": { "ios": "com.example.MyApp", "android": "com.example.myapp" } }

Resolution per target: --app-id / appId (MCP, mintLink, appduct/client's link()) → nearest .appduct/config.json declaring appId.<platform>, via the existing walk-up → usage error raised before minting, so a missing id never strands a pending session. android → appId.android, ios-device → appId.ios; ios-sim needs none (simctl openurl has no equivalent flag) and passing one there is a usage error.

Decisions worth a reviewer's attention

Required, not optional-with-fallback. Falling back to today's implicit intent would leave the zero-argument appduct_connect path — the one the issue is about — exactly as broken. A loud, actionable error beats a silent 120s timeout; that is the trade loopbackAddressMessage already makes. Note the consequence: on the auto-detected Android path an unconfigured project now gets invalid_request rather than the QR fallback it would previously have degraded to. That is deliberate — the error names the exact command to run — but it is the one behavioural change that goes beyond "add a flag".

No static discovery of the id. Reading applicationId out of build.gradle carries the failure mode the issue opens with: a project using applicationIdSuffix resolves the base id, and -p then targets an app that either isn't installed (loud) or is the wrong flavor declaring the same scheme (silent, and worse than the chooser). Guarding it needs flavor heuristics and "sources disagree" rules — more machinery than a committed config line.

Config is per-platform, the flag is not. Android forbids - and is conventionally lowercase, so com.example.MyApp / com.example.myapp divergence is real and a single config value would feed the wrong id to one platform. A flag doesn't have that problem because the target is known when it is typed. init takes two independent flags for the same reason and never guesses one from the other.

One shape check for both platforms. The existing bundle-id pattern gains a second caller. It is a safety check, not a grammar check: the value reaches both a devicectl trailing positional (where a leading - reads as an option) and a string adb shell re-parses on the device's own shell (where a space or ; is injection — the same reason §8 single-quotes the URL).

am start output is checked. am does not reliably exit non-zero, so output matching /^Error:/m becomes a thrown usage error. Without it an unresolvable -p reproduces the very silent hang being fixed.

Breaking

1. --open android, and Android delivery via appduct_connect, now require an app id.
2. --bundle-id (CLI), bundleId (MCP / mintLink / appduct/client), and config.json's iosBundleId are removed — no deprecation shim. A leftover iosBundleId is silently ignored (loadConfig's warn defaults to a no-op), so the delivery-time error is the only signal, which is why it names the migration.
3. Migration, once per app root: appduct init --scheme myapp --android-app-id com.example.myapp --ios-app-id com.example.MyApp.

Out of scope

Static discovery, any state-dir appId key, --ios-app-id/--android-app-id on appduct mcp (the per-call appId is the escape hatch when the server's cwd isn't the app root), doctor changes, and the debug BroadcastReceiver the issue defers.

Testing

pnpm typecheck, pnpm lint and pnpm check:links are clean. Test suite: 711 passed, 1 skipped, 1 failed — src/__tests__/e2e/daemon-restart.e2e.test.ts ("SIGKILL mid-session…"), which I verified fails identically on the base commit 92e5396 and touches nothing this change modifies. Flagging it rather than papering over it.

New coverage, all through the existing ExecFn seam (no real adb/xcrun): the -p argv with and without -s, a malformed id rejected before any exec call, am start Error: detection, the missing-id failure landing before link.create on both targets, --app-id beating the config and appId.<platform> selected per target, project-config parse/unknown-key errors, init's new flags with merge and --force semantics, and the MCP paths (explicit, auto-detected, and the ios-sim/none rejections).

The second commit is a fix from my own review of the first: resolveAppId was called from appduct_connect without stateDirRoot, while the same server passes it when resolving scheme — without it a --state-dir on the walk-up path would be read at the project tier, inverting the precedence globalConfigDirs exists to enforce.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MixZ87V14ZHMAnT5CCKRiU

---

Generated by Claude Code