expandai 0.0.0 → 0.0.2

package/src/BrowserOAuth.ts

@@ -0,0 +1,361 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
+import { NodeHttpClient } from '@effect/platform-node'
+import { DateTime, Duration, Effect, Inspectable, Redacted, Schema } from 'effect'
+import { ConfigManager, OAuthConfig } from './Config.js'
+
+const CLIENT_ID = 'expandai-cli'
+const OAUTH_AUTHORIZE_ENDPOINT = '/api/auth/oauth2/authorize'
+const OAUTH_TOKEN_ENDPOINT = '/api/auth/oauth2/token'
+const OAUTH_SCOPE = 'openid profile email offline_access'
+const LOOPBACK_HOST = '127.0.0.1'
+const OAUTH_LOGIN_TIMEOUT = Duration.minutes(5)
+
+const DurationFromSeconds = Schema.transform(Schema.Number, Schema.DurationFromSelf, {
+	strict: true,
+	decode: Duration.seconds,
+	encode: Duration.toSeconds,
+})
+
+export class TokenResponse extends Schema.Class<TokenResponse>('BrowserOAuthTokenResponse')({
+	access_token: Schema.String,
+	refresh_token: Schema.optional(Schema.String),
+	expires_in: DurationFromSeconds,
+	token_type: Schema.String,
+	scope: Schema.optional(Schema.String),
+}) {}
+
+export class BrowserOAuthRequestFailed extends Schema.TaggedError<BrowserOAuthRequestFailed>()(
+	'BrowserOAuthRequestFailed',
+	{
+		endpoint: Schema.String,
+		error: Schema.Defect,
+		status: Schema.optional(Schema.Number),
+	},
+) {
+	get message() {
+		return `OAuth request to ${this.endpoint} failed${this.status ? ` (${this.status})` : ''}: ${Inspectable.format(this.error)}`
+	}
+}
+
+export class BrowserOAuthCallbackError extends Schema.TaggedError<BrowserOAuthCallbackError>()(
+	'BrowserOAuthCallbackError',
+	{
+		error: Schema.String,
+		errorDescription: Schema.optional(Schema.String),
+	},
+) {
+	get message() {
+		return this.errorDescription ? `${this.error}: ${this.errorDescription}` : this.error
+	}
+}
+
+export class BrowserOAuthMissingCode extends Schema.TaggedError<BrowserOAuthMissingCode>()(
+	'BrowserOAuthMissingCode',
+	{},
+) {
+	get message() {
+		return 'OAuth callback did not include an authorization code.'
+	}
+}
+
+export class BrowserOAuthStateMismatch extends Schema.TaggedError<BrowserOAuthStateMismatch>()(
+	'BrowserOAuthStateMismatch',
+	{},
+) {
+	get message() {
+		return 'OAuth callback state did not match the login request.'
+	}
+}
+
+export class BrowserOAuthLoopbackFailed extends Schema.TaggedError<BrowserOAuthLoopbackFailed>()(
+	'BrowserOAuthLoopbackFailed',
+	{
+		error: Schema.Defect,
+	},
+) {
+	get message() {
+		return `Could not start OAuth loopback server: ${Inspectable.format(this.error)}`
+	}
+}
+
+export class BrowserOAuthTimedOut extends Schema.TaggedError<BrowserOAuthTimedOut>()('BrowserOAuthTimedOut', {}) {
+	get message() {
+		return 'OAuth browser login timed out before the local callback completed.'
+	}
+}
+
+type CallbackFailure = BrowserOAuthCallbackError | BrowserOAuthMissingCode | BrowserOAuthStateMismatch
+
+interface AuthorizeUrlInput {
+	readonly apiUrl: URL
+	readonly redirectUri: URL
+	readonly state: string
+	readonly codeChallenge: string
+}
+
+interface ExchangeCodeInput {
+	readonly code: string
+	readonly redirectUri: URL
+	readonly codeVerifier: string
+}
+
+interface LoopbackServer {
+	readonly redirectUri: URL
+	readonly waitForCode: Effect.Effect<string, CallbackFailure>
+	readonly close: Effect.Effect<void>
+}
+
+function base64Url(bytes: Uint8Array): string {
+	return Buffer.from(bytes).toString('base64').replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '')
+}
+
+function createHighEntropySecret(): string {
+	return base64Url(randomBytes(32))
+}
+
+export const createCodeChallenge = Effect.fn('BrowserOAuth.createCodeChallenge')(function* (codeVerifier: string) {
+	return base64Url(createHash('sha256').update(codeVerifier).digest())
+})
+
+export const buildAuthorizeUrl = Effect.fn('BrowserOAuth.buildAuthorizeUrl')(function* ({
+	apiUrl,
+	redirectUri,
+	state,
+	codeChallenge,
+}: AuthorizeUrlInput) {
+	const authorizeUrl = new URL(OAUTH_AUTHORIZE_ENDPOINT, apiUrl)
+	authorizeUrl.searchParams.set('response_type', 'code')
+	authorizeUrl.searchParams.set('client_id', CLIENT_ID)
+	authorizeUrl.searchParams.set('redirect_uri', redirectUri.toString())
+	authorizeUrl.searchParams.set('scope', OAUTH_SCOPE)
+	authorizeUrl.searchParams.set('code_challenge', codeChallenge)
+	authorizeUrl.searchParams.set('code_challenge_method', 'S256')
+	authorizeUrl.searchParams.set('state', state)
+	return authorizeUrl
+})
+
+function respond(response: ServerResponse, status: number, body: string): void {
+	response.writeHead(status, { 'content-type': 'text/html; charset=utf-8' })
+	response.end(body)
+}
+
+function validateCallback(request: IncomingMessage, expectedState: string): string {
+	const callbackUrl = new URL(request.url ?? '/', `http://${LOOPBACK_HOST}`)
+	const error = callbackUrl.searchParams.get('error')
+	if (error !== null) {
+		throw new BrowserOAuthCallbackError({
+			error,
+			errorDescription: callbackUrl.searchParams.get('error_description') ?? undefined,
+		})
+	}
+
+	if (callbackUrl.searchParams.get('state') !== expectedState) {
+		throw new BrowserOAuthStateMismatch()
+	}
+
+	const code = callbackUrl.searchParams.get('code')
+	if (code === null || code.length === 0) {
+		throw new BrowserOAuthMissingCode()
+	}
+
+	return code
+}
+
+function toCallbackFailure(error: unknown): CallbackFailure {
+	if (
+		error instanceof BrowserOAuthCallbackError ||
+		error instanceof BrowserOAuthMissingCode ||
+		error instanceof BrowserOAuthStateMismatch
+	) {
+		return error
+	}
+	return new BrowserOAuthCallbackError({ error: 'server_error', errorDescription: Inspectable.format(error) })
+}
+
+function closeServer(server: Server): Effect.Effect<void> {
+	return Effect.async<void>((resume) => {
+		server.close((error) => {
+			if (error) {
+				resume(Effect.void)
+				return
+			}
+			resume(Effect.void)
+		})
+	})
+}
+
+const startLoopbackServer = Effect.fn('BrowserOAuth.startLoopbackServer')(function* (expectedState: string) {
+	return yield* Effect.async<LoopbackServer, BrowserOAuthLoopbackFailed>((resume) => {
+		let settled = false
+		let resolveCode: (code: string) => void = () => undefined
+		let rejectCode: (error: CallbackFailure) => void = () => undefined
+		const codePromise = new Promise<string>((resolve, reject) => {
+			resolveCode = resolve
+			rejectCode = (error) => reject(error)
+		})
+
+		const server = createServer((request, response) => {
+			const requestUrl = new URL(request.url ?? '/', `http://${LOOPBACK_HOST}`)
+			if (requestUrl.pathname !== '/callback') {
+				respond(response, 404, 'Not found')
+				return
+			}
+
+			if (settled) {
+				respond(response, 409, 'OAuth callback already handled.')
+				return
+			}
+			settled = true
+
+			try {
+				const code = validateCallback(request, expectedState)
+				respond(response, 200, 'Authentication complete. You can close this tab.')
+				resolveCode(code)
+			} catch (error) {
+				respond(response, 400, 'Authentication failed. Return to the terminal and try again.')
+				rejectCode(toCallbackFailure(error))
+			}
+		})
+
+		server.once('error', (error) => {
+			resume(Effect.fail(new BrowserOAuthLoopbackFailed({ error })))
+		})
+
+		server.listen(0, LOOPBACK_HOST, () => {
+			const address = server.address()
+			if (address === null || typeof address === 'string') {
+				resume(Effect.fail(new BrowserOAuthLoopbackFailed({ error: 'loopback server did not report a port' })))
+				return
+			}
+
+			resume(
+				Effect.succeed({
+					redirectUri: new URL(`http://${LOOPBACK_HOST}:${address.port}/callback`),
+					waitForCode: Effect.tryPromise({
+						try: () => codePromise,
+						catch: toCallbackFailure,
+					}),
+					close: closeServer(server),
+				}),
+			)
+		})
+	})
+})
+
+export class BrowserOAuthService extends Effect.Service<BrowserOAuthService>()('@expandai/cli/BrowserOAuthService', {
+	dependencies: [NodeHttpClient.layer, ConfigManager.Default],
+	effect: Effect.gen(function* () {
+		const httpClient = yield* HttpClient.HttpClient
+		const configManager = yield* ConfigManager
+
+		const exchangeToken = Effect.fn('BrowserOAuthService.exchangeToken')(function* (
+			form: ReadonlyArray<readonly [string, string]>,
+		) {
+			const apiUrl = yield* configManager.getApiUrl()
+			const resource = apiUrl.toString()
+			const request = HttpClientRequest.post(new URL(OAUTH_TOKEN_ENDPOINT, apiUrl)).pipe(
+				HttpClientRequest.bodyUrlParams([...form, ['resource', resource]]),
+			)
+
+			return yield* httpClient.execute(request).pipe(
+				Effect.flatMap(
+					HttpClientResponse.matchStatus({
+						'200': (response) => HttpClientResponse.schemaBodyJson(TokenResponse)(response),
+						orElse: (response) =>
+							response.text.pipe(
+								Effect.flatMap((body) =>
+									Effect.fail(
+										new BrowserOAuthRequestFailed({
+											endpoint: OAUTH_TOKEN_ENDPOINT,
+											status: response.status,
+											error: body,
+										}),
+									),
+								),
+							),
+					}),
+				),
+				Effect.catchTags({
+					RequestError: (error) =>
+						Effect.fail(new BrowserOAuthRequestFailed({ endpoint: OAUTH_TOKEN_ENDPOINT, error })),
+					ResponseError: (error) =>
+						Effect.fail(new BrowserOAuthRequestFailed({ endpoint: OAUTH_TOKEN_ENDPOINT, error })),
+					ParseError: (error) => Effect.fail(new BrowserOAuthRequestFailed({ endpoint: OAUTH_TOKEN_ENDPOINT, error })),
+				}),
+			)
+		})
+
+		const exchangeCode = Effect.fn('BrowserOAuthService.exchangeCode')(function* ({
+			code,
+			redirectUri,
+			codeVerifier,
+		}: ExchangeCodeInput) {
+			return yield* exchangeToken([
+				['grant_type', 'authorization_code'],
+				['client_id', CLIENT_ID],
+				['code', code],
+				['redirect_uri', redirectUri.toString()],
+				['code_verifier', codeVerifier],
+			])
+		})
+
+		const refreshToken = Effect.fn('BrowserOAuthService.refreshToken')(function* (refreshToken: string) {
+			return yield* exchangeToken([
+				['grant_type', 'refresh_token'],
+				['client_id', CLIENT_ID],
+				['refresh_token', refreshToken],
+			])
+		})
+
+		const saveToken = Effect.fn('BrowserOAuthService.saveToken')(function* (tokenResponse: TokenResponse) {
+			const now = yield* DateTime.now
+			const expiresAt = DateTime.addDuration(now, tokenResponse.expires_in)
+
+			yield* configManager.updateConfig({
+				authMethod: OAuthConfig.make({
+					accessToken: Redacted.make(tokenResponse.access_token),
+					refreshToken:
+						tokenResponse.refresh_token === undefined ? undefined : Redacted.make(tokenResponse.refresh_token),
+					expiresAt,
+				}),
+			})
+		})
+
+		const login = Effect.fn('BrowserOAuthService.login')(function* <R>(
+			openAuthorizeUrl: (authorizeUrl: URL) => Effect.Effect<void, unknown, R>,
+		) {
+			const codeVerifier = createHighEntropySecret()
+			const state = createHighEntropySecret()
+			const codeChallenge = yield* createCodeChallenge(codeVerifier)
+			const loopback = yield* startLoopbackServer(state)
+			const apiUrl = yield* configManager.getApiUrl()
+			const authorizeUrl = yield* buildAuthorizeUrl({
+				apiUrl,
+				redirectUri: loopback.redirectUri,
+				state,
+				codeChallenge,
+			})
+
+			const code = yield* openAuthorizeUrl(authorizeUrl).pipe(
+				Effect.zipRight(loopback.waitForCode),
+				Effect.timeoutFail({
+					duration: OAUTH_LOGIN_TIMEOUT,
+					onTimeout: () => new BrowserOAuthTimedOut(),
+				}),
+				Effect.ensuring(loopback.close),
+			)
+			const token = yield* exchangeCode({ code, redirectUri: loopback.redirectUri, codeVerifier })
+			if (token === undefined) {
+				return yield* new BrowserOAuthRequestFailed({
+					endpoint: OAUTH_TOKEN_ENDPOINT,
+					error: 'OAuth token endpoint returned an empty response body',
+				})
+			}
+			yield* saveToken(token)
+		})
+
+		return { exchangeCode, refreshToken, saveToken, login } as const
+	}),
+}) {}

package/src/Commands/Fetch.ts

@@ -0,0 +1,157 @@
+import { Args, Command, HelpDoc, Options } from '@effect/cli'
+import { DEFAULT_PLAYGROUND_HOST, resolvePlaygroundHost } from '@expandai/sdk/Playground'
+import { Console, Effect, Match, Option, Schema, String } from 'effect'
+import { ApiClient } from '../ApiClient.js'
+import { renderSnippets } from '../Snippets.js'
+
+export class MarkdownUnavailable extends Schema.TaggedError<MarkdownUnavailable>()('MarkdownUnavailable', {
+	url: Schema.String,
+}) {
+	get message() {
+		return `No markdown content was returned for ${this.url}`
+	}
+}
+
+export class SnippetsUnavailable extends Schema.TaggedError<SnippetsUnavailable>()('SnippetsUnavailable', {
+	url: Schema.String,
+	query: Schema.String,
+}) {
+	get message() {
+		return `No snippets were returned for ${this.url} matching '${this.query}'`
+	}
+}
+
+// `Options.text('format').pipe(Options.withDefault('text'))` is optional, so
+// when the user types `expandai fetch --format` (no value) the parser falls
+// through to the default and `--format` is fed to the URL positional. WHATWG's
+// URL parser accepts `https://--format` as a host-only URL, so without this
+// guard the bogus value reaches the API. Reject flag-looking input up front,
+// and require a hostname with a dot (or `localhost`) so `fetch help` etc. fail
+// here with a clear message instead of via the API's schema decoder.
+//
+// `Args.mapEffect` is preferred over `Args.withSchema` because the latter
+// renders failures with `ParseResult.TreeFormatter`, which dumps the full
+// schema-decode trace.
+export const parseUrlArg = Effect.fn('Fetch.parseUrlArg')(function* (raw: string) {
+	if (raw.startsWith('-')) {
+		return yield* Effect.fail(HelpDoc.p(`Missing argument <url> (received '${raw}')`))
+	}
+	const candidate = raw.startsWith('http://') || raw.startsWith('https://') ? raw : `https://${raw}`
+	const parsed = yield* Effect.try({
+		try: () => new URL(candidate),
+		catch: () => HelpDoc.p(`Invalid URL '${raw}'`),
+	})
+	if (!parsed.hostname.includes('.') && parsed.hostname !== 'localhost') {
+		return yield* Effect.fail(HelpDoc.p(`URL must contain a valid domain (got '${raw}')`))
+	}
+	return parsed
+})
+
+const url = Args.text({ name: 'url' }).pipe(Args.mapEffect(parseUrlArg))
+
+const format = Options.text('format').pipe(
+	Options.withDefault('text'),
+	Options.withDescription('Output format (text or json)'),
+	Options.withSchema(Schema.Literal('text', 'json')),
+)
+
+const search = Options.text('search').pipe(
+	Options.optional,
+	Options.withDescription('Semantic search query. Returns relevant snippets instead of markdown.'),
+)
+
+const maxResults = Options.integer('max-results').pipe(
+	Options.withDefault(5),
+	Options.withDescription('Maximum snippets to return when using --search (default: 5)'),
+	Options.withSchema(Schema.Int.pipe(Schema.greaterThanOrEqualTo(1), Schema.lessThanOrEqualTo(50))),
+)
+
+const minScore = Options.float('min-score').pipe(
+	Options.withDefault(0.6),
+	Options.withDescription('Minimum snippet relevance score from 0 to 1 when using --search (default: 0.6)'),
+	Options.withSchema(Schema.Number.pipe(Schema.greaterThanOrEqualTo(0), Schema.lessThanOrEqualTo(1))),
+)
+
+const fetchConfig = {
+	url,
+	format,
+	search,
+	maxResults,
+	minScore,
+}
+
+interface FetchCommandConfig {
+	readonly url: URL
+	readonly format: 'text' | 'json'
+	readonly search: Option.Option<string>
+	readonly maxResults: number
+	readonly minScore: number
+}
+
+export const FetchCommand: Command.Command<'fetch', never, unknown, FetchCommandConfig> = Command.make(
+	'fetch',
+	fetchConfig,
+).pipe(
+	Command.withDescription('Fetch content from a URL as markdown or snippets'),
+	Command.withHandler(
+		Effect.fnUntraced(function* ({ format, maxResults, minScore, search, url }) {
+			const client = yield* ApiClient
+			const query = Option.getOrUndefined(search)
+			const fetchRequest =
+				query === undefined
+					? {
+							params: {},
+							payload: {
+								url: url.toString(),
+								include: { markdown: true },
+							},
+						}
+					: {
+							params: {},
+							payload: {
+								url: url.toString(),
+								include: { markdown: true, json: true },
+								search: {
+									query,
+									maxResults,
+									minScore,
+								},
+							},
+						}
+
+			const output =
+				format === 'text' && query === undefined
+					? yield* client
+							.fetchFetch(fetchRequest)
+							.pipe(
+								Effect.flatMap((markdown) =>
+									String.isNonEmpty(markdown)
+										? Effect.succeed(markdown)
+										: Effect.fail(new MarkdownUnavailable({ url: url.toString() })),
+								),
+							)
+					: yield* client.fetchFetchResult(fetchRequest).pipe(
+							Effect.flatMap((fetched) =>
+								Match.value(format).pipe(
+									Match.when('text', () => {
+										const snippets = fetched.data?.search?.snippets ?? []
+										return snippets.length === 0
+											? Effect.fail(new SnippetsUnavailable({ url: url.toString(), query: query ?? '' }))
+											: Effect.succeed(
+													renderSnippets(
+														fetched.meta.snapshotId,
+														resolvePlaygroundHost(fetched.meta.playground, DEFAULT_PLAYGROUND_HOST),
+														snippets,
+													),
+												)
+									}),
+									Match.when('json', () => Schema.encode(Schema.parseJson(Schema.Unknown, { space: 2 }))(fetched)),
+									Match.exhaustive,
+								),
+							),
+						)
+
+			yield* Console.log(output)
+		}, Effect.provide(ApiClient.Default)),
+	),
+)

package/src/Commands/Hook.ts

@@ -0,0 +1,48 @@
+import { Args, Command } from '@effect/cli'
+import { Effect } from 'effect'
+import { ClaudeHook } from '../Hook/Claude.js'
+import { OpencodeHook } from '../Hook/Opencode.js'
+import { HookInstaller } from '../Install/Hook.js'
+
+const ClaudeRunCommand = Command.make('claude-code').pipe(
+	Command.withDescription('Run the Claude Code WebFetch hook protocol over stdio'),
+	Command.withHandler(() => Effect.flatMap(ClaudeHook, (hook) => hook.runProtocol())),
+)
+
+const OpencodeRunCommand = Command.make('opencode').pipe(
+	Command.withDescription('Run the OpenCode webfetch plugin protocol over stdio'),
+	Command.withHandler(() => Effect.flatMap(OpencodeHook, (hook) => hook.runProtocol())),
+)
+
+const hostArg = Args.choice([
+	['claude-code', 'claude-code' as const],
+	['opencode', 'opencode' as const],
+])
+const scopeArg = Args.choice([
+	['global', 'global' as const],
+	['project', 'project' as const],
+])
+
+const InstallSubCommand = Command.make('install', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Install the expandai MCP server + webfetch hook for the chosen host + scope'),
+	Command.withHandler(({ host, scope }) =>
+		Effect.flatMap(HookInstaller, (installer) => installer.install(host, scope)),
+	),
+)
+
+const UninstallSubCommand = Command.make('uninstall', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Remove the expandai MCP server + webfetch hook for the chosen host + scope'),
+	Command.withHandler(({ host, scope }) =>
+		Effect.flatMap(HookInstaller, (installer) => installer.uninstall(host, scope)),
+	),
+)
+
+export const HumanHookCommand = Command.make('hook').pipe(
+	Command.withDescription('expandai hooks for AI coding assistants'),
+	Command.withSubcommands([ClaudeRunCommand, OpencodeRunCommand, InstallSubCommand, UninstallSubCommand]),
+)
+
+export const AgentHookCommand = Command.make('hook').pipe(
+	Command.withDescription('expandai hooks for AI coding assistants'),
+	Command.withSubcommands([ClaudeRunCommand, OpencodeRunCommand]),
+)

package/src/Commands/Mcp.ts

@@ -0,0 +1,30 @@
+import { Args, Command } from '@effect/cli'
+import { Effect } from 'effect'
+import { Mcp } from '../Install/Mcp.js'
+
+const hostArg = Args.choice([
+	['claude-code', 'claude-code' as const],
+	['cursor', 'cursor' as const],
+	['opencode', 'opencode' as const],
+	['codex', 'codex' as const],
+])
+
+const scopeArg = Args.choice([
+	['global', 'global' as const],
+	['project', 'project' as const],
+])
+
+export const InstallSubCommand = Command.make('install', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Install the expandai MCP server into the chosen host + scope (e.g. `claude-code global`)'),
+	Command.withHandler(
+		Effect.fnUntraced(function* ({ host, scope }) {
+			const mcp = yield* Mcp
+			yield* mcp.install(host, scope)
+		}),
+	),
+)
+
+export const UninstallSubCommand = Command.make('uninstall', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Remove the expandai MCP server from the chosen host + scope'),
+	Command.withHandler(({ host, scope }) => Effect.flatMap(Mcp, (mcp) => mcp.uninstall(host, scope))),
+)

package/src/Commands/McpRun.ts

@@ -0,0 +1,25 @@
+import { McpServer } from '@effect/ai'
+import { Command, Options } from '@effect/cli'
+import { NodeSink, NodeStream } from '@effect/platform-node'
+import { Effect, Layer } from 'effect'
+import { makeServerLayer, ServerInfo } from '../Mcp/Server.js'
+
+const includeDocsOption = Options.boolean('docs').pipe(
+	Options.withDefault(false),
+	Options.withDescription('Expose documentation resources alongside tools'),
+)
+
+export const McpRunCommand = Command.make('run', { includeDocs: includeDocsOption }).pipe(
+	Command.withDescription('Run the expandai MCP server over stdio'),
+	Command.withHandler(
+		Effect.fnUntraced(function* ({ includeDocs }) {
+			const McpLayer = McpServer.layerStdio({
+				...ServerInfo,
+				stdin: NodeStream.stdin,
+				stdout: NodeSink.stdout,
+			}).pipe(Layer.provide(makeServerLayer({ includeDocs })))
+
+			return yield* Layer.launch(McpLayer)
+		}),
+	),
+)