@graftland/cli 0.3.3 → 0.4.0

package/src/internal/commandHost.ts

@@ -0,0 +1,216 @@
+import {
+	Array,
+	Cause,
+	Console,
+	Effect,
+	Option,
+	Path,
+	Schema,
+	Stream,
+	String,
+} from "effect"
+import { CliError, CliOutput, Command } from "effect/cli"
+
+import { Graft, Plugin, type Fork } from "@graftland/graft"
+
+import { ProtocolOutput } from "../Application"
+import { Commands, type Environment } from "../Commands"
+import * as Configuration from "./commandConfig"
+import * as Registry from "./commandRegistry"
+import * as Importer from "./importer"
+import { reserve } from "./protocolOutput"
+
+class CommandPluginError extends Schema.TaggedError<
+	CommandPluginError,
+	{ readonly brand: unique symbol }
+>()("CommandPluginError", {
+	plugin: Schema.String,
+	detail: Schema.String,
+	cause: Schema.optionalKey(Schema.Cause(Schema.Unknown, Schema.Unknown)),
+}) {
+	override get message() {
+		return `${this.plugin}: ${this.detail}`
+	}
+}
+const failure = (name: string, cause: Cause.Cause<unknown>) =>
+	CommandPluginError.make({
+		plugin: name,
+		detail: "Command plugin failed",
+		cause,
+	})
+const observe = (fork: Fork.Fork, name: string) =>
+	fork.state.pipe(
+		Stream.runForEach((state) =>
+			state._tag === "Failed"
+				? Effect.fail(failure(name, state.cause))
+				: Effect.void,
+		),
+		Effect.andThen(Effect.never),
+	)
+const activate = Effect.fnUntraced(function* (
+	entry: Effect.Success<ReturnType<typeof Configuration.discover>>[number],
+	registry: Effect.Success<ReturnType<typeof Registry.make>>,
+) {
+	const { ConfigDirectory, Entry, ModuleResolver } = yield* Effect.promise(
+		() => import("@graftland/loader"),
+	).pipe(Effect.uninterruptible)
+	const path = yield* Path.Path
+	const directory = path.dirname(entry.file)
+	const importer = yield* Importer.make(directory)
+	const resolver = yield* ModuleResolver.make({ base: directory, importer })
+	const plugin = yield* resolver.resolve(entry.name)
+	const input = yield* Entry.resolveEnv(entry.config)
+	const owner = Plugin.make({
+		name: `command:${entry.name}`,
+		apply: Effect.fnUntraced(function* () {
+			yield* Graft.provide(Commands, registry.service(entry.name))
+			const child = yield* Graft.plugin(plugin, input)
+			const state = yield* child.state.pipe(
+				Stream.filter(
+					(state) => state._tag === "Active" || state._tag === "Failed",
+				),
+				Stream.runHead,
+			)
+			if (Option.isSome(state) && state.value._tag === "Failed")
+				return yield* failure(entry.name, state.value.cause)
+			yield* Plugin.fork(observe(child, entry.name))
+		}),
+	})
+	const fork = yield* Graft.plugin(owner, undefined, {
+		isolate: [Commands],
+	}).pipe(Effect.provideService(ConfigDirectory, Option.some(directory)))
+	yield* Effect.addFinalizer(() => fork.dispose.pipe(Effect.orDie))
+	yield* fork.await.pipe(
+		Effect.timeout("5 seconds"),
+		Effect.catchCause((cause) => Effect.fail(failure(entry.name, cause))),
+	)
+	if (!(yield* registry.has(entry.name)))
+		return yield* CommandPluginError.make({
+			plugin: entry.name,
+			detail: "The plugin did not register a command",
+		})
+	return fork
+})
+
+// Registration checks the error/environment bounds before this heterogeneous tree erases its input types.
+const execute = <Name extends string, Input, ContextInput>(
+	command: Command.Command<
+		Name,
+		Input,
+		ContextInput,
+		CliError.CliError,
+		Environment
+	>,
+	version: string,
+	args: ReadonlyArray<string>,
+): Effect.Effect<void, CliError.CliError, Environment> =>
+	Command.runWith(command, { version })(args)
+export const run = Effect.fnUntraced(function* (
+	builtins: ReadonlyArray<Command.Command.Any>,
+	root: Command.Command<
+		"graft",
+		{ readonly stdio: boolean; readonly noPlugins: boolean },
+		{ readonly stdio: boolean; readonly noPlugins: boolean },
+		never,
+		never
+	>,
+	version: string,
+	args: ReadonlyArray<string>,
+) {
+	const registry = yield* Registry.make(builtins)
+	const flags = Array.takeWhile(args, (arg) => arg !== "--")
+	const entries =
+		flags.includes("--no-plugins") ||
+		(args.length === 1 && args[0] === "--version")
+			? []
+			: yield* Configuration.discover(
+					Option.contains(
+						Array.findFirst(flags, (arg) => !String.startsWith("-")(arg)),
+						"start",
+					) &&
+						(flags.includes("--watch") || flags.includes("-w")),
+				)
+	const forks = yield* Effect.forEach(
+		entries,
+		(entry) =>
+			activate(entry, registry).pipe(
+				Effect.mapError((error) => failure(entry.name, Cause.fail(error))),
+			),
+		{ concurrency: "unbounded" },
+	)
+	const commands = yield* registry.freeze
+	return yield* execute(
+		root.pipe(
+			Command.withSubcommands([
+				...Array.map(builtins, Registry.erase),
+				...commands,
+			]),
+		),
+		version,
+		args,
+	).pipe(
+		Effect.raceFirst(
+			Effect.forEach(
+				forks,
+				(fork, index) => observe(fork, entries[index]?.name ?? "command"),
+				{ concurrency: "unbounded" },
+			).pipe(Effect.andThen(Effect.never)),
+		),
+	)
+})
+
+const usage = (message: string) =>
+	Console.error(message).pipe(
+		Effect.andThen(
+			CliError.UserError.make({
+				cause: "Invalid process flags",
+				userMessage: message,
+			}),
+		),
+	)
+
+/** Select output policy before discovery or CLI action flags can produce text. */
+export const output = <A, E, R>(
+	effect: Effect.Effect<A, E, R>,
+	args: ReadonlyArray<string>,
+) =>
+	Effect.gen(function* () {
+		const tokens = Array.takeWhile(args, (arg) => arg !== "--")
+		const stdio = tokens.includes("--stdio")
+		const program = Effect.gen(function* () {
+			if (
+				stdio &&
+				Array.some(
+					tokens,
+					(arg) =>
+						arg === "--wizard" ||
+						String.startsWith("--wizard=")(arg) ||
+						arg === "--completions" ||
+						String.startsWith("--completions=")(arg),
+				)
+			)
+				return yield* usage(
+					"--stdio cannot be combined with wizard or completions",
+				)
+			if (
+				Array.some(
+					tokens,
+					(arg) =>
+						String.startsWith("--stdio=")(arg) ||
+						arg === "--no-stdio" ||
+						String.startsWith("--no-plugins=")(arg),
+				)
+			)
+				return yield* usage("Use --stdio and --no-plugins as standalone flags")
+			return yield* effect
+		}).pipe(Effect.provideService(ProtocolOutput, stdio))
+		return yield* stdio
+			? program.pipe(
+					reserve,
+					Effect.provideService(
+						CliOutput.Formatter,
+						CliOutput.defaultFormatter({ colors: false }),
+					),
+				)
+			: program
+	})

package/src/internal/commandRegistry.ts

@@ -0,0 +1,100 @@
+import { Array, Effect, HashMap, Option, TxRef } from "effect"
+import { Command, type CliError } from "effect/cli"
+
+import {
+	CommandRegistrationError,
+	Commands,
+	type Environment,
+} from "../Commands"
+
+export type Registered = Command.Command<
+	string,
+	never,
+	{},
+	CliError.CliError,
+	Environment
+>
+/** The public register method checks E and R before input/name erasure. */
+export const erase = (command: Command.Command.Any): Registered => command
+
+const names = (command: Command.Command.Any) =>
+	command.alias === undefined ? [command.name] : [command.name, command.alias]
+const validate = (
+	commands: ReadonlyArray<Command.Command.Any>,
+): Effect.Effect<void, CommandRegistrationError> => {
+	const all = Array.flatMap(commands, names)
+	const duplicate = Array.findFirst(
+		all,
+		(name, index) => all.indexOf(name) !== index,
+	)
+	return Option.isSome(duplicate)
+		? Effect.fail(
+				CommandRegistrationError.make({
+					command: duplicate.value,
+					detail: "Duplicate command name or alias",
+				}),
+			)
+		: Effect.forEach(
+				commands,
+				(command) =>
+					validate(
+						Array.flatMap(command.subcommands, (group) => group.commands),
+					),
+				{ discard: true },
+			)
+}
+export const make = Effect.fnUntraced(function* (
+	builtins: ReadonlyArray<Command.Command.Any>,
+) {
+	const state = yield* TxRef.make({
+		frozen: false,
+		entries: HashMap.empty<string, Registered>(),
+	})
+	const service = (owner: string) =>
+		Commands.of({
+			register: (command) =>
+				Effect.acquireRelease(
+					Effect.gen(function* () {
+						const current = yield* TxRef.get(state)
+						if (current.frozen)
+							return yield* CommandRegistrationError.make({
+								command: command.name,
+								detail: "Registration is closed",
+							})
+						if (HashMap.has(current.entries, owner))
+							return yield* CommandRegistrationError.make({
+								command: command.name,
+								detail: "A plugin must register exactly one root command",
+							})
+						yield* validate([
+							...builtins,
+							...HashMap.values(current.entries),
+							command,
+						])
+						yield* TxRef.set(state, {
+							...current,
+							entries: HashMap.set(current.entries, owner, erase(command)),
+						})
+					}).pipe(Effect.tx),
+					() =>
+						TxRef.update(state, (current) => ({
+							...current,
+							entries: HashMap.remove(current.entries, owner),
+						})).pipe(Effect.tx),
+				),
+		})
+	const freeze = Effect.gen(function* () {
+		const current = yield* TxRef.get(state)
+		yield* TxRef.set(state, { ...current, frozen: true })
+		return Array.fromIterable(HashMap.values(current.entries))
+	}).pipe(Effect.tx)
+	return {
+		service,
+		freeze,
+		has: (owner: string) =>
+			TxRef.get(state).pipe(
+				Effect.map((current) => HashMap.has(current.entries, owner)),
+				Effect.tx,
+			),
+	}
+})

package/src/internal/configSchema.ts

@@ -1,13 +1,9 @@
-/**
- * The JSON Schema of the config file that graft start reads, derived from the
- * loader's entry fields and the intercepts the CLI registers. The build writes
- * it to the package's schema.json, so each release ships its own version.
- */
-import { Entry } from "@graftland/loader"
-import { Array, JsonSchema, Record, Schema } from "effect"
-import { registrations } from "./intercepts"
+/** The CLI adds its intercepts to the loader's recursive editor schema. */
+import { Array, Record, Schema } from "effect"
+
+import { ConfigSchema } from "@graftland/loader"
 
-const fields = Entry.Entry.schema.fields
+import { registrations } from "./intercepts"
 
 const Intercept = Schema.Struct(
 	Record.fromEntries(
@@ -22,64 +18,8 @@ const Intercept = Schema.Struct(
 		"Patches for references, applying to this entry and its descendants.",
 })
 
-const Metadata = [Schema.Record(Schema.String, Schema.Unknown)] as const
-
-const shared = {
-	...fields,
-	id: Schema.optionalKey(
-		fields.id.annotate({
-			description:
-				"Identifies the entry. Graft adds one, and writes it to the file, if an entry has none.",
-		}),
-	),
-	intercept: Schema.optionalKey(Intercept),
-}
-
-// Two shapes instead of one, so that only a group's config is checked as a
-// list of entries; a plugin's config is checked by the plugin's own Schema.
-const FileEntry: Schema.Top = Schema.Union([
-	Schema.StructWithRest(
-		Schema.Struct({
-			...shared,
-			group: Schema.Literal(true).annotate({
-				description: "true makes the entry a group of other entries.",
-			}),
-			config: Schema.optionalKey(
-				Schema.Array(Schema.suspend(() => FileEntry)).annotate({
-					description: "The entries of this group.",
-				}),
-			),
-		}),
-		Metadata,
-	),
-	Schema.StructWithRest(
-		Schema.Struct({
-			...shared,
-			group: Schema.optionalKey(
-				Schema.Literal(false).annotate({
-					description: "true makes the entry a group of other entries.",
-				}),
-			),
-		}),
-		Metadata,
-	),
-]).annotate({ identifier: "Entry" })
-
-const File = Schema.NullOr(Schema.Array(FileEntry)).annotate({
-	title: "Graft config file",
-	description:
-		"The entries that graft start loads. Each entry loads one plugin, or groups other entries.",
-})
-
-/** Draft-07, which YAML language servers support most widely. */
-export const make = () => {
-	const document = JsonSchema.toDocumentDraft07(
-		// Only the intercept struct is closed: entries keep a rest record for metadata.
-		Schema.toJsonSchemaDocument(File, { onExcessProperty: "error" }),
-	)
-	return {
-		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_07,
-		...document.schema,
-		definitions: document.definitions,
-	}
-}
+export const make = (entries?: ReadonlyArray<ConfigSchema.Registration>) =>
+	ConfigSchema.make({
+		...(entries === undefined ? {} : { entries }),
+		intercept: Intercept,
+	})

package/src/internal/env.ts

@@ -2,8 +2,6 @@
  * Where `!env` values come from: the process environment, then an optional
  * `.env` file that watch mode reads again when it changes.
  */
-import { observeShutdown } from "./observeShutdown"
-import type { PlatformError } from "effect"
 import {
 	Cause,
 	ConfigProvider,
@@ -17,8 +15,11 @@ import {
 	Queue,
 	Ref,
 	Stream,
+	type PlatformError,
 } from "effect"
 
+import { observeShutdown } from "./observeShutdown"
+
 // An empty variable is still set: it overrides the file, and the plugin's
 // schema decides whether it is valid.
 const options = { preserveEmptyStrings: true } as const

package/src/internal/importer.ts

@@ -0,0 +1,28 @@
+import { registerHooks } from "node:module"
+
+import { Effect, Path, String } from "effect"
+import { SecureRandom } from "effect/crypto"
+
+/** Bare names resolve from the application; imported dependencies keep their own parent URLs. */
+export const make = Effect.fnUntraced(function* (directory: string) {
+	const path = yield* Path.Path
+	const base = yield* path.toFileUrl(path.join(directory, "graft.yml"))
+	const random = yield* SecureRandom.SecureRandom
+	const id = yield* random.uuidV4()
+	const prefix = `graft-module-${id}:`
+	yield* Effect.acquireRelease(
+		Effect.sync(() =>
+			registerHooks({
+				resolve: (specifier, context, next) =>
+					String.startsWith(prefix)(specifier)
+						? next(String.slice(prefix.length)(specifier), {
+								...context,
+								parentURL: base.href,
+							})
+						: next(specifier, context),
+			}),
+		),
+		(hooks) => Effect.sync(() => hooks.deregister()),
+	)
+	return (specifier: string): Promise<unknown> => import(prefix + specifier)
+})

package/src/internal/intercepts.ts

@@ -1,6 +1,7 @@
-import { Intercept } from "@graftland/loader"
 import { LogLevel, References, Schema } from "effect"
 
+import { Intercept } from "@graftland/loader"
+
 /** References that can be configured by stock CLI entries. */
 export const registrations = [
 	Intercept.make(

package/src/internal/protocolOutput.ts

@@ -0,0 +1,101 @@
+import process from "node:process"
+// @effect-diagnostics-next-line nodeBuiltinImport:off -- a native Writable retains the protocol writer while Node forwards all diagnostic output to stderr.
+import { finished, Writable } from "node:stream"
+
+import { Context, Effect, Logger, Option, PlatformError, Stdio } from "effect"
+import { NodeSink } from "@effect/platform-node"
+
+// A peer that stops reading but keeps the pipe open must not hold shutdown forever.
+const flushTimeout = "2 seconds"
+const flushTimedOut = new Error(
+	"The protocol peer stopped reading during shutdown",
+)
+
+export const ProtocolStdio = Context.Reference(
+	"@graftland/cli/internal/ProtocolStdio",
+	{ defaultValue: (): Option.Option<Stdio.Stdio> => Option.none() },
+)
+
+/** Reserve the original stdout writer for Stdio; all process diagnostics use stderr. */
+export const reserve = <A, E, R>(program: Effect.Effect<A, E, R>) =>
+	Effect.scoped(
+		Effect.gen(function* () {
+			const stdio = yield* Stdio.Stdio
+			const protocol = yield* Effect.acquireRelease(
+				Effect.sync(() => {
+					const original = process.stdout.write
+					const write = original.bind(process.stdout)
+					const stream = new Writable({
+						write: (chunk, encoding, done) => {
+							write(chunk, encoding, done)
+						},
+					})
+					// Default worker forwarding waits for stdout's drain after write returns false.
+					const drain = () => {
+						process.stdout.emit("drain")
+					}
+					const error = (cause: Error) => {
+						stream.destroy(cause)
+					}
+					process.stdout.on("error", error)
+					process.stderr.on("drain", drain)
+					// Node's console and default worker forwarding use this same writer.
+					process.stdout.write = process.stderr.write.bind(process.stderr)
+					return { original, stream, drain, error }
+				}),
+				({ original, stream, drain, error }) =>
+					Effect.raceFirst(
+						Effect.callback<void>((resume) => {
+							const cleanup = finished(stream, (cause) => {
+								cleanup()
+								const timedOut = cause === flushTimedOut
+								const restore = () => {
+									// After a timeout, part of a frame may still be queued on stdout, so later
+									// output keeps going to stderr instead of corrupting the abandoned stream.
+									if (!timedOut) {
+										process.stdout.off("error", error)
+										process.stderr.off("drain", drain)
+										process.stdout.write = original
+									}
+									resume(
+										cause == null || timedOut ? Effect.void : Effect.die(cause),
+									)
+								}
+								// Keep the native error listener until every accepted write and delayed error has settled.
+								if (process.stdout.destroyed && !process.stdout.closed)
+									process.stdout.once("close", restore)
+								else restore()
+							})
+							stream.end()
+						}),
+						// Unflushed bytes for a peer that stopped reading are dropped, not a cleanup failure.
+						// Node cannot close stdio, so a clean exit still waits for the stalled peer; signals and failures exit.
+						Effect.sleep(flushTimeout).pipe(
+							Effect.andThen(Effect.sync(() => stream.destroy(flushTimedOut))),
+							Effect.andThen(Effect.never),
+							Effect.interruptible,
+						),
+					),
+			)
+			const reserved = {
+				...stdio,
+				stdout: (options?: { readonly endOnDone?: boolean }) =>
+					NodeSink.fromWritable({
+						evaluate: () => protocol.stream,
+						onError: (cause) =>
+							PlatformError.systemError({
+								module: "Stdio",
+								method: "stdout",
+								_tag: "Unknown",
+								cause,
+							}),
+						endOnDone: options?.endOnDone ?? false,
+					}),
+			}
+			return yield* program.pipe(
+				Effect.provideService(Logger.LogToStderr, true),
+				Effect.provideService(Stdio.Stdio, reserved),
+				Effect.provideService(ProtocolStdio, Option.some(reserved)),
+			)
+		}),
+	)

package/src/internal/watch.ts

@@ -1,7 +1,9 @@
-import { observeShutdown } from "./observeShutdown"
-import type * as Hmr from "@graftland/hmr"
 import { Array, Cause, Effect, Exit, Stream, String } from "effect"
 
+import type * as Hmr from "@graftland/hmr"
+
+import { observeShutdown } from "./observeShutdown"
+
 const moduleExtensions = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]
 
 /** Whether a change to this file should reload plugin modules. */