@illuminis/comprism 0.1.0

package/out/commands/install.d.ts

@@ -0,0 +1,163 @@
+/** The header the tenant reads to decide whether this machine may be served. */
+export declare const WORKSPACE_KEY_HEADER = "x-comprism-key";
+export declare function envScriptPath(): string;
+export declare function pidFilePath(): string;
+export declare function proxyLogPath(): string;
+/** Every profile we should add the line to, that actually exists. */
+export declare function shellProfiles(): string[];
+/**
+ * The tenant's own endpoint, and never anything on this machine.
+ *
+ * Three sources, most specific first: what the caller passed, the connection
+ * `comprism login` stored, and the tenant and domain in config. Null when none
+ * of them names a tenant, and null is load-bearing - the install then writes a
+ * script that exports nothing rather than one that guesses a hostname.
+ */
+export declare function tenantBaseUrl(explicit?: string): string | null;
+/**
+ * The script every new shell sources.
+ *
+ * Written as POSIX shell so it works in bash and zsh alike, and deliberately
+ * silent: a shell startup file that prints things is a shell startup file people
+ * delete.
+ *
+ * `OPENAI_BASE_URL` is deliberately NOT set. The hosted interceptor speaks the
+ * Anthropic shape today, so pointing an OpenAI client at it would send that
+ * client somewhere with no route for it - breaking a working tool in order to
+ * measure it, which is the one thing this file exists to prevent. It comes back
+ * the day there is an OpenAI-shaped endpoint to point at.
+ */
+export declare function envScript(baseUrl: string | null, workspaceKey?: string | null): string;
+export interface InstallReport {
+    envScript: string;
+    profilesTouched: string[];
+    profilesAlreadyHad: string[];
+    /** The tenant endpoint written into the script, or null if none is known. */
+    baseUrl: string | null;
+    /** Whether this machine holds a workspace key. Without one, nothing is exported. */
+    enrolled: boolean;
+    binary: LaunchCommand;
+    desktop: DesktopReport;
+}
+export interface DesktopReport {
+    /** Where the config lives, whether or not we wrote it. */
+    configPath: string;
+    /** Did the desktop client's config directory exist at all? */
+    present: boolean;
+    /**
+     * Always false. Kept so a caller reading this report cannot mistake "we
+     * touched the config" for "the connector is live" - the hosted connector is
+     * authorized by a consent screen, never by a file we write.
+     */
+    registered: boolean;
+    /** Did we take an earlier version's stdio entry back out? */
+    staleRemoved: boolean;
+    /** Set when we deliberately did nothing. */
+    note?: string;
+}
+/**
+ * Where the desktop client keeps its connector list, per platform.
+ *
+ * Only the directory the client itself created counts. Creating it ourselves on
+ * a machine with no desktop client would leave a config file for an application
+ * that is not installed, which is litter.
+ */
+export declare function desktopConfigPath(): string;
+/**
+ * Take our STDIO entry back out of Claude Desktop's config, and say what to add
+ * instead.
+ *
+ * This used to REGISTER a stdio server here - `node cli.js mcp` - and that was
+ * wrong in a way that cost a real afternoon. That server exposes `record_work`,
+ * `completion_receipt` and `coverage`: it only ever OBSERVES. It does not route,
+ * it does not answer, so there is no receipt for the client to render, and it
+ * appends to `~/.comprism/ledger.jsonl` on this laptop rather than to the
+ * tenant, so nothing it records can ever appear in the portal. The install then
+ * printed "Claude Desktop connector registered and answering", which was true of
+ * the handshake and false about the product.
+ *
+ * The connector that works is the hosted one, `{tenant}/mcp`, which runs the
+ * same nine steps as every other surface, returns the answer with the receipt
+ * attached, and writes the turn to the tenant. It is added by pasting its
+ * address into Claude Desktop's own Connectors dialog, because a remote
+ * connector is authorized by an OAuth consent screen that only the person
+ * sitting there can approve - there is nothing an installer could write into a
+ * file to stand in for that.
+ *
+ * So this now does the honest thing: removes a stale entry of ours if one is
+ * there, never writes one, and returns the address for the caller to print. Two
+ * things it still will never do: create the file on a machine where the desktop
+ * client is not installed, and overwrite a config it could not parse.
+ */
+export declare function installDesktopConnector(_binary: LaunchCommand): DesktopReport;
+/**
+ * Start the connector exactly as the desktop client will, and see if it answers.
+ *
+ * Written after a live failure that the installer had already called a success.
+ * `npm install -g .` from a checkout leaves the global package as a SYMLINK back
+ * into the source folder; on macOS the desktop client is sandboxed out of
+ * `~/Documents`, so the connector died on `EPERM` the moment it was launched -
+ * and the only trace was a log file nobody thinks to open. The installer said
+ * "registered", which was true and useless.
+ *
+ * So registration is no longer the claim. This spawns the real command, speaks
+ * the real handshake and waits for the real reply. A connector that cannot start
+ * is reported as broken, with the reason, at install time.
+ */
+export declare function probeDesktopConnector(binary: LaunchCommand): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Take the connector back out, leaving every other server alone. */
+export declare function uninstallDesktopConnector(): boolean;
+/**
+ * Do the setup. Idempotent: running it twice changes nothing the second time.
+ */
+export declare function install(options?: {
+    baseUrl?: string;
+    binary?: LaunchCommand;
+    workspaceKey?: string | null;
+}): InstallReport;
+/** Take the line back out. An install you cannot cleanly undo is a liability. */
+export declare function uninstall(): {
+    profilesCleaned: string[];
+};
+/**
+ * The command that starts this package's CLI, resolved from the package itself.
+ *
+ * It used to read `process.argv[1]` and assume that was the CLI. That holds when
+ * a person types `comprism install`, and is FALSE in the one case that matters
+ * most: the npm postinstall hook, where argv[1] is `postinstall.js`. So a global
+ * install wrote `node .../postinstall.js mcp` into the desktop config, and the
+ * connector "disconnected" on every launch - postinstall ignores the argument,
+ * does its work and exits, which looks exactly like a crash from the outside.
+ * It also silently overwrote a correct entry written moments earlier.
+ *
+ * Resolving from `__dirname` instead removes the guess: this file compiles to
+ * `out/install.js`, so the CLI is always `out/cli.js` beside it, whoever is
+ * calling and from where.
+ */
+/**
+ * How to start the CLI: a command and its arguments, kept apart.
+ *
+ * Apart, and never joined with a space, because "/Users/me/Code - Illuminis/…"
+ * is an ordinary macOS path and splitting on spaces turns it into three
+ * arguments and a connector that cannot launch. A shell string and an argv are
+ * different types; treating them as one is a bug waiting for the first customer
+ * whose folder has a space in it, which on a Mac is most of them.
+ */
+export interface LaunchCommand {
+    command: string;
+    args: string[];
+}
+/** The shell form, quoted, for the profile script that must be a shell string. */
+export declare function launchShellString(launch: LaunchCommand): string;
+export declare function proxyHealthy(port: number): Promise<boolean>;
+/**
+ * Start the proxy detached, so it outlives the shell that started it.
+ *
+ * Returns whether it came up. Never throws: a service that fails to start is a
+ * missing measurement, and the caller's job is to carry on regardless.
+ */
+export declare function startDaemon(port: number): Promise<boolean>;
+export declare function stopDaemon(): boolean;