@velum-labs/routekit-tool-claude 0.9.0

package/dist/install.d.ts

@@ -0,0 +1,26 @@
+export type ClaudeInstallOwner = {
+    id: string;
+    displayName: string;
+    installCommand: string;
+    uninstallCommand: string;
+    startCommand: string;
+};
+export type ClaudeInstallInput = {
+    gatewayUrl: string;
+    authToken?: string;
+    owner: ClaudeInstallOwner;
+    claudeConfigDir?: string;
+};
+export type ClaudeInstallResult = {
+    configPath: string;
+    action: "installed" | "updated";
+    managedKeys: string[];
+};
+export declare function installClaudeIntegration(input: ClaudeInstallInput): Promise<ClaudeInstallResult>;
+export declare function uninstallClaudeIntegration(input: {
+    ownerId: string;
+    claudeConfigDir?: string;
+}): Promise<{
+    configPath: string;
+    removed: boolean;
+}>;

package/dist/install.js

@@ -0,0 +1,519 @@
+import { chmodSync, lstatSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { SUBSCRIPTIONS } from "@velum-labs/routekit-registry";
+import { acquireLifecycleLock, trimTrailingSlashes, writeFileAtomic } from "@velum-labs/routekit-runtime";
+const MANAGED_ENV_KEYS = [
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"
+];
+function reached(boundary) {
+    // Deliberately not part of the package API: tests install a same-process
+    // throw hook to model termination immediately after an atomic boundary.
+    const testingGlobal = globalThis;
+    testingGlobal.__routekitClaudeInstallFaultInjector?.(boundary);
+}
+function assertSafeOwnerId(ownerId) {
+    if (ownerId.length === 0 ||
+        ownerId.includes("/") ||
+        ownerId.includes("\\") ||
+        ownerId === "." ||
+        ownerId === "..") {
+        throw new Error(`Claude integration owner id is not path-safe: ${JSON.stringify(ownerId)}`);
+    }
+}
+function defaultClaudeConfigDir() {
+    const registryPath = SUBSCRIPTIONS["claude-code"].configPath ?? "~/.claude/settings.json";
+    const configPath = registryPath.startsWith("~/")
+        ? join(homedir(), registryPath.slice(2))
+        : registryPath;
+    return dirname(configPath);
+}
+function paths(input) {
+    assertSafeOwnerId(input.ownerId);
+    const configDirectory = input.claudeConfigDir ??
+        process.env.CLAUDE_CONFIG_DIR ??
+        defaultClaudeConfigDir();
+    return {
+        configDirectory,
+        configPath: join(configDirectory, "settings.json"),
+        manifestPath: join(configDirectory, `.${input.ownerId}-integration.json`),
+        lockPath: join(configDirectory, ".routekit-claude-integration.lock")
+    };
+}
+function hash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function parseSettings(content, configPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        throw new Error(`your Claude settings (${configPath}) are not valid JSON (${detail})`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`your Claude settings (${configPath}) must contain a JSON object`);
+    }
+    const settings = parsed;
+    if (settings.env !== undefined &&
+        (typeof settings.env !== "object" || settings.env === null || Array.isArray(settings.env))) {
+        throw new Error(`the "env" field in your Claude settings (${configPath}) must be an object`);
+    }
+    return settings;
+}
+function unsupportedManifest(manifestPath) {
+    return new Error(`RouteKit's Claude ownership metadata (${manifestPath}) has an unsupported format`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    const validMode = value.mode === null ||
+        (typeof value.mode === "number" &&
+            Number.isInteger(value.mode) &&
+            value.mode >= 0 &&
+            value.mode <= 0o777);
+    return ((typeof value.content === "string" || value.content === null) &&
+        validMode &&
+        (value.content !== null || value.mode === null) &&
+        (typeof value.hash === "string" || value.hash === null) &&
+        value.hash === (value.content === null ? null : hash(value.content)));
+}
+function isStringRecord(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function isInstalledManifest(value) {
+    return (isRecord(value) &&
+        value.version === 2 &&
+        value.state === "installed" &&
+        typeof value.ownerId === "string" &&
+        isSnapshot(value.original) &&
+        typeof value.exactRestoreEligible === "boolean" &&
+        typeof value.installedContentHash === "string" &&
+        isStringRecord(value.managedEnvValues));
+}
+function parseManifest(content, manifestPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`RouteKit's Claude ownership metadata (${manifestPath}) is invalid; ` +
+            "move it aside and restore settings.json before retrying");
+    }
+    if (isRecord(parsed) &&
+        parsed.version === 1 &&
+        typeof parsed.ownerId === "string" &&
+        (typeof parsed.originalContent === "string" || parsed.originalContent === null) &&
+        typeof parsed.exactRestoreEligible === "boolean" &&
+        Array.isArray(parsed.installedContentHashes) &&
+        parsed.installedContentHashes.every((entry) => typeof entry === "string") &&
+        isRecord(parsed.managedEnvValues) &&
+        Object.values(parsed.managedEnvValues).every((entry) => Array.isArray(entry) &&
+            entry.every((candidate) => typeof candidate === "string"))) {
+        return parsed;
+    }
+    if (isInstalledManifest(parsed))
+        return parsed;
+    if (isRecord(parsed) &&
+        parsed.version === 2 &&
+        parsed.state === "install-pending" &&
+        typeof parsed.ownerId === "string" &&
+        isSnapshot(parsed.beforeSettings) &&
+        (parsed.beforeManifest === null ||
+            isInstalledManifest(parsed.beforeManifest)) &&
+        isSnapshot(parsed.targetSettings) &&
+        isInstalledManifest(parsed.targetManifest)) {
+        const pending = parsed;
+        if (pending.targetManifest.ownerId !== pending.ownerId ||
+            pending.targetManifest.installedContentHash !==
+                pending.targetSettings.hash ||
+            (pending.beforeManifest !== null &&
+                pending.beforeManifest.ownerId !== pending.ownerId)) {
+            throw unsupportedManifest(manifestPath);
+        }
+        return pending;
+    }
+    if (isRecord(parsed) &&
+        parsed.version === 2 &&
+        parsed.state === "uninstall-pending" &&
+        typeof parsed.ownerId === "string" &&
+        isSnapshot(parsed.beforeSettings) &&
+        isSnapshot(parsed.targetSettings)) {
+        return parsed;
+    }
+    throw unsupportedManifest(manifestPath);
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function managedEnv(input) {
+    return {
+        ANTHROPIC_BASE_URL: trimTrailingSlashes(input.gatewayUrl),
+        ANTHROPIC_AUTH_TOKEN: input.authToken ?? "routekit",
+        CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
+    };
+}
+function entryIfExists(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function assertConfigDirectory(configDirectory) {
+    const entry = entryIfExists(configDirectory);
+    if (entry === undefined)
+        return;
+    if (entry.isSymbolicLink()) {
+        throw new Error(`Claude config directory must not be a symlink: ${configDirectory}`);
+    }
+    if (!entry.isDirectory()) {
+        throw new Error(`Claude config path is not a directory: ${configDirectory}`);
+    }
+}
+function ensureConfigDirectory(configDirectory) {
+    assertConfigDirectory(configDirectory);
+    if (entryIfExists(configDirectory) !== undefined)
+        return;
+    mkdirSync(configDirectory, { recursive: true, mode: 0o700 });
+    assertConfigDirectory(configDirectory);
+    chmodSync(configDirectory, 0o700);
+}
+function assertRegularFileIfExists(path, label) {
+    const entry = entryIfExists(path);
+    if (entry === undefined)
+        return;
+    if (entry.isSymbolicLink()) {
+        throw new Error(`${label} must not be a symlink: ${path}`);
+    }
+    if (!entry.isFile()) {
+        throw new Error(`${label} must be a regular file: ${path}`);
+    }
+}
+function readSnapshot(path, label) {
+    assertRegularFileIfExists(path, label);
+    const entry = entryIfExists(path);
+    if (entry === undefined)
+        return { content: null, mode: null, hash: null };
+    const content = readFileSync(path, "utf8");
+    return {
+        content,
+        mode: entry.mode & 0o777,
+        hash: hash(content)
+    };
+}
+function snapshot(content, mode) {
+    return {
+        content,
+        mode,
+        hash: content === null ? null : hash(content)
+    };
+}
+function writePrivateFile(path, content, label) {
+    assertRegularFileIfExists(path, label);
+    writeFileAtomic(path, content, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function applySnapshot(path, target, label) {
+    assertRegularFileIfExists(path, label);
+    if (target.content === null) {
+        rmSync(path, { force: true });
+        return;
+    }
+    const mode = target.mode ?? 0o600;
+    writeFileAtomic(path, target.content, { mode });
+    chmodSync(path, mode);
+}
+function writeManifest(manifestPath, manifest) {
+    writePrivateFile(manifestPath, serialize(manifest), "Claude ownership metadata");
+}
+function currentManifest(manifestPath) {
+    assertRegularFileIfExists(manifestPath, "Claude ownership metadata");
+    return entryIfExists(manifestPath) === undefined
+        ? undefined
+        : parseManifest(readFileSync(manifestPath, "utf8"), manifestPath);
+}
+function assertExpectedSnapshot(current, expected, configPath, operation) {
+    if (expected.some((candidate) => candidate.hash === current.hash))
+        return;
+    throw new Error(`your Claude settings changed unexpectedly during ${operation} recovery (${configPath}); ` +
+        "RouteKit refused to overwrite the external edit");
+}
+function recoverPending(manifest, configPath, manifestPath) {
+    const current = readSnapshot(configPath, "Claude settings");
+    if (manifest.state === "install-pending") {
+        assertExpectedSnapshot(current, [manifest.beforeSettings, manifest.targetSettings], configPath, "install");
+        if (current.hash !== manifest.beforeSettings.hash) {
+            applySnapshot(configPath, manifest.beforeSettings, "Claude settings");
+        }
+        else if (current.content !== null &&
+            manifest.beforeSettings.mode !== null &&
+            current.mode !== manifest.beforeSettings.mode) {
+            chmodSync(configPath, manifest.beforeSettings.mode);
+        }
+        if (manifest.beforeManifest === null) {
+            assertRegularFileIfExists(manifestPath, "Claude ownership metadata");
+            rmSync(manifestPath, { force: true });
+        }
+        else {
+            writeManifest(manifestPath, manifest.beforeManifest);
+        }
+        return;
+    }
+    assertExpectedSnapshot(current, [manifest.beforeSettings, manifest.targetSettings], configPath, "uninstall");
+    if (current.hash !== manifest.targetSettings.hash) {
+        applySnapshot(configPath, manifest.targetSettings, "Claude settings");
+    }
+    else if (current.content !== null &&
+        manifest.targetSettings.mode !== null &&
+        current.mode !== manifest.targetSettings.mode) {
+        chmodSync(configPath, manifest.targetSettings.mode);
+    }
+    assertRegularFileIfExists(manifestPath, "Claude ownership metadata");
+    rmSync(manifestPath, { force: true });
+}
+function assertManagedValuesUnchanged(env, managedEnvValues, configPath) {
+    for (const [key, expected] of Object.entries(managedEnvValues)) {
+        const accepted = Array.isArray(expected) ? expected : [expected];
+        if (!accepted.includes(String(env[key]))) {
+            throw new Error(`your Claude settings changed RouteKit-managed env.${key} in ${configPath}; ` +
+                `remove or restore that value before rerunning the install command`);
+        }
+    }
+}
+const CLAUDE_LOCK_TIMEOUT_MS = 5_000;
+async function withConfigLock(resolved, operation) {
+    ensureConfigDirectory(resolved.configDirectory);
+    assertRegularFileIfExists(resolved.lockPath, "Claude integration lock");
+    assertRegularFileIfExists(`${resolved.lockPath}.reap`, "Claude integration reaper lock");
+    const lock = await acquireLifecycleLock(resolved.lockPath, {
+        timeoutMs: CLAUDE_LOCK_TIMEOUT_MS,
+        pollMs: 50
+    });
+    try {
+        assertConfigDirectory(resolved.configDirectory);
+        assertRegularFileIfExists(resolved.lockPath, "Claude integration lock");
+        return await operation();
+    }
+    finally {
+        lock.release();
+    }
+}
+function migrateLegacyManifest(manifest, current, configPath, manifestPath) {
+    const settings = parseSettings(current.content ?? "{}\n", configPath);
+    const env = { ...(settings.env ?? {}) };
+    const hasNoManagedValues = Object.keys(manifest.managedEnvValues).every((key) => env[key] === undefined);
+    if (current.content === manifest.originalContent &&
+        hasNoManagedValues) {
+        assertRegularFileIfExists(manifestPath, "Claude ownership metadata");
+        rmSync(manifestPath, { force: true });
+        return undefined;
+    }
+    if (current.hash === null ||
+        !manifest.installedContentHashes.includes(current.hash)) {
+        throw new Error(`RouteKit's legacy Claude ownership metadata (${manifestPath}) does not ` +
+            "match the current settings; refusing to overwrite them");
+    }
+    const selectedValues = {};
+    for (const [key, accepted] of Object.entries(manifest.managedEnvValues)) {
+        const value = env[key];
+        if (value === undefined || !accepted.includes(String(value))) {
+            throw new Error(`RouteKit's legacy Claude ownership metadata (${manifestPath}) cannot ` +
+                `safely identify the current env.${key} value; refusing to overwrite settings`);
+        }
+        selectedValues[key] = String(value);
+    }
+    const migrated = {
+        version: 2,
+        state: "installed",
+        ownerId: manifest.ownerId,
+        original: snapshot(manifest.originalContent, null),
+        exactRestoreEligible: manifest.exactRestoreEligible,
+        installedContentHash: current.hash,
+        managedEnvValues: selectedValues
+    };
+    writeManifest(manifestPath, migrated);
+    return migrated;
+}
+export async function installClaudeIntegration(input) {
+    const resolved = paths({
+        ownerId: input.owner.id,
+        ...(input.claudeConfigDir !== undefined
+            ? { claudeConfigDir: input.claudeConfigDir }
+            : {})
+    });
+    return await withConfigLock(resolved, () => {
+        const { configPath, manifestPath } = resolved;
+        let manifest = currentManifest(manifestPath);
+        if (manifest !== undefined &&
+            manifest.ownerId !== input.owner.id) {
+            throw new Error(`Claude ownership metadata in ${manifestPath} belongs to another integration`);
+        }
+        if (manifest?.version === 2 &&
+            manifest.state !== "installed") {
+            recoverPending(manifest, configPath, manifestPath);
+            manifest = currentManifest(manifestPath);
+        }
+        const beforeSettings = readSnapshot(configPath, "Claude settings");
+        let previousManifest;
+        if (manifest?.version === 1) {
+            previousManifest = migrateLegacyManifest(manifest, beforeSettings, configPath, manifestPath);
+        }
+        else if (manifest?.state === "installed") {
+            previousManifest = manifest;
+        }
+        else if (manifest !== undefined) {
+            throw unsupportedManifest(manifestPath);
+        }
+        const settings = parseSettings(beforeSettings.content ?? "{}\n", configPath);
+        const env = { ...(settings.env ?? {}) };
+        const nextManaged = managedEnv(input);
+        if (previousManifest === undefined) {
+            for (const key of MANAGED_ENV_KEYS) {
+                if (env[key] !== undefined) {
+                    throw new Error(`your Claude settings already define env.${key} in ${configPath}; ` +
+                        `remove it or use \`${input.owner.uninstallCommand}\` only after configuring RouteKit`);
+                }
+            }
+        }
+        else {
+            assertManagedValuesUnchanged(env, previousManifest.managedEnvValues, configPath);
+        }
+        for (const key of Object.keys(previousManifest?.managedEnvValues ?? {})) {
+            delete env[key];
+        }
+        Object.assign(env, nextManaged);
+        const nextSettings = { ...settings, env };
+        const nextContent = serialize(nextSettings);
+        const targetSettings = snapshot(nextContent, 0o600);
+        const exactRestoreEligible = previousManifest === undefined
+            ? true
+            : previousManifest.exactRestoreEligible &&
+                beforeSettings.hash === previousManifest.installedContentHash;
+        const targetManifest = {
+            version: 2,
+            state: "installed",
+            ownerId: input.owner.id,
+            original: previousManifest?.original ?? beforeSettings,
+            exactRestoreEligible,
+            installedContentHash: targetSettings.hash,
+            managedEnvValues: nextManaged
+        };
+        const pendingManifest = {
+            version: 2,
+            state: "install-pending",
+            ownerId: input.owner.id,
+            beforeSettings,
+            beforeManifest: previousManifest ?? null,
+            targetSettings,
+            targetManifest
+        };
+        writeManifest(manifestPath, pendingManifest);
+        reached("install-pending");
+        const unchanged = readSnapshot(configPath, "Claude settings");
+        assertExpectedSnapshot(unchanged, [beforeSettings], configPath, "install");
+        applySnapshot(configPath, targetSettings, "Claude settings");
+        reached("install-settings");
+        const pending = currentManifest(manifestPath);
+        if (pending?.version !== 2 ||
+            pending.state !== "install-pending") {
+            throw new Error(`Claude ownership metadata changed unexpectedly during install (${manifestPath})`);
+        }
+        writeManifest(manifestPath, targetManifest);
+        reached("install-committed");
+        return {
+            configPath,
+            action: previousManifest === undefined ? "installed" : "updated",
+            managedKeys: Object.keys(nextManaged)
+        };
+    });
+}
+export async function uninstallClaudeIntegration(input) {
+    const resolved = paths(input);
+    return await withConfigLock(resolved, () => {
+        const { configPath, manifestPath } = resolved;
+        let manifest = currentManifest(manifestPath);
+        if (manifest === undefined)
+            return { configPath, removed: false };
+        if (manifest.ownerId !== input.ownerId) {
+            throw new Error(`Claude ownership metadata in ${manifestPath} belongs to another integration`);
+        }
+        if (manifest.version === 2 && manifest.state !== "installed") {
+            recoverPending(manifest, configPath, manifestPath);
+            if (manifest.state === "uninstall-pending") {
+                reached("uninstall-committed");
+                return { configPath, removed: true };
+            }
+            manifest = currentManifest(manifestPath);
+            if (manifest === undefined)
+                return { configPath, removed: false };
+        }
+        const beforeSettings = readSnapshot(configPath, "Claude settings");
+        let installed;
+        if (manifest.version === 1) {
+            installed = migrateLegacyManifest(manifest, beforeSettings, configPath, manifestPath);
+        }
+        else if (manifest.state === "installed") {
+            installed = manifest;
+        }
+        else {
+            throw unsupportedManifest(manifestPath);
+        }
+        if (installed === undefined)
+            return { configPath, removed: false };
+        let targetSettings;
+        if (installed.exactRestoreEligible &&
+            beforeSettings.hash === installed.installedContentHash) {
+            targetSettings = installed.original;
+        }
+        else if (beforeSettings.content !== null) {
+            const settings = parseSettings(beforeSettings.content, configPath);
+            const env = { ...(settings.env ?? {}) };
+            for (const [key, accepted] of Object.entries(installed.managedEnvValues)) {
+                if (String(env[key]) === accepted)
+                    delete env[key];
+            }
+            const next = { ...settings };
+            if (Object.keys(env).length === 0)
+                delete next.env;
+            else
+                next.env = env;
+            targetSettings = snapshot(serialize(next), beforeSettings.mode);
+        }
+        else {
+            targetSettings = beforeSettings;
+        }
+        const pendingManifest = {
+            version: 2,
+            state: "uninstall-pending",
+            ownerId: input.ownerId,
+            beforeSettings,
+            targetSettings
+        };
+        writeManifest(manifestPath, pendingManifest);
+        reached("uninstall-pending");
+        const unchanged = readSnapshot(configPath, "Claude settings");
+        assertExpectedSnapshot(unchanged, [beforeSettings], configPath, "uninstall");
+        applySnapshot(configPath, targetSettings, "Claude settings");
+        reached("uninstall-settings");
+        const pending = currentManifest(manifestPath);
+        if (pending?.version !== 2 ||
+            pending.state !== "uninstall-pending") {
+            throw new Error(`Claude ownership metadata changed unexpectedly during uninstall (${manifestPath})`);
+        }
+        rmSync(manifestPath, { force: true });
+        reached("uninstall-committed");
+        return { configPath, removed: true };
+    });
+}

package/dist/launch.d.ts

@@ -0,0 +1,6 @@
+import type { AgentProfile, ToolLaunchContext } from "@velum-labs/routekit-tools";
+export declare function claudeEnv(gatewayUrl: string, authToken?: string): Record<string, string>;
+/** Serialize host-authored profiles once into Claude's session agent format. */
+export declare function claudeAgentsJson(profiles: readonly AgentProfile[]): string;
+export declare function claudeLaunchArgs(ctx: ToolLaunchContext): string[];
+export declare function launchClaude(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -0,0 +1,51 @@
+import { spawnTool } from "@velum-labs/routekit-runtime";
+export function claudeEnv(gatewayUrl, authToken) {
+    return {
+        ANTHROPIC_BASE_URL: gatewayUrl,
+        ANTHROPIC_AUTH_TOKEN: authToken ?? "routekit",
+        CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1",
+        ...(process.env.CLAUDE_CONFIG_DIR !== undefined
+            ? { CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR }
+            : {})
+    };
+}
+function claudeModelId(modelId) {
+    const pickerId = modelId.startsWith("claude-code/")
+        ? modelId.slice("claude-code/".length)
+        : modelId;
+    return pickerId.startsWith("claude") || pickerId.startsWith("anthropic")
+        ? pickerId
+        : `claude-${pickerId}`;
+}
+/** Serialize host-authored profiles once into Claude's session agent format. */
+export function claudeAgentsJson(profiles) {
+    return JSON.stringify(Object.fromEntries(profiles.map((profile) => [
+        profile.id,
+        {
+            description: profile.description,
+            prompt: profile.instructions,
+            model: claudeModelId(profile.model)
+        }
+    ])));
+}
+function hasAgentsArg(args) {
+    return args.some((arg) => arg === "--agents" || arg.startsWith("--agents="));
+}
+function hasModelArg(args) {
+    return args.some((arg) => arg === "--model" || arg.startsWith("--model="));
+}
+export function claudeLaunchArgs(ctx) {
+    const args = [...ctx.spec.args];
+    if (!hasModelArg(args)) {
+        args.unshift("--model", claudeModelId(ctx.spec.defaultModel));
+    }
+    const profiles = ctx.spec.agentProfiles ?? [];
+    if (profiles.length > 0 && !hasAgentsArg(args)) {
+        args.push("--agents", claudeAgentsJson(profiles));
+    }
+    return args;
+}
+export async function launchClaude(ctx) {
+    ctx.prepareForPassthrough();
+    return await spawnTool("claude", claudeLaunchArgs(ctx), claudeEnv(ctx.spec.gatewayUrl, ctx.spec.auth?.token), ctx.spec.cwd);
+}

package/dist/test/driver.test.d.ts

@@ -0,0 +1 @@
+export {};