expandai 0.0.2 → 0.0.3

package/src/Commands/Init.ts

@@ -0,0 +1,489 @@
+import { Command, Options, Prompt } from '@effect/cli'
+import { Terminal } from '@effect/platform'
+import { Array, Console, Effect, Either, Option, Schema } from 'effect'
+import { Authentication } from '../Authentication.js'
+import {
+	HARNESS_SELECTION_MESSAGE,
+	InitDetectionResult,
+	InitErrorEnvelope,
+	InitHarness,
+	type InitHarnesses,
+	InitRequest,
+	InitResult,
+	InitScope,
+	NO_HARNESS_DETECTED_MESSAGE,
+} from '../Init/Domain.js'
+import { HarnessDetector } from '../Init/HarnessDetector.js'
+import { InitService, InitServiceError } from '../Init/Service.js'
+
+const harness = Options.text('harness').pipe(
+	Options.optional,
+	Options.withDescription('Agent harness running this setup, used as a detection hint'),
+)
+
+const harnesses = Options.text('harnesses').pipe(
+	Options.optional,
+	Options.withDescription('Comma-separated harnesses to configure. Omit to configure every detected harness.'),
+)
+
+const detect = Options.boolean('detect').pipe(
+	Options.withDescription('Report the harnesses setup would configure, and change nothing'),
+)
+
+const scope = Options.text('scope').pipe(Options.optional, Options.withDescription('Configuration scope'))
+
+const setupToken = Options.text('setup-token').pipe(
+	Options.optional,
+	Options.withDescription('Short-lived, single-use setup token from the Expand dashboard'),
+)
+
+const json = Options.boolean('json').pipe(Options.withDescription('Emit one machine-readable JSON result'))
+
+const config = { harness, harnesses, detect, scope, setupToken, json }
+
+const InitErrorJson = Schema.parseJson(InitErrorEnvelope)
+const InitResultJson = Schema.parseJson(InitResult)
+const InitDetectionJson = Schema.parseJson(InitDetectionResult)
+
+const INVALID_ARGUMENTS_MESSAGE =
+	'Agent init requires --scope project|global and --json, or --detect --json to only report detected harnesses. Optional: --harnesses claude-code,cursor,opencode,codex to configure an explicit subset, --harness <name> as a current-harness hint, and --setup-token <token> from a dashboard setup prompt. After the user approves in the browser, run the same command again — there is no code to pass back.'
+
+export const SUPPORTED_HARNESS_LIST = 'claude-code, cursor, opencode, codex'
+
+/**
+ * Says that the *harness itself* is unsupported, rather than that the flag was
+ * malformed. An agent told only "invalid arguments" alongside a list of four
+ * valid names will pick one of them and misreport the user's environment.
+ */
+export const UNSUPPORTED_HARNESS_MESSAGE = `Expand does not support that agent harness. Supported harnesses are ${SUPPORTED_HARNESS_LIST}. Do not substitute a different harness: tell the user their agent is not supported yet.`
+
+const INVALID_SETUP_TOKEN_MESSAGE =
+	'That setup token is malformed. Copy it exactly as the dashboard issued it, or create a new one; do not retype or truncate it.'
+
+const INVALID_HARNESS_SELECTION_MESSAGE = `--harnesses takes a comma-separated list drawn from ${SUPPORTED_HARNESS_LIST}, for example --harnesses claude-code,cursor. Every entry must be one of those names.`
+
+/** Mirrors the `SetupToken` schema so a typo is reported as a bad token, not bad flags. */
+const SETUP_TOKEN_PATTERN = /^[A-Za-z0-9._~-]{20,256}$/u
+
+/** Distinct codes so an agent can fix the specific argument instead of guessing. */
+function argumentErrorJson(code: string, message: string): string {
+	return Schema.encodeSync(InitErrorJson)(
+		new InitErrorEnvelope({ schemaVersion: 1, status: 'error', code, message, recoverable: true }),
+	)
+}
+
+function invalidArgumentsJson(): string {
+	return argumentErrorJson('invalid_arguments', INVALID_ARGUMENTS_MESSAGE)
+}
+
+function errorJson(code: string, message: string, recoverable: boolean): string {
+	return Schema.encodeSync(InitErrorJson)(
+		new InitErrorEnvelope({ schemaVersion: 1, status: 'error', code, message, recoverable }),
+	)
+}
+
+function emitError(code: string, message: string, recoverable: boolean, exitCode: number) {
+	return Console.error(errorJson(code, message, recoverable)).pipe(
+		Effect.zipRight(Effect.sync(() => void (process.exitCode = exitCode))),
+	)
+}
+
+export interface InitCommandOptions {
+	readonly detect: boolean
+	readonly harness: Option.Option<string>
+	readonly harnesses: Option.Option<string>
+	readonly json: boolean
+	readonly scope: Option.Option<string>
+	readonly setupToken: Option.Option<string>
+}
+
+/**
+ * Decodes `--harnesses claude-code,cursor`. Returns `undefined` for any
+ * unknown or empty entry: silently dropping one would configure less than the
+ * user asked for, which is the failure mode this flag exists to prevent.
+ */
+export function parseHarnessSelection(value: string): InitHarnesses | undefined {
+	const entries = value.split(',').map((entry) => entry.trim())
+	const decoded: InitHarness[] = []
+	for (const entry of entries) {
+		const harness = Schema.decodeUnknownOption(InitHarness)(entry)
+		if (Option.isNone(harness)) return undefined
+		if (!decoded.includes(harness.value)) decoded.push(harness.value)
+	}
+	return Array.isNonEmptyArray(decoded) ? decoded : undefined
+}
+
+export interface OnboardingExecutionModeInput {
+	readonly argv: readonly string[]
+	readonly environment: Readonly<Record<string, string | undefined>>
+	readonly stdinIsTty: boolean
+	readonly stdoutIsTty: boolean
+}
+
+export interface InitExecutionModeInput extends OnboardingExecutionModeInput {}
+
+function enabledEnvironmentFlag(value: string | undefined): boolean {
+	return value !== undefined && value !== '' && value !== '0' && value !== 'false'
+}
+
+/** Selects a safe onboarding surface before either CLI tree parses the command. */
+export function resolveOnboardingExecutionMode(
+	input: OnboardingExecutionModeInput,
+	command: 'init' | 'status',
+): 'human' | 'machine' | undefined {
+	if (input.argv[2] !== command) return undefined
+	const args = input.argv.slice(3)
+	const agentSignal =
+		input.environment.EXPANDAI_CLI_CONTEXT === 'agent' ||
+		enabledEnvironmentFlag(input.environment.CLAUDECODE) ||
+		input.environment.CURSOR_TRACE_ID !== undefined ||
+		input.environment.CODEX_RUN_ID !== undefined
+	const machineSafe = !input.stdinIsTty || !input.stdoutIsTty || args.includes('--json') || agentSignal
+	return machineSafe ? 'machine' : 'human'
+}
+
+/** Selects the safe init surface before either CLI tree parses the command. */
+export function resolveInitExecutionMode(input: InitExecutionModeInput): 'human' | 'machine' | undefined {
+	return resolveOnboardingExecutionMode(input, 'init')
+}
+
+function parseMachineArguments(args: readonly string[]): InitCommandOptions | undefined {
+	function parse(index: number, parsed: InitCommandOptions): InitCommandOptions | undefined {
+		if (index >= args.length) return parsed
+		const token = args[index]
+		if (token === '--json' && !parsed.json) {
+			return parse(index + 1, { ...parsed, json: true })
+		}
+		if (token === '--detect' && !parsed.detect) {
+			return parse(index + 1, { ...parsed, detect: true })
+		}
+		if (token !== '--setup-token' && token !== '--harness' && token !== '--harnesses' && token !== '--scope')
+			return undefined
+		const value = args[index + 1]
+		if (value === undefined || value.startsWith('-')) return undefined
+		if (token === '--setup-token' && Option.isNone(parsed.setupToken)) {
+			return parse(index + 2, { ...parsed, setupToken: Option.some(value) })
+		}
+		if (token === '--harness' && Option.isNone(parsed.harness)) {
+			return parse(index + 2, { ...parsed, harness: Option.some(value) })
+		}
+		if (token === '--harnesses' && Option.isNone(parsed.harnesses)) {
+			return parse(index + 2, { ...parsed, harnesses: Option.some(value) })
+		}
+		if (token === '--scope' && Option.isNone(parsed.scope)) {
+			return parse(index + 2, { ...parsed, scope: Option.some(value) })
+		}
+		return undefined
+	}
+
+	return parse(0, {
+		detect: false,
+		harness: Option.none(),
+		harnesses: Option.none(),
+		json: false,
+		scope: Option.none(),
+		setupToken: Option.none(),
+	})
+}
+
+/** Returns a safe JSON error before Effect CLI can render ordinary parser help. */
+export function preflightAgentInitArgv(argv: readonly string[]): string | undefined {
+	if (argv[2] !== 'init') return undefined
+	const args = argv.slice(3)
+	if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) return undefined
+	const parsed = parseMachineArguments(args)
+	if (parsed === undefined) return invalidArgumentsJson()
+	if (!parsed.json) return invalidArgumentsJson()
+	if (Option.isSome(parsed.harness) && Option.isNone(Schema.decodeUnknownOption(InitHarness)(parsed.harness.value))) {
+		return argumentErrorJson('unsupported_harness', UNSUPPORTED_HARNESS_MESSAGE)
+	}
+	if (Option.isSome(parsed.harnesses) && parseHarnessSelection(parsed.harnesses.value) === undefined) {
+		return argumentErrorJson('invalid_harness_selection', INVALID_HARNESS_SELECTION_MESSAGE)
+	}
+	// Detection reports and exits, so it needs no scope and no credentials.
+	if (parsed.detect) return undefined
+	if (!Option.contains(parsed.scope, 'project') && !Option.contains(parsed.scope, 'global')) {
+		return invalidArgumentsJson()
+	}
+	if (Option.isSome(parsed.setupToken) && !SETUP_TOKEN_PATTERN.test(parsed.setupToken.value)) {
+		return argumentErrorJson('invalid_setup_token', INVALID_SETUP_TOKEN_MESSAGE)
+	}
+	return undefined
+}
+
+function renderHumanResult(result: typeof InitResult.Type): string {
+	if (result.status === 'authorization_required') {
+		// The approval page asks the user to type this code and compare it against
+		// their terminal, so the terminal has to print it.
+		return `Expand authorization required\n${result.userMessage}\nOpen: ${result.authorization.url.toString()}\nEnter code: ${result.authorization.userCode}`
+	}
+	const configured = result.installations.map((installation) => installation.harness).join(', ')
+	const failures = result.failures ?? []
+	// A run that configured some harnesses and not others must not print
+	// "complete" — the heading is the part a user skims.
+	const heading = failures.length > 0 ? 'Expand setup incomplete' : 'Expand setup complete'
+	const failed = failures.map((failure) => `${failure.harness} (${failure.code})`).join(', ')
+	return [
+		heading,
+		result.userMessage,
+		`Configured: ${configured}`,
+		...(failures.length > 0 ? [`Failed: ${failed}`] : []),
+	].join('\n')
+}
+
+const runInitService = Effect.fnUntraced(function* (request: InitRequest, jsonOutput: boolean) {
+	const initService = yield* InitService
+	const result = yield* Effect.either(initService.run(request))
+	if (Either.isLeft(result)) {
+		const error = result.left
+		if (error instanceof InitServiceError) {
+			yield* emitError(error.code, error.message, error.recoverable, 1)
+			return
+		}
+		yield* emitError('init_failed', 'Expand init could not be completed safely.', true, 1)
+		return
+	}
+	if (!jsonOutput) {
+		yield* Console.log(renderHumanResult(result.right))
+		return
+	}
+	const encoded = yield* Schema.encode(InitResultJson)(result.right).pipe(
+		Effect.catchAll(() => emitError('invalid_result', 'Expand init returned an invalid result.', false, 1)),
+	)
+	if (typeof encoded === 'string') yield* Console.log(encoded)
+})
+
+/** Emits what setup would configure without authorizing or writing anything. */
+const runAgentDetect = Effect.fnUntraced(function* (hint: Option.Option<InitHarness>) {
+	const detector = yield* HarnessDetector
+	const detected = yield* detector.detect({ ...(Option.isSome(hint) ? { hint: hint.value } : {}) })
+	const current = yield* detector.detectCurrent()
+	const encoded = yield* Schema.encode(InitDetectionJson)(
+		new InitDetectionResult({
+			schemaVersion: 1,
+			status: 'detected',
+			harnesses: detected,
+			...(Option.isSome(current) ? { current: current.value } : {}),
+			userMessage: detected.length === 0 ? NO_HARNESS_DETECTED_MESSAGE : HARNESS_SELECTION_MESSAGE,
+		}),
+	).pipe(Effect.catchAll(() => emitError('invalid_result', 'Expand init returned an invalid result.', false, 1)))
+	if (typeof encoded === 'string') yield* Console.log(encoded)
+})
+
+const runAgentInit = Effect.fnUntraced(function* ({
+	detect: detectOnly,
+	harness,
+	harnesses: harnessSelection,
+	json,
+	scope,
+	setupToken,
+}: InitCommandOptions) {
+	if (!json) {
+		yield* emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2)
+		return
+	}
+	const harnessHint = Option.flatMap(harness, (value) => Schema.decodeUnknownOption(InitHarness)(value))
+	if (Option.isSome(harness) && Option.isNone(harnessHint)) {
+		yield* emitError('unsupported_harness', UNSUPPORTED_HARNESS_MESSAGE, true, 2)
+		return
+	}
+	if (detectOnly) {
+		yield* runAgentDetect(harnessHint)
+		return
+	}
+	if (!Option.contains(scope, 'project') && !Option.contains(scope, 'global')) {
+		yield* emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2)
+		return
+	}
+	const selected = Option.map(harnessSelection, parseHarnessSelection)
+	if (Option.isSome(selected) && selected.value === undefined) {
+		yield* emitError('invalid_harness_selection', INVALID_HARNESS_SELECTION_MESSAGE, true, 2)
+		return
+	}
+	const detector = yield* HarnessDetector
+	// An explicit selection is the user's answer to "which harnesses?" — it is
+	// authoritative, and detection must not widen it.
+	const harnesses =
+		Option.isSome(selected) && selected.value !== undefined
+			? selected.value
+			: yield* detector.detect({ ...(Option.isSome(harnessHint) ? { hint: harnessHint.value } : {}) })
+	if (harnesses.length === 0) {
+		yield* emitError(
+			'no_harness_detected',
+			'No supported agent harness was detected. Pass --harness with the agent currently running setup.',
+			true,
+			2,
+		)
+		return
+	}
+
+	const request = yield* Schema.decodeUnknown(InitRequest)({
+		harnesses,
+		scope: Option.getOrUndefined(scope),
+		...(Option.isSome(setupToken) ? { setupToken: setupToken.value } : {}),
+	}).pipe(
+		Effect.catchAll(() =>
+			emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2).pipe(Effect.as(undefined)),
+		),
+	)
+	if (request === undefined) return
+
+	yield* runInitService(request, true)
+})
+
+export class InitTerminalInteraction extends Effect.Service<InitTerminalInteraction>()(
+	'@expandai/cli/Commands/InitTerminalInteraction',
+	{
+		effect: Effect.gen(function* () {
+			const terminal = yield* Terminal.Terminal
+			const chooseScope = Effect.fnUntraced(function* () {
+				return yield* Prompt.select({
+					message: 'Where should Expand be available?',
+					// Global leads: most people want Expand in every project, and it is
+					// the scope the hosted setup guide asks agents to offer first.
+					choices: [
+						{ title: 'All projects for this user', value: 'global' as const },
+						{ title: 'This project', value: 'project' as const },
+					],
+				}).pipe(Effect.provideService(Terminal.Terminal, terminal))
+			})
+			/**
+			 * Setup writes to every harness the user confirms here and to no other.
+			 * Detected harnesses start selected so the common "configure everything"
+			 * case is one keystroke, but the list is always shown before anything
+			 * on disk changes.
+			 */
+			const chooseHarnesses = Effect.fnUntraced(function* (detected: ReadonlyArray<InitHarness>) {
+				return yield* Prompt.multiSelect({
+					message: 'Which harnesses should Expand configure?',
+					choices: detected.map((harness) => ({ title: harness, value: harness, selected: true })),
+				}).pipe(Effect.provideService(Terminal.Terminal, terminal))
+			})
+			return { chooseScope, chooseHarnesses } as const
+		}),
+	},
+) {}
+
+/**
+ * Human counterpart to `runAgentDetect`: the same detection, rendered for a
+ * terminal instead of as JSON, and writing nothing either way.
+ */
+const runHumanDetect = Effect.fnUntraced(function* (hint: Option.Option<InitHarness>) {
+	const detector = yield* HarnessDetector
+	const detected = yield* detector.detect({ ...(Option.isSome(hint) ? { hint: hint.value } : {}) })
+	const current = yield* detector.detectCurrent()
+	if (detected.length === 0) {
+		yield* Console.log('No supported agent harness was detected. Nothing was changed.')
+		return
+	}
+	yield* Console.log(
+		[
+			'Detected harnesses. Nothing was changed.',
+			...detected.map(
+				(harness) => `  ${harness}${Option.isSome(current) && current.value === harness ? '  (this one)' : ''}`,
+			),
+			'',
+			'Run `expandai init` to configure them.',
+		].join('\n'),
+	)
+})
+
+export const runHumanInit = Effect.fnUntraced(function* (options: InitCommandOptions) {
+	if (options.json) {
+		yield* runAgentInit(options)
+		return
+	}
+	const decodedHarness = Option.flatMap(options.harness, (value) => Schema.decodeUnknownOption(InitHarness)(value))
+	if (Option.isSome(options.harness) && Option.isNone(decodedHarness)) {
+		yield* emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2)
+		return
+	}
+	// `--detect` documents itself as changing nothing, and the guide tells agents
+	// the same. Only `runAgentInit` ever read the flag, and humans do not pass
+	// `--json`, so `expandai init --detect` in a terminal performed a real install.
+	// Answered before the scope prompt, because asking is itself a side effect —
+	// and `--harnesses`/`--scope` are irrelevant to detection.
+	if (options.detect) {
+		yield* runHumanDetect(decodedHarness)
+		return
+	}
+	const interaction = yield* InitTerminalInteraction
+	const scopeInput = Option.isSome(options.scope) ? options.scope.value : yield* interaction.chooseScope()
+	const decodedScope = Schema.decodeUnknownOption(InitScope)(scopeInput)
+	if (Option.isNone(decodedScope)) {
+		yield* emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2)
+		return
+	}
+	const selected = Option.map(options.harnesses, parseHarnessSelection)
+	if (Option.isSome(selected) && selected.value === undefined) {
+		yield* emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2)
+		return
+	}
+	// An explicit `--harnesses` is the answer, not a hint, so detection is skipped
+	// entirely — it exists only to build the question. Running it first rejected
+	// `--harnesses codex` on a machine with no Codex config, which is exactly when
+	// someone passes the flag. The machine path already treats it as authoritative.
+	const explicit = Option.isSome(selected) ? selected.value : undefined
+	const harnesses =
+		explicit ??
+		(yield* Effect.gen(function* () {
+			const detector = yield* HarnessDetector
+			const detected = yield* detector.detect({
+				...(Option.isSome(decodedHarness) ? { hint: decodedHarness.value } : {}),
+			})
+			return detected.length === 0 ? undefined : yield* interaction.chooseHarnesses(detected)
+		}))
+	if (harnesses === undefined) {
+		yield* emitError(
+			'no_harness_detected',
+			'No supported agent harness was detected. Re-run with --harness for the agent you want to configure.',
+			true,
+			2,
+		)
+		return
+	}
+	if (!Array.isNonEmptyReadonlyArray(harnesses)) {
+		yield* Console.log('No harnesses selected. Nothing was changed.')
+		return
+	}
+	const request = yield* Schema.decodeUnknown(InitRequest)({
+		harnesses,
+		scope: decodedScope.value,
+		...(Option.isSome(options.setupToken) ? { setupToken: options.setupToken.value } : {}),
+	}).pipe(
+		Effect.catchAll(() =>
+			emitError('invalid_arguments', INVALID_ARGUMENTS_MESSAGE, true, 2).pipe(Effect.as(undefined)),
+		),
+	)
+	if (request === undefined) return
+
+	if (Option.isNone(options.setupToken)) {
+		const authentication = yield* Authentication
+		const credentialHealth = yield* Effect.either(authentication.hasLocallyUsableCredentials())
+		if (Either.isLeft(credentialHealth)) {
+			yield* emitError('credential_health_failed', 'Stored credentials could not be validated safely.', false, 1)
+			return
+		}
+		if (!credentialHealth.right) {
+			const login = yield* Effect.either(authentication.loginWithBrowser())
+			if (Either.isLeft(login)) {
+				yield* emitError('authorization_failed', 'Browser authorization could not be completed.', true, 1)
+				return
+			}
+		}
+	}
+
+	yield* runInitService(request, options.json)
+})
+
+const initDescription = 'Authorize Expand and configure the complete supported harness profile'
+
+export const HumanInitCommand = Command.make('init', config).pipe(
+	Command.withDescription(initDescription),
+	Command.withHandler(runHumanInit),
+)
+
+export const AgentInitCommand = Command.make('init', config).pipe(
+	Command.withDescription(initDescription),
+	Command.withHandler(runAgentInit),
+)

package/src/Commands/Search.ts

@@ -1,7 +1,9 @@
 import { Args, Command, Options } from '@effect/cli'
+import { resolvePlaygroundHost } from '@expandai/sdk/Playground'
 import { Console, Effect, Layer, Match, Schema } from 'effect'
 import { ApiClient } from '../ApiClient.js'
 import { ConfigManager } from '../Config.js'
+import { CitedSnapshotSearchResult, enrichSnapshotSearchResult } from '../Mcp/tools/Citations.js'
 import { renderSnippets } from '../Snippets.js'
 
 export class SnapshotSnippetsUnavailable extends Schema.TaggedError<SnapshotSnippetsUnavailable>()(
@@ -72,15 +74,18 @@ export const SearchCommand: Command.Command<'search', never, unknown, SearchComm
 					search: { query, maxResults, minScore },
 					include: { markdown: true, json: true },
 				})
+				const cited = enrichSnapshotSearchResult(result, host, 'cli-recovery')
 
 				const output = yield* Match.value(format).pipe(
 					Match.when('text', () => {
-						const snippets = result.search.snippets
+						const snippets = cited.search.snippets
 						return snippets.length === 0
 							? Effect.fail(new SnapshotSnippetsUnavailable({ snapshotId, query }))
-							: Effect.succeed(renderSnippets(snapshotId, host, snippets))
+							: Effect.succeed(
+									`[invocation: cli-recovery]\n${renderSnippets(snapshotId, resolvePlaygroundHost(result.playground, host), snippets)}`,
+								)
 					}),
-					Match.when('json', () => Schema.encode(Schema.parseJson(Schema.Unknown, { space: 2 }))(result)),
+					Match.when('json', () => Schema.encode(Schema.parseJson(CitedSnapshotSearchResult, { space: 2 }))(cited)),
 					Match.exhaustive,
 				)