@graftland/package-manager 0.1.0 → 0.2.0-beta.1

package/src/manifest.ts

@@ -1,10 +1,37 @@
-import { Array as Arr, Effect, Record, Schema, String as Str } from "effect"
+import {
+	Array,
+	Effect,
+	HashMap,
+	Chunk,
+	Option,
+	Record,
+	Schema,
+	String,
+} from "effect"
 
 export const PackageName = Schema.String.check(
-	Schema.isPattern(/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i),
+	Schema.isPattern(
+		/^(?!(?:node_modules|favicon\.ico)$)(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i,
+	),
 	Schema.isMaxLength(214),
+	Schema.isTrimmed(),
+)
+const isPackageName = Schema.is(PackageName)
+// A refined Record key filters unmatched keys. Validate names after retaining
+// every key so invalid input cannot silently become a partial change set.
+const dependencyNames = Schema.makeFilter(
+	(record: Readonly<Record<string, unknown>>) =>
+		Array.map(
+			Array.filter(Record.keys(record), (name) => !isPackageName(name)),
+			(name) => ({
+				path: [name],
+				issue: "Invalid dependency name",
+			}),
+		),
+)
+const Dependencies = Schema.Record(Schema.String, Schema.String).check(
+	dependencyNames,
 )
-const Dependencies = Schema.Record(PackageName, Schema.String)
 export const Manifest = Schema.StructWithRest(
 	Schema.Struct({
 		packageManager: Schema.optionalKey(Schema.String),
@@ -15,13 +42,17 @@ export const Manifest = Schema.StructWithRest(
 	[Schema.Record(Schema.String, Schema.Unknown)],
 )
 export type Manifest = typeof Manifest.Type
-export const decodeManifest = Schema.decodeUnknownEffect(
+const decodeJsonManifest = Schema.decodeUnknownEffect(
 	Schema.fromJsonString(Manifest),
 )
+// A BOM is a source-format marker, not part of the JSON value.
+export const decodeManifest = (source: string) =>
+	decodeJsonManifest(String.replace(/^\uFEFF/, "")(source))
+
 export const Changes = Schema.Record(
-	PackageName,
+	Schema.String,
 	Schema.Union([Schema.String.check(Schema.isPattern(/\S/)), Schema.Null]),
-)
+).check(dependencyNames)
 /** A spec adds or updates a dependency; null removes it from all dependency fields. */
 export type Changes = typeof Changes.Type
 export const fields = [
@@ -34,39 +65,212 @@ export const applyChanges = (
 	manifest: Manifest,
 	changes: Changes,
 ): Manifest => {
+	const edits = Record.toEntries(changes)
+	if (edits.length === 0) return manifest
 	let next = manifest
-	for (const [name, spec] of Record.toEntries(changes)) {
-		const existing = Arr.filter(fields, (field) =>
-			Record.has(next[field] ?? {}, name),
+	const additions = Array.flatMap(edits, ([name, spec]) =>
+		spec !== null &&
+		!Array.some(fields, (field) => Record.has(manifest[field] ?? {}, name))
+			? [[name, spec] as const]
+			: [],
+	)
+	for (const field of fields) {
+		const entries = Array.flatMap(
+			Record.toEntries(manifest[field] ?? {}),
+			([name, old]) => {
+				const spec = Record.has(changes, name) ? changes[name]! : old
+				return spec === null ? [] : [[name, spec] as const]
+			},
 		)
-		const targets =
-			spec === null
-				? fields
-				: existing.length > 0
-					? existing
-					: (["dependencies"] as const)
-		for (const field of targets) {
-			const deps = next[field] ?? {}
+		if (field === "dependencies" && additions.length > 0) {
 			next = {
 				...next,
-				[field]:
-					spec === null
-						? Record.remove(deps, name)
-						: Record.set(deps, name, spec),
+				[field]: Record.fromEntries([...entries, ...additions]),
 			}
+		} else if (manifest[field] !== undefined) {
+			next = { ...next, [field]: Record.fromEntries(entries) }
 		}
 	}
 	return next
 }
 
+const decodeKey = Schema.decodeEffect(Schema.fromJsonString(Schema.String))
+const encodeString = Schema.encodeEffect(Schema.fromJsonString(Schema.String))
+
+interface Member {
+	readonly name: string
+	readonly leading: string
+	readonly key: string
+	readonly colon: string
+	readonly value: string
+	readonly trailing: string
+}
+
+/** Read member spans from a JSON object already validated by decodeManifest. */
+const readObject = Effect.fnUntraced(function* (source: string) {
+	// Strings are single tokens, so punctuation inside them cannot affect nesting.
+	const tokens = Array.fromIterable(
+		String.matchAll(/"(?:\\[\s\S]|[^"\\])*"|[{}\[\]:,]|[^\s{}\[\]:,]+/g)(
+			source,
+		),
+	)
+	let members = Chunk.empty<Member>()
+	let cursor = 1
+	let start = (tokens[0]?.index ?? 0) + 1
+	while (cursor < tokens.length && tokens[cursor]?.[0] !== "}") {
+		const key = tokens[cursor]!
+		const valueStart = tokens[cursor + 2]!.index
+		cursor += 2
+		let depth = 0
+		let end = valueStart
+		do {
+			const token = tokens[cursor++]!
+			if (token[0] === "{" || token[0] === "[") depth++
+			if (token[0] === "}" || token[0] === "]") depth--
+			end = token.index! + token[0].length
+		} while (depth > 0)
+		members = Chunk.append(members, {
+			name: yield* decodeKey(key[0]),
+			leading: String.slice(start, key.index)(source),
+			key: key[0],
+			colon: String.slice(key.index! + key[0].length, valueStart)(source),
+			value: String.slice(valueStart, end)(source),
+			trailing:
+				tokens[cursor]?.[0] === ","
+					? String.slice(end, tokens[cursor]!.index)(source)
+					: "",
+		})
+		start = end
+		if (tokens[cursor]?.[0] !== ",") break
+		start = tokens[cursor++]!.index! + 1
+	}
+	const close = tokens[cursor]!.index
+	const tail = String.slice(start, close)(source)
+	return {
+		members: Chunk.toArray(members),
+		tail,
+		open: tokens[0]!.index!,
+		close,
+	}
+})
+
+/** Ordered edits preserve insertion order; None removes every occurrence. */
+type Edit = readonly [string, Option.Option<string>]
+type Edits = ReadonlyArray<Edit>
+
+const editObject = Effect.fnUntraced(function* (
+	source: string,
+	changes: Edits,
+) {
+	const { members, tail, open, close } = yield* readObject(source)
+	const edits = HashMap.fromIterable(changes)
+	const first = Array.head(members)
+	const lastOccurrences = HashMap.fromIterable(
+		Array.map(members, (member, index) => [member.name, index] as const),
+	)
+	const retained = Array.flatMap(members, (member, index) =>
+		Option.match(HashMap.get(edits, member.name), {
+			onNone: () => [member],
+			onSome: (change) =>
+				Option.match(change, {
+					// Removing every occurrence prevents an earlier value from becoming active.
+					onNone: () => [],
+					onSome: (value) => [
+						Option.getOrUndefined(HashMap.get(lastOccurrences, member.name)) ===
+						index
+							? { ...member, value }
+							: member,
+					],
+				}),
+		}),
+	)
+	const added = yield* Effect.forEach(
+		Array.filter(changes, ([name]) => !HashMap.has(lastOccurrences, name)),
+		Effect.fnUntraced(function* ([name, change]) {
+			if (Option.isNone(change)) return []
+			const key = yield* encodeString(name)
+			return [
+				{
+					name,
+					leading: Option.match(first, {
+						onNone: () => tail,
+						onSome: (member) => member.leading,
+					}),
+					key,
+					colon: Option.match(first, {
+						onNone: () => ": ",
+						onSome: (member) => member.colon,
+					}),
+					value: change.value,
+					trailing: "",
+				},
+			]
+		}),
+	)
+	return (
+		String.slice(0, open + 1)(source) +
+		Array.join(
+			Array.map(
+				[...retained, ...Array.flatten(added)],
+				(member) =>
+					member.leading +
+					member.key +
+					member.colon +
+					member.value +
+					member.trailing,
+			),
+			",",
+		) +
+		tail +
+		String.slice(close)(source)
+	)
+})
+
 export const encodeManifest = Effect.fnUntraced(function* (
 	manifest: Manifest,
 	original: string,
 ) {
-	const space = /^[{[]\r?\n([ \t]+)/.exec(original)?.[1] ?? 2
-	const text = yield* Schema.encodeEffect(
-		Schema.fromJsonString(Manifest, { space }),
-	)(manifest)
-	const eol = Str.includes("\r\n")(original) ? "\r\n" : "\n"
-	return Str.replaceAll("\n", eol)(text) + (/\r?\n$/.test(original) ? eol : "")
+	const before = yield* decodeManifest(original)
+	const { members } = yield* readObject(original)
+	const changes = yield* Effect.reduce(
+		fields,
+		() => Chunk.empty<Edit>(),
+		Effect.fnUntraced(function* (changes, field) {
+			const oldSpecs = HashMap.fromIterable(
+				Record.toEntries(before[field] ?? {}),
+			)
+			const nextSpecs = HashMap.fromIterable(
+				Record.toEntries(manifest[field] ?? {}),
+			)
+			const specs = yield* Effect.reduce(
+				Array.dedupe([
+					...Record.keys(before[field] ?? {}),
+					...Record.keys(manifest[field] ?? {}),
+				]),
+				() => Chunk.empty<Edit>(),
+				Effect.fnUntraced(function* (specs, name) {
+					const old = HashMap.get(oldSpecs, name)
+					const next = HashMap.get(nextSpecs, name)
+					if (Option.getOrUndefined(old) === Option.getOrUndefined(next))
+						return specs
+					const value = yield* Option.match(next, {
+						onNone: () => Effect.succeedNone,
+						onSome: (value) => encodeString(value).pipe(Effect.asSome),
+					})
+					return Chunk.append(specs, [name, value] as const)
+				}),
+			)
+			if (Chunk.isEmpty(specs)) return changes
+			const section = Array.findLast(members, (member) => member.name === field)
+			const source = Option.match(section, {
+				onNone: () => "{}",
+				onSome: (member) => member.value,
+			})
+			const edited = yield* editObject(source, Chunk.toArray(specs))
+			return Chunk.append(changes, [field, Option.some(edited)] as const)
+		}),
+	)
+	return Chunk.isEmpty(changes)
+		? original
+		: yield* editObject(original, Chunk.toArray(changes))
 })

package/src/process.ts

@@ -0,0 +1,122 @@
+// The spawner exposes no process-group existence check after kill loses errno.
+import * as NodeProcess from "node:process"
+import {
+	Array,
+	Cause,
+	Data,
+	Effect,
+	Exit,
+	PlatformError,
+	Schedule,
+	Schema,
+} from "effect"
+import type { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+const missingGroup = Schema.is(Schema.Struct({ code: Schema.Literal("ESRCH") }))
+const unsignallableGroup = Schema.is(
+	Schema.Struct({ code: Schema.Literal("EPERM") }),
+)
+// Node's kill(false) fallback loses errno, but has a specific signal-failure shape.
+const failedSignal = Schema.is(
+	Schema.Struct({ message: Schema.Literal("Failed to kill child process") }),
+)
+const isSignalFailure = (error: PlatformError.PlatformError) =>
+	error.reason.module === "ChildProcess" &&
+	error.reason.method === "kill" &&
+	(missingGroup(error.cause) ||
+		(error.reason._tag === "Unknown" && failedSignal(error.cause)))
+
+/** Signal zero checks the group without signalling any member. */
+export const groupExists = (pid: ChildProcessSpawner.ProcessId) =>
+	Effect.try({
+		try: () => {
+			NodeProcess.kill(-pid, 0)
+			return true
+		},
+		catch: (cause) =>
+			PlatformError.systemError({
+				_tag: "Unknown",
+				module: "ChildProcess",
+				method: "probeGroup",
+				cause,
+			}),
+	}).pipe(
+		Effect.catchIf(
+			(error) => missingGroup(error.cause) || unsignallableGroup(error.cause),
+			// EPERM can mean zombies on macOS. It never establishes group absence.
+			(error) => Effect.succeed(!missingGroup(error.cause)),
+		),
+	)
+
+/** Close the original group, including descendants that remain in it after leader exit. */
+export const closeProcess = (
+	process: ChildProcessSpawner.ChildProcessHandle,
+	options: ChildProcess.KillOptions,
+	probe: typeof groupExists = groupExists,
+) =>
+	Effect.gen(function* () {
+		const killed = yield* Effect.suspend(() => process.kill(options)).pipe(
+			Effect.exit,
+		)
+		// Windows retains its as-is adapter contract; POSIX requires group evidence.
+		if (NodeProcess.platform === "win32") return yield* killed
+		const checked = yield* Effect.suspend(() => probe(process.pid)).pipe(
+			Effect.exit,
+			Effect.repeat({
+				while: (exit) => Exit.isSuccess(exit) && exit.value,
+				times: 100,
+				schedule: Schedule.spaced("20 millis"),
+			}),
+		)
+		if (Exit.isFailure(checked))
+			return yield* Effect.failCause(
+				Exit.isFailure(killed)
+					? Cause.combine(killed.cause, checked.cause)
+					: checked.cause,
+			)
+		if (checked.value) {
+			if (Exit.isFailure(killed)) return yield* Effect.failCause(killed.cause)
+			return yield* PlatformError.systemError({
+				_tag: "Unknown",
+				module: "ChildProcess",
+				method: "confirmGroupStopped",
+				description: `Process group ${process.pid} still exists after the two-second confirmation window`,
+			})
+		}
+		if (Exit.isFailure(killed)) {
+			// Absence resolves only a failed signal to a nonexistent group, not other cleanup failures.
+			const remaining = Array.filter(
+				killed.cause.reasons,
+				(reason) =>
+					!(Cause.isFailReason(reason) && isSignalFailure(reason.error)),
+			)
+			if (remaining.length > 0)
+				return yield* Effect.failCause(Cause.fromReasons(remaining))
+		}
+	})
+
+export type Termination = Data.TaggedEnum<{
+	OriginalGroupStopped: {}
+	Unconfirmed: { readonly cause: Cause.Cause<PlatformError.PlatformError> }
+}>
+
+export const Termination = Data.taggedEnum<Termination>()
+
+export type OriginalGroupStopped = Data.TaggedEnum.Value<
+	Termination,
+	"OriginalGroupStopped"
+>
+
+/** Only proves termination of the original group, not detached groups or daemons. */
+export const terminateProcess = (
+	process: ChildProcessSpawner.ChildProcessHandle,
+	options: ChildProcess.KillOptions,
+) =>
+	Effect.suspend(() => closeProcess(process, options)).pipe(
+		Effect.exit,
+		Effect.map((exit): Termination =>
+			Exit.isSuccess(exit)
+				? Termination.OriginalGroupStopped()
+				: Termination.Unconfirmed({ cause: exit.cause }),
+		),
+	)

package/src/snapshot.ts

@@ -0,0 +1,261 @@
+import {
+	Array,
+	Cause,
+	Effect,
+	Equal,
+	Exit,
+	Option,
+	Random,
+	Schema,
+	Scope,
+} from "effect"
+import type { FileSystem, Path, PlatformError } from "effect"
+/** File writes have completed and the original installer group is stopped or absent. */
+export interface ManagedWritersIdle {
+	readonly _tag: "ManagedWritersIdle"
+}
+
+export interface SnapshotCleanupFailure {
+	readonly snapshotDirectory: string
+	readonly cause: Cause.Cause<PlatformError.PlatformError>
+}
+
+/** Separate the transaction's outcome from disposal of its snapshot. */
+export const withSnapshot = <A, E, R>(
+	fs: FileSystem.FileSystem,
+	canDelete: Effect.Effect<boolean>,
+	use: (directory: string) => Effect.Effect<A, E, R>,
+) =>
+	Effect.uninterruptibleMask((resume) =>
+		Effect.gen(function* () {
+			const snapshotDirectory = yield* fs.makeTempDirectory({
+				prefix: "graft-recovery-",
+			})
+			const outcome = yield* resume(
+				Effect.suspend(() => use(snapshotDirectory)),
+			).pipe(Effect.exit)
+			const cleanup = (yield* canDelete)
+				? yield* Effect.suspend(() =>
+						fs.remove(snapshotDirectory, { recursive: true }),
+					).pipe(Effect.exit)
+				: Exit.void
+			if (Exit.isFailure(outcome)) {
+				return yield* Effect.failCause(
+					Exit.isFailure(cleanup)
+						? Cause.combine(outcome.cause, cleanup.cause)
+						: outcome.cause,
+				)
+			}
+			return yield* resume(
+				Effect.succeed({
+					value: outcome.value,
+					snapshotCleanupFailure: Exit.isFailure(cleanup)
+						? Option.some<SnapshotCleanupFailure>({
+								snapshotDirectory,
+								cause: cleanup.cause,
+							})
+						: Option.none<SnapshotCleanupFailure>(),
+				}),
+			).pipe(
+				// Cancellation can prevent delivery, but must not hide a cleanup failure.
+				Effect.onExit((exit) =>
+					Exit.isFailure(exit) && Exit.isFailure(cleanup)
+						? Effect.failCause(cleanup.cause)
+						: Effect.void,
+				),
+			)
+		}),
+	)
+
+export class UnsupportedFileTypeError extends Schema.TaggedError<
+	UnsupportedFileTypeError,
+	{ readonly brand: unique symbol }
+>()("UnsupportedFileTypeError", {
+	path: Schema.String,
+	fileType: Schema.String,
+	message: Schema.String,
+}) {}
+
+interface RegularFileMetadata {
+	readonly mode: number
+	readonly uid: Option.Option<number>
+	readonly gid: Option.Option<number>
+}
+export interface Contents extends RegularFileMetadata {
+	readonly bytes: Uint8Array
+}
+export interface Backup {
+	readonly name: string
+	readonly file: string
+	readonly contents: Option.Option<Contents>
+}
+
+/** lstat distinguishes missing paths from links, including dangling links. */
+export const inspectManagedFiles = Effect.fnUntraced(function* (
+	fs: FileSystem.FileSystem,
+	path: Path.Path,
+	directory: string,
+	names: ReadonlyArray<string>,
+) {
+	return yield* Effect.forEach(names, (name) =>
+		Effect.gen(function* () {
+			const file = path.join(directory, name)
+			const metadata = yield* fs.lstat(file).pipe(
+				Effect.flatMap((info) =>
+					info.type === "File"
+						? Effect.succeed<RegularFileMetadata>({
+								mode: info.mode & 0o7777,
+								uid: info.uid,
+								gid: info.gid,
+							})
+						: Effect.fail(
+								UnsupportedFileTypeError.make({
+									path: file,
+									fileType: info.type,
+									message: `Managed paths must be regular files or absent: ${file} is ${info.type}`,
+								}),
+							),
+				),
+				Effect.asSome,
+				// Only an entirely missing-path failure establishes absence.
+				Effect.catchCauseIf(
+					(cause) =>
+						Array.every(
+							cause.reasons,
+							(reason) =>
+								Cause.isFailReason(reason) &&
+								reason.error._tag === "PlatformError" &&
+								reason.error.reason.module === "FileSystem" &&
+								reason.error.reason.method === "lstat" &&
+								reason.error.reason._tag === "NotFound",
+						),
+					() => Effect.succeedNone,
+				),
+			)
+			return { name, file, metadata }
+		}),
+	)
+})
+
+const encodeInventory = Schema.encodeEffect(
+	Schema.fromJsonString(
+		Schema.Struct({
+			directory: Schema.String,
+			agent: Schema.String,
+			files: Schema.Array(
+				Schema.Struct({
+					name: Schema.String,
+					backup: Schema.NullOr(Schema.String),
+					mode: Schema.NullOr(Schema.Int),
+					uid: Schema.NullOr(Schema.Int),
+					gid: Schema.NullOr(Schema.Int),
+				}),
+			),
+		}),
+		{ space: 2 },
+	),
+)
+
+/** Persist every byte before allowing the installer to modify the project. */
+export const writeSnapshot = Effect.fnUntraced(function* (
+	fs: FileSystem.FileSystem,
+	path: Path.Path,
+	snapshotDirectory: string,
+	directory: string,
+	agent: string,
+	backups: ReadonlyArray<Backup>,
+) {
+	const files = yield* Effect.forEach(backups, (entry, index) =>
+		Effect.gen(function* () {
+			if (Option.isNone(entry.contents))
+				return {
+					name: entry.name,
+					backup: null,
+					mode: null,
+					uid: null,
+					gid: null,
+				}
+			const { bytes, mode, uid, gid } = entry.contents.value
+			const backup = `${index}.bin`
+			yield* fs.writeFile(path.join(snapshotDirectory, backup), bytes, {
+				mode: 0o600,
+			})
+			return {
+				name: entry.name,
+				backup,
+				mode,
+				uid: Option.getOrNull(uid),
+				gid: Option.getOrNull(gid),
+			}
+		}),
+	)
+	const inventory = yield* encodeInventory({ directory, agent, files })
+	yield* fs.writeFileString(
+		path.join(snapshotDirectory, "snapshot.json"),
+		inventory,
+		{ mode: 0o600 },
+	)
+	return {
+		// The caller must establish that file writes and the original process group have stopped.
+		restore: (_idle: ManagedWritersIdle) =>
+			Array.reduce<Backup, Effect.Effect<void, PlatformError.PlatformError>>(
+				backups,
+				Effect.void,
+				(previous, { file, contents }) =>
+					previous.pipe(
+						Effect.onExit(() =>
+							Option.match(contents, {
+								onNone: () => fs.remove(file, { force: true }),
+								onSome: (contents) => restoreFile(fs, path, file, contents),
+							}),
+						),
+					),
+			),
+	}
+}, Effect.uninterruptible)
+
+/** Create privately and restore metadata before making the replacement visible. */
+const restoreFile = Effect.fnUntraced(function* (
+	fs: FileSystem.FileSystem,
+	path: Path.Path,
+	target: string,
+	contents: Contents,
+) {
+	yield* fs.makeDirectory(path.dirname(target), { recursive: true })
+	const suffix = yield* Random.nextIntBetween(0, 0xffffffff)
+	const temporary = `${target}.${suffix.toString(16)}.tmp`
+	yield* Effect.acquireUseRelease(
+		Scope.make(),
+		(scope) =>
+			Effect.acquireUseRelease(
+				fs
+					.open(temporary, { flag: "wx", mode: 0o600 })
+					.pipe(Effect.provideService(Scope.Scope, scope)),
+				(file) =>
+					Effect.gen(function* () {
+						yield* file.writeAll(contents.bytes)
+						const current = yield* file.stat
+						const { uid, gid } = contents
+						if (
+							Option.isSome(uid) &&
+							Option.isSome(gid) &&
+							(!Equal.equals(uid, current.uid) ||
+								!Equal.equals(gid, current.gid))
+						) {
+							yield* fs.chown(temporary, uid.value, gid.value)
+						}
+						yield* fs.chmod(temporary, contents.mode)
+						yield* file.sync
+						yield* Scope.close(scope, Exit.void)
+						yield* fs.rename(temporary, target)
+					}),
+				(_, exit) =>
+					Exit.isSuccess(exit)
+						? Effect.void
+						: Scope.close(scope, exit).pipe(
+								Effect.onExit(() => fs.remove(temporary, { force: true })),
+							),
+			),
+		(scope, exit) => Scope.close(scope, exit),
+	)
+})