appduct 0.10.0 → 0.11.1

package/dist/key-material.d.ts

@@ -11,4 +11,3 @@ export declare const generatePrivateKeyPem: () => string;
  * `path` still succeed, since `rename` replaces the destination on POSIX regardless of whether it
  * already existed — only the *temp* path must be exclusive. */
 export declare const writePrivateKeyAtomically: (path: string, keyPem: string) => Promise<void>;
-//# sourceMappingURL=key-material.d.ts.map

package/dist/link.d.ts

@@ -11,10 +11,11 @@
  * The `pin` param is separate from the `appduct` bootstrap blob (opt-in hardening dev-mode) — it
  * is never part of that binary v2 payload, so old apps that don't know about it simply ignore it.
  * It carries the daemon's SPKI pin (same value as `daemon.status`'s `pinnedKeys[0]` / `appduct
- * keygen`'s output) so a debug build with no build-time `cliPins` configured can trust it for this
- * one connection instead of requiring a native rebuild just to test locally. The pin is standard
- * (non-URL-safe) base64 (`sha256/<44-char-base64>`, may contain `+`/`/`/`=`), so it is percent-
- * encoded here; native/JS parsers use `URLSearchParams`, which decodes it back.
+ * keygen`'s output) so any build that embeds no `cliPins` — whatever its build type, there is no
+ * build-type gate — can trust it for this one connection instead of requiring a native rebuild
+ * just to test locally. The pin is standard (non-URL-safe) base64
+ * (`sha256/<44-char-base64>`, may contain `+`/`/`/`=`), so it is percent-encoded here; native/JS
+ * parsers use `URLSearchParams`, which decodes it back.
  */
 import { type AgentEndpoint, type LinkCreateResult } from "@appduct/shared";
 import { type ExecFn, type OpenTarget } from "./cli/open-target.js";
@@ -40,8 +41,9 @@ export type MintLinkOptions = {
     /** An adb device serial (`target: "android"`), a simulator udid (`target: "ios-sim"`) or a
      * paired-device udid (`target: "ios-device"`). Only meaningful alongside a target. */
     device?: string;
-    /** Overrides `config.json`'s `iosBundleId`. Only meaningful with `target: "ios-device"`. */
-    bundleId?: string;
+    /** The installed app's id (Android package name / iOS bundle id) — highest-precedence source in
+     * `resolveAppId`'s order. Only meaningful with `target: "android"` or `target: "ios-device"`. */
+    appId?: string;
     /** `target: "ios-device"` only: terminate a running instance before launching
      * (`--terminate-existing`). Off by default. */
     relaunch?: boolean;
@@ -73,4 +75,3 @@ export type MintLinkResult = {
  * that straight through the CLI's own error path; `client/bootstrap.ts` converts it to a
  * `AppductError` via `toAppductError` (which already understands `AppductCliError`). */
 export declare const mintLink: (options: MintLinkOptions) => Promise<MintLinkResult>;
-//# sourceMappingURL=link.d.ts.map

package/dist/mcp/app-tools.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The built-in `appduct_list_tools` / `appduct_describe_tool` / `appduct_call_tool` MCP tools
+ * (ARCHITECTURE.md §9). The app's own tools are never listed as MCP tools. An agent reaches them
+ * the way the CLI does: compact signatures first (`appduct tools`), one full schema on demand
+ * (`appduct tools <name>`), then a call by name (`appduct invoke`). A registry of hundreds of tools
+ * therefore costs a client three fixed tool definitions, and `tools/list` never changes while an
+ * agent works.
+ *
+ * Every lookup goes to the daemon live, with no caching: the session and its registry can change
+ * between any two calls, and the daemon is the single source of truth for both.
+ */
+import { type EffectivePolicyDecision, type ListedToolDescriptor } from "@appduct/shared";
+import type { DaemonCall } from "./daemon-tools.js";
+export declare const LIST_TOOLS_TOOL_NAME = "appduct_list_tools";
+export declare const DESCRIBE_TOOL_TOOL_NAME = "appduct_describe_tool";
+export declare const CALL_TOOL_TOOL_NAME = "appduct_call_tool";
+/** Applied when `appduct_list_tools` gets no `limit`, so the first call on a large app returns a
+ * page, not the whole registry; `total` tells the agent how much it left out. */
+export declare const DEFAULT_LIST_TOOLS_LIMIT = 50;
+export declare const LIST_TOOLS_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_list_tools";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Session alias or id. Omit to target the sole active/suspended session.";
+            };
+            readonly group: {
+                readonly type: "string";
+                readonly pattern: string;
+            };
+            readonly filter: {
+                readonly type: "string";
+                readonly maxLength: 256;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
+            readonly offset: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
+export declare const DESCRIBE_TOOL_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_describe_tool";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Session alias or id. Omit to target the sole active/suspended session.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly required: readonly ["name"];
+        readonly additionalProperties: false;
+    };
+};
+export declare const CALL_TOOL_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_call_tool";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Session alias or id. Omit to target the sole active/suspended session.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly args: {
+                readonly type: "object";
+            };
+            readonly timeoutMs: {
+                readonly type: "integer";
+                readonly minimum: 1000;
+                readonly maximum: 600000;
+            };
+        };
+        readonly required: readonly ["name"];
+        readonly additionalProperties: false;
+    };
+};
+/** One app tool resolved against a live session, with everything `appduct_call_tool` needs to
+ * run it: the session id the call, its progress subscription and any cancel are routed by, the
+ * alias shown to people, the descriptor (for its name and declared deadline), and the effective
+ * policy (for whether to ask for consent). */
+export type ResolvedAppTool = {
+    sessionId: string;
+    alias: string;
+    descriptor: ListedToolDescriptor;
+    policy: EffectivePolicyDecision;
+};
+export type CallToolArgs = {
+    selector?: string;
+    name: string;
+    args: Record<string, unknown>;
+    timeoutMs?: number;
+};
+export declare const handleListToolsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
+    groups?: import("@appduct/shared").ToolGroupSummary[] | undefined;
+    tools: {
+        annotations?: import("@appduct/shared").ToolAnnotations | undefined;
+        name: string;
+        signature: string;
+        summary: string;
+        group: string | null;
+        policy: EffectivePolicyDecision;
+    }[];
+    offset?: {} | undefined;
+    limit: {};
+    filter?: {} | undefined;
+    group?: {} | undefined;
+    session: string;
+    total: number;
+}>;
+export declare const handleDescribeToolTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
+    name: string;
+    description: string;
+    input_schema?: import("@appduct/shared").ToolSchemaDescriptor | undefined;
+    output_schema?: import("@appduct/shared").ToolSchemaDescriptor | undefined;
+    annotations?: import("@appduct/shared").ToolAnnotations | undefined;
+    timeout_ms?: number | undefined;
+    group: string | null;
+    session: string;
+    signature: string;
+    policy: EffectivePolicyDecision;
+}>;
+export declare const parseCallToolArgs: (rawArgs: unknown) => CallToolArgs;
+/**
+ * The deadline a call runs under: the tool's own (`clampTimeout` folds in the 10 s default for a
+ * tool that declares none), or a shorter one the caller asked for. Never longer: the `tool_call`
+ * frame carries no deadline, so the app stops the handler at the tool's own deadline whatever the
+ * daemon waits for (docs/PROTOCOL.md), and a longer caller deadline would only turn a clear
+ * `tool_timeout` into the same timeout after a retry that ran the tool again.
+ */
+export declare const resolveCallDeadline: (tool: ResolvedAppTool, requestedTimeoutMs: number | undefined) => number;
+export declare const resolveAppTool: (call: DaemonCall, selector: string | undefined, name: string) => Promise<ResolvedAppTool>;

package/dist/mcp/connect-tool.d.ts

@@ -29,7 +29,7 @@ export declare const CONNECT_TOOL_DESCRIPTOR: {
             readonly device: {
                 readonly type: "string";
             };
-            readonly bundleId: {
+            readonly appId: {
                 readonly type: "string";
             };
             readonly relaunch: {
@@ -63,10 +63,10 @@ export declare const WAIT_FOR_SESSION_TOOL_DESCRIPTOR: {
 };
 /** Errors from the built-in management tools reuse the daemon's wire `ErrorType` union
  * (`RpcApplicationError`-style: `{ type, message }`) so the MCP server's generic error-content
- * mapping (see `server.ts`) handles them the same way it handles a proxied device tool's error. */
+ * mapping (see `server.ts`) handles them the same way it handles an app tool's error. */
 export declare class McpBuiltinToolError extends Error {
-    readonly type: "invalid_request" | "tool_timeout" | "tool_execution_error";
-    constructor(type: "invalid_request" | "tool_timeout" | "tool_execution_error", message: string);
+    readonly type: "invalid_request" | "tool_not_found" | "tool_timeout" | "tool_cancelled" | "tool_execution_error" | "connection_error";
+    constructor(type: "invalid_request" | "tool_not_found" | "tool_timeout" | "tool_cancelled" | "tool_execution_error" | "connection_error", message: string);
 }
 export type ConnectToolDeps = {
     call: DaemonCall;
@@ -77,9 +77,16 @@ export type ConnectToolDeps = {
     /** Every location `scheme.ts` consulted, named in the failure below so an agent can tell its
      * human exactly where to put a scheme instead of guessing at one global file. */
     schemeTried?: string[];
-    /** `config.json`'s `iosBundleId`, the default for the experimental `ios-device` target when the
-     * call did not pass `bundleId`. Same source order as `scheme`. */
-    iosBundleId?: string;
+    /** Where the project `.appduct/config.json` walk-up starts when resolving an `appId` for
+     * `target: "android"`/`"ios-device"` (`scheme.ts`'s `resolveAppId`) — unlike `scheme`, this is
+     * resolved fresh on every call rather than once at startup, since which platform's `appId.<key>`
+     * is needed depends on the call's (or auto-detection's) target. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** The state directory in use, so the `appId` walk-up can never mistake it for a project config
+     * — the same exclusion `resolveScheme` is given at server startup (`commands/mcp.ts`). Without
+     * it, an operator who points `--state-dir` at a directory on the walk-up path would have that
+     * *global* file read at the project tier, inverting the documented precedence. */
+    stateDirRoot?: string;
     exec?: ExecFn;
     env?: NodeJS.ProcessEnv;
 };
@@ -112,4 +119,3 @@ export type WaitForSessionToolResult = {
     alias: string;
 };
 export declare const handleWaitForSessionTool: (rawArgs: unknown, deps: WaitForSessionToolDeps) => Promise<WaitForSessionToolResult>;
-//# sourceMappingURL=connect-tool.d.ts.map

package/dist/mcp/daemon-tools.d.ts

@@ -1,13 +1,4 @@
-/**
- * Fetches the effective (possibly namespaced) MCP tool list live from the daemon
- * (ARCHITECTURE.md §9): `sessions.list` for the live sessions, then `tools.list` per session.
- * There is no caching here — every `tools/list` request and every list-changed check re-fetches,
- * since the daemon's session/registry state is the single source of truth and can change between
- * any two calls.
- */
-import { type NamespacedTool } from "./tool-namespace.js";
 /** A method call against the daemon RPC — satisfied by both `callDaemon` (bound to a method+params)
- * and `DaemonStream.call` from `rpc/client.ts`. */
+ * and `DaemonStream.call` from `rpc/client.ts`. The MCP server's built-in tools take one of these
+ * rather than a whole stream, so they can be tested against a fake. */
 export type DaemonCall = <TResult>(method: string, params?: unknown) => Promise<TResult>;
-export declare const fetchEffectiveTools: (call: DaemonCall) => Promise<NamespacedTool[]>;
-//# sourceMappingURL=daemon-tools.d.ts.map

package/dist/mcp/events-tool.d.ts

@@ -108,4 +108,3 @@ export type WaitForEventToolResult = {
     seq: number;
 };
 export declare const handleWaitForEventTool: (rawArgs: unknown, deps: WaitForEventToolDeps) => Promise<WaitForEventToolResult>;
-//# sourceMappingURL=events-tool.d.ts.map

package/dist/mcp/server.d.ts

@@ -1,28 +1,45 @@
 /**
- * The `appduct mcp` stdio MCP server (ARCHITECTURE.md §9): a thin proxy that maps the daemon RPC
- * surface (`rpc/client.ts`, same auto-spawning client the CLI uses) onto MCP's `tools/list`,
- * `tools/call`, `notifications/tools/list_changed`, progress notifications, and one resource
+ * The `appduct mcp` stdio MCP server (ARCHITECTURE.md §9): a thin proxy over the daemon RPC surface
+ * (`rpc/client.ts`, same auto-spawning client the CLI uses). `tools/list` is a fixed set of
+ * built-in tools; the app's own tools are reached through `appduct_list_tools`,
+ * `appduct_describe_tool` and `appduct_call_tool` (`app-tools.ts`), mirroring the CLI, never
+ * listed as MCP tools themselves. Also progress notifications, cancellation, and one resource
  * (`appduct://sessions`). All logging here goes to stderr only — stdout is reserved for the MCP
  * transport's protocol frames.
  *
  * One persistent daemon connection (`stream`) is used for everything except progress-correlated
- * `tools.call`s, which get their own short-lived connection (see `callProxiedTool` below) so the
+ * `tools.call`s, which get their own short-lived connection (see `callAppTool` below) so the
  * `tool_call_started` event that reveals the call's `callId` is unambiguous.
  *
- * This is also where both `"prompt"`-policy consent channels live (ARCHITECTURE.md §12):
- * `resolveToolCallConsent` prefers `elicitation/create` (issue #10, any client that declares the
- * `elicitation` capability) over the `_meta["anthropic/requiresUserInteraction"]` flag (issue #14,
- * Claude Code ≥ v2.1.199 only), and the two never arm for the same call — see
- * `clientSupportsElicitation` and the `tools/list` handler below.
+ * This is also where the `"prompt"`-policy consent channel lives (ARCHITECTURE.md §12):
+ * `resolveToolCallConsent` asks the human via `elicitation/create` (issue #10) when the client
+ * declared the `elicitation` capability. A client that didn't gets no consent marker, so the
+ * daemon's `"prompt"` gate denies the call (`policy_denied`, reason `no_consent_channel`).
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { ExecFn } from "../cli/open-target.js";
-import { type SpawnFn, type VersionCheckOptions } from "../rpc/client.js";
+import { type DaemonStream, type SpawnFn, type VersionCheckOptions } from "../rpc/client.js";
 export declare const SESSIONS_RESOURCE_URI = "appduct://sessions";
+/**
+ * How this server opens a daemon connection. Both the startup stream and each short-lived
+ * progress stream go through it, so a caller can put something other than a real daemon on the
+ * other end. The only production implementation is {@link openDaemonStream}; the seam exists so
+ * the behaviour that is purely this module's own — the built-in tools, consent, progress and
+ * cancellation — can be tested without a TLS listener, a pidfile and a
+ * subprocess, none of which those behaviours depend on.
+ */
+export type OpenDaemonStreamFn = (options: {
+    stateDir: string;
+    spawn?: SpawnFn;
+    checkVersion?: VersionCheckOptions;
+}) => Promise<DaemonStream>;
 export type CreateMcpServerOptions = {
     stateDir: string;
     spawn?: SpawnFn;
+    /** Overrides how daemon connections are opened; defaults to {@link openDaemonStream}. Test-only
+     * seam — every real caller (`cli/mcp-command.ts`) leaves it unset. */
+    openStream?: OpenDaemonStreamFn;
     /**
      * Daemon/CLI version check (issue #30), applied to the startup stream only — never to the
      * short-lived progress streams below, which must never restart the daemon out from under a call
@@ -39,9 +56,12 @@ export type CreateMcpServerOptions = {
     /** Every location consulted while resolving {@link scheme}, so `appduct_connect` can name
      * them when it has to fail. Only meaningful when `scheme` is undefined. */
     schemeTried?: string[];
-    /** `config.json`'s `iosBundleId`; the default bundle id for `appduct_connect`'s experimental
-     * `ios-device` target (issue #31). */
-    iosBundleId?: string;
+    /** Where `appduct_connect` resolves an `appId` from (its project `.appduct/config.json`
+     * walk-up); see `ConnectToolDeps.cwd`. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** The state directory in use, excluded from that walk-up exactly as it is from `scheme`'s.
+     * See `ConnectToolDeps.stateDirRoot`. */
+    stateDirRoot?: string;
     exec?: ExecFn;
     env?: NodeJS.ProcessEnv;
     /** Overrides `ELICITATION_TIMEOUT_MS` (ARCHITECTURE.md §12 / issue #10) — test-only seam so the
@@ -55,4 +75,3 @@ export type McpServerHandle = {
     close: () => Promise<void>;
 };
 export declare const createMcpServer: (options: CreateMcpServerOptions) => Promise<McpServerHandle>;
-//# sourceMappingURL=server.d.ts.map

package/dist/native-scheme.d.ts

@@ -56,4 +56,3 @@ export type NativeSchemeDiscovery = {
  * every location this looked without the caller needing to know which probes exist.
  */
 export declare const discoverNativeScheme: (root: string) => Promise<NativeSchemeDiscovery>;
-//# sourceMappingURL=native-scheme.d.ts.map

package/dist/output.d.ts

@@ -1,9 +1,13 @@
 import { type EventNotification } from "@appduct/shared";
 import type { CliResult } from "./cli/result-types.js";
+import { type GlobalFlags } from "./cli/global-flags.js";
 export type RenderOptions = {
     command: string;
-    json: boolean;
-    color: boolean;
+    flags: GlobalFlags;
+    /** "Now", for the one renderer (`ls`'s Age column) that needs a reference time absent `meta`
+     * (which is only attached under `--verbose`). Defaults to the wall clock when omitted, matching
+     * the pre-`--verbose` fallback behavior for a caller that doesn't care (e.g. non-`ls` tests). */
+    now?: Date;
     /** `link`-only: also render the deep link as terminal QR art (never affects `--json` output). */
     qr?: boolean;
     /** `tools`-only: render full schemas/annotations for every listed tool, not just name+description. */
@@ -14,15 +18,8 @@ export declare const renderResult: (result: CliResult<unknown>, options: RenderO
     stderr?: string;
 };
 /** Renders one `appduct events` line: NDJSON under `--json`, a compact human line otherwise. */
-export declare const renderEventLine: (event: EventNotification, options: {
-    json: boolean;
-    color: boolean;
-}) => string;
+export declare const renderEventLine: (event: EventNotification, flags: GlobalFlags) => string;
 /** Renders the trailing cursor line for `appduct events --since` (issue #6): NDJSON under
  * `--json` so a scripted caller can parse the resume point without maxing `seq` over the printed
  * events (impossible when the response is empty), a human note otherwise. */
-export declare const renderEventsCursorLine: (cursor: number, options: {
-    json: boolean;
-    color: boolean;
-}) => string;
-//# sourceMappingURL=output.d.ts.map
+export declare const renderEventsCursorLine: (cursor: number, flags: GlobalFlags) => string;

package/dist/package-root.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Locates this package's root directory (the one holding `appduct`'s `package.json`) from
+ * wherever this module happens to be evaluated.
+ *
+ * The published build is bundled (`scripts/bundle.mjs`), so a module's location on disk is not
+ * its location in `src/`: this code may run from `src/…` under Vitest, from `dist/<entry>.js`, or
+ * from a shared chunk at `dist/<name>-<hash>.js`. A fixed `join(here, "..")` cannot be right in
+ * all three, so the root is found by walking up to the nearest `package.json` that names this
+ * package — at most a couple of `stat`s, done once per process.
+ */
+export declare const getPackageRoot: () => string;

package/dist/package-version.d.ts

@@ -27,4 +27,3 @@ export declare const getPackageVersion: () => string;
  * started in-process by a test picks up the environment that test set.
  */
 export declare const getDaemonReportedVersion: (env?: NodeJS.ProcessEnv) => string;
-//# sourceMappingURL=package-version.d.ts.map

package/dist/qr-terminal.d.ts

@@ -10,4 +10,3 @@ export type QrTerminalRenderOptions = {
  * Renders a QR payload as compact half-block terminal art (two modules per character row).
  */
 export declare const renderQrToTerminal: (content: string, options?: QrTerminalRenderOptions) => string;
-//# sourceMappingURL=qr-terminal.d.ts.map

package/dist/rpc/client.d.ts

@@ -1,7 +1,8 @@
 /**
  * The auto-spawning RPC client library (ARCHITECTURE.md §4, §5) used by the CLI, MCP server, and
- * tests to talk to `daemon.sock`. On `ENOENT`/`ECONNREFUSED` it takes an exclusive spawn-lock,
- * spawns `daemon run` detached, polls the socket until ready, then retries the request once.
+ * tests to talk to `daemon.sock`. On `ENOENT`/`ECONNREFUSED` it creates the state dir if it is
+ * missing, takes an exclusive spawn-lock, spawns `daemon run` detached, polls the socket until
+ * ready, then retries the request once.
  */
 import { type RpcErrorData } from "@appduct/shared";
 export type SpawnContext = {
@@ -134,4 +135,3 @@ export type DaemonStream = {
 export declare const openDaemonStream: (options: Omit<CallDaemonOptions, "requestTimeoutMs"> & {
     requestTimeoutMs?: number;
 }) => Promise<DaemonStream>;
-//# sourceMappingURL=client.d.ts.map

package/dist/scheme.d.ts

@@ -33,7 +33,9 @@
  * project file (`native-scheme.ts`'s doc comment has the detail). Dynamic-config projects use
  * `--scheme`, `APPDUCT_SCHEME`, or a project `.appduct/config.json` instead.
  *
- * A project `.appduct/config.json` carries client-side keys only (`scheme` today). It never
+ * A project `.appduct/config.json` carries client-side keys only — `scheme` and, since issue #63,
+ * `appId.<platform>` (see {@link resolveAppId} below, which mirrors this module's shape but with a
+ * shorter order: no environment-variable tier and no filesystem-discovery tier). It never
  * redirects the state directory — `--state-dir` / `APPDUCT_STATE_DIR` remain the only way to do
  * that — so a project file can never move the daemon's key, socket or audit log.
  */
@@ -142,6 +144,23 @@ export declare const findProjectConfig: (startDir: string, options?: ProjectConf
  * accepting (say) `keyPath` here would let a checked-in file redirect the daemon's key material.
  */
 export declare const readProjectConfigScheme: (path: string) => Promise<string | undefined>;
+/** A target's platform, and the key it reads under `appId` in a project config — `"ios"` for
+ * `ios-device`, `"android"` for `android`. See `cli/open-target.ts`'s `platformOf`, the single
+ * place a delivery target is mapped to one of these. */
+export type AppIdPlatform = "ios" | "android";
+/**
+ * Reads `appId.<platform>` out of a project `.appduct/config.json`. Same stance as
+ * {@link readProjectConfigScheme}: this is Appduct's own file, so anything wrong with the `appId`
+ * block is a hard error rather than a silent fall-through, including an unknown key inside it — a
+ * typo'd `"andriod"` must read as "this file is broken", not as "no Android app id was recorded",
+ * which would otherwise look exactly like a project that simply hasn't set one up yet.
+ *
+ * Deliberately does *not* apply `cli/open-target.ts`'s `isValidAppId` charset check here: that
+ * check guards an argv/remote-shell hazard at the point a value is actually used, the same
+ * arrangement the old `iosBundleId` config key had. A structurally well-formed but wrong-for-its-
+ * platform id is caught there instead, with the command that needed it named in the error.
+ */
+export declare const readProjectConfigAppId: (path: string, platform: AppIdPlatform) => Promise<string | undefined>;
 export type ResolveSchemeOptions = {
     /** `--scheme` (or a programmatic `scheme` option) — highest precedence. */
     flagScheme?: string;
@@ -178,4 +197,43 @@ export declare const resolveScheme: (options?: ResolveSchemeOptions) => Promise<
 export declare const describeMissingScheme: (tried: string[]) => string;
 /** {@link resolveScheme}, throwing {@link usageError} with {@link describeMissingScheme} when nothing matched. */
 export declare const resolveSchemeOrThrow: (options?: ResolveSchemeOptions) => Promise<string>;
-//# sourceMappingURL=scheme.d.ts.map
+/** Which step of {@link resolveAppId}'s order produced the app id. */
+export type AppIdSource = "flag" | "project-config";
+export type ResolvedAppId = {
+    /** Undefined when no source produced one; `tried` then explains where we looked. */
+    appId?: string;
+    source?: AppIdSource;
+    /** Human-readable descriptions of every location consulted, in order, for error messages. */
+    tried: string[];
+};
+export type ResolveAppIdOptions = {
+    /** Which `appId.<platform>` key to read from a project config; see `cli/open-target.ts`'s
+     * `platformOf`. */
+    platform: AppIdPlatform;
+    /** `--app-id` (CLI `link`) / `appId` (MCP `appduct_connect`) / `appId` (`mintLink`, the
+     * `appduct/client` `link()`) — highest precedence, because the target is known at the call
+     * site. */
+    flagAppId?: string;
+    /** Where the project walk-up starts. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** The state directory root, so the walk-up never mistakes it for a project config. */
+    stateDirRoot?: string;
+    /** Overrides the home directory whose `.appduct` the walk-up skips (tests point this at a
+     * temp tree rather than the real `$HOME`). */
+    homeDir?: string;
+};
+/**
+ * Resolves an app id against the order the contract fixes: an explicit value first, then the
+ * nearest project `.appduct/config.json` declaring `appId.<platform>` (the same walk-up
+ * {@link resolveScheme} uses, via {@link findProjectConfigs}). Unlike {@link resolveScheme} there
+ * is no environment-variable tier and no filesystem-discovery tier (issue #63 leaves static
+ * discovery of an app id from `build.gradle`/`app.json` out of scope) — an app id that cannot be
+ * found either way is a plain usage error, not something worth guessing at.
+ */
+export declare const resolveAppId: (options: ResolveAppIdOptions) => Promise<ResolvedAppId>;
+/**
+ * The shared "no app id anywhere" message (issue #63). Every caller renders the same body — the
+ * CLI's `--app-id` guard, `mintLink`, and `appduct_connect` — so the three fixes it names (the
+ * flag, the MCP argument, and the project config `appduct init` writes) cannot drift between them.
+ */
+export declare const describeMissingAppId: (platform: AppIdPlatform, tried: string[]) => string;

package/dist/spki-pin.d.ts

@@ -1,3 +1,2 @@
 export declare const createSpkiPin: (spkiDer: Buffer) => string;
 export declare const getSpkiPinFromPrivateKeyPem: (keyPem: string) => string;
-//# sourceMappingURL=spki-pin.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appduct",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Driving React Native tools without in-app debug UI.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,11 +45,13 @@
     "reflect-metadata": "^0.2.2",
     "toqr": "^0.1.1",
     "ws": "^8.18.3",
-    "@appduct/shared": "0.10.0"
+    "@appduct/shared": "0.11.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.12",
+    "eslint": "^10",
     "typescript": "~5.9.2"
   },
   "files": [
@@ -57,8 +59,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/bundle.mjs",
     "clean": "rm -rf dist",
+    "lint": "eslint src",
     "test": "vitest run --config ../../vitest.config.ts src/__tests__",
     "typecheck": "tsc -p tsconfig.json"
   }

package/dist/artifact-inspect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"artifact-inspect.d.ts","sourceRoot":"","sources":["../src/artifact-inspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAQH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,CAAC;AACjD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE3D,MAAM,MAAM,eAAe,GACvB,wBAAwB,GACxB,uBAAuB,GACvB,qBAAqB,GACrB,0BAA0B,GAC1B,4BAA4B,GAC5B,iCAAiC,CAAC;AAEtC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB;;mCAE+B;IAC/B,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC;AAoDF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;YAEY;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE1F;;4EAE4E;AAC5E,eAAO,MAAM,iBAAiB,EAAE,YAgB/B,CAAC;AAiOF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,CAAC;AAEF;;;mEAGmE;AACnE,eAAO,MAAM,eAAe,GAC1B,cAAc,MAAM,EACpB,UAAS,sBAA2B,KACnC,OAAO,CAAC,kBAAkB,CA+C5B,CAAC"}