expandai 0.0.4 → 0.0.6

package/src/Hook/Claude.ts

@@ -1,81 +0,0 @@
-import { NodeStream } from '@effect/platform-node'
-import { Console, Effect, Schema, String } from 'effect'
-import { ApiClient } from '../ApiClient.js'
-import { MarkdownUnavailable } from '../Commands/Fetch.js'
-import { HookProtocolFailed, StdinReadError } from './Errors.js'
-import { withSnapshotNote } from './SnapshotNote.js'
-
-/**
- * Runner for `expandai hook claude-code`. Reads a Claude Code PreToolUse
- * payload from stdin, fetches the requested URL via expand.ai, and writes
- * a `hookSpecificOutput` payload that substitutes the markdown for what
- * WebFetch would have produced.
- *
- * Substitution mechanism: `permissionDecision: "deny"` blocks the WebFetch,
- * and the page markdown is delivered via `additionalContext` (the documented
- * channel for injecting page content). `permissionDecisionReason` carries
- * a short label only — the agent SDK has no documented cap on it, but
- * `additionalContext` is the semantically correct field for the body.
- */
-
-const WEBFETCH_TOOL_NAME = 'WebFetch'
-
-class WebFetchToolInput extends Schema.Class<WebFetchToolInput>('WebFetchToolInput')({
-	url: Schema.String,
-	prompt: Schema.optional(Schema.String),
-}) {}
-
-class PreToolUseHookPayload extends Schema.Class<PreToolUseHookPayload>('PreToolUseHookPayload')({
-	hook_event_name: Schema.Literal('PreToolUse'),
-	tool_name: Schema.String,
-	tool_input: WebFetchToolInput,
-}) {}
-
-const decodeHookPayload = Schema.decode(Schema.parseJson(PreToolUseHookPayload))
-const encodeHookOutput = Schema.encode(Schema.parseJson(Schema.Unknown))
-
-const readStdin = NodeStream.toString(() => process.stdin, {
-	onFailure: (error) => new StdinReadError({ error }),
-	encoding: 'utf8',
-})
-
-export class ClaudeHook extends Effect.Service<ClaudeHook>()('@expandai/cli/Hook/Claude', {
-	dependencies: [ApiClient.Default],
-	effect: Effect.gen(function* () {
-		const apiClient = yield* ApiClient
-
-		const runProtocol = Effect.fn('ClaudeHook.runProtocol')(function* () {
-			const raw = yield* readStdin.pipe(Effect.mapError((error) => new HookProtocolFailed({ error })))
-			const payload = yield* decodeHookPayload(raw).pipe(Effect.mapError((error) => new HookProtocolFailed({ error })))
-
-			// Defensive — settings.json matcher already scopes us to WebFetch.
-			if (payload.tool_name !== WEBFETCH_TOOL_NAME) return
-
-			const url = payload.tool_input.url
-			yield* Effect.gen(function* () {
-				// Object mode (`/v1/fetch/json`) over markdown mode so the response carries
-				// `meta.snapshotId` — the handle the agent uses to search this same capture
-				// via `fetch_search` instead of fetching the URL again.
-				const result = yield* apiClient.fetchFetchResult({
-					params: {},
-					payload: { url, include: { markdown: true } },
-				})
-				if (String.isEmpty(result.markdown)) {
-					return yield* new MarkdownUnavailable({ url })
-				}
-
-				const output = {
-					hookSpecificOutput: {
-						hookEventName: 'PreToolUse',
-						permissionDecision: 'deny',
-						permissionDecisionReason: `Fetched by expand.ai instead — the captured page follows, with evidence ids for citing it. Do not retry this URL.`,
-						additionalContext: withSnapshotNote(result.markdown, result.meta.snapshotId, result.meta.playground),
-					},
-				}
-				yield* Console.log(yield* encodeHookOutput(output))
-			}).pipe(Effect.mapError((error) => new HookProtocolFailed({ error, url })))
-		})
-
-		return { runProtocol } as const
-	}),
-}) {}

package/src/Hook/Errors.ts

@@ -1,19 +0,0 @@
-import { Schema } from 'effect'
-
-export class StdinReadError extends Schema.TaggedError<StdinReadError>()('StdinReadError', {
-	error: Schema.Defect,
-}) {
-	get message() {
-		return 'Failed to read hook payload from stdin.'
-	}
-}
-
-export class HookProtocolFailed extends Schema.TaggedError<HookProtocolFailed>()('HookProtocolFailed', {
-	error: Schema.Defect,
-	url: Schema.optional(Schema.String),
-}) {
-	get message() {
-		const inner = this.error instanceof Error ? this.error.message : 'Hook protocol failed.'
-		return this.url ? `${inner} (url: ${this.url})` : inner
-	}
-}

package/src/Hook/Opencode.ts

@@ -1,58 +0,0 @@
-import { NodeStream } from '@effect/platform-node'
-import { Console, Effect, Schema, String } from 'effect'
-import { ApiClient } from '../ApiClient.js'
-import { MarkdownUnavailable } from '../Commands/Fetch.js'
-import { HookProtocolFailed, StdinReadError } from './Errors.js'
-import { withSnapshotNote } from './SnapshotNote.js'
-
-/**
- * Runner for `expandai hook opencode`. Reads `{ url }` from stdin (sent by
- * the OpenCode plugin), fetches via expand.ai, and writes `{ markdown }`
- * to stdout for the plugin to splice back into webfetch's result.
- */
-
-class ProtocolInput extends Schema.Class<ProtocolInput>('OpencodeWebfetchInput')({
-	url: Schema.String,
-}) {}
-
-const decodeProtocolInput = Schema.decode(Schema.parseJson(ProtocolInput))
-const encodeProtocolOutput = Schema.encode(Schema.parseJson(Schema.Unknown))
-
-const readStdin = NodeStream.toString(() => process.stdin, {
-	onFailure: (error) => new StdinReadError({ error }),
-	encoding: 'utf8',
-})
-
-export class OpencodeHook extends Effect.Service<OpencodeHook>()('@expandai/cli/Hook/Opencode', {
-	dependencies: [ApiClient.Default],
-	effect: Effect.gen(function* () {
-		const apiClient = yield* ApiClient
-
-		const runProtocol = Effect.fn('OpencodeHook.runProtocol')(function* () {
-			const raw = yield* readStdin.pipe(Effect.mapError((error) => new HookProtocolFailed({ error })))
-			const payload = yield* decodeProtocolInput(raw).pipe(
-				Effect.mapError((error) => new HookProtocolFailed({ error })),
-			)
-			const url = payload.url
-
-			yield* Effect.gen(function* () {
-				// Object mode (`/v1/fetch/json`) over markdown mode so the response carries
-				// `meta.snapshotId` — the handle the agent uses to search this same capture
-				// via `fetch_search` instead of fetching the URL again. The note rides inside
-				// `markdown`, so the installed plugin needs no protocol change.
-				const result = yield* apiClient.fetchFetchResult({
-					params: {},
-					payload: { url, include: { markdown: true } },
-				})
-				if (String.isEmpty(result.markdown)) {
-					return yield* new MarkdownUnavailable({ url })
-				}
-
-				const markdown = withSnapshotNote(result.markdown, result.meta.snapshotId, result.meta.playground)
-				yield* Console.log(yield* encodeProtocolOutput({ markdown }))
-			}).pipe(Effect.mapError((error) => new HookProtocolFailed({ error, url })))
-		})
-
-		return { runProtocol } as const
-	}),
-}) {}

package/src/Hook/SnapshotNote.ts

@@ -1,66 +0,0 @@
-import { String } from 'effect'
-
-/**
- * Prepends a short note to fetched markdown carrying the snapshot handle, the public
- * playground link, and the citation contract. Both the Claude Code and OpenCode hooks
- * inject this so the surfaced guidance stays identical.
- *
- * The citation rules are stated here rather than only in the onboarding guide or
- * `SKILL.md`: the guide is read once during setup, and a skill may not be loaded in the
- * session that happens to fetch. This note is the only instruction guaranteed to be in
- * context at the moment the page arrives, so an answer that cites nothing — or cites the
- * bare capture URL, which is not auditable — traces back to what is written here.
- */
-const FRONT_MATTER_PLAYGROUND = /^playground:\s*"?([^"\n]+)"?\s*$/mu
-
-/**
- * Citation guidance for `expandai fetch` text output consumed by an agent. The plain
- * command is a third fetch path alongside the hook and the MCP tools — an agent that
- * shells out to it used to receive evidence ids with nothing telling it to cite them,
- * and answered uncited. Humans at a TTY do not need this, so callers gate on that.
- *
- * Returns the markdown unchanged when no playground URL is present, rather than
- * emitting an instruction the reader cannot follow.
- */
-export function withCitationFooter(markdown: string): string {
-	const playgroundUrl = FRONT_MATTER_PLAYGROUND.exec(markdown)?.[1]?.trim()
-	if (playgroundUrl === undefined || playgroundUrl.length === 0) return markdown
-	const footer = String.stripMargin(`
-		|---
-		|
-		|> Cite what you take from this page. Evidence ids are stamped next to the text they
-		|> belong to, written as \`{1199}\`. End your answer with:
-		|>
-		|> **Sources**
-		|> [1] [<page title>](${playgroundUrl}?id=<evidence id>)
-		|>
-		|> One marker per sentence, numbered in order. Never invent an evidence id, and never
-		|> reuse an id from different text. A link without \`?id=\` is not a citation, so if the
-		|> sentence you want carries no id, quote one that does or say the capture has none —
-		|> never fall back to linking the original page.`)
-	return `${markdown.trimEnd()}\n\n${footer}\n`
-}
-
-export function withSnapshotNote(markdown: string, snapshotId: string, playgroundUrl: string): string {
-	const note = String.stripMargin(`
-		|> Fetched via expand.ai (snapshot \`${snapshotId}\`). Capture: ${playgroundUrl}
-		|>
-		|> Cite every claim you take from this page. The body below stamps an evidence id next
-		|> to the text it belongs to, written as \`{1199}\`. For each sentence you use, take the
-		|> id nearest that text and end your answer with:
-		|>
-		|> **Sources**
-		|> [1] [<page title>](${playgroundUrl}?id=<evidence id>)
-		|>
-		|> Number the markers \`[1]\`, \`[2]\`, … in the order they appear, one per sentence.
-		|> Never invent an evidence id, and never reuse an id from different text.
-		|> A bare capture link without \`?id=\` is not a citation — the reader cannot
-		|> check the sentence against the page. If the sentence you want carries no id, quote
-		|> one that does, or say the capture has none. Never fall back to the original page URL.
-		|>
-		|> To extract specific passages, search the snapshot by handle — call the \`fetch_search\`
-		|> tool with \`snapshotId: "${snapshotId}"\`, or run \`expandai search ${snapshotId} "<query>"\`.
-		|> Each snippet returns a \`citationUrl\` that already carries the right \`?id=\`.
-		|> Do not fetch this URL again.`)
-	return `${note}\n\n---\n\n${markdown}`
-}

package/src/Init/ClaudeAdapter.ts

@@ -1,191 +0,0 @@
-import { Command, CommandExecutor } from '@effect/platform'
-import { NodeCommandExecutor } from '@effect/platform-node'
-import { Config, Effect, Layer, Schema, Stream } from 'effect'
-import { CLI_VERSION } from '../Version.js'
-import { CLAUDE_PROFILE_VERSION, ClaudeProfile, type ClaudeProfileInspection } from './ClaudeProfile.js'
-import type { InitScope } from './Domain.js'
-import { HarnessConfigurationError, type HarnessInspection, HarnessInspectionError } from './HarnessAdapter.js'
-import { MutationTransaction } from './MutationTransaction.js'
-
-export class IncompatibleClaudeProfileVersionError extends Schema.TaggedError<IncompatibleClaudeProfileVersionError>()(
-	'IncompatibleClaudeProfileVersionError',
-	{
-		executingVersion: Schema.String,
-		requiredVersion: Schema.String,
-	},
-) {
-	get message() {
-		return `Executing CLI ${this.executingVersion} is incompatible with Claude profile ${this.requiredVersion}`
-	}
-}
-
-export class ClaudeProfilePolicyBlockedError extends Schema.TaggedError<ClaudeProfilePolicyBlockedError>()(
-	'ClaudeProfilePolicyBlockedError',
-	{
-		policyBlock: Schema.String,
-	},
-) {
-	get message() {
-		return `Claude Code policy blocks profile configuration: ${this.policyBlock}`
-	}
-}
-
-export class ClaudeAdapterOperationError extends Schema.TaggedError<ClaudeAdapterOperationError>()(
-	'ClaudeAdapterOperationError',
-	{
-		code: Schema.Literal('inspection_failed', 'configuration_failed'),
-	},
-) {
-	get message() {
-		return this.code === 'inspection_failed'
-			? 'Claude Code profile inspection failed'
-			: 'Claude Code profile configuration failed'
-	}
-}
-
-const PORTABLE_PROBE_TIMEOUT = '5 seconds'
-
-interface ClaudeRuntimeProbeContract {
-	readonly executingVersion: string
-	readonly portableCommandAvailable: Effect.Effect<boolean, unknown>
-}
-
-const makeClaudeRuntimeProbe = Effect.gen(function* () {
-	const commandExecutor = yield* CommandExecutor.CommandExecutor
-	const searchPath = yield* Config.string('PATH').pipe(Config.withDefault(''))
-	const portableCommandAvailable = Effect.scoped(
-		Effect.gen(function* () {
-			const command = Command.make('expandai', '--version').pipe(
-				// Version probing must not persist telemetry state or emit a request in
-				// the child. Keep the remaining environment intact while making PATH
-				// injectable for fixture verification.
-				Command.env({ ...process.env, EXPANDAI_NO_TELEMETRY: '1', PATH: searchPath }),
-				Command.stdout('pipe'),
-				Command.stderr('pipe'),
-			)
-			const child = yield* commandExecutor.start(command)
-			const [stdout, , exitCode] = yield* Effect.all(
-				[child.stdout.pipe(Stream.decodeText(), Stream.mkString), child.stderr.pipe(Stream.runDrain), child.exitCode],
-				{ concurrency: 'unbounded' },
-			)
-			return exitCode === 0 && stdout.trim() === CLI_VERSION
-		}),
-	).pipe(
-		// A shim on PATH that never exits would otherwise hang setup forever. This
-		// probe only decides a "restart your harness" hint, so a slow answer is
-		// worth no more than a missing one. `Effect.scoped` above reaps the child.
-		Effect.timeoutFail({
-			duration: PORTABLE_PROBE_TIMEOUT,
-			onTimeout: () => new Error('expandai --version timed out'),
-		}),
-		Effect.orElseSucceed(() => false),
-	)
-	return { executingVersion: CLI_VERSION, portableCommandAvailable } satisfies ClaudeRuntimeProbeContract
-})
-
-/** Runtime facts kept separate from persisted harness commands. */
-export class ClaudeRuntimeProbe extends Effect.Service<ClaudeRuntimeProbe>()('@expandai/cli/Init/ClaudeRuntimeProbe', {
-	dependencies: [NodeCommandExecutor.layer],
-	effect: makeClaudeRuntimeProbe,
-}) {
-	/**
-	 * Not `DefaultWithoutDependencies`: that layer always reports `CLI_VERSION` and
-	 * always runs the real command probe. Tests need to pin an arbitrary executing
-	 * version and a precomputed probe result, which only a fixture layer can supply.
-	 */
-	static testLayer(options: { readonly executingVersion: string; readonly portableCommandAvailable: boolean }) {
-		return Layer.succeed(
-			ClaudeRuntimeProbe,
-			ClaudeRuntimeProbe.make({
-				executingVersion: options.executingVersion,
-				portableCommandAvailable: Effect.succeed(options.portableCommandAvailable),
-			}),
-		)
-	}
-}
-
-function projectInspection(
-	inspection: ClaudeProfileInspection,
-	portableCommandAvailable: boolean,
-	changed: boolean,
-): HarnessInspection {
-	const policyBlock = inspection.policyBlocks[0]
-	const blocked = policyBlock !== undefined
-	const reloadRequired = inspection.configured && !portableCommandAvailable
-	return {
-		configured: inspection.configured,
-		changed,
-		components: inspection.components,
-		integrationVersion: inspection.profileVersion,
-		...(policyBlock === undefined ? {} : { policyBlock }),
-		runtimeState: blocked ? 'blocked' : reloadRequired ? 'reload_required' : 'unverified',
-		nextAction: blocked
-			? 'resolve-claude-policy-block'
-			: reloadRequired
-				? 'restart-claude-code-current-path-unavailable'
-				: inspection.configured
-					? 'invoke-native-webfetch'
-					: 'configure-claude-code',
-	}
-}
-
-const makeClaudeAdapter = Effect.gen(function* () {
-	const profile = yield* ClaudeProfile
-	const transaction = yield* MutationTransaction
-	const runtime = yield* ClaudeRuntimeProbe
-
-	const inspect = Effect.fn('ClaudeAdapter.inspect')(function* (scope: InitScope) {
-		return yield* Effect.gen(function* () {
-			const inspection = yield* profile.inspect(scope)
-			const portableCommandAvailable = yield* runtime.portableCommandAvailable
-			return projectInspection(inspection, portableCommandAvailable, false)
-		}).pipe(
-			Effect.catchAllDefect(() => new ClaudeAdapterOperationError({ code: 'inspection_failed' })),
-			Effect.mapError(
-				() =>
-					new HarnessInspectionError({
-						harness: 'claude-code',
-						scope,
-						error: new ClaudeAdapterOperationError({ code: 'inspection_failed' }),
-					}),
-			),
-		)
-	})
-
-	const configure = Effect.fn('ClaudeAdapter.configure')(function* (scope: InitScope) {
-		return yield* Effect.gen(function* () {
-			if (runtime.executingVersion !== CLAUDE_PROFILE_VERSION) {
-				return yield* new IncompatibleClaudeProfileVersionError({
-					executingVersion: runtime.executingVersion,
-					requiredVersion: CLAUDE_PROFILE_VERSION,
-				})
-			}
-			const portableCommandAvailable = yield* runtime.portableCommandAvailable
-			const plan = yield* profile.plan(scope)
-			const policyBlock = plan.inspection.policyBlocks[0]
-			if (policyBlock !== undefined) return yield* new ClaudeProfilePolicyBlockedError({ policyBlock })
-			yield* transaction.run(plan.operations)
-			return projectInspection(plan.resultInspection, portableCommandAvailable, plan.changed)
-		}).pipe(
-			Effect.catchAllDefect(() => new ClaudeAdapterOperationError({ code: 'configuration_failed' })),
-			Effect.mapError(
-				(error) =>
-					new HarnessConfigurationError({
-						harness: 'claude-code',
-						scope,
-						error:
-							error instanceof IncompatibleClaudeProfileVersionError || error instanceof ClaudeProfilePolicyBlockedError
-								? error
-								: new ClaudeAdapterOperationError({ code: 'configuration_failed' }),
-					}),
-			),
-		)
-	})
-
-	return { harness: 'claude-code' as const, inspect, configure } as const
-})
-
-export class ClaudeAdapter extends Effect.Service<ClaudeAdapter>()('@expandai/cli/Init/ClaudeAdapter', {
-	dependencies: [ClaudeProfile.Default, MutationTransaction.Default, ClaudeRuntimeProbe.Default],
-	effect: makeClaudeAdapter,
-}) {}