appduct 0.9.0

package/dist/cli/dispatch.js

@@ -0,0 +1,275 @@
+import { handleDaemonRunCommand, handleDaemonStartCommand, handleDaemonStatusCommand, handleDaemonStopCommand, } from "../commands/daemon.js";
+import { handleDoctorCommand } from "../commands/doctor.js";
+import { handleEventsCommand } from "../commands/events.js";
+import { handleInitCommand } from "../commands/init.js";
+import { handleInvokeCommand } from "../commands/invoke.js";
+import { handleKeygenCommand } from "../commands/keygen.js";
+import { handleLinkCommand } from "../commands/link.js";
+import { handleLsCommand } from "../commands/ls.js";
+import { handleMcpCommand } from "../commands/mcp.js";
+import { handleRevokeCommand } from "../commands/revoke.js";
+import { handleToolsCommand } from "../commands/tools.js";
+import { loadConfig } from "../daemon/config.js";
+import { getStateDirPaths, resolveStateDir } from "../daemon/state-dir.js";
+import { usageError } from "../errors.js";
+import { renderEventLine, renderEventsCursorLine } from "../output.js";
+import { getPackageVersion } from "../package-version.js";
+import { ensureDaemonVersionMatches } from "../rpc/client.js";
+import { parseJsonInputOption, parseNonNegativeIntegerOption, parsePositiveIntegerOption, splitOptionalSelector, splitOptionalSelectorAndTarget, splitSelectorAndRequiredTarget, } from "./command-options.js";
+import { createCli } from "./create-cli.js";
+import { executeCommand, executeHostedCommand } from "./runner.js";
+import { systemClock } from "./types.js";
+/** `APPDUCT_DAEMON_RESTART=1` forces a version-mismatch restart for one run — the env-var form
+ * of `--daemon-restart`, so an MCP launch config (which passes no CLI flags) can opt in. */
+const DAEMON_RESTART_ENV = "APPDUCT_DAEMON_RESTART";
+const isEnvTruthy = (value) => {
+    return value === "1" || value?.toLowerCase() === "true";
+};
+export const runCli = async (argv, options = {}) => {
+    const writers = {
+        stdout: options.stdout ?? process.stdout,
+        stderr: options.stderr ?? process.stderr,
+    };
+    const clock = options.clock ?? systemClock;
+    const cli = createCli();
+    try {
+        cli.parse(["node", "appduct", ...argv], {
+            run: false,
+        });
+    }
+    catch (error) {
+        return executeCommand("cli", () => {
+            throw error;
+        }, {
+            json: argv.includes("--json"),
+            color: !argv.includes("--no-color"),
+            stdout: writers.stdout,
+            stderr: writers.stderr,
+            clock,
+        });
+    }
+    const matchedCommand = cli.matchedCommandName;
+    const parsedOptions = cli.options;
+    const parsedArgs = cli.args;
+    if (parsedOptions.help || parsedOptions.version) {
+        return 0;
+    }
+    if (!matchedCommand) {
+        if (parsedArgs[0]) {
+            return executeCommand("cli", () => {
+                throw usageError(`Unknown command "${parsedArgs[0]}".`);
+            }, {
+                json: Boolean(parsedOptions.json),
+                color: parsedOptions.color !== false,
+                stdout: writers.stdout,
+                stderr: writers.stderr,
+                clock,
+            });
+        }
+        cli.outputHelp();
+        return 0;
+    }
+    const json = Boolean(parsedOptions.json);
+    const color = parsedOptions.color !== false;
+    const io = { json, color, stdout: writers.stdout, stderr: writers.stderr, clock };
+    const stateDir = resolveStateDir(typeof parsedOptions.stateDir === "string" ? parsedOptions.stateDir : undefined);
+    // --- daemon/CLI version drift (issue #30, ARCHITECTURE.md §4 "Version drift") ------------------
+    let forceRestart;
+    /** Memoized so the config read behind `restartDaemonOnVersionMismatch` happens at most once. */
+    const resolveForceRestart = () => {
+        forceRestart ??= (async () => {
+            let configuredForce = false;
+            try {
+                configuredForce = (await loadConfig(getStateDirPaths(stateDir))).restartDaemonOnVersionMismatch;
+            }
+            catch {
+                // An unreadable/invalid `config.json` must not turn every command into a config error just
+                // because one optional knob lives there; the daemon reports the real problem when it starts.
+            }
+            // An explicit flag wins outright, in both directions: `--no-daemon-restart` is how an
+            // operator overrules a `restartDaemonOnVersionMismatch: true` in their config (or a
+            // `APPDUCT_DAEMON_RESTART` exported by a wrapper script) for one command, and silently
+            // ignoring it would be the worst kind of surprise for a knob that decides whether their
+            // connected devices survive.
+            const flag = typeof parsedOptions.daemonRestart === "boolean" ? parsedOptions.daemonRestart : undefined;
+            return flag ?? (isEnvTruthy(process.env[DAEMON_RESTART_ENV]) || configuredForce);
+        })();
+        return forceRestart;
+    };
+    /**
+     * Where the "the running daemon is newer than this client" notice goes. `--json` promises one
+     * machine-readable object and nothing else, so in that mode the notice is dropped rather than
+     * dribbled onto stderr where it would corrupt a script that captures both streams — the check
+     * still behaves identically, it just says nothing. (A structured warning channel would be the
+     * better answer; the runner has none today.)
+     */
+    const cliWarning = json ? () => { } : (message) => void writers.stderr.write(message);
+    const versionCheckFor = async (onWarning) => {
+        return {
+            clientVersion: getPackageVersion(),
+            forceRestart: await resolveForceRestart(),
+            onWarning,
+        };
+    };
+    /**
+     * Wraps a command handler so the daemon's version is verified once, before the command's first
+     * RPC. `autoSpawn: false`: with nothing listening there is no drift to find, and any daemon this
+     * process spawns afterwards is its own build. Applied to every command that talks to the daemon
+     * except `daemon run` (it *is* the daemon), `daemon status` (warns instead — see
+     * `commands/daemon.ts`) and `daemon stop` (already the remedy); `keygen`/`doctor` never open a
+     * daemon connection at all.
+     */
+    const guarded = (handler) => {
+        return async () => {
+            await ensureDaemonVersionMatches({
+                stateDir,
+                autoSpawn: false,
+                checkVersion: await versionCheckFor(cliWarning),
+            });
+            return handler();
+        };
+    };
+    switch (matchedCommand) {
+        case "init":
+            return executeCommand("init", () => handleInitCommand({
+                scheme: typeof parsedOptions.scheme === "string" ? parsedOptions.scheme : undefined,
+                force: Boolean(parsedOptions.force),
+            }, 
+            // `init` never reads the state dir, but it must know which directory it is so it can
+            // refuse to write a "safe to commit" project config into the daemon's own state.
+            { stateDir }), io);
+        case "keygen":
+            return executeCommand("keygen", () => handleKeygenCommand({
+                out: typeof parsedOptions.out === "string" ? parsedOptions.out : undefined,
+                force: Boolean(parsedOptions.force),
+            }, { stateDir }), io);
+        case "link": {
+            return executeCommand("link", guarded(() => handleLinkCommand({
+                ttlSeconds: parsePositiveIntegerOption(parsedOptions.ttl, "--ttl"),
+                scheme: typeof parsedOptions.scheme === "string" ? parsedOptions.scheme : undefined,
+                open: typeof parsedOptions.open === "string" ? parsedOptions.open : undefined,
+                device: typeof parsedOptions.device === "string" ? parsedOptions.device : undefined,
+                // cac camelCases `--bundle-id`; the dashed spelling is kept as a fallback so a
+                // parser change can't silently drop the flag.
+                bundleId: typeof parsedOptions.bundleId === "string"
+                    ? parsedOptions.bundleId
+                    : typeof parsedOptions["bundle-id"] === "string"
+                        ? parsedOptions["bundle-id"]
+                        : undefined,
+                // Left `undefined` when absent rather than coerced to `false`, so that
+                // "--relaunch only applies with --open ios-device" fires on the flag actually being
+                // passed and not on every `link` invocation.
+                relaunch: parsedOptions.relaunch === true ? true : undefined,
+            }, { stateDir })), {
+                ...io,
+                qr: Boolean(parsedOptions.qr),
+            });
+        }
+        case "ls":
+            return executeCommand("ls", guarded(() => handleLsCommand({ stateDir })), io);
+        case "tools": {
+            const { selector, target, selectorOrTarget } = splitOptionalSelectorAndTarget(parsedArgs, "tools [selector] [name]");
+            return executeCommand("tools", guarded(() => handleToolsCommand({ selector: selector ?? selectorOrTarget, name: target }, { stateDir })), { ...io, full: Boolean(parsedOptions.full) });
+        }
+        case "invoke": {
+            const { selector, target: tool } = splitSelectorAndRequiredTarget(parsedArgs, "invoke [selector] <tool> --input '<json>'");
+            // SIGINT cancels the in-flight tools.call rather than leaving it running unowned in the app
+            // (issue #9) — the listener is torn down once the command settles either way.
+            const cancelController = new AbortController();
+            const onSigint = () => cancelController.abort();
+            process.once("SIGINT", onSigint);
+            try {
+                return await executeCommand("invoke", guarded(() => handleInvokeCommand({
+                    selector,
+                    tool,
+                    args: parseJsonInputOption(typeof parsedOptions.input === "string" ? parsedOptions.input : undefined),
+                    timeoutMs: parsePositiveIntegerOption(parsedOptions.timeout, "--timeout"),
+                }, { stateDir }, cancelController.signal)), io);
+            }
+            finally {
+                process.off("SIGINT", onSigint);
+            }
+        }
+        case "revoke": {
+            const { selector } = splitOptionalSelector(parsedArgs, "revoke [selector]");
+            return executeCommand("revoke", guarded(() => handleRevokeCommand({ selector }, { stateDir })), io);
+        }
+        case "events": {
+            const { selector } = splitOptionalSelector(parsedArgs, "events [selector]");
+            const since = parseNonNegativeIntegerOption(parsedOptions.since, "--since");
+            const follow = Boolean(parsedOptions.follow);
+            return executeHostedCommand("events", guarded(() => {
+                // Deferred into the wrapped handler (rather than thrown directly in this case body,
+                // matching the codebase's existing lax convention for that) so `executeHostedCommand`'s
+                // own try/catch renders it as a normal usage_error instead of an uncaught rejection.
+                if (since !== undefined && follow) {
+                    throw usageError('"--since" is a one-shot pull and cannot be combined with "--follow".');
+                }
+                return handleEventsCommand({ selector, since }, {
+                    stateDir,
+                    onEvent: (event) => {
+                        writers.stdout.write(`${renderEventLine(event, { json, color })}\n`);
+                    },
+                    onCursor: (cursor) => {
+                        writers.stdout.write(`${renderEventsCursorLine(cursor, { json, color })}\n`);
+                    },
+                });
+            }), {
+                ...io,
+                reporter: {
+                    kind: "interactive",
+                    onEvent: () => { },
+                    dispose: () => { },
+                },
+            });
+        }
+        case "mcp": {
+            return executeHostedCommand("mcp", 
+            // Unlike every other command the check is threaded into the server itself, not run ahead
+            // of it: the MCP server is long-lived and auto-spawns its own daemon, so the check belongs
+            // on the startup stream that establishes the connection it keeps (ARCHITECTURE.md §9).
+            // The notice always goes to stderr here, `--json` or not: stdout carries MCP protocol
+            // frames, and stderr is this server's only log channel (ARCHITECTURE.md §9).
+            async () => handleMcpCommand({
+                stateDir,
+                scheme: typeof parsedOptions.scheme === "string" ? parsedOptions.scheme : undefined,
+                checkVersion: await versionCheckFor((message) => void writers.stderr.write(message)),
+            }), {
+                ...io,
+                reporter: {
+                    kind: "interactive",
+                    onEvent: () => { },
+                    dispose: () => { },
+                },
+            });
+        }
+        case "doctor": {
+            return executeCommand("doctor", () => handleDoctorCommand({
+                artifactPath: parsedArgs[0],
+                assertPresent: Boolean(parsedOptions.assertPresent),
+                assertAbsent: Boolean(parsedOptions.assertAbsent),
+            }), io);
+        }
+        case "daemon": {
+            const action = parsedArgs[0];
+            switch (action) {
+                case "run":
+                    return executeHostedCommand("daemon run", () => handleDaemonRunCommand({ stateDir, clock }), io);
+                case "start":
+                    return executeCommand("daemon start", guarded(() => handleDaemonStartCommand({ stateDir, clock })), io);
+                case "stop":
+                    return executeCommand("daemon stop", () => handleDaemonStopCommand({ stateDir, clock }), io);
+                case "status":
+                    return executeCommand("daemon status", () => handleDaemonStatusCommand({ stateDir, clock }), io);
+                default:
+                    return executeCommand("daemon", () => {
+                        throw usageError(`The daemon command requires an action: run, start, stop, or status (got ${action === undefined ? "none" : `"${action}"`}).`);
+                    }, io);
+            }
+        }
+        default:
+            return executeCommand(matchedCommand, () => {
+                throw usageError(`Unknown command "${matchedCommand}".`);
+            }, io);
+    }
+};

package/dist/cli/open-target.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Emulator/simulator fast path (ARCHITECTURE.md §8 delivery path 1, §10 `link --open`): delivers a
+ * deep link to a booted Android emulator/device or iOS simulator without any human handling a QR
+ * code — this is the CI/agent path. All subprocess execution goes through the injectable
+ * {@link ExecFn} seam so every branch here is testable without `adb`/`xcrun` installed.
+ *
+ * {@link detectBootedTargets} is the same enumeration used *before* a target is chosen, so callers
+ * that were given no explicit target (notably `appduct_connect` over MCP) can deliver to the one
+ * obvious device instead of falling back to a QR code nobody is there to scan.
+ *
+ * A third, experimental target — `ios-device`, a paired physical iPhone/iPad via `xcrun devicectl`
+ * (issue #31) — is explicit opt-in only: it is never auto-detected, it needs the app's bundle id,
+ * and its link must carry the LAN address rather than `127.0.0.1` (see {@link usesLoopbackAddress}).
+ */
+export type OpenTarget = "android" | "ios-sim" | "ios-device";
+export declare const isOpenTarget: (value: string) => value is OpenTarget;
+/** Human-readable list of every accepted target, for the "must be one of" validation messages the
+ * CLI, the shared `mintLink` core and `appduct_connect` each render in their own wording. */
+export declare const OPEN_TARGETS: readonly OpenTarget[];
+/**
+ * Whether a link delivered to this target reaches the daemon over loopback, and so must be minted
+ * with the `127.0.0.1` address override (`link.ts`, `mcp/connect-tool.ts`). True for `android`
+ * (`adb reverse` forwards the port onto the device) and `ios-sim` (the simulator shares the host's
+ * network stack); false for `ios-device` — a physical iPhone reaches the daemon only over the LAN,
+ * so such a link must carry the machine's real advertised address (issue #31).
+ */
+export declare const usesLoopbackAddress: (target: OpenTarget) => boolean;
+/**
+ * Whether an advertised address is one that only resolves back to the machine that minted the link.
+ * `daemon/address.ts` falls back to `127.0.0.1` when it cannot find a routable interface, and such
+ * a link handed to a physical phone points the phone at *itself*: the app connects to nothing, the
+ * session is never claimed, and `wait_for_session` blocks for its whole timeout with no clue why.
+ * The `ios-device` path checks this after minting and refuses rather than delivering.
+ */
+export declare const isLoopbackAddress: (address: string) => boolean;
+/** The one wording for that refusal, shared by the CLI and MCP paths. */
+export declare const loopbackAddressMessage: (address: string) => string;
+export type ExecResult = {
+    stdout: string;
+    stderr: string;
+};
+/** Injectable process-execution seam; tests stub this instead of shelling out to `adb`/`xcrun`. */
+export type ExecFn = (command: string, args: string[]) => Promise<ExecResult>;
+/** Real subprocess execution via `execFile` (no shell involved — argv is passed verbatim). */
+export declare const defaultExec: ExecFn;
+export type BootedSimulator = {
+    udid: string;
+    name: string;
+};
+export type PairedIosDevice = {
+    udid: string;
+    name: string;
+};
+/** The single wording naming both ways to supply a bundle id, so the CLI and MCP paths agree. */
+export declare const MISSING_BUNDLE_ID_MESSAGE: string;
+export declare const isValidBundleId: (value: string) => boolean;
+export declare const invalidBundleIdMessage: (value: string) => string;
+/** One device a link could be delivered to, resolved concretely enough to deliver without a
+ * second, racy lookup: `device` is an adb serial or a simulator udid. */
+export type DetectedTarget = {
+    target: OpenTarget;
+    device: string;
+    /** Human-readable form for error messages and agent-facing notes. */
+    label: string;
+};
+export type TargetDetection = {
+    kind: "single";
+    detected: DetectedTarget;
+} | {
+    kind: "none";
+} | {
+    kind: "ambiguous";
+    candidates: DetectedTarget[];
+};
+export type DetectBootedTargetsOptions = {
+    exec?: ExecFn;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Enumerates every booted simulator and attached Android device so a caller with no explicit
+ * target can deliver to the single obvious one. `ANDROID_SERIAL`, when set, narrows the Android
+ * side to that serial — it is exactly the disambiguation the user has already made.
+ *
+ * Physical iPhones (`ios-device`) are deliberately *not* enumerated here (issue #31): a paired
+ * iPhone is often someone's personal phone rather than a test device, delivery to it may
+ * cold-launch the app, and it additionally needs a bundle id the caller has to supply. It is an
+ * explicit, opt-in target only.
+ */
+export declare const detectBootedTargets: (options?: DetectBootedTargetsOptions) => Promise<TargetDetection>;
+export type OpenTargetOptions = {
+    target: OpenTarget;
+    /** The composed `<scheme>:///?appduct=<payload>` deep link to deliver. */
+    deepLink: string;
+    /** The daemon's wss port; used for `adb reverse tcp:<port> tcp:<port>`. */
+    wssPort: number;
+    /** An adb device serial (`target: "android"`), a simulator udid (`target: "ios-sim"`) or a
+     * paired-device udid (`target: "ios-device"`). */
+    device?: string;
+    /** The installed app's bundle id. Required by (and only used for) `target: "ios-device"`. */
+    bundleId?: string;
+    /** `target: "ios-device"` only: terminate a running instance first (`--terminate-existing`)
+     * instead of launching over it. Off by default; see {@link deliverToOpenTarget}. */
+    relaunch?: boolean;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    exec?: ExecFn;
+};
+/** Delivers `deepLink` to a booted Android device/emulator, an iOS simulator, or (experimentally)
+ * a paired physical iOS device. Throws a clear, actionable error (missing tool, no booted device,
+ * ambiguous device, missing bundle id) rather than a raw one. */
+export declare const deliverToOpenTarget: (options: OpenTargetOptions) => Promise<void>;
+//# sourceMappingURL=open-target.d.ts.map

package/dist/cli/open-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-target.d.ts","sourceRoot":"","sources":["../../src/cli/open-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;AAE9D,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,UAErD,CAAC;AAEF;6FAC6F;AAC7F,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAyC,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,UAAU,KAAG,OAExD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,OAUnD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,KAAG,MAI3C,CAAC;AAEf,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,mGAAmG;AACnG,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAE9E,8FAA8F;AAC9F,eAAO,MAAM,WAAW,EAAE,MAWzB,CAAC;AAkCF,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAkH7D,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA6F7D,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,QAEwB,CAAC;AAe/D,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,OAAwC,CAAC;AAEzF,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,KAAG,MAEzC,CAAC;AAiLf;yEACyE;AACzE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC;AAcxD,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAS,0BAA+B,KACvC,OAAO,CAAC,eAAe,CAiCzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;sDACkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;wFACoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;iEAEiE;AACjE,eAAO,MAAM,mBAAmB,GAAU,SAAS,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAoBlF,CAAC"}