@graftland/cli 0.4.2 → 0.5.0

package/src/Manage.ts

@@ -12,6 +12,7 @@ import {
 	Record,
 	Schema,
 } from "effect"
+import { CliError } from "effect/cli"
 
 import * as Create from "@graftland/create"
 import * as PackageManager from "@graftland/package-manager"
@@ -20,6 +21,7 @@ import { parseDocument, type Document } from "yaml"
 
 import { CommandConfigError } from "./Commands"
 import { home } from "./internal/commandConfig"
+import { schemaFileName } from "./internal/schemaFileName"
 
 const report = (result: PackageManager.InstallResult) =>
 	Effect.logInfo(
@@ -52,6 +54,29 @@ const Spec = Schema.Union([
 ])
 const decodeSpecs = Schema.decodeEffect(Schema.Array(Spec))
 
+/**
+ * Regenerates the project's editor schema, but only when it has one, so that
+ * the plugins just added or removed are checked. Imports no plugin.
+ */
+const refreshSchema = Effect.fnUntraced(function* (directory: string) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const root = path.resolve(directory)
+	const file = path.join(root, schemaFileName)
+	if (!(yield* fs.exists(file))) return
+	const EditorSchema = yield* Effect.promise(
+		() => import("./internal/schemaFile"),
+	).pipe(Effect.uninterruptible)
+	yield* EditorSchema.write(root, file).pipe(
+		Effect.mapError((cause) =>
+			CliError.UserError.make({
+				cause,
+				userMessage: `Dependencies changed, but ${file} was not regenerated: ${cause.message}`,
+			}),
+		),
+	)
+})
+
 const install = Effect.fn("Manage.install")(function* (
 	directory: string,
 	changes: Readonly<Record<string, string | null>>,
@@ -64,6 +89,7 @@ const install = Effect.fn("Manage.install")(function* (
 	const manager = yield* PackageManager.make({ directory, userAgent })
 	const result = yield* manager.install(decoded)
 	yield* report(result)
+	yield* refreshSchema(directory)
 })
 
 export const add = Effect.fn("Manage.add")(function* (
@@ -144,11 +170,23 @@ export const addPlugin = Effect.fn("Manage.addPlugin")(function* (
 	const path = yield* Path.Path
 	const fs = yield* FileSystem.FileSystem
 	const directory = global ? yield* home : path.resolve(".")
-	const packageName = Create.pluginPackage(name)
+	if (global) yield* prepareHome(directory)
+	const userAgent = yield* Config.String("npm_config_user_agent").pipe(
+		Config.withDefault(""),
+	)
+	const packageName = yield* Create.pluginPackage(name, {
+		directory,
+		userAgent,
+	}).pipe(
+		Effect.mapError((error) =>
+			error._tag === "PluginNotFound" || error._tag === "AmbiguousPluginName"
+				? CliError.UserError.make({ cause: error, userMessage: error.message })
+				: error,
+		),
+	)
 	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)

package/src/Start.ts

@@ -153,7 +153,7 @@ export const run = (
 			const { reload: reloadDir } = yield* EnvDir
 			const { envFile, envDir } = options
 			const reloader = Plugin.make({
-				name: "reloader",
+				name: "@graftland/cli/Start/reloader",
 				inject: [Loader.Loader, FileSystem.FileSystem, Path.Path],
 				apply: () =>
 					Effect.gen(function* () {

package/src/bin.ts

@@ -12,6 +12,7 @@ import { Graft } from "@graftland/graft"
 import { version } from "../package.json" with { type: "json" }
 import { platform } from "./Application"
 import * as Host from "./internal/commandHost"
+import { schemaFileName } from "./internal/schemaFileName"
 
 const start = Command.make(
 	"start",
@@ -97,6 +98,26 @@ const remove = Command.make(
 	),
 )
 
+const schema = Command.make(
+	"schema",
+	{
+		output: Flag.String("output").pipe(
+			Flag.withAlias("o"),
+			Flag.withDescription("Path of the schema file"),
+			Flag.withDefault(schemaFileName),
+		),
+	},
+	({ output }) =>
+		Effect.promise(() => import("./internal/schemaFile")).pipe(
+			Effect.uninterruptible,
+			Effect.flatMap((EditorSchema) => EditorSchema.write(".", output)),
+		),
+).pipe(
+	Command.withDescription(
+		"Write the JSON Schema of graft.yml, with the config of installed plugins",
+	),
+)
+
 const graft = Command.make("graft").pipe(
 	Command.withDescription("Run and manage Graft applications"),
 	Command.withSharedFlags({
@@ -113,7 +134,7 @@ const program = Effect.gen(function* () {
 			Effect.gen(function* () {
 				const context = yield* Layer.build(Graft.layer)
 				return yield* Host.run(
-					[start, create, add, remove],
+					[start, create, add, remove, schema],
 					graft,
 					version,
 					args,

package/src/internal/schemaFile.ts

@@ -0,0 +1,186 @@
+/** Composes the editor schema of a project's config file from its installed plugins. */
+import {
+	Array,
+	Effect,
+	FileSystem,
+	Option,
+	Path,
+	Predicate,
+	Record,
+	Schema,
+	type PlatformError,
+} from "effect"
+
+import { make } from "./configSchema"
+import * as Importer from "./importer"
+
+/** A dependency's `./schema` export could not be read. */
+export class SchemaRegistrationError extends Schema.TaggedError<
+	SchemaRegistrationError,
+	{ readonly brand: unique symbol }
+>()("SchemaRegistrationError", {
+	packageName: Schema.String,
+	detail: Schema.String,
+	cause: Schema.optionalKey(Schema.Unknown),
+}) {
+	override get message() {
+		return `${this.packageName}/schema: ${this.detail}`
+	}
+}
+
+const Dependencies = Schema.optionalKey(
+	Schema.Record(Schema.String, Schema.String),
+)
+const ProjectManifest = Schema.fromJsonString(
+	Schema.Struct({
+		dependencies: Dependencies,
+		devDependencies: Dependencies,
+		optionalDependencies: Dependencies,
+	}),
+)
+const InstalledManifest = Schema.fromJsonString(
+	Schema.Struct({
+		exports: Schema.optionalKey(Schema.Unknown),
+		dependencies: Dependencies,
+		peerDependencies: Dependencies,
+	}),
+)
+const Registrations = Schema.Array(
+	Schema.Struct({
+		names: Schema.Array(Schema.String),
+		schema: Schema.Record(Schema.String, Schema.Unknown),
+		required: Schema.optionalKey(Schema.Boolean),
+	}),
+)
+
+/**
+ * The manifest of an installed package, looked up as Node does: in
+ * `node_modules` of the directory and then of each parent, so hoisted
+ * workspace installs are found.
+ */
+const installedManifest = (
+	directory: string,
+	packageName: string,
+): Effect.Effect<
+	Option.Option<string>,
+	PlatformError.PlatformError,
+	FileSystem.FileSystem | Path.Path
+> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const file = path.join(
+			directory,
+			"node_modules",
+			packageName,
+			"package.json",
+		)
+		if (yield* fs.exists(file)) return Option.some(file)
+		const parent = path.dirname(directory)
+		return parent === directory
+			? Option.none()
+			: yield* installedManifest(parent, packageName)
+	})
+
+/**
+ * Whether an installed dependency is a plugin package that exports `./schema`,
+ * read without importing it. Other packages, such as `effect`, may export a
+ * `./schema` of their own.
+ */
+const exportsSchema = Effect.fnUntraced(function* (
+	directory: string,
+	packageName: string,
+) {
+	const fs = yield* FileSystem.FileSystem
+	const file = yield* installedManifest(directory, packageName)
+	if (Option.isNone(file)) {
+		yield* Effect.logWarning(
+			`${packageName} is not installed; its config is left open`,
+		)
+		return false
+	}
+	const text = yield* fs.readFileString(file.value)
+	const manifest = yield* Schema.decodeEffect(InstalledManifest)(text)
+	return (
+		Predicate.hasProperty(manifest.exports, "./schema") &&
+		(Record.has(manifest.dependencies ?? {}, "@graftland/graft") ||
+			Record.has(manifest.peerDependencies ?? {}, "@graftland/graft"))
+	)
+})
+
+const load = Effect.fnUntraced(function* (
+	importer: (specifier: string) => Promise<unknown>,
+	packageName: string,
+) {
+	const failed = (detail: string) => (cause: unknown) =>
+		SchemaRegistrationError.make({ packageName, detail, cause })
+	const module = yield* Effect.tryPromise({
+		try: () => importer(`${packageName}/schema`),
+		catch: failed("cannot be imported"),
+	})
+	if (
+		!Predicate.hasProperty(module, "entries") ||
+		!Predicate.isFunction(module.entries)
+	)
+		return yield* SchemaRegistrationError.make({
+			packageName,
+			detail: "does not export an entries function",
+		})
+	const entries = module.entries
+	const value = yield* Effect.try({
+		try: () => entries(),
+		catch: failed("entries() threw"),
+	})
+	return yield* Schema.decodeUnknownEffect(Registrations)(value).pipe(
+		Effect.mapError(failed("entries() returned invalid registrations")),
+	)
+})
+
+/**
+ * The registrations exported as `./schema` by the dependencies in the
+ * project's package.json. Only these modules are imported, never the plugins.
+ */
+export const registrations = Effect.fn("EditorSchema.registrations")(function* (
+	directory: string,
+) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const text = yield* fs.readFileString(path.join(directory, "package.json"))
+	const manifest = yield* Schema.decodeEffect(ProjectManifest)(text)
+	const names = Array.dedupe(
+		Array.flatMap(
+			[
+				manifest.dependencies,
+				manifest.devDependencies,
+				manifest.optionalDependencies,
+			],
+			(dependencies) => Record.keys(dependencies ?? {}),
+		),
+	)
+	const plugins = yield* Effect.filter(names, (name) =>
+		exportsSchema(directory, name),
+	)
+	const importer = yield* Importer.make(directory)
+	const loaded = yield* Effect.forEach(plugins, (name) => load(importer, name))
+	return { plugins, entries: Array.flatten(loaded) }
+}, Effect.scoped)
+
+const encode = Schema.encodeEffect(
+	Schema.fromJsonString(Schema.Unknown, { space: "\t" }),
+)
+
+/** Writes the editor schema for the project in a directory. */
+export const write = Effect.fn("EditorSchema.write")(function* (
+	directory: string,
+	output: string,
+) {
+	const fs = yield* FileSystem.FileSystem
+	const { plugins, entries } = yield* registrations(directory)
+	const text = yield* encode(make(entries))
+	yield* fs.writeFileString(output, text + "\n")
+	yield* Effect.logInfo(
+		plugins.length === 0
+			? `Wrote ${output}; no dependency exports ./schema`
+			: `Wrote ${output} with ${Array.join(plugins, ", ")}`,
+	)
+})

package/src/internal/schemaFileName.ts

@@ -0,0 +1,2 @@
+/** The editor schema that `graft schema` writes, and that add, remove and create keep current. */
+export const schemaFileName = "graft.schema.json"

package/src/internal/watch.ts

@@ -1,5 +1,6 @@
 import { Array, Cause, Effect, Exit, Stream, String } from "effect"
 
+import type { Graft } from "@graftland/graft"
 import type * as Hmr from "@graftland/hmr"
 
 import { observeShutdown } from "./observeShutdown"
@@ -11,16 +12,40 @@ export const isModule = (path: string) =>
 	!Array.contains(String.split(/[/\\]/)(path), "node_modules") &&
 	Array.some(moduleExtensions, (extension) => String.endsWith(extension)(path))
 
+/** One warning per failed or timed-out plugin; failures retain their full cause. */
+const rolledBack = (failures: ReadonlyArray<Graft.ReplacementFailure>) =>
+	Effect.forEach(
+		failures,
+		(failure) =>
+			(failure._tag === "Failed"
+				? Effect.logWarning(
+						`Kept the previous code: plugin "${failure.plugin}" failed to start`,
+						failure.cause,
+					)
+				: Effect.logWarning(
+						`Kept the previous code: plugin "${failure.plugin}" did not start in time`,
+					)
+			).pipe(
+				Effect.annotateLogs({
+					"graft.fork": failure.fork,
+					"graft.plugin": failure.plugin,
+				}),
+			),
+		{ discard: true },
+	)
+
 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, ", ")}`,
-			)
+		: result._tag === "RolledBack"
+			? rolledBack(result.failures)
+			: 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>(