@graftland/cli 0.3.3 → 0.4.0

package/src/Application.ts

@@ -0,0 +1,55 @@
+import {
+	Context,
+	Effect,
+	Exit,
+	Layer,
+	Option,
+	Schema,
+	Scope,
+	Stdio,
+} from "effect"
+import { Digest, SecureRandom, Signature } from "effect/crypto"
+import { FetchHttpClient } from "effect/http"
+import { NodeServices } from "@effect/platform-node"
+
+import { ProtocolStdio } from "./internal/protocolOutput"
+
+/** Set before argument parsing when stdout belongs to a byte protocol. */
+export const ProtocolOutput = Context.Reference(
+	"@graftland/cli/ProtocolOutput",
+	{ defaultValue: () => false },
+)
+
+/** An application requested a failed process exit, preserving its original cause. */
+export class ApplicationError extends Schema.TaggedError<
+	ApplicationError,
+	{ readonly brand: unique symbol }
+>()("ApplicationError", {
+	cause: Schema.Cause(Schema.Unknown, Schema.Unknown),
+}) {}
+
+/** Applications can request process completion and report cleanup independently of loader diagnostics. */
+export class Application extends Context.Service<
+	Application,
+	{
+		/** Exclusively reserves the process protocol channel until the caller releases its scope. */
+		readonly claimProtocol: Effect.Effect<void, ApplicationError, Scope.Scope>
+		readonly finish: (exit: Exit.Exit<void, unknown>) => Effect.Effect<void>
+		readonly onExit: (release: Effect.Effect<void>) => Effect.Effect<void>
+	}
+>()("@graftland/cli/Application") {}
+
+/** Node capabilities shared by application and command hosts. */
+export const platform = Layer.mergeAll(
+	Layer.effect(
+		Stdio.Stdio,
+		Effect.gen(function* () {
+			const reserved = yield* ProtocolStdio
+			return Option.isSome(reserved) ? reserved.value : yield* Stdio.Stdio
+		}),
+	).pipe(Layer.provideMerge(NodeServices.layer)),
+	FetchHttpClient.layer,
+	Digest.layerWebCrypto,
+	SecureRandom.layerWebCrypto,
+	Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto)),
+)

package/src/Commands.ts

@@ -0,0 +1,47 @@
+import { Context, Effect, Schema, Scope } from "effect"
+import type { CliError, Command } from "effect/cli"
+
+/** Services available when a registered command runs. Provide other services on the command itself. */
+export type Environment = Command.Environment | Scope.Scope
+
+/** A command name, alias, or registration lifetime conflicts with the host. */
+export class CommandRegistrationError extends Schema.TaggedError<
+	CommandRegistrationError,
+	{ readonly brand: unique symbol }
+>()("CommandRegistrationError", {
+	command: Schema.String,
+	detail: Schema.String,
+}) {
+	override get message() {
+		return `${this.command}: ${this.detail}`
+	}
+}
+
+/** Register one native Effect CLI command tree during the plugin's activation. */
+export class Commands extends Context.Service<
+	Commands,
+	{
+		readonly register: <
+			const Name extends string,
+			Input,
+			ContextInput,
+			E extends CliError.CliError,
+			R extends Environment,
+		>(
+			command: Command.Command<Name, Input, ContextInput, E, R>,
+		) => Effect.Effect<void, CommandRegistrationError, Scope.Scope>
+	}
+>()("@graftland/cli/Commands") {}
+
+/** A declared command plugin could not be decoded from its config file. */
+export class CommandConfigError extends Schema.TaggedError<
+	CommandConfigError,
+	{ readonly brand: unique symbol }
+>()("CommandConfigError", {
+	file: Schema.String,
+	cause: Schema.Unknown,
+}) {
+	override get message() {
+		return `Cannot read command plugins from ${this.file}`
+	}
+}

package/src/Manage.ts

@@ -1,18 +1,27 @@
 /**
  * Creating projects and changing their dependencies.
  */
-import * as Create from "@graftland/create"
-import * as PackageManager from "@graftland/package-manager"
 import {
 	Array,
 	Config,
 	Effect,
+	FileSystem,
 	Option,
+	Path,
 	Predicate,
 	Record,
 	Schema,
+	String,
 } from "effect"
 
+import * as Create from "@graftland/create"
+import * as PackageManager from "@graftland/package-manager"
+
+import { parseDocument, type Document } from "yaml"
+
+import { CommandConfigError } from "./Commands"
+import { home } from "./internal/commandConfig"
+
 const report = (result: PackageManager.InstallResult) =>
 	Effect.logInfo(
 		`${result.agent}: ${result.added.length} added, ${result.updated.length} updated, ${result.removed.length} removed`,
@@ -95,3 +104,73 @@ export const remove = (names: ReadonlyArray<string>) =>
 		".",
 		Record.fromEntries(Array.map(names, (name) => [name, null] as const)),
 	)
+
+const enabledConfig = Effect.fnUntraced(function* (
+	file: string,
+	module: string,
+) {
+	const fs = yield* FileSystem.FileSystem
+	const text = (yield* fs.exists(file))
+		? yield* fs.readFileString(file)
+		: "[]\n"
+	const document = yield* Effect.try({
+		try: () => {
+			const document: Document = parseDocument(text)
+			const error = document.errors[0]
+			if (error !== undefined) throw error
+			if (document.toJS() === null) document.contents = document.createNode([])
+			return document
+		},
+		catch: (cause) => CommandConfigError.make({ file, cause }),
+	})
+	const entries = yield* Schema.decodeUnknownEffect(
+		Schema.Array(Schema.Unknown),
+	)(document.toJS())
+	const existing = Array.findFirstIndex(
+		entries,
+		(entry) =>
+			Predicate.hasProperty(entry, "name") &&
+			entry.name === module &&
+			Predicate.hasProperty(entry, "cli") &&
+			entry.cli === true,
+	)
+	return yield* Effect.try({
+		try: () => {
+			if (Option.isSome(existing))
+				document.setIn([existing.value, "disabled"], false)
+			else document.add({ name: module, cli: true })
+			return document.toString()
+		},
+		catch: (cause) => CommandConfigError.make({ file, cause }),
+	})
+})
+const prepareHome = Effect.fnUntraced(function* (directory: string) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	yield* fs.makeDirectory(directory, { recursive: true })
+	const manifest = path.join(directory, "package.json")
+	if (!(yield* fs.exists(manifest)))
+		yield* fs.writeFileString(manifest, '{"private":true,"type":"module"}\n')
+}, Effect.uninterruptible)
+
+/** Install a command plugin and explicitly enable its /cli entry. */
+export const addPlugin = Effect.fn("Manage.addPlugin")(function* (
+	name: string,
+	global: boolean = false,
+) {
+	const path = yield* Path.Path
+	const fs = yield* FileSystem.FileSystem
+	const directory = global ? yield* home : path.resolve(".")
+	const packageName =
+		String.startsWith("@")(name) || String.startsWith("graft-plugin-")(name)
+			? name
+			: `@graftland/plugin-${name}`
+	const module = `${packageName}/cli`
+	const file = path.join(directory, "graft.yml")
+	const text = yield* enabledConfig(file, module)
+	if (global) yield* prepareHome(directory)
+	yield* install(directory, Record.singleton(packageName, "latest"))
+	// Once accepted, the native write must finish before command cleanup can proceed.
+	yield* fs.writeFileString(file, text).pipe(Effect.uninterruptible)
+	yield* Effect.logInfo(`Enabled ${module} in ${file}`)
+})

package/src/Start.ts

@@ -1,14 +1,36 @@
 /**
  * Runs a Graft application from its config file.
  */
+import {
+	Array,
+	Cause,
+	Deferred,
+	Effect,
+	Exit,
+	FileSystem,
+	Layer,
+	Logger,
+	Option,
+	Path,
+	Scope,
+	Semaphore,
+	type PlatformError,
+	type Schema,
+} from "effect"
 import { NodeServices } from "@effect/platform-node"
-import { SecureRandom } from "effect/crypto"
+
 import { Graft, Plugin } from "@graftland/graft"
 import * as Hmr from "@graftland/hmr"
-import { Include, Loader, ModuleResolver, type Tree } from "@graftland/loader"
-import type { PlatformError, Schema } from "effect"
-import { Effect, FileSystem, Layer, Logger, Path } from "effect"
-import { EnvFile, layer as env, watchEnvFile } from "./internal/env"
+import {
+	Entry,
+	Include,
+	Loader,
+	ModuleResolver,
+	type Tree,
+} from "@graftland/loader"
+
+import { Application, ApplicationError, platform } from "./Application"
+import { layer as env, EnvFile, watchEnvFile } from "./internal/env"
 import { layer as intercepts } from "./internal/intercepts"
 import { watchModules } from "./internal/watch"
 
@@ -29,18 +51,48 @@ export interface Options {
  * modules are imported through the hot reloader, so bare specifiers resolve
  * from the application directory whether or not `watch` is on.
  */
-export const run: (
+export const run = (
 	options: Options,
-) => Effect.Effect<
-	never,
+): Effect.Effect<
+	void,
+	| ApplicationError
 	| Graft.ServiceConflict
 	| PlatformError.BadArgument
 	| PlatformError.PlatformError
 	| Schema.SchemaError
 	| Loader.StoreError
 	| Tree.InvalidOperation
-> = Effect.fn("Start.run")(
-	function* (options: Options) {
+> =>
+	Effect.gen(function* () {
+		const scope = yield* Effect.scope
+		const done = yield* Deferred.make<void, ApplicationError>()
+		const protocol = yield* Semaphore.make(1)
+		yield* Graft.provide(Application, {
+			claimProtocol: Effect.acquireRelease(
+				protocol.takeIfAvailable(1).pipe(
+					Effect.flatMap((acquired) =>
+						acquired
+							? Effect.void
+							: Effect.fail(
+									ApplicationError.make({
+										cause: Cause.fail(
+											"Only one runner may own the process stdio channel",
+										),
+									}),
+								),
+					),
+				),
+				() => protocol.release(1),
+			),
+			finish: (exit) =>
+				Deferred.done(
+					done,
+					Exit.isFailure(exit)
+						? Exit.fail(ApplicationError.make({ cause: exit.cause }))
+						: Exit.void,
+				).pipe(Effect.asVoid),
+			onExit: (release) => Scope.addFinalizer(scope, release),
+		})
 		const path = yield* Path.Path
 		const file = path.resolve(options.config)
 		const directory = path.dirname(file)
@@ -52,16 +104,37 @@ export const run: (
 		})
 		const modules = yield* ModuleResolver.make({
 			base: directory,
-			importer: hmr.importModule,
+			importer: options.watch ? hmr.importModuleScoped : hmr.importModule,
 		})
 		yield* Graft.provide(ModuleResolver.ModuleResolver, {
 			resolve: resolver.resolve,
 			importModule: modules.importModule,
 		})
+		const fs = yield* FileSystem.FileSystem
+		const observe = hmr.observation.pipe(
+			Effect.provideService(FileSystem.FileSystem, fs),
+			Effect.map((source) => ({
+				...source,
+				watch: (files: ReadonlyArray<string>, activation: Scope.Scope) =>
+					source.watch(files, activation).pipe(
+						Effect.mapError((cause) =>
+							ModuleResolver.ModuleInvalid.make({
+								specifier: Array.join(files, ", "),
+								cause,
+							}),
+						),
+					),
+			})),
+		)
 		const included = yield* Graft.plugin(Include.Include, {
 			path: file,
 			watch: options.watch,
-		})
+		}).pipe(
+			Effect.provideService(
+				ModuleResolver.Watch,
+				options.watch ? Option.some(observe) : Option.none(),
+			),
+		)
 		yield* included.await
 		if (options.watch) {
 			const { reload } = yield* EnvFile
@@ -69,16 +142,17 @@ export const run: (
 			const reloader = Plugin.make({
 				name: "reloader",
 				inject: [Loader.Loader, FileSystem.FileSystem, Path.Path],
-				apply: Effect.fnUntraced(function* () {
-					const loader = yield* Loader.Loader
-					yield* watchModules(hmr, directory, loader.retry).pipe(
-						Effect.forkScoped,
-					)
-					if (envFile !== undefined)
-						yield* watchEnvFile(envFile, reload, loader.retry).pipe(
+				apply: () =>
+					Effect.gen(function* () {
+						const loader = yield* Loader.Loader
+						yield* watchModules(hmr, directory, loader.retry).pipe(
 							Effect.forkScoped,
 						)
-				}),
+						if (envFile !== undefined)
+							yield* watchEnvFile(envFile, reload, loader.retry).pipe(
+								Effect.forkScoped,
+							)
+					}),
 			})
 			yield* Graft.plugin(reloader)
 		}
@@ -86,22 +160,20 @@ export const run: (
 		yield* Effect.logInfo(
 			`Running ${path.relative(process.cwd(), file) || file}`,
 		)
-		return yield* Effect.never
-	},
-	Effect.scoped,
-	(effect, options) =>
+		return yield* Deferred.await(done)
+	}).pipe(
+		Effect.scoped,
+		Effect.provideService(Entry.Select, (entry) => entry["cli"] !== true),
 		// @effect-diagnostics-next-line strictEffectProvide:off -- this runs the whole application, so it is an entry point
 		Effect.provide(
-			effect,
 			Layer.provideMerge(
 				Graft.layer,
 				Layer.mergeAll(
-					SecureRandom.layerWebCrypto,
-					NodeServices.layer,
+					platform,
 					intercepts,
 					env(options.envFile).pipe(Layer.provide(NodeServices.layer)),
 					Logger.layer([Logger.consolePretty()]),
 				),
 			),
 		),
-)
+	)

package/src/bin.ts

@@ -2,10 +2,15 @@
 /**
  * The `graft` executable. Running this module starts the program.
  */
-import { NodeRuntime, NodeServices } from "@effect/platform-node"
-import { Effect, Option } from "effect"
-import { Argument, Command, Flag } from "effect/cli"
+import { Array, Effect, Layer, Logger, Option, Stdio } from "effect"
+import { Argument, CliError, Command, Flag } from "effect/cli"
+import { NodeRuntime } from "@effect/platform-node"
+
+import { Graft } from "@graftland/graft"
+
 import { version } from "../package.json" with { type: "json" }
+import { platform } from "./Application"
+import * as Host from "./internal/commandHost"
 
 const start = Command.make(
 	"start",
@@ -64,12 +69,28 @@ const create = Command.make(
 
 const add = Command.make(
 	"add",
-	{ packages: Argument.variadic(Argument.String("package")) },
-	({ packages }) =>
-		Effect.promise(() => import("./Manage")).pipe(
+	{
+		packages: Argument.variadic(Argument.String("package")),
+		plugin: Flag.String("plugin").pipe(Flag.optional),
+		global: Flag.Boolean("global").pipe(Flag.withDefault(false)),
+	},
+	Effect.fnUntraced(function* ({ packages, plugin, global }) {
+		if (
+			(global && Option.isNone(plugin)) ||
+			(Option.isSome(plugin) && packages.length > 0)
+		)
+			return yield* CliError.UserError.make({
+				cause: "Conflicting install options",
+				userMessage:
+					"Use add --plugin <name> [--global] without package arguments",
+			})
+		const Manage = yield* Effect.promise(() => import("./Manage")).pipe(
 			Effect.uninterruptible,
-			Effect.flatMap((Manage) => Manage.add(packages)),
-		),
+		)
+		return yield* Option.isSome(plugin)
+			? Manage.addPlugin(plugin.value, global)
+			: Manage.add(packages)
+	}),
 ).pipe(
 	Command.withDescription(
 		"Add dependencies, restoring the project if installing fails",
@@ -92,10 +113,57 @@ const remove = Command.make(
 
 const graft = Command.make("graft").pipe(
 	Command.withDescription("Run and manage Graft applications"),
-	Command.withSubcommands([start, create, add, remove]),
+	Command.withSharedFlags({
+		stdio: Flag.Boolean("stdio").pipe(Flag.withDefault(false)),
+		noPlugins: Flag.Boolean("no-plugins").pipe(Flag.withDefault(false)),
+	}),
 )
 
-Command.run(graft, { version }).pipe(
-	Effect.provide(NodeServices.layer),
-	NodeRuntime.runMain,
+const program = Effect.gen(function* () {
+	const stdio = yield* Stdio.Stdio
+	const args = yield* stdio.args
+	return yield* Host.output(
+		Effect.scoped(
+			Effect.gen(function* () {
+				const context = yield* Layer.build(Graft.layer)
+				return yield* Host.run(
+					[start, create, add, remove],
+					graft,
+					version,
+					args,
+				).pipe(Effect.provideContext(context))
+			}),
+		),
+		args,
+	)
+})
+NodeRuntime.runMain(
+	Effect.scoped(
+		Effect.gen(function* () {
+			const context = yield* Layer.build(platform)
+			return yield* program.pipe(Effect.provideContext(context))
+		}),
+	).pipe(
+		(effect) =>
+			Effect.withFiber((main) =>
+				effect.pipe(
+					Effect.tapCause((cause) =>
+						Array.every(
+							cause.reasons,
+							(reason) =>
+								reason._tag === "Interrupt" && reason.fiberId === main.id,
+						) ||
+						Array.every(
+							cause.reasons,
+							(reason) =>
+								reason._tag === "Fail" && CliError.isCliError(reason.error),
+						)
+							? Effect.void
+							: Effect.logError(cause),
+					),
+				),
+			),
+		Effect.provideService(Logger.LogToStderr, true),
+	),
+	{ disableErrorReporting: true },
 )

package/src/index.ts

@@ -3,3 +3,6 @@
  */
 export * as Manage from "./Manage"
 export * as Start from "./Start"
+
+export * as Commands from "./Commands"
+export * as Application from "./Application"

package/src/internal/commandConfig.ts

@@ -0,0 +1,91 @@
+import {
+	Array,
+	Config,
+	Effect,
+	FileSystem,
+	HashMap,
+	Option,
+	Path,
+	Predicate,
+	Schema,
+} from "effect"
+
+import { parseDocument } from "yaml"
+
+import { CommandConfigError } from "../Commands"
+
+const Description = Schema.Struct({
+	name: Schema.String,
+	config: Schema.optionalKey(Schema.Unknown),
+	disabled: Schema.optionalKey(Schema.Boolean),
+})
+export const home = Effect.gen(function* () {
+	const path = yield* Path.Path
+	const override = yield* Config.String("GRAFT_HOME").pipe(Config.option)
+	if (Option.isSome(override)) return path.resolve(override.value)
+	const directory = yield* Config.String("HOME")
+	return path.join(directory, ".graft")
+})
+export const read = Effect.fnUntraced(function* (file: string) {
+	const fs = yield* FileSystem.FileSystem
+	if (!(yield* fs.exists(file))) return []
+	const text = yield* fs.readFileString(file)
+	const { Entry } = yield* Effect.promise(
+		() => import("@graftland/loader"),
+	).pipe(Effect.uninterruptible)
+	const value = yield* Effect.try({
+		try: () => {
+			const document = parseDocument(text, {
+				customTags: [
+					{ tag: "!env", resolve: (name: string) => new Entry.Env({ name }) },
+				],
+			})
+			const error = document.errors[0]
+			if (error !== undefined) throw error
+			return document.toJS()
+		},
+		catch: (cause) => CommandConfigError.make({ file, cause }),
+	})
+	const entries = yield* Schema.decodeUnknownEffect(
+		Schema.NullOr(Schema.Array(Schema.Unknown)),
+	)(value).pipe(
+		Effect.mapError((cause) => CommandConfigError.make({ file, cause })),
+	)
+	return yield* Effect.forEach(
+		Array.filter(
+			entries ?? [],
+			(entry) => Predicate.hasProperty(entry, "cli") && entry.cli === true,
+		),
+		(entry) =>
+			Schema.decodeUnknownEffect(Description)(entry).pipe(
+				Effect.mapBoth({
+					onFailure: (cause) => CommandConfigError.make({ file, cause }),
+					onSuccess: (entry) => ({ ...entry, file }),
+				}),
+			),
+	)
+})
+export const discover = Effect.fnUntraced(function* (watch: boolean) {
+	const path = yield* Path.Path
+	const directory = yield* home
+	const global = yield* read(path.join(directory, "graft.yml"))
+	const project = yield* read(path.resolve("graft.yml")).pipe(
+		Effect.catchTag("CommandConfigError", (error) =>
+			watch
+				? Effect.logWarning(
+						"Command discovery skipped invalid project configuration; restart to load command plugins",
+						error,
+					).pipe(Effect.as([]))
+				: Effect.fail(error),
+		),
+	)
+	const merged = Array.reduce(
+		[...global, ...project],
+		HashMap.empty<string, (typeof global)[number]>(),
+		(map, entry) => HashMap.set(map, entry.name, entry),
+	)
+	return Array.filter(
+		Array.fromIterable(HashMap.values(merged)),
+		(entry) => entry.disabled !== true,
+	)
+})