@kimchi-dev/kimchictl 0.0.2

package/src/ssh/bridge.test.ts

@@ -0,0 +1,70 @@
+import type { AddressInfo } from "node:net"
+import { Readable, Writable } from "node:stream"
+import { afterEach, describe, expect, it } from "vitest"
+import { WebSocketServer } from "ws"
+import { BridgeError, bridgeStdioToWebSocket } from "./bridge.js"
+
+const servers: WebSocketServer[] = []
+
+afterEach(async () => {
+	await Promise.all(servers.splice(0).map((s) => new Promise<void>((resolve) => s.close(() => resolve()))))
+})
+
+/** Start an echo+header-capture WS server. Returns the ws:// URL and captured state. */
+async function startEchoServer(): Promise<{ url: string; authHeader: { value?: string } }> {
+	const wss = new WebSocketServer({ port: 0 })
+	servers.push(wss)
+	const authHeader: { value?: string } = {}
+	wss.on("connection", (ws, req) => {
+		authHeader.value = req.headers.authorization
+		ws.binaryType = "arraybuffer"
+		ws.on("message", (data, isBinary) => {
+			ws.send(data, { binary: isBinary })
+		})
+	})
+	await new Promise<void>((resolve) => wss.on("listening", resolve))
+	const { port } = wss.address() as AddressInfo
+	return { url: `ws://127.0.0.1:${port}/ssh`, authHeader }
+}
+
+function collectOutput(): { output: Writable; chunks: Buffer[] } {
+	const chunks: Buffer[] = []
+	const output = new Writable({
+		write(chunk, _encoding, callback) {
+			chunks.push(Buffer.from(chunk))
+			callback()
+		},
+	})
+	return { output, chunks }
+}
+
+describe("bridgeStdioToWebSocket", () => {
+	it("pumps stdin chunks through the WS and echoes them back to stdout", async () => {
+		const { url, authHeader } = await startEchoServer()
+		const { output, chunks } = collectOutput()
+
+		await bridgeStdioToWebSocket({
+			wsUrl: url,
+			token: "workspace-jwt",
+			input: Readable.from([Buffer.from("hello "), Buffer.from([0x00, 0xff, 0x42])]),
+			output,
+		})
+
+		expect(authHeader.value).toBe("Bearer workspace-jwt")
+		expect(Buffer.concat(chunks).toString("hex")).toBe(
+			Buffer.concat([Buffer.from("hello "), Buffer.from([0x00, 0xff, 0x42])]).toString("hex"),
+		)
+	})
+
+	it("fails to start with a BridgeError when the endpoint rejects the handshake", async () => {
+		// No server listening on this port.
+		await expect(
+			bridgeStdioToWebSocket({
+				wsUrl: "ws://127.0.0.1:1/ssh",
+				token: "t",
+				input: Readable.from([]),
+				output: collectOutput().output,
+			}),
+		).rejects.toThrow(BridgeError)
+	})
+})

package/src/ssh/bridge.ts

@@ -0,0 +1,110 @@
+import type { Readable, Writable } from "node:stream"
+import { type RawData, WebSocket } from "ws"
+
+/**
+ * Binary WebSocket↔stdio bridge — the runtime behind the hidden
+ * `kimchictl ssh proxy` command that the generated ssh_config references via
+ * ProxyCommand. TS port of kap's internal/ssh/bridge.go.
+ *
+ * Exit semantics (mirroring kap): stdin EOF or a normal WS close end the
+ * bridge without error; any other failure rejects with a descriptive error.
+ * The proxy process is short-lived — it exits when the bridge resolves, so
+ * dangling listeners cannot outlive it.
+ */
+
+export class BridgeError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "BridgeError"
+	}
+}
+
+export interface BridgeOptions {
+	wsUrl: string
+	token: string
+	input?: Readable
+	output?: Writable
+	/** Injected WebSocket constructor (tests may pass a wrapped client). */
+	_WebSocket?: typeof WebSocket
+}
+
+export async function bridgeStdioToWebSocket(options: BridgeOptions): Promise<void> {
+	const WS = options._WebSocket ?? WebSocket
+	const input = options.input ?? process.stdin
+	const output = options.output ?? process.stdout
+
+	let ws: InstanceType<typeof WebSocket>
+	try {
+		ws = new WS(options.wsUrl, {
+			headers: { Authorization: `Bearer ${options.token}` },
+		})
+	} catch (err) {
+		throw new BridgeError(`websocket dial ${options.wsUrl}: ${err instanceof Error ? err.message : String(err)}`)
+	}
+
+	await new Promise<void>((resolve, reject) => {
+		let settled = false
+		const done = (err?: Error) => {
+			if (settled) return
+			settled = true
+			if (err) reject(err)
+			else resolve()
+		}
+
+		ws.on("open", () => done())
+		ws.on("unexpected-response", (_req, res) => {
+			done(
+				new BridgeError(
+					`websocket dial ${options.wsUrl}: unexpected HTTP ${res.statusCode} ${res.statusMessage ?? ""}`.trim(),
+				),
+			)
+		})
+		ws.on("error", (err) => done(new BridgeError(`websocket dial ${options.wsUrl}: ${err.message}`)))
+	})
+
+	return new Promise<void>((resolve, reject) => {
+		let settled = false
+		const finish = (err?: Error) => {
+			if (settled) return
+			settled = true
+			input.removeAllListeners()
+			// Output is process.stdout when bridging for real — never end() that;
+			// only close streams the caller explicitly passed in.
+			if (options.output) output.end()
+			if (err) reject(err)
+			else resolve()
+		}
+
+		// WS → stdout
+		ws.on("message", (data: RawData, isBinary: boolean) => {
+			// The workspace bridge is binary-only; text frames would be a server bug,
+			// but writing them through is still friendlier than dropping bytes.
+			void isBinary
+			const buffer = Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data)
+			if (!output.write(buffer)) {
+				// Keep memory bounded if the consumer stalls: pause the socket until drained.
+				ws.pause()
+				output.once("drain", () => ws.resume())
+			}
+		})
+		ws.on("close", () => finish())
+		ws.on("error", (err: Error & { code?: number }) =>
+			finish(
+				err.code === 1000 || err.code === 1001
+					? undefined // normal / going-away closure
+					: new BridgeError(`websocket error: ${err.message}`),
+			),
+		)
+
+		// stdin → WS
+		if (input.isPaused?.()) input.resume()
+		input.on("data", (chunk: Buffer | string) => {
+			if (ws.readyState !== WebSocket.OPEN) return
+			ws.send(chunk, { binary: true })
+		})
+		input.on("end", () => {
+			if (ws.readyState === WebSocket.OPEN) ws.close(1000)
+		})
+		input.on("error", (err) => finish(err))
+	})
+}

package/src/ssh/config.test.ts

@@ -0,0 +1,213 @@
+import { readFileSync, statSync, writeFileSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { cleanupTempDirs, makeTempDir } from "../test-support.js"
+import {
+	isSshIntegrationConfigured,
+	resolveProxyCommandTarget,
+	resolveSshDomain,
+	resolveSshPaths,
+	SSH_INCLUDE_BEGIN,
+	type SshPaths,
+	setupSshIntegration,
+	sshConfigContent,
+	uninstallSshIntegration,
+} from "./config.js"
+
+afterEach(() => {
+	cleanupTempDirs()
+	vi.unstubAllEnvs()
+})
+
+function makePaths(): { root: string; paths: SshPaths } {
+	const root = makeTempDir()
+	return {
+		root,
+		paths: {
+			home: join(root, ".kimchictl"),
+			sshConfig: join(root, ".kimchictl", "ssh_config"),
+			knownHosts: join(root, ".kimchictl", "known_hosts"),
+			userSshConfig: join(root, ".ssh", "config"),
+		},
+	}
+}
+
+const DOMAIN = "remote.kimchi.dev"
+
+describe("setupSshIntegration", () => {
+	it("writes ssh_config (0600) and prepends the Include block", async () => {
+		const { paths } = makePaths()
+
+		const target = resolveProxyCommandTarget()
+		const { notes } = await setupSshIntegration({ paths, domain: DOMAIN })
+
+		const generated = readFileSync(paths.sshConfig, "utf-8")
+		expect(generated).toBe(sshConfigContent(DOMAIN, paths.knownHosts, target))
+		expect(statSync(paths.sshConfig).mode & 0o777).toBe(0o600)
+
+		const userConfig = readFileSync(paths.userSshConfig, "utf-8")
+		expect(userConfig).toBe(`${SSH_INCLUDE_BEGIN}\nInclude ${paths.sshConfig}\n# <<< kimchictl managed include <<<\n`)
+		expect(notes).toEqual([
+			`wrote ${paths.sshConfig} (Host *.${DOMAIN})`,
+			`added Include block to ${paths.userSshConfig}`,
+		])
+	})
+
+	it("keeps the Include above existing user Host blocks (first match wins)", async () => {
+		const { paths } = makePaths()
+		await mkdir(join(paths.userSshConfig, ".."), { recursive: true })
+		writeFileSync(paths.userSshConfig, "Host example\n    HostName example.com\n")
+
+		await setupSshIntegration({ paths, domain: DOMAIN })
+
+		const userConfig = readFileSync(paths.userSshConfig, "utf-8")
+		expect(userConfig.startsWith(SSH_INCLUDE_BEGIN)).toBe(true)
+		expect(userConfig).toContain("Host example\n    HostName example.com\n")
+	})
+
+	it("is idempotent (second run produces no notes, no duplicate block)", async () => {
+		const { paths } = makePaths()
+
+		await setupSshIntegration({ paths, domain: DOMAIN })
+		const { notes } = await setupSshIntegration({ paths, domain: DOMAIN })
+
+		expect(notes).toEqual([])
+		const userConfig = readFileSync(paths.userSshConfig, "utf-8")
+		expect(userConfig.split(SSH_INCLUDE_BEGIN).length - 1).toBe(1)
+	})
+
+	it("replaces a stale managed block pointing at a different path", async () => {
+		const { paths } = makePaths()
+		await setupSshIntegration({ paths, domain: DOMAIN })
+
+		const moved = { ...paths, home: join(paths.home, "moved"), sshConfig: join(paths.home, "moved", "ssh_config") }
+		const { notes } = await setupSshIntegration({ paths: moved, domain: DOMAIN })
+
+		const userConfig = readFileSync(paths.userSshConfig, "utf-8")
+		expect(userConfig).toContain(`Include ${moved.sshConfig}`)
+		expect(userConfig).not.toContain(`Include ${paths.sshConfig}`)
+		expect(notes).toContain(`updated stale Include block in ${paths.userSshConfig}`)
+	})
+
+	it("warns about a conflicting kap-managed block", async () => {
+		const { paths } = makePaths()
+		await mkdir(join(paths.userSshConfig, ".."), { recursive: true })
+		writeFileSync(
+			paths.userSshConfig,
+			"# >>> kap managed include >>>\nInclude /home/x/.config/kap/ssh_config\n# <<< kap managed include <<<\n",
+		)
+
+		const { notes } = await setupSshIntegration({ paths, domain: DOMAIN })
+
+		expect(notes.some((n) => n.includes("kap-managed"))).toBe(true)
+	})
+})
+
+describe("uninstallSshIntegration", () => {
+	it("removes the block and the generated ssh_config, keeping other content", async () => {
+		const { paths } = makePaths()
+		await mkdir(join(paths.userSshConfig, ".."), { recursive: true })
+		writeFileSync(paths.userSshConfig, "Host example\n    HostName example.com\n")
+		await setupSshIntegration({ paths, domain: DOMAIN })
+
+		const { notes } = await uninstallSshIntegration({ paths })
+
+		const userConfig = readFileSync(paths.userSshConfig, "utf-8")
+		expect(userConfig).not.toContain("kimchictl managed include")
+		expect(userConfig).toContain("Host example")
+		expect(notes).toEqual([`removed Include block from ${paths.userSshConfig}`, `removed ${paths.sshConfig}`])
+	})
+
+	it("is a no-op when nothing was configured", async () => {
+		const { paths } = makePaths()
+		const { notes } = await uninstallSshIntegration({ paths })
+		expect(notes).toEqual([])
+	})
+})
+
+describe("isSshIntegrationConfigured", () => {
+	it("false before setup, true after, false again on domain drift", async () => {
+		const { paths } = makePaths()
+
+		expect(await isSshIntegrationConfigured(paths, DOMAIN)).toBe(false)
+		await setupSshIntegration({ paths, domain: DOMAIN })
+		expect(await isSshIntegrationConfigured(paths, DOMAIN)).toBe(true)
+		// Endpoint changed → different wildcard domain → re-setup needed.
+		expect(await isSshIntegrationConfigured(paths, "remote.dev.example.com")).toBe(false)
+	})
+
+	it("re-triggers setup when the ProxyCommand target drifted (binary moved)", async () => {
+		const { paths } = makePaths()
+
+		await setupSshIntegration({ paths, domain: DOMAIN, proxyTarget: "/old/location/kimchictl" })
+
+		expect(await isSshIntegrationConfigured(paths, DOMAIN, "/new/location/kimchictl")).toBe(false)
+		expect(await isSshIntegrationConfigured(paths, DOMAIN, "/old/location/kimchictl")).toBe(true)
+	})
+})
+
+describe("resolveSshDomain", () => {
+	it("defaults to remote.kimchi.dev", () => {
+		vi.stubEnv("KIMCHI_REMOTE_ENDPOINT", "")
+		vi.stubEnv("KIMCHICTL_SSH_DOMAIN", "")
+		expect(resolveSshDomain()).toBe("remote.kimchi.dev")
+	})
+
+	it("derives from an endpoint override (app.X → remote.X)", () => {
+		expect(
+			resolveSshDomain(undefined, { KIMCHI_REMOTE_ENDPOINT: "https://app.dev.kimchi.dev/api" } as NodeJS.ProcessEnv),
+		).toBe("remote.dev.kimchi.dev")
+	})
+
+	it("honors explicit flag and env override before derivation", () => {
+		expect(
+			resolveSshDomain("custom.example", {
+				KIMCHI_REMOTE_ENDPOINT: "https://app.dev.kimchi.dev/api",
+			} as NodeJS.ProcessEnv),
+		).toBe("custom.example")
+		expect(resolveSshDomain(undefined, { KIMCHICTL_SSH_DOMAIN: "env.example" } as NodeJS.ProcessEnv)).toBe(
+			"env.example",
+		)
+	})
+})
+
+describe("resolveProxyCommandTarget", () => {
+	it("uses the compiled binary's own path when named like kimchictl", () => {
+		expect(resolveProxyCommandTarget("/usr/local/bin/kimchictl")).toBe("/usr/local/bin/kimchictl")
+		expect(resolveProxyCommandTarget("/opt/kimchictl-v1.2.3")).toBe("/opt/kimchictl-v1.2.3")
+	})
+
+	it("pins the runtime + absolute entry script under node/bun (no PATH reliance)", () => {
+		expect(resolveProxyCommandTarget("/usr/local/bin/node", "/opt/app/dist/cli.js")).toBe(
+			"/usr/local/bin/node /opt/app/dist/cli.js",
+		)
+		// Relative entries resolve to absolute so the config works from any cwd.
+		expect(resolveProxyCommandTarget("/usr/bin/bun", "src/cli.ts")).toBe(
+			`/usr/bin/bun ${join(process.cwd(), "src/cli.ts")}`,
+		)
+	})
+
+	it("quotes tokens containing spaces", () => {
+		expect(resolveProxyCommandTarget("/opt/My App/kimchictl")).toBe('"/opt/My App/kimchictl"')
+		expect(resolveProxyCommandTarget("/usr/bin/node", "/opt/My App/cli.js")).toBe('/usr/bin/node "/opt/My App/cli.js"')
+	})
+})
+
+describe("resolveSshPaths", () => {
+	it("defaults to ~/.config/kimchi/kimchictl, alongside the harness config tree", () => {
+		const paths = resolveSshPaths({ HOME: "/home/tester" })
+
+		expect(paths.home).toBe("/home/tester/.config/kimchi/kimchictl")
+		expect(paths.sshConfig).toBe("/home/tester/.config/kimchi/kimchictl/ssh_config")
+		expect(paths.knownHosts).toBe("/home/tester/.config/kimchi/kimchictl/known_hosts")
+		expect(paths.userSshConfig).toBe("/home/tester/.ssh/config")
+	})
+
+	it("honors KIMCHICTL_HOME as an explicit override", () => {
+		const paths = resolveSshPaths({ HOME: "/home/tester", KIMCHICTL_HOME: "/custom/state" })
+
+		expect(paths.home).toBe("/custom/state")
+		expect(paths.sshConfig).toBe("/custom/state/ssh_config")
+	})
+})

package/src/ssh/config.ts

@@ -0,0 +1,233 @@
+import { existsSync } from "node:fs"
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+
+/**
+ * Native SSH integration (TS port of kap:internal/ssh/setup.go).
+ *
+ * Layout:
+ *   ~/.config/kimchi/kimchictl/ssh_config   — `Host *.<domain>` wildcard routing
+ *                                             through `kimchictl ssh proxy %h` as ProxyCommand
+ *   ~/.config/kimchi/kimchictl/known_hosts  — dedicated known_hosts for workspace hosts
+ *   ~/.ssh/config                           — gets a marker-wrapped `Include` block
+ *
+ * Behavior per the product decision "setup happens on install": writes are
+ * automatic (no y/N prompt) with a clear notice; `--uninstall` reverts.
+ */
+
+export const SSH_INCLUDE_BEGIN = "# >>> kimchictl managed include >>>"
+export const SSH_INCLUDE_END = "# <<< kimchictl managed include <<<"
+
+export interface SshPaths {
+	/** ~/.config/kimchi/kimchictl root (also used for the update-check cache). */
+	home: string
+	sshConfig: string
+	knownHosts: string
+	userSshConfig: string
+}
+
+export function resolveSshPaths(env: NodeJS.ProcessEnv = process.env): SshPaths {
+	// Lives with the rest of the kimchi config tree (harness/, desktop/, memory/…).
+	const home = env.KIMCHICTL_HOME ?? join(env.HOME ?? homedir(), ".config", "kimchi", "kimchictl")
+	const userSshConfig = join(env.HOME ?? homedir(), ".ssh", "config")
+	return {
+		home,
+		sshConfig: join(home, "ssh_config"),
+		knownHosts: join(home, "known_hosts"),
+		userSshConfig,
+	}
+}
+
+/**
+ * The wildcard domain workspaces are reached at. Default remote.kimchi.dev;
+ * derived from the API endpoint host for dev environments
+ * (app.X → remote.X), overridable via flag/env for exotic setups.
+ */
+export function resolveSshDomain(explicit?: string, env: NodeJS.ProcessEnv = process.env): string {
+	if (explicit) return explicit
+	if (env.KIMCHICTL_SSH_DOMAIN) return env.KIMCHICTL_SSH_DOMAIN
+	const endpoint = env.KIMCHI_REMOTE_ENDPOINT
+	if (endpoint) {
+		try {
+			const host = new URL(endpoint).hostname
+			const stripped = host.startsWith("app.") ? host.slice("app.".length) : host
+			return `remote.${stripped}`
+		} catch {
+			// Fall through to the production default below.
+		}
+	}
+	return "remote.kimchi.dev"
+}
+
+/** Shell-quote a single ProxyCommand token when it contains whitespace. */
+function shellQuote(token: string): string {
+	return /\s|"|'/.test(token) ? `"${token.replace(/"/g, '\\"')}"` : token
+}
+
+/**
+ * The ProxyCommand must not rely on ssh's PATH lookup — point it at a
+ * fully-qualified command:
+ *   - compiled binary: its own absolute path
+ *   - node/bun runtime: the runtime plus the ABSOLUTE entry script
+ *     (e.g. `/usr/bin/node /…/dist/cli.js`), so the config works from any cwd
+ * Bare `kimchictl` remains only as a last resort when no entry can be named.
+ */
+export function resolveProxyCommandTarget(execPath: string = process.execPath, entryScript?: string): string {
+	const base = execPath.split("/").pop() ?? ""
+	if (base === "kimchictl" || base.startsWith("kimchictl-")) {
+		return shellQuote(execPath)
+	}
+	const entry = entryScript ?? process.argv[1]
+	if (entry) {
+		return `${shellQuote(execPath)} ${shellQuote(resolve(entry))}`
+	}
+	return "kimchictl"
+}
+
+export function sshConfigContent(domain: string, knownHostsPath: string, proxyTarget: string): string {
+	return (
+		`Host *.${domain}\n` +
+		`    ProxyCommand ${proxyTarget} ssh proxy %h\n` +
+		`    UserKnownHostsFile ${knownHostsPath}\n` +
+		`    StrictHostKeyChecking accept-new\n` +
+		`    User developer\n`
+	)
+}
+
+export interface SetupResult {
+	notes: string[]
+}
+
+async function writePrivateFile(path: string, content: string): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+	await writeFile(path, content, { mode: 0o600 })
+	await chmod(path, 0o600)
+}
+
+function managedBlock(includePath: string): string {
+	return `${SSH_INCLUDE_BEGIN}\nInclude ${includePath}\n${SSH_INCLUDE_END}`
+}
+
+/** Extract an existing managed include block (any path), or undefined. */
+function extractManagedBlock(content: string): string | undefined {
+	const start = content.indexOf(SSH_INCLUDE_BEGIN)
+	if (start === -1) return undefined
+	const endRel = content.slice(start).indexOf(SSH_INCLUDE_END)
+	if (endRel === -1) return undefined
+	return content.slice(start, start + endRel + SSH_INCLUDE_END.length + 1)
+}
+
+/**
+ * Write the kimchictl ssh_config and ensure ~/.ssh/config includes it.
+ * Idempotent; a stale managed block (different include path) is replaced in
+ * place. Returns human-readable notes of everything that changed.
+ */
+export async function setupSshIntegration(options: {
+	paths: SshPaths
+	domain: string
+	proxyTarget?: string
+	/** Detect and warn about a kap-managed block (same wildcard domain conflict). */
+	warnKapConflict?: (note: string) => void
+}): Promise<SetupResult> {
+	const { paths, domain } = options
+	const notes: string[] = []
+
+	const content = sshConfigContent(domain, paths.knownHosts, options.proxyTarget ?? resolveProxyCommandTarget())
+	const previous = existsSync(paths.sshConfig) ? await readFile(paths.sshConfig, "utf-8") : undefined
+	if (previous !== content) {
+		await writePrivateFile(paths.sshConfig, content)
+		notes.push(`wrote ${paths.sshConfig} (Host *.${domain})`)
+	}
+
+	let userConfig = ""
+	try {
+		userConfig = await readFile(paths.userSshConfig, "utf-8")
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+	}
+
+	if (userConfig.includes("# >>> kap managed include >>>")) {
+		notes.push(
+			"⚠ found a kap-managed Include block in ~/.ssh/config — both wildcard configs match " +
+				"this domain; the first Include wins. Remove one if connections route to the wrong proxy.",
+		)
+	}
+
+	const block = managedBlock(paths.sshConfig)
+	const existing = extractManagedBlock(userConfig)
+	if (existing === undefined) {
+		// First match in ssh config wins for most options: the Include must come first.
+		const next = userConfig.length > 0 ? `${block}\n\n${userConfig}` : `${block}\n`
+		await writePrivateFile(paths.userSshConfig, next)
+		notes.push(`added Include block to ${paths.userSshConfig}`)
+	} else if (existing !== block && existing !== `${block}\n`) {
+		// Stale block (e.g. config dir moved) — replace in place.
+		const next = userConfig.replace(existing, `${block}\n`)
+		await writePrivateFile(paths.userSshConfig, next)
+		notes.push(`updated stale Include block in ${paths.userSshConfig}`)
+	}
+
+	return { notes }
+}
+
+/** Remove the Include block and the generated ssh_config. Returns notes. */
+export async function uninstallSshIntegration(options: { paths: SshPaths }): Promise<SetupResult> {
+	const { paths } = options
+	const notes: string[] = []
+
+	let userConfig = ""
+	try {
+		userConfig = await readFile(paths.userSshConfig, "utf-8")
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+	}
+
+	const existing = extractManagedBlock(userConfig)
+	if (existing !== undefined) {
+		let next = userConfig.replace(existing, "")
+		// Tidy the blank line we added after the block when nothing precedes it.
+		next = next.replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n")
+		await writePrivateFile(paths.userSshConfig, next)
+		notes.push(`removed Include block from ${paths.userSshConfig}`)
+	}
+
+	if (existsSync(paths.sshConfig)) {
+		// Remove rather than truncate: keep the dir (it also holds known_hosts/cache).
+		await rm(paths.sshConfig, { force: true })
+		notes.push(`removed ${paths.sshConfig}`)
+	}
+
+	return { notes }
+}
+
+/**
+ * True when the generated ssh_config exists AND the user config includes it.
+ * Used by `ssh <name>` / `login` to auto-setup when missing.
+ */
+export async function isSshIntegrationConfigured(
+	paths: SshPaths,
+	domain: string,
+	proxyTarget?: string,
+): Promise<boolean> {
+	if (!existsSync(paths.sshConfig)) return false
+	try {
+		const userConfig = await readFile(paths.userSshConfig, "utf-8")
+		const expected = managedBlock(paths.sshConfig)
+		const existing = extractManagedBlock(userConfig)
+		if (existing !== expected && existing !== `${expected}\n`) return false
+		const generated = await readFile(paths.sshConfig, "utf-8")
+		// Both domain drift (endpoint override changed) and proxy-target drift
+		// (the executable moved since setup) must re-trigger setup: compare the
+		// full expected content.
+		return generated === sshConfigContent(domain, paths.knownHosts, proxyTarget ?? resolveProxyCommandTarget())
+	} catch {
+		return false
+	}
+}
+
+/** Disabled-marker env var honored by every auto-setup caller. */
+export function isSshSetupDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const value = env.KIMCHICTL_NO_SSH_SETUP
+	return value !== undefined && value !== "" && value !== "0" && value !== "false"
+}