appduct 0.14.0 → 0.15.0

package/dist/cli/routes/init.js

@@ -97,7 +97,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
   // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
   // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -213,14 +213,98 @@ var APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 var isValidAppId = (value) => APP_ID_PATTERN.test(value);
 var invalidAppIdMessage = (value) => `"${value}" is not a valid app id (letters, digits, ".", "_" and "-", starting with a letter or digit).`;
 
+// src/native-scheme.ts
+import { readdir, readFile as readFile2, stat } from "node:fs/promises";
+import { join as join4 } from "node:path";
+
 // src/scheme.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname as dirname2, join as join4, resolve } from "node:path";
+import { dirname as dirname2, join as join3, resolve } from "node:path";
+var PROJECT_CONFIG_DIR = ".appduct";
+var PROJECT_CONFIG_FILENAME = "config.json";
+var PROJECT_CONFIG_RELATIVE_PATH = join3(PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+var APP_JSON_FILENAME = "app.json";
+var SCHEME_ENV_VAR = "APPDUCT_SCHEME";
+var SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*$/u;
+var isValidScheme = (value) => SCHEME_PATTERN.test(value);
+var requireValidScheme = (value, origin) => {
+  if (!isValidScheme(value)) {
+    throw usageError(
+      `Invalid deep-link scheme ${JSON.stringify(value)} from ${origin}: a scheme must start with a letter and contain only letters, digits, "+", "-" or "." (for example "myapp") \u2014 do not include "://".`
+    );
+  }
+  return value;
+};
+var isPlainObject = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readJsonFile = async (path) => {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+      return void 0;
+    }
+    throw error;
+  }
+  try {
+    return { raw: JSON.parse(text) };
+  } catch (error) {
+    throw usageError(`Could not parse ${path}: ${error.message}`);
+  }
+};
+var firstConfiguredScheme = (value) => {
+  if (Array.isArray(value)) {
+    return value.find((entry) => typeof entry === "string" && entry.length > 0);
+  }
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+var discoverExpoScheme = async (dir) => {
+  const path = join3(resolve(dir), APP_JSON_FILENAME);
+  const file = await readJsonFile(path);
+  if (!file || !isPlainObject(file.raw)) {
+    return void 0;
+  }
+  const expo = file.raw.expo;
+  if (!isPlainObject(expo)) {
+    return void 0;
+  }
+  const scheme = firstConfiguredScheme(expo.scheme);
+  return scheme === void 0 ? void 0 : requireValidScheme(scheme, `"expo.scheme" in ${path}`);
+};
+var discoverStaticProjectScheme = async (cwd) => {
+  const appJsonPath = join3(resolve(cwd), APP_JSON_FILENAME);
+  const tried = [`${appJsonPath} ("expo.scheme")`];
+  const appJsonScheme = await discoverExpoScheme(cwd);
+  if (appJsonScheme !== void 0) {
+    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, nativeResults: [], tried };
+  }
+  const native = await discoverNativeScheme(resolve(cwd));
+  tried.push(...native.tried);
+  const [first] = native.results;
+  if (first !== void 0) {
+    return {
+      scheme: first.scheme,
+      source: first.source,
+      origin: first.origin,
+      nativeResults: native.results,
+      tried
+    };
+  }
+  return { nativeResults: [], tried };
+};
+var globalConfigDirs = (options = {}) => {
+  const excluded = /* @__PURE__ */ new Set([join3(resolve(options.homeDir ?? homedir()), PROJECT_CONFIG_DIR)]);
+  if (options.stateDirRoot !== void 0) {
+    excluded.add(resolve(options.stateDirRoot));
+  }
+  return excluded;
+};
 
 // src/native-scheme.ts
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join as join3 } from "node:path";
 var MAX_PROBE_FILE_BYTES = 2 * 1024 * 1024;
 var MAX_PLIST_WALK_DEPTH = 2;
 var MAX_WALK_ENTRIES = 5e3;
@@ -247,7 +331,7 @@ var readCappedBuffer = async (path) => {
     return { ok: false, reason: "too-large" };
   }
   try {
-    return { ok: true, data: await readFile(path) };
+    return { ok: true, data: await readFile2(path) };
   } catch {
     return { ok: false, reason: "unreadable" };
   }
@@ -267,7 +351,7 @@ var extractGradleScheme = (text) => {
   return value !== void 0 && value.length > 0 ? value : void 0;
 };
 var probeAndroidGradle = async (root) => {
-  const candidates = [join3(root, "app", "build.gradle.kts"), join3(root, "app", "build.gradle")];
+  const candidates = [join4(root, "app", "build.gradle.kts"), join4(root, "app", "build.gradle")];
   const notes = [];
   for (const candidate of candidates) {
     const read = await readCappedText(candidate);
@@ -314,7 +398,7 @@ var extractManifestScheme = (xml) => {
   return void 0;
 };
 var probeAndroidManifest = async (root) => {
-  const manifestPath = join3(root, "app", "src", "main", "AndroidManifest.xml");
+  const manifestPath = join4(root, "app", "src", "main", "AndroidManifest.xml");
   const read = await readCappedText(manifestPath);
   const description = `${manifestPath} (first <data android:scheme> in a VIEW intent-filter)`;
   if (!read.ok) {
@@ -454,12 +538,12 @@ var walkForFilename = async (root, filename, maxDepth) => {
           continue;
         }
         if (depth < maxDepth) {
-          await walk(join3(dir, entry.name), depth + 1);
+          await walk(join4(dir, entry.name), depth + 1);
         }
         continue;
       }
       if (entry.isFile() && entry.name === filename) {
-        hits.push({ path: join3(dir, entry.name), depth });
+        hits.push({ path: join4(dir, entry.name), depth });
       }
     }
   };
@@ -513,7 +597,7 @@ var extractProjectYmlScheme = (text) => {
   return raw !== void 0 && raw.length > 0 ? raw : void 0;
 };
 var probeIosProjectYml = async (root) => {
-  const path = join3(root, "project.yml");
+  const path = join4(root, "project.yml");
   const description = `${path} ("info.properties.CFBundleURLTypes" > "CFBundleURLSchemes")`;
   const read = await readCappedText(path);
   if (!read.ok) {
@@ -532,23 +616,34 @@ var probeIosProjectYml = async (root) => {
   };
 };
 var PROBES = [
-  probeAndroidGradle,
-  probeAndroidManifest,
-  probeIosInfoPlist,
-  probeIosProjectYml
+  ["android", probeAndroidGradle],
+  ["android", probeAndroidManifest],
+  ["ios", probeIosInfoPlist],
+  ["ios", probeIosProjectYml]
 ];
+var isFlutterProject = async (root) => {
+  return (await readCappedText(join4(root, "pubspec.yaml"))).ok;
+};
 var discoverNativeScheme = async (root) => {
   const tried = [];
   const results = [];
-  for (const probe of PROBES) {
-    const outcome = await probe(root);
-    tried.push(...outcome.tried);
-    if (outcome.result !== void 0) {
-      results.push(outcome.result);
+  const flutter = await isFlutterProject(root);
+  const androidRoot = flutter ? join4(root, "android") : root;
+  const iosRoots = flutter ? [join4(root, "ios"), join4(root, "macos")] : [root];
+  for (const [platform, probe] of PROBES) {
+    let roots = [root];
+    if (platform === "android") {
+      roots = [androidRoot];
+    } else if (probe === probeIosInfoPlist) {
+      roots = iosRoots;
+    }
+    for (const probeRoot of roots) {
+      const outcome = await probe(probeRoot);
+      tried.push(...outcome.tried);
+      if (outcome.result !== void 0) {
+        results.push(outcome.result);
+      }
     }
-  }
-  if (results.length === 0) {
-    return { tried };
   }
   const distinctSchemes = new Set(results.map((entry) => entry.scheme));
   if (distinctSchemes.size > 1) {
@@ -556,89 +651,7 @@ var discoverNativeScheme = async (root) => {
       "Conflicting deep-link schemes found in this project: " + results.map((entry) => `${entry.origin} says ${JSON.stringify(entry.scheme)}`).join(", but ") + ". Appduct will not guess which one is right \u2014 pass --scheme <scheme> to pick one."
     );
   }
-  return { result: results[0], tried };
-};
-
-// src/scheme.ts
-var PROJECT_CONFIG_DIR = ".appduct";
-var PROJECT_CONFIG_FILENAME = "config.json";
-var PROJECT_CONFIG_RELATIVE_PATH = join4(PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
-var APP_JSON_FILENAME = "app.json";
-var SCHEME_ENV_VAR = "APPDUCT_SCHEME";
-var SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*$/u;
-var isValidScheme = (value) => SCHEME_PATTERN.test(value);
-var requireValidScheme = (value, origin) => {
-  if (!isValidScheme(value)) {
-    throw usageError(
-      `Invalid deep-link scheme ${JSON.stringify(value)} from ${origin}: a scheme must start with a letter and contain only letters, digits, "+", "-" or "." (for example "myapp") \u2014 do not include "://".`
-    );
-  }
-  return value;
-};
-var isPlainObject = (value) => {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-};
-var readJsonFile = async (path) => {
-  let text;
-  try {
-    text = await readFile2(path, "utf8");
-  } catch (error) {
-    const code = error.code;
-    if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
-      return void 0;
-    }
-    throw error;
-  }
-  try {
-    return { raw: JSON.parse(text) };
-  } catch (error) {
-    throw usageError(`Could not parse ${path}: ${error.message}`);
-  }
-};
-var firstConfiguredScheme = (value) => {
-  if (Array.isArray(value)) {
-    return value.find((entry) => typeof entry === "string" && entry.length > 0);
-  }
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-};
-var discoverExpoScheme = async (dir) => {
-  const path = join4(resolve(dir), APP_JSON_FILENAME);
-  const file = await readJsonFile(path);
-  if (!file || !isPlainObject(file.raw)) {
-    return void 0;
-  }
-  const expo = file.raw.expo;
-  if (!isPlainObject(expo)) {
-    return void 0;
-  }
-  const scheme = firstConfiguredScheme(expo.scheme);
-  return scheme === void 0 ? void 0 : requireValidScheme(scheme, `"expo.scheme" in ${path}`);
-};
-var discoverStaticProjectScheme = async (cwd) => {
-  const appJsonPath = join4(resolve(cwd), APP_JSON_FILENAME);
-  const tried = [`${appJsonPath} ("expo.scheme")`];
-  const appJsonScheme = await discoverExpoScheme(cwd);
-  if (appJsonScheme !== void 0) {
-    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, tried };
-  }
-  const native = await discoverNativeScheme(resolve(cwd));
-  tried.push(...native.tried);
-  if (native.result !== void 0) {
-    return {
-      scheme: native.result.scheme,
-      source: native.result.source,
-      origin: native.result.origin,
-      tried
-    };
-  }
-  return { tried };
-};
-var globalConfigDirs = (options = {}) => {
-  const excluded = /* @__PURE__ */ new Set([join4(resolve(options.homeDir ?? homedir()), PROJECT_CONFIG_DIR)]);
-  if (options.stateDirRoot !== void 0) {
-    excluded.add(resolve(options.stateDirRoot));
-  }
-  return excluded;
+  return { results, tried };
 };
 
 // src/commands/init.ts
@@ -720,6 +733,60 @@ var readExistingAppId = (existing, path, platform, flagName, replaceable) => {
   }
   return value;
 };
+var MAX_MANIFEST_WALK_UP = 2;
+var declaresReactNative = async (root) => {
+  let directory = root;
+  for (let levelsUp = 0; levelsUp <= MAX_MANIFEST_WALK_UP; levelsUp += 1) {
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile3(join5(directory, "package.json"), "utf8"));
+    } catch {
+      manifest = void 0;
+    }
+    if (typeof manifest === "object" && manifest !== null) {
+      const declared = manifest;
+      const dependencies = [declared.dependencies, declared.devDependencies].flatMap(
+        (field) => typeof field === "object" && field !== null ? Object.keys(field) : []
+      );
+      return dependencies.includes("react-native") || dependencies.includes("expo");
+    }
+    const parent = dirname3(directory);
+    if (parent === directory) {
+      break;
+    }
+    directory = parent;
+  }
+  return false;
+};
+var discoveredPlatforms = (discovered) => {
+  const sources = discovered.nativeResults.map((entry) => entry.source);
+  return [
+    ...sources.some((source) => source.startsWith("android-")) ? ["android"] : [],
+    ...sources.some((source) => source.startsWith("ios-")) ? ["ios"] : []
+  ];
+};
+var wiringNextSteps = async (root, discovered, scheme, platforms) => {
+  if (discovered.source === "app-json" || await declaresReactNative(root)) {
+    return [
+      'Add `import "@appduct/react-native/auto";` to your app entry (index.js / App.tsx) \u2014 it is what starts the in-app agent endpoint.'
+    ];
+  }
+  const ios = "Forward every opened URL to Appduct: `_ = Appduct.shared.handle(url)` in SwiftUI's `.onOpenURL` (UIKit: `scene(_:openURLContexts:)`). It is what receives the connection link.";
+  const androidPlaceholder = `Check that \`app/build.gradle(.kts)\` sets \`manifestPlaceholders["appductScheme"] = "${scheme}"\` \u2014 Appduct's own activity receives the connection link on that scheme. Placeholders are fixed at build time, so rebuild and reinstall after changing one.`;
+  const androidOwnScheme = "Appduct receives links on the scheme in `manifestPlaceholders[\"appductScheme\"]` in `app/build.gradle(.kts)`. Give it a scheme of your own, not one your app already handles: on a shared scheme Appduct's activity can't tell your links from its own and yours stop reaching your app. That scheme is what the CLI opens too, so record it with `appduct init --scheme <scheme> --force` and rebuild. Both options: https://callstackincubator.github.io/appduct/install/android/#deep-links.";
+  const showIos = platforms.length === 0 || platforms.includes("ios");
+  const showAndroid = platforms.length === 0 || platforms.includes("android");
+  const gradleHit = discovered.nativeResults.some((entry) => entry.source === "android-gradle");
+  return [
+    ...showIos ? [ios] : [],
+    ...showAndroid ? [gradleHit ? androidPlaceholder : androidOwnScheme] : []
+  ];
+};
+var flutterNextSteps = (scheme) => [
+  "Add the package with `flutter pub add appduct`, then call `await Appduct.ensureInitialized();` in `main()` before `runApp` \u2014 it is what starts the in-app agent endpoint.",
+  `Register your URL scheme on each platform you run. Android: add an \`<intent-filter>\` to your activity in \`android/app/src/main/AndroidManifest.xml\` with the actions and categories \`android.intent.action.VIEW\`, \`android.intent.category.DEFAULT\` and \`android.intent.category.BROWSABLE\`, and \`<data android:scheme="${scheme}"/>\`. iOS and macOS: add \`CFBundleURLTypes\` > \`CFBundleURLSchemes\` to \`ios/Runner/Info.plist\` (and \`macos/Runner/Info.plist\`).`,
+  'Allow the connection to your computer. Android: add `<uses-permission android:name="android.permission.INTERNET"/>` to `android/app/src/main/AndroidManifest.xml` (Flutter only puts it in the debug and profile manifests, so a release build you opt in to Appduct needs it in the main one). iOS: add `NSLocalNetworkUsageDescription` to `ios/Runner/Info.plist`. macOS: set `com.apple.security.network.client` to `true` in both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`.'
+];
 var handleInitCommand = async (options, context = {}) => {
   const root = resolve2(context.cwd ?? process.cwd());
   const projectDir = join5(root, PROJECT_CONFIG_DIR);
@@ -778,6 +845,7 @@ var handleInitCommand = async (options, context = {}) => {
   const discovered = await discoverStaticProjectScheme(root);
   const discoveredScheme = discovered.scheme;
   const discoveredSourceLabel = discovered.source === void 0 ? void 0 : discovered.source === "app-json" ? "app.json" : discovered.source;
+  const platforms = discoveredPlatforms(discovered);
   const [scheme, source, origin] = (() => {
     if (options.scheme !== void 0) {
       return [options.scheme, "--scheme", void 0];
@@ -825,6 +893,7 @@ Run \`appduct init --scheme <scheme>\` with the scheme your app registers for de
       scheme,
       source,
       ...origin === void 0 ? {} : { origin },
+      ...platforms.length === 0 ? {} : { platforms },
       created: existing === void 0,
       changed: !alreadyCorrect,
       ...iosAppId === void 0 && androidAppId === void 0 ? {} : {
@@ -839,7 +908,7 @@ Run \`appduct init --scheme <scheme>\` with the scheme your app registers for de
         args: ["mcp", "--scheme", scheme]
       },
       nextSteps: [
-        'Add `import "@appduct/react-native/auto";` to your app entry (index.js / App.tsx) \u2014 it is what starts the in-app agent endpoint.',
+        ...await isFlutterProject(root) ? flutterNextSteps(scheme) : await wiringNextSteps(root, discovered, scheme, platforms),
         `Add the Appduct MCP server entry to your agent's MCP config. "--scheme ${scheme}" keeps that entry self-contained; ${SCHEME_ENV_VAR} and this ${PROJECT_CONFIG_RELATIVE_PATH} work too.`,
         "With the app running, pair a device: `appduct sessions link --open ios-sim` (or `--open android`).",
         ...origin === void 0 ? [] : [`Scheme "${scheme}" was read from ${origin}.`],
@@ -1197,6 +1266,36 @@ var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -1317,6 +1416,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],

package/dist/cli/routes/keygen.js

@@ -112,7 +112,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
   // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
   // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -646,6 +646,36 @@ var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -766,6 +796,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],