opencode-effect-enforcer 0.2.0

package/skills/effect-command-executor/SKILL.md

@@ -0,0 +1,675 @@
+---
+name: effect-command-executor
+description: Spawn and manage child processes using Effect's ChildProcess module. Use this skill when running shell commands, capturing process output, piping commands, streaming long-running process output, or managing process lifecycles with scoped cleanup.
+---
+
+# Child Process Execution with Effect v4
+
+## Overview
+
+The `ChildProcess` module provides type-safe, composable process execution with automatic resource cleanup via `Scope`. Commands are AST values — built first with `make` and `pipeTo`, then executed via the `ChildProcessSpawner` service.
+
+**When to use this skill:**
+
+- Running shell commands or external programs
+- Capturing command output as string, lines, or stream
+- Piping commands together (shell pipeline equivalent)
+- Streaming output from long-running processes
+- Managing process lifecycles with scoped cleanup
+
+**Note:** This skill covers child process execution, NOT `@effect/cli` for building CLI applications.
+
+## Import Pattern
+
+```typescript
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+```
+
+Platform layer (Node.js):
+
+```typescript
+import { NodeServices } from '@effect/platform-node';
+```
+
+## Creating Commands
+
+### Template Literal Form
+
+```typescript
+import { ChildProcess } from 'effect/unstable/process';
+
+// Simple command — parsed by whitespace
+const cmd = ChildProcess.make`echo hello world`;
+
+// With interpolation — expressions become separate arguments
+const name = 'my-package';
+const cmd2 = ChildProcess.make`bun publish ${name}`;
+
+// Array expressions expand to multiple arguments
+const files = ['a.ts', 'b.ts', 'c.ts'];
+const cmd3 = ChildProcess.make`oxfmt ${files}`;
+```
+
+### Options + Template Literal Form
+
+```typescript
+import { ChildProcess } from 'effect/unstable/process';
+
+// Options object returns a tagged template function
+const cmd = ChildProcess.make({ cwd: '/tmp' })`ls -la`;
+
+const cmd2 = ChildProcess.make({
+	cwd: '/app',
+	env: { NODE_ENV: 'production' },
+	extendEnv: true
+})`node server.js`;
+```
+
+### Array Form
+
+```typescript
+import { ChildProcess } from 'effect/unstable/process';
+
+// Explicit command + args array
+const cmd = ChildProcess.make('git', ['status'], {
+	extendEnv: true,
+	stdin: 'ignore'
+});
+
+// With options
+const cmd2 = ChildProcess.make('bun', ['lint'], {
+	env: { FORCE_COLOR: '1' },
+	extendEnv: true,
+	stdin: 'ignore'
+});
+
+// Command only (no args)
+const cmd3 = ChildProcess.make('node', {
+	cwd: '/app',
+	extendEnv: true,
+	stdin: 'ignore'
+});
+```
+
+### Command Options
+
+```typescript
+import { ChildProcess } from 'effect/unstable/process';
+
+const cmd = ChildProcess.make('node', ['script.js'], {
+	// Working directory
+	cwd: '/path/to/project',
+
+	// Environment variables
+	env: { NODE_ENV: 'production', API_KEY: 'xyz' },
+
+	// Merge with process.env (default: false)
+	extendEnv: true,
+
+	// Run inside a shell (generally disadvised)
+	shell: false,
+
+	// Detach from parent (default: true on non-Windows)
+	detached: true,
+
+	// stdio configuration — use 'ignore' for non-interactive commands
+	stdin: 'ignore', // "pipe" | "inherit" | "ignore" | Stream
+	stdout: 'pipe', // "pipe" | "inherit" | "ignore" | Sink
+	stderr: 'pipe', // "pipe" | "inherit" | "ignore" | Sink
+
+	// Kill signal defaults
+	killSignal: 'SIGTERM',
+	forceKillAfter: '3 seconds',
+
+	// Additional file descriptors
+	additionalFds: {
+		fd3: { type: 'output' }, // readable by parent
+		fd4: { type: 'input' } // writable by parent
+	}
+});
+```
+
+`extendEnv` defaults to `false`. If `env` is supplied without `extendEnv: true`, it replaces the inherited child environment rather than merging with it.
+
+The `fd3`/`fd4` names above configure child-process stdio channels. They are unrelated to the `FileSystem.File.Descriptor` type removed in beta.103; process handles still expose `getInputFd(number)` and `getOutputFd(number)` for configured additional descriptors.
+
+### Combinators
+
+```typescript
+import { ChildProcess } from 'effect/unstable/process';
+
+// Set cwd (applies to all commands in a pipeline)
+const cmd = ChildProcess.make`ls -la`.pipe(ChildProcess.setCwd('/tmp'));
+
+// Set env (applies to all commands in a pipeline)
+const cmd2 = ChildProcess.make`node script.js`.pipe(
+	ChildProcess.setEnv({ NODE_ENV: 'test' })
+);
+
+// Prefix a command (e.g. `time`, `nice`, `sudo`)
+const cmd3 = ChildProcess.make`echo foo`.pipe(ChildProcess.prefix`time`);
+// executes: time echo foo
+```
+
+## Executing Commands
+
+Commands are `Effect` values: `yield*` on a command evaluates through its `Effectable` implementation, calls `ChildProcessSpawner.spawn`, and returns a `ChildProcessHandle`. `spawner.spawn` still requires `Scope`; helpers such as `string`, `lines`, and `exitCode` manage scope internally.
+
+### Get the Spawner Service
+
+```typescript
+import { Effect } from 'effect';
+import { ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	// use spawner.string, spawner.lines, spawner.spawn, etc.
+});
+```
+
+### Capture as String
+
+```typescript
+import { Effect, String } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const version = yield* spawner
+		.string(ChildProcess.make('node', ['--version']))
+		.pipe(Effect.map(String.trim));
+	// version: "v22.0.0"
+});
+```
+
+### Capture as Lines
+
+```typescript
+import { Effect } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const files = yield* spawner.lines(
+		ChildProcess.make('git', ['diff', '--name-only', 'main...HEAD'])
+	);
+	const tsFiles = files.filter((f) => f.endsWith('.ts'));
+});
+```
+
+### Progressive Output with Side Effects
+
+```typescript
+import { Effect, Stream } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	let output = '';
+	const handle = yield* spawner.spawn(
+		ChildProcess.make('bun', ['test'], {
+			extendEnv: true,
+			stdin: 'ignore'
+		})
+	);
+	yield* Stream.runForEach(Stream.decodeText(handle.all), (chunk) =>
+		Effect.sync(() => {
+			output += chunk;
+		})
+	).pipe(Effect.forkScoped);
+	const exitCode = yield* handle.exitCode;
+	return { output, exitCode };
+}).pipe(Effect.scoped);
+```
+
+Use this pattern when you need per-chunk side effects (progress reporting, streaming to UI) during command execution. `spawner.string`/`spawner.lines` cannot provide per-chunk callbacks.
+
+### Get Exit Code
+
+```typescript
+import { Effect } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const exitCode = yield* spawner.exitCode(
+		ChildProcess.make('test', ['-f', 'package.json'])
+	);
+	// exitCode: ExitCode (branded number)
+	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+		yield* Effect.fail(new Error('file not found'));
+	}
+});
+```
+
+### Stream Output (Long-Running Processes)
+
+```typescript
+import { Console, Effect, Stream } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+	// Stream lines from a command
+	yield* spawner
+		.streamLines(ChildProcess.make`tail -f /var/log/app.log`)
+		.pipe(Stream.runForEach((line) => Console.log(line)));
+
+	// Stream raw string chunks
+	yield* spawner
+		.streamString(ChildProcess.make`my-program`)
+		.pipe(Stream.runForEach((chunk) => Console.log(chunk)));
+});
+```
+
+## Process Handle (spawn)
+
+Use `spawner.spawn` when you need the process handle for interactive control, streaming output while running, or checking exit codes.
+
+```typescript
+import { Console, Effect, Stream } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+	const handle = yield* spawner.spawn(
+		ChildProcess.make('bun', ['lint'], {
+			env: { FORCE_COLOR: '1' },
+			extendEnv: true,
+			stdin: 'ignore'
+		})
+	);
+
+	// Stream combined stdout+stderr while process runs
+	yield* handle.all.pipe(
+		Stream.decodeText(),
+		Stream.splitLines,
+		Stream.runForEach((line) => Console.log(`[lint] ${line}`))
+	);
+
+	// Wait for exit
+	const exitCode = yield* handle.exitCode;
+	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+		yield* Effect.fail(new Error(`lint failed: exit ${exitCode}`));
+	}
+}).pipe(Effect.scoped); // <-- spawn requires Scope
+```
+
+### ChildProcessHandle API
+
+| Property/Method   | Type                                           | Description                                                                |
+| ----------------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
+| `pid`             | `ProcessId`                                    | Process identifier (branded number)                                        |
+| `exitCode`        | `Effect<ExitCode, PlatformError>`              | Waits for exit, returns exit code                                          |
+| `isRunning`       | `Effect<boolean, PlatformError>`               | Check if still running                                                     |
+| `kill(options?)`  | `Effect<void, PlatformError>`                  | Kill with signal; pass `{ forceKillAfter: '3 seconds' }` to ensure cleanup |
+| `stdin`           | `Sink<void, Uint8Array, never, PlatformError>` | Write to process stdin                                                     |
+| `stdout`          | `Stream<Uint8Array, PlatformError>`            | Read process stdout                                                        |
+| `stderr`          | `Stream<Uint8Array, PlatformError>`            | Read process stderr                                                        |
+| `all`             | `Stream<Uint8Array, PlatformError>`            | Interleaved stdout+stderr                                                  |
+| `getInputFd(fd)`  | `Sink<void, Uint8Array, ...>`                  | Write to additional fd                                                     |
+| `getOutputFd(fd)` | `Stream<Uint8Array, ...>`                      | Read from additional fd                                                    |
+
+## Piping Commands
+
+```typescript
+import { Effect } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+	// stdout → stdin (default)
+	const lines = yield* spawner.lines(
+		ChildProcess.make('git', [
+			'log',
+			'--pretty=format:%s',
+			'-n',
+			'20'
+		]).pipe(ChildProcess.pipeTo(ChildProcess.make('head', ['-n', '5'])))
+	);
+
+	// Pipe stderr instead of stdout
+	const errors = yield* spawner.lines(
+		ChildProcess.make`my-program`.pipe(
+			ChildProcess.pipeTo(ChildProcess.make`grep error`, {
+				from: 'stderr'
+			})
+		)
+	);
+
+	// Pipe combined stdout+stderr
+	const all = yield* spawner.lines(
+		ChildProcess.make`my-program`.pipe(
+			ChildProcess.pipeTo(ChildProcess.make`tee output.log`, {
+				from: 'all'
+			})
+		)
+	);
+});
+```
+
+## Providing the Platform Layer
+
+`ChildProcess` commands require a `ChildProcessSpawner` implementation. In Node.js:
+
+```typescript
+import { NodeServices } from '@effect/platform-node';
+import { Effect } from 'effect';
+
+// NodeServices.layer provides: ChildProcessSpawner, Crypto, FileSystem, Path, Stdio, Terminal
+const program = Effect.gen(function* () {
+	// ...
+}).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
+```
+
+Or provide just the spawner:
+
+```typescript
+import { NodeChildProcessSpawner } from '@effect/platform-node';
+
+const program = myEffect.pipe(Effect.provide(NodeChildProcessSpawner.layer));
+```
+
+## Complete Example: DevTools Service
+
+```typescript
+import { NodeServices } from '@effect/platform-node';
+import {
+	Console,
+	Effect,
+	Layer,
+	Schema,
+	Context,
+	Stream,
+	String
+} from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+class DevToolsError extends Schema.TaggedError<DevToolsError>()(
+	'DevToolsError',
+	{
+		cause: Schema.Defect()
+	}
+) {}
+
+class DevTools extends Context.Service<
+	DevTools,
+	{
+		readonly nodeVersion: Effect.Effect<string, DevToolsError>;
+		readonly recentCommitSubjects: Effect.Effect<
+			ReadonlyArray<string>,
+			DevToolsError
+		>;
+		readonly runLintFix: Effect.Effect<void, DevToolsError>;
+		changedTypeScriptFiles(
+			baseRef: string
+		): Effect.Effect<ReadonlyArray<string>, DevToolsError>;
+	}
+>()('app/DevTools') {
+	static readonly layer = Layer.effect(
+		DevTools,
+		Effect.gen(function* () {
+			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+			const nodeVersion = spawner
+				.string(ChildProcess.make('node', ['--version']))
+				.pipe(
+					Effect.map(String.trim),
+					Effect.mapError((cause) => new DevToolsError({ cause }))
+				);
+
+			const changedTypeScriptFiles = Effect.fn(
+				'DevTools.changedTypeScriptFiles'
+			)(function* (baseRef: string) {
+				yield* Effect.annotateCurrentSpan({ baseRef });
+				const files = yield* spawner
+					.lines(
+						ChildProcess.make('git', [
+							'diff',
+							'--name-only',
+							`${baseRef}...HEAD`
+						])
+					)
+					.pipe(
+						Effect.mapError((cause) => new DevToolsError({ cause }))
+					);
+				return files.filter((file) => file.endsWith('.ts'));
+			});
+
+			const recentCommitSubjects = spawner
+				.lines(
+					ChildProcess.make('git', [
+						'log',
+						'--pretty=format:%s',
+						'-n',
+						'20'
+					]).pipe(
+						ChildProcess.pipeTo(
+							ChildProcess.make('head', ['-n', '5'])
+						)
+					)
+				)
+				.pipe(Effect.mapError((cause) => new DevToolsError({ cause })));
+
+			const runLintFix = Effect.gen(function* () {
+				const handle = yield* spawner
+					.spawn(
+						ChildProcess.make('bun', ['lint'], {
+							env: { FORCE_COLOR: '1' },
+							extendEnv: true,
+							stdin: 'ignore'
+						})
+					)
+					.pipe(
+						Effect.mapError((cause) => new DevToolsError({ cause }))
+					);
+
+				yield* handle.all.pipe(
+					Stream.decodeText(),
+					Stream.splitLines,
+					Stream.runForEach((line) => Console.log(`[lint] ${line}`)),
+					Effect.mapError((cause) => new DevToolsError({ cause }))
+				);
+
+				const exitCode = yield* handle.exitCode.pipe(
+					Effect.mapError((cause) => new DevToolsError({ cause }))
+				);
+				if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+					return yield* new DevToolsError({
+						cause: new Error(
+							`bun lint failed with exit code ${exitCode}`
+						)
+					});
+				}
+			}).pipe(Effect.scoped);
+
+			return DevTools.of({
+				nodeVersion,
+				changedTypeScriptFiles,
+				recentCommitSubjects,
+				runLintFix
+			});
+		})
+	).pipe(Layer.provide(NodeServices.layer));
+}
+```
+
+## DO / DON'T
+
+### DO: Use `Effect.scoped` when calling `spawner.spawn`
+
+```typescript
+// spawn returns a handle that requires Scope for lifecycle management
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
+	// handle is automatically cleaned up when scope closes
+}).pipe(Effect.scoped);
+```
+
+### DON'T: Use `spawner.spawn` without scoping
+
+```typescript
+// Process handle leaks — no scope to manage cleanup
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
+	// ❌ no Effect.scoped — process may leak
+});
+```
+
+### DO: Use `spawner.string` / `spawner.lines` for simple output capture
+
+```typescript
+// These convenience methods handle scope internally
+const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+const output = yield* spawner.string(ChildProcess.make`echo hello`);
+const lines = yield* spawner.lines(ChildProcess.make`ls -1`);
+```
+
+### DON'T: Use `spawn` + manual stream collection when `string`/`lines` suffices
+
+```typescript
+// Unnecessarily complex for simple output capture
+const handle = yield* spawner.spawn(ChildProcess.make`echo hello`);
+const chunks = yield* Stream.runCollect(handle.stdout);
+// ❌ overkill — just use spawner.string
+```
+
+### DO: Use `Effect.mapError` to wrap `PlatformError` in domain errors
+
+```typescript
+class MyError extends Schema.TaggedError<MyError>()('MyError', {
+	cause: Schema.Defect()
+}) {}
+
+const result =
+	yield*
+	spawner
+		.string(ChildProcess.make`git status`)
+		.pipe(Effect.mapError((cause) => new MyError({ cause })));
+```
+
+### DON'T: Let `PlatformError` leak into your service API
+
+```typescript
+// ❌ exposes platform implementation details to consumers
+class MyService extends Context.Service<
+	MyService,
+	{
+		readonly status: Effect.Effect<string, PlatformError.PlatformError>; // ❌
+	}
+>()('MyService') {}
+```
+
+### DO: Check `ExitCode` with the branded constructor
+
+```typescript
+if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+	yield* Effect.fail(new Error(`command failed: ${exitCode}`));
+}
+```
+
+### DON'T: Compare exit codes as raw numbers
+
+```typescript
+// ❌ ExitCode is a branded type — direct number comparison may not work as expected
+if (exitCode !== 0) {
+	/* ... */
+}
+```
+
+### DO: Use `handle.all` for interleaved stdout+stderr
+
+```typescript
+yield*
+	handle.all.pipe(
+		Stream.decodeText(),
+		Stream.splitLines,
+		Stream.runForEach((line) => Console.log(line))
+	);
+```
+
+### DON'T: Mix `handle.stdout`/`handle.stderr` with `handle.all`
+
+```typescript
+// ❌ Using stdout/stderr alongside all may cause interleaving issues
+yield* Stream.merge(handle.stdout, handle.all).pipe(Stream.runCollect);
+```
+
+## Error Handling
+
+Child process operations fail with `PlatformError`:
+
+```typescript
+import { Effect } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+
+const program = Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+	const result = yield* spawner
+		.string(ChildProcess.make`non-existent-command`)
+		.pipe(
+			Effect.catchTag('PlatformError', (error) =>
+				Effect.succeed(`fallback: ${error.message}`)
+			)
+		);
+});
+```
+
+## Boundary Abort Signals
+
+Prefer Effect interruption as the cancellation signal between your own services. If a host API hands you an `AbortSignal`, convert it once at the outer boundary instead of threading `AbortSignal` through unrelated services.
+
+Keep process kill, timeout, and output-drain logic inside the process adapter that owns the `ChildProcessHandle`.
+
+## Bridging External Signals
+
+Use `Effect.callback` to convert an `AbortSignal` (or any event-driven API) into an Effect. The cleanup Effect removes the listener, and the already-aborted edge case is handled first:
+
+```typescript
+import { Effect } from 'effect';
+
+const fromAbortSignal = (signal: AbortSignal) =>
+	Effect.callback<void>((resume) => {
+		if (signal.aborted) return resume(Effect.void);
+		const handler = () => resume(Effect.void);
+		signal.addEventListener('abort', handler, { once: true });
+		return Effect.sync(() => signal.removeEventListener('abort', handler));
+	});
+```
+
+### Abort / Timeout Multiplexing
+
+Combine `Effect.raceAll` with discriminated result types to handle exit, abort, and timeout in a single expression:
+
+```typescript
+import { Effect } from 'effect';
+
+const exit =
+	yield*
+	Effect.raceAll([
+		handle.exitCode.pipe(
+			Effect.map((code) => ({ kind: 'exit' as const, code }))
+		),
+		fromAbortSignal(signal).pipe(
+			Effect.map(() => ({ kind: 'abort' as const }))
+		),
+		Effect.sleep(timeout).pipe(
+			Effect.map(() => ({ kind: 'timeout' as const }))
+		)
+	]);
+if (exit.kind !== 'exit') {
+	yield* handle.kill({ forceKillAfter: '3 seconds' });
+}
+```
+
+## Related Skills
+
+- **effect-platform-abstraction**: FileSystem, Path, and other platform services
+- **effect-testing**: Testing Effect programs with @effect/vitest
+- **effect-error-handling**: Typed error handling patterns with catchTag