expandai 0.0.2 → 0.0.3

package/src/Install/Claude/Mcp.ts

@@ -1,15 +1,17 @@
 import { homedir } from 'node:os'
 import { Config, Console, Effect, Match, Record, Schema } from 'effect'
-import { ConfigIo, McpParseError, McpServersConfigSchema, McpWriteError, SERVER_KEY } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
-
-/**
- * Claude Code MCP descriptor — `mcpServers` shape (de facto Claude Desktop
- * convention; also read by Cursor and other clients).
- *
- *   - global  → `~/.claude.json`        (Claude Code's user-scope store)
- *   - project → `<cwd>/.mcp.json`       (the agent-agnostic project file)
- */
+import {
+	type CliCommand,
+	ConfigIo,
+	DIRECT_CLI,
+	McpParseError,
+	McpServersConfigSchema,
+	McpWriteError,
+	SERVER_KEY,
+} from '../Domain.js'
+import type { InstallScope } from '../Mcp.js'
+
+/** Claude Code MCP descriptor stored under the Expand-owned server key. */
 export class Entry extends Schema.Class<Entry>('ClaudeMcpEntry')({
 	type: Schema.Literal('stdio'),
 	command: Schema.NonEmptyTrimmedString,
@@ -17,6 +19,64 @@ export class Entry extends Schema.Class<Entry>('ClaudeMcpEntry')({
 	env: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
 }) {}
 
+export interface ClaudeMcpPlan {
+	readonly changed: boolean
+	readonly config: typeof McpServersConfigSchema.Type
+}
+
+const MCP_ARGS = ['mcp', 'run'] as const
+
+/** Claude execs the descriptor directly, so `command`/`args` stay separate. */
+export function claudeMcpEntry(cli: CliCommand = DIRECT_CLI): Entry {
+	return new Entry({
+		type: 'stdio',
+		command: cli.command,
+		args: [...cli.args, ...MCP_ARGS],
+		env: { EXPANDAI_HARNESS: 'claude-code' },
+	})
+}
+
+export const CLAUDE_MCP_ENTRY = claudeMcpEntry()
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isCurrentEntry(value: unknown, expected: Entry): boolean {
+	if (!isUnknownRecord(value)) return false
+	const args = value.args
+	const env = value.env
+	return (
+		value.type === expected.type &&
+		value.command === expected.command &&
+		Array.isArray(args) &&
+		args.length === expected.args.length &&
+		args.every((arg, index) => arg === expected.args[index]) &&
+		isUnknownRecord(env) &&
+		env.EXPANDAI_HARNESS === 'claude-code'
+	)
+}
+
+export function planClaudeMcp(config: typeof McpServersConfigSchema.Type, cli: CliCommand = DIRECT_CLI): ClaudeMcpPlan {
+	const entry = claudeMcpEntry(cli)
+	if (isCurrentEntry(config.mcpServers[SERVER_KEY], entry)) return { changed: false, config }
+	return {
+		changed: true,
+		config: {
+			...config,
+			mcpServers: { ...config.mcpServers, [SERVER_KEY]: entry },
+		},
+	}
+}
+
+export function planClaudeMcpRemoval(config: typeof McpServersConfigSchema.Type): ClaudeMcpPlan {
+	if (!(SERVER_KEY in config.mcpServers)) return { changed: false, config }
+	return {
+		changed: true,
+		config: { ...config, mcpServers: Record.remove(config.mcpServers, SERVER_KEY) },
+	}
+}
+
 export class ClaudeMcp extends Effect.Service<ClaudeMcp>()('@expandai/cli/Install/Claude/Mcp', {
 	dependencies: [ConfigIo.Default],
 	effect: Effect.gen(function* () {
@@ -24,7 +84,7 @@ export class ClaudeMcp extends Effect.Service<ClaudeMcp>()('@expandai/cli/Instal
 		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
 		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
 
-		const pathFor = Effect.fn(function* (scope: Scope) {
+		const pathFor = Effect.fn(function* (scope: InstallScope) {
 			return yield* Match.value(scope).pipe(
 				Match.when('global', () => Effect.succeed(`${home}/.claude.json`)),
 				Match.when('project', () => Effect.succeed(`${cwd}/.mcp.json`)),
@@ -44,37 +104,24 @@ export class ClaudeMcp extends Effect.Service<ClaudeMcp>()('@expandai/cli/Instal
 				.pipe(Effect.mapError((error) => new McpWriteError({ path: file, error })))
 		})
 
-		const install = Effect.fn(function* (scope: Scope) {
+		const install = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
-			const config = yield* readConfig(file)
-			yield* writeConfig(file, {
-				...config,
-				mcpServers: {
-					...config.mcpServers,
-					[SERVER_KEY]: new Entry({
-						type: 'stdio',
-						command: 'expandai',
-						args: ['mcp', 'run'],
-					}),
-				},
-			})
+			const plan = planClaudeMcp(yield* readConfig(file))
+			if (plan.changed) yield* writeConfig(file, plan.config)
 			yield* Console.log(`Installed expandai MCP server into ${file}`)
 		})
 
-		const uninstall = Effect.fn(function* (scope: Scope) {
+		const uninstall = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
-			const config = yield* readConfig(file)
-			if (!(SERVER_KEY in config.mcpServers)) {
-				return
-			}
-			yield* writeConfig(file, { ...config, mcpServers: Record.remove(config.mcpServers, SERVER_KEY) })
+			const plan = planClaudeMcpRemoval(yield* readConfig(file))
+			if (!plan.changed) return
+			yield* writeConfig(file, plan.config)
 			yield* Console.log(`Removed expandai MCP server from ${file}`)
 		})
 
-		const isInstalled = Effect.fn(function* (scope: Scope) {
+		const isInstalled = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
-			const config = yield* readConfig(file)
-			return SERVER_KEY in config.mcpServers
+			return SERVER_KEY in (yield* readConfig(file)).mcpServers
 		})
 
 		return { install, uninstall, isInstalled, pathFor } as const

package/src/Install/Claude/Skill.ts

@@ -1,44 +1,77 @@
 import { homedir } from 'node:os'
+import { FileSystem, Path } from '@effect/platform'
+import { NodeFileSystem, NodePath } from '@effect/platform-node'
 import { Config, Effect, Match } from 'effect'
-import { SkillIo } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
-
-/**
- * Claude Code skills live under `<scope>/.claude/skills/<name>/SKILL.md`.
- *
- *   - global  → `~/.claude/skills/expandai/SKILL.md`
- *   - project → `<cwd>/.claude/skills/expandai/SKILL.md`
- *
- * (Globally-scoped Claude Code skills are also reachable via `npx skills`,
- * but file-copy gives us a uniform install path with OpenCode and works
- * without npm.)
- */
+import { CLI_VERSION } from '../../Version.js'
+import type { InstallScope } from '../Mcp.js'
 
 export const SKILL_NAME = 'expandai'
+export const SKILL_FILE_NAME = 'SKILL.md'
+const PROFILE_VERSION_LINE = /^(\s*expandai-profile-version:\s*).+$/mu
+
+export interface ClaudeSkillPlan {
+	readonly changed: boolean
+	readonly text: string
+}
+
+export function renderClaudeSkill(source: string, profileVersion: string = CLI_VERSION): string {
+	if (!PROFILE_VERSION_LINE.test(source)) {
+		throw new Error('Bundled Expand skill is missing expandai-profile-version metadata')
+	}
+	return source.replace(PROFILE_VERSION_LINE, `$1${profileVersion}`)
+}
+
+export function planClaudeSkill(
+	current: string | undefined,
+	source: string,
+	profileVersion: string = CLI_VERSION,
+): ClaudeSkillPlan {
+	const text = renderClaudeSkill(source, profileVersion)
+	return { changed: current !== text, text }
+}
+
+const makeClaudeSkill = Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
+	const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
+	const moduleFile = yield* path.fromFileUrl(new URL(import.meta.url))
+	const sourceFile = path.resolve(path.dirname(moduleFile), '..', '..', '..', 'skills', SKILL_NAME, SKILL_FILE_NAME)
+
+	const pathFor = Effect.fn(function* (scope: InstallScope) {
+		return yield* Match.value(scope).pipe(
+			Match.when('global', () => Effect.succeed(path.join(home, '.claude', 'skills', SKILL_NAME))),
+			Match.when('project', () => Effect.succeed(path.join(cwd, '.claude', 'skills', SKILL_NAME))),
+			Match.exhaustive,
+		)
+	})
+
+	const source = Effect.fn('ClaudeSkill.source')(function* () {
+		return yield* fileSystem.readFileString(sourceFile)
+	})
+
+	const install = Effect.fn('ClaudeSkill.install')(function* (scope: InstallScope) {
+		const target = yield* pathFor(scope)
+		const targetFile = path.join(target, SKILL_FILE_NAME)
+		const current = (yield* fileSystem.exists(targetFile)) ? yield* fileSystem.readFileString(targetFile) : undefined
+		const plan = planClaudeSkill(current, yield* source())
+		if (plan.changed) {
+			yield* fileSystem.makeDirectory(target, { recursive: true })
+			yield* fileSystem.writeFileString(targetFile, plan.text)
+		}
+		return target
+	})
+
+	const uninstall = Effect.fn('ClaudeSkill.uninstall')(function* (scope: InstallScope) {
+		const target = yield* pathFor(scope)
+		if (yield* fileSystem.exists(target)) yield* fileSystem.remove(target, { recursive: true })
+		return target
+	})
+
+	return { install, uninstall, pathFor, source } as const
+})
 
 export class ClaudeSkill extends Effect.Service<ClaudeSkill>()('@expandai/cli/Install/Claude/Skill', {
-	dependencies: [SkillIo.Default],
-	effect: Effect.gen(function* () {
-		const io = yield* SkillIo
-		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
-		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
-
-		const pathFor = Effect.fn(function* (scope: Scope) {
-			return yield* Match.value(scope).pipe(
-				Match.when('global', () => Effect.succeed(`${home}/.claude/skills/${SKILL_NAME}`)),
-				Match.when('project', () => Effect.succeed(`${cwd}/.claude/skills/${SKILL_NAME}`)),
-				Match.exhaustive,
-			)
-		})
-
-		const install = Effect.fn(function* (scope: Scope) {
-			return yield* io.install(yield* pathFor(scope))
-		})
-
-		const uninstall = Effect.fn(function* (scope: Scope) {
-			return yield* io.uninstall(yield* pathFor(scope))
-		})
-
-		return { install, uninstall } as const
-	}),
+	dependencies: [NodeFileSystem.layer, NodePath.layer],
+	effect: makeClaudeSkill,
 }) {}

package/src/Install/Codex/Mcp.ts

@@ -1,12 +1,13 @@
 import { homedir } from 'node:os'
 import { Config, Console, Effect, Match, Record, Schema } from 'effect'
 import { parse, stringify, type TomlTableWithoutBigInt } from 'smol-toml'
-import { ConfigIo, McpParseError, McpWriteError, SERVER_KEY } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
+import { CliInvocation, ConfigIo, McpParseError, McpWriteError, SERVER_KEY } from '../Domain.js'
+import type { InstallScope } from '../Mcp.js'
 
 export class Entry extends Schema.Class<Entry>('CodexMcpEntry')({
 	command: Schema.NonEmptyTrimmedString,
 	args: Schema.Array(Schema.String),
+	env: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
 	enabled: Schema.Boolean,
 }) {}
 
@@ -32,13 +33,14 @@ function toStringifyValue(value: TomlTableWithoutBigInt) {
  *   - project → `<cwd>/.codex/config.toml`
  */
 export class CodexMcp extends Effect.Service<CodexMcp>()('@expandai/cli/Install/Codex/Mcp', {
-	dependencies: [ConfigIo.Default],
+	dependencies: [ConfigIo.Default, CliInvocation.Default],
 	effect: Effect.gen(function* () {
 		const io = yield* ConfigIo
+		const cli = yield* CliInvocation
 		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
 		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
 
-		const pathFor = Effect.fn(function* (scope: Scope) {
+		const pathFor = Effect.fn(function* (scope: InstallScope) {
 			return yield* Match.value(scope).pipe(
 				Match.when('global', () => Effect.succeed(`${home}/.codex/config.toml`)),
 				Match.when('project', () => Effect.succeed(`${cwd}/.codex/config.toml`)),
@@ -62,20 +64,23 @@ export class CodexMcp extends Effect.Service<CodexMcp>()('@expandai/cli/Install/
 			yield* io.writeText(file, encoded).pipe(Effect.mapError((error) => new McpWriteError({ path: file, error })))
 		})
 
-		const install = Effect.fn(function* (scope: Scope) {
+		const install = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
 			const servers = yield* getMcpServers(config)
 
+			const invocation = yield* cli.resolve()
 			const entryModel = new Entry({
-				command: 'expandai',
-				args: ['mcp', 'run'],
+				command: invocation.command,
+				args: [...invocation.args, 'mcp', 'run'],
+				env: { EXPANDAI_HARNESS: 'codex' },
 				enabled: true,
 			})
 
 			const entry: TomlTableWithoutBigInt = {
 				command: entryModel.command,
 				args: [...entryModel.args],
+				env: { ...entryModel.env },
 				enabled: entryModel.enabled,
 			}
 
@@ -86,7 +91,7 @@ export class CodexMcp extends Effect.Service<CodexMcp>()('@expandai/cli/Install/
 			yield* Console.log(`Installed expandai MCP server into ${file}`)
 		})
 
-		const uninstall = Effect.fn(function* (scope: Scope) {
+		const uninstall = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
 			const servers = yield* getMcpServers(config)
@@ -97,7 +102,7 @@ export class CodexMcp extends Effect.Service<CodexMcp>()('@expandai/cli/Install/
 			yield* Console.log(`Removed expandai MCP server from ${file}`)
 		})
 
-		const isInstalled = Effect.fn(function* (scope: Scope) {
+		const isInstalled = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
 			const servers = yield* getMcpServers(config)

package/src/Install/Codex/Skill.ts

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os'
 import { Config, Effect, Match } from 'effect'
 import { SkillIo } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
+import type { InstallScope } from '../Mcp.js'
 
 /**
  * Codex skills use the open agent skills locations:
@@ -19,7 +19,7 @@ export class CodexSkill extends Effect.Service<CodexSkill>()('@expandai/cli/Inst
 		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
 		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
 
-		const pathFor = Effect.fn(function* (scope: Scope) {
+		const pathFor = Effect.fn(function* (scope: InstallScope) {
 			return yield* Match.value(scope).pipe(
 				Match.when('global', () => Effect.succeed(`${home}/.agents/skills/${SKILL_NAME}`)),
 				Match.when('project', () => Effect.succeed(`${cwd}/.agents/skills/${SKILL_NAME}`)),
@@ -27,14 +27,18 @@ export class CodexSkill extends Effect.Service<CodexSkill>()('@expandai/cli/Inst
 			)
 		})
 
-		const install = Effect.fn(function* (scope: Scope) {
+		const install = Effect.fn(function* (scope: InstallScope) {
 			return yield* io.install(yield* pathFor(scope))
 		})
 
-		const uninstall = Effect.fn(function* (scope: Scope) {
+		const uninstall = Effect.fn(function* (scope: InstallScope) {
 			return yield* io.uninstall(yield* pathFor(scope))
 		})
 
-		return { install, uninstall } as const
+		const isCurrent = Effect.fn(function* (scope: InstallScope) {
+			return yield* io.isCurrent(yield* pathFor(scope))
+		})
+
+		return { install, uninstall, isCurrent, pathFor } as const
 	}),
 }) {}

package/src/Install/Cursor/Mcp.ts

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os'
 import { Config, Console, Effect, Match, Record, Schema } from 'effect'
-import { ConfigIo, McpParseError, McpServersConfigSchema, McpWriteError, SERVER_KEY } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
+import { CliInvocation, ConfigIo, McpParseError, McpServersConfigSchema, McpWriteError, SERVER_KEY } from '../Domain.js'
+import type { InstallScope } from '../Mcp.js'
 
 /**
  * Cursor MCP descriptor — same `mcpServers` shape as Claude Code, different
@@ -18,13 +18,14 @@ export class Entry extends Schema.Class<Entry>('CursorMcpEntry')({
 }) {}
 
 export class CursorMcp extends Effect.Service<CursorMcp>()('@expandai/cli/Install/Cursor/Mcp', {
-	dependencies: [ConfigIo.Default],
+	dependencies: [ConfigIo.Default, CliInvocation.Default],
 	effect: Effect.gen(function* () {
 		const io = yield* ConfigIo
+		const cli = yield* CliInvocation
 		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
 		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
 
-		const pathFor = Effect.fn(function* (scope: Scope) {
+		const pathFor = Effect.fn(function* (scope: InstallScope) {
 			return yield* Match.value(scope).pipe(
 				Match.when('global', () => Effect.succeed(`${home}/.cursor/mcp.json`)),
 				Match.when('project', () => Effect.succeed(`${cwd}/.cursor/mcp.json`)),
@@ -44,24 +45,26 @@ export class CursorMcp extends Effect.Service<CursorMcp>()('@expandai/cli/Instal
 				.pipe(Effect.mapError((error) => new McpWriteError({ path: file, error })))
 		})
 
-		const install = Effect.fn(function* (scope: Scope) {
+		const install = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
+			const invocation = yield* cli.resolve()
 			yield* writeConfig(file, {
 				...config,
 				mcpServers: {
 					...config.mcpServers,
 					[SERVER_KEY]: new Entry({
 						type: 'stdio',
-						command: 'expandai',
-						args: ['mcp', 'run'],
+						command: invocation.command,
+						args: [...invocation.args, 'mcp', 'run'],
+						env: { EXPANDAI_HARNESS: 'cursor' },
 					}),
 				},
 			})
 			yield* Console.log(`Installed expandai MCP server into ${file}`)
 		})
 
-		const uninstall = Effect.fn(function* (scope: Scope) {
+		const uninstall = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
 			if (!(SERVER_KEY in config.mcpServers)) {
@@ -71,7 +74,7 @@ export class CursorMcp extends Effect.Service<CursorMcp>()('@expandai/cli/Instal
 			yield* Console.log(`Removed expandai MCP server from ${file}`)
 		})
 
-		const isInstalled = Effect.fn(function* (scope: Scope) {
+		const isInstalled = Effect.fn(function* (scope: InstallScope) {
 			const file = yield* pathFor(scope)
 			const config = yield* readConfig(file)
 			return SERVER_KEY in config.mcpServers

package/src/Install/Cursor/Skill.ts

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os'
 import { Config, Effect, Match } from 'effect'
 import { SkillIo } from '../Domain.js'
-import type { Scope } from '../Mcp.js'
+import type { InstallScope } from '../Mcp.js'
 
 /**
  * Cursor skills are auto-loaded from these locations (per
@@ -26,7 +26,7 @@ export class CursorSkill extends Effect.Service<CursorSkill>()('@expandai/cli/In
 		const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
 		const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
 
-		const pathFor = Effect.fn(function* (scope: Scope) {
+		const pathFor = Effect.fn(function* (scope: InstallScope) {
 			return yield* Match.value(scope).pipe(
 				Match.when('global', () => Effect.succeed(`${home}/.cursor/skills/${SKILL_NAME}`)),
 				Match.when('project', () => Effect.succeed(`${cwd}/.cursor/skills/${SKILL_NAME}`)),
@@ -34,14 +34,18 @@ export class CursorSkill extends Effect.Service<CursorSkill>()('@expandai/cli/In
 			)
 		})
 
-		const install = Effect.fn(function* (scope: Scope) {
+		const install = Effect.fn(function* (scope: InstallScope) {
 			return yield* io.install(yield* pathFor(scope))
 		})
 
-		const uninstall = Effect.fn(function* (scope: Scope) {
+		const uninstall = Effect.fn(function* (scope: InstallScope) {
 			return yield* io.uninstall(yield* pathFor(scope))
 		})
 
-		return { install, uninstall } as const
+		const isCurrent = Effect.fn(function* (scope: InstallScope) {
+			return yield* io.isCurrent(yield* pathFor(scope))
+		})
+
+		return { install, uninstall, isCurrent, pathFor } as const
 	}),
 }) {}

package/src/Install/Domain.ts

@@ -1,6 +1,6 @@
 import { FileSystem, Path } from '@effect/platform'
 import { NodeFileSystem, NodePath } from '@effect/platform-node'
-import { Effect, Inspectable, Schema } from 'effect'
+import { Array, Config, Effect, Inspectable, Layer, Schema, String } from 'effect'
 
 export class McpParseError extends Schema.TaggedError<McpParseError>()('McpParseError', {
 	path: Schema.String,
@@ -23,8 +23,16 @@ export class McpWriteError extends Schema.TaggedError<McpWriteError>()('McpWrite
 export const Host = Schema.Literal('claude-code', 'cursor', 'opencode', 'codex')
 export type Host = typeof Host.Type
 
-export const Scope = Schema.Literal('project', 'global')
-export type Scope = typeof Scope.Type
+/**
+ * The agent harness invoking the CLI — every install target plus 'unknown'
+ * for uninstrumented callers. Installers bake `EXPANDAI_HARNESS=<host>` into
+ * MCP/hook configs; telemetry reads it back.
+ */
+export const Harness = Schema.Literal(...Host.literals, 'unknown')
+export type Harness = typeof Harness.Type
+
+export const InstallScope = Schema.Literal('project', 'global')
+export type InstallScope = typeof InstallScope.Type
 
 const McpServerMap = Schema.Record({ key: Schema.String, value: Schema.Unknown })
 
@@ -40,6 +48,56 @@ export const OpencodeConfigSchema = Schema.parseJson(
 
 export const SERVER_KEY = 'expandai'
 
+/** How a host config should launch the CLI: `command` plus leading args. */
+export interface CliCommand {
+	readonly command: string
+	readonly args: ReadonlyArray<string>
+}
+
+export const DIRECT_CLI: CliCommand = { command: 'expandai', args: [] }
+const NPX_CLI: CliCommand = { command: 'npx', args: ['-y', 'expandai'] }
+
+/**
+ * Renders a `CliCommand` as the single shell string Claude Code stores for hook
+ * entries. MCP descriptors keep `command`/`args` separate because they exec
+ * directly; hooks are run through a shell, so they need one flat line.
+ */
+export function cliShellCommand(cli: CliCommand, args: ReadonlyArray<string>): string {
+	return [cli.command, ...cli.args, ...args].join(' ')
+}
+
+/**
+ * Resolves how installed host configs should invoke the expandai CLI. MCP
+ * entries exec their `command` directly (no shell), so the fallback decision
+ * happens at install time: prefer the `expandai` binary when it is on PATH,
+ * otherwise write an `npx -y expandai` invocation so installs performed via
+ * `npx expandai …` keep working without a global CLI install.
+ */
+const makeCliInvocation = Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const searchPath = yield* Config.string('PATH').pipe(Config.withDefault(''))
+
+	const resolve = Effect.fn('CliInvocation.resolve')(function* () {
+		// ':' is the POSIX PATH delimiter — the install flow already assumes
+		// POSIX conventions (HOME-based config paths, shell hooks).
+		const onPath = yield* Effect.exists(Array.filter(searchPath.split(':'), String.isNonEmpty), (dir) =>
+			fs.exists(path.join(dir, 'expandai')).pipe(Effect.orElseSucceed(() => false)),
+		)
+		return onPath ? DIRECT_CLI : NPX_CLI
+	})
+
+	return { resolve } as const
+})
+
+export class CliInvocation extends Effect.Service<CliInvocation>()('@expandai/cli/Install/CliInvocation', {
+	dependencies: [NodeFileSystem.layer, NodePath.layer],
+	effect: makeCliInvocation,
+}) {
+	/** Dependency-open layer so fixtures can supply their own file system and PATH. */
+	static readonly layer = Layer.effect(CliInvocation, makeCliInvocation.pipe(Effect.map(CliInvocation.make)))
+}
+
 export const readConfigText = Effect.fn(function* (file: string) {
 	const fs = yield* FileSystem.FileSystem
 	const exists = yield* fs.exists(file)
@@ -143,6 +201,21 @@ export class SkillIo extends Effect.Service<SkillIo>()('@expandai/cli/Install/Sk
 			return target
 		})
 
-		return { install, uninstall } as const
+		/**
+		 * Whether the installed skill matches the bundled one. Presence alone is not
+		 * enough: an upgraded CLI ships new skill text, and a harness whose install is
+		 * gated on "the file exists" would keep serving the old instructions forever.
+		 */
+		const isCurrent = Effect.fn('SkillIo.isCurrent')(function* (target: string) {
+			const targetFile = path.join(target, 'SKILL.md')
+			if (!(yield* fs.exists(targetFile))) return false
+			const [installed, bundled] = yield* Effect.all([
+				fs.readFileString(targetFile),
+				fs.readFileString(path.join(sourceDir, 'SKILL.md')),
+			])
+			return installed === bundled
+		})
+
+		return { install, uninstall, isCurrent } as const
 	}),
 }) {}

package/src/Install/Hook.ts

@@ -1,6 +1,6 @@
 import { Effect, Match, Schema } from 'effect'
 import { ClaudeHook } from './Claude/Hook.js'
-import { Mcp, type Scope } from './Mcp.js'
+import { type InstallScope, Mcp } from './Mcp.js'
 import { OpencodeHook } from './Opencode/Hook.js'
 
 /**
@@ -26,7 +26,7 @@ export class HookInstaller extends Effect.Service<HookInstaller>()('@expandai/cl
 		const claudeHook = yield* ClaudeHook
 		const opencodeHook = yield* OpencodeHook
 
-		const install = Effect.fn('HookInstaller.install')(function* (host: HookHost, scope: Scope) {
+		const install = Effect.fn('HookInstaller.install')(function* (host: HookHost, scope: InstallScope) {
 			// Bundle: MCP install first, then host-specific hook config.
 			yield* mcp.install(host, scope)
 			yield* Match.value(host).pipe(
@@ -36,7 +36,7 @@ export class HookInstaller extends Effect.Service<HookInstaller>()('@expandai/cl
 			)
 		})
 
-		const uninstall = Effect.fn('HookInstaller.uninstall')(function* (host: HookHost, scope: Scope) {
+		const uninstall = Effect.fn('HookInstaller.uninstall')(function* (host: HookHost, scope: InstallScope) {
 			yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claudeHook.uninstall(scope)),
 				Match.when('opencode', () => opencodeHook.uninstall(scope)),

package/src/Install/Mcp.ts

@@ -2,10 +2,10 @@ import { Effect, Match } from 'effect'
 import { ClaudeMcp } from './Claude/Mcp.js'
 import { CodexMcp } from './Codex/Mcp.js'
 import { CursorMcp } from './Cursor/Mcp.js'
-import type { Host, Scope } from './Domain.js'
+import type { Host, InstallScope } from './Domain.js'
 import { OpencodeMcp } from './Opencode/Mcp.js'
 
-export { Host, McpParseError, McpWriteError, Scope } from './Domain.js'
+export { Host, InstallScope, McpParseError, McpWriteError } from './Domain.js'
 
 /**
  * MCP install dispatcher. Per-host descriptors live in `Install/<Host>/Mcp.ts`
@@ -26,7 +26,7 @@ export class Mcp extends Effect.Service<Mcp>()('@expandai/cli/Install/Mcp', {
 		const opencode = yield* OpencodeMcp
 		const codex = yield* CodexMcp
 
-		const pathFor = Effect.fn('Mcp.pathFor')(function* (host: Host, scope: Scope) {
+		const pathFor = Effect.fn('Mcp.pathFor')(function* (host: Host, scope: InstallScope) {
 			return yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.pathFor(scope)),
 				Match.when('cursor', () => cursor.pathFor(scope)),
@@ -36,7 +36,7 @@ export class Mcp extends Effect.Service<Mcp>()('@expandai/cli/Install/Mcp', {
 			)
 		})
 
-		const install = Effect.fn('Mcp.install')(function* (host: Host, scope: Scope) {
+		const install = Effect.fn('Mcp.install')(function* (host: Host, scope: InstallScope) {
 			yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.install(scope)),
 				Match.when('cursor', () => cursor.install(scope)),
@@ -46,7 +46,7 @@ export class Mcp extends Effect.Service<Mcp>()('@expandai/cli/Install/Mcp', {
 			)
 		})
 
-		const uninstall = Effect.fn('Mcp.uninstall')(function* (host: Host, scope: Scope) {
+		const uninstall = Effect.fn('Mcp.uninstall')(function* (host: Host, scope: InstallScope) {
 			yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.uninstall(scope)),
 				Match.when('cursor', () => cursor.uninstall(scope)),
@@ -56,7 +56,7 @@ export class Mcp extends Effect.Service<Mcp>()('@expandai/cli/Install/Mcp', {
 			)
 		})
 
-		const isInstalled = Effect.fn('Mcp.isInstalled')(function* (host: Host, scope: Scope) {
+		const isInstalled = Effect.fn('Mcp.isInstalled')(function* (host: Host, scope: InstallScope) {
 			return yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.isInstalled(scope)),
 				Match.when('cursor', () => cursor.isInstalled(scope)),