@effected/package-json 0.7.3 → 0.9.0

package/License.js

@@ -10,7 +10,7 @@ import { isValidExpression } from "@effected/spdx";
 *
 * @public
 */
-var InvalidSpdxLicenseError = class extends Schema.TaggedErrorClass()("InvalidSpdxLicenseError", { 
+var InvalidSpdxLicenseError = class extends Schema.TaggedError()("InvalidSpdxLicenseError", { 
 /** The raw input string that failed validation. */
 input: Schema.String }) {
 	get message() {

package/Package.js

@@ -1,7 +1,8 @@
 import { Dependency } from "./Dependency.js";
 import { DevEnginesSchema } from "./DevEngines.js";
 import { InvalidSpdxLicenseError, SpdxLicense, isValidSpdx } from "./License.js";
-import { renderJson, resolveIndent } from "./internal/format.js";
+import { renderJson, resolveFormatOptions } from "./internal/format.js";
+import { makeWire } from "./internal/wire.js";
 import { PackageManager } from "./PackageManager.js";
 import { InvalidPackageNameError, PackageName } from "./PackageName.js";
 import { Person } from "./Person.js";
@@ -80,42 +81,13 @@ const RepositoryField = Schema.Union([Schema.String, Schema.Record(Schema.String
 *
 * @public
 */
-var PackageDecodeError = class extends Schema.TaggedErrorClass()("PackageDecodeError", { 
+var PackageDecodeError = class extends Schema.TaggedError()("PackageDecodeError", { 
 /** The underlying `SchemaError`, preserved structurally rather than stringified. */
 cause: Schema.Defect() }) {
 	get message() {
 		return "Failed to decode package.json";
 	}
 };
-const resolveFormatOptions = (options) => ({
-	indent: resolveIndent(options?.indent, options?.sourceText),
-	sort: options?.sort ?? true,
-	stripEmpty: options?.stripEmpty ?? true,
-	newline: options?.newline ?? true
-});
-const RawJson = Schema.Record(Schema.String, Schema.Unknown);
-const makeWire = (Class) => {
-	const knownKeys = new Set(Object.keys(Class.fields).filter((k) => k !== "rest"));
-	return RawJson.pipe(Schema.decodeTo(Class, SchemaTransformation.transform({
-		decode: (raw) => {
-			const known = {};
-			const rest = {};
-			for (const [key, value] of Object.entries(raw)) if (knownKeys.has(key)) known[key] = value;
-			else rest[key] = value;
-			return {
-				...known,
-				rest
-			};
-		},
-		encode: (encoded) => {
-			const { rest, ...known } = encoded;
-			return {
-				...rest ?? {},
-				...known
-			};
-		}
-	})));
-};
 /**
 * A package.json document as a rich `Schema.Class`: typed known fields, a
 * `rest` catch-all preserving unknown top-level fields across a read/edit/write

package/PackageJsonFile.js

@@ -1,4 +1,6 @@
 import { Package } from "./Package.js";
+import { PackageJsonFormat } from "./PackageJsonFormat.js";
+import { PackageManifest } from "./PackageManifest.js";
 import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
 
 //#region src/PackageJsonFile.ts
@@ -8,7 +10,7 @@ import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
 *
 * @public
 */
-var PackageJsonReadError = class extends Schema.TaggedErrorClass()("PackageJsonReadError", {
+var PackageJsonReadError = class extends Schema.TaggedError()("PackageJsonReadError", {
 	/** The path that could not be read. */
 	path: Schema.String,
 	/** The underlying failure, preserved structurally. */
@@ -24,7 +26,7 @@ var PackageJsonReadError = class extends Schema.TaggedErrorClass()("PackageJsonR
 *
 * @public
 */
-var PackageJsonNotFoundError = class extends Schema.TaggedErrorClass()("PackageJsonNotFoundError", { 
+var PackageJsonNotFoundError = class extends Schema.TaggedError()("PackageJsonNotFoundError", { 
 /** The path where package.json was expected. */
 path: Schema.String }) {
 	get message() {
@@ -36,7 +38,7 @@ path: Schema.String }) {
 *
 * @public
 */
-var PackageJsonParseError = class extends Schema.TaggedErrorClass()("PackageJsonParseError", {
+var PackageJsonParseError = class extends Schema.TaggedError()("PackageJsonParseError", {
 	/** The path whose contents failed to parse as JSON. */
 	path: Schema.String,
 	/** The underlying `SyntaxError`, preserved structurally. */
@@ -53,7 +55,7 @@ var PackageJsonParseError = class extends Schema.TaggedErrorClass()("PackageJson
 *
 * @public
 */
-var PackageJsonWriteError = class extends Schema.TaggedErrorClass()("PackageJsonWriteError", {
+var PackageJsonWriteError = class extends Schema.TaggedError()("PackageJsonWriteError", {
 	/** The path that could not be written. */
 	path: Schema.String,
 	/** The underlying filesystem failure, preserved structurally. Narrowed to the write failure only. */
@@ -88,40 +90,63 @@ var PackageJsonFile = class PackageJsonFile extends Context.Service()("@effected
 	static make = Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
-		return {
-			read: Effect.fn("PackageJsonFile.read")(function* (target) {
-				const content = yield* fs.readFileString(target).pipe(Effect.mapError((cause) => cause.reason._tag === "NotFound" ? new PackageJsonNotFoundError({ path: target }) : new PackageJsonReadError({
+		const readText = (target) => fs.readFileString(target).pipe(Effect.mapError((cause) => cause.reason._tag === "NotFound" ? new PackageJsonNotFoundError({ path: target }) : new PackageJsonReadError({
+			path: target,
+			cause
+		})));
+		const readJson = (target) => Effect.gen(function* () {
+			const content = yield* readText(target);
+			return yield* Effect.try({
+				try: () => JSON.parse(content),
+				catch: (cause) => new PackageJsonParseError({
 					path: target,
 					cause
-				})));
-				const json = yield* Effect.try({
-					try: () => JSON.parse(content),
-					catch: (cause) => new PackageJsonParseError({
-						path: target,
-						cause
-					})
-				});
-				return yield* Package.decode(json);
+				})
+			});
+		});
+		const withPreservedSource = (target, options) => Effect.gen(function* () {
+			if (options?.indent !== "preserve" || options.sourceText !== void 0) return options;
+			const existing = yield* fs.readFileString(target).pipe(Effect.catch(() => Effect.succeed(void 0)));
+			return existing === void 0 ? options : {
+				...options,
+				sourceText: existing
+			};
+		});
+		const writeText = (target, json) => Effect.gen(function* () {
+			const directory = path.dirname(target);
+			yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError((cause) => new PackageJsonWriteError({
+				path: target,
+				cause
+			})));
+			yield* fs.writeFileString(target, json).pipe(Effect.mapError((cause) => new PackageJsonWriteError({
+				path: target,
+				cause
+			})));
+		});
+		return {
+			read: Effect.fn("PackageJsonFile.read")(function* (target) {
+				return yield* Package.decode(yield* readJson(target));
 			}),
 			write: Effect.fn("PackageJsonFile.write")(function* (target, pkg, options) {
-				let effective = options;
-				if (options?.indent === "preserve" && options.sourceText === void 0) {
-					const existing = yield* fs.readFileString(target).pipe(Effect.catch(() => Effect.succeed(void 0)));
-					if (existing !== void 0) effective = {
-						...options,
-						sourceText: existing
-					};
-				}
-				const json = pkg.toJsonString(effective);
-				const directory = path.dirname(target);
-				yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError((cause) => new PackageJsonWriteError({
-					path: target,
-					cause
-				})));
-				yield* fs.writeFileString(target, json).pipe(Effect.mapError((cause) => new PackageJsonWriteError({
+				const effective = yield* withPreservedSource(target, options);
+				yield* writeText(target, pkg.toJsonString(effective));
+			}),
+			readManifest: Effect.fn("PackageJsonFile.readManifest")(function* (target) {
+				return yield* PackageManifest.decode(yield* readJson(target));
+			}),
+			writeManifest: Effect.fn("PackageJsonFile.writeManifest")(function* (target, manifest, options) {
+				const effective = yield* withPreservedSource(target, options);
+				yield* writeText(target, manifest.toJsonString(effective));
+			}),
+			modify: Effect.fn("PackageJsonFile.modify")(function* (target, edits) {
+				const source = yield* readText(target);
+				let text = source;
+				for (const edit of edits) text = yield* PackageJsonFormat.modifyToString(text, edit.path, edit.value).pipe(Effect.catchTag("PackageJsonSyntaxError", (cause) => new PackageJsonParseError({
 					path: target,
 					cause
 				})));
+				if (text !== source) yield* writeText(target, text);
+				return text;
 			})
 		};
 	});

package/PackageJsonFormat.js

@@ -1,5 +1,6 @@
-import { renderJson, resolveIndent, sortKeys } from "./internal/format.js";
-import { Result, Schema } from "effect";
+import { detectIndent, renderJson, resolveIndent, sortKeys } from "./internal/format.js";
+import { JsoncEdit, JsoncModifier } from "@effected/jsonc";
+import { Effect, Result, Schema } from "effect";
 
 //#region src/PackageJsonFormat.ts
 /**
@@ -14,7 +15,7 @@ import { Result, Schema } from "effect";
 *
 * @public
 */
-var PackageJsonSyntaxError = class extends Schema.TaggedErrorClass()("PackageJsonSyntaxError", {
+var PackageJsonSyntaxError = class extends Schema.TaggedError()("PackageJsonSyntaxError", {
 	/** Which syntactic precondition failed. */
 	reason: Schema.Literals(["invalid-json", "not-an-object"]),
 	/** The underlying `SyntaxError` for `"invalid-json"`, preserved structurally. */
@@ -26,6 +27,28 @@ var PackageJsonSyntaxError = class extends Schema.TaggedErrorClass()("PackageJso
 };
 const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
+* Indicates that a surgical modification could not be applied: the value on
+* the navigation path is not the container kind the next path segment
+* requires. The underlying `@effected/jsonc` `JsoncModificationError` —
+* which names the expected container and the 1-based depth of the mismatch —
+* is preserved on the structured `cause` field, never stringified.
+*
+* Raised by {@link PackageJsonFormat.modify} and
+* {@link PackageJsonFormat.modifyToString}.
+*
+* @public
+*/
+var PackageJsonModifyError = class extends Schema.TaggedError()("PackageJsonModifyError", {
+	/** The field path whose navigation failed. */
+	path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
+	/** The underlying `JsoncModificationError`, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to modify package.json at path [${this.path.join(", ")}]`;
+	}
+};
+/**
 * Decode-free canonical sort and format statics. Not instantiable.
 *
 * @remarks
@@ -44,7 +67,7 @@ const isJsonObject = (value) => typeof value === "object" && value !== null && !
 *
 * @public
 */
-var PackageJsonFormat = class {
+var PackageJsonFormat = class PackageJsonFormat {
 	constructor() {}
 	/**
 	* Order a package.json object's keys canonically **without decoding it into
@@ -132,7 +155,79 @@ var PackageJsonFormat = class {
 			newline: options?.newline ?? true
 		}));
 	}
+	/**
+	* Compute the surgical edits that set, replace or delete the value at
+	* `path` **without decoding, sorting or reformatting anything else**. The
+	* opposite posture to {@link PackageJsonFormat.formatToString}: where the
+	* formatter's job is the canonical order, the mutator's job is to leave
+	* every untouched byte untouched — key order, indentation, line endings and
+	* the trailing newline all survive, because only the edited span changes.
+	* That is what makes the result reviewable when a tool commits a one-field
+	* change to someone else's repository.
+	*
+	* Built on `@effected/jsonc`'s scanner-based edit engine. Inserted content
+	* matches the source's own style: indentation (tab vs N spaces) is detected
+	* from the first indented line and the line ending from the first `\r\n`.
+	*
+	* Passing `value === undefined` deletes the target key (including its
+	* comma) — the `@effected/jsonc` / `@effected/yaml` modify convention. A
+	* missing insertion target appends after the last key of its container.
+	*
+	* @param source - the package.json file contents (strict JSON — npm does
+	*   not accept comments, and neither does this)
+	* @param path - the field path, e.g. `["packageManager"]` or
+	*   `["devEngines", "runtime", "version"]`
+	* @param value - the plain JSON value to write, or `undefined` to delete
+	* @returns the edits to apply via `JsoncEdit.applyAll` — or use
+	*   {@link PackageJsonFormat.modifyToString} for the applied text in one step
+	*/
+	static modify = Effect.fn("PackageJsonFormat.modify")(function* (source, path, value) {
+		let parsed;
+		try {
+			parsed = JSON.parse(source);
+		} catch (cause) {
+			return yield* new PackageJsonSyntaxError({
+				reason: "invalid-json",
+				cause
+			});
+		}
+		if (!isJsonObject(parsed)) return yield* new PackageJsonSyntaxError({ reason: "not-an-object" });
+		const indent = detectIndent(source);
+		const formattingOptions = {
+			insertSpaces: indent !== "	",
+			tabSize: indent === void 0 || indent === "	" ? 2 : indent.length,
+			eol: source.includes("\r\n") ? "\r\n" : "\n"
+		};
+		return yield* JsoncModifier.modify(source, path, value, { formattingOptions }).pipe(Effect.catchTag("JsoncModificationError", (cause) => new PackageJsonModifyError({
+			path,
+			cause
+		})));
+	});
+	/**
+	* Modify `source` and apply the resulting edits in one step
+	* (`JsoncEdit.applyAll` composed over {@link PackageJsonFormat.modify}).
+	* Text in, text out; every byte outside the edited span is preserved.
+	* Inherits the modify error channel: {@link PackageJsonSyntaxError} when
+	* the source is not a JSON object, {@link PackageJsonModifyError} when the
+	* path cannot be navigated.
+	*
+	* @example
+	* ```ts
+	* import { PackageJsonFormat } from "@effected/package-json";
+	* import { Effect } from "effect";
+	*
+	* const program = PackageJsonFormat.modifyToString(
+	*   '{\n  "private": true,\n  "packageManager": "pnpm@11.2.0"\n}\n',
+	*   ["packageManager"],
+	*   "pnpm@11.3.0",
+	* ); // only the packageManager value changes; every other byte survives
+	* ```
+	*/
+	static modifyToString = Effect.fn("PackageJsonFormat.modifyToString")(function* (source, path, value) {
+		const edits = yield* PackageJsonFormat.modify(source, path, value);
+		return JsoncEdit.applyAll(source, edits);
+	});
 };
 
 //#endregion
-export { PackageJsonFormat, PackageJsonSyntaxError };
+export { PackageJsonFormat, PackageJsonModifyError, PackageJsonSyntaxError };

package/PackageManager.js

@@ -4,7 +4,7 @@ import { SemVer } from "@effected/semver";
 
 //#region src/PackageManager.ts
 const PACKAGE_MANAGER_NAME_RE = /^[a-z]+$/;
-const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue(Option.some(input), { message }));
+const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue({ message }, input));
 /**
 * A structured `packageManager` value with `name`, `version` and an optional
 * `integrity` hash.

package/PackageManagerRange.js

@@ -0,0 +1,124 @@
+import { CorepackIntegrityHash } from "@effected/npm";
+import { Effect, Exit, Option, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { Range, SemVer } from "@effected/semver";
+
+//#region src/PackageManagerRange.ts
+const PACKAGE_MANAGER_NAME_RE = /^[a-z]+$/;
+const invalid = (input, message) => Effect.fail(new SchemaIssue.InvalidValue({ message }, input));
+/** `Schema.String` refined to parse as a semver range (`Range.parseResult` succeeds). The check is erased from the built type. */
+const SemVerRangeString = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => value.length > 0 && Result.isSuccess(Range.parseResult(value)) ? void 0 : "Expected a semver range (an exact version, a caret/tilde range, a comparator set, ...)")));
+/**
+* A structured `packageManager` value whose version position is a semver
+* **range**, carried verbatim: `name`, `range` and an optional `integrity`
+* hash.
+*
+* @remarks
+* The range-tolerant sibling of {@link PackageManager}. The strict class
+* models the corepack pin — an exact version, which is all corepack itself
+* accepts — and stays strict; this class models the field as pnpm reads it,
+* where a range such as `^11.20.0` is a supported spelling that pnpm resolves
+* to a concrete version. An exact version is a valid range, so every string
+* the strict codec accepts decodes here too; {@link PackageManagerRange.isExact}
+* is how a caller tracks which form the manifest actually carried.
+*
+* The `range` field is the manifest's text **verbatim** — validated to parse
+* as a semver range but never normalized, so encoding is byte-identical to
+* the accepted input and reading a manifest never rewrites the field.
+* Interpretation is a derived getter, following `Repository`'s
+* carry-verbatim posture.
+*
+* The first `+` after the `@` begins the integrity component, exactly as in
+* the strict grammar — the version position of this field never carries
+* semver build metadata.
+*
+* @example
+* ```ts
+* import { PackageManagerRange } from "@effected/package-json";
+* import { Effect, Schema } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const pm = yield* Schema.decodeUnknownEffect(PackageManagerRange.FromString)("pnpm@^11.20.0");
+*   console.log(pm.name, pm.range, pm.isExact); // "pnpm" "^11.20.0" false
+* });
+* ```
+*
+* @public
+*/
+var PackageManagerRange = class PackageManagerRange extends Schema.Class("PackageManagerRange")({
+	/** The package-manager name (e.g. `pnpm`). Any lowercase name — the same latitude as {@link PackageManager}, for the same evidence. */
+	name: Schema.String,
+	/**
+	* The version position, verbatim: a semver range (`^11.20.0`,
+	* `>=10 <12`, ...) or an exact version (`11.2.0`). Validated to parse
+	* through `@effected/semver`'s `Range.parseResult`; never normalized, so
+	* the field round-trips byte-identically.
+	*/
+	range: SemVerRangeString,
+	/**
+	* The optional integrity hash (e.g. `sha512.abc`): `@effected/npm`'s
+	* `CorepackIntegrityHash`. Meaningful only alongside an exact range —
+	* an integrity pins one artifact — but carried whenever the manifest
+	* carries it, because fidelity outranks plausibility in a field model.
+	*/
+	integrity: Schema.Option(CorepackIntegrityHash)
+}) {
+	/**
+	* Schema transformation between the `"name@range[+integrity]"` string and a
+	* {@link PackageManagerRange}.
+	*
+	* @remarks
+	* Decoding splits on the first `@`, then on the first `+` — which always
+	* begins the integrity, never semver build metadata — and validates each
+	* component: the name against the lowercase grammar, the range through
+	* `@effected/semver`'s `Range.parseResult`, the integrity through
+	* `CorepackIntegrityHash`. Every failure is a typed decode failure naming
+	* the component that failed. Encoding reconstructs the string from the
+	* verbatim parts, so it is byte-identical to any input this codec accepts.
+	*/
+	static FromString = Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(PackageManagerRange), SchemaTransformation.transformOrFail({
+		decode: (input) => {
+			const at = input.indexOf("@");
+			if (at === -1) return invalid(input, `Invalid packageManager format: "${input}"`);
+			const name = input.slice(0, at);
+			if (!PACKAGE_MANAGER_NAME_RE.test(name)) return invalid(input, `Invalid packageManager name: "${name}"`);
+			const rest = input.slice(at + 1);
+			const plus = rest.indexOf("+");
+			const range = plus === -1 ? rest : rest.slice(0, plus);
+			if (range.length === 0 || Result.isFailure(Range.parseResult(range))) return invalid(input, `Invalid packageManager range: "${range}"`);
+			if (plus === -1) return Effect.succeed(PackageManagerRange.make({
+				name,
+				range,
+				integrity: Option.none()
+			}));
+			const rawIntegrity = rest.slice(plus + 1);
+			const decoded = Schema.decodeUnknownExit(CorepackIntegrityHash)(rawIntegrity);
+			if (Exit.isFailure(decoded)) return invalid(input, `Invalid packageManager integrity: "${rawIntegrity}"`);
+			return Effect.succeed(PackageManagerRange.make({
+				name,
+				range,
+				integrity: Option.some(decoded.value)
+			}));
+		},
+		encode: (pm) => Effect.succeed(Option.match(pm.integrity, {
+			onNone: () => `${pm.name}@${pm.range}`,
+			onSome: (integrity) => `${pm.name}@${pm.range}+${integrity}`
+		}))
+	})));
+	/**
+	* Whether the range is an exact, pinnable version (`11.2.0`) rather than a
+	* genuine range (`^11.20.0`) — decided by `SemVer.isPinnable` over the
+	* verbatim text, so `=11.2.0` and other range spellings of a single
+	* version report `false`. This is the exactness a consumer tracks when it
+	* must re-emit the same spelling it read.
+	*/
+	get isExact() {
+		return SemVer.isPinnable(this.range);
+	}
+	/** Whether an integrity hash is present. */
+	get hasIntegrity() {
+		return Option.isSome(this.integrity);
+	}
+};
+
+//#endregion
+export { PackageManagerRange };

package/PackageManifest.js

@@ -0,0 +1,93 @@
+import { renderJson, resolveFormatOptions } from "./internal/format.js";
+import { makeWire } from "./internal/wire.js";
+import { PackageName } from "./PackageName.js";
+import { Package, PackageDecodeError } from "./Package.js";
+import { PackageManagerRange } from "./PackageManagerRange.js";
+import { Effect, Schema } from "effect";
+import { SemVer } from "@effected/semver";
+
+//#region src/PackageManifest.ts
+/**
+* A package.json document as it exists on disk, publishable or not: every
+* field of {@link Package} with `name` and `version` optional and
+* `packageManager` accepting the range spelling.
+*
+* @remarks
+* **Lenient about absence, strict about shape.** npm requires `name` and
+* `version` only for a package that will be published; the idiomatic private
+* workspace root (`{ "private": true, "packageManager": "pnpm@11.2.0" }`)
+* carries neither, and {@link Package.decode} rightly rejects it — the strict
+* model's contract is publishability. This class decodes that shape, and any
+* other manifest, so long as every field that IS present satisfies its typed
+* codec: a present `version` must still be strict semver (`"1.0"` fails
+* typed), a present `name` must still satisfy the npm grammar, a present
+* `packageManager` must still parse — though here the version position may be
+* a semver range (`pnpm@^11.20.0`), decoded as {@link PackageManagerRange}.
+* For total tolerance of malformed fields, use the decode-free
+* {@link PackageJsonFormat} text path (or `@effected/npm`'s shape-blind
+* `Manifest`) — silently carrying a value the type claims to have validated
+* would be a lie, and silently dropping it would break round-trip fidelity.
+*
+* The model is deliberately lean — fields, the `rest` catch-all wire codec,
+* {@link PackageManifest.decode} and {@link PackageManifest.toJsonString} —
+* because the write half of a manifest-editing tool is the surgical
+* {@link PackageJsonFormat.modifyToString} / `PackageJsonFile.modify` path,
+* which never goes through a model at all. Mutation statics live on the
+* strict {@link Package}.
+*
+* @example
+* ```ts
+* import { PackageManifest } from "@effected/package-json";
+* import { Effect, Option } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const root = yield* PackageManifest.decode({ private: true, packageManager: "pnpm@^11.20.0" });
+*   console.log(root.isPrivate, root.packageManager?.isExact); // true false
+* });
+* ```
+*
+* @public
+*/
+var PackageManifest = class PackageManifest extends Schema.Class("PackageManifest")({
+	...Package.fields,
+	name: Schema.optionalKey(PackageName),
+	version: Schema.optionalKey(SemVer.FromString),
+	packageManager: Schema.optionalKey(PackageManagerRange.FromString)
+}) {
+	/**
+	* The wire codec: an open JSON object ↔ a {@link PackageManifest} instance,
+	* partitioning unknown keys into `rest` and flattening them back on encode —
+	* the same transform {@link Package.schema} uses, over this class's fields.
+	*/
+	static schema = makeWire(PackageManifest);
+	/**
+	* Decode an unknown JSON value into a {@link PackageManifest}, normalizing
+	* any `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
+	*
+	* @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
+	* @returns an Effect resolving to the decoded `PackageManifest`
+	* @throws (typed) `PackageDecodeError` when a present field does not satisfy
+	* its codec
+	*/
+	static decode = Effect.fn("PackageManifest.decode")(function* (input) {
+		return yield* Schema.decodeUnknownEffect(PackageManifest.schema)(input).pipe(Effect.catchTag("SchemaError", (cause) => new PackageDecodeError({ cause })));
+	});
+	/** Whether the manifest is marked private. */
+	get isPrivate() {
+		return this.private ?? false;
+	}
+	/**
+	* Serialize to a formatted package.json string: encode through the wire
+	* codec (flattening `rest`), then apply the canonical key order, dependency
+	* sorting and empty-map stripping unless the options opt out. Pure, and
+	* shared with `Package.toJsonString` down to the same internal renderer.
+	* Absent `name` / `version` keys stay absent — nothing is invented.
+	*/
+	toJsonString(options) {
+		const raw = Schema.encodeUnknownSync(PackageManifest.schema)(this);
+		return renderJson(raw, resolveFormatOptions(options));
+	}
+};
+
+//#endregion
+export { PackageManifest };

package/PackageName.js

@@ -9,7 +9,7 @@ import { Option, Schema } from "effect";
 *
 * @public
 */
-var InvalidPackageNameError = class extends Schema.TaggedErrorClass()("InvalidPackageNameError", { 
+var InvalidPackageNameError = class extends Schema.TaggedError()("InvalidPackageNameError", { 
 /** The raw input string that failed validation. */
 input: Schema.String }) {
 	get message() {

package/PackageValidator.js

@@ -9,7 +9,7 @@ import { Context, Effect, HashMap, Layer, Option, Result, Schema } from "effect"
 *
 * @public
 */
-var PackageValidationError = class extends Schema.TaggedErrorClass()("PackageValidationError", { 
+var PackageValidationError = class extends Schema.TaggedError()("PackageValidationError", { 
 /** The aggregated rule failures. */
 failures: Schema.Array(Schema.Struct({
 	rule: Schema.String,

package/index.d.ts

@@ -1,3 +1,4 @@
+import { JsoncEdit, JsoncEdit as JsoncEdit$1, JsoncPath, JsoncPath as JsoncPath$1 } from "@effected/jsonc";
 import { CatalogResolver, DependencyKind, DependencyProtocol, DependencyProtocol as DependencyProtocol$1, DependencySpecifier, DependencySpecifierBrand, InvalidDependencySpecifierError, WorkspaceResolver, isValidDependencySpecifier } from "@effected/npm";
 import { InvalidVersionError, Range, SemVer } from "@effected/semver";
 import { Brand, Context, Effect, FileSystem, HashMap, Layer, Option, Path, Result, Schema } from "effect";
@@ -745,117 +746,6 @@ declare class Package extends Package_base {
   toJsonString(options?: PackageFormatOptions): string;
 }
 //#endregion
-//#region src/PackageJsonFile.d.ts
-declare const PackageJsonReadError_base: Schema.Class<PackageJsonReadError, Schema.TaggedStruct<"PackageJsonReadError", {
-  /** The path that could not be read. */
-  readonly path: Schema.String;
-  /** The underlying failure, preserved structurally. */
-  readonly cause: Schema.Defect;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a package.json file could not be read from the filesystem
- * (a filesystem error other than not-found).
- *
- * @public
- */
-declare class PackageJsonReadError extends PackageJsonReadError_base {
-  get message(): string;
-}
-declare const PackageJsonNotFoundError_base: Schema.Class<PackageJsonNotFoundError, Schema.TaggedStruct<"PackageJsonNotFoundError", {
-  /** The path where package.json was expected. */
-  readonly path: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that no package.json file exists at the expected path. Carries its
- * own tag for `catchTag` routing.
- *
- * @public
- */
-declare class PackageJsonNotFoundError extends PackageJsonNotFoundError_base {
-  get message(): string;
-}
-declare const PackageJsonParseError_base: Schema.Class<PackageJsonParseError, Schema.TaggedStruct<"PackageJsonParseError", {
-  /** The path whose contents failed to parse as JSON. */
-  readonly path: Schema.String;
-  /** The underlying `SyntaxError`, preserved structurally. */
-  readonly cause: Schema.Defect;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a package.json file's contents are not valid JSON.
- *
- * @public
- */
-declare class PackageJsonParseError extends PackageJsonParseError_base {
-  get message(): string;
-}
-declare const PackageJsonWriteError_base: Schema.Class<PackageJsonWriteError, Schema.TaggedStruct<"PackageJsonWriteError", {
-  /** The path that could not be written. */
-  readonly path: Schema.String;
-  /** The underlying filesystem failure, preserved structurally. Narrowed to the write failure only. */
-  readonly cause: Schema.Defect;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a package.json file could not be written to the filesystem.
- * Narrowed to the filesystem-write failure only — never a resolution or encode
- * error.
- *
- * @public
- */
-declare class PackageJsonWriteError extends PackageJsonWriteError_base {
-  get message(): string;
-}
-/**
- * The shape of the {@link PackageJsonFile} service — the value produced by
- * {@link PackageJsonFile.make} and carried by its layer.
- *
- * @public
- */
-interface PackageJsonFileShape {
-  /**
-   * Read and decode a package.json file. Fails with `PackageJsonNotFoundError`
-   * (ENOENT), `PackageJsonReadError` (other fs errors), `PackageJsonParseError`
-   * (invalid JSON) or `PackageDecodeError` (schema decode).
-   */
-  readonly read: (path: string) => Effect.Effect<Package, PackageJsonReadError | PackageJsonNotFoundError | PackageJsonParseError | PackageDecodeError>;
-  /**
-   * Serialize and write a package.json file. Fails with
-   * `PackageJsonWriteError`. With `indent: "preserve"` and no explicit
-   * `sourceText`, the existing file at `path` (when readable) supplies the
-   * source text whose indentation is preserved.
-   */
-  readonly write: (path: string, pkg: Package, options?: PackageFormatOptions) => Effect.Effect<void, PackageJsonWriteError>;
-}
-declare const PackageJsonFile_base: Context.ServiceClass<PackageJsonFile, "@effected/package-json/PackageJsonFile", PackageJsonFileShape>;
-/**
- * Reads and writes package.json over core `FileSystem` / `Path`. The layer
- * requires those services; provide `@effect/platform-node`'s `NodeFileSystem` /
- * `NodePath` (or a bun equivalent) at the application boundary.
- *
- * @example
- * ```ts
- * import { PackageJsonFile } from "@effected/package-json";
- * import { NodeFileSystem, NodePath } from "@effect/platform-node";
- * import { Effect } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const files = yield* PackageJsonFile;
- *   const pkg = yield* files.read("./package.json");
- *   console.log(pkg.name);
- * }).pipe(Effect.provide(PackageJsonFile.layer), Effect.provide(NodeFileSystem.layer), Effect.provide(NodePath.layer));
- * ```
- *
- * @public
- */
-declare class PackageJsonFile extends PackageJsonFile_base {
-  /** Build the service implementation from `FileSystem` / `Path` in context; use {@link PackageJsonFile.layer} to provide it. */
-  static readonly make: Effect.Effect<PackageJsonFileShape, never, FileSystem.FileSystem | Path.Path>;
-  /**
-   * The live layer. Requires core `FileSystem` / `Path`, provided by the
-   * consumer's platform implementation at the edge.
-   */
-  static readonly layer: Layer.Layer<PackageJsonFile, never, FileSystem.FileSystem | Path.Path>;
-}
-//#endregion
 //#region src/PackageJsonFormat.d.ts
 declare const PackageJsonSyntaxError_base: Schema.Class<PackageJsonSyntaxError, Schema.TaggedStruct<"PackageJsonSyntaxError", {
   /** Which syntactic precondition failed. */
@@ -907,6 +797,27 @@ interface PackageFormatTextOptions {
   /** Append a trailing newline (default `true`). */
   readonly newline?: boolean;
 }
+declare const PackageJsonModifyError_base: Schema.Class<PackageJsonModifyError, Schema.TaggedStruct<"PackageJsonModifyError", {
+  /** The field path whose navigation failed. */
+  readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+  /** The underlying `JsoncModificationError`, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a surgical modification could not be applied: the value on
+ * the navigation path is not the container kind the next path segment
+ * requires. The underlying `@effected/jsonc` `JsoncModificationError` —
+ * which names the expected container and the 1-based depth of the mismatch —
+ * is preserved on the structured `cause` field, never stringified.
+ *
+ * Raised by {@link PackageJsonFormat.modify} and
+ * {@link PackageJsonFormat.modifyToString}.
+ *
+ * @public
+ */
+declare class PackageJsonModifyError extends PackageJsonModifyError_base {
+  get message(): string;
+}
 /**
  * Decode-free canonical sort and format statics. Not instantiable.
  *
@@ -996,6 +907,416 @@ declare class PackageJsonFormat {
    * ```
    */
   static formatToString(source: string, options?: PackageFormatTextOptions): Result.Result<string, PackageJsonSyntaxError>;
+  /**
+   * Compute the surgical edits that set, replace or delete the value at
+   * `path` **without decoding, sorting or reformatting anything else**. The
+   * opposite posture to {@link PackageJsonFormat.formatToString}: where the
+   * formatter's job is the canonical order, the mutator's job is to leave
+   * every untouched byte untouched — key order, indentation, line endings and
+   * the trailing newline all survive, because only the edited span changes.
+   * That is what makes the result reviewable when a tool commits a one-field
+   * change to someone else's repository.
+   *
+   * Built on `@effected/jsonc`'s scanner-based edit engine. Inserted content
+   * matches the source's own style: indentation (tab vs N spaces) is detected
+   * from the first indented line and the line ending from the first `\r\n`.
+   *
+   * Passing `value === undefined` deletes the target key (including its
+   * comma) — the `@effected/jsonc` / `@effected/yaml` modify convention. A
+   * missing insertion target appends after the last key of its container.
+   *
+   * @param source - the package.json file contents (strict JSON — npm does
+   *   not accept comments, and neither does this)
+   * @param path - the field path, e.g. `["packageManager"]` or
+   *   `["devEngines", "runtime", "version"]`
+   * @param value - the plain JSON value to write, or `undefined` to delete
+   * @returns the edits to apply via `JsoncEdit.applyAll` — or use
+   *   {@link PackageJsonFormat.modifyToString} for the applied text in one step
+   */
+  static readonly modify: (source: string, path: JsoncPath$1, value: unknown) => Effect.Effect<readonly JsoncEdit$1[], PackageJsonModifyError | PackageJsonSyntaxError, never>;
+  /**
+   * Modify `source` and apply the resulting edits in one step
+   * (`JsoncEdit.applyAll` composed over {@link PackageJsonFormat.modify}).
+   * Text in, text out; every byte outside the edited span is preserved.
+   * Inherits the modify error channel: {@link PackageJsonSyntaxError} when
+   * the source is not a JSON object, {@link PackageJsonModifyError} when the
+   * path cannot be navigated.
+   *
+   * @example
+   * ```ts
+   * import { PackageJsonFormat } from "@effected/package-json";
+   * import { Effect } from "effect";
+   *
+   * const program = PackageJsonFormat.modifyToString(
+   *   '{\n  "private": true,\n  "packageManager": "pnpm@11.2.0"\n}\n',
+   *   ["packageManager"],
+   *   "pnpm@11.3.0",
+   * ); // only the packageManager value changes; every other byte survives
+   * ```
+   */
+  static readonly modifyToString: (source: string, path: JsoncPath$1, value: unknown) => Effect.Effect<string, PackageJsonModifyError | PackageJsonSyntaxError, never>;
+}
+//#endregion
+//#region src/PackageManagerRange.d.ts
+declare const PackageManagerRange_base: Schema.Class<PackageManagerRange, Schema.Struct<{
+  /** The package-manager name (e.g. `pnpm`). Any lowercase name — the same latitude as {@link PackageManager}, for the same evidence. */
+  readonly name: Schema.String;
+  /**
+   * The version position, verbatim: a semver range (`^11.20.0`,
+   * `>=10 <12`, ...) or an exact version (`11.2.0`). Validated to parse
+   * through `@effected/semver`'s `Range.parseResult`; never normalized, so
+   * the field round-trips byte-identically.
+   */
+  readonly range: Schema.String;
+  /**
+   * The optional integrity hash (e.g. `sha512.abc`): `@effected/npm`'s
+   * `CorepackIntegrityHash`. Meaningful only alongside an exact range —
+   * an integrity pins one artifact — but carried whenever the manifest
+   * carries it, because fidelity outranks plausibility in a field model.
+   */
+  readonly integrity: Schema.Option<Schema.brand<Schema.String, "IntegrityHash">>;
+}>, {}>;
+/**
+ * A structured `packageManager` value whose version position is a semver
+ * **range**, carried verbatim: `name`, `range` and an optional `integrity`
+ * hash.
+ *
+ * @remarks
+ * The range-tolerant sibling of {@link PackageManager}. The strict class
+ * models the corepack pin — an exact version, which is all corepack itself
+ * accepts — and stays strict; this class models the field as pnpm reads it,
+ * where a range such as `^11.20.0` is a supported spelling that pnpm resolves
+ * to a concrete version. An exact version is a valid range, so every string
+ * the strict codec accepts decodes here too; {@link PackageManagerRange.isExact}
+ * is how a caller tracks which form the manifest actually carried.
+ *
+ * The `range` field is the manifest's text **verbatim** — validated to parse
+ * as a semver range but never normalized, so encoding is byte-identical to
+ * the accepted input and reading a manifest never rewrites the field.
+ * Interpretation is a derived getter, following `Repository`'s
+ * carry-verbatim posture.
+ *
+ * The first `+` after the `@` begins the integrity component, exactly as in
+ * the strict grammar — the version position of this field never carries
+ * semver build metadata.
+ *
+ * @example
+ * ```ts
+ * import { PackageManagerRange } from "@effected/package-json";
+ * import { Effect, Schema } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pm = yield* Schema.decodeUnknownEffect(PackageManagerRange.FromString)("pnpm@^11.20.0");
+ *   console.log(pm.name, pm.range, pm.isExact); // "pnpm" "^11.20.0" false
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PackageManagerRange extends PackageManagerRange_base {
+  /**
+   * Schema transformation between the `"name@range[+integrity]"` string and a
+   * {@link PackageManagerRange}.
+   *
+   * @remarks
+   * Decoding splits on the first `@`, then on the first `+` — which always
+   * begins the integrity, never semver build metadata — and validates each
+   * component: the name against the lowercase grammar, the range through
+   * `@effected/semver`'s `Range.parseResult`, the integrity through
+   * `CorepackIntegrityHash`. Every failure is a typed decode failure naming
+   * the component that failed. Encoding reconstructs the string from the
+   * verbatim parts, so it is byte-identical to any input this codec accepts.
+   */
+  static readonly FromString: Schema.Codec<PackageManagerRange, string>;
+  /**
+   * Whether the range is an exact, pinnable version (`11.2.0`) rather than a
+   * genuine range (`^11.20.0`) — decided by `SemVer.isPinnable` over the
+   * verbatim text, so `=11.2.0` and other range spellings of a single
+   * version report `false`. This is the exactness a consumer tracks when it
+   * must re-emit the same spelling it read.
+   */
+  get isExact(): boolean;
+  /** Whether an integrity hash is present. */
+  get hasIntegrity(): boolean;
+}
+//#endregion
+//#region src/PackageManifest.d.ts
+declare const PackageManifest_base: Schema.Class<PackageManifest, Schema.Struct<{
+  readonly description: Schema.optionalKey<Schema.String>;
+  readonly private: Schema.optionalKey<Schema.Boolean>;
+  readonly type: Schema.optionalKey<Schema.Literals<readonly ["module", "commonjs"]>>;
+  readonly main: Schema.optionalKey<Schema.String>;
+  readonly license: Schema.optionalKey<Schema.brand<Schema.String, "SpdxLicense">>;
+  readonly author: Schema.optionalKey<Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>;
+  readonly contributors: Schema.optionalKey<Schema.$Array<Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>>;
+  readonly maintainers: Schema.optionalKey<Schema.$Array<Schema.Codec<Person, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>>;
+  readonly keywords: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly repository: Schema.optionalKey<Schema.Codec<Repository, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>;
+  readonly bugs: Schema.optionalKey<Schema.Codec<Bugs, string | {
+    readonly [k: string]: unknown;
+  }, never, never>>;
+  readonly homepage: Schema.optionalKey<Schema.String>;
+  readonly dependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
+  readonly devDependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
+  readonly peerDependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
+  readonly optionalDependencies: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
+  readonly peerDependenciesMeta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Struct<{
+    readonly optional: Schema.optionalKey<Schema.Boolean>;
+  }>>>;
+  readonly scripts: Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>, never, never>;
+  readonly bin: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.$Record<Schema.String, Schema.String>, never, never>]>>;
+  readonly engines: Schema.optionalKey<Schema.decodeTo<Schema.HashMap<Schema.String, Schema.String>, Schema.$Record<Schema.String, Schema.String>, never, never>>;
+  readonly exports: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.$Record<Schema.String, Schema.Unknown>]>>;
+  readonly publishConfig: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+  readonly devEngines: Schema.optionalKey<Schema.Struct<{
+    readonly packageManager: Schema.optionalKey<typeof DevEngineOrArray>;
+    readonly runtime: Schema.optionalKey<typeof DevEngineOrArray>;
+    readonly os: Schema.optionalKey<typeof DevEngineOrArray>;
+    readonly cpu: Schema.optionalKey<typeof DevEngineOrArray>;
+    readonly libc: Schema.optionalKey<typeof DevEngineOrArray>;
+  }>>;
+  readonly rest: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+  readonly name: Schema.optionalKey<Schema.Union<readonly [Schema.brand<Schema.String, "ScopedPackageName">, Schema.brand<Schema.String, "UnscopedPackageName">]> & {
+    isValid: (name: string) => boolean;
+    scope: (name: string) => import("effect/Option").Option<string>;
+    unscoped: (name: string) => string;
+    isScoped: (name: string) => boolean;
+  }>;
+  readonly version: Schema.optionalKey<Schema.Codec<SemVer, string, never, never>>;
+  readonly packageManager: Schema.optionalKey<Schema.Codec<PackageManagerRange, string, never, never>>;
+}>, {}>;
+/**
+ * A package.json document as it exists on disk, publishable or not: every
+ * field of {@link Package} with `name` and `version` optional and
+ * `packageManager` accepting the range spelling.
+ *
+ * @remarks
+ * **Lenient about absence, strict about shape.** npm requires `name` and
+ * `version` only for a package that will be published; the idiomatic private
+ * workspace root (`{ "private": true, "packageManager": "pnpm@11.2.0" }`)
+ * carries neither, and {@link Package.decode} rightly rejects it — the strict
+ * model's contract is publishability. This class decodes that shape, and any
+ * other manifest, so long as every field that IS present satisfies its typed
+ * codec: a present `version` must still be strict semver (`"1.0"` fails
+ * typed), a present `name` must still satisfy the npm grammar, a present
+ * `packageManager` must still parse — though here the version position may be
+ * a semver range (`pnpm@^11.20.0`), decoded as {@link PackageManagerRange}.
+ * For total tolerance of malformed fields, use the decode-free
+ * {@link PackageJsonFormat} text path (or `@effected/npm`'s shape-blind
+ * `Manifest`) — silently carrying a value the type claims to have validated
+ * would be a lie, and silently dropping it would break round-trip fidelity.
+ *
+ * The model is deliberately lean — fields, the `rest` catch-all wire codec,
+ * {@link PackageManifest.decode} and {@link PackageManifest.toJsonString} —
+ * because the write half of a manifest-editing tool is the surgical
+ * {@link PackageJsonFormat.modifyToString} / `PackageJsonFile.modify` path,
+ * which never goes through a model at all. Mutation statics live on the
+ * strict {@link Package}.
+ *
+ * @example
+ * ```ts
+ * import { PackageManifest } from "@effected/package-json";
+ * import { Effect, Option } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root = yield* PackageManifest.decode({ private: true, packageManager: "pnpm@^11.20.0" });
+ *   console.log(root.isPrivate, root.packageManager?.isExact); // true false
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PackageManifest extends PackageManifest_base {
+  /**
+   * The wire codec: an open JSON object ↔ a {@link PackageManifest} instance,
+   * partitioning unknown keys into `rest` and flattening them back on encode —
+   * the same transform {@link Package.schema} uses, over this class's fields.
+   */
+  static readonly schema: Schema.Codec<PackageManifest, {
+    readonly [k: string]: unknown;
+  }>;
+  /**
+   * Decode an unknown JSON value into a {@link PackageManifest}, normalizing
+   * any `SchemaError` to a typed {@link PackageDecodeError} at the boundary.
+   *
+   * @param input - the parsed package.json JSON value (e.g. from `JSON.parse`)
+   * @returns an Effect resolving to the decoded `PackageManifest`
+   * @throws (typed) `PackageDecodeError` when a present field does not satisfy
+   * its codec
+   */
+  static readonly decode: (input: unknown) => Effect.Effect<PackageManifest, PackageDecodeError, never>;
+  /** Whether the manifest is marked private. */
+  get isPrivate(): boolean;
+  /**
+   * Serialize to a formatted package.json string: encode through the wire
+   * codec (flattening `rest`), then apply the canonical key order, dependency
+   * sorting and empty-map stripping unless the options opt out. Pure, and
+   * shared with `Package.toJsonString` down to the same internal renderer.
+   * Absent `name` / `version` keys stay absent — nothing is invented.
+   */
+  toJsonString(options?: PackageFormatOptions): string;
+}
+//#endregion
+//#region src/PackageJsonFile.d.ts
+declare const PackageJsonReadError_base: Schema.Class<PackageJsonReadError, Schema.TaggedStruct<"PackageJsonReadError", {
+  /** The path that could not be read. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a package.json file could not be read from the filesystem
+ * (a filesystem error other than not-found).
+ *
+ * @public
+ */
+declare class PackageJsonReadError extends PackageJsonReadError_base {
+  get message(): string;
+}
+declare const PackageJsonNotFoundError_base: Schema.Class<PackageJsonNotFoundError, Schema.TaggedStruct<"PackageJsonNotFoundError", {
+  /** The path where package.json was expected. */
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that no package.json file exists at the expected path. Carries its
+ * own tag for `catchTag` routing.
+ *
+ * @public
+ */
+declare class PackageJsonNotFoundError extends PackageJsonNotFoundError_base {
+  get message(): string;
+}
+declare const PackageJsonParseError_base: Schema.Class<PackageJsonParseError, Schema.TaggedStruct<"PackageJsonParseError", {
+  /** The path whose contents failed to parse as JSON. */
+  readonly path: Schema.String;
+  /** The underlying `SyntaxError`, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a package.json file's contents are not valid JSON.
+ *
+ * @public
+ */
+declare class PackageJsonParseError extends PackageJsonParseError_base {
+  get message(): string;
+}
+declare const PackageJsonWriteError_base: Schema.Class<PackageJsonWriteError, Schema.TaggedStruct<"PackageJsonWriteError", {
+  /** The path that could not be written. */
+  readonly path: Schema.String;
+  /** The underlying filesystem failure, preserved structurally. Narrowed to the write failure only. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a package.json file could not be written to the filesystem.
+ * Narrowed to the filesystem-write failure only — never a resolution or encode
+ * error.
+ *
+ * @public
+ */
+declare class PackageJsonWriteError extends PackageJsonWriteError_base {
+  get message(): string;
+}
+/**
+ * One surgical field edit for {@link PackageJsonFile}'s `modify`: set `value`
+ * at `path`, or delete the key there when `value` is `undefined` (the
+ * `@effected/jsonc` / `@effected/yaml` modify convention — deletion is spelled
+ * with an explicit `value: undefined`, so it is always deliberate).
+ *
+ * @public
+ */
+interface PackageFieldEdit {
+  /** The field path, e.g. `["packageManager"]` or `["devEngines", "runtime", "version"]`. */
+  readonly path: JsoncPath$1;
+  /** The plain JSON value to write, or `undefined` to delete the target key. */
+  readonly value: unknown;
+}
+/**
+ * The shape of the {@link PackageJsonFile} service — the value produced by
+ * {@link PackageJsonFile.make} and carried by its layer.
+ *
+ * @public
+ */
+interface PackageJsonFileShape {
+  /**
+   * Read and decode a package.json file. Fails with `PackageJsonNotFoundError`
+   * (ENOENT), `PackageJsonReadError` (other fs errors), `PackageJsonParseError`
+   * (invalid JSON) or `PackageDecodeError` (schema decode).
+   */
+  readonly read: (path: string) => Effect.Effect<Package, PackageJsonReadError | PackageJsonNotFoundError | PackageJsonParseError | PackageDecodeError>;
+  /**
+   * Serialize and write a package.json file. Fails with
+   * `PackageJsonWriteError`. With `indent: "preserve"` and no explicit
+   * `sourceText`, the existing file at `path` (when readable) supplies the
+   * source text whose indentation is preserved.
+   */
+  readonly write: (path: string, pkg: Package, options?: PackageFormatOptions) => Effect.Effect<void, PackageJsonWriteError>;
+  /**
+   * Read and decode a package.json file through the presence-lenient
+   * {@link PackageManifest} — the read that accepts the private
+   * workspace-root shape (`{ "private": true, "packageManager": ... }`)
+   * `read` rejects. Same error channel as `read`; a present field that does
+   * not satisfy its codec still fails as `PackageDecodeError`.
+   */
+  readonly readManifest: (path: string) => Effect.Effect<PackageManifest, PackageJsonReadError | PackageJsonNotFoundError | PackageJsonParseError | PackageDecodeError>;
+  /**
+   * Serialize and write a {@link PackageManifest}. Fails with
+   * `PackageJsonWriteError`. Shares `write`'s `indent: "preserve"` behavior:
+   * with no explicit `sourceText`, the existing file at `path` (when
+   * readable) supplies the source text whose indentation is preserved.
+   */
+  readonly writeManifest: (path: string, manifest: PackageManifest, options?: PackageFormatOptions) => Effect.Effect<void, PackageJsonWriteError>;
+  /**
+   * Apply surgical field edits to a package.json file **without decoding
+   * it**: one read, each {@link PackageFieldEdit} applied in order through
+   * `PackageJsonFormat.modifyToString`, one write — skipped when the result
+   * is byte-identical to what was read. Every byte outside the edited spans
+   * is preserved (key order, indentation, line endings, trailing newline),
+   * which is what keeps a one-field change reviewable in someone else's
+   * repository. Succeeds with the file's final text.
+   *
+   * Invalid JSON at `path` fails as `PackageJsonParseError` — the same tag
+   * `read` uses for it — and an unnavigable edit path as
+   * `PackageJsonModifyError`.
+   */
+  readonly modify: (path: string, edits: ReadonlyArray<PackageFieldEdit>) => Effect.Effect<string, PackageJsonReadError | PackageJsonNotFoundError | PackageJsonParseError | PackageJsonModifyError | PackageJsonWriteError>;
+}
+declare const PackageJsonFile_base: Context.ServiceClass<PackageJsonFile, "@effected/package-json/PackageJsonFile", PackageJsonFileShape>;
+/**
+ * Reads and writes package.json over core `FileSystem` / `Path`. The layer
+ * requires those services; provide `@effect/platform-node`'s `NodeFileSystem` /
+ * `NodePath` (or a bun equivalent) at the application boundary.
+ *
+ * @example
+ * ```ts
+ * import { PackageJsonFile } from "@effected/package-json";
+ * import { NodeFileSystem, NodePath } from "@effect/platform-node";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const files = yield* PackageJsonFile;
+ *   const pkg = yield* files.read("./package.json");
+ *   console.log(pkg.name);
+ * }).pipe(Effect.provide(PackageJsonFile.layer), Effect.provide(NodeFileSystem.layer), Effect.provide(NodePath.layer));
+ * ```
+ *
+ * @public
+ */
+declare class PackageJsonFile extends PackageJsonFile_base {
+  /** Build the service implementation from `FileSystem` / `Path` in context; use {@link PackageJsonFile.layer} to provide it. */
+  static readonly make: Effect.Effect<PackageJsonFileShape, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The live layer. Requires core `FileSystem` / `Path`, provided by the
+   * consumer's platform implementation at the edge.
+   */
+  static readonly layer: Layer.Layer<PackageJsonFile, never, FileSystem.FileSystem | Path.Path>;
 }
 //#endregion
 //#region src/PackageValidator.d.ts
@@ -1097,5 +1418,5 @@ declare class PackageValidator extends PackageValidator_base {
   }): Layer.Layer<PackageValidator>;
 }
 //#endregion
-export { BinField, Bugs, Dependency, type DependencyKind, DependencyMapField, type DependencyProtocol, DependencySpecifier, type DependencySpecifierBrand, DevEngine, DevEngineOrArray, type DevEngines, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, Package, PackageDecodeError, type PackageFormatOptions, type PackageFormatTextOptions, type PackageIndent, PackageJsonFile, type PackageJsonFileShape, PackageJsonFormat, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonSyntaxError, PackageJsonWriteError, PackageManager, PackageName, type PackagePatch, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, Repository, RepositoryField, type RuleFailure, ScopedPackageName, SpdxLicense, StringMapField, type UnresolvedDependency, UnscopedPackageName, type ValidationRule, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };
+export { BinField, Bugs, Dependency, type DependencyKind, DependencyMapField, type DependencyProtocol, DependencySpecifier, type DependencySpecifierBrand, DevEngine, DevEngineOrArray, type DevEngines, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, JsoncEdit, type JsoncPath, Package, PackageDecodeError, type PackageFieldEdit, type PackageFormatOptions, type PackageFormatTextOptions, type PackageIndent, PackageJsonFile, type PackageJsonFileShape, PackageJsonFormat, PackageJsonModifyError, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonSyntaxError, PackageJsonWriteError, PackageManager, PackageManagerRange, PackageManifest, PackageName, type PackagePatch, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, Repository, RepositoryField, type RuleFailure, ScopedPackageName, SpdxLicense, StringMapField, type UnresolvedDependency, UnscopedPackageName, type ValidationRule, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,9 +6,12 @@ import { InvalidPackageNameError, PackageName, ScopedPackageName, UnscopedPackag
 import { Person } from "./Person.js";
 import { Bugs, Repository } from "./Repository.js";
 import { BinField, DependencyMapField, ExportsField, Package, PackageDecodeError, PeerDependenciesMetaField, PublishConfigField, RepositoryField, StringMapField } from "./Package.js";
+import { PackageJsonFormat, PackageJsonModifyError, PackageJsonSyntaxError } from "./PackageJsonFormat.js";
+import { PackageManagerRange } from "./PackageManagerRange.js";
+import { PackageManifest } from "./PackageManifest.js";
 import { PackageJsonFile, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonWriteError } from "./PackageJsonFile.js";
-import { PackageJsonFormat, PackageJsonSyntaxError } from "./PackageJsonFormat.js";
 import { PackageValidationError, PackageValidator, defaultRules, noLocalDepsRule, noUnresolvedDepsRule } from "./PackageValidator.js";
+import { JsoncEdit } from "@effected/jsonc";
 import { DependencySpecifier, InvalidDependencySpecifierError, isValidDependencySpecifier } from "@effected/npm";
 
-export { BinField, Bugs, Dependency, DependencyMapField, DependencySpecifier, DevEngine, DevEngineOrArray, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, Package, PackageDecodeError, PackageJsonFile, PackageJsonFormat, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonSyntaxError, PackageJsonWriteError, PackageManager, PackageName, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, Repository, RepositoryField, ScopedPackageName, SpdxLicense, StringMapField, UnscopedPackageName, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };
+export { BinField, Bugs, Dependency, DependencyMapField, DependencySpecifier, DevEngine, DevEngineOrArray, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, JsoncEdit, Package, PackageDecodeError, PackageJsonFile, PackageJsonFormat, PackageJsonModifyError, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonSyntaxError, PackageJsonWriteError, PackageManager, PackageManagerRange, PackageManifest, PackageName, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, Repository, RepositoryField, ScopedPackageName, SpdxLicense, StringMapField, UnscopedPackageName, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };

package/internal/format.js

@@ -210,6 +210,18 @@ const resolveIndent = (indent, sourceText) => {
 	return indent ?? DEFAULT_INDENT;
 };
 /**
+* Resolve the public `PackageFormatOptions` bag (mirrored structurally here —
+* this module cannot import `Package.ts` without closing a cycle) to the
+* concrete {@link renderJson} options. Shared by `Package.toJsonString` and
+* `PackageManifest.toJsonString` so the two serializers cannot drift.
+*/
+const resolveFormatOptions = (options) => ({
+	indent: resolveIndent(options?.indent, options?.sourceText),
+	sort: options?.sort ?? true,
+	stripEmpty: options?.stripEmpty ?? true,
+	newline: options?.newline ?? true
+});
+/**
 * Render an already-encoded package.json record to a JSON string, applying the
 * empty-map strip, canonical key ordering and a trailing newline unless the
 * corresponding options opt out.
@@ -222,4 +234,4 @@ const renderJson = (raw, options) => {
 };
 
 //#endregion
-export { detectIndent, renderJson, resolveIndent, sortKeys, stripEmptyDependencyMaps };
+export { detectIndent, renderJson, resolveFormatOptions, resolveIndent, sortKeys, stripEmptyDependencyMaps };

package/internal/wire.js

@@ -0,0 +1,35 @@
+import { Schema, SchemaTransformation } from "effect";
+
+//#region src/internal/wire.ts
+const RawJson = Schema.Record(Schema.String, Schema.Unknown);
+/**
+* Build the open-JSON ↔ class wire codec for a `Schema.Class` carrying a
+* `rest` catch-all field. Generic over the class so `Package`, its
+* `.extend()`ed subclasses and `PackageManifest` all share the one
+* implementation and cannot drift.
+*/
+const makeWire = (Class) => {
+	const knownKeys = new Set(Object.keys(Class.fields).filter((k) => k !== "rest"));
+	return RawJson.pipe(Schema.decodeTo(Class, SchemaTransformation.transform({
+		decode: (raw) => {
+			const known = {};
+			const rest = Object.create(null);
+			for (const [key, value] of Object.entries(raw)) if (knownKeys.has(key)) known[key] = value;
+			else rest[key] = value;
+			return {
+				...known,
+				rest
+			};
+		},
+		encode: (encoded) => {
+			const { rest, ...known } = encoded;
+			return {
+				...rest ?? {},
+				...known
+			};
+		}
+	})));
+};
+
+//#endregion
+export { makeWire };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/package-json",
-	"version": "0.7.3",
+	"version": "0.9.0",
 	"private": false,
 	"description": "package.json parsing, editing, validation and file IO as Effect schemas.",
 	"keywords": [
@@ -38,12 +38,13 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/npm": "^0.8.2",
-		"@effected/semver": "^0.3.2",
-		"@effected/spdx": "^0.1.2"
+		"@effected/jsonc": "^0.6.0",
+		"@effected/npm": "^0.9.0",
+		"@effected/semver": "^0.4.0",
+		"@effected/spdx": "^0.2.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-beta.101"
+		"effect": "4.0.0-beta.107"
 	},
 	"engines": {
 		"node": ">=24.11.0"