@sentropic/h2a 0.90.1 → 0.90.3

package/dist/hosts/installation-doctor.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Host-installation convergence for `h2a doctor`.
+ *
+ * The h2a plugin is the canonical host integration. A direct `mcp-serve`
+ * configuration alongside that plugin starts a second endpoint, and the old
+ * standalone Track MCP starts a competing projection of `track_*` tools. This
+ * module treats both as an incoherent installation rather than a warning.
+ *
+ * Host plugin CLIs retain authority over their own installation registries.
+ * Doctor repairs their plain configuration/cache residue itself, then asks the
+ * native CLI to install/update the canonical `h2a@sentropic` plugin. A command
+ * failure is retained as an unrepaired finding; it must never become a clean
+ * result merely because a config file was edited.
+ */
+import type { H2ASession } from "../session.js";
+export declare const H2A_PLUGIN_SELECTOR = "h2a@sentropic";
+export declare const H2A_MARKETPLACE_NAME = "sentropic";
+export declare const H2A_MARKETPLACE_REPOSITORY = "rhanka/h2a";
+export declare const H2A_MARKETPLACE_GIT_URL = "https://github.com/rhanka/h2a.git";
+export declare const HOST_REPAIR_FRESHNESS_GUARANTEE = "doctor guarantees the coherence of the repairs it performed. It does not detect installation changes made by other tools; after changing your installation by hand, restart your sessions.";
+export declare const HOST_REPAIR_NATIVE_COMMAND_FAILURE_LIMIT = "If a native host CLI fails after it has already changed the installation, doctor reports the failure as host-command-failed and does not undo what that CLI already did. Doctor's own configuration writes are atomic. It has no snapshot of third-party state and does not simulate one: a partial restore would promise a recovery it cannot deliver. After a reported native failure, verify the host installation before relying on it.";
+type Host = "claude" | "codex";
+export interface HostCommandResult {
+    readonly ok: boolean;
+    readonly message?: string;
+}
+export type HostCommandRunner = (command: "claude" | "codex", args: readonly string[]) => HostCommandResult;
+export interface HostInstallationDoctorOptions {
+    readonly home?: string;
+    /** `false` is inspect-only. `true` performs the documented repair. */
+    readonly repair?: boolean;
+    /** Injectable for hermetic tests; production uses the running CLI version. */
+    readonly version?: string;
+    /** Injectable for hermetic tests; production invokes the native host CLI. */
+    readonly runHostCommand?: HostCommandRunner;
+    /** Test-only native-CLI reachability override; configuration artifacts decide host installation. */
+    readonly testHostCliReachable?: (host: Host) => boolean;
+    /** Test-only responses from the known-good and candidate Codex configuration probes. */
+    readonly testCodexConfigurationOracle?: {
+        readonly knownGood: HostCommandResult;
+        readonly candidate: HostCommandResult;
+    };
+    /** Test-only responses from the known-good and candidate Claude configuration probes. */
+    readonly testClaudeConfigurationOracle?: {
+        readonly knownGood: HostCommandResult;
+        readonly candidate: HostCommandResult;
+    };
+    /** Injectable for hermetic tests; production writes the durable repair marker. */
+    readonly writeRepairMarker?: (path: string, content: string) => void;
+    /** Report host repair findings and planned actions without mutating the host. */
+    readonly dryRun?: boolean;
+    /** Test-only Claude uninstall requests used to exercise the native-command boundary. */
+    readonly testClaudePluginUninstalls?: readonly string[];
+    /** Test-only fault injection for the atomic configuration-write boundary. */
+    readonly testConfigurationWrite?: {
+        readonly mutateRendered?: (path: string, format: "json" | "toml", rendered: string) => string;
+        readonly beforeRename?: (path: string, temporaryPath: string) => void;
+        readonly rename?: (temporaryPath: string, path: string) => void;
+    };
+}
+export interface HostInstallationFinding {
+    readonly code: "config-preserved" | "config-invalid" | "marketplace-missing" | "marketplace-stale" | "plugin-missing" | "plugin-stale" | "version-skew" | "orphan-cache" | "h2a-endpoint-count" | "standalone-track-mcp" | "host-command-failed" | "host-command-refused" | "host-command-unavailable" | "host-cli-unreachable" | "host-cli-unavailable" | "host-config-unavailable" | "host-config-unverifiable" | "host-not-installed" | "ownership-unverified" | "repair-marker-unavailable" | "repair-marker-write-failed" | "runtime-artifact-unavailable";
+    readonly message: string;
+    readonly path?: string;
+}
+export interface HostRepairMarker {
+    readonly path: string;
+    readonly repairedAt: string;
+    /** Concrete paths that a completed repair actually changed. */
+    readonly repairedPaths: readonly string[];
+}
+export interface HostInstallationReport {
+    readonly host: Host;
+    readonly ok: boolean;
+    readonly findings: readonly HostInstallationFinding[];
+    /** Non-blocking inspection notes; never a host-health or session-freshness verdict. */
+    readonly diagnostics: readonly HostInstallationFinding[];
+    readonly changed: readonly string[];
+    /** Deliberately retained host state, named precisely and never a health failure. */
+    readonly preserved: readonly HostInstallationFinding[];
+    /** Operations doctor attempted but could not complete; always prevent a healthy host verdict. */
+    readonly failures: readonly HostInstallationFinding[];
+    /** State doctor needed to verify but could not establish safely; always prevents a healthy host verdict. */
+    readonly unverifiable: readonly HostInstallationFinding[];
+    /** Backward-compatible flat view of blocking failures and unverifiable state. */
+    readonly unrepaired: readonly HostInstallationFinding[];
+    /** Declared artifacts retained for diagnostics and to determine precisely what a repair rewrote. */
+    readonly coherencePaths: readonly string[];
+    /** Host actions proposed by doctor; legacy-plugin transitions retain their prior value. */
+    readonly plannedActions: readonly string[];
+    /** Expected durable repair-marker location, whether or not it currently exists. */
+    readonly repairMarkerPath: string;
+    /** Durable fact recorded after this host installation was repaired. */
+    readonly repairMarker?: HostRepairMarker;
+}
+export interface HostInstallationDoctorReport {
+    readonly ok: boolean;
+    readonly repair: boolean;
+    readonly dryRun: boolean;
+    /** Exact boundary of the live-session restart guarantee. */
+    readonly sessionFreshnessGuarantee: string;
+    /** Exact boundary of recovery from a native host CLI failure. */
+    readonly nativeCommandFailureLimit: string;
+    readonly version: string;
+    readonly hosts: readonly HostInstallationReport[];
+}
+export interface LiveHostSessionFinding {
+    readonly host: Host;
+    readonly sessionId: string;
+    readonly startedAt: string;
+    readonly configPath: string;
+    readonly message: string;
+}
+/** Inspect, and optionally repair, the H2A installation state of both supported hosts. */
+export declare function doctorHostInstallations(options?: HostInstallationDoctorOptions): HostInstallationDoctorReport;
+/**
+ * A host repair cannot rewire an already-open stdio connection. A recorded
+ * repair marker is authoritative for our repairs. Doctor does not infer the
+ * complete runtime load graph, so externally modified artifacts are diagnostic
+ * only and never become a live-session freshness verdict.
+ */
+export declare function findLiveSessionsPredatingHostConfig(sessions: readonly H2ASession[], hosts: readonly HostInstallationReport[]): LiveHostSessionFinding[];
+export {};
+//# sourceMappingURL=installation-doctor.d.ts.map

package/dist/hosts/installation-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation-doctor.d.ts","sourceRoot":"","sources":["../../src/hosts/installation-doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAuBH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AACnD,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAC;AACvD,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAC3E,eAAO,MAAM,+BAA+B,+LACkJ,CAAC;AAC/L,eAAO,MAAM,wCAAwC,gbAC0X,CAAC;AAEhb,KAAK,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,QAAQ,GAAG,OAAO,EAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,iBAAiB,CAAC;AAEvB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,CAAC;IAC5C,oGAAoG;IACpG,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;IACxD,wFAAwF;IACxF,QAAQ,CAAC,4BAA4B,CAAC,EAAE;QACtC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;KACvC,CAAC;IACF,yFAAyF;IACzF,QAAQ,CAAC,6BAA6B,CAAC,EAAE;QACvC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACtC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;KACvC,CAAC;IACF,kFAAkF;IAClF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxD,6EAA6E;IAC7E,QAAQ,CAAC,sBAAsB,CAAC,EAAE;QAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;QACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;KACjE,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EACT,kBAAkB,GAClB,gBAAgB,GAChB,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,sBAAsB,GACtB,qBAAqB,GACrB,sBAAsB,GACtB,0BAA0B,GAC1B,sBAAsB,GACtB,sBAAsB,GACtB,yBAAyB,GACzB,0BAA0B,GAC1B,oBAAoB,GACpB,sBAAsB,GACtB,2BAA2B,GAC3B,4BAA4B,GAC5B,8BAA8B,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,4GAA4G;IAC5G,QAAQ,CAAC,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC1D,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACxD,oGAAoG;IACpG,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CAC1C;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AA00ED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CA+E9B;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,KAAK,EAAE,SAAS,sBAAsB,EAAE,GACvC,sBAAsB,EAAE,CA4D1B"}