@savvy-web/silk-effects 3.3.1 → 4.0.1

package/lint/cli/templates/markdownlint.gen.js

@@ -1,13 +1,4 @@
 //#region src/lint/cli/templates/markdownlint.gen.ts
-/**
-* Markdownlint template data.
-*
-* Originally generated in the now-deprecated `@savvy-web/lint-staged` package;
-* the generator does not live in this repo, so this file is maintained by hand.
-* Edit the `MARKDOWNLINT_TEMPLATE` / `MARKDOWNLINT_CONFIG` objects directly.
-*
-* @internal
-*/
 /** Full markdownlint-cli2 config template. */
 const MARKDOWNLINT_TEMPLATE = {
 	$schema: "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.22.0/schema/markdownlint-cli2-config-schema.json",

package/lint/handlers/PnpmWorkspace.js

@@ -1,6 +1,8 @@
 import { Command } from "../utils/Command.js";
+import { Effect, Result } from "effect";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { parse, stringify } from "yaml";
+import { Yaml, YamlStringifyOptions } from "@effected/yaml";
+import { format, resolveConfig } from "prettier";
 
 //#region src/lint/handlers/PnpmWorkspace.ts
 /**
@@ -10,12 +12,21 @@ import { parse, stringify } from "yaml";
 */
 /**
 * Default YAML stringify options for consistent formatting.
+*
+* @remarks
+* `lineWidth: 0` disables line wrapping, matching the v3 `yaml` package
+* behavior. `@effected/yaml` emits block sequences without the extra
+* two-space indentation the v3 `yaml` package used, so the stringified
+* output is normalized through Prettier's YAML printer below — probed
+* byte-identical to the v3 `yaml.stringify(..., { indent: 2, lineWidth: 0,
+* singleQuote: false })` output on this repo's real `pnpm-workspace.yaml`
+* and on hostile synthetic shapes (quoted keys, block scalars, nested
+* sequences of maps).
 */
-const DEFAULT_STRINGIFY_OPTIONS = {
+const DEFAULT_STRINGIFY_OPTIONS = new YamlStringifyOptions({
 	indent: 2,
-	lineWidth: 0,
-	singleQuote: false
-};
+	lineWidth: 0
+});
 /**
 * Handler for pnpm-workspace.yaml.
 *
@@ -116,20 +127,23 @@ var PnpmWorkspace = class PnpmWorkspace {
 		const skipSort = options.skipSort ?? false;
 		const skipFormat = options.skipFormat ?? false;
 		const skipLint = options.skipLint ?? false;
-		return () => {
+		return async () => {
 			const filepath = "pnpm-workspace.yaml";
 			if (!existsSync(filepath)) return [];
 			const content = readFileSync(filepath, "utf-8");
-			let parsed;
-			try {
-				parsed = parse(content);
-			} catch (error) {
-				if (!skipLint) throw new Error(`Invalid YAML in ${filepath}: ${error instanceof Error ? error.message : String(error)}`);
+			const parseResult = Effect.runSync(Effect.result(Yaml.parse(content)));
+			if (Result.isFailure(parseResult)) {
+				if (!skipLint) throw new Error(`Invalid YAML in ${filepath}: ${parseResult.failure.message}`);
 				return [];
 			}
+			let parsed = parseResult.success;
 			if (!skipSort) parsed = PnpmWorkspace.sortContent(parsed);
 			if (!skipSort || !skipFormat) {
-				writeFileSync(filepath, stringify(parsed, DEFAULT_STRINGIFY_OPTIONS), "utf-8");
+				writeFileSync(filepath, await format(Effect.runSync(Yaml.stringify(parsed, DEFAULT_STRINGIFY_OPTIONS)), {
+					...await resolveConfig(filepath),
+					filepath,
+					parser: "yaml"
+				}), "utf-8");
 				return [];
 			}
 			return [];

package/lint/utils/Filter.js

@@ -1,18 +1,5 @@
 //#region src/lint/utils/Filter.ts
 /**
-* Utilities for filtering staged file lists.
-*
-* @example
-* ```typescript
-* import { Filter } from '@savvy-web/silk/lint';
-*
-* const handler = (filenames: readonly string[]) => {
-*   const filtered = Filter.exclude(filenames, ['dist/', '__fixtures__']);
-*   return filtered.length > 0 ? `biome check ${Filter.shellEscape(filtered)}` : [];
-* };
-* ```
-*/
-/**
 * Static utility class for filtering file lists.
 */
 var Filter = class Filter {

package/lint/utils/Workspace.js

@@ -1,14 +1,18 @@
 import { dirname } from "node:path";
-import { findWorkspaceRootSync, getWorkspacePackagesSync } from "workspaces-effect";
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
+import { nodeSyncOps } from "@effected/workspaces/node-sync";
 
 //#region src/lint/utils/Workspace.ts
 /**
 * Workspace-aware discovery utilities.
 *
 * @remarks
-* Wraps the synchronous APIs from `workspaces-effect` with caching.
-* Workspace layout does not change during a lint-staged run, so
-* results are cached on first access. Use `resetWorkspaceCache()`
+* Wraps the synchronous APIs from `@effected/workspaces` with caching.
+* The kit's sync entry points never import `node:*` themselves — the
+* Node binding is the kit's own `@effected/workspaces/node-sync` preset
+* (`nodeSyncOps`), which replaced this module's hand-wired ops in kit
+* round 3. Workspace layout does not change during a lint-staged run,
+* so results are cached on first access. Use `resetWorkspaceCache()`
 * in tests to clear state between runs.
 */
 /** Sentinel indicating "not yet resolved". */
@@ -23,7 +27,7 @@ let cachedPaths = UNRESOLVED;
 */
 function getWorkspaceRoot() {
 	if (cachedRoot !== UNRESOLVED) return cachedRoot;
-	cachedRoot = findWorkspaceRootSync() ?? null;
+	cachedRoot = findWorkspaceRootSync(nodeSyncOps);
 	return cachedRoot;
 }
 /**
@@ -38,7 +42,7 @@ function getWorkspacePackages() {
 		cachedPackages = null;
 		return null;
 	}
-	cachedPackages = (getWorkspacePackagesSync(root) ?? []).filter((pkg) => pkg.path !== root);
+	cachedPackages = getWorkspacePackagesSync(root, nodeSyncOps).filter((pkg) => pkg.path !== root);
 	return cachedPackages;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "3.3.1",
+	"version": "4.0.1",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
@@ -23,7 +23,8 @@
 	"exports": {
 		".": {
 			"types": "./index.d.ts",
-			"import": "./index.js"
+			"import": "./index.js",
+			"default": "./index.js"
 		},
 		"./package.json": "./package.json"
 	},
@@ -32,28 +33,28 @@
 		"@changesets/config": "^4.0.0-next.6",
 		"@changesets/get-github-info": "^1.0.0-next.3",
 		"@changesets/get-release-plan": "^5.0.0-next.7",
+		"@effected/git": "^0.4.0",
+		"@effected/glob": "^0.1.1",
+		"@effected/jsonc": "^0.2.0",
+		"@effected/package-json": "^0.3.0",
+		"@effected/walker": "^0.2.1",
+		"@effected/workspaces": "^0.3.1",
+		"@effected/yaml": "^0.3.0",
 		"@manypkg/get-packages": "^3.1.0",
-		"jsonc-effect": "^0.3.1",
 		"mdast-util-heading-range": "^4.0.0",
 		"mdast-util-to-string": "^4.0.0",
 		"prettier": "^3.9.5",
 		"remark-gfm": "^4.0.1",
 		"remark-parse": "^11.0.0",
 		"remark-stringify": "^11.0.0",
-		"semver-effect": "^0.3.1",
 		"shell-quote": "^1.10.0",
 		"sort-package-json": "^4.0.0",
-		"tinyglobby": "^0.2.17",
 		"unified": "^11.0.5",
 		"unified-lint-rule": "^3.0.1",
 		"unist-util-visit": "^5.1.0",
-		"workspaces-effect": "^2.1.0",
-		"yaml": "^2.9.0",
-		"yaml-effect": "^0.7.2",
 		"yaml-lint": "^1.7.0"
 	},
 	"peerDependencies": {
-		"@effect/platform": "^0.96.0",
-		"effect": "^3.21.0"
+		"effect": "4.0.0-beta.98"
 	}
 }

package/repos/index.js

@@ -3,8 +3,8 @@ import { MANIFEST_PATH, REPOS_DIR } from "./constants.js";
 import { GitSubmoduleError, GitSubmoduleErrorBase, NoteNotFoundError, NoteNotFoundErrorBase, RepoNotFoundError, RepoNotFoundErrorBase, ReposConfigError, ReposConfigErrorBase } from "./errors.js";
 import { RepoEntry, RepoName, RepoNote, RepoOrientation, ReposManifestFile } from "./schemas/manifest.js";
 import { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport } from "./schemas/reports.js";
-import { ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive } from "./services/config-store.js";
-import { ReposManager, ReposManagerBase, ReposManagerLive, STALE_LOCK_MAX_AGE_MS } from "./services/manager.js";
+import { ReposConfigStore, ReposConfigStoreLive } from "./services/config-store.js";
+import { ReposManager, ReposManagerLive, STALE_LOCK_MAX_AGE_MS } from "./services/manager.js";
 
 //#region src/repos/index.ts
 var repos_exports = /* @__PURE__ */ __exportAll({
@@ -26,10 +26,8 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 	ReposConfigError: () => ReposConfigError,
 	ReposConfigErrorBase: () => ReposConfigErrorBase,
 	ReposConfigStore: () => ReposConfigStore,
-	ReposConfigStoreBase: () => ReposConfigStoreBase,
 	ReposConfigStoreLive: () => ReposConfigStoreLive,
 	ReposManager: () => ReposManager,
-	ReposManagerBase: () => ReposManagerBase,
 	ReposManagerLive: () => ReposManagerLive,
 	ReposManifestFile: () => ReposManifestFile,
 	ReposNoteResult: () => ReposNoteResult,
@@ -40,4 +38,4 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive, ReposManager, ReposManagerBase, ReposManagerLive, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, repos_exports };
+export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreLive, ReposManager, ReposManagerLive, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, repos_exports };

package/repos/schemas/manifest.js

@@ -7,7 +7,7 @@ import { Schema } from "effect";
 * (`.repos/<name>`) without escaping the `.repos/` directory.
 * @public
 */
-const RepoName = Schema.String.pipe(Schema.pattern(/^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/), Schema.annotations({ identifier: "RepoName" }));
+const RepoName = Schema.String.check(Schema.isPattern(/^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/)).annotate({ identifier: "RepoName" });
 /**
 * An agent-appended note: a discovered answer stamped with the pin it was written against.
 * @public
@@ -16,7 +16,7 @@ const RepoNote = Schema.Struct({
 	id: Schema.String,
 	date: Schema.String,
 	ref: Schema.String,
-	note: Schema.String.pipe(Schema.minLength(1))
+	note: Schema.String.check(Schema.isMinLength(1))
 });
 /**
 * Curated per-repo orientation: layout, entry points, where to start.
@@ -24,10 +24,7 @@ const RepoNote = Schema.Struct({
 */
 const RepoOrientation = Schema.Struct({
 	layout: Schema.optional(Schema.String),
-	keyPaths: Schema.optional(Schema.Record({
-		key: Schema.String,
-		value: Schema.String
-	})),
+	keyPaths: Schema.optional(Schema.Record(Schema.String, Schema.String)),
 	startHere: Schema.optional(Schema.String)
 });
 /**
@@ -35,9 +32,9 @@ const RepoOrientation = Schema.Struct({
 * @public
 */
 const RepoEntry = Schema.Struct({
-	url: Schema.String.pipe(Schema.minLength(1)),
-	ref: Schema.String.pipe(Schema.minLength(1)),
-	purpose: Schema.String.pipe(Schema.minLength(1)),
+	url: Schema.String.check(Schema.isMinLength(1)),
+	ref: Schema.String.check(Schema.isMinLength(1)),
+	purpose: Schema.String.check(Schema.isMinLength(1)),
 	sparse: Schema.optional(Schema.Array(Schema.String)),
 	orientation: Schema.optional(RepoOrientation),
 	notes: Schema.optional(Schema.Array(RepoNote))
@@ -61,10 +58,7 @@ const isRepoName = Schema.is(RepoName);
 * The committed .repos/config.json manifest.
 * @public
 */
-const ReposManifestFile = Schema.Struct({ repos: Schema.Record({
-	key: Schema.String,
-	value: RepoEntry
-}).pipe(Schema.filter((repos) => {
+const ReposManifestFile = Schema.Struct({ repos: Schema.Record(Schema.String, RepoEntry).check(Schema.makeFilter((repos) => {
 	const badKey = Object.keys(repos).find((key) => !isRepoName(key));
 	return badKey === void 0 ? void 0 : `every repos key must be a valid RepoName (non-empty, no "/" or "\\", not "." or ".."); got ${JSON.stringify(badKey)}`;
 })) });

package/repos/schemas/reports.js

@@ -62,7 +62,11 @@ const ReposAddResult = Schema.Struct({
 */
 const ReposNoteResult = Schema.Struct({
 	name: Schema.String,
-	op: Schema.Literal("add", "remove", "promote"),
+	op: Schema.Literals([
+		"add",
+		"remove",
+		"promote"
+	]),
 	id: Schema.String,
 	noteCount: Schema.Number
 });

package/repos/services/config-store.js

@@ -1,20 +1,16 @@
 import { MANIFEST_PATH, REPOS_DIR } from "../constants.js";
 import { ReposConfigError } from "../errors.js";
 import { ReposManifestFile } from "../schemas/manifest.js";
-import { Context, Effect, Layer, Schema } from "effect";
-import { FileSystem, Path } from "@effect/platform";
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
 
 //#region src/repos/services/config-store.ts
-const _tag = Context.Tag("@savvy-web/silk-effects/ReposConfigStore");
-/** @internal */
-const ReposConfigStoreBase = _tag();
 /**
 * Reads, validates, and writes the .repos/config.json manifest.
 * @public
 */
-var ReposConfigStore = class extends ReposConfigStoreBase {};
+var ReposConfigStore = class extends Context.Service()("@savvy-web/silk-effects/ReposConfigStore") {};
 /**
-* Live layer over the platform FileSystem.
+* Live layer over the core FileSystem.
 * @public
 */
 const ReposConfigStoreLive = Layer.effect(ReposConfigStore, Effect.gen(function* () {
@@ -45,7 +41,7 @@ const ReposConfigStoreLive = Layer.effect(ReposConfigStore, Effect.gen(function*
 				kind: "invalid"
 			})
 		});
-		return yield* Schema.decodeUnknown(ReposManifestFile)(json).pipe(Effect.mapError((cause) => new ReposConfigError({
+		return yield* Schema.decodeUnknownEffect(ReposManifestFile)(json).pipe(Effect.mapError((cause) => new ReposConfigError({
 			path: manifestPath(root),
 			reason: String(cause),
 			kind: "invalid"
@@ -58,7 +54,7 @@ const ReposConfigStoreLive = Layer.effect(ReposConfigStore, Effect.gen(function*
 			reason: `mkdir failed: ${String(cause)}`,
 			kind: "invalid"
 		})));
-		const encoded = yield* Schema.encode(ReposManifestFile)(manifest).pipe(Effect.mapError((cause) => new ReposConfigError({
+		const encoded = yield* Schema.encodeEffect(ReposManifestFile)(manifest).pipe(Effect.mapError((cause) => new ReposConfigError({
 			path: manifestPath(root),
 			reason: String(cause),
 			kind: "invalid"
@@ -83,4 +79,4 @@ const ReposConfigStoreLive = Layer.effect(ReposConfigStore, Effect.gen(function*
 }));
 
 //#endregion
-export { ReposConfigStore, ReposConfigStoreBase, ReposConfigStoreLive };
+export { ReposConfigStore, ReposConfigStoreLive };

package/repos/services/manager.js

@@ -2,8 +2,8 @@ import { MANIFEST_PATH, REPOS_DIR } from "../constants.js";
 import { GitSubmoduleError, NoteNotFoundError, RepoNotFoundError, ReposConfigError } from "../errors.js";
 import { RepoName } from "../schemas/manifest.js";
 import { ReposConfigStore } from "./config-store.js";
-import { Clock, Context, Effect, Layer, Option, Schema, Stream } from "effect";
-import { Command, CommandExecutor, FileSystem, Path } from "@effect/platform";
+import { Clock, Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Git } from "@effected/git";
 import { createHash } from "node:crypto";
 
 //#region src/repos/services/manager.ts
@@ -25,9 +25,6 @@ const STALE_LOCKS = ["index.lock", "shallow.lock"];
 * @public
 */
 const STALE_LOCK_MAX_AGE_MS = 10 * 6e4;
-const _tag = Context.Tag("@savvy-web/silk-effects/ReposManager");
-/** @internal */
-const ReposManagerBase = _tag();
 /**
 * Drives the vendored `.repos/` submodules over git: reports status
 * (presence, dirtiness, stale notes), reconciles the working tree with the
@@ -35,54 +32,38 @@ const ReposManagerBase = _tag();
 * ref (`pin`), and adds, removes, or promotes agent notes (`note`).
 * @public
 */
-var ReposManager = class extends ReposManagerBase {};
+var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/ReposManager") {};
 /**
 * Live implementation of {@link ReposManager}.
 *
 * @remarks
-* Mirrors `TurboInspector`: the `CommandExecutor` is captured once at layer
-* construction and discharged onto each git invocation via
-* `Effect.provideService`, so the public method effects stay at `R = never`.
+* All git plumbing runs through `@effected/git`'s `Git` service (captured once
+* at layer construction; `Git.layer` requires `ChildProcessSpawner` at the app
+* edge), so the public method effects stay at `R = never`. The kit classifies
+* git's exit-code/stderr taxonomy into typed failures, which are mapped onto
+* this module's {@link GitSubmoduleError} to keep the declared error unions.
 * @public
 */
 const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 	const configStore = yield* ReposConfigStore;
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
-	const executor = yield* CommandExecutor.CommandExecutor;
-	const runGit = (cwd, args) => Effect.scoped(Effect.gen(function* () {
-		const process = yield* executor.start(Command.workingDirectory(Command.make("git", ...args), cwd));
-		const [exitCode, stdout, stderr] = yield* Effect.all([
-			process.exitCode,
-			process.stdout.pipe(Stream.decodeText(), Stream.runFold("", (acc, chunk) => acc + chunk)),
-			process.stderr.pipe(Stream.decodeText(), Stream.runFold("", (acc, chunk) => acc + chunk))
-		], { concurrency: 3 });
-		if (exitCode !== 0) return yield* Effect.fail(new GitSubmoduleError({
-			command: `git ${args.join(" ")}`,
-			cwd,
-			reason: stderr.trim().length > 0 ? stderr.trim() : `exit code ${exitCode}`
-		}));
-		return stdout.trim();
-	})).pipe(Effect.catchAll((cause) => Effect.fail(cause instanceof GitSubmoduleError ? cause : new GitSubmoduleError({
-		command: `git ${args.join(" ")}`,
+	const git = yield* Git;
+	/** Map any typed `@effected/git` failure onto this module's `GitSubmoduleError`. */
+	const asSubmoduleError = (command, cwd) => (error) => new GitSubmoduleError({
+		command,
 		cwd,
-		reason: String(cause)
-	}))));
+		reason: error.message
+	});
 	const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
 	const status = (root) => Effect.gen(function* () {
 		const manifest = yield* configStore.read(root);
 		const repos = yield* Effect.forEach(Object.entries(manifest.repos), ([name, entry]) => Effect.gen(function* () {
 			const repoPath = path.join(root, REPOS_DIR, name);
 			const present = yield* isPresent(repoPath);
-			const lsTree = yield* runGit(root, [
-				"ls-tree",
-				"HEAD",
-				"--",
-				`${REPOS_DIR}/${name}`
-			]);
-			const commit = lsTree.length > 0 ? lsTree.split(/\s+/)[2] ?? null : null;
+			const commit = (yield* git.lsTree(root, "HEAD", { pathspec: [`${".repos"}/${name}`] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${".repos"}/${name}`, root))))[0]?.oid ?? null;
 			let dirty = false;
-			if (present) dirty = (yield* runGit(repoPath, ["status", "--porcelain"])).length > 0;
+			if (present) dirty = (yield* git.status(repoPath).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", repoPath)))).length > 0;
 			const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== entry.ref).map((note) => note.id);
 			return {
 				name,
@@ -123,24 +104,15 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 			}
 			if (clearedAnyLock) clearedLocks.push(name);
 			if (!(yield* isPresent(repoPath))) {
-				yield* runGit(root, [
-					"submodule",
-					"update",
-					"--init",
-					"--depth",
-					"1",
-					"--",
-					`${REPOS_DIR}/${name}`
-				]);
+				yield* git.submoduleUpdate(root, {
+					init: true,
+					depth: 1,
+					paths: [`${REPOS_DIR}/${name}`]
+				}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${REPOS_DIR}/${name}`, root)));
 				initialized.push(name);
 			} else upToDate.push(name);
 			if (entry.sparse && entry.sparse.length > 0) {
-				yield* runGit(repoPath, [
-					"sparse-checkout",
-					"set",
-					"--no-cone",
-					...entry.sparse
-				]);
+				yield* git.sparseCheckoutSet(repoPath, entry.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", repoPath)));
 				sparseApplied.push(name);
 			}
 		}
@@ -157,27 +129,22 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 		return last.endsWith(".git") ? last.slice(0, -4) : last;
 	};
 	/**
-	* Fetch `ref` shallow into a submodule. Tags need the explicit
-	* `fetch origin tag <ref>` form; branches/commits fall back to a plain
-	* `fetch origin <ref>`.
+	* Fetch `ref` shallow into a submodule via the kit's `Git.fetchAny`:
+	* tag-form fetch first (tags need the explicit `fetch origin tag <ref>`
+	* form), falling back to a plain `fetch origin <ref>` on
+	* `UnknownRefError` OR `GitCommandError` (unclassified tag-form stderr
+	* keeps the v3 any-failure fallback). `NotARepositoryError` deliberately
+	* does NOT fall back — a plain fetch in a non-repo fails identically, so
+	* retrying only doubled the latency of a certain failure. When both
+	* attempts fail, the plain fetch's error surfaces.
 	*/
-	const fetchRef = (sub, ref) => runGit(sub, [
-		"fetch",
-		"--depth",
-		"1",
-		"origin",
-		"tag",
-		ref
-	]).pipe(Effect.orElse(() => runGit(sub, [
-		"fetch",
-		"--depth",
-		"1",
-		"origin",
-		ref
-	])));
+	const fetchRef = (sub, ref) => git.fetchAny(sub, {
+		ref,
+		depth: 1
+	}).pipe(Effect.mapError(asSubmoduleError(`git fetch --depth 1 origin ${ref}`, sub)));
 	const add = (root, options) => Effect.gen(function* () {
 		const name = options.name ?? repoSlug(options.url);
-		yield* Schema.decodeUnknown(RepoName)(name).pipe(Effect.mapError(() => new ReposConfigError({
+		yield* Schema.decodeUnknownEffect(RepoName)(name).pipe(Effect.mapError(() => new ReposConfigError({
 			path: MANIFEST_PATH,
 			reason: `invalid repo name "${name}": must be non-empty, contain no "/" or "\\", and not be "." or ".."`,
 			kind: "invalid"
@@ -190,33 +157,15 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 		}));
 		const repoPath = `${REPOS_DIR}/${name}`;
 		const subPath = path.join(root, repoPath);
-		yield* runGit(root, [
-			"submodule",
-			"add",
-			"--depth",
-			"1",
-			options.url,
-			repoPath
-		]);
-		yield* runGit(root, [
-			"config",
-			"-f",
-			".gitmodules",
-			`submodule.${repoPath}.shallow`,
-			"true"
-		]);
+		yield* git.submoduleAdd(root, {
+			url: options.url,
+			path: repoPath,
+			depth: 1
+		}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${options.url} ${repoPath}`, root)));
+		yield* git.configSet(root, `submodule.${repoPath}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPath}.shallow true`, root)));
 		yield* fetchRef(subPath, options.ref);
-		yield* runGit(subPath, [
-			"checkout",
-			"--detach",
-			"FETCH_HEAD"
-		]);
-		if (options.sparse && options.sparse.length > 0) yield* runGit(subPath, [
-			"sparse-checkout",
-			"set",
-			"--no-cone",
-			...options.sparse
-		]);
+		yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
+		if (options.sparse && options.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, options.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
 		const entry = {
 			url: options.url,
 			ref: options.ref,
@@ -227,12 +176,11 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 			...manifest.repos,
 			[name]: entry
 		} });
-		yield* runGit(root, [
-			"add",
+		yield* git.add(root, [
 			".gitmodules",
 			MANIFEST_PATH,
 			repoPath
-		]);
+		]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${MANIFEST_PATH} ${repoPath}`, root)));
 		return {
 			name,
 			ref: options.ref,
@@ -245,14 +193,10 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 		if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
 		const repoPath = `${REPOS_DIR}/${name}`;
 		const subPath = path.join(root, repoPath);
-		const oldCommit = yield* runGit(subPath, ["rev-parse", "HEAD"]).pipe(Effect.orElseSucceed(() => null));
+		const oldCommit = yield* git.revParse(subPath, "HEAD").pipe(Effect.orElseSucceed(() => null));
 		yield* fetchRef(subPath, ref);
-		yield* runGit(subPath, [
-			"checkout",
-			"--detach",
-			"FETCH_HEAD"
-		]);
-		const newCommit = yield* runGit(subPath, ["rev-parse", "HEAD"]);
+		yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
+		const newCommit = yield* git.revParse(subPath, "HEAD").pipe(Effect.mapError(asSubmoduleError("git rev-parse HEAD", subPath)));
 		yield* configStore.write(root, { repos: {
 			...manifest.repos,
 			[name]: {
@@ -260,11 +204,7 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 				ref
 			}
 		} });
-		yield* runGit(root, [
-			"add",
-			MANIFEST_PATH,
-			repoPath
-		]);
+		yield* git.add(root, [MANIFEST_PATH, repoPath]).pipe(Effect.mapError(asSubmoduleError(`git add ${MANIFEST_PATH} ${repoPath}`, root)));
 		const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== ref).map((note) => note.id);
 		return {
 			name,
@@ -371,14 +311,14 @@ const ReposManagerLive = Layer.effect(ReposManager, Effect.gen(function* () {
 			noteCount: updatedNotes.length
 		};
 	});
-	return ReposManager.of({
+	return {
 		status,
 		sync,
 		add,
 		pin,
 		note
-	});
+	};
 }));
 
 //#endregion
-export { ReposManager, ReposManagerBase, ReposManagerLive, STALE_LOCK_MAX_AGE_MS };
+export { ReposManager, ReposManagerLive, STALE_LOCK_MAX_AGE_MS };

package/schemas/CommentStyle.js

@@ -11,7 +11,7 @@ import { Schema } from "effect";
 * @since 0.1.0
 * @public
 */
-const CommentStyle = Schema.Literal("#", "//");
+const CommentStyle = Schema.Literals(["#", "//"]);
 
 //#endregion
 export { CommentStyle };