@ken-jo/agent-connector 0.1.0

package/dist/types-CYUB1OTr.d.ts

@@ -0,0 +1,427 @@
+/**
+ * core/types — the shared contract surface for agent-connector.
+ *
+ * Everything in this file is type-only (no runtime), so it is safe to import
+ * from anywhere without creating module cycles. It is the single source of
+ * truth that every adapter, the telemetry layer, the CLI, and the public API
+ * code against.
+ *
+ * Grounded in the understand-phase report (docs/research/understand-report.md)
+ * and generalized from context-mode's proven 15-platform adapter SPI:
+ *   - context-mode hardcoded the served identity ("context-mode"); here the
+ *     identity is a parameter the developer supplies via defineConnector().
+ *   - context-mode's session/memory/FTS domain logic is removed from the SPI.
+ *   - MCP server registration is modeled here (root key + format differ per
+ *     platform, so adapters must render it — it is NOT "100% portable").
+ */
+/**
+ * Stable identifiers for every host platform agent-connector can target.
+ *
+ * NOTE on usage-only platforms: `"synthetic"` is a TELEMETRY-ONLY id
+ * (Octofriend / synthetic.new). It has a usage reader (usage/readers/synthetic)
+ * but DELIBERATELY no deploy adapter and no ADAPTER_REGISTRY entry — Octofriend
+ * exposes no writable MCP config to install into. The registry-completeness test
+ * (tests/adapters/registry-completeness.test.ts) allowlists it for this reason.
+ */
+type PlatformId = "claude-code" | "codex" | "cursor" | "vscode-copilot" | "jetbrains-copilot" | "copilot-cli" | "gemini-cli" | "opencode" | "kilo" | "kilo-cli" | "warp" | "hermes" | "openclaw" | "zed" | "antigravity" | "antigravity-cli" | "kiro" | "qwen-code" | "kimi" | "pi" | "omp" | "droid" | "roo-code" | "trae" | "amp" | "codebuff" | "mux" | "crush" | "goose" | "synthetic" | "unknown";
+/**
+ * Hook I/O paradigm — the deepest cross-platform divergence (report §4).
+ * Canonical shipped sets (keep in sync with src/adapters/registry.ts — this
+ * comment once drifted and seeded a docs-wide misclassification):
+ *   - "json-stdio" (16): host pipes JSON to a command on stdin, reads
+ *     JSON/exit-code back — Claude Code, Codex, Cursor, VS Code/JetBrains
+ *     Copilot, Copilot CLI, Gemini CLI, Qwen, Kiro, Kimi, Crush, Goose, Hermes,
+ *     Droid (Factory), Antigravity (+ the agy CLI). One universal entrypoint
+ *     binary handles all of them.
+ *   - "ts-plugin" (4): host loads a JS/TS module exporting lifecycle functions
+ *     — OpenCode, Kilo CLI, OMP, OpenClaw. Framework generates the module.
+ *   - "mcp-only" (9): no hook layer at all — Warp, Kilo, Roo Code, Trae, Zed,
+ *     Amp, Codebuff, Mux, Pi. Only the MCP server (or skills surface) is
+ *     installed; hooks are reported unavailable.
+ */
+type HookParadigm = "json-stdio" | "ts-plugin" | "mcp-only";
+/**
+ * Install scope, normalized across platforms and ordered low→high precedence.
+ * Each adapter maps these to a concrete config path and knows which it supports.
+ */
+type InstallScope = "system" | "user" | "project" | "profile" | "managed";
+type Transport = "stdio" | "http" | "sse" | "ws";
+interface ToolFilter {
+    /** Glob/exact tool names to expose. Default: ["*"]. */
+    include?: string[];
+    /** Glob/exact tool names to hide. */
+    exclude?: string[];
+}
+interface AuthSpec {
+    type: "oauth" | "bearerEnv" | "none";
+    /** Env var holding the bearer token when type === "bearerEnv". */
+    bearerEnvVar?: string;
+}
+/**
+ * A normalized, transport-polymorphic MCP server descriptor. Declared ONCE by
+ * the developer; each adapter renders it into that platform's native dialect
+ * (root key, field names, format). Adapters that cannot honor a requested
+ * transport downgrade-or-skip and report it — they never throw.
+ */
+interface ServerDef {
+    transport: Transport;
+    command?: string;
+    args?: string[];
+    /** Env vars passed to the server process. Values support ${env:VAR} interpolation. */
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    auth?: AuthSpec;
+    tools?: ToolFilter;
+    timeoutMs?: number;
+    /** Default true. When false, the entry is written disabled where supported. */
+    enabled?: boolean;
+    /**
+     * Wrap the server with `agent-connector serve` so per-tool telemetry is
+     * captured transparently. Default: true for stdio servers when telemetry is
+     * enabled; false for remote servers (cannot intercept) and when explicitly off.
+     */
+    wrapForTelemetry?: boolean;
+}
+/** Canonical, platform-agnostic lifecycle event names. */
+type HookEventName = "SessionStart" | "SessionEnd" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PreCompact" | "Stop" | "Notification";
+interface BaseEvent {
+    /** Which host produced this event (from runtime detection). */
+    hostPlatform: PlatformId;
+    /** Connector id this event is dispatched to. */
+    connectorId: string;
+    /** Host session id (adapter-extracted; "" when the host provides none). */
+    sessionId: string;
+    /** Project directory if the host exposes one. */
+    projectDir?: string;
+    /** Raw host-specific payload for passthrough/escape-hatch use. */
+    raw: unknown;
+}
+interface PreToolUseEvent extends BaseEvent {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+}
+interface PostToolUseEvent extends BaseEvent {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolOutput?: string;
+    isError?: boolean;
+}
+interface SessionStartEvent extends BaseEvent {
+    source: "startup" | "compact" | "resume" | "clear";
+}
+interface SessionEndEvent extends BaseEvent {
+    reason?: string;
+}
+interface UserPromptSubmitEvent extends BaseEvent {
+    prompt: string;
+}
+interface PreCompactEvent extends BaseEvent {
+    trigger?: "auto" | "manual";
+}
+interface StopEvent extends BaseEvent {
+    /** True when the stop hook itself was triggered during a previous stop hook. */
+    stopHookActive?: boolean;
+}
+interface NotificationEvent extends BaseEvent {
+    message: string;
+}
+/** Map of event name → its normalized payload type. */
+interface EventPayloadMap {
+    SessionStart: SessionStartEvent;
+    SessionEnd: SessionEndEvent;
+    UserPromptSubmit: UserPromptSubmitEvent;
+    PreToolUse: PreToolUseEvent;
+    PostToolUse: PostToolUseEvent;
+    PreCompact: PreCompactEvent;
+    Stop: StopEvent;
+    Notification: NotificationEvent;
+}
+/**
+ * Normalized hook response. A handler returns a subset of these; the adapter
+ * formats it into the host's native reply (exit codes / JSON / control fields).
+ * Adapters drop fields the host cannot honor (e.g. updatedOutput where the host
+ * cannot rewrite tool output) and the framework reports the degradation.
+ */
+interface HookResponse {
+    /**
+     *  - "allow":   pass through (default when handler returns void)
+     *  - "deny":    block tool execution / stop the action
+     *  - "modify":  replace tool input (PreToolUse) with `updatedInput`
+     *  - "context": inject `additionalContext` as soft guidance
+     *  - "ask":     prompt the user to confirm
+     */
+    decision?: "allow" | "deny" | "modify" | "context" | "ask";
+    /** Shown to the model/user; required in spirit for deny/ask. */
+    reason?: string;
+    /** Replacement tool input — only meaningful with decision "modify". */
+    updatedInput?: Record<string, unknown>;
+    /** Extra context to inject — meaningful with "context" or on SessionStart. */
+    additionalContext?: string;
+    /** Rewritten tool output — only where the host supports it (PostToolUse). */
+    updatedOutput?: string;
+}
+/** A handler bound to one event, optionally filtered by a tool matcher. */
+interface HookDefinition<E extends HookEventName = HookEventName> {
+    /**
+     * Regex string matched against the tool name (tool events only). Empty/omitted
+     * matches all. Rendered into each host's native matcher syntax where supported,
+     * else evaluated by the universal entrypoint at runtime.
+     */
+    matcher?: string;
+    handler(event: EventPayloadMap[E]): HookResponse | void | Promise<HookResponse | void>;
+}
+/** Developer-declared hooks, keyed by canonical event name. */
+interface HooksConfig {
+    SessionStart?: HookDefinition<"SessionStart">;
+    SessionEnd?: HookDefinition<"SessionEnd">;
+    UserPromptSubmit?: HookDefinition<"UserPromptSubmit">;
+    PreToolUse?: HookDefinition<"PreToolUse">;
+    PostToolUse?: HookDefinition<"PostToolUse">;
+    PreCompact?: HookDefinition<"PreCompact">;
+    Stop?: HookDefinition<"Stop">;
+    Notification?: HookDefinition<"Notification">;
+}
+/** What a given host can actually honor. The single-API layer degrades to it. */
+interface PlatformCapabilities {
+    preToolUse: boolean;
+    postToolUse: boolean;
+    preCompact: boolean;
+    sessionStart: boolean;
+    sessionEnd: boolean;
+    userPromptSubmit: boolean;
+    stop: boolean;
+    notification: boolean;
+    /** Can a PreToolUse hook rewrite tool arguments? */
+    canModifyArgs: boolean;
+    /** Can a PostToolUse hook rewrite tool output? */
+    canModifyOutput: boolean;
+    /** Can a hook inject context at session start / compaction? */
+    canInjectSessionContext: boolean;
+    /** MCP transports this host can register. */
+    transports: Transport[];
+    /**
+     * Content-surface support (all OPTIONAL so existing adapter capability
+     * literals compile unchanged; read as `?? false`). Only surface-supporting
+     * adapters set these true. The BaseAdapter install/uninstall defaults
+     * handle the "unsupported" skip/warn regardless of the flag.
+     */
+    supportsCommands?: boolean;
+    supportsSkills?: boolean;
+    supportsSubagents?: boolean;
+}
+/** Tool access expressed once; adapters render to allowed-tools / tools[] / readonly. */
+interface SurfaceToolPolicy {
+    allow?: string[];
+    deny?: string[];
+}
+/** A slash command (= a Skill on 2026 Claude; adapters pick the right surface). */
+interface CommandDef {
+    /** kebab-case; becomes the slash name and the filename stem. Source of truth. */
+    name: string;
+    /** One-line description for /help + model auto-selection. */
+    description?: string;
+    /** Prompt template body (markdown). The portable core of the command. */
+    prompt: string;
+    /** Shown in argument completion, e.g. "[environment]". */
+    argumentHint?: string;
+    tools?: SurfaceToolPolicy;
+    /** Model override (raw id or alias; adapters pass through or drop+warn). */
+    model?: string;
+    /** Force subagent / forked context where the platform supports it. */
+    subtask?: boolean;
+    /** Verbatim per-platform frontmatter additions (escape hatch). */
+    extra?: Record<string, unknown>;
+}
+/** An Agent Skill (folder + SKILL.md, Agent Skills open standard). */
+interface SkillDef {
+    /** <=64 chars, [a-z0-9-]; MUST equal the skill dir name. Source of truth. */
+    name: string;
+    /** <=1024 chars, 3rd-person "what + when"; drives model auto-selection. Required. */
+    description: string;
+    /** SKILL.md markdown body (instructions). */
+    body: string;
+    tools?: SurfaceToolPolicy;
+    model?: string;
+    disableModelInvocation?: boolean;
+    /** Extra files bundled beside SKILL.md, relative path → contents. */
+    resources?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+/** A named subagent (system-prompt + tool/model scoping). */
+interface SubagentDef {
+    /** kebab-case identifier. Source of truth (filename stem on most platforms). */
+    name: string;
+    /** Delegation hint shown to the orchestrator. Required. */
+    description: string;
+    /** System prompt = the agent's instructions (markdown body / developer_instructions). */
+    prompt: string;
+    tools?: SurfaceToolPolicy;
+    /** Model: alias|full-id|"inherit". Default left to platform. */
+    model?: string;
+    /** Coarse permission knob → Cursor readonly, opencode/kilo permission map. */
+    readonly?: boolean;
+    extra?: Record<string, unknown>;
+}
+interface TelemetryConfig {
+    /** On by default. Global kill switch also via AGENT_CONNECTOR_TELEMETRY=0. */
+    enabled?: boolean;
+    /** Tokenizer family selection. "auto" infers from client/host. */
+    modelFamilyHint?: "auto" | "openai" | "anthropic" | "generic";
+    /** Tokenize tools/list schemas once → fixed per-turn tool-definition overhead. */
+    measureToolDefs?: boolean;
+    /** Opt-in network calibration (sends content off-box — off by default). */
+    calibration?: {
+        anthropicCountTokens?: boolean;
+    };
+    /**
+     * OPT-IN host-native turn-usage capture (off by default). When enabled, the
+     * Gemini / Antigravity adapters ALSO install an AfterModel / PostInvocation hook
+     * that reads the host's `usageMetadata` and records a DISTINCT `model_turn`
+     * telemetry row (confidence `host-native`). Whole-conversation, never summed with
+     * the per-MCP `call` rows. May also be forced on at install via the env switch
+     * AGENT_CONNECTOR_HOST_NATIVE=1. Aggregate counts only; no raw content stored.
+     */
+    hostNativeUsage?: boolean;
+    /** Storage backend. NDJSON (default) needs no native deps; sqlite is an upgrade. */
+    store?: "ndjson" | "sqlite";
+}
+/** Per-platform override / escape hatch (report §3.2). */
+interface PlatformOverride {
+    /** false → do not install hooks on this platform; object → merge/replace hooks. */
+    hooks?: boolean | Partial<HooksConfig>;
+    /** false → do not register the MCP server here; object → shallow-merge into ServerDef. */
+    server?: Partial<ServerDef> | false;
+    /** Force a specific scope for this platform. */
+    scope?: InstallScope;
+    /** false → skip command files on this platform. */
+    commands?: boolean;
+    /** false → skip skill files on this platform. */
+    skills?: boolean;
+    /** false → skip subagent files on this platform. */
+    subagents?: boolean;
+    /** Verbatim fields merged into the native config (reach platform-exclusive features). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Distribution metadata for the OFFICIAL MCP standard artifacts `package` can
+ * emit — the registry `server.json` and the MCPB `.mcpb` bundle. These describe
+ * the developer's REAL upstream MCP server (what a registry installer / Claude
+ * Desktop runs directly), NOT agent-connector's telemetry `serve` wrapper, so
+ * they need inputs the cross-platform install does not: the namespace the dev
+ * proved ownership of, their published package name, and bundle author info.
+ *
+ * All optional — a connector that never publishes to the registry or as a
+ * bundle can omit this entirely; the relevant `package --format` raises a clear,
+ * actionable error only when its required field is missing.
+ */
+interface PublishConfig {
+    /**
+     * Reverse-DNS namespace the developer OWNS, e.g. "io.github.acme" or
+     * "com.acme". server.json `name` is rendered as `${registryNamespace}/${id}`.
+     * agent-connector never mints a namespace on the dev's behalf — the registry
+     * requires proven ownership (the `mcp-publisher login` step the dev runs).
+     */
+    registryNamespace?: string;
+    /**
+     * The developer's REAL published package that runs the MCP server, e.g.
+     * "@acme/acme-db-mcp" — server.json packages[].identifier. Required to emit a
+     * registry npm package entry (we cannot guess the published name).
+     */
+    packageName?: string;
+    /** Package registry base URL. Default https://registry.npmjs.org for npm. */
+    registryBaseUrl?: string;
+    /** Bundle author. The MCPB manifest requires author.name. */
+    author?: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+}
+/** What a developer passes to defineConnector(). */
+interface ConnectorConfig {
+    /** Stable connector id (kebab-case). Replaces context-mode's hardcoded identity. */
+    id: string;
+    displayName?: string;
+    version?: string;
+    /** The MCP server to deploy. Omit for a hooks-only connector. */
+    server?: ServerDef;
+    /** Lifecycle hooks. Omit for a server-only connector. */
+    hooks?: HooksConfig;
+    /** Telemetry options. Telemetry is ON by default even if this is omitted. */
+    telemetry?: TelemetryConfig;
+    /** Slash commands to deploy as native content files. */
+    commands?: CommandDef[];
+    /** Agent Skills to deploy as native content files. */
+    skills?: SkillDef[];
+    /** Named subagents to deploy as native content files. */
+    subagents?: SubagentDef[];
+    /** Per-platform overrides / escape hatches. */
+    platforms?: Partial<Record<PlatformId, PlatformOverride>>;
+    /** "auto" (all detected) or an explicit allow-list. Default "auto". */
+    targets?: "auto" | PlatformId[];
+    /** Distribution metadata for the registry server.json + MCPB bundle formats. */
+    publish?: PublishConfig;
+}
+/**
+ * A validated, normalized connector — what defineConnector() returns and what
+ * adapters/CLI consume. All optional config fields are resolved to defaults.
+ */
+interface ResolvedConnector {
+    id: string;
+    displayName: string;
+    version: string;
+    server?: ServerDef;
+    hooks: HooksConfig;
+    hookEvents: HookEventName[];
+    telemetry: Required<Omit<TelemetryConfig, "calibration">> & {
+        calibration: {
+            anthropicCountTokens: boolean;
+        };
+    };
+    /** Normalized commands; defaults applied; [] when none. */
+    commands: CommandDef[];
+    /** Normalized skills; defaults applied; [] when none. */
+    skills: SkillDef[];
+    /** Normalized subagents; defaults applied; [] when none. */
+    subagents: SubagentDef[];
+    platforms: Partial<Record<PlatformId, PlatformOverride>>;
+    targets: "auto" | PlatformId[];
+    /** Distribution metadata (registry server.json + MCPB bundle); passed through verbatim. */
+    publish?: PublishConfig;
+}
+/** Result of detecting one platform on this machine. */
+interface DetectedPlatform {
+    id: PlatformId;
+    name: string;
+    installed: boolean;
+    paradigm: HookParadigm;
+    capabilities: PlatformCapabilities;
+    /** Native config path that would be written for `scope`. */
+    configPath: string;
+    scope: InstallScope;
+    reason: string;
+    confidence: "high" | "medium" | "low";
+}
+interface ChangeRecord {
+    platform: PlatformId;
+    action: "create" | "update" | "skip" | "remove" | "warn";
+    /** File touched (when applicable). */
+    path?: string;
+    detail: string;
+}
+interface InstallResult {
+    connectorId: string;
+    dryRun: boolean;
+    changes: ChangeRecord[];
+    warnings: string[];
+}
+interface DiagnosticResult {
+    check: string;
+    status: "pass" | "fail" | "warn";
+    message: string;
+    fix?: string;
+}
+
+export type { AuthSpec as A, ConnectorConfig as C, DetectedPlatform as D, EventPayloadMap as E, HookDefinition as H, InstallResult as I, NotificationEvent as N, PlatformCapabilities as P, ResolvedConnector as R, ServerDef as S, TelemetryConfig as T, UserPromptSubmitEvent as U, ChangeRecord as a, DiagnosticResult as b, HookEventName as c, HookParadigm as d, HookResponse as e, HooksConfig as f, InstallScope as g, PlatformId as h, PlatformOverride as i, PostToolUseEvent as j, PreCompactEvent as k, PreToolUseEvent as l, SessionEndEvent as m, SessionStartEvent as n, StopEvent as o, ToolFilter as p, Transport as q };

package/dist/uninstall-IGCKNOSF.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import {
+  uninstallConnector
+} from "./chunk-7MSDGHJW.js";
+import {
+  fail,
+  parseScope,
+  parseTargets,
+  print,
+  renderInstallResult
+} from "./chunk-54EMKTTX.js";
+import "./chunk-KHO5WNTP.js";
+import "./chunk-XUCWLJY5.js";
+import {
+  findConnectorConfig,
+  loadConnectorFromPath
+} from "./chunk-LTT56GI3.js";
+import "./chunk-XNAM7F35.js";
+import "./chunk-TRQKHP7D.js";
+
+// src/cli/commands/uninstall.ts
+import { parseArgs } from "util";
+async function resolveConnectorId(explicitId, connectorPath, projectDir) {
+  if (explicitId && explicitId.trim() !== "") return explicitId;
+  const configPath = connectorPath ?? findConnectorConfig(projectDir);
+  if (!configPath) return null;
+  const { connector } = await loadConnectorFromPath(configPath);
+  return connector.id;
+}
+async function run(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      scope: { type: "string", default: "user" },
+      targets: { type: "string" },
+      connector: { type: "string" },
+      "connector-id": { type: "string" },
+      project: { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+      purge: { type: "boolean", default: false }
+    },
+    allowPositionals: false
+  });
+  const projectDir = values.project ?? process.cwd();
+  const scope = parseScope(values.scope);
+  if (scope == null) return fail(`invalid --scope "${values.scope}" (use user|project)`);
+  const connectorId = await resolveConnectorId(
+    values["connector-id"],
+    values.connector,
+    projectDir
+  );
+  if (!connectorId) {
+    return fail(
+      "could not determine connector id. Pass --connector-id <id>, --connector <path>, or run inside a project with an agent-connector config."
+    );
+  }
+  const targets = parseTargets(values.targets);
+  const result = await uninstallConnector({
+    connectorId,
+    scope,
+    projectDir,
+    dryRun: values["dry-run"],
+    purge: values.purge,
+    ...targets ? { targets } : {}
+  });
+  print(renderInstallResult(result, "uninstall"));
+  return result.changes.some((c) => c.action === "warn") ? 1 : 0;
+}
+export {
+  run
+};
+//# sourceMappingURL=uninstall-IGCKNOSF.js.map

package/dist/uninstall-IGCKNOSF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/commands/uninstall.ts"],"sourcesContent":["/**\n * cli/commands/uninstall — strip a connector's MCP + hook registrations.\n *\n * The connector id is taken from --connector-id, or inferred from the local\n * connector config (--connector <path> / findConnectorConfig). The installer's\n * uninstall orchestration loads the registered connector for context and removes\n * its entries from every resolved target.\n *\n * --purge additionally removes the framework-state this connector left behind:\n * its DATA-dir connector record (connectorDir(id)) and, when no connectors\n * remain, the shared home-bin launcher. Without --purge those linger so the\n * connector can be re-synced without re-registering.\n */\n\nimport { parseArgs } from \"node:util\";\n\nimport { uninstallConnector } from \"../../core/installer.js\";\nimport { findConnectorConfig, loadConnectorFromPath } from \"../../core/load-connector.js\";\nimport { fail, parseScope, parseTargets, print, renderInstallResult } from \"../app.js\";\n\n/** Resolve the connector id from flags, then from a local config file. */\nasync function resolveConnectorId(\n  explicitId: string | undefined,\n  connectorPath: string | undefined,\n  projectDir: string,\n): Promise<string | null> {\n  if (explicitId && explicitId.trim() !== \"\") return explicitId;\n  const configPath = connectorPath ?? findConnectorConfig(projectDir);\n  if (!configPath) return null;\n  const { connector } = await loadConnectorFromPath(configPath);\n  return connector.id;\n}\n\nexport async function run(argv: string[]): Promise<number> {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      scope: { type: \"string\", default: \"user\" },\n      targets: { type: \"string\" },\n      connector: { type: \"string\" },\n      \"connector-id\": { type: \"string\" },\n      project: { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n      purge: { type: \"boolean\", default: false },\n    },\n    allowPositionals: false,\n  });\n\n  const projectDir = values.project ?? process.cwd();\n\n  const scope = parseScope(values.scope);\n  if (scope == null) return fail(`invalid --scope \"${values.scope}\" (use user|project)`);\n\n  const connectorId = await resolveConnectorId(\n    values[\"connector-id\"],\n    values.connector,\n    projectDir,\n  );\n  if (!connectorId) {\n    return fail(\n      \"could not determine connector id. Pass --connector-id <id>, \" +\n        \"--connector <path>, or run inside a project with an agent-connector config.\",\n    );\n  }\n\n  const targets = parseTargets(values.targets);\n\n  const result = await uninstallConnector({\n    connectorId,\n    scope,\n    projectDir,\n    dryRun: values[\"dry-run\"],\n    purge: values.purge,\n    ...(targets ? { targets } : {}),\n  });\n\n  print(renderInstallResult(result, \"uninstall\"));\n  return result.changes.some((c) => c.action === \"warn\") ? 1 : 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAcA,SAAS,iBAAiB;AAO1B,eAAe,mBACb,YACA,eACA,YACwB;AACxB,MAAI,cAAc,WAAW,KAAK,MAAM,GAAI,QAAO;AACnD,QAAM,aAAa,iBAAiB,oBAAoB,UAAU;AAClE,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,EAAE,UAAU,IAAI,MAAM,sBAAsB,UAAU;AAC5D,SAAO,UAAU;AACnB;AAEA,eAAsB,IAAI,MAAiC;AACzD,QAAM,EAAE,OAAO,IAAI,UAAU;AAAA,IAC3B,MAAM;AAAA,IACN,SAAS;AAAA,MACP,OAAO,EAAE,MAAM,UAAU,SAAS,OAAO;AAAA,MACzC,SAAS,EAAE,MAAM,SAAS;AAAA,MAC1B,WAAW,EAAE,MAAM,SAAS;AAAA,MAC5B,gBAAgB,EAAE,MAAM,SAAS;AAAA,MACjC,SAAS,EAAE,MAAM,SAAS;AAAA,MAC1B,WAAW,EAAE,MAAM,WAAW,SAAS,MAAM;AAAA,MAC7C,OAAO,EAAE,MAAM,WAAW,SAAS,MAAM;AAAA,IAC3C;AAAA,IACA,kBAAkB;AAAA,EACpB,CAAC;AAED,QAAM,aAAa,OAAO,WAAW,QAAQ,IAAI;AAEjD,QAAM,QAAQ,WAAW,OAAO,KAAK;AACrC,MAAI,SAAS,KAAM,QAAO,KAAK,oBAAoB,OAAO,KAAK,sBAAsB;AAErF,QAAM,cAAc,MAAM;AAAA,IACxB,OAAO,cAAc;AAAA,IACrB,OAAO;AAAA,IACP;AAAA,EACF;AACA,MAAI,CAAC,aAAa;AAChB,WAAO;AAAA,MACL;AAAA,IAEF;AAAA,EACF;AAEA,QAAM,UAAU,aAAa,OAAO,OAAO;AAE3C,QAAM,SAAS,MAAM,mBAAmB;AAAA,IACtC;AAAA,IACA;AAAA,IACA;AAAA,IACA,QAAQ,OAAO,SAAS;AAAA,IACxB,OAAO,OAAO;AAAA,IACd,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,EAC/B,CAAC;AAED,QAAM,oBAAoB,QAAQ,WAAW,CAAC;AAC9C,SAAO,OAAO,QAAQ,KAAK,CAAC,MAAM,EAAE,WAAW,MAAM,IAAI,IAAI;AAC/D;","names":[]}

package/dist/upgrade-JV2VK242.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import {
+  resolveCliEntry,
+  syncConnector
+} from "./chunk-7MSDGHJW.js";
+import {
+  fail,
+  parseScope,
+  parseTargets,
+  print,
+  renderInstallResult
+} from "./chunk-54EMKTTX.js";
+import "./chunk-KHO5WNTP.js";
+import "./chunk-XUCWLJY5.js";
+import {
+  findConnectorConfig,
+  loadConnectorFromPath
+} from "./chunk-LTT56GI3.js";
+import "./chunk-XNAM7F35.js";
+import {
+  ensureHomeBin,
+  homeBinPath
+} from "./chunk-TRQKHP7D.js";
+
+// src/cli/commands/upgrade.ts
+import { parseArgs } from "util";
+function looksNpmManaged() {
+  const entry = resolveCliEntry().replace(/\\/g, "/");
+  return entry.includes("/node_modules/");
+}
+async function run(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      channel: { type: "string", default: "stable" },
+      scope: { type: "string", default: "user" },
+      targets: { type: "string" },
+      connector: { type: "string" },
+      project: { type: "string" },
+      "dry-run": { type: "boolean", default: false }
+    },
+    allowPositionals: false
+  });
+  const channel = values.channel;
+  if (channel !== "stable" && channel !== "latest") {
+    return fail(`invalid --channel "${channel}" (use stable|latest)`);
+  }
+  const ch = channel;
+  const scope = parseScope(values.scope);
+  if (scope == null) return fail(`invalid --scope "${values.scope}" (use user|project)`);
+  let hadWarn = false;
+  const projectDir = values.project ?? process.cwd();
+  const configPath = values.connector ?? findConnectorConfig(projectDir);
+  if (configPath) {
+    const { connector, modulePath } = await loadConnectorFromPath(configPath);
+    const targets = parseTargets(values.targets);
+    const result = await syncConnector({
+      connector,
+      modulePath,
+      scope,
+      projectDir,
+      dryRun: values["dry-run"],
+      ...targets ? { targets } : {}
+    });
+    print(renderInstallResult(result, "upgrade"));
+    if (result.changes.some((c) => c.action === "warn")) hadWarn = true;
+    print("");
+  } else {
+    print("upgrade: no connector config found \u2014 refreshing the tool only.");
+    print(
+      "(pass --connector <path> or run inside a project to also re-render host config.)\n"
+    );
+  }
+  print("agent-connector uses managed (explicit) updates \u2014 never silent");
+  print("auto-update \u2014 so one bad release can't break every project at once.\n");
+  const dist = ch === "stable" ? "latest" : "next";
+  if (looksNpmManaged()) {
+    print(`To update the ${ch} channel, run:`);
+    print(`  npm i -g @ken-jo/agent-connector@${dist}`);
+  } else {
+    print(
+      `This install does not look npm-managed. Update it the way you installed it,`
+    );
+    print(`then re-run \`agent-connector upgrade\` to refresh the home pointer.`);
+    print(`(npm installs would use: npm i -g @ken-jo/agent-connector@${dist})`);
+  }
+  if (!values["dry-run"]) {
+    try {
+      const binPath = ensureHomeBin(resolveCliEntry());
+      print(`
+Refreshed home binary pointer: ${binPath}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      print(`
+[warn] could not refresh home binary at ${homeBinPath()}: ${message}`);
+      return 1;
+    }
+  }
+  return hadWarn ? 1 : 0;
+}
+export {
+  run
+};
+//# sourceMappingURL=upgrade-JV2VK242.js.map

package/dist/upgrade-JV2VK242.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/commands/upgrade.ts"],"sourcesContent":["/**\n * cli/commands/upgrade — bring an agent-connector install current.\n *\n * `upgrade` (aliases: `update`, `sync`) consolidates the two former verbs into\n * ONE the way npm/brew pair `install` + `upgrade`, so there is a single verb to\n * learn for \"make everything current\". It:\n *\n *   1. re-renders the connector's config into every target host idempotently\n *      (identical entries report \"skip\"), exactly like the old `sync` — this is\n *      also the self-heal path: run `upgrade` to repair a drifted install; then\n *   2. refreshes the stable home-bin pointer and prints managed (never-silent)\n *      update guidance for the chosen channel, exactly like the old `update`.\n *\n * When no connector config is resolvable it still does step 2, so `upgrade`\n * works as a pure tool-refresh from anywhere. By design agent-connector NEVER\n * silently auto-updates (docs/ARCHITECTURE.md §3 R1).\n */\n\nimport { parseArgs } from \"node:util\";\n\nimport { resolveCliEntry, syncConnector } from \"../../core/installer.js\";\nimport { findConnectorConfig, loadConnectorFromPath } from \"../../core/load-connector.js\";\nimport { ensureHomeBin, homeBinPath } from \"../../core/paths.js\";\nimport { fail, parseScope, parseTargets, print, renderInstallResult } from \"../app.js\";\n\ntype Channel = \"stable\" | \"latest\";\n\n/** Heuristic: does the running CLI live under an npm-style node_modules tree? */\nfunction looksNpmManaged(): boolean {\n  const entry = resolveCliEntry().replace(/\\\\/g, \"/\");\n  return entry.includes(\"/node_modules/\");\n}\n\nexport async function run(argv: string[]): Promise<number> {\n  const { values } = parseArgs({\n    args: argv,\n    options: {\n      channel: { type: \"string\", default: \"stable\" },\n      scope: { type: \"string\", default: \"user\" },\n      targets: { type: \"string\" },\n      connector: { type: \"string\" },\n      project: { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n    },\n    allowPositionals: false,\n  });\n\n  const channel = values.channel;\n  if (channel !== \"stable\" && channel !== \"latest\") {\n    return fail(`invalid --channel \"${channel}\" (use stable|latest)`);\n  }\n  const ch: Channel = channel;\n\n  const scope = parseScope(values.scope);\n  if (scope == null) return fail(`invalid --scope \"${values.scope}\" (use user|project)`);\n\n  let hadWarn = false;\n\n  // ── Step 1: re-render the connector into every target host (former `sync`). ──\n  const projectDir = values.project ?? process.cwd();\n  const configPath = values.connector ?? findConnectorConfig(projectDir);\n  if (configPath) {\n    const { connector, modulePath } = await loadConnectorFromPath(configPath);\n    const targets = parseTargets(values.targets);\n    const result = await syncConnector({\n      connector,\n      modulePath,\n      scope,\n      projectDir,\n      dryRun: values[\"dry-run\"],\n      ...(targets ? { targets } : {}),\n    });\n    print(renderInstallResult(result, \"upgrade\"));\n    if (result.changes.some((c) => c.action === \"warn\")) hadWarn = true;\n    print(\"\");\n  } else {\n    print(\"upgrade: no connector config found — refreshing the tool only.\");\n    print(\n      \"(pass --connector <path> or run inside a project to also re-render host config.)\\n\",\n    );\n  }\n\n  // ── Step 2: managed update guidance + home-bin pointer refresh (former `update`). ──\n  print(\"agent-connector uses managed (explicit) updates — never silent\");\n  print(\"auto-update — so one bad release can't break every project at once.\\n\");\n\n  const dist = ch === \"stable\" ? \"latest\" : \"next\";\n  if (looksNpmManaged()) {\n    print(`To update the ${ch} channel, run:`);\n    print(`  npm i -g @ken-jo/agent-connector@${dist}`);\n  } else {\n    print(\n      `This install does not look npm-managed. Update it the way you installed it,`,\n    );\n    print(`then re-run \\`agent-connector upgrade\\` to refresh the home pointer.`);\n    print(`(npm installs would use: npm i -g @ken-jo/agent-connector@${dist})`);\n  }\n\n  // Refresh the stable home-bin pointer so hosts keep execing a working CLI.\n  if (!values[\"dry-run\"]) {\n    try {\n      const binPath = ensureHomeBin(resolveCliEntry());\n      print(`\\nRefreshed home binary pointer: ${binPath}`);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      print(`\\n[warn] could not refresh home binary at ${homeBinPath()}: ${message}`);\n      return 1;\n    }\n  }\n\n  return hadWarn ? 1 : 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAkBA,SAAS,iBAAiB;AAU1B,SAAS,kBAA2B;AAClC,QAAM,QAAQ,gBAAgB,EAAE,QAAQ,OAAO,GAAG;AAClD,SAAO,MAAM,SAAS,gBAAgB;AACxC;AAEA,eAAsB,IAAI,MAAiC;AACzD,QAAM,EAAE,OAAO,IAAI,UAAU;AAAA,IAC3B,MAAM;AAAA,IACN,SAAS;AAAA,MACP,SAAS,EAAE,MAAM,UAAU,SAAS,SAAS;AAAA,MAC7C,OAAO,EAAE,MAAM,UAAU,SAAS,OAAO;AAAA,MACzC,SAAS,EAAE,MAAM,SAAS;AAAA,MAC1B,WAAW,EAAE,MAAM,SAAS;AAAA,MAC5B,SAAS,EAAE,MAAM,SAAS;AAAA,MAC1B,WAAW,EAAE,MAAM,WAAW,SAAS,MAAM;AAAA,IAC/C;AAAA,IACA,kBAAkB;AAAA,EACpB,CAAC;AAED,QAAM,UAAU,OAAO;AACvB,MAAI,YAAY,YAAY,YAAY,UAAU;AAChD,WAAO,KAAK,sBAAsB,OAAO,uBAAuB;AAAA,EAClE;AACA,QAAM,KAAc;AAEpB,QAAM,QAAQ,WAAW,OAAO,KAAK;AACrC,MAAI,SAAS,KAAM,QAAO,KAAK,oBAAoB,OAAO,KAAK,sBAAsB;AAErF,MAAI,UAAU;AAGd,QAAM,aAAa,OAAO,WAAW,QAAQ,IAAI;AACjD,QAAM,aAAa,OAAO,aAAa,oBAAoB,UAAU;AACrE,MAAI,YAAY;AACd,UAAM,EAAE,WAAW,WAAW,IAAI,MAAM,sBAAsB,UAAU;AACxE,UAAM,UAAU,aAAa,OAAO,OAAO;AAC3C,UAAM,SAAS,MAAM,cAAc;AAAA,MACjC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,QAAQ,OAAO,SAAS;AAAA,MACxB,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC/B,CAAC;AACD,UAAM,oBAAoB,QAAQ,SAAS,CAAC;AAC5C,QAAI,OAAO,QAAQ,KAAK,CAAC,MAAM,EAAE,WAAW,MAAM,EAAG,WAAU;AAC/D,UAAM,EAAE;AAAA,EACV,OAAO;AACL,UAAM,qEAAgE;AACtE;AAAA,MACE;AAAA,IACF;AAAA,EACF;AAGA,QAAM,qEAAgE;AACtE,QAAM,4EAAuE;AAE7E,QAAM,OAAO,OAAO,WAAW,WAAW;AAC1C,MAAI,gBAAgB,GAAG;AACrB,UAAM,iBAAiB,EAAE,gBAAgB;AACzC,UAAM,sCAAsC,IAAI,EAAE;AAAA,EACpD,OAAO;AACL;AAAA,MACE;AAAA,IACF;AACA,UAAM,sEAAsE;AAC5E,UAAM,6DAA6D,IAAI,GAAG;AAAA,EAC5E;AAGA,MAAI,CAAC,OAAO,SAAS,GAAG;AACtB,QAAI;AACF,YAAM,UAAU,cAAc,gBAAgB,CAAC;AAC/C,YAAM;AAAA,iCAAoC,OAAO,EAAE;AAAA,IACrD,SAAS,KAAK;AACZ,YAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC/D,YAAM;AAAA,0CAA6C,YAAY,CAAC,KAAK,OAAO,EAAE;AAC9E,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO,UAAU,IAAI;AACvB;","names":[]}