appduct 0.9.0

package/dist/scheme.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Deep-link scheme resolution (ARCHITECTURE.md §10, issue #29).
+ *
+ * A scheme is needed to compose `<scheme>:///?appduct=<payload>` in `appduct link`,
+ * `appduct/client`'s `link()` and the MCP `appduct_connect` tool. Before this module the only
+ * source was `<state-dir>/config.json` — a single global file, which meant two apps with different
+ * schemes on one machine required hand-editing it on every switch.
+ *
+ * The resolution order below is shared by every one of those callers so it cannot drift, first
+ * match wins:
+ *
+ *   1. an explicit flag/option (`--scheme`)
+ *   2. the `APPDUCT_SCHEME` environment variable
+ *   3. the nearest `.appduct/config.json` that declares a `scheme`, walking up from the working
+ *      directory (never `~/.appduct` or the state dir in use — see {@link findProjectConfigs};
+ *      a project config without a `scheme` key does not stop the walk)
+ *   4. `scheme` in the state directory's `config.json` (the pre-#29 behaviour)
+ *   5. a static-file project probe, tried in this order (no walk-up — an app root is where you
+ *      run these commands), with {@link discoverStaticProjectScheme} owning the whole step:
+ *      a. `<cwd>/app.json`'s `expo.scheme` (the pre-#48 behaviour, unchanged)
+ *      b. Android: `app/build.gradle(.kts)`'s `appductScheme` manifest placeholder, then
+ *         `app/src/main/AndroidManifest.xml`'s first `<data android:scheme>` in a `VIEW`
+ *         intent filter
+ *      c. iOS: any `Info.plist` up to two levels deep (excluding `Pods`/`build`/`node_modules`/
+ *         `DerivedData`) for the first `CFBundleURLSchemes` entry, then xcodegen's `project.yml`
+ *         for the same key — see `native-scheme.ts`, which owns 5b/5c and never guesses when two
+ *         of them disagree (throws instead, naming both)
+ *
+ * Nothing here executes project code: `app.config.js`/`app.config.ts` are deliberately *not*
+ * evaluated (running arbitrary project JS to read one string is a much larger blast radius than
+ * this feature warrants), and neither is `xcodebuild`/`plutil`/a Gradle evaluation for the native
+ * probes added in issue #48 — every one of them is a plain, defensively-parsed read of a static
+ * 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
+ * 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";
+/** 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}. */
+export declare const PROJECT_CONFIG_FILENAME = "config.json";
+/** Relative path used in messages/docs: `.appduct/config.json`. */
+export declare const PROJECT_CONFIG_RELATIVE_PATH: string;
+/** The Expo app manifest discovery reads. Only static JSON — see this module's doc comment. */
+export declare const APP_JSON_FILENAME = "app.json";
+export declare const SCHEME_ENV_VAR = "APPDUCT_SCHEME";
+export declare const isValidScheme: (value: string) => boolean;
+/** Which step of the order above produced the scheme. The four `NativeSchemeSource` values are
+ * step 5's native-project probes (`native-scheme.ts`); `"app-json"` is step 5's original,
+ * unchanged probe. */
+export type SchemeSource = "flag" | "env" | "project-config" | "state-config" | "app-json" | NativeSchemeSource;
+export type ResolvedScheme = {
+    /** Undefined when no source produced one; `tried` then explains where we looked. */
+    scheme?: string;
+    source?: SchemeSource;
+    /** Human-readable descriptions of every location consulted, in order, for error messages. */
+    tried: string[];
+};
+/**
+ * Normalizes Expo's `scheme` field, which is either a single string or an array of them. Mirrors
+ * `packages/react-native/app.plugin.js`'s `configuredSchemes` so the CLI and the config plugin
+ * agree on what "the app's scheme" means; the first entry wins for an array.
+ *
+ * Exported so {@link ../native-scheme.js} can apply the same "string, or first non-empty entry of
+ * an array" rule to `CFBundleURLSchemes` (`Info.plist`/`project.yml`) — the shape is identical.
+ */
+export declare const firstConfiguredScheme: (value: unknown) => string | undefined;
+/**
+ * Reads `<dir>/app.json`'s `expo.scheme`. Returns `undefined` when the file is missing, is not a
+ * JSON object, has no `expo` object, or declares no usable scheme — every one of which just means
+ * "discovery found nothing here". A *malformed* `app.json` throws, because silently ignoring a
+ * syntax error in the file the user is pointing us at reads as "Appduct ignored my config".
+ */
+export declare const discoverExpoScheme: (dir: string) => Promise<string | undefined>;
+export type StaticProjectSchemeDiscovery = {
+    /** `undefined` when nothing in this step resolved a scheme. */
+    scheme?: string;
+    source?: "app-json" | NativeSchemeSource;
+    /** The human-readable location `scheme` was actually read from (a path, plus what was read from
+     * it) — distinct from `tried` below, which lists every location whether or not it hit. Only set
+     * alongside `scheme`. */
+    origin?: string;
+    /** 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[];
+};
+/**
+ * Step 5 of {@link resolveScheme} in full: `<cwd>/app.json` first (unchanged), then the native
+ * Android/iOS project probes from `native-scheme.ts`. Exported as its own step — not inlined into
+ * `resolveScheme` — because `appduct init` (`commands/init.ts`) runs exactly this same
+ * discovery on its own, deliberately skipping steps 1-4 (see that file's doc comment for why): the
+ * two must never disagree about what "discovery" means for the tail of the precedence order, or
+ * `init` could write a scheme `resolveScheme` would never have found on its own.
+ */
+export declare const discoverStaticProjectScheme: (cwd: string) => Promise<StaticProjectSchemeDiscovery>;
+export type ProjectConfigLookupOptions = {
+    /** The state dir actually in use, so the walk can never mistake it for a project config. */
+    stateDirRoot?: string;
+    /** The home directory whose `.appduct` is the *default* state dir. Injectable so tests can
+     * point it at a temp tree instead of the real `$HOME`; defaults to `os.homedir()`. */
+    homeDir?: string;
+};
+/**
+ * The `.appduct` directories that are *global* state, never a project's own config.
+ *
+ * Shared by the walk-up (which must not read them at the project tier) and `appduct init`
+ * (which must not *write* into them: it would drop a config next to the daemon's `key.pem` and
+ * call it safe to commit), so the two can never disagree about which directory is which.
+ */
+export declare const globalConfigDirs: (options?: ProjectConfigLookupOptions) => Set<string>;
+/**
+ * Every `<dir>/.appduct/config.json` on the path from `startDir` up to the filesystem root,
+ * nearest first.
+ *
+ * The walk terminates at the root (`dirname("/") === "/"`, and likewise for a Windows drive root)
+ * — it cannot escape above it, and it never follows `..` out of a caller-supplied path because
+ * every candidate is derived from the resolved absolute `startDir`.
+ *
+ * Two directories are never treated as a project root, because a hit there would silently apply a
+ * *global* file at the project tier — one step above the state dir's own config, inverting the
+ * documented precedence:
+ *
+ * - `<homeDir>/.appduct`, the default state dir. Essentially every project lives somewhere under
+ *   the home directory, so without this a plain `appduct link` in any repo would pick up the
+ *   global `config.json` as if it were the project's — and with `--state-dir` pointing elsewhere it
+ *   would shadow the state dir the operator explicitly chose.
+ * - `stateDirRoot`, the state dir actually in use, for the same reason when it is not the default.
+ */
+export declare const findProjectConfigs: (startDir: string, options?: ProjectConfigLookupOptions) => string[];
+/** The nearest project config on the path from `startDir` upwards, if any. */
+export declare const findProjectConfig: (startDir: string, options?: ProjectConfigLookupOptions) => string | undefined;
+/**
+ * Reads the `scheme` key out of a project `.appduct/config.json`. Unlike `app.json` this *is*
+ * Appduct's own file, so anything wrong with it (not an object, `scheme` not a non-empty
+ * string) is a hard error rather than a silent fall-through — a typo here must not quietly
+ * degrade to a different scheme from a lower-precedence source.
+ *
+ * Keys other than `scheme` are ignored: a project file is client-side settings only, and
+ * 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>;
+export type ResolveSchemeOptions = {
+    /** `--scheme` (or a programmatic `scheme` option) — highest precedence. */
+    flagScheme?: string;
+    /**
+     * The environment `APPDUCT_SCHEME` is read from. Defaults to `process.env`.
+     *
+     * Deliberately separate from the environment callers hand to `adb`/`simctl`: those callers
+     * narrow that env on purpose, and reusing it here would silently drop a `APPDUCT_SCHEME` the
+     * user really had exported.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Where the project walk-up and `app.json` discovery start. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** `scheme` already loaded from the state directory's `config.json`. */
+    configScheme?: string;
+    /** The state directory's `config.json` path, named in `tried` (and used to skip it in the walk-up). */
+    stateConfigPath?: 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 the deep-link scheme against the documented order, reporting both the winner and every
+ * location consulted so callers can render an error that says where to put one.
+ */
+export declare const resolveScheme: (options?: ResolveSchemeOptions) => Promise<ResolvedScheme>;
+/**
+ * The shared "no scheme anywhere" message. Every caller renders the same body so the locations
+ * listed (and the fixes suggested) can't drift between `appduct link`, `appduct mcp` and
+ * `appduct_connect`.
+ */
+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

package/dist/scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheme.d.ts","sourceRoot":"","sources":["../src/scheme.ts"],"names":[],"mappings":"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"}

package/dist/scheme.js

@@ -0,0 +1,321 @@
+/**
+ * Deep-link scheme resolution (ARCHITECTURE.md §10, issue #29).
+ *
+ * A scheme is needed to compose `<scheme>:///?appduct=<payload>` in `appduct link`,
+ * `appduct/client`'s `link()` and the MCP `appduct_connect` tool. Before this module the only
+ * source was `<state-dir>/config.json` — a single global file, which meant two apps with different
+ * schemes on one machine required hand-editing it on every switch.
+ *
+ * The resolution order below is shared by every one of those callers so it cannot drift, first
+ * match wins:
+ *
+ *   1. an explicit flag/option (`--scheme`)
+ *   2. the `APPDUCT_SCHEME` environment variable
+ *   3. the nearest `.appduct/config.json` that declares a `scheme`, walking up from the working
+ *      directory (never `~/.appduct` or the state dir in use — see {@link findProjectConfigs};
+ *      a project config without a `scheme` key does not stop the walk)
+ *   4. `scheme` in the state directory's `config.json` (the pre-#29 behaviour)
+ *   5. a static-file project probe, tried in this order (no walk-up — an app root is where you
+ *      run these commands), with {@link discoverStaticProjectScheme} owning the whole step:
+ *      a. `<cwd>/app.json`'s `expo.scheme` (the pre-#48 behaviour, unchanged)
+ *      b. Android: `app/build.gradle(.kts)`'s `appductScheme` manifest placeholder, then
+ *         `app/src/main/AndroidManifest.xml`'s first `<data android:scheme>` in a `VIEW`
+ *         intent filter
+ *      c. iOS: any `Info.plist` up to two levels deep (excluding `Pods`/`build`/`node_modules`/
+ *         `DerivedData`) for the first `CFBundleURLSchemes` entry, then xcodegen's `project.yml`
+ *         for the same key — see `native-scheme.ts`, which owns 5b/5c and never guesses when two
+ *         of them disagree (throws instead, naming both)
+ *
+ * Nothing here executes project code: `app.config.js`/`app.config.ts` are deliberately *not*
+ * evaluated (running arbitrary project JS to read one string is a much larger blast radius than
+ * this feature warrants), and neither is `xcodebuild`/`plutil`/a Gradle evaluation for the native
+ * probes added in issue #48 — every one of them is a plain, defensively-parsed read of a static
+ * 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
+ * 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 { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { usageError } from "./errors.js";
+import { discoverNativeScheme } from "./native-scheme.js";
+/** The directory a project-level config lives in, relative to an app root. */
+export const PROJECT_CONFIG_DIR = ".appduct";
+/** The project-level config filename, inside {@link PROJECT_CONFIG_DIR}. */
+export const PROJECT_CONFIG_FILENAME = "config.json";
+/** Relative path used in messages/docs: `.appduct/config.json`. */
+export const PROJECT_CONFIG_RELATIVE_PATH = join(PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+/** The Expo app manifest discovery reads. Only static JSON — see this module's doc comment. */
+export const APP_JSON_FILENAME = "app.json";
+export const SCHEME_ENV_VAR = "APPDUCT_SCHEME";
+/**
+ * RFC 3986 §3.1 scheme grammar: `ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )`.
+ *
+ * Enforced so a value like `"myapp://"` (a very natural thing to paste into `--scheme`) fails with
+ * a message naming the offending source instead of silently composing the unopenable
+ * `myapp://:///?appduct=…`.
+ */
+const SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*$/u;
+export const isValidScheme = (value) => SCHEME_PATTERN.test(value);
+const 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") — do not ' +
+            'include "://".');
+    }
+    return value;
+};
+const isPlainObject = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/** Reads and JSON-parses a file; `undefined` when it does not exist. Other I/O errors propagate. */
+const readJsonFile = async (path) => {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        // A `.appduct` that is a file, or an `app.json` that is a directory, is "nothing usable
+        // here" rather than a hard failure — the caller falls through to the next source.
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        return { raw: JSON.parse(text) };
+    }
+    catch (error) {
+        throw usageError(`Could not parse ${path}: ${error.message}`);
+    }
+};
+/**
+ * Normalizes Expo's `scheme` field, which is either a single string or an array of them. Mirrors
+ * `packages/react-native/app.plugin.js`'s `configuredSchemes` so the CLI and the config plugin
+ * agree on what "the app's scheme" means; the first entry wins for an array.
+ *
+ * Exported so {@link ../native-scheme.js} can apply the same "string, or first non-empty entry of
+ * an array" rule to `CFBundleURLSchemes` (`Info.plist`/`project.yml`) — the shape is identical.
+ */
+export const firstConfiguredScheme = (value) => {
+    if (Array.isArray(value)) {
+        return value.find((entry) => typeof entry === "string" && entry.length > 0);
+    }
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+/**
+ * Reads `<dir>/app.json`'s `expo.scheme`. Returns `undefined` when the file is missing, is not a
+ * JSON object, has no `expo` object, or declares no usable scheme — every one of which just means
+ * "discovery found nothing here". A *malformed* `app.json` throws, because silently ignoring a
+ * syntax error in the file the user is pointing us at reads as "Appduct ignored my config".
+ */
+export const discoverExpoScheme = async (dir) => {
+    const path = join(resolve(dir), APP_JSON_FILENAME);
+    const file = await readJsonFile(path);
+    if (!file || !isPlainObject(file.raw)) {
+        return undefined;
+    }
+    const expo = file.raw.expo;
+    if (!isPlainObject(expo)) {
+        return undefined;
+    }
+    const scheme = firstConfiguredScheme(expo.scheme);
+    return scheme === undefined ? undefined : requireValidScheme(scheme, `"expo.scheme" in ${path}`);
+};
+/**
+ * Step 5 of {@link resolveScheme} in full: `<cwd>/app.json` first (unchanged), then the native
+ * Android/iOS project probes from `native-scheme.ts`. Exported as its own step — not inlined into
+ * `resolveScheme` — because `appduct init` (`commands/init.ts`) runs exactly this same
+ * discovery on its own, deliberately skipping steps 1-4 (see that file's doc comment for why): the
+ * two must never disagree about what "discovery" means for the tail of the precedence order, or
+ * `init` could write a scheme `resolveScheme` would never have found on its own.
+ */
+export const discoverStaticProjectScheme = async (cwd) => {
+    const appJsonPath = join(resolve(cwd), APP_JSON_FILENAME);
+    const tried = [`${appJsonPath} ("expo.scheme")`];
+    const appJsonScheme = await discoverExpoScheme(cwd);
+    if (appJsonScheme !== undefined) {
+        return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, tried };
+    }
+    const native = await discoverNativeScheme(resolve(cwd));
+    tried.push(...native.tried);
+    if (native.result !== undefined) {
+        return {
+            scheme: native.result.scheme,
+            source: native.result.source,
+            origin: native.result.origin,
+            tried,
+        };
+    }
+    return { tried };
+};
+/**
+ * The `.appduct` directories that are *global* state, never a project's own config.
+ *
+ * Shared by the walk-up (which must not read them at the project tier) and `appduct init`
+ * (which must not *write* into them: it would drop a config next to the daemon's `key.pem` and
+ * call it safe to commit), so the two can never disagree about which directory is which.
+ */
+export const globalConfigDirs = (options = {}) => {
+    const excluded = new Set([join(resolve(options.homeDir ?? homedir()), PROJECT_CONFIG_DIR)]);
+    if (options.stateDirRoot !== undefined) {
+        excluded.add(resolve(options.stateDirRoot));
+    }
+    return excluded;
+};
+/**
+ * Every `<dir>/.appduct/config.json` on the path from `startDir` up to the filesystem root,
+ * nearest first.
+ *
+ * The walk terminates at the root (`dirname("/") === "/"`, and likewise for a Windows drive root)
+ * — it cannot escape above it, and it never follows `..` out of a caller-supplied path because
+ * every candidate is derived from the resolved absolute `startDir`.
+ *
+ * Two directories are never treated as a project root, because a hit there would silently apply a
+ * *global* file at the project tier — one step above the state dir's own config, inverting the
+ * documented precedence:
+ *
+ * - `<homeDir>/.appduct`, the default state dir. Essentially every project lives somewhere under
+ *   the home directory, so without this a plain `appduct link` in any repo would pick up the
+ *   global `config.json` as if it were the project's — and with `--state-dir` pointing elsewhere it
+ *   would shadow the state dir the operator explicitly chose.
+ * - `stateDirRoot`, the state dir actually in use, for the same reason when it is not the default.
+ */
+export const findProjectConfigs = (startDir, options = {}) => {
+    const excluded = globalConfigDirs(options);
+    const found = [];
+    let dir = resolve(startDir);
+    for (;;) {
+        const projectDir = join(dir, PROJECT_CONFIG_DIR);
+        if (!excluded.has(projectDir)) {
+            const candidate = join(projectDir, PROJECT_CONFIG_FILENAME);
+            if (existsSync(candidate)) {
+                found.push(candidate);
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return found;
+        }
+        dir = parent;
+    }
+};
+/** The nearest project config on the path from `startDir` upwards, if any. */
+export const findProjectConfig = (startDir, options = {}) => {
+    return findProjectConfigs(startDir, options)[0];
+};
+/**
+ * Reads the `scheme` key out of a project `.appduct/config.json`. Unlike `app.json` this *is*
+ * Appduct's own file, so anything wrong with it (not an object, `scheme` not a non-empty
+ * string) is a hard error rather than a silent fall-through — a typo here must not quietly
+ * degrade to a different scheme from a lower-precedence source.
+ *
+ * Keys other than `scheme` are ignored: a project file is client-side settings only, and
+ * accepting (say) `keyPath` here would let a checked-in file redirect the daemon's key material.
+ */
+export const readProjectConfigScheme = async (path) => {
+    const file = await readJsonFile(path);
+    if (!file) {
+        return undefined;
+    }
+    if (!isPlainObject(file.raw)) {
+        throw usageError(`Invalid Appduct project config at ${path}: must be a JSON object.`);
+    }
+    const scheme = file.raw.scheme;
+    if (scheme === undefined) {
+        return undefined;
+    }
+    if (typeof scheme !== "string" || scheme.length === 0) {
+        throw usageError(`Invalid Appduct project config at ${path}: "scheme" must be a non-empty string.`);
+    }
+    return requireValidScheme(scheme, `"scheme" in ${path}`);
+};
+/**
+ * Resolves the deep-link scheme against the documented order, reporting both the winner and every
+ * location consulted so callers can render an error that says where to put one.
+ */
+export const resolveScheme = async (options = {}) => {
+    const env = options.env ?? process.env;
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const tried = [];
+    tried.push("the --scheme flag");
+    if (options.flagScheme !== undefined && options.flagScheme.length > 0) {
+        return {
+            scheme: requireValidScheme(options.flagScheme, "the --scheme flag"),
+            source: "flag",
+            tried,
+        };
+    }
+    tried.push(`the ${SCHEME_ENV_VAR} environment variable`);
+    const envScheme = env[SCHEME_ENV_VAR];
+    if (typeof envScheme === "string" && envScheme.length > 0) {
+        return {
+            scheme: requireValidScheme(envScheme, `the ${SCHEME_ENV_VAR} environment variable`),
+            source: "env",
+            tried,
+        };
+    }
+    // Every project config on the way up, not just the nearest: one that exists but declares no
+    // `scheme` (a future version's file holding some other client-side key, say) is not an answer,
+    // so the walk continues past it rather than treating its silence as "no project scheme".
+    const projectConfigPaths = findProjectConfigs(cwd, {
+        stateDirRoot: options.stateDirRoot,
+        homeDir: options.homeDir,
+    });
+    tried.push(projectConfigPaths.length === 0
+        ? `${PROJECT_CONFIG_RELATIVE_PATH} (searched upwards from ${cwd})`
+        : projectConfigPaths.join(", "));
+    for (const projectConfigPath of projectConfigPaths) {
+        const projectScheme = await readProjectConfigScheme(projectConfigPath);
+        if (projectScheme !== undefined) {
+            return { scheme: projectScheme, source: "project-config", tried };
+        }
+    }
+    tried.push(options.stateConfigPath === undefined
+        ? 'the state directory\'s config.json ("scheme")'
+        : `${options.stateConfigPath} ("scheme")`);
+    if (options.configScheme !== undefined && options.configScheme.length > 0) {
+        return {
+            scheme: requireValidScheme(options.configScheme, options.stateConfigPath === undefined
+                ? 'the state directory\'s config.json "scheme"'
+                : `"scheme" in ${options.stateConfigPath}`),
+            source: "state-config",
+            tried,
+        };
+    }
+    const discovered = await discoverStaticProjectScheme(cwd);
+    tried.push(...discovered.tried);
+    if (discovered.scheme !== undefined) {
+        return { scheme: discovered.scheme, source: discovered.source, tried };
+    }
+    return { tried };
+};
+/**
+ * The shared "no scheme anywhere" message. Every caller renders the same body so the locations
+ * listed (and the fixes suggested) can't drift between `appduct link`, `appduct mcp` and
+ * `appduct_connect`.
+ */
+export const describeMissingScheme = (tried) => {
+    const locations = tried.length === 0
+        ? ""
+        : `Looked in, in order:\n${tried
+            .map((location, index) => `  ${index + 1}. ${location}`)
+            .join("\n")}\n`;
+    return ("A deep-link scheme is required to compose the link, and none was found. " +
+        locations +
+        `Set one with --scheme <scheme>, ${SCHEME_ENV_VAR}=<scheme>, "expo.scheme" in ${APP_JSON_FILENAME}, ` +
+        `or run \`appduct init\` in your app root to write ${PROJECT_CONFIG_RELATIVE_PATH}.`);
+};
+/** {@link resolveScheme}, throwing {@link usageError} with {@link describeMissingScheme} when nothing matched. */
+export const resolveSchemeOrThrow = async (options = {}) => {
+    const resolved = await resolveScheme(options);
+    if (resolved.scheme === undefined) {
+        throw usageError(describeMissingScheme(resolved.tried));
+    }
+    return resolved.scheme;
+};

package/dist/spki-pin.d.ts

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

package/dist/spki-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spki-pin.d.ts","sourceRoot":"","sources":["../src/spki-pin.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,MAI/C,CAAC;AAEF,eAAO,MAAM,2BAA2B,GAAI,QAAQ,MAAM,KAAG,MAW5D,CAAC"}

package/dist/spki-pin.js

@@ -0,0 +1,14 @@
+import { createHash, createPrivateKey, createPublicKey } from "node:crypto";
+export const createSpkiPin = (spkiDer) => {
+    const digest = createHash("sha256").update(spkiDer).digest("base64");
+    return `sha256/${digest}`;
+};
+export const getSpkiPinFromPrivateKeyPem = (keyPem) => {
+    const privateKey = createPrivateKey(keyPem);
+    const publicKey = createPublicKey(privateKey);
+    const spkiDer = Buffer.from(publicKey.export({
+        type: "spki",
+        format: "der",
+    }));
+    return createSpkiPin(spkiDer);
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "appduct",
+  "version": "0.9.0",
+  "description": "Driving React Native tools without in-app debug UI.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "appduct": "./bin.js"
+  },
+  "keywords": [
+    "appduct",
+    "react-native",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/callstackincubator/appduct"
+  },
+  "bugs": {
+    "url": "https://github.com/callstackincubator/appduct/issues"
+  },
+  "author": "Szymon Chmal <szymon@chmal.it> (V3RON)",
+  "license": "MIT",
+  "homepage": "https://github.com/callstackincubator/appduct/tree/main/packages/appduct#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@peculiar/x509": "^2.0.0",
+    "cac": "^6.7.14",
+    "picocolors": "^1.1.1",
+    "reflect-metadata": "^0.2.2",
+    "toqr": "^0.1.1",
+    "ws": "^8.18.3",
+    "@appduct/shared": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.9.2"
+  },
+  "files": [
+    "bin.js",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run --config ../../vitest.config.ts src/__tests__",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}