@graftland/cli 0.1.0 → 0.2.0-beta.1

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@graftland/cli",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.1",
   "type": "module",
   "engines": {
-    "node": ">=22.15.0"
+    "node": ">=22.19.0"
   },
   "description": "The graft command: start, create, add and remove",
   "license": "Apache-2.0",
@@ -15,15 +15,19 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "schema.json",
+    "README.zh-CN.md",
+    "README.zh-TW.md"
   ],
   "exports": {
     ".": "./dist/index.js",
     "./bin": "./dist/bin.js",
+    "./internal/configSchema": "./dist/internal/configSchema.js",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "effect": "4.1.2"
+    "effect": "4.1.*"
   },
   "devDependencies": {
     "@effect/vitest": "4.1.2",
@@ -31,18 +35,18 @@
     "vitest": "5.1.0"
   },
   "dependencies": {
-    "@graftland/graft": "0.1.0",
-    "@graftland/loader": "0.1.0",
-    "@graftland/hmr": "0.1.0",
-    "@graftland/create": "0.1.0",
-    "@graftland/package-manager": "0.1.0",
+    "@graftland/graft": "0.2.0-beta.1",
+    "@graftland/loader": "0.2.0-beta.1",
+    "@graftland/hmr": "0.2.0-beta.1",
+    "@graftland/create": "0.2.0-beta.1",
+    "@graftland/package-manager": "0.2.0-beta.1",
     "@effect/platform-node": "4.1.2"
   },
   "bin": {
     "graft": "./dist/bin.js"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && node scripts/schema.mjs",
     "test": "vitest run"
   }
 }

package/schema.json

@@ -0,0 +1,178 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"anyOf": [
+		{
+			"type": "array",
+			"items": {
+				"$ref": "#/definitions/Entry"
+			}
+		},
+		{
+			"type": "null"
+		}
+	],
+	"title": "Graft config file",
+	"description": "The entries that graft start loads. Each entry loads one plugin, or groups other entries.",
+	"definitions": {
+		"Intercept": {
+			"type": "object",
+			"properties": {
+				"effect/References/CurrentLogAnnotations": {
+					"type": "object",
+					"description": "Shallowly merges with outer annotations; configured keys win."
+				},
+				"effect/References/MinimumLogLevel": {
+					"type": "string",
+					"enum": [
+						"All",
+						"Fatal",
+						"Error",
+						"Warn",
+						"Info",
+						"Debug",
+						"Trace",
+						"None"
+					],
+					"description": "Replaces the outer minimum log level."
+				}
+			},
+			"additionalProperties": false,
+			"description": "Patches for references, applying to this entry and its descendants."
+		},
+		"Entry": {
+			"anyOf": [
+				{
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"description": "Identifies the entry. Graft adds one, and writes it to the file, if an entry has none."
+						},
+						"name": {
+							"type": "string",
+							"description": "The plugin's module: a relative path, a package name, or a short name. Ignored for groups."
+						},
+						"config": {
+							"type": "array",
+							"description": "The entries of this group.",
+							"items": {
+								"$ref": "#/definitions/Entry"
+							}
+						},
+						"disabled": {
+							"type": "boolean",
+							"description": "true unloads the entry but keeps it in the file."
+						},
+						"group": {
+							"type": "boolean",
+							"enum": [
+								true
+							],
+							"description": "true makes the entry a group of other entries."
+						},
+						"inject": {
+							"type": "array",
+							"description": "Service keys to wait for before loading the plugin, in addition to its own inject.",
+							"items": {
+								"type": "string"
+							}
+						},
+						"isolate": {
+							"type": "object",
+							"additionalProperties": {
+								"anyOf": [
+									{
+										"type": "boolean",
+										"enum": [
+											true
+										]
+									},
+									{
+										"type": "string"
+									}
+								]
+							},
+							"description": "Service or event keys to isolate: true for a private realm, or a label for a shared one."
+						},
+						"intercept": {
+							"$ref": "#/definitions/Intercept"
+						}
+					},
+					"required": [
+						"name",
+						"group"
+					],
+					"allOf": [
+						{
+							"type": "object",
+							"additionalProperties": {}
+						}
+					]
+				},
+				{
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"description": "Identifies the entry. Graft adds one, and writes it to the file, if an entry has none."
+						},
+						"name": {
+							"type": "string",
+							"description": "The plugin's module: a relative path, a package name, or a short name. Ignored for groups."
+						},
+						"config": {
+							"description": "The plugin's input. For a group, its list of entries."
+						},
+						"disabled": {
+							"type": "boolean",
+							"description": "true unloads the entry but keeps it in the file."
+						},
+						"group": {
+							"type": "boolean",
+							"enum": [
+								false
+							],
+							"description": "true makes the entry a group of other entries."
+						},
+						"inject": {
+							"type": "array",
+							"description": "Service keys to wait for before loading the plugin, in addition to its own inject.",
+							"items": {
+								"type": "string"
+							}
+						},
+						"isolate": {
+							"type": "object",
+							"additionalProperties": {
+								"anyOf": [
+									{
+										"type": "boolean",
+										"enum": [
+											true
+										]
+									},
+									{
+										"type": "string"
+									}
+								]
+							},
+							"description": "Service or event keys to isolate: true for a private realm, or a label for a shared one."
+						},
+						"intercept": {
+							"$ref": "#/definitions/Intercept"
+						}
+					},
+					"required": [
+						"name"
+					],
+					"allOf": [
+						{
+							"type": "object",
+							"additionalProperties": {}
+						}
+					]
+				}
+			]
+		}
+	}
+}

package/src/Manage.ts

@@ -4,13 +4,13 @@
 import * as Create from "@graftland/create"
 import * as PackageManager from "@graftland/package-manager"
 import {
-	Array as Arr,
+	Array,
 	Config,
 	Effect,
 	Option,
+	Predicate,
 	Record,
 	Schema,
-	String as Str,
 } from "effect"
 
 const report = (result: PackageManager.InstallResult) =>
@@ -18,16 +18,19 @@ const report = (result: PackageManager.InstallResult) =>
 		`${result.agent}: ${result.added.length} added, ${result.updated.length} updated, ${result.removed.length} removed`,
 	)
 
-/** Splits `name@range` (the scope's `@` excluded); a bare name means the latest version. */
-const parseSpec = (spec: string): readonly [string, string] =>
-	Option.match(
-		Option.filter(Str.lastIndexOf("@")(spec), (at) => at > 0),
-		{
-			onNone: () => [spec, "latest"] as const,
-			onSome: (at) =>
-				[Str.slice(0, at)(spec), Str.slice(at + 1)(spec)] as const,
-		},
-	)
+/**
+ * `name@range`, split at the last `@` so a scope's `@` stays in the name. A
+ * bare name means the latest version.
+ */
+const Spec = Schema.Union([
+	Schema.TemplateLiteralParser([
+		PackageManager.PackageName,
+		"@",
+		Schema.String,
+	]),
+	PackageManager.PackageName,
+])
+const decodeSpecs = Schema.decodeEffect(Schema.Array(Spec))
 
 const install = (
 	directory: string,
@@ -62,10 +65,21 @@ export const create = (options: {
 	})
 
 export const add = (specs: ReadonlyArray<string>) =>
-	install(".", Record.fromEntries(Arr.map(specs, parseSpec)))
+	Effect.flatMap(decodeSpecs(specs), (specs) =>
+		install(
+			".",
+			Record.fromEntries(
+				Array.map(specs, (spec) =>
+					Predicate.isString(spec)
+						? ([spec, "latest"] as const)
+						: ([spec[0], spec[2]] as const),
+				),
+			),
+		),
+	)
 
 export const remove = (names: ReadonlyArray<string>) =>
 	install(
 		".",
-		Record.fromEntries(Arr.map(names, (name) => [name, null] as const)),
+		Record.fromEntries(Array.map(names, (name) => [name, null] as const)),
 	)

package/src/Start.ts

@@ -4,41 +4,25 @@
 import { NodeServices } from "@effect/platform-node"
 import { Graft, Plugin } from "@graftland/graft"
 import * as Hmr from "@graftland/hmr"
-import { Include, Loader, ModuleResolver } from "@graftland/loader"
-import type { PlatformError } from "effect"
-import {
-	Array as Arr,
-	Effect,
-	FileSystem,
-	Layer,
-	Logger,
-	Path,
-	Queue,
-	Stream,
-	String as Str,
-} from "effect"
+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 { layer as intercepts } from "./internal/intercepts"
+import { watchModules } from "./internal/watch"
 
 export interface Options {
 	/** Path of the config file. */
 	readonly config: string
 	/** Reload plugin modules and the config file when they change. */
 	readonly watch: boolean
+	/**
+	 * A `.env` file that `!env` reads when the process environment does not set
+	 * a variable. With `watch`, changes to it are read again.
+	 */
+	readonly envFile?: string | undefined
 }
 
-const moduleExtensions = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]
-
-/** Whether a change to this file should reload plugin modules. */
-const isModule = (path: string) =>
-	!Str.includes("node_modules")(path) &&
-	Arr.some(moduleExtensions, (extension) => Str.endsWith(extension)(path))
-
-const describe = (result: Hmr.ReloadResult) =>
-	result._tag === "Reloaded"
-		? Effect.logInfo(`Reloaded ${result.entries.length} plugin module(s)`)
-		: Effect.logWarning(
-				`Restart required to pick up ${Arr.join(result.modules, ", ")}`,
-			)
-
 /**
  * Loads the entries of the config file and runs until interrupted. Plugin
  * modules are imported through the hot reloader, so bare specifiers resolve
@@ -46,9 +30,16 @@ const describe = (result: Hmr.ReloadResult) =>
  */
 export const run = (
 	options: Options,
-): Effect.Effect<never, Graft.ServiceConflict | PlatformError.BadArgument> =>
+): Effect.Effect<
+	never,
+	| Graft.ServiceConflict
+	| PlatformError.BadArgument
+	| PlatformError.PlatformError
+	| Schema.SchemaError
+	| Loader.StoreError
+	| Tree.InvalidOperation
+> =>
 	Effect.gen(function* () {
-		const fs = yield* FileSystem.FileSystem
 		const path = yield* Path.Path
 		const file = path.resolve(options.config)
 		const directory = path.dirname(file)
@@ -56,38 +47,30 @@ export const run = (
 		const hmr = yield* Hmr.make({ base: base.href })
 		const resolver = yield* ModuleResolver.make({
 			base: directory,
-			importer: hmr.importer,
+			importer: hmr.importerScoped,
 		})
 		yield* Graft.provide(ModuleResolver.ModuleResolver, resolver)
-		yield* Graft.plugin(Include.Include, { path: file, watch: options.watch })
+		const included = yield* Graft.plugin(Include.Include, {
+			path: file,
+			watch: options.watch,
+		})
+		yield* included.await
 		if (options.watch) {
-			// A save raises several events; a one-slot sliding queue folds them into one pending reload.
-			const changed = yield* Queue.sliding<void>(1)
-			// Only module changes reload code; the config file is watched by the loader itself.
-			yield* fs.watch(directory, { recursive: true }).pipe(
-				Stream.filter((event) => isModule(event.path)),
-				Stream.runForEach(() => Queue.offer(changed, undefined)),
-				Effect.forkScoped,
-			)
+			const { reload } = yield* EnvFile
+			const envFile = options.envFile
 			const reloader = Plugin.make({
 				name: "reloader",
-				inject: [Loader.Loader],
+				inject: [Loader.Loader, FileSystem.FileSystem, Path.Path],
 				apply: () =>
 					Effect.gen(function* () {
 						const loader = yield* Loader.Loader
-						yield* Queue.take(changed).pipe(
-							Effect.andThen(Effect.sleep("50 millis")),
-							Effect.andThen(Queue.clear(changed)),
-							Effect.andThen(hmr.reload),
-							Effect.flatMap(describe),
-							// Entries whose module failed to load get another chance with the new code.
-							Effect.andThen(loader.retry),
-							Effect.catchCause((cause) =>
-								Effect.logError("Reloading plugin modules failed", cause),
-							),
-							Effect.forever,
+						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)
@@ -105,6 +88,8 @@ export const run = (
 				Graft.layer,
 				Layer.mergeAll(
 					NodeServices.layer,
+					intercepts,
+					env(options.envFile).pipe(Layer.provide(NodeServices.layer)),
 					Logger.layer([Logger.consolePretty()]),
 				),
 			),

package/src/bin.ts

@@ -3,10 +3,9 @@
  * The `graft` executable. Running this module starts the program.
  */
 import { NodeRuntime, NodeServices } from "@effect/platform-node"
-import { Effect, FileSystem, Path, Schema } from "effect"
+import { Effect, Option } from "effect"
 import { Argument, Command, Flag } from "effect/cli"
-import * as Manage from "./Manage"
-import * as Start from "./Start"
+import { version } from "../package.json" with { type: "json" }
 
 const start = Command.make(
 	"start",
@@ -20,8 +19,22 @@ const start = Command.make(
 			Flag.withDescription("Reload plugins and config when files change"),
 			Flag.withDefault(false),
 		),
+		envFile: Flag.String("env-file").pipe(
+			Flag.withDescription(
+				"Read variables for !env from a .env file; the process environment takes precedence",
+			),
+			Flag.optional,
+		),
 	},
-	Start.run,
+	(options) =>
+		Effect.promise(() => import("./Start")).pipe(
+			Effect.flatMap((Start) =>
+				Start.run({
+					...options,
+					envFile: Option.getOrUndefined(options.envFile),
+				}),
+			),
+		),
 ).pipe(
 	Command.withDescription("Run the application described by a config file"),
 )
@@ -41,13 +54,19 @@ const create = Command.make(
 			Flag.withDefault(false),
 		),
 	},
-	Manage.create,
+	(options) =>
+		Effect.promise(() => import("./Manage")).pipe(
+			Effect.flatMap((Manage) => Manage.create(options)),
+		),
 ).pipe(Command.withDescription("Create a new Graft project"))
 
 const add = Command.make(
 	"add",
 	{ packages: Argument.variadic(Argument.String("package")) },
-	({ packages }) => Manage.add(packages),
+	({ packages }) =>
+		Effect.promise(() => import("./Manage")).pipe(
+			Effect.flatMap((Manage) => Manage.add(packages)),
+		),
 ).pipe(
 	Command.withDescription(
 		"Add dependencies, restoring the project if installing fails",
@@ -57,7 +76,10 @@ const add = Command.make(
 const remove = Command.make(
 	"remove",
 	{ packages: Argument.variadic(Argument.String("package")) },
-	({ packages }) => Manage.remove(packages),
+	({ packages }) =>
+		Effect.promise(() => import("./Manage")).pipe(
+			Effect.flatMap((Manage) => Manage.remove(packages)),
+		),
 ).pipe(
 	Command.withDescription(
 		"Remove dependencies, restoring the project if installing fails",
@@ -69,17 +91,7 @@ const graft = Command.make("graft").pipe(
 	Command.withSubcommands([start, create, add, remove]),
 )
 
-const Manifest = Schema.fromJsonString(
-	Schema.Struct({ version: Schema.String }),
+Command.run(graft, { version }).pipe(
+	Effect.provide(NodeServices.layer),
+	NodeRuntime.runMain,
 )
-
-Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem
-	const path = yield* Path.Path
-	const file = yield* path.fromFileUrl(
-		new URL("../package.json", import.meta.url),
-	)
-	const text = yield* fs.readFileString(file)
-	const { version } = yield* Schema.decodeEffect(Manifest)(text)
-	return yield* Command.run(graft, { version })
-}).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain)

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,
+	}
+}