appduct 0.13.0 → 0.15.0

package/dist/link.d.ts

@@ -17,7 +17,7 @@
  * (`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 AgentEndpoint, type LinkCreateResult, type WebAttachParams, type WebAttachResult } from "@appduct/shared";
 import { type ExecFn, type OpenTarget } from "./cli/open-target.js";
 import { type SpawnFn } from "./rpc/client.js";
 /**
@@ -30,6 +30,40 @@ import { type SpawnFn } from "./rpc/client.js";
  * *after* the bootstrap blob, so anything reading `appduct=` must stop at the `&`.
  */
 export declare const composeDeepLink: (scheme: string, result: LinkCreateResult) => string;
+/** What a web target hands back instead of a deep link: the page URL to open, and the script to
+ * run in an already-open page. Both carry the same bootstrap payload. */
+export type WebLinkResult = {
+    sessionId: string;
+    /** The page URL with `#appduct=<payload>` appended (replacing any fragment it had). */
+    url: string;
+    script: string;
+    /** Unix seconds. */
+    expiresAt: number;
+};
+/** Throws a usage error unless `pageUrl` is an http(s) URL. Called before a link is minted, so a
+ * bad URL does not strand a pending link. */
+export declare const assertWebPageUrl: (pageUrl: string) => void;
+/** Composes the web target's result from a `link.create` result minted with `transport: "web"`. */
+export declare const composeWebLink: (pageUrl: string, result: LinkCreateResult) => WebLinkResult;
+export type MintWebLinkOptions = {
+    stateDir: string;
+    spawn?: SpawnFn;
+    autoSpawn?: boolean;
+    ttlSeconds?: number;
+    /** The page the link will be opened in. */
+    url: string;
+};
+/** Mints a link only the web listener accepts. Needs no scheme: a web page is reached by URL. */
+export declare const mintWebLink: (options: MintWebLinkOptions) => Promise<WebLinkResult>;
+export type AttachWebTabOptions = WebAttachParams & {
+    stateDir: string;
+    spawn?: SpawnFn;
+    autoSpawn?: boolean;
+};
+/** Asks the daemon to attach a tab of the debugging-port browser at `browserUrl` and claim a session on it. */
+export declare const attachWebTab: ({ stateDir, spawn, autoSpawn, ...params }: AttachWebTabOptions) => Promise<WebAttachResult & {
+    attached: true;
+}>;
 export type MintLinkOptions = {
     stateDir: string;
     spawn?: SpawnFn;

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

@@ -107,12 +107,30 @@ export type ResolvedAppTool = {
     descriptor: ListedToolDescriptor;
     policy: EffectivePolicyDecision;
 };
+type ResolvedSession = {
+    sessionId: string;
+    alias: string;
+};
 export type CallToolArgs = {
     selector?: string;
     name: string;
     args: Record<string, unknown>;
     timeoutMs?: number;
 };
+/** Every key an agent sends must be one the tool declares. A misspelled key (`arguments` for
+ * `args`, `timeout_ms` for `timeoutMs`) would otherwise be dropped silently, and the tool would run
+ * without what the agent meant to pass. */
+export declare const rejectUnknownKeys: (args: Record<string, unknown>, tool: string, allowed: readonly string[]) => void;
+/** `null` counts as absent for every optional field: some clients fill unset optional
+ * parameters with `null` rather than leaving them out. */
+export declare const asOptionalString: (value: unknown, field: string) => string | undefined;
+/** Resolves `selector` (an alias, a session id, or nothing) to one concrete session first, with
+ * the daemon's own rules and errors (`no_session`, `ambiguous_session`, `unknown_session`).
+ * Everything after that is routed by the **session id**, never the alias: the daemon frees an
+ * alias when a session ends and gives it to the next device of the same model, so routing by alias
+ * could land a call — one the user may already have approved — on a different device. If the
+ * session goes away mid-call, the next daemon call fails with `unknown_session` instead. */
+export declare const resolveSession: (call: DaemonCall, selector: string | undefined) => Promise<ResolvedSession>;
 export declare const handleListToolsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
     groups?: import("@appduct/shared").ToolGroupSummary[] | undefined;
     tools: {
@@ -152,3 +170,4 @@ export declare const parseCallToolArgs: (rawArgs: unknown) => CallToolArgs;
  */
 export declare const resolveCallDeadline: (tool: ResolvedAppTool, requestedTimeoutMs: number | undefined) => number;
 export declare const resolveAppTool: (call: DaemonCall, selector: string | undefined, name: string) => Promise<ResolvedAppTool>;
+export {};

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

@@ -11,7 +11,9 @@
  * caller asked for it with `target: "none"`), where it carries explicit instructions telling the
  * agent to show the code and ask.
  */
+import { type WebAttachResult } from "@appduct/shared";
 import { type ExecFn, type OpenTarget } from "../cli/open-target.js";
+import { type WebLinkResult } from "../link.js";
 import { type SpawnFn } from "../rpc/client.js";
 import type { DaemonCall } from "./daemon-tools.js";
 export declare const CONNECT_TOOL_NAME = "appduct_connect";
@@ -24,7 +26,16 @@ export declare const CONNECT_TOOL_DESCRIPTOR: {
         readonly properties: {
             readonly target: {
                 readonly type: "string";
-                readonly enum: readonly ["android", "ios-sim", "ios-device", "none"];
+                readonly enum: readonly ["android", "ios-sim", "ios-device", "none", "web"];
+            };
+            readonly url: {
+                readonly type: "string";
+            };
+            readonly browserUrl: {
+                readonly type: "string";
+            };
+            readonly targetId: {
+                readonly type: "string";
             };
             readonly device: {
                 readonly type: "string";
@@ -108,7 +119,9 @@ export type ConnectToolResult = {
     /** Present only on the QR path: what the agent must do before waiting. See {@link QR_INSTRUCTIONS}. */
     instructions?: string;
 };
-export declare const handleConnectTool: (rawArgs: unknown, deps: ConnectToolDeps) => Promise<ConnectToolResult>;
+export declare const handleConnectTool: (rawArgs: unknown, deps: ConnectToolDeps) => Promise<ConnectToolResult | WebLinkResult | (WebAttachResult & {
+    attached: true;
+})>;
 export type WaitForSessionToolDeps = {
     stateDir: string;
     spawn?: SpawnFn;

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

@@ -12,12 +12,40 @@
 import { type AppEvent } from "@appduct/shared";
 import { type SpawnFn } from "../rpc/client.js";
 import type { DaemonCall } from "./daemon-tools.js";
+export declare const LIST_EVENTS_TOOL_NAME = "appduct_list_events";
 export declare const EVENTS_TOOL_NAME = "appduct_events";
 export declare const WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
 /** Server-side cap on `timeoutMs` (issue #6's "Cap timeoutMs server-side below the idle window
  * rather than trusting the caller") — a pure function so the cap's boundary behavior is
  * unit-testable without spinning up a daemon or actually waiting out either bound. */
 export declare const clampWaitForEventTimeoutMs: (requestedMs: number | undefined) => number;
+export declare const LIST_EVENTS_TOOL_DESCRIPTOR: {
+    readonly name: "appduct_list_events";
+    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 limit: {
+                readonly type: "integer";
+                readonly exclusiveMinimum: 0;
+            };
+            readonly offset: {
+                readonly type: "integer";
+                readonly minimum: 0;
+            };
+        };
+        readonly additionalProperties: false;
+    };
+};
 export declare const EVENTS_TOOL_DESCRIPTOR: {
     readonly name: "appduct_events";
     readonly description: string;
@@ -78,6 +106,17 @@ export declare const WAIT_FOR_EVENT_TOOL_DESCRIPTOR: {
 export type EventsToolDeps = {
     call: DaemonCall;
 };
+export declare const handleListEventsTool: (rawArgs: unknown, call: DaemonCall) => Promise<{
+    session: string;
+    total: number;
+    limit: {};
+    events: {
+        payload_schema?: import("@appduct/shared").EventSchemaDescriptor | undefined;
+        name: string;
+        signature: string;
+        description: string;
+    }[];
+}>;
 export type EventsToolResult = {
     events: AppEvent[];
     cursor: number;

package/dist/native-scheme.d.ts

@@ -1,6 +1,5 @@
 /**
- * Static-file scheme discovery for plain iOS (Xcode) and Android (Gradle) apps
- * (docs/tasks/20-cli-native-scheme-discovery.md, phase 3 of issue #48).
+ * Static-file scheme discovery for plain iOS (Xcode) and Android (Gradle) apps.
  *
  * `scheme.ts`'s `resolveScheme` treats this module as one more thing to try after `<cwd>/app.json`
  * — it never walks up (an app root is where these commands run, same rule as `app.json`), and,
@@ -8,6 +7,8 @@
  * `xcodebuild`, no Gradle evaluation. Every probe is a plain read of a well-known project file,
  * parsed defensively:
  *
+ * - Flutter (a root with a `pubspec.yaml`): the Android probes below read `android/app/…` instead
+ *   of `app/…`; the iOS walk already reaches `ios/Runner` and `macos/Runner`.
  * - Android: `app/build.gradle.kts` / `app/build.gradle` for a `manifestPlaceholders["appductScheme"]`
  *   (or `.appductScheme =`) assignment, then `app/src/main/AndroidManifest.xml` for the first
  *   `<data android:scheme>` inside an intent filter that also declares
@@ -35,19 +36,22 @@ export type NativeSchemeProbeResult = {
     origin: string;
 };
 export type NativeSchemeDiscovery = {
-    /** `undefined` when no probe resolved a scheme. */
-    result?: NativeSchemeProbeResult;
+    /** Every probe that resolved a scheme, in probe order (all agree on the scheme, or discovery
+     * throws). Empty when none did. */
+    results: NativeSchemeProbeResult[];
     /** Every probe's human-readable description, in order, for {@link describeMissingScheme}-style
      * reporting — always as many entries as there are probes, whether or not any of them hit. */
     tried: string[];
 };
+/** Whether `root` is a Flutter project root: it has a `pubspec.yaml`. */
+export declare const isFlutterProject: (root: string) => Promise<boolean>;
 /**
  * Runs every static-file probe against `root` (never walking up — same rule as `app.json`) and
  * decides the result:
  *
- * - No probe resolves a scheme: `result` is `undefined`.
- * - Every probe that resolves one agrees: that scheme wins, attributed to whichever probe ran
- *   first (the order in {@link PROBES}).
+ * - No probe resolves a scheme: `results` is empty.
+ * - Every probe that resolves one agrees: `results` holds each of them in the order of
+ *   {@link PROBES}, so a caller can see every platform the project spans, not one winner.
  * - Two probes resolve *different* schemes: throws a usage error naming both sources and their
  *   values, since guessing which one is right would silently target the wrong app on one
  *   platform.

package/dist/scheme.d.ts

@@ -39,7 +39,7 @@
  * 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.
  */
-import { type NativeSchemeSource } from "./native-scheme.js";
+import { type NativeSchemeProbeResult, type NativeSchemeSource } from "./native-scheme.js";
 /** The directory a project-level config lives in, relative to an app root. */
 export declare const PROJECT_CONFIG_DIR = ".appduct";
 /** The project-level config filename, inside {@link PROJECT_CONFIG_DIR}. */
@@ -85,6 +85,10 @@ export type StaticProjectSchemeDiscovery = {
      * it) — distinct from `tried` below, which lists every location whether or not it hit. Only set
      * alongside `scheme`. */
     origin?: string;
+    /** Every native-project probe that resolved a scheme, in probe order — `scheme`, `source` and
+     * `origin` are the first of them. Empty when `app.json` answered (the native probes do not run)
+     * or nothing did; the platforms a project spans are read from here. */
+    nativeResults: NativeSchemeProbeResult[];
     /** Every location this step consulted, in order: `app.json` first (unchanged from pre-#48), then
      * every `native-scheme.ts` probe — always present, hit or miss, one entry each. */
     tried: string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appduct",
-  "version": "0.13.0",
-  "description": "Driving React Native tools without in-app debug UI.",
+  "version": "0.15.0",
+  "description": "Call functions inside your running iOS, Android or React Native app from a terminal, test or AI agent.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,6 +24,8 @@
   },
   "keywords": [
     "appduct",
+    "ios",
+    "android",
     "react-native",
     "agent"
   ],
@@ -45,14 +47,22 @@
     "reflect-metadata": "^0.2.2",
     "toqr": "^0.1.1",
     "ws": "^8.18.3",
-    "@appduct/shared": "0.13.0"
+    "@appduct/shared": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "~19.1.17",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.25.12",
     "eslint": "^10",
-    "typescript": "~5.9.2"
+    "playwright-core": "1.56.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "typescript": "~5.9.2",
+    "vite": "^8.1.4",
+    "webpack": "^5.111.1",
+    "@appduct/react-native": "0.15.0",
+    "@appduct/web": "0.15.0"
   },
   "files": [
     "bin.js",
@@ -62,7 +72,7 @@
     "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__",
+    "test": "vitest run src/__tests__",
     "typecheck": "tsc -p tsconfig.json"
   }
 }