appduct 0.9.0

package/dist/mcp/tool-mapping.js

@@ -0,0 +1,143 @@
+/**
+ * Maps a `NamespacedTool` (daemon `ToolDescriptor` + resolved external name) onto the MCP SDK's
+ * `Tool` wire shape (ARCHITECTURE.md §9/§7): `description` maps directly and `annotations` map
+ * verbatim, while `input_schema`/`output_schema` are emitted only if the SDK's own `ToolSchema`
+ * accepts them (issue #26) — a rejected `input_schema` is replaced with an empty, permissive
+ * object schema and a rejected `output_schema` is dropped entirely. Either way the tool stays
+ * listed and callable: one app-side schema MCP cannot represent must never take down the whole
+ * `tools/list`.
+ *
+ * The gate is the SDK schema itself rather than a hand-rolled `type === "object"` check, because
+ * MCP constrains more than the root type — `properties` must be a record of *object* subschemas
+ * (the JSON Schema shorthand `properties: { a: true }` is rejected) and `required` must be an
+ * array. Any of those makes a client reject the entire `tools/list` result, so the only safe
+ * predicate is the one the client will actually apply.
+ *
+ * A tool whose effective policy is `"prompt"` (ARCHITECTURE.md §12) gets
+ * `_meta["anthropic/requiresUserInteraction"] = true` — but only when the caller says to
+ * (`emitRequiresUserInteractionFlag`), which `mcp/server.ts` decides is true only when the
+ * connected client is known to enforce the flag (issue #14) *and* it hasn't already preferred the
+ * elicitation channel instead (issue #10). Emitting the flag for a client that ignores it would
+ * create a false sense of security; emitting it *and* using elicitation for the same tool would
+ * arm two consent prompts for one call — so this function never decides that itself, only renders
+ * the decision it's handed.
+ */
+import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
+/** MCP requires `inputSchema.type === "object"`; an app that registered a tool without a schema
+ * gets the most permissive possible one rather than an MCP-invalid `{}`. */
+const EMPTY_OBJECT_SCHEMA = { type: "object", additionalProperties: true };
+/**
+ * Why the SDK's `ToolSchema` would reject `schema` in this slot, or `undefined` when it accepts
+ * it. The probe wraps the schema in an otherwise-minimal valid `Tool` so the only thing under test
+ * is the schema; the returned reason is the first issue, with the leading `inputSchema`/
+ * `outputSchema` path segment stripped so the message reads from the app author's point of view.
+ */
+const mcpSchemaRejection = (schema, slot) => {
+    const probe = slot === "input"
+        ? { name: "probe", inputSchema: schema }
+        : { name: "probe", inputSchema: EMPTY_OBJECT_SCHEMA, outputSchema: schema };
+    const parsed = ToolSchema.safeParse(probe);
+    if (parsed.success) {
+        return undefined;
+    }
+    const issue = parsed.error.issues[0];
+    if (!issue) {
+        return "it does not match MCP's tool schema";
+    }
+    const path = issue.path.slice(1).join(".");
+    return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+};
+/**
+ * Whether `tools/list` will carry an `outputSchema` for this descriptor. `server.ts`'s success
+ * path shares this predicate so the "did we advertise a schema?" and "must this result carry
+ * `structuredContent`?" decisions can never disagree — a client demands the latter exactly when
+ * it saw the former.
+ */
+export const emitsMcpOutputSchema = (schema) => {
+    return schema !== undefined && mcpSchemaRejection(schema, "output") === undefined;
+};
+/** stderr only — stdout carries the MCP transport's protocol frames (ARCHITECTURE.md §9). */
+const defaultWarn = (message) => {
+    console.error(`appduct mcp: ${message}`);
+};
+/**
+ * Upper bound on remembered notices. A key embeds the offending schema, and an app is free to
+ * build a schema from live data (a `z.enum` over rows it just fetched), so an unbounded set would
+ * grow with every distinct broken schema for the life of the process. Past the cap the oldest key
+ * is evicted, which at worst re-prints a notice the operator has already seen.
+ */
+const MAX_REMEMBERED_NOTICES = 256;
+/**
+ * Builds a mapper with its own degradation-notice dedup, so nothing here is module state and no
+ * reset hook has to be exported for tests: a server owns one mapper for its lifetime, and a test
+ * owns one per case. `warn` defaults to stderr and exists so a test can capture notices without
+ * spying on the console.
+ *
+ * Notices dedupe on session + tool name + the offending schema, because `tools/list` is
+ * re-answered on every client request and on every `notifications/tools/list_changed` refresh. Two
+ * devices exposing the same broken tool each get their own notice, and re-registering a tool with
+ * a *differently* broken schema warns again; only the same problem on the same tool of the same
+ * session stays quiet. The session's `selector` is the key rather than the namespaced `mcpName` so
+ * the single↔multi session flip, which rewrites every `mcpName`, does not re-warn about tools
+ * nothing changed about.
+ */
+export const createMcpToolMapper = (warn = defaultWarn) => {
+    const warned = new Set();
+    const warnOnce = (tool, slot, schema, message) => {
+        const key = `${tool.selector}\u0000${tool.descriptor.name}\u0000${slot}\u0000${JSON.stringify(schema)}`;
+        if (warned.has(key)) {
+            return;
+        }
+        // A `Set` iterates in insertion order, so the first key is the oldest.
+        if (warned.size >= MAX_REMEMBERED_NOTICES) {
+            const oldest = warned.values().next();
+            if (!oldest.done) {
+                warned.delete(oldest.value);
+            }
+        }
+        warned.add(key);
+        warn(message);
+    };
+    const mapInputSchema = (tool) => {
+        const schema = tool.descriptor.input_schema;
+        if (schema === undefined) {
+            return EMPTY_OBJECT_SCHEMA;
+        }
+        const rejection = mcpSchemaRejection(schema, "input");
+        if (rejection === undefined) {
+            return schema;
+        }
+        warnOnce(tool, "input", schema, `Tool "${tool.mcpName}" declares an input schema MCP cannot accept (${rejection}); MCP tool ` +
+            "arguments are always an object, so the schema was replaced with a permissive empty object " +
+            "schema and agents cannot see the tool's real arguments. Wrap the input in an object schema.");
+        return EMPTY_OBJECT_SCHEMA;
+    };
+    const mapOutputSchema = (tool) => {
+        const schema = tool.descriptor.output_schema;
+        if (schema === undefined) {
+            return undefined;
+        }
+        const rejection = mcpSchemaRejection(schema, "output");
+        if (rejection === undefined) {
+            return schema;
+        }
+        warnOnce(tool, "output", schema, `Tool "${tool.mcpName}" declares an output schema MCP cannot accept (${rejection}); it was ` +
+            "dropped from tools/list, so agents get the result without a schema to validate it against. " +
+            "Wrap the output in an object schema to give agents a described, structured result.");
+        return undefined;
+    };
+    return (tool, emitRequiresUserInteractionFlag) => {
+        const { descriptor } = tool;
+        const requiresUserInteraction = tool.policy === "prompt" && emitRequiresUserInteractionFlag;
+        const outputSchema = mapOutputSchema(tool);
+        return {
+            name: tool.mcpName,
+            description: descriptor.description,
+            inputSchema: mapInputSchema(tool),
+            ...(outputSchema ? { outputSchema } : {}),
+            ...(descriptor.annotations ? { annotations: { ...descriptor.annotations } } : {}),
+            // Must be the JSON boolean `true` literal — any other value is ignored by the client.
+            ...(requiresUserInteraction ? { _meta: { "anthropic/requiresUserInteraction": true } } : {}),
+        };
+    };
+};

package/dist/mcp/tool-namespace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Builds the effective MCP tool list from live daemon sessions and their tool registries
+ * (ARCHITECTURE.md §9): exactly one live session exposes tools under their
+ * own names; two or more namespace every tool as `<alias>__<name>` so names never collide across
+ * devices.
+ *
+ * The `__` separator is unambiguous to split back apart even though a tool's own name
+ * (`[a-zA-Z0-9_-]{1,64}`, `daemon/registry.ts`) may itself contain underscores: aliases
+ * (`daemon/sessions.ts`'s `slugifyDeviceModel`/`dedupeAlias`) only ever contain lowercase
+ * alphanumerics and hyphens, so the alias half of a namespaced name never itself contains `__` —
+ * the first occurrence of `__` in a namespaced name is always the alias/tool-name boundary.
+ */
+import type { EffectivePolicyDecision, SessionSummary, ToolDescriptor, ToolsListEntry } from "@appduct/shared";
+export declare const TOOL_NAMESPACE_SEPARATOR = "__";
+export type NamespacedTool = {
+    /** The name exposed to MCP clients: `descriptor.name` verbatim when exactly one session is live,
+     * else `<alias>__<name>`. */
+    mcpName: string;
+    /** The session alias `tools.call`'s `selector` should target for this tool. */
+    selector: string;
+    descriptor: ToolDescriptor;
+    /** The effective policy decision for this tool right now (ARCHITECTURE.md §12), as resolved by
+     * the daemon's `tools.list` — carried through so the MCP server can emit
+     * `_meta["anthropic/requiresUserInteraction"]` and set `consent` on `tools.call` without a
+     * second round trip (issue #14). */
+    policy: EffectivePolicyDecision;
+};
+/** Builds the namespaced (or not) tool list for the current set of live sessions. `toolsByAlias`
+ * is looked up by `session.alias` (not `sessionId`) to match `tools.list`'s `selector` semantics. */
+export declare const buildNamespacedTools: (sessions: readonly SessionSummary[], toolsByAlias: ReadonlyMap<string, readonly ToolsListEntry[]>) => NamespacedTool[];
+export declare const findNamespacedTool: (tools: readonly NamespacedTool[], mcpName: string) => NamespacedTool | undefined;
+/** A stable, order-independent key used to detect whether the effective tool list actually
+ * changed (name, target session, and the descriptor fields a client can see) — used to decide
+ * whether to fire `notifications/tools/list_changed` rather than on every qualifying daemon event.
+ *
+ * `timeout_ms` is deliberately excluded: it never reaches the MCP `Tool` JSON (`tool-mapping.ts`),
+ * so an app re-registering a tool with only a different deadline changes nothing a client could
+ * observe, and telling it the list changed would just make it re-fetch an identical list. */
+export declare const namespacedToolsSnapshotKey: (tools: readonly NamespacedTool[]) => string;
+//# sourceMappingURL=tool-namespace.d.ts.map

package/dist/mcp/tool-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-namespace.d.ts","sourceRoot":"","sources":["../../src/mcp/tool-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/G,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG;IAC3B;iCAC6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;IAC3B;;;wCAGoC;IACpC,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF;qGACqG;AACrG,eAAO,MAAM,oBAAoB,GAC/B,UAAU,SAAS,cAAc,EAAE,EACnC,cAAc,WAAW,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC,KAC3D,cAAc,EA4BhB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,OAAO,SAAS,cAAc,EAAE,EAChC,SAAS,MAAM,KACd,cAAc,GAAG,SAEnB,CAAC;AAEF;;;;;;6FAM6F;AAC7F,eAAO,MAAM,0BAA0B,GAAI,OAAO,SAAS,cAAc,EAAE,KAAG,MAe7E,CAAC"}

package/dist/mcp/tool-namespace.js

@@ -0,0 +1,65 @@
+/**
+ * Builds the effective MCP tool list from live daemon sessions and their tool registries
+ * (ARCHITECTURE.md §9): exactly one live session exposes tools under their
+ * own names; two or more namespace every tool as `<alias>__<name>` so names never collide across
+ * devices.
+ *
+ * The `__` separator is unambiguous to split back apart even though a tool's own name
+ * (`[a-zA-Z0-9_-]{1,64}`, `daemon/registry.ts`) may itself contain underscores: aliases
+ * (`daemon/sessions.ts`'s `slugifyDeviceModel`/`dedupeAlias`) only ever contain lowercase
+ * alphanumerics and hyphens, so the alias half of a namespaced name never itself contains `__` —
+ * the first occurrence of `__` in a namespaced name is always the alias/tool-name boundary.
+ */
+export const TOOL_NAMESPACE_SEPARATOR = "__";
+/** Builds the namespaced (or not) tool list for the current set of live sessions. `toolsByAlias`
+ * is looked up by `session.alias` (not `sessionId`) to match `tools.list`'s `selector` semantics. */
+export const buildNamespacedTools = (sessions, toolsByAlias) => {
+    const namespaced = sessions.length > 1;
+    const tools = [];
+    for (const session of sessions) {
+        for (const entry of toolsByAlias.get(session.alias) ?? []) {
+            // Explicit pick (not a `{ policy, ...descriptor }` rest-spread) so a future non-descriptor
+            // field added to `ToolsListEntry` can't silently leak into `descriptor` and from there into
+            // the MCP tool surface and the snapshot key below.
+            const descriptor = {
+                name: entry.name,
+                description: entry.description,
+                input_schema: entry.input_schema,
+                output_schema: entry.output_schema,
+                annotations: entry.annotations,
+                timeout_ms: entry.timeout_ms,
+            };
+            tools.push({
+                mcpName: namespaced ? `${session.alias}${TOOL_NAMESPACE_SEPARATOR}${descriptor.name}` : descriptor.name,
+                selector: session.alias,
+                descriptor,
+                policy: entry.policy,
+            });
+        }
+    }
+    return tools;
+};
+export const findNamespacedTool = (tools, mcpName) => {
+    return tools.find((tool) => tool.mcpName === mcpName);
+};
+/** A stable, order-independent key used to detect whether the effective tool list actually
+ * changed (name, target session, and the descriptor fields a client can see) — used to decide
+ * whether to fire `notifications/tools/list_changed` rather than on every qualifying daemon event.
+ *
+ * `timeout_ms` is deliberately excluded: it never reaches the MCP `Tool` JSON (`tool-mapping.ts`),
+ * so an app re-registering a tool with only a different deadline changes nothing a client could
+ * observe, and telling it the list changed would just make it re-fetch an identical list. */
+export const namespacedToolsSnapshotKey = (tools) => {
+    const sorted = tools
+        .map((tool) => {
+        const { timeout_ms: _timeoutMs, ...clientVisibleDescriptor } = tool.descriptor;
+        return {
+            name: tool.mcpName,
+            selector: tool.selector,
+            descriptor: clientVisibleDescriptor,
+            policy: tool.policy,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return JSON.stringify(sorted);
+};

package/dist/native-scheme.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Static-file scheme discovery for plain iOS (Xcode) and Android (Gradle) apps
+ * (docs/tasks/20-cli-native-scheme-discovery.md, phase 3 of issue #48).
+ *
+ * `scheme.ts`'s `resolveScheme` treats this module as one more thing to try after `<cwd>/app.json`
+ * — it never walks up (an app root is where these commands run, same rule as `app.json`), and,
+ * like every other source in that file, **nothing here executes project code**: no `plutil`, no
+ * `xcodebuild`, no Gradle evaluation. Every probe is a plain read of a well-known project file,
+ * parsed defensively:
+ *
+ * - Android: `app/build.gradle.kts` / `app/build.gradle` for a `manifestPlaceholders["appductScheme"]`
+ *   (or `.appductScheme =`) assignment, then `app/src/main/AndroidManifest.xml` for the first
+ *   `<data android:scheme>` inside an intent filter that also declares
+ *   `android.intent.action.VIEW`.
+ * - iOS: any `Info.plist` up to two levels below the app root (excluding `Pods`, `build`,
+ *   `node_modules` and `DerivedData` — vendored/build-output trees that are not the project's own
+ *   config, and can be enormous) for the first `CFBundleURLSchemes` entry, then `project.yml`
+ *   (xcodegen) for the same key under `info.properties.CFBundleURLTypes`.
+ *
+ * A binary-encoded `Info.plist` (Xcode can write either encoding) is reported as unreadable rather
+ * than decoded — `plutil -convert xml1` would work, but that is exactly the "run a tool against
+ * project state" this module exists to avoid, so a binary plist just falls through to `--scheme`
+ * like any other file this can't make sense of.
+ *
+ * **Disagreement is not guessed away.** If more than one probe below resolves to a *different*
+ * scheme (e.g. a monorepo whose `android/` and `ios/` declare different values), discovery throws
+ * a usage error naming every conflicting source instead of picking one — silently choosing would
+ * mean `appduct link` opens the wrong app on whichever platform lost.
+ */
+export type NativeSchemeSource = "android-gradle" | "android-manifest" | "ios-info-plist" | "ios-project-yml";
+export type NativeSchemeProbeResult = {
+    source: NativeSchemeSource;
+    scheme: string;
+    /** Human-readable path (plus what was read from it), for disagreement errors and `init`'s hint. */
+    origin: string;
+};
+export type NativeSchemeDiscovery = {
+    /** `undefined` when no probe resolved a scheme. */
+    result?: NativeSchemeProbeResult;
+    /** Every probe's human-readable description, in order, for {@link describeMissingScheme}-style
+     * reporting — always as many entries as there are probes, whether or not any of them hit. */
+    tried: string[];
+};
+/**
+ * Runs every static-file probe against `root` (never walking up — same rule as `app.json`) and
+ * decides the result:
+ *
+ * - No probe resolves a scheme: `result` is `undefined`.
+ * - Every probe that resolves one agrees: that scheme wins, attributed to whichever probe ran
+ *   first (the order in {@link PROBES}).
+ * - Two probes resolve *different* schemes: throws a usage error naming both sources and their
+ *   values, since guessing which one is right would silently target the wrong app on one
+ *   platform.
+ *
+ * `tried` always has one entry per probe, hit or miss, so a "no scheme anywhere" error can list
+ * every location this looked without the caller needing to know which probes exist.
+ */
+export declare const discoverNativeScheme: (root: string) => Promise<NativeSchemeDiscovery>;
+//# sourceMappingURL=native-scheme.d.ts.map

package/dist/native-scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-scheme.d.ts","sourceRoot":"","sources":["../src/native-scheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,mDAAmD;IACnD,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC;iGAC6F;IAC7F,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAihBF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,qBAAqB,CA4BtF,CAAC"}