@agent-native/skills 0.1.1 → 0.2.1

package/README.md

@@ -3,13 +3,21 @@
 Install BuilderIO skill folders into Codex and Claude skill directories.
 
 ```bash
-npx @agent-native/skills add
-npx @agent-native/skills add --skill quick-recap --client codex --scope project --update-instructions
-npx @agent-native/skills add --skill visual-recap --client all --with-github-action
+npx @agent-native/skills@latest add
+npx @agent-native/skills@latest add --skill quick-recap --client codex --scope project --update-instructions
+npx @agent-native/skills@latest add --skill visual-recap --client all --with-github-action
 ```
 
 Use `--skill <name>` one or more times to select specific skills, or omit it in
 an interactive terminal to choose from a prompt. Use `--client codex`,
-`--client claude-code`, or `--client all` to choose install targets. Add
-`--update-instructions` to append an idempotent managed block to `AGENTS.md`
-and/or `CLAUDE.md` for instruction-style skills.
+`--client claude-code`, or `--client all` to choose install targets; omitted
+`--client` defaults to all supported clients. Add `--update-instructions` to
+append an idempotent managed block to `AGENTS.md` and/or `CLAUDE.md` for
+instruction-style skills.
+
+Skill content comes from `BuilderIO/skills@main` at install/list time. That
+means adding or updating public skills such as `quick-recap` or
+`efficient-fable` in the skills repo is picked up by this CLI without publishing
+a new `@agent-native/skills` package. `visual-plan` and `visual-recap` are also
+installed from `BuilderIO/skills`; Agent Native syncs those two into the public
+repo from the framework source of truth.

package/dist/built-in-apps.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical "built-in agent-native app -> MCP server" descriptor registry.
+ *
+ * This is a dependency-free mirror of the manifest data encoded in
+ * `@agent-native/core`'s `BUILT_IN_APP_SKILLS` object
+ * (`packages/core/src/cli/skills.ts`, around line 1711+). The standalone
+ * `@agent-native/skills` installer uses this to know which skill name maps to
+ * which hosted MCP server without importing the (much heavier) core CLI module.
+ *
+ * IMPORTANT: every URL / serverName / alias / authMode below MUST stay byte-for-byte
+ * identical to core's `BUILT_IN_APP_SKILLS`. The provenance of each value is noted
+ * inline as `packages/core/src/cli/skills.ts:<line>`. If core changes, update here too
+ * (a future sync guard test should compare the two).
+ */
+/** Auth modes mirrored from core's `auth.mode` on each app-skill manifest. */
+export type BuiltInAppAuthMode = "oauth" | "device" | "none";
+/**
+ * Descriptor for a single built-in agent-native app and the hosted MCP server
+ * its skills connect to.
+ */
+export interface BuiltInAppMcp {
+    /** Stable app id (matches the manifest `id` in core). */
+    appId: string;
+    /** Human-facing display name. */
+    displayName: string;
+    /** Skill names this app exports (a skill name resolves back to this app). */
+    skillNames: string[];
+    /** MCP server name used when registering the connector. */
+    serverName: string;
+    /** Hosted MCP endpoint URL (`hosted.mcpUrl`). */
+    mcpUrl: string;
+    /** Hosted app base URL (`hosted.url`). */
+    hostedUrl: string;
+    /** Alternate server names accepted for this app (`mcp.aliases`). */
+    aliases?: string[];
+    /** Auth mode for connecting the MCP server (`auth.mode`). */
+    authMode: BuiltInAppAuthMode;
+    /** True when the app ships only as a local command (no remote refresh). */
+    localOnly?: boolean;
+    /** True when the app provides a PR Visual Recap GitHub Action workflow. */
+    hasGithubAction?: boolean;
+}
+/**
+ * The built-in app -> MCP registry.
+ *
+ * Each entry's values are copied verbatim from core. Provenance per field is
+ * cited inline using the `packages/core/src/cli/skills.ts` line numbers.
+ */
+export declare const BUILT_IN_APP_MCP: BuiltInAppMcp[];
+/**
+ * Resolve the built-in app whose `skillNames` contains `skillName`
+ * (case-insensitive). Returns `undefined` when no built-in app exports it.
+ */
+export declare function resolveAppForSkill(skillName: string): BuiltInAppMcp | undefined;
+/**
+ * True when the given skill name maps to a built-in app with a hosted MCP
+ * server.
+ */
+export declare function appHasMcp(skillName: string): boolean;
+//# sourceMappingURL=built-in-apps.d.ts.map

package/dist/built-in-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-apps.d.ts","sourceRoot":"","sources":["../src/built-in-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAkE3C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB,aAAa,GAAG,SAAS,CAM3B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEpD"}

package/dist/built-in-apps.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical "built-in agent-native app -> MCP server" descriptor registry.
+ *
+ * This is a dependency-free mirror of the manifest data encoded in
+ * `@agent-native/core`'s `BUILT_IN_APP_SKILLS` object
+ * (`packages/core/src/cli/skills.ts`, around line 1711+). The standalone
+ * `@agent-native/skills` installer uses this to know which skill name maps to
+ * which hosted MCP server without importing the (much heavier) core CLI module.
+ *
+ * IMPORTANT: every URL / serverName / alias / authMode below MUST stay byte-for-byte
+ * identical to core's `BUILT_IN_APP_SKILLS`. The provenance of each value is noted
+ * inline as `packages/core/src/cli/skills.ts:<line>`. If core changes, update here too
+ * (a future sync guard test should compare the two).
+ */
+/**
+ * The built-in app -> MCP registry.
+ *
+ * Each entry's values are copied verbatim from core. Provenance per field is
+ * cited inline using the `packages/core/src/cli/skills.ts` line numbers.
+ */
+export const BUILT_IN_APP_MCP = [
+    {
+        // core skills.ts:1822 (id), :1823 (displayName)
+        appId: "visual-plans",
+        displayName: "Agent-Native Plan",
+        // core skills.ts:1803 (skillName "visual-plan") + :1805 (extraSkills "visual-recap")
+        skillNames: ["visual-plan", "visual-recap"],
+        // core skills.ts:1830 (mcp.serverName + mcp.aliases)
+        serverName: "plan",
+        aliases: ["agent-native-plans"],
+        // core skills.ts:1828 (hosted.mcpUrl)
+        mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
+        // core skills.ts:1827 (hosted.url)
+        hostedUrl: "https://plan.agent-native.com",
+        // core skills.ts:1832 (auth.mode)
+        authMode: "oauth",
+        // core skills.ts:3321-3322 (githubActionPath gated on knownTarget === "visual-plans")
+        hasGithubAction: true,
+    },
+    {
+        // core skills.ts:1716 (id), :1717 (displayName)
+        appId: "assets",
+        displayName: "Assets",
+        // core skills.ts:1713 (skillName)
+        skillNames: ["assets"],
+        // core skills.ts:1724 (mcp.serverName)
+        serverName: "agent-native-assets",
+        // core skills.ts:1722 (hosted.mcpUrl)
+        mcpUrl: "https://assets.agent-native.com/_agent-native/mcp",
+        // core skills.ts:1721 (hosted.url)
+        hostedUrl: "https://assets.agent-native.com",
+        // core skills.ts:1726 (auth.mode)
+        authMode: "oauth",
+    },
+    {
+        // core skills.ts:1762 (id), :1763 (displayName)
+        appId: "design",
+        displayName: "Design",
+        // core skills.ts:1759 (skillName)
+        skillNames: ["design-exploration"],
+        // core skills.ts:1770 (mcp.serverName)
+        serverName: "agent-native-design",
+        // core skills.ts:1768 (hosted.mcpUrl)
+        mcpUrl: "https://design.agent-native.com/_agent-native/mcp",
+        // core skills.ts:1767 (hosted.url)
+        hostedUrl: "https://design.agent-native.com",
+        // core skills.ts:1772 (auth.mode)
+        authMode: "oauth",
+    },
+    {
+        // core skills.ts:1881 (id), :1882 (displayName)
+        appId: "context-xray",
+        displayName: "Context X-Ray",
+        // core skills.ts:1877 (skillName)
+        skillNames: ["context-xray"],
+        // core skills.ts:1889 (mcp.serverName)
+        serverName: "agent-native-context-xray",
+        // core skills.ts:1887 (hosted.mcpUrl)
+        mcpUrl: "https://context-xray.agent-native.com/_agent-native/mcp",
+        // core skills.ts:1886 (hosted.url)
+        hostedUrl: "https://context-xray.agent-native.com",
+        // core skills.ts:1890 (auth.mode)
+        authMode: "none",
+        // core skills.ts:1878 (localOnly: true)
+        localOnly: true,
+    },
+];
+/**
+ * Resolve the built-in app whose `skillNames` contains `skillName`
+ * (case-insensitive). Returns `undefined` when no built-in app exports it.
+ */
+export function resolveAppForSkill(skillName) {
+    const needle = skillName.trim().toLowerCase();
+    if (!needle)
+        return undefined;
+    return BUILT_IN_APP_MCP.find((app) => app.skillNames.some((name) => name.toLowerCase() === needle));
+}
+/**
+ * True when the given skill name maps to a built-in app with a hosted MCP
+ * server.
+ */
+export function appHasMcp(skillName) {
+    return resolveAppForSkill(skillName) !== undefined;
+}
+//# sourceMappingURL=built-in-apps.js.map

package/dist/built-in-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-apps.js","sourceRoot":"","sources":["../src/built-in-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgCH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,gDAAgD;QAChD,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,mBAAmB;QAChC,qFAAqF;QACrF,UAAU,EAAE,CAAC,aAAa,EAAE,cAAc,CAAC;QAC3C,qDAAqD;QACrD,UAAU,EAAE,MAAM;QAClB,OAAO,EAAE,CAAC,oBAAoB,CAAC;QAC/B,sCAAsC;QACtC,MAAM,EAAE,iDAAiD;QACzD,mCAAmC;QACnC,SAAS,EAAE,+BAA+B;QAC1C,kCAAkC;QAClC,QAAQ,EAAE,OAAO;QACjB,sFAAsF;QACtF,eAAe,EAAE,IAAI;KACtB;IACD;QACE,gDAAgD;QAChD,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,QAAQ;QACrB,kCAAkC;QAClC,UAAU,EAAE,CAAC,QAAQ,CAAC;QACtB,uCAAuC;QACvC,UAAU,EAAE,qBAAqB;QACjC,sCAAsC;QACtC,MAAM,EAAE,mDAAmD;QAC3D,mCAAmC;QACnC,SAAS,EAAE,iCAAiC;QAC5C,kCAAkC;QAClC,QAAQ,EAAE,OAAO;KAClB;IACD;QACE,gDAAgD;QAChD,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,QAAQ;QACrB,kCAAkC;QAClC,UAAU,EAAE,CAAC,oBAAoB,CAAC;QAClC,uCAAuC;QACvC,UAAU,EAAE,qBAAqB;QACjC,sCAAsC;QACtC,MAAM,EAAE,mDAAmD;QAC3D,mCAAmC;QACnC,SAAS,EAAE,iCAAiC;QAC5C,kCAAkC;QAClC,QAAQ,EAAE,OAAO;KAClB;IACD;QACE,gDAAgD;QAChD,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,eAAe;QAC5B,kCAAkC;QAClC,UAAU,EAAE,CAAC,cAAc,CAAC;QAC5B,uCAAuC;QACvC,UAAU,EAAE,2BAA2B;QACvC,sCAAsC;QACtC,MAAM,EAAE,yDAAyD;QACjE,mCAAmC;QACnC,SAAS,EAAE,uCAAuC;QAClD,kCAAkC;QAClC,QAAQ,EAAE,MAAM;QAChB,wCAAwC;QACxC,SAAS,EAAE,IAAI;KAChB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiB;IAEjB,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CACnC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC;AACrD,CAAC","sourcesContent":["/**\n * Canonical \"built-in agent-native app -> MCP server\" descriptor registry.\n *\n * This is a dependency-free mirror of the manifest data encoded in\n * `@agent-native/core`'s `BUILT_IN_APP_SKILLS` object\n * (`packages/core/src/cli/skills.ts`, around line 1711+). The standalone\n * `@agent-native/skills` installer uses this to know which skill name maps to\n * which hosted MCP server without importing the (much heavier) core CLI module.\n *\n * IMPORTANT: every URL / serverName / alias / authMode below MUST stay byte-for-byte\n * identical to core's `BUILT_IN_APP_SKILLS`. The provenance of each value is noted\n * inline as `packages/core/src/cli/skills.ts:<line>`. If core changes, update here too\n * (a future sync guard test should compare the two).\n */\n\n/** Auth modes mirrored from core's `auth.mode` on each app-skill manifest. */\nexport type BuiltInAppAuthMode = \"oauth\" | \"device\" | \"none\";\n\n/**\n * Descriptor for a single built-in agent-native app and the hosted MCP server\n * its skills connect to.\n */\nexport interface BuiltInAppMcp {\n  /** Stable app id (matches the manifest `id` in core). */\n  appId: string;\n  /** Human-facing display name. */\n  displayName: string;\n  /** Skill names this app exports (a skill name resolves back to this app). */\n  skillNames: string[];\n  /** MCP server name used when registering the connector. */\n  serverName: string;\n  /** Hosted MCP endpoint URL (`hosted.mcpUrl`). */\n  mcpUrl: string;\n  /** Hosted app base URL (`hosted.url`). */\n  hostedUrl: string;\n  /** Alternate server names accepted for this app (`mcp.aliases`). */\n  aliases?: string[];\n  /** Auth mode for connecting the MCP server (`auth.mode`). */\n  authMode: BuiltInAppAuthMode;\n  /** True when the app ships only as a local command (no remote refresh). */\n  localOnly?: boolean;\n  /** True when the app provides a PR Visual Recap GitHub Action workflow. */\n  hasGithubAction?: boolean;\n}\n\n/**\n * The built-in app -> MCP registry.\n *\n * Each entry's values are copied verbatim from core. Provenance per field is\n * cited inline using the `packages/core/src/cli/skills.ts` line numbers.\n */\nexport const BUILT_IN_APP_MCP: BuiltInAppMcp[] = [\n  {\n    // core skills.ts:1822 (id), :1823 (displayName)\n    appId: \"visual-plans\",\n    displayName: \"Agent-Native Plan\",\n    // core skills.ts:1803 (skillName \"visual-plan\") + :1805 (extraSkills \"visual-recap\")\n    skillNames: [\"visual-plan\", \"visual-recap\"],\n    // core skills.ts:1830 (mcp.serverName + mcp.aliases)\n    serverName: \"plan\",\n    aliases: [\"agent-native-plans\"],\n    // core skills.ts:1828 (hosted.mcpUrl)\n    mcpUrl: \"https://plan.agent-native.com/_agent-native/mcp\",\n    // core skills.ts:1827 (hosted.url)\n    hostedUrl: \"https://plan.agent-native.com\",\n    // core skills.ts:1832 (auth.mode)\n    authMode: \"oauth\",\n    // core skills.ts:3321-3322 (githubActionPath gated on knownTarget === \"visual-plans\")\n    hasGithubAction: true,\n  },\n  {\n    // core skills.ts:1716 (id), :1717 (displayName)\n    appId: \"assets\",\n    displayName: \"Assets\",\n    // core skills.ts:1713 (skillName)\n    skillNames: [\"assets\"],\n    // core skills.ts:1724 (mcp.serverName)\n    serverName: \"agent-native-assets\",\n    // core skills.ts:1722 (hosted.mcpUrl)\n    mcpUrl: \"https://assets.agent-native.com/_agent-native/mcp\",\n    // core skills.ts:1721 (hosted.url)\n    hostedUrl: \"https://assets.agent-native.com\",\n    // core skills.ts:1726 (auth.mode)\n    authMode: \"oauth\",\n  },\n  {\n    // core skills.ts:1762 (id), :1763 (displayName)\n    appId: \"design\",\n    displayName: \"Design\",\n    // core skills.ts:1759 (skillName)\n    skillNames: [\"design-exploration\"],\n    // core skills.ts:1770 (mcp.serverName)\n    serverName: \"agent-native-design\",\n    // core skills.ts:1768 (hosted.mcpUrl)\n    mcpUrl: \"https://design.agent-native.com/_agent-native/mcp\",\n    // core skills.ts:1767 (hosted.url)\n    hostedUrl: \"https://design.agent-native.com\",\n    // core skills.ts:1772 (auth.mode)\n    authMode: \"oauth\",\n  },\n  {\n    // core skills.ts:1881 (id), :1882 (displayName)\n    appId: \"context-xray\",\n    displayName: \"Context X-Ray\",\n    // core skills.ts:1877 (skillName)\n    skillNames: [\"context-xray\"],\n    // core skills.ts:1889 (mcp.serverName)\n    serverName: \"agent-native-context-xray\",\n    // core skills.ts:1887 (hosted.mcpUrl)\n    mcpUrl: \"https://context-xray.agent-native.com/_agent-native/mcp\",\n    // core skills.ts:1886 (hosted.url)\n    hostedUrl: \"https://context-xray.agent-native.com\",\n    // core skills.ts:1890 (auth.mode)\n    authMode: \"none\",\n    // core skills.ts:1878 (localOnly: true)\n    localOnly: true,\n  },\n];\n\n/**\n * Resolve the built-in app whose `skillNames` contains `skillName`\n * (case-insensitive). Returns `undefined` when no built-in app exports it.\n */\nexport function resolveAppForSkill(\n  skillName: string,\n): BuiltInAppMcp | undefined {\n  const needle = skillName.trim().toLowerCase();\n  if (!needle) return undefined;\n  return BUILT_IN_APP_MCP.find((app) =>\n    app.skillNames.some((name) => name.toLowerCase() === needle),\n  );\n}\n\n/**\n * True when the given skill name maps to a built-in app with a hosted MCP\n * server.\n */\nexport function appHasMcp(skillName: string): boolean {\n  return resolveAppForSkill(skillName) !== undefined;\n}\n"]}

package/dist/connect.d.ts

@@ -0,0 +1,81 @@
+/**
+ * MCP-server registration + authentication for `@agent-native/skills`.
+ *
+ * This is a dependency-free port of the MCP-config-writing + device-code/OAuth
+ * flow that lives in `@agent-native/core`'s `cli/connect.ts`. The skills package
+ * ships standalone (no `@agent-native/core` dependency), so this module
+ * re-implements just the registration surface against the shared on-disk
+ * writers in `./mcp-config-writers.js`. It writes the SAME config and speaks the
+ * SAME device-code/OAuth protocol as core.
+ *
+ * Two client families, exactly as in core:
+ *   - OAuth-capable (claude-code, claude-code-cli): get a URL-only HTTP MCP
+ *     entry (no bearer headers). The user authenticates in-host via standard
+ *     remote MCP OAuth: restart Claude Code, run /mcp, choose Authenticate.
+ *   - Device-code (codex, cowork): run the browser device-code flow against the
+ *     descriptor's hosted URL, then write the entry WITH the minted bearer token
+ *     + headers. Non-interactive (or no TTY) skips the flow and writes a
+ *     URL-only entry, surfacing the exact `agent-native connect <url> --token`
+ *     fallback command.
+ *
+ * Server contract (identical paths + JSON field names to core):
+ *   POST <hostedUrl>/_agent-native/mcp/connect/device/start  (no auth)
+ *     body { client?, app? }
+ *     → { device_code, user_code, verification_uri,
+ *         verification_uri_complete, interval, expires_in }
+ *   POST <hostedUrl>/_agent-native/mcp/connect/device/poll   (no auth)
+ *     body { device_code }
+ *     → { status: "pending" }
+ *     | { status: "approved", token, mcpUrl, serverName, mcpServerEntry }
+ *     | { status: "expired" } | { status: "consumed" }
+ *     | { status: "error" | "not_found", message? }
+ *
+ * Node-only. Node built-ins + global fetch only; no npm deps.
+ */
+import { ClientId } from "./mcp-config-writers.js";
+/**
+ * Describes one MCP server to register. `serverName` is the canonical config
+ * key; `aliases` are additional config keys that point at the same MCP URL
+ * (e.g. `plan` + `agent-native-plans`). `hostedUrl` is the deployed app origin
+ * the device-code flow authenticates against; `mcpUrl` is the resolved MCP
+ * endpoint written into the config (defaults to `<hostedUrl>/_agent-native/mcp`
+ * when only `hostedUrl` is supplied).
+ */
+export interface McpDescriptor {
+    serverName: string;
+    mcpUrl: string;
+    aliases?: string[];
+    authMode?: "oauth" | "device" | "none";
+    hostedUrl?: string;
+}
+export interface RegisterMcpOptions {
+    descriptor: McpDescriptor;
+    clients: ClientId[];
+    scope: "user" | "project";
+    baseDir: string;
+    interactive: boolean;
+    log?: (m: string) => void;
+    deps?: {
+        fetchImpl?: typeof fetch;
+        now?: () => number;
+        sleep?: (ms: number) => Promise<void>;
+    };
+}
+export interface RegisterMcpResult {
+    written: {
+        client: ClientId;
+        file: string;
+    }[];
+    authenticated: boolean;
+    guidance: string[];
+}
+export declare function supportsRemoteMcpOAuth(client: ClientId): boolean;
+/**
+ * Register an MCP server (plus aliases) into the requested client configs,
+ * authenticating device-code clients via the browser flow when interactive.
+ *
+ * Idempotent: re-running replaces the same named entries. Never throws on a
+ * single client/key failing — failures are collected into `guidance`.
+ */
+export declare function registerMcpServer(opts: RegisterMcpOptions): Promise<RegisterMcpResult>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,QAAQ,EAA2B,MAAM,yBAAyB,CAAC;AAmB5E;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,aAAa,CAAC;IAC1B,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;QACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACvC,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0CD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAEhE;AAsSD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAuI5B"}

package/dist/connect.js

@@ -0,0 +1,352 @@
+/**
+ * MCP-server registration + authentication for `@agent-native/skills`.
+ *
+ * This is a dependency-free port of the MCP-config-writing + device-code/OAuth
+ * flow that lives in `@agent-native/core`'s `cli/connect.ts`. The skills package
+ * ships standalone (no `@agent-native/core` dependency), so this module
+ * re-implements just the registration surface against the shared on-disk
+ * writers in `./mcp-config-writers.js`. It writes the SAME config and speaks the
+ * SAME device-code/OAuth protocol as core.
+ *
+ * Two client families, exactly as in core:
+ *   - OAuth-capable (claude-code, claude-code-cli): get a URL-only HTTP MCP
+ *     entry (no bearer headers). The user authenticates in-host via standard
+ *     remote MCP OAuth: restart Claude Code, run /mcp, choose Authenticate.
+ *   - Device-code (codex, cowork): run the browser device-code flow against the
+ *     descriptor's hosted URL, then write the entry WITH the minted bearer token
+ *     + headers. Non-interactive (or no TTY) skips the flow and writes a
+ *     URL-only entry, surfacing the exact `agent-native connect <url> --token`
+ *     fallback command.
+ *
+ * Server contract (identical paths + JSON field names to core):
+ *   POST <hostedUrl>/_agent-native/mcp/connect/device/start  (no auth)
+ *     body { client?, app? }
+ *     → { device_code, user_code, verification_uri,
+ *         verification_uri_complete, interval, expires_in }
+ *   POST <hostedUrl>/_agent-native/mcp/connect/device/poll   (no auth)
+ *     body { device_code }
+ *     → { status: "pending" }
+ *     | { status: "approved", token, mcpUrl, serverName, mcpServerEntry }
+ *     | { status: "expired" } | { status: "consumed" }
+ *     | { status: "error" | "not_found", message? }
+ *
+ * Node-only. Node built-ins + global fetch only; no npm deps.
+ */
+import { writeHttpEntryForClient } from "./mcp-config-writers.js";
+const DEVICE_START_PATH = "/_agent-native/mcp/connect/device/start";
+const DEVICE_POLL_PATH = "/_agent-native/mcp/connect/device/poll";
+const MCP_PATH = "/_agent-native/mcp";
+/** OAuth-capable clients (in-host remote MCP OAuth, never a local bearer). */
+const REMOTE_MCP_OAUTH_CLIENTS = new Set([
+    "claude-code",
+    "claude-code-cli",
+]);
+/** Identical to core: ask the deployed app to expose the full action catalog. */
+const MCP_FULL_CATALOG_HEADER = "X-Agent-Native-MCP-Full-Catalog";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function supportsRemoteMcpOAuth(client) {
+    return REMOTE_MCP_OAUTH_CLIENTS.has(client);
+}
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Trailing-slash-stripped origin+path for a hosted app URL. */
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Resolve the MCP endpoint URL for a descriptor. Prefers an explicit `mcpUrl`,
+ * otherwise derives `<hostedUrl>/_agent-native/mcp` (mirrors core's
+ * `mcpUrlForBaseUrl`). Returns `undefined` when neither is usable.
+ */
+function resolveMcpUrl(descriptor) {
+    if (descriptor.mcpUrl && descriptor.mcpUrl.trim()) {
+        return descriptor.mcpUrl.trim();
+    }
+    if (descriptor.hostedUrl && descriptor.hostedUrl.trim()) {
+        const base = stripTrailingSlash(descriptor.hostedUrl.trim());
+        return `${base}${MCP_PATH}`;
+    }
+    return undefined;
+}
+/** Base (origin) URL of the deployed app the device flow runs against. */
+function resolveBaseUrl(descriptor) {
+    if (descriptor.hostedUrl && descriptor.hostedUrl.trim()) {
+        return stripTrailingSlash(descriptor.hostedUrl.trim());
+    }
+    // Fall back to stripping the MCP path off an explicit mcpUrl.
+    if (descriptor.mcpUrl && descriptor.mcpUrl.trim()) {
+        const trimmed = stripTrailingSlash(descriptor.mcpUrl.trim());
+        if (trimmed.endsWith(MCP_PATH)) {
+            return trimmed.slice(0, -MCP_PATH.length);
+        }
+    }
+    return undefined;
+}
+/** All config keys to register: the canonical name plus any aliases (deduped). */
+function configKeys(descriptor) {
+    const keys = [descriptor.serverName];
+    for (const alias of descriptor.aliases ?? []) {
+        if (alias && alias !== descriptor.serverName && !keys.includes(alias)) {
+            keys.push(alias);
+        }
+    }
+    return keys;
+}
+/** Always tag bearer-bearing entries so the client sees the full catalog. */
+function withFullCatalogHeader(headers) {
+    return { ...(headers ?? {}), [MCP_FULL_CATALOG_HEADER]: "1" };
+}
+function responseMessage(json, fallback) {
+    const message = typeof json?.message === "string"
+        ? json.message
+        : typeof json?.error === "string"
+            ? json.error
+            : "";
+    return message.trim() || fallback;
+}
+async function postJson(fetchImpl, url, body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body ?? {}),
+            signal: controller.signal,
+        });
+        let json = null;
+        try {
+            json = await response.json();
+        }
+        catch {
+            json = null;
+        }
+        return { status: response.status, json };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * The exact no-browser fallback command core prints. Surfaced as guidance when
+ * a device-code client is asked to register non-interactively.
+ */
+function fallbackConnectCommand(baseUrl) {
+    return `npx @agent-native/core@latest connect ${baseUrl} --client all --token <token>`;
+}
+/** Write a URL-only entry (no bearer) for every config key, collecting files. */
+function writeUrlOnlyEntries(clients, keys, mcpUrl, scope, baseDir, written, errors) {
+    for (const client of clients) {
+        for (const key of keys) {
+            try {
+                const file = writeHttpEntryForClient(client, key, mcpUrl, undefined, baseDir, scope, undefined);
+                written.push({ client, file });
+            }
+            catch (err) {
+                errors.push(`Could not write ${key} for ${client}: ${err?.message ?? err}`);
+            }
+        }
+    }
+}
+/** Write a token+headers entry for every config key, collecting files. */
+function writeAuthedEntries(clients, keys, mcpUrl, token, headers, scope, baseDir, written, errors) {
+    for (const client of clients) {
+        for (const key of keys) {
+            try {
+                const file = writeHttpEntryForClient(client, key, mcpUrl, token, baseDir, scope, withFullCatalogHeader(headers));
+                written.push({ client, file });
+            }
+            catch (err) {
+                errors.push(`Could not write ${key} for ${client}: ${err?.message ?? err}`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Device-code flow (dependency-free port of core's runDeviceFlow)
+// ---------------------------------------------------------------------------
+/**
+ * Run the device-code flow against `baseUrl` and return the approved grant, or
+ * `null` (after logging a clear message) on expiry/consumed/error/timeout. Same
+ * state machine and field handling as core; the spinner/browser-open are
+ * dropped since this runs inside a non-interactive installer context.
+ */
+async function runDeviceFlow(baseUrl, appSlug, clientArg, log, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleep ?? realSleep;
+    const now = deps.now ?? (() => Date.now());
+    let start;
+    try {
+        const { status, json } = await postJson(fetchImpl, `${baseUrl}${DEVICE_START_PATH}`, { client: clientArg, app: appSlug });
+        if (status < 200 || status >= 300 || !json?.device_code) {
+            log(`  Could not start the connect flow on ${baseUrl} (HTTP ${status}). ` +
+                `Is this an agent-native app, and is it deployed with the connect ` +
+                `endpoint enabled?`);
+            return null;
+        }
+        start = json;
+    }
+    catch (err) {
+        log(`  Could not reach ${baseUrl} (${err?.message ?? err}). ` +
+            `Check the URL and your network.`);
+        return null;
+    }
+    const interval = Math.max(1, Number(start.interval) || 5);
+    const expiresIn = Math.max(interval, Number(start.expires_in) || 600);
+    const deadline = now() + expiresIn * 1000;
+    log("");
+    log(`  Connecting to ${baseUrl}`);
+    log("");
+    log(`  Your code:  ${start.user_code}`);
+    log(`  Open:       ${start.verification_uri_complete}`);
+    log("");
+    log("  Approve in the browser to finish.");
+    while (now() < deadline) {
+        let poll;
+        try {
+            const { status, json } = await postJson(fetchImpl, `${baseUrl}${DEVICE_POLL_PATH}`, { device_code: start.device_code });
+            if (status < 200 || status >= 300) {
+                log(`  Connect polling failed (HTTP ${status}): ` +
+                    responseMessage(json, "server returned an error."));
+                return null;
+            }
+            poll = (json ?? { status: "pending" });
+        }
+        catch {
+            // Transient network error — keep polling until the deadline.
+            poll = { status: "pending" };
+        }
+        if (poll.status === "approved") {
+            const token = poll.token ?? "";
+            const mcpUrl = poll.mcpUrl ?? `${baseUrl}${MCP_PATH}`;
+            const serverName = poll.serverName ?? appSlug;
+            const headers = poll.mcpServerEntry &&
+                typeof poll.mcpServerEntry === "object" &&
+                poll.mcpServerEntry.headers &&
+                typeof poll.mcpServerEntry.headers === "object"
+                ? poll.mcpServerEntry.headers
+                : undefined;
+            log("  Approved.");
+            return { token: token || undefined, mcpUrl, serverName, headers };
+        }
+        if (poll.status === "expired") {
+            log("  The connect request expired before it was approved.");
+            log("  Run the command again to retry.");
+            return null;
+        }
+        if (poll.status === "consumed") {
+            log("  This connect code was already used. Run the command again.");
+            return null;
+        }
+        if (poll.status === "error" || poll.status === "not_found") {
+            log(`  Connect polling failed: ${responseMessage(poll, poll.status === "not_found"
+                ? "device code was not found."
+                : "server returned an error.")}`);
+            return null;
+        }
+        await sleep(interval * 1000);
+    }
+    log("  Timed out waiting for approval. Run the command again to retry.");
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Register an MCP server (plus aliases) into the requested client configs,
+ * authenticating device-code clients via the browser flow when interactive.
+ *
+ * Idempotent: re-running replaces the same named entries. Never throws on a
+ * single client/key failing — failures are collected into `guidance`.
+ */
+export async function registerMcpServer(opts) {
+    const { descriptor, scope, baseDir, interactive } = opts;
+    const log = opts.log ?? (() => { });
+    const deps = opts.deps ?? {};
+    const written = [];
+    const guidance = [];
+    const errors = [];
+    let authenticated = false;
+    const keys = configKeys(descriptor);
+    const mcpUrl = resolveMcpUrl(descriptor);
+    if (!mcpUrl) {
+        return {
+            written,
+            authenticated,
+            guidance: [
+                `Cannot register "${descriptor.serverName}": no mcpUrl or hostedUrl supplied.`,
+            ],
+        };
+    }
+    const authMode = descriptor.authMode ?? "device";
+    // authMode "none" (e.g. context-xray): URL-only for ALL clients, no auth.
+    if (authMode === "none") {
+        writeUrlOnlyEntries(opts.clients, keys, mcpUrl, scope, baseDir, written, errors);
+        return { written, authenticated, guidance: [...guidance, ...errors] };
+    }
+    // Split into OAuth-capable and device-code clients, exactly like core.
+    const oauthClients = opts.clients.filter((c) => supportsRemoteMcpOAuth(c));
+    const deviceClients = opts.clients.filter((c) => !supportsRemoteMcpOAuth(c));
+    // OAuth clients always get URL-only entries (in-host OAuth, no local bearer).
+    if (oauthClients.length > 0) {
+        writeUrlOnlyEntries(oauthClients, keys, mcpUrl, scope, baseDir, written, errors);
+        guidance.push(`${describeClients(oauthClients)}: wrote URL-only MCP config (no bearer headers).`, "Next: restart Claude Code, run /mcp, and choose Authenticate.");
+    }
+    // Device-code clients.
+    if (deviceClients.length > 0) {
+        const baseUrl = resolveBaseUrl(descriptor);
+        // We only reach here for authMode "oauth"/"device" (authMode "none" returned
+        // earlier). Run the flow only when interactive AND we have a hosted URL to
+        // authenticate against; otherwise fall back to URL-only.
+        const canRunFlow = interactive && !!baseUrl;
+        if (!canRunFlow) {
+            writeUrlOnlyEntries(deviceClients, keys, mcpUrl, scope, baseDir, written, errors);
+            if (baseUrl) {
+                guidance.push(`${describeClients(deviceClients)}: wrote URL-only MCP config (no token).`, `To authenticate non-interactively, run: ${fallbackConnectCommand(baseUrl)}`);
+            }
+            else {
+                guidance.push(`${describeClients(deviceClients)}: wrote URL-only MCP config (no hosted URL to authenticate against).`);
+            }
+        }
+        else {
+            const appSlug = appSlugFor(descriptor, baseUrl);
+            const clientArg = deviceClients.length === 1 ? deviceClients[0] : "all";
+            const grant = await runDeviceFlow(baseUrl, appSlug, clientArg, log, deps);
+            if (grant && grant.token) {
+                // Write authed entries; honour the server's resolved mcpUrl when given.
+                const resolvedUrl = grant.mcpUrl || mcpUrl;
+                writeAuthedEntries(deviceClients, keys, resolvedUrl, grant.token, grant.headers, scope, baseDir, written, errors);
+                authenticated = true;
+            }
+            else {
+                // Flow failed (or approved with no token) — fall back to URL-only and
+                // surface the exact recovery command.
+                writeUrlOnlyEntries(deviceClients, keys, mcpUrl, scope, baseDir, written, errors);
+                guidance.push(`${describeClients(deviceClients)}: authentication did not complete; wrote URL-only MCP config.`, `To finish, run: ${fallbackConnectCommand(baseUrl)}`);
+            }
+        }
+    }
+    return { written, authenticated, guidance: [...guidance, ...errors] };
+}
+function describeClients(clients) {
+    return clients.join(", ");
+}
+/** Derive the `app` slug the device-start endpoint expects. */
+function appSlugFor(descriptor, baseUrl) {
+    // Prefer the descriptor's server name without the agent-native prefix.
+    const name = descriptor.serverName.replace(/^agent-native-/, "");
+    if (name)
+        return name;
+    try {
+        const host = new URL(baseUrl).hostname;
+        const first = host.split(".")[0];
+        return first && first !== "www" ? first : "app";
+    }
+    catch {
+        return "app";
+    }
+}
+//# sourceMappingURL=connect.js.map