expandai 0.0.3 → 0.0.5

package/src/Telemetry.ts

@@ -1,186 +0,0 @@
-/**
- * Anonymous usage telemetry (PostHog). Events carry a persisted machine UUID,
- * the invoking harness, and coarse feature usage — never URLs, queries,
- * keys, or tokens.
- *
- * Delivery is fire-and-forget: each capture forks into a FiberSet and `flush`
- * caps shutdown at one second, so telemetry can never block a command, delay
- * an MCP/hook payload, or write to stdout (stdout is a protocol surface).
- *
- * Settings live in the config file (`telemetry.enabled` / `distinctId` /
- * `noticeShown`). `DO_NOT_TRACK` / `EXPANDAI_NO_TELEMETRY`, or a non-default
- * effective API URL (env or config file — dev traffic), disable capture per
- * invocation without touching the file. A config file that fails to parse
- * also disables telemetry for the invocation and is never written to.
- */
-import { randomUUID } from 'node:crypto'
-import { HttpClient, HttpClientRequest } from '@effect/platform'
-import { NodeHttpClient } from '@effect/platform-node'
-import { Config, Console, Effect, FiberSet, Layer, Option } from 'effect'
-import { ConfigManager, DEFAULT_API_URL, envFlag, envLiteral } from './Config.js'
-import { Harness } from './Install/Domain.js'
-import { CLI_VERSION } from './Version.js'
-
-// Every field reads leniently (envFlag / envLiteral / plain strings) so a
-// malformed env var can never fail service construction — telemetry must
-// silently degrade, not crash the CLI.
-export const TelemetryEnvironment = Config.all({
-	// PostHog project write-only key — safe to embed as the default (it ships
-	// in every browser bundle that uses posthog-js) and only permits ingestion.
-	apiKey: Config.string('POSTHOG_API_KEY').pipe(Config.withDefault('phc_sffcV4skT33mMKmo0BenNoE7t7AghUrOugyW9qSx43B')),
-	host: Config.string('POSTHOG_HOST').pipe(Config.withDefault('https://us.i.posthog.com')),
-	doNotTrack: envFlag('DO_NOT_TRACK'),
-	noTelemetry: envFlag('EXPANDAI_NO_TELEMETRY'),
-	apiUrl: Config.string('EXPAND_API_URL').pipe(Config.option),
-	// Baked into MCP/hook configs at install time; wins over ambient signals.
-	// An unrecognized value (e.g. written by a newer installer) reads as None.
-	harnessOverride: envLiteral('EXPANDAI_HARNESS', Harness),
-	claudeCode: envFlag('CLAUDECODE'),
-	cursor: Config.string('CURSOR_TRACE_ID').pipe(Config.option, Config.map(Option.isSome)),
-	codex: Config.string('CODEX_RUN_ID').pipe(Config.option, Config.map(Option.isSome)),
-})
-
-type TelemetryEnvironment = Config.Config.Success<typeof TelemetryEnvironment>
-
-function detectHarness(environment: TelemetryEnvironment): Harness {
-	if (Option.isSome(environment.harnessOverride)) return environment.harnessOverride.value
-	if (environment.claudeCode) return 'claude-code'
-	if (environment.cursor) return 'cursor'
-	if (environment.codex) return 'codex'
-	return 'unknown'
-}
-
-const generateDistinctId = Effect.sync(() => randomUUID())
-
-// Lenient normalization for the non-default-API comparison: `new URL()` adds
-// the trailing slash a bare origin string lacks, and a value that doesn't
-// parse compares as non-default — never crash construction, and treat unknown
-// endpoints as non-production traffic.
-function normalizeApiUrl(url: string): string {
-	try {
-		return new URL(url).toString()
-	} catch {
-		return `unparseable:${url}`
-	}
-}
-
-export class Telemetry extends Effect.Service<Telemetry>()('@expandai/cli/Telemetry', {
-	dependencies: [ConfigManager.Default, NodeHttpClient.layer],
-	scoped: Effect.gen(function* () {
-		const configManager = yield* ConfigManager
-		const httpClient = yield* HttpClient.HttpClient
-		const fibers = yield* FiberSet.make()
-
-		const environment = yield* TelemetryEnvironment
-		// EXPAND_API_KEY overrides the config file for requests (see ConfigManager),
-		// so it must win here too or env-key users all report 'none'.
-		const envApiKey = yield* Config.string('EXPAND_API_KEY').pipe(Config.option, Config.map(Option.isSome))
-
-		// The config file is read best-effort: telemetry must work (or silently
-		// no-op) before login and survive an unreadable config. A parse failure
-		// disables capture for the invocation — an unreadable file must never be
-		// mistaken for an empty one, and never be written to.
-		const { config, parseFailed } = yield* configManager.readConfigFile()
-		const settings = config.telemetry
-
-		// Same env-over-file precedence as ConfigManager: a self-hosted apiUrl in
-		// the config file is dev traffic too. Deliberately not Config.url /
-		// getApiUrl — those fail on a malformed env value, and telemetry must
-		// degrade instead of crashing the CLI.
-		const effectiveApiUrl = Option.firstSomeOf([
-			environment.apiUrl,
-			Option.map(Option.fromNullable(config.apiUrl), (url) => url.toString()),
-		])
-		const nonDefaultApi = Option.match(effectiveApiUrl, {
-			onNone: () => false,
-			onSome: (url) => normalizeApiUrl(url) !== normalizeApiUrl(DEFAULT_API_URL),
-		})
-
-		const enabled =
-			!environment.doNotTrack &&
-			!environment.noTelemetry &&
-			!nonDefaultApi &&
-			!parseFailed &&
-			settings?.enabled !== false
-
-		const harness = detectHarness(environment)
-		const authMethod = envApiKey
-			? 'api-key'
-			: config.authMethod?._tag === 'ApiKey'
-				? 'api-key'
-				: config.authMethod?._tag === 'OAuth'
-					? 'oauth'
-					: 'none'
-
-		const persistNewDistinctId = Effect.fnUntraced(function* () {
-			const generated = yield* generateDistinctId
-			// Best-effort persistence — an unwritable config yields a per-run id.
-			yield* configManager.updateConfig({ telemetry: { ...settings, distinctId: generated } }).pipe(Effect.ignore)
-			return generated
-		})
-
-		// Disabled runs never write: DO_NOT_TRACK users don't get an id persisted,
-		// and after a parse failure a write would clobber the original file.
-		const distinctId = settings?.distinctId ?? (enabled ? yield* persistNewDistinctId() : yield* generateDistinctId)
-
-		const capture = Effect.fn('Telemetry.capture')(function* (
-			event: string,
-			properties: Record<string, string | number | boolean>,
-		) {
-			if (!enabled) return
-			const post = HttpClientRequest.post(`${environment.host}/i/v0/e`).pipe(
-				HttpClientRequest.bodyJson({
-					api_key: environment.apiKey,
-					event,
-					distinct_id: distinctId,
-					timestamp: new Date().toISOString(),
-					properties: {
-						$lib: 'expandai-cli',
-						$lib_version: CLI_VERSION,
-						version: CLI_VERSION,
-						harness,
-						auth_method: authMethod,
-						...properties,
-					},
-				}),
-			)
-			yield* FiberSet.run(
-				fibers,
-				post.pipe(
-					Effect.flatMap((request) => httpClient.execute(request)),
-					Effect.scoped,
-					Effect.timeout('2 seconds'),
-					Effect.ignore,
-				),
-			)
-		})
-
-		// Cap delivery at flush time so short-lived processes get events out
-		// without ever holding the process open noticeably.
-		const flush = FiberSet.awaitEmpty(fibers).pipe(Effect.timeout('1 second'), Effect.ignore)
-
-		const showNoticeIfNeeded = Effect.fn('Telemetry.showNoticeIfNeeded')(function* () {
-			if (!enabled || settings?.noticeShown === true) return
-			yield* Console.error(
-				'expandai collects anonymous usage data to improve the CLI. Opt out with `expandai telemetry disable` or EXPANDAI_NO_TELEMETRY=1.',
-			)
-			yield* configManager
-				.updateConfig({ telemetry: { ...settings, distinctId, noticeShown: true } })
-				.pipe(Effect.ignore)
-		})
-
-		return { capture, flush, showNoticeIfNeeded, enabled, distinctId } as const
-	}),
-}) {
-	/** A side-effect-free telemetry service for commands whose contract is read-only. */
-	static readonly DISABLED = Layer.succeed(
-		Telemetry,
-		Telemetry.make({
-			capture: () => Effect.void,
-			flush: Effect.void,
-			showNoticeIfNeeded: () => Effect.void,
-			enabled: false,
-			distinctId: 'disabled',
-		}),
-	)
-}

package/src/Version.ts

@@ -1,3 +0,0 @@
-// Single source of truth for the CLI version. Keep in sync with package.json —
-// the compiled binary cannot read package.json at runtime.
-export const CLI_VERSION = '0.0.3'

package/src/Xdg.ts

@@ -1,18 +0,0 @@
-import { homedir } from 'node:os'
-import { Path } from '@effect/platform'
-import { Config, Effect } from 'effect'
-
-/**
- * XDG base-directory lookup, shared by everything that persists CLI state so
- * the fallback rules cannot drift apart. The spec treats an unset and an empty
- * variable identically: fall back to `$HOME/.config`. Without the empty check,
- * `XDG_CONFIG_HOME=` resolves paths relative to the working directory — which
- * would drop credentials inside whatever project the CLI happens to run in.
- */
-export const xdgConfigDirectory = Effect.gen(function* () {
-	const path = yield* Path.Path
-	return yield* Config.string('XDG_CONFIG_HOME').pipe(
-		Config.withDefault(''),
-		Config.map((directory) => (directory.trim() === '' ? path.join(homedir(), '.config') : directory)),
-	)
-})

package/src/index.ts

@@ -1 +0,0 @@
-export * from './Mcp/Server.js'

package/src/main.ts

@@ -1,305 +0,0 @@
-#!/usr/bin/env node
-import { CliConfig, Command, ValidationError } from '@effect/cli'
-import { Terminal } from '@effect/platform'
-import { NodeContext, NodeRuntime } from '@effect/platform-node'
-import { Cause, Config, Console, Effect, Layer, Logger, LogLevel, Option, Schema, String } from 'effect'
-import { ManualAuthorization } from './Auth/ManualAuthorization.js'
-import { PendingInitStore } from './Auth/PendingInit.js'
-import { SetupGrantAuthorization } from './Auth/SetupGrantAuthorization.js'
-import { Authentication, LoginCommand, LogoutCommand, WhoamiCommand } from './Authentication.js'
-import { commandFromArgv } from './CommandPath.js'
-import { FetchCommand } from './Commands/Fetch.js'
-import { AgentHookCommand, HumanHookCommand } from './Commands/Hook.js'
-import {
-	AgentInitCommand,
-	HumanInitCommand,
-	InitTerminalInteraction,
-	preflightAgentInitArgv,
-	resolveInitExecutionMode,
-} from './Commands/Init.js'
-import { InstallSubCommand, UninstallSubCommand } from './Commands/Mcp.js'
-import { McpRunCommand } from './Commands/McpRun.js'
-import { SearchCommand } from './Commands/Search.js'
-import { SkillCommand } from './Commands/Skill.js'
-import {
-	AgentStatusCommand,
-	HumanStatusCommand,
-	preflightAgentStatusArgv,
-	resolveStatusExecutionMode,
-	StatusTerminalInteraction,
-} from './Commands/Status.js'
-import { TelemetryCommand } from './Commands/Telemetry.js'
-import { UninstallCommand } from './Commands/Uninstall.js'
-import { ConfigManager, envFlag, envLiteral } from './Config.js'
-import { ClaudeHook } from './Hook/Claude.js'
-import { OpencodeHook } from './Hook/Opencode.js'
-import { HarnessDetector } from './Init/HarnessDetector.js'
-import { HarnessRegistry } from './Init/HarnessRegistry.js'
-import { InitService } from './Init/Service.js'
-import { StatusService } from './Init/Status.js'
-import { HookInstaller } from './Install/Hook.js'
-import { Mcp } from './Install/Mcp.js'
-import { Skill as SkillInstaller } from './Install/Skill.js'
-import { Uninstall } from './Install/Uninstall.js'
-import { Telemetry } from './Telemetry.js'
-import { CLI_VERSION } from './Version.js'
-
-/**
- * Where this process is running:
- *  - 'human': interactive terminal use. Setup commands (`mcp install`, `skill install`) are visible.
- *  - 'agent': an agent host (Claude Code / Cursor / Codex) or the expandai skill is invoking
- *            the CLI. Setup commands are hidden because the integration is already wired up.
- *  - 'mcp':   the binary is serving as the MCP transport. MCP only runs in agents.
- */
-
-// envFlag / envLiteral read leniently: a malformed value (CLAUDECODE=banana,
-// EXPANDAI_CLI_CONTEXT=bogus) must degrade instead of crashing the CLI —
-// Config.option / Config.withDefault only absorb missing data, not invalid.
-const EnvironmentSignals = Config.all({
-	override: envLiteral('EXPANDAI_CLI_CONTEXT', Schema.Literal('human', 'agent')),
-	mcpTransport: Config.string('MCP_TRANSPORT').pipe(Config.option, Config.map(Option.isSome)),
-	claudeCode: envFlag('CLAUDECODE'),
-	cursor: Config.string('CURSOR_TRACE_ID').pipe(Config.option, Config.map(Option.isSome)),
-	codex: Config.string('CODEX_RUN_ID').pipe(Config.option, Config.map(Option.isSome)),
-})
-
-const detectContext = Effect.fnUntraced(function* (command: string) {
-	const initMode = resolveInitExecutionMode({
-		argv: process.argv,
-		environment: process.env,
-		stdinIsTty: process.stdin.isTTY === true,
-		stdoutIsTty: process.stdout.isTTY === true,
-	})
-	if (initMode !== undefined) return initMode === 'machine' ? ('agent' as const) : ('human' as const)
-	const statusMode = resolveStatusExecutionMode({
-		argv: process.argv,
-		environment: process.env,
-		stdinIsTty: process.stdin.isTTY === true,
-		stdoutIsTty: process.stdout.isTTY === true,
-	})
-	if (statusMode !== undefined) return statusMode === 'machine' ? ('agent' as const) : ('human' as const)
-
-	const signals = yield* EnvironmentSignals
-
-	// Installed MCP entries invoke `expandai mcp run` without any transport env
-	// var, so the resolved command is the reliable signal; MCP_TRANSPORT stays
-	// as a secondary hint for hand-written configs that set it.
-	const mcp = command === 'mcp run' || signals.mcpTransport ? Option.some('mcp' as const) : Option.none<'mcp'>()
-	// Authentication.logout uses both stdout and stdin TTY checks because Prompt
-	// reads from stdin; for context detection a non-TTY stdout alone is enough
-	// to identify a non-interactive caller.
-	const agent =
-		signals.claudeCode || signals.cursor || signals.codex || !process.stdout.isTTY
-			? Option.some('agent' as const)
-			: Option.none<'agent'>()
-
-	return Option.firstSomeOf([mcp, signals.override, agent]).pipe(Option.getOrElse(() => 'human' as const))
-})
-
-const HumanMcp = Command.make('mcp').pipe(
-	Command.withDescription('Run or install the expandai MCP server'),
-	Command.withSubcommands([McpRunCommand, InstallSubCommand, UninstallSubCommand]),
-)
-
-const AgentMcp = Command.make('mcp').pipe(
-	Command.withDescription('Run the expandai MCP server'),
-	Command.withSubcommands([McpRunCommand]),
-)
-
-const InitServiceLive = InitService.DefaultWithoutDependencies.pipe(
-	Layer.provide(
-		Layer.mergeAll(
-			Authentication.Default,
-			ManualAuthorization.Default,
-			SetupGrantAuthorization.Default,
-			HarnessRegistry.Default,
-		),
-	),
-)
-
-const StatusServiceLive = StatusService.DefaultWithoutDependencies.pipe(
-	Layer.provide(Layer.mergeAll(ConfigManager.Default, PendingInitStore.Default, HarnessRegistry.Default)),
-)
-
-const HumanCli = Command.make('expandai').pipe(
-	Command.withDescription('expand.ai CLI and MCP server'),
-	Command.withSubcommands([
-		FetchCommand,
-		SearchCommand,
-		LoginCommand,
-		WhoamiCommand,
-		LogoutCommand,
-		HumanInitCommand,
-		HumanStatusCommand,
-		UninstallCommand,
-		HumanMcp,
-		SkillCommand,
-		HumanHookCommand,
-		TelemetryCommand,
-	]),
-	Command.provide(
-		Layer.mergeAll(
-			ConfigManager.Default,
-			Authentication.Default,
-			Mcp.Default,
-			HookInstaller.Default,
-			SkillInstaller.Default,
-			Uninstall.Default,
-			ClaudeHook.Default,
-			OpencodeHook.Default,
-			InitServiceLive,
-			HarnessDetector.Default,
-			InitTerminalInteraction.Default,
-			StatusServiceLive,
-			StatusTerminalInteraction.Default,
-		),
-	),
-)
-
-const AgentCli = Command.make('expandai').pipe(
-	Command.withDescription('expand.ai CLI and MCP server'),
-	Command.withSubcommands([
-		FetchCommand,
-		SearchCommand,
-		LoginCommand,
-		WhoamiCommand,
-		LogoutCommand,
-		AgentInitCommand,
-		AgentStatusCommand,
-		// The consent step tells the user `expandai uninstall` is how to undo
-		// setup — including removing the machine-wide `WebFetch` deny rule. That
-		// text is read by an agent, so the command has to exist in this tree too;
-		// it was human-only, and an agent running it got "Invalid subcommand".
-		UninstallCommand,
-		AgentMcp,
-		AgentHookCommand,
-		TelemetryCommand,
-	]),
-	Command.provide(
-		Layer.mergeAll(
-			ConfigManager.Default,
-			Authentication.Default,
-			ClaudeHook.Default,
-			OpencodeHook.Default,
-			Mcp.Default,
-			HookInstaller.Default,
-			SkillInstaller.Default,
-			Uninstall.Default,
-			InitServiceLive,
-			HarnessDetector.Default,
-			StatusServiceLive,
-		),
-	),
-)
-
-const LoggerLive = Layer.unwrapEffect(
-	Effect.gen(function* () {
-		const isDebug = yield* Config.boolean('DEBUG').pipe(Config.withDefault(false))
-		// stdout is a protocol/data surface (hook JSON payloads, fetched
-		// markdown) — a log line ahead of the payload corrupts it for the
-		// consumer, so diagnostics go to stderr.
-		return Layer.mergeAll(
-			Logger.replace(Logger.defaultLogger, Logger.prettyLogger({ stderr: true })),
-			Logger.minimumLogLevel(isDebug ? LogLevel.All : LogLevel.Info),
-		)
-	}),
-)
-
-// Status is a read-only diagnostic contract, and `init --detect` documents itself
-// as changing nothing — the guide prints "This changes nothing:" directly above
-// it. Select the no-op service before layer acquisition so Telemetry.Default
-// cannot persist a distinct id, repair config permissions, display a notice, or
-// send a request. A brand-new HOME came back from `--detect` with a config.json
-// holding a telemetry id, which is a write however small. Other commands retain
-// the ordinary telemetry service unchanged.
-const writesNothing =
-	commandFromArgv(process.argv) === 'status' ||
-	(commandFromArgv(process.argv) === 'init' && process.argv.includes('--detect'))
-const TelemetryLive = writesNothing ? Telemetry.DISABLED : Telemetry.Default
-const Env = Layer.mergeAll(NodeContext.layer, CliConfig.layer({ showBuiltIns: false }), LoggerLive, TelemetryLive)
-
-const errorTagFromCause = (cause: Cause.Cause<unknown>): string =>
-	Cause.failureOption(cause).pipe(
-		Option.match({
-			onNone: () => 'Defect',
-			onSome: (error) =>
-				typeof error === 'object' && error !== null && '_tag' in error && typeof error._tag === 'string'
-					? error._tag
-					: 'UnknownError',
-		}),
-	)
-
-function startupOnboardingPreflightError(): string | undefined {
-	const initMode = resolveInitExecutionMode({
-		argv: process.argv,
-		environment: process.env,
-		stdinIsTty: process.stdin.isTTY === true,
-		stdoutIsTty: process.stdout.isTTY === true,
-	})
-	if (initMode === 'machine') return preflightAgentInitArgv(process.argv)
-	const statusMode = resolveStatusExecutionMode({
-		argv: process.argv,
-		environment: process.env,
-		stdinIsTty: process.stdin.isTTY === true,
-		stdoutIsTty: process.stdout.isTTY === true,
-	})
-	return statusMode === 'machine' ? preflightAgentStatusArgv(process.argv) : undefined
-}
-
-const program = Effect.gen(function* () {
-	const command = commandFromArgv(process.argv)
-	const context = yield* detectContext(command)
-	const telemetry = yield* Telemetry
-	if (context === 'human') {
-		yield* telemetry.showNoticeIfNeeded()
-	}
-	yield* telemetry.capture('cli_command_run', { command, context })
-	const cli = context === 'human' ? HumanCli : AgentCli
-	return yield* Command.run(cli, { name: 'expand.ai CLI', version: CLI_VERSION })(process.argv)
-}).pipe(
-	Effect.catchAllCause((cause) => {
-		const failure = Cause.failureOption(cause)
-		// Ctrl-C during a `Prompt` surfaces as a `QuitException` failure rather
-		// than a pure interrupt; treat it the same as an interrupt so we exit
-		// cleanly instead of printing a blank "Error: " (QuitException has no message).
-		if (Cause.isInterruptedOnly(cause) || (Option.isSome(failure) && Terminal.isQuitException(failure.value))) {
-			return Effect.void
-		}
-		// `@effect/cli` already printed a help/usage message before failing with
-		// a `ValidationError`; we only need to propagate the non-zero exit.
-		const print = Option.match(failure, {
-			onSome: (error) =>
-				ValidationError.isValidationError(error) ? Effect.void : Console.error(`Error: ${(error as Error).message}`),
-			onNone: () =>
-				Console.error(
-					String.stripMargin(`
-						|Unexpected failure:
-						|${Cause.pretty(cause)}`),
-				),
-		})
-		const debug = Effect.logDebug('Error cause').pipe(Effect.annotateLogs({ cause: Cause.pretty(cause) }))
-		const trackFailure = Effect.flatMap(Telemetry, (telemetry) =>
-			telemetry.capture('cli_command_failed', {
-				command: commandFromArgv(process.argv),
-				error_tag: errorTagFromCause(cause),
-			}),
-		)
-		return print.pipe(Effect.zipRight(debug), Effect.zipRight(trackFailure), Effect.zipRight(Effect.failCause(cause)))
-	}),
-	// Deliver any pending telemetry before the process exits; capped at 1s by
-	// Telemetry.flush so it can never hold a short-lived invocation open.
-	Effect.ensuring(Effect.flatMap(Telemetry, (telemetry) => telemetry.flush)),
-	Effect.provide(Env),
-)
-
-// disablePrettyLogger: runMain's own pretty logger writes to stdout, which
-// would put diagnostics back on the protocol/data stream LoggerLive keeps clean.
-const preflightError = startupOnboardingPreflightError()
-if (preflightError !== undefined) {
-	// This validation must finish before the Effect runtime acquires Telemetry,
-	// otherwise an invalid machine command could still create local state.
-	process.stderr.write(`${preflightError}\n`)
-	process.exitCode = 2
-} else {
-	NodeRuntime.runMain(program, { disableErrorReporting: true, disablePrettyLogger: true })
-}