@graftland/cli 0.0.0-stage → 0.2.0-beta.0

package/src/internal/configSchema.ts

@@ -0,0 +1,85 @@
+/**
+ * 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"
+
+const fields = Entry.Entry.schema.fields
+
+const Intercept = Schema.Struct(
+	Record.fromEntries(
+		Array.map(
+			registrations,
+			({ key, schema }) => [key, Schema.optionalKey(schema)] as const,
+		),
+	),
+).annotate({
+	identifier: "Intercept",
+	description:
+		"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,
+	}
+}

package/src/internal/env.ts

@@ -0,0 +1,163 @@
+/**
+ * Where `!env` values come from: the process environment, then an optional
+ * `.env` file that watch mode reads again when it changes.
+ */
+import type { PlatformError } from "effect"
+import {
+	Cause,
+	ConfigProvider,
+	Context,
+	Deferred,
+	Effect,
+	Exit,
+	FileSystem,
+	Layer,
+	Path,
+	Queue,
+	Ref,
+	Stream,
+} from "effect"
+
+// 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
+
+interface Loaded {
+	readonly target: string
+	readonly text: string
+	readonly provider: ConfigProvider.ConfigProvider
+}
+
+export class EnvFile extends Context.Service<
+	EnvFile,
+	{
+		/** Reads the file again; reports whether its contents changed. */
+		readonly reload: Effect.Effect<boolean, PlatformError.PlatformError>
+	}
+>()("@graftland/cli/internal/env/EnvFile") {}
+
+/** Provides `ConfigProvider` and `EnvFile`; a missing file fails the layer. */
+export const layer = (file: string | undefined) =>
+	Layer.unwrap(
+		Effect.gen(function* () {
+			const environment = ConfigProvider.fromEnv(options)
+			if (file === undefined)
+				return Layer.merge(
+					ConfigProvider.layer(environment),
+					Layer.succeed(EnvFile, { reload: Effect.succeed(false) }),
+				)
+			const fs = yield* FileSystem.FileSystem
+			// Resolve the request on every read, including polling. Never pin a
+			// symlink to its initial target. The provider and its baseline are
+			// committed together from the bytes actually read.
+			const read = Effect.gen(function* () {
+				const target = yield* fs.realPath(file)
+				const text = yield* fs.readFileString(target)
+				return {
+					target,
+					text,
+					provider: ConfigProvider.fromDotEnvContents(text, options),
+				}
+			})
+			const initial: Loaded = yield* read
+			const loaded = yield* Ref.make(initial)
+			const fromFile = ConfigProvider.make((path) =>
+				Effect.flatMap(Ref.get(loaded), ({ provider }) => provider.load(path)),
+			)
+			return Layer.merge(
+				ConfigProvider.layer(ConfigProvider.orElse(environment, fromFile)),
+				Layer.succeed(EnvFile, {
+					reload: Effect.gen(function* () {
+						const next = yield* read
+						const previous = yield* Ref.getAndSet(loaded, next)
+						return next.text !== previous.text
+					}),
+				}),
+			)
+		}),
+	)
+
+/**
+ * The handlers below let interruption through, and with it any failure raised
+ * while stopping. Log those; failures without interruption are handled there.
+ */
+const logStopped =
+	(file: string) =>
+	<A, E>(exit: Exit.Exit<A, E>) =>
+		Exit.isFailure(exit) &&
+		Cause.hasInterrupts(exit.cause) &&
+		(Cause.hasFails(exit.cause) || Cause.hasDies(exit.cause))
+			? Effect.logError(`Watching ${file} stopped with a failure`, exit.cause)
+			: Effect.void
+
+/**
+ * Reloads the file when it changes and retries the loader's entries, which
+ * reads `!env` again. A file that cannot be read keeps its previous values.
+ */
+export const watchEnvFile = <E, R>(
+	file: string,
+	reload: Effect.Effect<boolean, PlatformError.PlatformError>,
+	retry: Effect.Effect<void, E, R>,
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const ready = yield* Deferred.make<void>()
+		// As in HMR, own the source scope inside the producer. Observe its
+		// complete Exit after cleanup, before merge can discard it.
+		const events = Stream.callback<
+			FileSystem.WatchEvent,
+			PlatformError.PlatformError
+		>(
+			(queue) =>
+				fs
+					.watch(path.dirname(file), {
+						onReady: () => Deferred.doneUnsafe(ready, Effect.void),
+					})
+					.pipe(
+						Stream.filter(
+							(event) => path.basename(event.path) === path.basename(file),
+						),
+						Stream.runForEachArray((events) => Queue.offerAll(queue, events)),
+						Effect.scoped,
+						Effect.onExit(logStopped(file)),
+						Effect.catchCauseIf(
+							(cause) => !Cause.hasInterrupts(cause),
+							(cause) => Effect.logError(`Watching ${file} failed`, cause),
+						),
+						// A failed native backend must not stop content reconciliation.
+						Effect.andThen(Effect.sleep("1 second")),
+						Effect.forever,
+					),
+			{ bufferSize: 16 },
+		)
+		// Native events accelerate updates. Poll the request too: its target
+		// may live outside this directory, change, or lose a notification.
+		yield* Stream.mergeAll(
+			[
+				Stream.as(events, undefined),
+				Stream.fromEffect(Deferred.await(ready)),
+				Stream.tick("1 second").pipe(Stream.drop(1)),
+			],
+			{ concurrency: "unbounded" },
+		).pipe(
+			Stream.runForEach(() =>
+				// Delay to let writes settle.
+				Effect.sleep("100 millis").pipe(
+					Effect.andThen(reload),
+					Effect.flatMap((changed) => (changed ? retry : Effect.void)),
+					Effect.catchCauseIf(
+						(cause) => !Cause.hasInterrupts(cause),
+						(cause) => Effect.logError(`Reloading ${file} failed`, cause),
+					),
+				),
+			),
+			Effect.catchCauseIf(
+				(cause) => !Cause.hasInterrupts(cause),
+				(cause) => Effect.logError(`Stopped watching ${file}`, cause),
+			),
+		)
+	}).pipe(
+		// Observe the whole watcher before forkScoped owns it.
+		Effect.onExit(logStopped(file)),
+	)

package/src/internal/intercepts.ts

@@ -0,0 +1,23 @@
+import { Intercept } from "@graftland/loader"
+import { LogLevel, References, Schema } from "effect"
+
+/** References that can be configured by stock CLI entries. */
+export const registrations = [
+	Intercept.make(
+		References.CurrentLogAnnotations,
+		Schema.Record(Schema.String, Schema.Unknown).annotate({
+			description:
+				"Shallowly merges with outer annotations; configured keys win.",
+		}),
+		(outer, patch) => ({ ...outer, ...patch }),
+	),
+	Intercept.make(
+		References.MinimumLogLevel,
+		Schema.Literals(LogLevel.values).annotate({
+			description: "Replaces the outer minimum log level.",
+		}),
+		(_, level) => level,
+	),
+]
+
+export const layer = Intercept.layer(registrations)

package/src/internal/watch.ts

@@ -0,0 +1,58 @@
+import type * as Hmr from "@graftland/hmr"
+import { Array, Cause, Effect, Exit, Stream, String } from "effect"
+
+const moduleExtensions = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]
+
+/** Whether a change to this file should reload plugin modules. */
+export const isModule = (path: string) =>
+	!Array.contains(String.split(/[/\\]/)(path), "node_modules") &&
+	Array.some(moduleExtensions, (extension) => String.endsWith(extension)(path))
+
+const describe = (result: Hmr.ReloadResult) =>
+	result._tag === "Reloaded"
+		? Effect.logInfo(`Reloaded ${result.entries.length} plugin module(s)`)
+		: Effect.logWarning(
+				result.reason === "ambiguous-exports"
+					? `Restart required: shared plugin exports diverged in ${Array.join(result.modules, ", ")}`
+					: result.reason === "identity-conflict"
+						? `Restart required: plugin replacement identities conflict in ${Array.join(result.modules, ", ")}`
+						: `Restart required to pick up ${Array.join(result.modules, ", ")}`,
+			)
+
+/** Owns the HMR stream and retries failed loader entries after each reload. */
+export const watchModules = <E, R>(
+	hmr: Pick<Hmr.Hmr, "watch">,
+	directory: string,
+	retry: Effect.Effect<void, E, R>,
+) =>
+	hmr.watch([directory], { recursive: true, filter: isModule }).pipe(
+		Stream.runForEach((result) =>
+			Effect.gen(function* () {
+				if (result._tag === "Failed")
+					return yield* Effect.failCause(result.cause)
+				yield* describe(result)
+				yield* retry
+			}).pipe(
+				Effect.catchCauseIf(
+					(cause) => !Cause.hasInterrupts(cause),
+					(cause) => Effect.logError("Reloading plugin modules failed", cause),
+				),
+			),
+		),
+		Effect.catchCauseIf(
+			(cause) => !Cause.hasInterrupts(cause),
+			(cause) => Effect.logError("Watching plugin modules failed", cause),
+		),
+		// A backend failure ends the stream. Reinstall it after a delay rather than
+		// leaving the application running without a watcher.
+		Effect.andThen(Effect.sleep("1 second")),
+		Effect.forever,
+		// onExit runs uninterruptibly, after stream cleanup. Observe the entire
+		// worker before forkScoped owns it, including mixed interruption causes.
+		Effect.onExit((exit) =>
+			Exit.isFailure(exit) &&
+			(Cause.hasFails(exit.cause) || Cause.hasDies(exit.cause))
+				? Effect.logError("Module watcher exited with a failure", exit.cause)
+				: Effect.void,
+		),
+	)