appduct 0.9.0 → 0.11.0

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

@@ -10,6 +10,14 @@ export declare const parsePositiveIntegerOption: (value: unknown, flagName: stri
  * {@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;
+/**
+ * Reads a free-text flag's value exactly as typed. `cac` coerces any numeric-looking value to a
+ * number (`--filter 404` arrives as `404`, `--filter 007` as `7`), so the verbatim string is
+ * recovered from `argv` (`--flag value` or `--flag=value`, the last occurrence wins, nothing after
+ * `--`), falling back to the parsed value if argv somehow does not carry it. A flag given with no
+ * value (`cac` reports `true`) is a usage error rather than silently ignored.
+ */
+export declare const readTextOption: (argv: readonly string[], value: unknown, flagName: string) => string | 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
@@ -41,4 +49,3 @@ export declare const splitOptionalSelectorAndTarget: (args: readonly string[], c
  * 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/create-cli.d.ts

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

package/dist/cli/dispatch.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The CLI's eager entry: everything that runs before a command word is known. Parses argv with
+ * `cac`, resolves the global flags, and hands off to the root router, which lazy-loads exactly one
+ * route module (`./routes/<command>.js`) for the command that matched.
+ *
+ * Keep this module's *static* imports to what every invocation needs (ARCHITECTURE.md §10
+ * "Startup cost"): the parser, the runner, the state-dir resolution and the version guard. A
+ * command's handler, and anything only that command needs, belongs behind its route's loader in
+ * {@link rootRouter}, never up here.
+ */
 import type { RunCliOptions } from "./types.js";
 export declare const runCli: (argv: string[], options?: RunCliOptions) => Promise<number>;
-//# sourceMappingURL=dispatch.d.ts.map

package/dist/cli/envelope.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Owns the CLI result envelope — the {@link CommandMeta} block a rendered result carries, and
+ * when it's attached. This module sits on the eager path (`runner.ts` calls it for every
+ * command), so it imports nothing beyond `result-types`'s types and `global-flags`'s types.
+ */
+import type { CliResult, CommandMeta } from "./result-types.js";
+import type { GlobalFlags } from "./global-flags.js";
+export declare const createCommandMeta: (command: string, startedAt: Date, finishedAt: Date) => CommandMeta;
+export type CommandTiming = {
+    command: string;
+    startedAt: Date;
+    finishedAt: Date;
+};
+/**
+ * Attaches `meta` to a command's result, but only under `--verbose` — otherwise the result is
+ * returned exactly as the handler produced it, with no `meta` key at all (never `meta: undefined`,
+ * so `--json` output carries no `meta` property to filter out).
+ */
+export declare const finalizeResult: <T>(result: CliResult<T>, timing: CommandTiming, flags: Pick<GlobalFlags, "verbose">) => CliResult<T>;

package/dist/cli/global-flags.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The CLI's global output flags (`--json`, `--pretty`, `--verbose`, `--no-color`) as a single
+ * declarative table. This module sits on the eager path (ARCHITECTURE.md §10 "Startup cost") —
+ * every invocation resolves these flags before a command word is even known — so it imports
+ * nothing beyond `cac`'s types (erased at build time) and stays free of runtime dependencies.
+ *
+ * Add a flag by adding one entry to {@link globalFlagDefinitions}: `create-cli.ts` registers it
+ * with `cac` via {@link registerGlobalFlags}, and `dispatch.ts` resolves it into the
+ * {@link GlobalFlags} object every route receives as `env.flags` via {@link resolveGlobalFlags} /
+ * {@link resolveGlobalFlagsFromArgv} — no other file needs to change.
+ */
+import type { CAC } from "cac";
+export type GlobalFlags = {
+    json: boolean;
+    pretty: boolean;
+    verbose: boolean;
+    color: boolean;
+};
+/** Registers every table entry with `cli.option()`, in table order. */
+export declare const registerGlobalFlags: (cli: CAC) => void;
+/** Resolves {@link GlobalFlags} from `cac`'s parsed options object (the normal path). */
+export declare const resolveGlobalFlags: (options: Readonly<Record<string, unknown>>) => GlobalFlags;
+/** Resolves {@link GlobalFlags} directly from argv — used when `cac.parse()` itself throws before
+ * a parsed options object exists. */
+export declare const resolveGlobalFlagsFromArgv: (argv: readonly string[]) => GlobalFlags;
+/**
+ * The single place that decides compact vs. indented JSON. Compact (`JSON.stringify(value)`) by
+ * default; `--pretty` restores the 2-space indentation the CLI used to always apply.
+ */
+export declare const formatJson: (value: unknown, flags: Pick<GlobalFlags, "pretty">) => string;

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

@@ -25,6 +25,13 @@ export declare const OPEN_TARGETS: readonly OpenTarget[];
  * so such a link must carry the machine's real advertised address (issue #31).
  */
 export declare const usesLoopbackAddress: (target: OpenTarget) => boolean;
+/**
+ * The `appId.<platform>` config key a target's app id is read from — the single place that maps a
+ * delivery target to the platform whose app id it needs. `undefined` for `ios-sim`: `simctl
+ * openurl` has no equivalent of `-p`/a bundle-id argument, so it needs no app id and none should
+ * ever be required for it.
+ */
+export declare const platformOf: (target: OpenTarget) => "ios" | "android" | undefined;
 /**
  * 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
@@ -51,10 +58,18 @@ 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;
+/**
+ * The single wording naming every way to supply an app id, shared by the `android` and
+ * `ios-device` paths (and by the CLI/MCP/programmatic callers that resolve one before minting a
+ * link) so the fix cannot drift between them. This is the *last-line-of-defence* message: the
+ * normal path is `scheme.ts`'s `resolveAppId`/`describeMissingAppId`, which names the exact
+ * project-config locations it looked in and fires before a link is even minted. This one covers a
+ * caller that reaches `deliverToOpenTarget` some other way (a test, or a future direct caller)
+ * with no app id at all.
+ */
+export declare const MISSING_APP_ID_MESSAGE: string;
+export declare const isValidAppId: (value: string) => boolean;
+export declare const invalidAppIdMessage: (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 = {
@@ -96,8 +111,11 @@ export type OpenTargetOptions = {
     /** 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;
+    /** The installed app's id: the Android package name for `target: "android"`, the iOS bundle id
+     * for `target: "ios-device"`. Required by both; unused (and never required) for `target:
+     * "ios-sim"` — see {@link platformOf}. Resolution (flag, then project config) happens before
+     * this is called; see `scheme.ts`'s `resolveAppId`. */
+    appId?: 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;
@@ -107,6 +125,5 @@ export type OpenTargetOptions = {
 };
 /** 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. */
+ * ambiguous device, missing app id) rather than a raw one. */
 export declare const deliverToOpenTarget: (options: OpenTargetOptions) => Promise<void>;
-//# sourceMappingURL=open-target.d.ts.map

package/dist/cli/result-types.d.ts

@@ -4,7 +4,7 @@
  * the thin-client shapes for the v2 command table.
  */
 import type { OpenTarget } from "./open-target.js";
-import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolDescriptor } from "@appduct/shared";
+import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolDescriptor, ToolGroupSummary, ToolsListResult } from "@appduct/shared";
 /**
  * CLI-domain error classes, used only to pick a sysexits-style exit code (see `errors.ts`).
  * `CliError.type` itself is *not* restricted to this union: RPC/app-originated failures preserve
@@ -70,6 +70,14 @@ export type InitCommandData = {
     created: boolean;
     /** This run wrote to the file. `false` on an idempotent re-run. */
     changed: boolean;
+    /** `appId.<platform>` as it stands in the project config after this run — from `--ios-app-id`/
+     * `--android-app-id` on this invocation, or already recorded from an earlier one. Omitted
+     * entirely (rather than `{}`) when neither platform has one, so `--json` output doesn't grow an
+     * empty object issue #63 didn't ask for. */
+    appId?: {
+        ios?: string;
+        android?: string;
+    };
     /** Present when the recorded scheme and the value discovery would currently find (`app.json` or
      * a native probe) disagree. The recorded one still wins (a re-run must not start failing because
      * the underlying project file was edited); this says so and names the `--force` invocation that
@@ -94,7 +102,8 @@ export type LinkCommandData = {
     expiresAt: number;
     /** The daemon's SPKI pin, same value as embedded in `deepLink`'s `pin` query param — surfaced
      * as its own field for `--json` consumers that don't want to re-parse the URL (opt-in
-     * hardening dev-mode: native clients trust this only in debug builds with no `cliPins`). */
+     * hardening dev-mode: native clients trust it only when the build embeds no `cliPins`, in any
+     * build type). */
     pin: string;
     /** Present (and `true`) only once `--open <target>` has successfully delivered the link
      * (ARCHITECTURE.md §10). */
@@ -104,8 +113,25 @@ export type LinkCommandData = {
 };
 /** `appduct ls`: `sessions.list` passthrough, verbatim (ARCHITECTURE.md §10: "--json passthrough"). */
 export type LsCommandData = SessionSummary[];
-/** `appduct tools`: the full list, or a single descriptor when a tool name resolved to a detail lookup. */
-export type ToolsCommandData = ToolDescriptor[] | ToolDescriptor;
+/** `appduct tools`'s listing form: the daemon's `tools.list` result, plus the `--group`/`--filter`/
+ * `--limit`/`--offset` inputs that produced it (only the ones actually given — echoed so `--json` and the
+ * human renderer's "Showing n of total" line can report what was asked for without threading the
+ * CLI options through separately). */
+export type ToolsListing = ToolsListResult & {
+    offset?: number;
+    limit?: number;
+    group?: string;
+    filter?: string;
+};
+/** `appduct tools --groups`: the daemon's `groups` summary alone, plus the registry's size. */
+export type ToolGroupsListing = {
+    groups: ToolGroupSummary[];
+    /** Every tool in the session, grouped or not. */
+    total: number;
+};
+/** `appduct tools`: a listing, a groups summary (`--groups`), or a single descriptor when a tool
+ * name resolved to a detail lookup. */
+export type ToolsCommandData = ToolsListing | ToolGroupsListing | ToolDescriptor;
 /** `appduct invoke`: the tool's raw result payload, printed as-is. */
 export type InvokeCommandData = unknown;
 export type RevokeCommandData = {
@@ -191,4 +217,3 @@ export type DaemonStatusCommandData = {
         bytes?: number;
     };
 };
-//# sourceMappingURL=result-types.d.ts.map

package/dist/cli/router.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The CLI's multi-level command router — the mechanism behind ARCHITECTURE.md §10 "Startup cost".
+ *
+ * A route table maps one command word to a *loader*: a `() => import("./routes/<name>.js")`.
+ * Nothing behind a loader is evaluated until its command word actually matches, so the module
+ * graph a process pays for at startup is the router plus the one route it takes, never the sum
+ * of every command. A route module may itself export another router (`daemon` does), and the
+ * same rule applies one level down: `daemon status` never loads `daemon run`'s daemon.
+ *
+ * The contract for a route module is a single `route` export of type {@link Route}. Keep the
+ * route module's *static* imports limited to what that command needs — a static import in a
+ * lazily loaded module is still lazy, it is the eager path (`dispatch.ts`, this file, `runner.ts`)
+ * that must stay lean.
+ */
+import type { CliEnv } from "./types.js";
+/** The inputs of the daemon version check (ARCHITECTURE.md §4 "Version drift"), as plain data so
+ * they can cross the bundle boundary; `cli/version-guard.ts` turns them into the check itself. */
+export type VersionCheckInputs = {
+    /** The version this client actually is — always the real package version, never an override. */
+    readonly clientVersion: string;
+    /** Resolves `--daemon-restart` / `APPDUCT_DAEMON_RESTART` / `restartDaemonOnVersionMismatch`;
+     * memoized by the caller, and it never throws (an unreadable config reads as `false`). */
+    readonly forceRestart: () => Promise<boolean>;
+    /** Where a "the daemon is newer than this client" notice goes for a command that is checked
+     * ahead of its first RPC; a no-op under `--json`, whose stdout/stderr contract has no room for
+     * it. A command that owns its own log channel (`mcp`) substitutes its own writer. */
+    readonly warn: (message: string) => void;
+};
+/**
+ * Everything a route needs to run one command; built once by `dispatch.ts`, narrowed per level.
+ *
+ * This object is the only thing that crosses from the eager bundle (`dist/bin.js`) into a route
+ * bundle (`dist/cli/routes/<command>.js`), and each route bundle carries its *own copy* of the
+ * modules it shares with the eager one (`scripts/bundle.mjs`). Two copies of a module mean two
+ * copies of its classes, and `instanceof` fails across them — so the context carries plain data,
+ * writers and closures that never throw. A closure that could throw an `AppductCliError` made in
+ * the eager bundle would reach the route's copy of `toCliError` and render as `internal_error`.
+ */
+export type RouteContext = {
+    /** The command words matched so far, e.g. `["daemon", "status"]`. Joined with spaces it is the
+     * command name used to pick a success-data renderer, and (under `--verbose`) the `meta.command`
+     * a rendered result reports. */
+    readonly path: readonly string[];
+    /** The positional arguments left after {@link path}: what the matched command itself receives. */
+    readonly args: readonly string[];
+    /** Every parsed flag (global and per-command), as `cac` reports them (camelCased). */
+    readonly options: Readonly<Record<string, unknown>>;
+    /** The raw argv `runCli` received (no `node`/script prefix). For the rare flag whose value must
+     * be read verbatim: `cac` coerces every numeric-looking value to a number (`--filter 007` → `7`),
+     * so a free-text flag recovers its exact string from here (`command-options.ts`'s
+     * `readTextOption`). */
+    readonly argv: readonly string[];
+    readonly env: CliEnv;
+    /** The resolved state directory (`--state-dir` / `APPDUCT_STATE_DIR` / default). */
+    readonly stateDir: string;
+    readonly versionCheck: VersionCheckInputs;
+};
+export type Route = (context: RouteContext) => Promise<number>;
+export type RouteLoader = () => Promise<{
+    route: Route;
+}>;
+export type RouteTable = Readonly<Record<string, RouteLoader>>;
+export type RouterOptions = {
+    /** Builds the error for an unmatched (or missing) command word at this level. */
+    readonly unknown: (word: string | undefined, context: RouteContext) => Error;
+};
+/** The command name for a context (the `meta.command` a rendered result reports under
+ * `--verbose`): the matched words joined, or the level's own name. */
+export declare const commandName: (context: RouteContext) => string;
+/**
+ * Builds a {@link Route} that consumes the next positional as a command word, lazy-loads the
+ * matching route module and hands it the rest. An unmatched word renders `options.unknown`'s
+ * error through the standard runner, so the exit code and `--json` shape are the same as any
+ * other usage error.
+ */
+export declare const createRouter: (table: RouteTable, options: RouterOptions) => Route;
+/** The default {@link RouterOptions.unknown} for a level whose commands are all top-level. */
+export declare const unknownCommandError: (word: string | undefined) => Error;

package/dist/cli/routes/daemon/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Route for `appduct daemon` — itself a router over the daemon actions, so `daemon status` loads
+ * `status.ts` and nothing else. In particular it never evaluates `run.ts`, the only action that
+ * pulls in the daemon implementation (ARCHITECTURE.md §10 "Startup cost").
+ *
+ * cac only matches a command's first word (`cli/create-cli.ts`), so the action arrives here as
+ * the first positional rather than as a cac command of its own.
+ */
+export declare const route: import("../../router.js").Route;