appduct 0.9.0

package/dist/artifact-inspect.js

@@ -0,0 +1,315 @@
+/**
+ * `appduct doctor` (docs/tasks/08-appduct-doctor.md): the artifact-level replacement for the
+ * runtime `debuggable`/`#if DEBUG` gate removed elsewhere in opt-in hardening. Given a built
+ * `.app`/`.ipa`/`.apk`/`.aab`, decide whether Appduct's native code actually shipped inside it —
+ * not whether the config that's supposed to have produced it looks right.
+ *
+ * The one property everything here is built around: **never report "absent" because a tool was
+ * missing or the artifact couldn't be read.** That failure mode is strictly worse than not having
+ * this check at all, because it turns a release gate into a rubber stamp that always exits 0 once
+ * `unzip` happens to be missing from a runner's image. Every path that can't produce a truthful
+ * answer throws {@link inspectionError} — a distinct, non-zero exit — instead of falling through to
+ * `present: false`.
+ *
+ * Detection strategy, and why no single signal is authoritative on either platform:
+ *
+ * - iOS: `present` is decided by real-code-only symbols alone, exactly like Android below —
+ *   `AppductCoreMarker` (`packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift`,
+ *   docs/tasks/14-native-core-extraction.md), an `@objc` class compiled only into the real
+ *   implementation, never into the SwiftPM package's `Stub/` branch, so its presence cannot be
+ *   confused with a stub build. `RCTNativeAppduct` (`RCT_EXPORT_MODULE`, see
+ *   `packages/react-native/ios/RCTNativeAppduct.mm`) is kept as a second real-code signal for
+ *   artifacts built before the marker existed. Both are Objective-C runtime metadata — they live in
+ *   `__objc_classname`/`__objc_data`, and `strip`/release optimization leaves them alone because
+ *   removing them would break `+[NSObject class]`-based dispatch. (A build that dead-strips the whole
+ *   translation unit for lack of `-ObjC`/`-force_load` could still drop them — these signals assume
+ *   the module actually links into the binary, which is the thing being checked in the first
+ *   place.) The plugin-authored `Info.plist` keys
+ *   (`AppductCliPins`/`AppductTrust`/`AppductAllowPrivateLanOnly`, docs/tasks/00-overview.md
+ *   "Native config keys the plugin writes") are reported as a corroborating signal only and can no
+ *   longer flip `present` to `true` on their own — an app author can write these keys by hand (or a
+ *   future stub could ship them) without the real implementation being present, exactly the reason
+ *   the Android signals below aren't all treated as equally authoritative either.
+ * - Android: the primary signal is `AppductNativeMarker`
+ *   (`packages/native/android/core/src/main/java/com/callstackincubator/appduct/AppductNativeMarker.kt`,
+ *   vendored into `@appduct/react-native` at `android/core/src/main/java/...`), a marker class with no
+ *   other purpose. Its fully-qualified name is kept unminified and unremoved by a `-keep` rule in
+ *   `consumer-rules.pro` (same vendoring path), shipped to every consuming app via `consumerProguardFiles`
+ *   (see `../build.gradle`) — R8 applies it regardless of whether the app used the Expo config plugin or
+ *   bare-RN autolinking, and regardless of whether the app authored any keep rules of its own
+ *   (docs/tasks/10-android-detection-keep-rule.md). This is the only Android signal guaranteed to survive
+ *   minification in every supported consumer setup.
+ *
+ *   Two more signals are kept as fallbacks for artifacts built before this marker existed: the
+ *   `com.callstackincubator.appduct` package string in the dex string pool (survives as long as
+ *   R8/ProGuard minification+obfuscation isn't applied to it — an aggressive release config with no keep
+ *   rule for this package can rename it away) and the plugin-authored meta-data key names in
+ *   `AndroidManifest.xml` (`com.callstackincubator.appduct.CLI_PINS`/`TRUST`/`ALLOW_PRIVATE_LAN_ONLY`):
+ *   those are XML attribute string values written by the config plugin at prebuild time, not compiled
+ *   identifiers, so R8 never touches them, but they only exist at all if the config plugin ran. Both
+ *   encodings AAPT2 can choose for the manifest string pool (UTF-8 or UTF-16LE) are checked.
+ *
+ * On iOS, `present` is an OR across the two real-code-only signals (`ios-core-marker-symbol`,
+ * `ios-objc-class-symbol`) — specifically so a stripped binary that dropped one literal doesn't flip
+ * a real inclusion to "absent" just because one check missed — but the Info.plist keys signal cannot
+ * flip it to `true` by itself, matching Android's marker-only rule below (a stub that ships the same
+ * plist keys without the real implementation is exactly the failure mode this guards against, even
+ * though no such stub exists yet as of Phase 1 of docs/tasks/14-native-core-extraction.md).
+ *
+ * On Android, `present` is decided by the keep-rule marker alone, not an OR across all three
+ * signals. The other two are reported in `signals` for corroboration/debugging but cannot flip
+ * `present` to `true` on their own: `android/build.gradle`'s `APPDUCT_ENABLED`-gated vendored
+ * source-directory swap (`core` vs `core-noop`, docs/tasks/14-native-core-extraction.md; previously a
+ * `src/debug`/`src/release-stub` swap, see docs/tasks/00-overview.md's "Revisited
+ * post-implementation") compiles a genuine no-op `AppductPackage` into a default release build at
+ * the *same* fully-qualified name the real one uses (required so the shared, non-variant-aware
+ * `PackageList.java` still resolves), and the config plugin writes the same manifest meta-data
+ * regardless of variant (Expo mods edit the single merged manifest, not a per-variant one). Both
+ * fallback signals therefore fire on that harmless stub exactly as they would on the real module, and
+ * can no longer prove inclusion by themselves.
+ *
+ * `appduct doctor` is strictly better than the runtime check it replaces (docs/tasks/00-overview.md
+ * "What we give up, deliberately"). The keep-rule marker closes the previously-documented gap where a
+ * bare-RN app with no config plugin and no keep rule could evade both older Android signals under R8
+ * minification (docs/tasks/10-android-detection-keep-rule.md) — that gap applied to builds produced before
+ * this library shipped the marker/keep rule; an app that pins an older `@appduct/react-native` version
+ * still lacks it, and doctor cannot detect inclusion on such a build at all.
+ */
+import { execFile } from "node:child_process";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { inspectionError, usageError } from "./errors.js";
+// --- markers ---
+// `@objc(AppductCoreMarker)` -- packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift.
+// Compiled only into the real implementation, never the SwiftPM package's Stub/ branch, so unlike
+// the Info.plist keys below it cannot exist without the real implementation also being present.
+const IOS_CORE_MARKER = "AppductCoreMarker";
+const IOS_OBJC_CLASS_MARKER = "RCTNativeAppduct";
+const IOS_INFO_PLIST_KEY_MARKERS = ["AppductCliPins", "AppductTrust", "AppductAllowPrivateLanOnly"];
+// Fully-qualified name of `AppductNativeMarker`
+// (packages/native/android/core/src/main/java/com/callstackincubator/appduct/AppductNativeMarker.kt,
+// vendored into packages/react-native/android/core/src/main/java/com/callstackincubator/appduct/AppductNativeMarker.kt
+// by scripts/sync-native-core.mjs), kept unminified by packages/native/android/core/consumer-rules.pro
+// (vendored to packages/react-native/android/core/consumer-rules.pro the same way). Checked as a dex
+// type descriptor (`Lcom/.../AppductNativeMarker;`) — see detectAndroidSignals — which is how the
+// class's fully-qualified name is actually encoded in classes.dex.
+const ANDROID_KEEP_RULE_MARKER_CLASS = "com/callstackincubator/appduct/AppductNativeMarker";
+const ANDROID_DEX_PACKAGE_MARKERS = ["com/callstackincubator/appduct", "com.callstackincubator.appduct"];
+const ANDROID_MANIFEST_KEY_MARKER = "com.callstackincubator.appduct.";
+const bufferIncludesAscii = (haystack, needle) => {
+    return haystack.includes(Buffer.from(needle, "utf8"));
+};
+const bufferIncludesUtf16le = (haystack, needle) => {
+    return haystack.includes(Buffer.from(needle, "utf16le"));
+};
+/** Real subprocess execution via `execFile`, buffered as raw bytes. `maxBuffer` is generous (an
+ * artifact's full decompressed contents are read into memory at once — see {@link readZipEntries})
+ * since real `.ipa`/`.apk`/`.aab` files can run into the hundreds of MB. */
+export const defaultExecBuffer = (command, args) => {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { encoding: "buffer", maxBuffer: 512 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                reject(Object.assign(error, { stdout, stderr }));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+};
+const TOOL_INSTALL_HINT = {
+    unzip: "Info-ZIP's unzip (present by default on macOS and most Linux CI images)",
+};
+/** Runs an external tool, translating "not found on PATH" and "ran but failed" into a single
+ * {@link inspectionError} class — both mean the same thing to a caller: this artifact could not be
+ * inspected, so no presence/absence claim can be trusted. Never resolves to a result that looks
+ * like a clean "not present" answer. */
+const runToolOrInspectionError = async (exec, command, args, context) => {
+    try {
+        const result = await exec(command, args);
+        return result.stdout;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            throw inspectionError(`"${command}" was not found on PATH; cannot inspect ${context}. Install ${TOOL_INSTALL_HINT[command] ?? command} and retry.`);
+        }
+        if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+            throw inspectionError(`"${command} ${args.join(" ")}" produced more output than this command will buffer while ` +
+                `inspecting ${context}. The artifact is unusually large, not necessarily corrupt — this is ` +
+                `a tooling limit, not a presence/absence answer.`);
+        }
+        const stderr = err.stderr ? err.stderr.toString("utf8").trim() : "";
+        throw inspectionError(`"${command} ${args.join(" ")}" failed while inspecting ${context}${stderr ? `: ${stderr}` : `: ${err.message}`}. The artifact may be corrupt or not a valid archive.`);
+    }
+};
+/** The container-shape check every zip-format artifact must pass before its contents are trusted
+ * for a presence/absence answer (see {@link readZipEntries}): an empty, wrong-file-renamed, or
+ * otherwise not-actually-that-kind-of-artifact zip must never silently read back as "no signals
+ * found" — it isn't an answer, it's evidence the input wasn't what its extension claimed. */
+const EXPECTED_ENTRY_PATTERN = {
+    ipa: /\.app\//iu,
+    apk: /(^|\/)AndroidManifest\.xml$/u,
+    aab: /(^|\/)AndroidManifest\.xml$/u,
+};
+const assertExpectedZipShape = (format, entries, context) => {
+    if (entries.length === 0) {
+        throw inspectionError(`${context} contains no entries — it is not a valid archive.`);
+    }
+    if (!entries.some((entry) => EXPECTED_ENTRY_PATTERN[format].test(entry))) {
+        throw inspectionError(`${context} does not look like a valid .${format}: none of its ${entries.length} entries match ` +
+            `the expected ${format === "ipa" ? '"*.app/" bundle' : '"AndroidManifest.xml"'} shape. Refusing ` +
+            `to report absence for an artifact that may simply be the wrong file.`);
+    }
+};
+/** Lists a zip archive's entry names via `unzip -Z1` (zipinfo mode: one path per line, nothing
+ * else) — used only for the {@link assertExpectedZipShape} sanity check, not for detection itself. */
+const listZipEntries = async (exec, archivePath, context) => {
+    const stdout = await runToolOrInspectionError(exec, "unzip", ["-Z1", archivePath], context);
+    return stdout
+        .toString("utf8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+};
+/** Streams every entry of a zip-format archive (`.ipa`/`.apk`/`.aab` are all zip containers)
+ * decompressed and concatenated to one buffer, via `unzip -p`. Deliberately does not attempt to
+ * enumerate entries and extract selectively first — a single whole-archive pass is simpler, cannot
+ * miss a signal hiding in an unexpected internal path (embedded framework, AAB's `base/dex/`
+ * nesting, ...), and correctness matters far more than the marginal speed of a narrower read for a
+ * command that runs once per release. Validates the archive actually has the expected internal
+ * shape first ({@link assertExpectedZipShape}) so an empty or mislabeled zip can't read back as a
+ * clean "no signals found" instead of the "this wasn't a real artifact" it actually is. */
+const readZipEntries = async (exec, archivePath, format, context) => {
+    const entries = await listZipEntries(exec, archivePath, context);
+    assertExpectedZipShape(format, entries, context);
+    return runToolOrInspectionError(exec, "unzip", ["-p", archivePath], context);
+};
+/** Recursively reads every regular file under a `.app` bundle directory into one concatenated
+ * buffer. Symlinks are skipped (never followed) to avoid loops; `.app` bundles don't legitimately
+ * need them for this check. */
+const readAppDirectory = async (appDirPath, context) => {
+    const chunks = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            throw inspectionError(`Could not read "${dir}" while inspecting ${context}: ${error.message}.`);
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(entryPath);
+                continue;
+            }
+            if (entry.isFile()) {
+                try {
+                    chunks.push(await readFile(entryPath));
+                }
+                catch (error) {
+                    throw inspectionError(`Could not read "${entryPath}" while inspecting ${context}: ${error.message}.`);
+                }
+            }
+        }
+    };
+    await walk(appDirPath);
+    return Buffer.concat(chunks);
+};
+// --- format resolution ---
+const resolveFormat = (artifactPath) => {
+    const extension = path.extname(artifactPath).toLowerCase();
+    switch (extension) {
+        case ".app":
+            return { platform: "ios", format: "app" };
+        case ".ipa":
+            return { platform: "ios", format: "ipa" };
+        case ".apk":
+            return { platform: "android", format: "apk" };
+        case ".aab":
+            return { platform: "android", format: "aab" };
+        default:
+            throw usageError(`Unrecognized artifact extension "${extension || artifactPath}". Expected one of: .app, .ipa, .apk, .aab.`);
+    }
+};
+// --- signal detection ---
+const detectIosSignals = (bytes) => {
+    const signals = [];
+    // Primary signal: checked first because, unlike the Info.plist keys below, it cannot exist
+    // without the real implementation (see the file-level doc comment).
+    if (bufferIncludesAscii(bytes, IOS_CORE_MARKER)) {
+        signals.push("ios-core-marker-symbol");
+    }
+    if (bufferIncludesAscii(bytes, IOS_OBJC_CLASS_MARKER)) {
+        signals.push("ios-objc-class-symbol");
+    }
+    if (IOS_INFO_PLIST_KEY_MARKERS.some((marker) => bufferIncludesAscii(bytes, marker))) {
+        signals.push("ios-info-plist-keys");
+    }
+    return signals;
+};
+const detectAndroidSignals = (bytes) => {
+    const signals = [];
+    // Primary signal: checked first because it's the only one guaranteed to survive R8 minification
+    // in every supported consumer setup (see the file-level doc comment). Matched as a dex type
+    // descriptor (`L` + fully-qualified-name-with-slashes + `;`) since that's the actual encoding of
+    // a class name inside classes.dex, not just a loose substring check.
+    if (bufferIncludesAscii(bytes, `L${ANDROID_KEEP_RULE_MARKER_CLASS};`)) {
+        signals.push("android-keep-rule-marker");
+    }
+    if (ANDROID_DEX_PACKAGE_MARKERS.some((marker) => bufferIncludesAscii(bytes, marker))) {
+        signals.push("android-dex-package-symbol");
+    }
+    if (bufferIncludesAscii(bytes, ANDROID_MANIFEST_KEY_MARKER) ||
+        bufferIncludesUtf16le(bytes, ANDROID_MANIFEST_KEY_MARKER)) {
+        signals.push("android-manifest-meta-data-keys");
+    }
+    return signals;
+};
+/** Inspects a built artifact for Appduct's native inclusion. Throws {@link usageError} for an
+ * unrecognized path/extension (a CLI-usage mistake) and {@link inspectionError} for anything that
+ * prevents a truthful presence/absence answer (missing tool, unreadable/corrupt artifact) — it
+ * never resolves successfully with a guessed or default answer. */
+export const inspectArtifact = async (artifactPath, options = {}) => {
+    const exec = options.exec ?? defaultExecBuffer;
+    const { platform, format } = resolveFormat(artifactPath);
+    const context = `"${artifactPath}"`;
+    let stats;
+    try {
+        stats = await stat(artifactPath);
+    }
+    catch (error) {
+        throw inspectionError(`Artifact not found at ${context}: ${error.message}.`);
+    }
+    let bytes;
+    if (format === "app") {
+        if (!stats.isDirectory()) {
+            throw inspectionError(`Expected ${context} (a ".app" bundle) to be a directory.`);
+        }
+        bytes = await readAppDirectory(artifactPath, context);
+    }
+    else {
+        if (!stats.isFile()) {
+            throw inspectionError(`Expected ${context} to be a file.`);
+        }
+        bytes = await readZipEntries(exec, artifactPath, format, context);
+    }
+    const signals = platform === "ios" ? detectIosSignals(bytes) : detectAndroidSignals(bytes);
+    // Android: only the keep-rule marker proves inclusion (see the file-level doc comment) -- the
+    // other two Android signals are reported but can't flip `present` on their own. iOS mirrors
+    // this: only the two real-code-only symbols prove inclusion (OR'd together so a stripped binary
+    // that dropped one doesn't read as absent) -- the Info.plist keys are corroborating only and
+    // can't flip `present` on their own either.
+    const present = platform === "android"
+        ? signals.includes("android-keep-rule-marker")
+        : signals.includes("ios-core-marker-symbol") || signals.includes("ios-objc-class-symbol");
+    return {
+        platform,
+        format,
+        present,
+        signals,
+    };
+};

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);

package/dist/cli/command-options.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Small option-parsing helpers shared across the v2 command handlers wired in `dispatch.ts`. Kept
+ * separate from `dispatch.ts` itself so each parsing rule (numeric flags, the selector/target
+ * positional split) has one obvious place to test in isolation.
+ */
+/** Parses a `cac`-provided option value (already a number, a numeric string, or `undefined`) into a
+ * positive integer, or throws a clear `usage_error`. */
+export declare const parsePositiveIntegerOption: (value: unknown, flagName: string) => number | undefined;
+/** Parses a `cac`-provided option value into a non-negative integer (0 allowed, unlike
+ * {@link parsePositiveIntegerOption}), or throws a clear `usage_error`. Used by `events --since`,
+ * whose cursor `0` is a meaningful "everything retained" value, not an omission. */
+export declare const parseNonNegativeIntegerOption: (value: unknown, flagName: string) => number | undefined;
+/**
+ * Splits the positional args of a command shaped `<command> [selector] <target>` (e.g. `invoke
+ * [selector] <tool>`, `tools [selector] <name>`): the last positional is always the required
+ * target, everything before it (zero or one args) is the optional selector.
+ */
+export declare const splitSelectorAndRequiredTarget: (args: readonly string[], commandUsage: string) => {
+    selector?: string;
+    target: string;
+};
+/** Splits the positional args of a command shaped `<command> [selector]`: at most one positional,
+ * the optional selector. */
+export declare const splitOptionalSelector: (args: readonly string[], commandUsage: string) => {
+    selector?: string;
+};
+/**
+ * Splits the positional args of a command shaped `<command> [selector] [target]` (`tools [selector]
+ * [name]`): with 2 args, `(selector, target)`; with 1, the single arg is ambiguous between "the
+ * selector" and "the target with the selector omitted" — the caller resolves that (see
+ * `commands/tools.ts`), so it comes back unlabeled here as `selectorOrTarget`.
+ */
+export declare const splitOptionalSelectorAndTarget: (args: readonly string[], commandUsage: string) => {
+    selector?: string;
+    target?: string;
+    selectorOrTarget?: string;
+};
+/**
+ * Parses the JSON payload for `invoke --input`; never throws a raw `SyntaxError` at the CLI
+ * boundary. A missing flag is a usage error (nothing was given); a present-but-unparseable or
+ * wrong-shaped value is a validation error (something was given, and it's invalid).
+ */
+export declare const parseJsonInputOption: (value: string | undefined) => Record<string, unknown>;
+//# sourceMappingURL=command-options.d.ts.map

package/dist/cli/command-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-options.d.ts","sourceRoot":"","sources":["../../src/cli/command-options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;wDACwD;AACxD,eAAO,MAAM,0BAA0B,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAAM,GAAG,SAYtF,CAAC;AAEF;;oFAEoF;AACpF,eAAO,MAAM,6BAA6B,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAAM,GAAG,SAYzF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GACzC,MAAM,SAAS,MAAM,EAAE,EACvB,cAAc,MAAM,KACnB;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAcrC,CAAC;AAEF;4BAC4B;AAC5B,eAAO,MAAM,qBAAqB,GAAI,MAAM,SAAS,MAAM,EAAE,EAAE,cAAc,MAAM,KAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAMxG,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GACzC,MAAM,SAAS,MAAM,EAAE,EACvB,cAAc,MAAM,KACnB;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAcjE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAkBtF,CAAC"}

package/dist/cli/command-options.js

@@ -0,0 +1,95 @@
+/**
+ * Small option-parsing helpers shared across the v2 command handlers wired in `dispatch.ts`. Kept
+ * separate from `dispatch.ts` itself so each parsing rule (numeric flags, the selector/target
+ * positional split) has one obvious place to test in isolation.
+ */
+import { usageError, validationError } from "../errors.js";
+/** Parses a `cac`-provided option value (already a number, a numeric string, or `undefined`) into a
+ * positive integer, or throws a clear `usage_error`. */
+export const parsePositiveIntegerOption = (value, flagName) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+        throw usageError(`"${flagName}" must be a positive integer.`);
+    }
+    return parsed;
+};
+/** Parses a `cac`-provided option value into a non-negative integer (0 allowed, unlike
+ * {@link parsePositiveIntegerOption}), or throws a clear `usage_error`. Used by `events --since`,
+ * whose cursor `0` is a meaningful "everything retained" value, not an omission. */
+export const parseNonNegativeIntegerOption = (value, flagName) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+        throw usageError(`"${flagName}" must be a non-negative integer.`);
+    }
+    return parsed;
+};
+/**
+ * Splits the positional args of a command shaped `<command> [selector] <target>` (e.g. `invoke
+ * [selector] <tool>`, `tools [selector] <name>`): the last positional is always the required
+ * target, everything before it (zero or one args) is the optional selector.
+ */
+export const splitSelectorAndRequiredTarget = (args, commandUsage) => {
+    if (args.length === 0) {
+        throw usageError(`Usage: ${commandUsage}`);
+    }
+    if (args.length > 2) {
+        throw usageError(`Usage: ${commandUsage} (too many arguments).`);
+    }
+    if (args.length === 1) {
+        return { target: args[0] };
+    }
+    return { selector: args[0], target: args[1] };
+};
+/** Splits the positional args of a command shaped `<command> [selector]`: at most one positional,
+ * the optional selector. */
+export const splitOptionalSelector = (args, commandUsage) => {
+    if (args.length > 1) {
+        throw usageError(`Usage: ${commandUsage} (too many arguments).`);
+    }
+    return { selector: args[0] };
+};
+/**
+ * Splits the positional args of a command shaped `<command> [selector] [target]` (`tools [selector]
+ * [name]`): with 2 args, `(selector, target)`; with 1, the single arg is ambiguous between "the
+ * selector" and "the target with the selector omitted" — the caller resolves that (see
+ * `commands/tools.ts`), so it comes back unlabeled here as `selectorOrTarget`.
+ */
+export const splitOptionalSelectorAndTarget = (args, commandUsage) => {
+    if (args.length > 2) {
+        throw usageError(`Usage: ${commandUsage} (too many arguments).`);
+    }
+    if (args.length === 2) {
+        return { selector: args[0], target: args[1] };
+    }
+    if (args.length === 1) {
+        return { selectorOrTarget: args[0] };
+    }
+    return {};
+};
+/**
+ * Parses the JSON payload for `invoke --input`; never throws a raw `SyntaxError` at the CLI
+ * boundary. A missing flag is a usage error (nothing was given); a present-but-unparseable or
+ * wrong-shaped value is a validation error (something was given, and it's invalid).
+ */
+export const parseJsonInputOption = (value) => {
+    if (value === undefined) {
+        throw usageError('"--input" is required.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw validationError(`"--input" must be valid JSON: ${error.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw validationError('"--input" must be a JSON object.');
+    }
+    return parsed;
+};

package/dist/cli/create-cli.d.ts

@@ -0,0 +1,2 @@
+export declare const createCli: () => import("cac").CAC;
+//# sourceMappingURL=create-cli.d.ts.map

package/dist/cli/create-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli.d.ts","sourceRoot":"","sources":["../../src/cli/create-cli.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS,yBA2FrB,CAAC"}

package/dist/cli/create-cli.js

@@ -0,0 +1,56 @@
+import { cac } from "cac";
+import { getPackageVersion } from "../package-version.js";
+export const createCli = () => {
+    const version = getPackageVersion();
+    const cli = cac("appduct");
+    cli.option("--json", "Print machine-readable JSON (NDJSON for streaming commands).");
+    cli.option("--no-color", "Disable terminal color in human-readable output.");
+    cli.option("--state-dir <path>", "Override the Appduct state directory (default: ~/.appduct).");
+    cli.option("--daemon-restart", "On a daemon/CLI version mismatch, restart the daemon even though that drops live sessions and unclaimed links.");
+    cli
+        .command("init", "Set up the current app directory: write .appduct/config.json and print the MCP snippet.")
+        .option("--scheme <scheme>", "Deep-link URI scheme to write. Only this flag and <cwd>/app.json are consulted — not " +
+        "APPDUCT_SCHEME, and no walk-up: init decides what to write here, so it never bakes " +
+        "an ambient value into a committed file.")
+        .option("--force", "Replace the scheme already recorded in the project config.");
+    cli
+        .command("keygen", "Generate a Appduct host private key and print its app fingerprint.")
+        .option("--out <path>", "Destination path (default: <state-dir>/key.pem).")
+        .option("--force", "Overwrite an existing key at the destination path.");
+    cli
+        .command("link", "Mint a pending session and print its deep link.")
+        .option("--ttl <seconds>", "Link time-to-live in seconds (default: from config.json).")
+        .option("--qr", "Also render the deep link as a terminal QR code.")
+        .option("--scheme <scheme>", "Deep-link URI scheme (also: APPDUCT_SCHEME; default: app.json's \"expo.scheme\").")
+        .option("--open <target>", "Deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental).")
+        .option("--device <id>", "adb serial, simulator udid or paired-device udid to target when --open is ambiguous.")
+        .option("--bundle-id <id>", "App bundle id for --open ios-device (default: config.json's \"iosBundleId\").")
+        .option("--relaunch", "With --open ios-device, terminate a running instance first (try this if delivery to an already-running app does nothing).");
+    cli.command("ls", "List Appduct sessions.");
+    cli
+        .command("tools [selector] [name]", "List a session's tools, or show one tool's full schema.")
+        .option("--full", "Render full schemas/annotations for every listed tool.");
+    cli
+        .command("invoke [selector] [tool]", "Call a tool on a session.")
+        .option("--input <json>", "Tool input arguments as a JSON object.")
+        .option("--timeout <ms>", "Call timeout in milliseconds. Shortens the deadline; it cannot extend one past the app's " +
+        "own timer, which is the tool's declared timeoutMs (else 10000).");
+    cli
+        .command("events [selector]", "Stream session/tool events until interrupted.")
+        .option("--follow", "Accepted for script readability; the default behavior already follows.")
+        .option("--since <cursor>", "One-shot: print events retained since this cursor instead of streaming live.");
+    cli.command("revoke [selector]", "Revoke a session.");
+    cli
+        .command("mcp", "Start a stdio MCP server that proxies connected apps' tools to MCP clients.")
+        .option("--scheme <scheme>", "Deep-link URI scheme for appduct_connect (also: APPDUCT_SCHEME).");
+    cli
+        .command("doctor <artifact>", "Report (or assert) whether a built .app/.ipa/.apk/.aab contains Appduct.")
+        .option("--assert-present", "Exit non-zero (and report) if Appduct is not present in the artifact.")
+        .option("--assert-absent", "Exit non-zero (and report) if Appduct is present in the artifact.");
+    // cac only matches a command's first word against argv[0], so "run"/"start"/"stop"/"status"
+    // are handled as a sub-action of the single "daemon" command rather than four cac commands.
+    cli.command("daemon [action]", "Manage the Appduct daemon: run, start, stop, or status.");
+    cli.help();
+    cli.version(version);
+    return cli;
+};

package/dist/cli/dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { RunCliOptions } from "./types.js";
+export declare const runCli: (argv: string[], options?: RunCliOptions) => Promise<number>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/cli/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAUhD,eAAO,MAAM,MAAM,GAAU,MAAM,MAAM,EAAE,EAAE,UAAS,aAAkB,KAAG,OAAO,CAAC,MAAM,CAmYxF,CAAC"}