expandai 0.0.2 → 0.0.3

package/src/Init/Service.ts

@@ -0,0 +1,385 @@
+import { Array, Config, Console, DateTime, Effect, Either, Schema } from 'effect'
+import { ManualAuthorizationApiError } from '../ApiClient.js'
+import {
+	ManualAuthorization,
+	ManualAuthorizationCredentialSaveFailed,
+	ManualAuthorizationDenied,
+	ManualAuthorizationInput,
+	ManualAuthorizationRefused,
+} from '../Auth/ManualAuthorization.js'
+import { SetupGrantAuthorization, SetupGrantAuthorizationError } from '../Auth/SetupGrantAuthorization.js'
+import { Authentication } from '../Authentication.js'
+import { CredentialStoreInsecure } from '../Config.js'
+import {
+	ALREADY_AUTHENTICATED_MESSAGE,
+	AUTHORIZATION_CONSUMED_MESSAGE,
+	AUTHORIZATION_REQUIRED_MESSAGE,
+	type InitHarness,
+	type InitRequest,
+	InitResult,
+	PARTIAL_CONFIGURATION_MESSAGE,
+} from './Domain.js'
+import type { HarnessInspection } from './HarnessAdapter.js'
+import { HarnessRegistry, UnsupportedInitHarnessError } from './HarnessRegistry.js'
+
+const InitServiceErrorCode = Schema.Literal(
+	'authorization_failed',
+	'setup_token_rejected',
+	'setup_unreachable',
+	'stored_credential_conflict',
+	'authorization_unreachable',
+	'authorization_denied',
+	'authorization_refused',
+	'credential_health_failed',
+	'credential_save_failed',
+	'credential_storage_insecure',
+	'unsupported_harness',
+	'inspection_failed',
+	'configuration_failed',
+	'policy_blocked',
+	'invalid_adapter_result',
+)
+
+export class InitServiceError extends Schema.TaggedError<InitServiceError>()('InitServiceError', {
+	code: InitServiceErrorCode,
+	recoverable: Schema.Boolean,
+}) {
+	get message() {
+		switch (this.code) {
+			case 'authorization_failed':
+				return 'Authorization could not be completed. Start authorization again.'
+			// A setup token is single-use and is spent by the attempt that failed, so
+			// the only way forward is a new prompt — never a retry of the same one.
+			case 'setup_token_rejected':
+				return 'That setup token was rejected and is now spent. Do not retry it. Ask the user for a fresh setup prompt from the Expand dashboard, or continue without one to authorize in a browser.'
+			// Distinct from a rejection: the token was never redeemed, so the same
+			// one is still good once the connection works.
+			case 'setup_unreachable':
+				return 'Could not reach Expand to redeem the setup token. Nothing was sent, so the same token is still good — check the network and run the same command again.'
+			// Refused before redemption, so unlike every other setup-token failure the
+			// prompt is still good — the user clears the stored key and runs it again.
+			case 'stored_credential_conflict':
+				return 'An Expand API key is already stored on this machine, and completing setup would replace it with no way to recover it. Nothing was changed and the setup prompt is still valid. Tell the user to run `expandai logout` to clear the stored key, then run the same setup command again.'
+			// Reached both when starting an authorization and when polling one that
+			// is already pending — either way nothing was changed, so "start again"
+			// is the one piece of advice guaranteed not to help.
+			case 'authorization_unreachable':
+				return 'Could not reach the Expand API. Nothing was changed: any pending authorization is still pending, and if none existed, none was started. Do not retry the same command until the connection is fixed. Check that this machine can reach the API — if you are running inside an agent sandbox, its shell may have network access disabled — and check `EXPAND_API_URL` if it is set. Then run the same command again.'
+			// A server-side refusal that a new code cannot fix. The one authorization
+			// failure where "run it again" is actively wrong: each retry costs the
+			// user another approval and fails identically.
+			case 'authorization_refused':
+				return 'Expand refused to complete the authorization for a reason a new code cannot fix — most likely an OAuth client, resource, or scope misconfiguration on the server. Do not run setup again; each retry asks the user to approve and then fails the same way. Report the error under `code`.'
+			// The user clicked Deny. Rerunning creates a fresh request; nothing is stuck.
+			case 'authorization_denied':
+				return 'The authorization was denied in the browser. If that was unintended, run the same command again for a fresh approval code.'
+			case 'credential_health_failed':
+				return 'Stored credentials could not be validated safely.'
+			case 'credential_save_failed':
+				return 'Authorization completed, but credentials could not be saved. Start authorization again.'
+			case 'credential_storage_insecure':
+				return 'Credential storage is not secure enough to continue.'
+			case 'unsupported_harness':
+				return 'This harness is not supported by init.'
+			case 'inspection_failed':
+				return 'The harness configuration could not be inspected safely.'
+			case 'configuration_failed':
+				return 'The harness configuration could not be updated safely.'
+			case 'policy_blocked':
+				return 'A managed harness policy blocks this configuration.'
+			case 'invalid_adapter_result':
+				return 'The harness adapter returned an invalid configuration result.'
+		}
+	}
+}
+
+function serviceError(code: typeof InitServiceErrorCode.Type, recoverable: boolean): InitServiceError {
+	return new InitServiceError({ code, recoverable })
+}
+
+function withoutInstallerOutput<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> {
+	return Console.consoleWith((base) =>
+		effect.pipe(
+			Console.withConsole({
+				...base,
+				log: () => Effect.void,
+			}),
+		),
+	)
+}
+
+function unknownField(input: unknown, field: string): unknown {
+	if (typeof input !== 'object' || input === null || !(field in input)) return undefined
+	return Object.getOwnPropertyDescriptor(input, field)?.value
+}
+
+function stringField(input: unknown, field: string): string | undefined {
+	const value = unknownField(input, field)
+	return typeof value === 'string' ? value : undefined
+}
+
+function booleanField(input: unknown, field: string): boolean | undefined {
+	const value = unknownField(input, field)
+	return typeof value === 'boolean' ? value : undefined
+}
+
+function mapCredentialHealthError(error: unknown): InitServiceError {
+	return error instanceof CredentialStoreInsecure
+		? serviceError('credential_storage_insecure', false)
+		: serviceError('credential_health_failed', false)
+}
+
+function mapAuthorizationError(error: unknown): InitServiceError {
+	if (error instanceof CredentialStoreInsecure) return serviceError('credential_storage_insecure', false)
+	if (error instanceof ManualAuthorizationDenied) return serviceError('authorization_denied', true)
+	if (error instanceof ManualAuthorizationRefused) return serviceError('authorization_refused', false)
+	if (error instanceof ManualAuthorizationCredentialSaveFailed) return serviceError('credential_save_failed', false)
+	// A lost poll *response* self-heals: the next run finds the code spent and
+	// transparently starts a fresh request, so unlike the old exchange there is
+	// no state to warn about — only the request-never-left case needs its name.
+	if (error instanceof ManualAuthorizationApiError && error.kind === 'request_failed') {
+		return serviceError('authorization_unreachable', true)
+	}
+	return serviceError('authorization_failed', booleanField(error, 'recoverable') ?? true)
+}
+
+/**
+ * Setup-token failures need their own codes. Collapsing them into
+ * `authorization_failed` told an agent only that something went wrong, and it
+ * filled the gap by guessing — reporting an expiry that had not happened, and
+ * retrying a token that redemption had already spent.
+ */
+function mapSetupGrantError(error: unknown): InitServiceError {
+	if (error instanceof CredentialStoreInsecure) return serviceError('credential_storage_insecure', false)
+	if (error instanceof SetupGrantAuthorizationError) {
+		// The one setup-token failure where the token is *not* spent.
+		if (error.code === 'stored_credential_conflict') return serviceError('stored_credential_conflict', true)
+		if (error.code === 'request_failed') return serviceError('setup_unreachable', true)
+		if (error.code === 'denied') return serviceError('authorization_denied', true)
+		// The token redeemed but the local write failed — a fresh prompt cannot
+		// help until storage is fixed, so don't report it as a token problem.
+		if (error.code === 'credential_save_failed') return serviceError('credential_save_failed', false)
+		// Same server-side refusal as the browser path; a fresh prompt cannot help.
+		if (error.code === 'refused') return serviceError('authorization_refused', false)
+		// Nothing was redeemed, so the prompt is still good once the file is fixed.
+		if (error.code === 'config_unreadable') return serviceError('credential_storage_insecure', true)
+		return serviceError('setup_token_rejected', true)
+	}
+	return serviceError('authorization_failed', booleanField(error, 'recoverable') ?? true)
+}
+
+function mapConfigurationError(error: unknown): InitServiceError {
+	if (error instanceof UnsupportedInitHarnessError) return serviceError('unsupported_harness', false)
+	const nested = unknownField(error, 'error') ?? error
+	const tag = stringField(nested, '_tag')
+	if (tag === 'ClaudeProfilePolicyBlockedError') return serviceError('policy_blocked', false)
+	if (tag === 'ClaudeAdapterOperationError' && stringField(nested, 'code') === 'inspection_failed') {
+		return serviceError('inspection_failed', true)
+	}
+	return serviceError('configuration_failed', true)
+}
+
+function manualInput(request: InitRequest): ManualAuthorizationInput {
+	return new ManualAuthorizationInput({ harness: 'agent-harnesses', scope: request.scope })
+}
+
+function completedRuntimeState(inspection: HarnessInspection): 'unverified' | 'reload_required' {
+	return inspection.runtimeState === 'reload_required' ? 'reload_required' : 'unverified'
+}
+
+interface CompleteHarnessInspection extends HarnessInspection {
+	readonly changed: boolean
+	readonly integrationVersion: string
+}
+
+function isCompleteHarnessInspection(
+	harness: InitHarness,
+	inspection: HarnessInspection,
+): inspection is CompleteHarnessInspection {
+	if (!inspection.configured || typeof inspection.changed !== 'boolean') return false
+	if (inspection.integrationVersion === undefined || inspection.integrationVersion.trim().length === 0) return false
+	if (inspection.nextAction.trim().length === 0) return false
+	const components = new Set(inspection.components)
+	const expectsHook = harness === 'claude-code' || harness === 'opencode'
+	return (
+		components.size === inspection.components.length &&
+		components.has('runtime-skill') &&
+		components.has('mcp') &&
+		(expectsHook ? components.has('webfetch-hook') && components.size === 3 : components.size === 2)
+	)
+}
+
+export class InitService extends Effect.Service<InitService>()('@expandai/cli/Init/Service', {
+	dependencies: [
+		Authentication.Default,
+		ManualAuthorization.Default,
+		SetupGrantAuthorization.Default,
+		HarnessRegistry.Default,
+	],
+	effect: Effect.gen(function* () {
+		const authentication = yield* Authentication
+		const authorization = yield* ManualAuthorization
+		const setupGrantAuthorization = yield* SetupGrantAuthorization
+		const registry = yield* HarnessRegistry
+
+		const configure = Effect.fnUntraced(function* (request: InitRequest, resumedAuthorization: boolean) {
+			// One pass per harness, and every harness gets its pass. Both stages used
+			// to be `Effect.forEach` with no options — sequential and fail-fast — so a
+			// failure on harness 2 of 4 left harness 1 configured on disk, skipped 3
+			// and 4 entirely, and told the caller only `configuration_failed` with no
+			// harness named, though the error carries one. Folding validation into the
+			// same pass keeps each harness's outcome attributable.
+			//
+			// Deliberately not rolled back across harnesses: undoing a working Cursor
+			// install because Codex failed is worse than reporting the difference.
+			// Re-running is safe — the adapters gate on `if (!configured)`.
+			// Concurrent: each adapter writes only inside its own harness namespace
+			// (`.claude/`, `.cursor/`, `.codex/`, `.opencode/`), and installer output
+			// is suppressed above — so there is no shared write target and no
+			// interleaved logging to order. Sequential here was incidental rather
+			// than deliberate.
+			//
+			// The Claude adapter does shell out — `expandai --version`, to check the
+			// installed CLI is on PATH — but it is a read-only probe in its own
+			// process, so running four of them at once is fine.
+			const outcomes = yield* Effect.forEach(
+				request.harnesses,
+				(harness) =>
+					withoutInstallerOutput(registry.configure(harness, request.scope)).pipe(
+						Effect.withTracerEnabled(false),
+						Effect.mapError(mapConfigurationError),
+						Effect.flatMap((inspection) => {
+							if (inspection.policyBlock !== undefined || inspection.runtimeState === 'blocked') {
+								return serviceError('policy_blocked', false)
+							}
+							if (!isCompleteHarnessInspection(harness, inspection)) {
+								return serviceError('invalid_adapter_result', false)
+							}
+							return Effect.succeed({
+								harness,
+								configured: inspection.configured,
+								changed: inspection.changed,
+								components: inspection.components,
+								version: inspection.integrationVersion,
+								verification: {
+									runtimeState: completedRuntimeState(inspection),
+									nextAction: inspection.nextAction,
+								},
+							})
+						}),
+						Effect.either,
+						Effect.map((outcome) => ({ harness, outcome })),
+					),
+				{ concurrency: 'unbounded' },
+			)
+			const installations = Array.getRights(outcomes.map(({ outcome }) => outcome))
+			const failures = outcomes.flatMap(({ harness, outcome }) =>
+				Either.isLeft(outcome) ? [{ harness, code: outcome.left.code, recoverable: outcome.left.recoverable }] : [],
+			)
+			// Nothing landed, so there is no partial result to report — this is the
+			// same plain failure it has always been, with the first harness's reason.
+			const firstFailure = failures[0]
+			if (installations.length === 0 && firstFailure !== undefined) {
+				return yield* serviceError(firstFailure.code, firstFailure.recoverable)
+			}
+			// Same resolution the installers use, so the reported path is the one
+			// that was actually written to rather than an educated guess.
+			const projectPath = yield* Config.string('PWD').pipe(
+				Config.withDefault(process.cwd()),
+				// `Config.withDefault` is `orElseIf(..., ConfigError.isMissingDataOnly)`,
+				// so it recovers a *missing* PWD and nothing else. This catches the rest
+				// — provider and source failures — keeping `ConfigError` out of a service
+				// whose callers type against `InitServiceError` alone.
+				Effect.orElseSucceed(() => process.cwd()),
+			)
+			const candidate = {
+				schemaVersion: 1 as const,
+				status: 'completed' as const,
+				harnesses: request.harnesses,
+				scope: request.scope,
+				// A partial run outranks "authorization consumed": the agent relays this
+				// verbatim, and the thing the user needs to know is that a harness they
+				// picked is not set up, not how the credential was obtained.
+				userMessage:
+					failures.length > 0
+						? PARTIAL_CONFIGURATION_MESSAGE
+						: resumedAuthorization
+							? AUTHORIZATION_CONSUMED_MESSAGE
+							: ALREADY_AUTHENTICATED_MESSAGE,
+				auth: { healthy: true },
+				...(request.scope === 'project' ? { projectPath } : {}),
+				installations,
+				...(failures.length > 0 ? { failures } : {}),
+			}
+			const result = yield* Schema.decodeUnknown(InitResult)(candidate).pipe(
+				Effect.mapError(() => serviceError('invalid_adapter_result', false)),
+			)
+			yield* Effect.annotateCurrentSpan({
+				status: result.status,
+				harnessCount: installations.length,
+				componentCount: installations.reduce((count, installation) => count + installation.components.length, 0),
+			})
+			return result
+		})
+
+		const run = Effect.fn('InitService.run')(function* (request: InitRequest) {
+			yield* Effect.annotateCurrentSpan({
+				harnessCount: request.harnesses.length,
+				scope: request.scope,
+			})
+			return yield* Effect.gen(function* () {
+				const initiallyHealthy = yield* authentication
+					.hasLocallyUsableCredentials()
+					.pipe(Effect.withTracerEnabled(false), Effect.mapError(mapCredentialHealthError))
+
+				if (request.setupToken !== undefined) {
+					yield* setupGrantAuthorization
+						.authorize({ setupToken: request.setupToken, harness: 'agent-harnesses', scope: request.scope })
+						.pipe(Effect.withTracerEnabled(false), Effect.mapError(mapSetupGrantError))
+					const setupHealthy = yield* authentication
+						.hasLocallyUsableCredentials()
+						.pipe(Effect.withTracerEnabled(false), Effect.mapError(mapCredentialHealthError))
+					if (!setupHealthy) return yield* serviceError('authorization_failed', true)
+					return yield* configure(request, true)
+				}
+
+				if (initiallyHealthy) return yield* configure(request, false)
+
+				// One advance per invocation: create the device authorization on the
+				// first run, poll it once on every later run. The agent drives the
+				// RFC 8628 loop by re-invoking; this process never waits.
+				const outcome = yield* authorization
+					.advance(manualInput(request))
+					.pipe(Effect.withTracerEnabled(false), Effect.mapError(mapAuthorizationError))
+
+				if (outcome._tag === 'TokensSaved') {
+					const resumedHealthy = yield* authentication
+						.hasLocallyUsableCredentials()
+						.pipe(Effect.withTracerEnabled(false), Effect.mapError(mapCredentialHealthError))
+					if (!resumedHealthy) return yield* serviceError('authorization_failed', true)
+					return yield* configure(request, true)
+				}
+
+				const candidate = {
+					schemaVersion: 1 as const,
+					status: 'authorization_required' as const,
+					harnesses: request.harnesses,
+					scope: request.scope,
+					userMessage: AUTHORIZATION_REQUIRED_MESSAGE,
+					authorization: {
+						url: outcome.pending.verificationUri,
+						userCode: outcome.pending.userCode,
+						approvalExpiresAt: DateTime.formatIso(outcome.pending.approvalExpiresAt),
+					},
+				}
+				const result = yield* Schema.decodeUnknown(InitResult)(candidate).pipe(
+					Effect.mapError(() => serviceError('authorization_failed', false)),
+				)
+				yield* Effect.annotateCurrentSpan({ status: result.status, componentCount: 0 })
+				return result
+			})
+		})
+
+		return { run } as const
+	}),
+}) {}

package/src/Init/StandardAdapters.ts

@@ -0,0 +1,141 @@
+import { FileSystem } from '@effect/platform'
+import { NodeFileSystem } from '@effect/platform-node'
+import { Effect } from 'effect'
+import { CodexMcp } from '../Install/Codex/Mcp.js'
+import { CodexSkill } from '../Install/Codex/Skill.js'
+import { CursorMcp } from '../Install/Cursor/Mcp.js'
+import { CursorSkill } from '../Install/Cursor/Skill.js'
+import { OpencodeHook } from '../Install/Opencode/Hook.js'
+import { OpencodeMcp } from '../Install/Opencode/Mcp.js'
+import { OpencodeSkill } from '../Install/Opencode/Skill.js'
+import { CLI_VERSION } from '../Version.js'
+import type { InitComponent, InitHarness, InitScope } from './Domain.js'
+import { HarnessConfigurationError, type HarnessInspection, HarnessInspectionError } from './HarnessAdapter.js'
+
+interface StandardHarnessOperations {
+	readonly harness: InitHarness
+	readonly components: InitComponent[]
+	/** Per component, so a partial install is reported as one — see `inspection`. */
+	readonly inspectComponents: (scope: InitScope) => Effect.Effect<ReadonlyArray<InitComponent>, unknown>
+	readonly install: (scope: InitScope) => Effect.Effect<unknown, unknown>
+}
+
+/**
+ * Reports what is actually present rather than collapsing everything into one
+ * boolean. Deriving `components` from a single flag meant that after a CLI
+ * upgrade which only changes `SKILL.md`, a perfectly valid `~/.cursor/mcp.json`
+ * was reported as absent — and `integrationVersion` and `runtimeState` degraded
+ * with it, so the whole record went blank over one stale file.
+ */
+function inspection(
+	operations: StandardHarnessOperations,
+	present: ReadonlyArray<InitComponent>,
+	changed: boolean,
+): HarnessInspection {
+	const configured = operations.components.every((component) => present.includes(component))
+	return {
+		configured,
+		changed,
+		components: [...present],
+		integrationVersion: configured ? CLI_VERSION : undefined,
+		runtimeState: configured ? 'reload_required' : 'unverified',
+		nextAction: configured ? 'restart-or-reload-harness-then-use-expand' : 'configure-harness',
+	}
+}
+
+function makeAdapter(operations: StandardHarnessOperations) {
+	const inspect = Effect.fn(`${operations.harness}.inspect`)(function* (scope: InitScope) {
+		return yield* operations.inspectComponents(scope).pipe(
+			Effect.map((present) => inspection(operations, present, false)),
+			Effect.mapError((error) => new HarnessInspectionError({ harness: operations.harness, scope, error })),
+		)
+	})
+	const configure = Effect.fn(`${operations.harness}.configure`)(function* (scope: InitScope) {
+		return yield* Effect.gen(function* () {
+			const before = yield* operations.inspectComponents(scope)
+			const complete = operations.components.every((component) => before.includes(component))
+			if (!complete) yield* operations.install(scope)
+			const verified = yield* operations.inspectComponents(scope)
+			return inspection(operations, verified, !complete)
+		}).pipe(Effect.mapError((error) => new HarnessConfigurationError({ harness: operations.harness, scope, error })))
+	})
+	return { harness: operations.harness, inspect, configure } as const
+}
+
+export class CursorAdapter extends Effect.Service<CursorAdapter>()('@expandai/cli/Init/CursorAdapter', {
+	dependencies: [CursorMcp.Default, CursorSkill.Default],
+	effect: Effect.gen(function* () {
+		const mcp = yield* CursorMcp
+		const skill = yield* CursorSkill
+		return makeAdapter({
+			harness: 'cursor',
+			components: ['runtime-skill', 'mcp'],
+			inspectComponents: (scope) =>
+				Effect.all([
+					mcp.isInstalled(scope),
+					// Content, not presence: a CLI upgrade ships new skill text, and gating on
+					// "the file exists" would keep serving the previous instructions forever.
+					skill.isCurrent(scope),
+				]).pipe(
+					Effect.map(([mcpInstalled, skillCurrent]) => [
+						...(skillCurrent ? (['runtime-skill'] as const) : []),
+						...(mcpInstalled ? (['mcp'] as const) : []),
+					]),
+				),
+			install: (scope) => Effect.all([mcp.install(scope), skill.install(scope)]),
+		})
+	}),
+}) {}
+
+export class CodexAdapter extends Effect.Service<CodexAdapter>()('@expandai/cli/Init/CodexAdapter', {
+	dependencies: [CodexMcp.Default, CodexSkill.Default],
+	effect: Effect.gen(function* () {
+		const mcp = yield* CodexMcp
+		const skill = yield* CodexSkill
+		return makeAdapter({
+			harness: 'codex',
+			components: ['runtime-skill', 'mcp'],
+			inspectComponents: (scope) =>
+				Effect.all([
+					mcp.isInstalled(scope),
+					// Content, not presence: a CLI upgrade ships new skill text, and gating on
+					// "the file exists" would keep serving the previous instructions forever.
+					skill.isCurrent(scope),
+				]).pipe(
+					Effect.map(([mcpInstalled, skillCurrent]) => [
+						...(skillCurrent ? (['runtime-skill'] as const) : []),
+						...(mcpInstalled ? (['mcp'] as const) : []),
+					]),
+				),
+			install: (scope) => Effect.all([mcp.install(scope), skill.install(scope)]),
+		})
+	}),
+}) {}
+
+export class OpencodeAdapter extends Effect.Service<OpencodeAdapter>()('@expandai/cli/Init/OpencodeAdapter', {
+	dependencies: [NodeFileSystem.layer, OpencodeHook.Default, OpencodeMcp.Default, OpencodeSkill.Default],
+	effect: Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem
+		const hook = yield* OpencodeHook
+		const mcp = yield* OpencodeMcp
+		const skill = yield* OpencodeSkill
+		return makeAdapter({
+			harness: 'opencode',
+			components: ['webfetch-hook', 'runtime-skill', 'mcp'],
+			inspectComponents: (scope) =>
+				Effect.all([
+					mcp.isInstalled(scope),
+					hook.pathFor(scope).pipe(Effect.flatMap(fileSystem.exists)),
+					// Content, not presence — see the note on the other standard adapters.
+					skill.isCurrent(scope),
+				]).pipe(
+					Effect.map(([mcpInstalled, hookInstalled, skillCurrent]) => [
+						...(hookInstalled ? (['webfetch-hook'] as const) : []),
+						...(skillCurrent ? (['runtime-skill'] as const) : []),
+						...(mcpInstalled ? (['mcp'] as const) : []),
+					]),
+				),
+			install: (scope) => Effect.all([mcp.install(scope), hook.install(scope), skill.install(scope)]),
+		})
+	}),
+}) {}