@savvy-web/silk-effects 9.2.1 → 9.3.0

package/changesets/schemas/dependency-table.js

@@ -95,7 +95,7 @@ const DependencyTableTypeSchema = Schema.Literals([
 *
 * @public
 */
-const VERSION_RE = /^(\u2014|[~^]?\d+\.\d+\.\d+(?:[-+.][\w.+-]+)?|(?:catalog|workspace|npm|jsr|file|link|portal):[^\s|]+)$/;
+const VERSION_RE = /^(\u2014|[~^]?\d+\.\d+\.\d+(?:[-+.][\w.+-]+)?|(?:catalog|workspace|npm|jsr|file|link|portal):[^\s|]+)$/u;
 /**
 * Version string or em dash (U+2014) sentinel for added/removed entries.
 *

package/changesets/schemas/git.js

@@ -40,7 +40,7 @@ import { Schema } from "effect";
 *
 * @public
 */
-const CommitHashSchema = Schema.String.check(Schema.isPattern(/^[a-f0-9]{7,}$/, { message: "Commit hash must be 7 or more lowercase hexadecimal characters (0-9, a-f). Example: \"a1b2c3d\" or a full 40-character SHA like \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\". Uppercase letters are not allowed" }));
+const CommitHashSchema = Schema.String.check(Schema.isPattern(/^[a-f0-9]{7,}$/u, { message: "Commit hash must be 7 or more lowercase hexadecimal characters (0-9, a-f). Example: \"a1b2c3d\" or a full 40-character SHA like \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\". Uppercase letters are not allowed" }));
 /**
 * Semantic version bump type.
 *

package/changesets/schemas/github.js

@@ -52,7 +52,7 @@ function isValidUrl(value) {
 *
 * @public
 */
-const UsernameSchema = Schema.String.check(Schema.isPattern(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, { message: "Invalid GitHub username format. Usernames must contain only alphanumeric characters and hyphens, and cannot start or end with a hyphen. Example: \"octocat\" or \"my-user-123\"" }));
+const UsernameSchema = Schema.String.check(Schema.isPattern(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/u, { message: "Invalid GitHub username format. Usernames must contain only alphanumeric characters and hyphens, and cannot start or end with a hyphen. Example: \"octocat\" or \"my-user-123\"" }));
 /**
 * Schema for a GitHub issue or PR number (positive integer).
 *

package/changesets/schemas/options.js

@@ -23,7 +23,7 @@ import { Effect, Schema } from "effect";
 *
 */
 /** Regex for `owner/repo` format, shared between schema and validation. */
-const REPO_PATTERN = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+const REPO_PATTERN = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/u;
 /**
 * Schema for a GitHub repository in `owner/repo` format.
 *

package/changesets/schemas/version-files.js

@@ -54,7 +54,7 @@ import { Schema } from "effect";
 *
 * @public
 */
-const JsonPathSchema = Schema.String.check(Schema.isPattern(/^\$\.[^.]/, { message: "JSONPath must start with \"$.\" followed by a property (e.g., \"$.version\", \"$.metadata.version\")" }));
+const JsonPathSchema = Schema.String.check(Schema.isPattern(/^\$\.[^.]/u, { message: "JSONPath must start with \"$.\" followed by a property (e.g., \"$.version\", \"$.metadata.version\")" }));
 /**
 * Schema for a single version file configuration entry — **new shape**.
 *

package/changesets/services/branch-analyzer.js

@@ -103,6 +103,7 @@ function resolveBaseBranch(git, opts) {
 }
 function makeShape(inspector, git) {
 	const analyzeBranch = (cwd, opts) => Effect.gen(function* () {
+		yield* inspector.refreshIn(cwd);
 		const inspected = yield* inspector.inspect(cwd);
 		const baseBranch = yield* resolveBaseBranch(git, {
 			explicit: opts?.baseBranch,

package/changesets/services/deps-regen.js

@@ -5,12 +5,12 @@ import { ChangesetConfig } from "../../services/ChangesetConfig.js";
 import { SilkPublishability } from "../../services/SilkPublishability.js";
 import { ConfigInspector } from "./config-inspector.js";
 import { computeWorkspaceDependencyDiffs } from "../utils/dep-diff.js";
-import { gitListChangesetFilesAtRef, gitMergeBase, gitShowFileAtRef } from "../utils/git.js";
+import { gitListChangesetFilesAtRef, gitMergeBase, gitResolveRef, gitShowFileAtRef } from "../utils/git.js";
 import { listPublishablePackageNames } from "../utils/publishability.js";
 import { Context, Effect, FileSystem, Layer, Option } from "effect";
 import { basename, join, resolve } from "node:path";
 import { Git } from "@effected/git";
-import { PublishabilityDetector, WorkspaceDiscovery, WorkspaceSnapshots, Workspaces } from "@effected/workspaces";
+import { LockfileReader, PublishabilityDetector, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceSnapshots, Workspaces } from "@effected/workspaces";
 import { Yaml } from "@effected/yaml";
 
 //#region src/changesets/services/deps-regen.ts
@@ -322,24 +322,35 @@ var DepsRegen = class extends Context.Service()("Changesets/DepsRegen") {
 	/**
 	* Production layer for {@link DepsRegen}.
 	*
-	* Requires `WorkspaceSnapshots`, `WorkspaceDiscovery`,
-	* `PublishabilityDetector` (all from `@effected/workspaces`),
+	* Requires `WorkspaceSnapshots`, `WorkspaceDiscovery`, `WorkspaceCatalogs`,
+	* `LockfileReader`, `PublishabilityDetector` (all from `@effected/workspaces`),
 	* `Git` (from `@effected/git`, backing merge-base resolution),
 	* {@link ConfigInspector}, {@link ChangesetConfig}, and
 	* `FileSystem.FileSystem` (resolved once at construction and closed over by
 	* the shape, keeping `plan`/`execute` themselves requirement-free).
 	*
+	* `WorkspaceCatalogs` and `LockfileReader` must be the SAME instances the
+	* provided `WorkspaceSnapshots` reads its worktree through (one shared kit
+	* graph, as `Workspaces.*` composites give): `plan` refreshes them before
+	* snapshotting the worktree so a long-lived host never diffs against a
+	* memo from an earlier call (savvy-web/systems#715).
+	*
 	* @public
 	*/
 	static layer = Layer.effect(this, Effect.gen(function* () {
 		const snapshots = yield* WorkspaceSnapshots;
 		const inspector = yield* ConfigInspector;
 		const discovery = yield* WorkspaceDiscovery;
+		const catalogs = yield* WorkspaceCatalogs;
+		const lockfiles = yield* LockfileReader;
 		const detector = yield* PublishabilityDetector;
 		const config = yield* ChangesetConfig;
 		const fs = yield* FileSystem.FileSystem;
 		const git = yield* Git;
-		return makeShape(snapshots, inspector, discovery, detector, config, fs, Layer.succeed(Git, git));
+		return makeShape(snapshots, inspector, discovery, {
+			catalogs,
+			lockfiles
+		}, detector, config, fs, Layer.succeed(Git, git));
 	}));
 };
 /**
@@ -347,7 +358,7 @@ var DepsRegen = class extends Context.Service()("Changesets/DepsRegen") {
 * implementations, keeping the public `plan`/`execute` signatures
 * requirement-free (`R = never`).
 */
-function makeShape(snapshots, inspector, discovery, detector, config, fs, provideGit) {
+function makeShape(snapshots, inspector, discovery, worktreeMemos, detector, config, fs, provideGit) {
 	const provideDetector = Layer.succeed(PublishabilityDetector, detector);
 	const fileExists = (p) => fs.exists(p).pipe(Effect.orElseSucceed(() => false));
 	const plan = (options) => Effect.gen(function* () {
@@ -355,18 +366,21 @@ function makeShape(snapshots, inspector, discovery, detector, config, fs, provid
 		const changesetDir = join(resolvedCwd, ".changeset");
 		yield* inspector.refresh();
 		yield* config.refresh();
-		let fromRef = options.from;
+		yield* worktreeMemos.lockfiles.refresh();
+		yield* worktreeMemos.catalogs.refresh();
+		let fromRef = options.from ? yield* gitResolveRef(resolvedCwd, options.from).pipe(Effect.provide(provideGit)) : "";
 		if (!fromRef) {
 			let baseBranch = options.base;
 			if (!baseBranch) baseBranch = (yield* inspector.inspect(resolvedCwd).pipe(Effect.catchTag("ConfigurationError", () => Effect.succeed({ baseBranch: "main" })))).baseBranch;
 			fromRef = yield* gitMergeBase(resolvedCwd, baseBranch).pipe(Effect.provide(provideGit));
 		}
+		const toRef = options.to ? yield* gitResolveRef(resolvedCwd, options.to).pipe(Effect.provide(provideGit)) : void 0;
 		const before = yield* snapshots.at(fromRef);
-		const after = options.to ? yield* snapshots.at(options.to) : yield* snapshots.worktree();
+		const after = toRef ? yield* snapshots.at(toRef) : yield* snapshots.worktree();
 		const workspaceYaml = "pnpm-workspace.yaml";
 		const declaredBefore = yield* declaredConfigDependencies(yield* gitShowFileAtRef(resolvedCwd, fromRef, workspaceYaml).pipe(Effect.provide(provideGit)));
-		const declaredAfter = yield* declaredConfigDependencies(options.to ? yield* gitShowFileAtRef(resolvedCwd, options.to, workspaceYaml).pipe(Effect.provide(provideGit)) : yield* fs.readFileString(join(resolvedCwd, workspaceYaml)).pipe(Effect.option));
-		yield* assertHooksReplayed(fromRef, declaredBefore, before);
+		const declaredAfter = yield* declaredConfigDependencies(toRef ? yield* gitShowFileAtRef(resolvedCwd, toRef, workspaceYaml).pipe(Effect.provide(provideGit)) : yield* fs.readFileString(join(resolvedCwd, workspaceYaml)).pipe(Effect.option));
+		yield* assertHooksReplayed(options.from || fromRef, declaredBefore, before);
 		yield* assertHooksReplayed(options.to ?? "worktree", declaredAfter, after);
 		const rawDiffs = computeWorkspaceDependencyDiffs(before, after);
 		const explicitTargets = /* @__PURE__ */ new Set([...options.packages ?? [], ...options.package ? [options.package] : []]);

package/changesets/services/release-planner.js

@@ -475,6 +475,7 @@ function applyEffect(root, dryRun, changelogModules, snapshot, inspector, fs) {
 			});
 		}
 		const newVersionByName = new Map(plan.releases.map((r) => [r.name, r.newVersion]));
+		yield* inspector.refreshIn(root);
 		const inspected = yield* inspector.inspect(root).pipe(Effect.catch((error) => Effect.logWarning(`Skipping versionFiles update: ${errMsg(error)}`).pipe(Effect.as(null))));
 		let versionFileUpdates = [];
 		if (inspected) {

package/changesets/utils/git.js

@@ -32,6 +32,28 @@ function gitMergeBase(cwd, base) {
 	});
 }
 /**
+* Pin `ref` to the commit it names right now (`git rev-parse --verify`).
+*
+* @remarks
+* `WorkspaceSnapshots.at(ref)` caches per ref STRING for the layer's
+* lifetime, which is only sound for an immutable ref. A branch or tag name
+* handed to a long-lived host (savvy-mcp) would otherwise keep answering
+* from the commit it named on first use (savvy-web/systems#715); keying the
+* snapshot on the SHA makes every cache hit correct by construction.
+*
+* Tolerant: an unresolvable ref, or a `cwd` outside a git repository, hands
+* back `ref` unchanged, so the snapshot read that follows reports the
+* failure in its own typed terms (and synthetic refs keep working against
+* test doubles).
+*
+* @internal
+*/
+function gitResolveRef(cwd, ref) {
+	return Effect.gen(function* () {
+		return yield* (yield* Git).revParse(cwd, ref).pipe(Effect.orElseSucceed(() => ref));
+	});
+}
+/**
 * List the basenames of `.changeset/*.md` files tracked at `ref` (e.g. the
 * merge base), via `git ls-tree -r`. Used by `DepsRegen.plan()`
 * to protect changesets authored by already-merged PRs from being deleted by
@@ -84,4 +106,4 @@ function gitShowFileAtRef(cwd, ref, path) {
 }
 
 //#endregion
-export { gitListChangesetFilesAtRef, gitMergeBase, gitShowFileAtRef };
+export { gitListChangesetFilesAtRef, gitMergeBase, gitResolveRef, gitShowFileAtRef };

package/index.d.ts

@@ -1,11 +1,11 @@
 import { AnalyzedWorkspace, BiomeSyncError, BiomeSyncError as BiomeSyncError$1, BiomeSyncOptions, BiomeSyncResult, BiomeSyncResult as BiomeSyncResult$1, ChangesetConfigError, ChangesetConfigError as ChangesetConfigError$1, ChangesetConfigFile, ChangesetConfigFile as ChangesetConfigFile$1, ConfigDiscoveryOptions, ConfigLocation, ConfigLocation as ConfigLocation$1, ConfigNotFoundError, ConfigSource, LIFECYCLE_SCRIPTS_CONFIG_KEY, PrBody, PublishTargetBindingError, PublishTargetBindingError as PublishTargetBindingError$1, SavvyBaseSection, SavvyHooksSection, SavvyInstallHook, SavvyInstallSection, SavvyOkfSection, SavvyToolchainSection, SilkChangesetConfigFile, SilkChangesetConfigFile as SilkChangesetConfigFile$1, SilkPublishConfig, WorkspaceAnalysis, WorkspaceAnalysis as WorkspaceAnalysis$1, WorkspaceAnalysisError, WorkspaceAnalysisError as WorkspaceAnalysisError$1, publishesBuiltLinkDirectory, savvyBasePreamble, savvyHooksHygiene, savvyInstallBlock, savvyInstallDeps, savvyOkfBlock, savvyOkfSync, savvyToolSection, savvyToolchainCheck } from "@savvy-web/silk-core";
-import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+import { Context, Effect, FileSystem, Layer, Path, PlatformError, Schema } from "effect";
 import { Plugin } from "unified";
 import { ChildProcessSpawner } from "effect/process";
-import { PackageManagerDetector, PublishTarget, PublishabilityDetector, WorkspaceDiscovery, WorkspaceDiscoveryFailure, WorkspacePackage, WorkspaceSnapshotAtFailure, WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, WorkspaceStateSnapshot, WorkspacesOptions } from "@effected/workspaces";
-import { Git } from "@effected/git";
+import { LockfileReader, PackageManagerDetector, PublishTarget, PublishabilityDetector, WorkspaceCatalogs, WorkspaceDiscovery, WorkspaceDiscoveryFailure, WorkspacePackage, WorkspaceSnapshotAtFailure, WorkspaceSnapshotWorktreeFailure, WorkspaceSnapshots, WorkspaceStateSnapshot, WorkspacesOptions } from "@effected/workspaces";
+import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
 import { GlobExpansionError } from "@effected/walker";
-import * as PlatformError from "effect/PlatformError";
+import * as PlatformError$1 from "effect/PlatformError";
 import { YamlFormattingOptions } from "@effected/yaml";
 import { Section, SectionId } from "@effected/templates";
 import { ToolDiscovery } from "@effected/commands";
@@ -3943,16 +3943,22 @@ declare class DepsRegen extends DepsRegen_base {
   /**
    * Production layer for {@link DepsRegen}.
    *
-   * Requires `WorkspaceSnapshots`, `WorkspaceDiscovery`,
-   * `PublishabilityDetector` (all from `@effected/workspaces`),
+   * Requires `WorkspaceSnapshots`, `WorkspaceDiscovery`, `WorkspaceCatalogs`,
+   * `LockfileReader`, `PublishabilityDetector` (all from `@effected/workspaces`),
    * `Git` (from `@effected/git`, backing merge-base resolution),
    * {@link ConfigInspector}, {@link ChangesetConfig}, and
    * `FileSystem.FileSystem` (resolved once at construction and closed over by
    * the shape, keeping `plan`/`execute` themselves requirement-free).
    *
+   * `WorkspaceCatalogs` and `LockfileReader` must be the SAME instances the
+   * provided `WorkspaceSnapshots` reads its worktree through (one shared kit
+   * graph, as `Workspaces.*` composites give): `plan` refreshes them before
+   * snapshotting the worktree so a long-lived host never diffs against a
+   * memo from an earlier call (savvy-web/systems#715).
+   *
    * @public
    */
-  static readonly layer: Layer.Layer<DepsRegen, never, WorkspaceSnapshots | ConfigInspector | WorkspaceDiscovery | PublishabilityDetector | ChangesetConfig | Git | FileSystem.FileSystem>;
+  static readonly layer: Layer.Layer<DepsRegen, never, WorkspaceSnapshots | ConfigInspector | WorkspaceDiscovery | WorkspaceCatalogs | LockfileReader | PublishabilityDetector | ChangesetConfig | Git | FileSystem.FileSystem>;
 }
 /**
  * Build the batteries-included {@link DepsRegen} layer over a
@@ -5119,7 +5125,7 @@ declare class VersionFiles {
    * @see {@link jsonPathResolve} for concrete-path enumeration
    * @see {@link VersionFiles.applyVersionEdit} for the per-path edit
    */
-  static updateFile(filePath: string, jsonPaths: readonly string[], version: string): Effect.Effect<VersionFileUpdate | undefined, PlatformError.PlatformError, FileSystem.FileSystem>;
+  static updateFile(filePath: string, jsonPaths: readonly string[], version: string): Effect.Effect<VersionFileUpdate | undefined, PlatformError$1.PlatformError, FileSystem.FileSystem>;
   /**
    * Compute the full update for a document without touching the filesystem:
    * the edited content, the previous values at every matched path, and how
@@ -6955,6 +6961,23 @@ interface ShellScriptsOptions extends BaseHandlerOptions {
    */
   makeExecutable?: boolean;
 }
+/**
+ * Options for the TextFiles handler: only the shared `exclude` list.
+ */
+type TextFilesOptions = BaseHandlerOptions;
+/**
+ * Options for `TextFiles.listTracked`.
+ */
+interface TextFilesListOptions extends BaseHandlerOptions {
+  /**
+   * List for a staged (index) check: keep every regular-file index entry,
+   * including one deleted from the working tree without the deletion being
+   * staged — the commit still records its blob. When `false`, entries with
+   * no working-tree file are dropped, since a worktree read would fail.
+   * @defaultValue false
+   */
+  staged?: boolean;
+}
 /**
  * Options for the Yaml handler.
  */
@@ -7018,6 +7041,10 @@ interface CreateConfigOptions {
    * Options for ShellScripts handler, or false to disable.
    */
   shellScripts?: ShellScriptsOptions | false;
+  /**
+   * Options for TextFiles handler (NUL-byte / invalid UTF-8 check), or false to disable.
+   */
+  textFiles?: TextFilesOptions | false;
   /**
    * Options for Yaml handler, or false to disable.
    */
@@ -7519,6 +7546,244 @@ declare class ShellScripts {
   static create(options?: ShellScriptsOptions): LintStagedHandler;
 }
 //#endregion
+//#region src/lint/handlers/TextFiles.d.ts
+/**
+ * Why a file is not grep-visible text.
+ *
+ * @remarks
+ * `"nul"` — the file contains a NUL byte, which ripgrep (anywhere) and
+ * `git grep -I` (first 8000 bytes) take as the mark of a binary file and
+ * silently skip. `"invalid-utf8"` — the bytes are not well-formed UTF-8.
+ *
+ * @public
+ */
+declare const TextFileViolationReason: Schema.Literals<readonly ["nul", "invalid-utf8"]>;
+/** @public */
+type TextFileViolationReason = typeof TextFileViolationReason.Type;
+declare const TextFileViolation_base: Schema.Class<TextFileViolation, Schema.Struct<{
+  readonly reason: Schema.Literals<readonly ["nul", "invalid-utf8"]>;
+  readonly offset: Schema.Number;
+  readonly line: Schema.Number;
+  readonly column: Schema.Number;
+}>, {}>;
+/**
+ * The first occurrence of one {@link TextFileViolationReason} in a byte buffer.
+ *
+ * @remarks
+ * `offset` is the 0-based byte offset of the offending byte (for
+ * `"invalid-utf8"`, the first byte of the ill-formed sequence). `line` is
+ * 1-based and unambiguous even in invalid input: LF never occurs inside a
+ * multi-byte UTF-8 sequence. `column` is the 1-based character column,
+ * counting code points on the line before the offset (a leading BOM is not
+ * counted); when the line prefix itself holds invalid bytes it is an
+ * approximation, and `offset` is the exact position.
+ *
+ * @public
+ */
+declare class TextFileViolation extends TextFileViolation_base {}
+declare const TextFileFinding_base: Schema.Class<TextFileFinding, Schema.Struct<{
+  readonly path: Schema.String;
+  readonly reason: Schema.Literals<readonly ["nul", "invalid-utf8"]>;
+  readonly offset: Schema.Number;
+  readonly line: Schema.Number;
+  readonly column: Schema.Number;
+}>, {}>;
+/**
+ * A {@link TextFileViolation} found in a named file.
+ *
+ * @public
+ */
+declare class TextFileFinding extends TextFileFinding_base {
+  /** `path:line:column`, the form editors and terminals turn into a link. */
+  get location(): string;
+  /** A one-line explanation with the mechanical fix. */
+  get message(): string;
+}
+/**
+ * Base of {@link TextFileStagedReadError}, exported so downstream declaration
+ * emit can name it (an unexported `Data.TaggedError` base fails TS4023 in any
+ * package whose inferred types carry the error).
+ *
+ * @internal
+ */
+declare const TextFileStagedReadErrorBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TextFileStagedReadError";
+} & Readonly<A>;
+/**
+ * A file's staged (index) content could not be read.
+ *
+ * @remarks
+ * Raised by {@link TextFiles.readStaged} when `git cat-file` exits non-zero —
+ * typically because the path has no stage-0 index entry (never added, or
+ * mid-merge), or the directory is not inside a git repository.
+ *
+ * @public
+ */
+declare class TextFileStagedReadError extends TextFileStagedReadErrorBase<{
+  readonly path: string;
+  readonly exitCode: number;
+  readonly stderr: string;
+}> {
+  get message(): string;
+}
+/**
+ * The outcome of {@link TextFiles.checkStagedFiles}: the findings in every
+ * staged blob that could be read, and a read error for each file that could
+ * not.
+ *
+ * @remarks
+ * An unreadable file does not stop the check: every other file is still read
+ * and classified, so one path without an index entry cannot hide a finding
+ * elsewhere. Both arrays keep the input order.
+ *
+ * @public
+ */
+interface TextFileStagedCheck {
+  /** One finding per violation across the readable files. */
+  readonly findings: ReadonlyArray<TextFileFinding>;
+  /** One error per file whose staged content could not be read. */
+  readonly unreadable: ReadonlyArray<TextFileStagedReadError>;
+}
+/**
+ * Handler for grep-visible text files.
+ *
+ * Fails a commit when a staged source file contains a NUL byte or is not
+ * valid UTF-8 — the two ways a text file becomes invisible to `grep`/`rg`,
+ * which then return false negatives instead of an error.
+ *
+ * @remarks
+ * The check is read-only, so its glob may overlap the Biome `--write` key
+ * without a staging conflict. The lint-staged handler shells out to
+ * `savvy lint text --staged <files>` (reading the index, not the worktree),
+ * the same command `savvy lint text` runs with no
+ * arguments over every git-tracked file matching {@link TextFiles.glob}. The
+ * fix is always mechanical: write `\0` as an escape, never a literal NUL.
+ *
+ * @example
+ * ```typescript
+ * import { TextFiles } from '\@savvy-web/silk/lint';
+ *
+ * export default {
+ *   [TextFiles.glob]: TextFiles.create({ exclude: ['vendor/'] }),
+ * };
+ * ```
+ *
+ * @public
+ */
+declare class TextFiles {
+  /**
+   * File extensions checked: source, config, docs and shell text.
+   */
+  static readonly extensions: readonly ["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "json", "jsonc", "md", "mdx", "yml", "yaml", "toml", "css", "sh", "bats"];
+  /**
+   * Glob pattern for matching checked files, derived from {@link TextFiles.extensions}.
+   * @defaultValue `'**\/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc,md,mdx,yml,yaml,toml,css,sh,bats}'`
+   */
+  static readonly glob: string;
+  /**
+   * Default patterns to exclude from checking.
+   * @defaultValue `[]`
+   */
+  static readonly defaultExcludes: readonly [];
+  /**
+   * Pre-configured handler with default options.
+   */
+  static readonly handler: LintStagedHandler;
+  /**
+   * Whether `path` has one of the checked {@link TextFiles.extensions}.
+   *
+   * @param path - A file path
+   * @returns `true` when the file is in scope
+   */
+  static matches(path: string): boolean;
+  /**
+   * Classify a file's bytes.
+   *
+   * @remarks
+   * Pure. Returns the first NUL byte and the first ill-formed UTF-8 sequence,
+   * each at most once, ordered by offset; an empty array means the bytes are
+   * grep-visible text. A UTF-8 BOM is valid, and an empty buffer passes.
+   *
+   * @param bytes - The file contents
+   * @returns The violations found, empty when none
+   */
+  static classify(bytes: Uint8Array): ReadonlyArray<TextFileViolation>;
+  /**
+   * Read and classify each file, in order.
+   *
+   * @param paths - Files to check
+   * @returns One finding per violation, empty when every file passes
+   */
+  static checkFiles(paths: ReadonlyArray<string>): Effect.Effect<ReadonlyArray<TextFileFinding>, PlatformError.PlatformError, FileSystem.FileSystem>;
+  /**
+   * Read a file's staged bytes from the git index, not the working tree.
+   *
+   * @remarks
+   * Runs `git cat-file blob :./<name>` from the file's own directory, so an
+   * absolute path (what lint-staged passes) and a relative one both resolve
+   * against the right repository without computing a repo-relative path.
+   * When that directory is gone from the working tree (a staged file whose
+   * directory was deleted, deletion unstaged), it runs from the nearest
+   * existing ancestor with the path relative to it instead.
+   * Stdout is collected as raw bytes — `\@effected/git`'s `show` decodes to a
+   * string, which would erase exactly the NULs and invalid bytes this check
+   * looks for. Reading the index makes the lint-staged run race-free against
+   * concurrent `--write` tasks on the working tree, and checks exactly what
+   * the commit will record.
+   *
+   * @param path - File path, absolute or relative to the process cwd
+   * @returns The staged blob's bytes
+   */
+  static readStaged(path: string): Effect.Effect<Uint8Array, TextFileStagedReadError | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Read each file's STAGED content (see {@link TextFiles.readStaged}) and
+   * classify it, in order.
+   *
+   * @remarks
+   * Every file is checked: a file whose staged content cannot be read is
+   * collected into {@link TextFileStagedCheck.unreadable} rather than
+   * failing the whole check, so it cannot hide findings in the others. Only
+   * a platform failure (git could not be spawned) fails the effect.
+   *
+   * @param paths - Files to check
+   * @returns The findings, and a read error per unreadable file; both empty when every staged blob passes
+   */
+  static checkStagedFiles(paths: ReadonlyArray<string>): Effect.Effect<TextFileStagedCheck, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path>;
+  /**
+   * List the git-tracked files under `cwd` that this check covers.
+   *
+   * @remarks
+   * Reads the index (`git ls-files`), keeping regular files (modes `100644`
+   * and `100755`) — gitlinks and symlinks are not file contents — that match
+   * {@link TextFiles.matches} and are not excluded. For a worktree check the
+   * file must also still exist in the working tree; with `staged: true` it
+   * need not, since a file deleted from the worktree without the deletion
+   * staged is still in the commit and {@link TextFiles.readStaged} reads its
+   * blob from the index. Paths come back joined onto `cwd`, deduplicated
+   * across the stages of an unresolved merge.
+   *
+   * @param cwd - Repository directory to list from
+   * @param options - `exclude` patterns (defaults to {@link TextFiles.defaultExcludes}) and `staged`
+   * @returns The files to check
+   */
+  static listTracked(cwd: string, options?: TextFilesListOptions): Effect.Effect<ReadonlyArray<string>, GitCommandError | NotARepositoryError | UnknownRefError | PlatformError.PlatformError, Git | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Create a handler with custom options.
+   *
+   * @remarks
+   * Returns a `savvy lint text --staged <files>` command rather than checking
+   * in the handler body, so the check runs with the same code as the CLI.
+   * `--staged` reads each file from the git index: lint-staged runs other
+   * glob keys (Biome `--write`) concurrently against the working tree, and a
+   * worktree read could observe a half-written file. The index only changes
+   * when lint-staged re-stages, after every task has finished.
+   *
+   * @param options - Configuration options
+   * @returns A lint-staged compatible handler function
+   */
+  static create(options?: TextFilesOptions): LintStagedHandler;
+}
+//#endregion
 //#region src/lint/handlers/TypeScript.d.ts
 /**
  * TypeScript compiler to use.
@@ -7826,6 +8091,7 @@ declare class Preset {
    * - Yaml (format + lint)
    * - PnpmWorkspace (sort + format)
    * - ShellScripts (chmod management)
+   * - TextFiles (NUL-byte / invalid UTF-8 check)
    *
    * @param extend - Options to customize or extend the preset
    * @returns A lint-staged configuration object
@@ -7850,6 +8116,7 @@ declare class Preset {
    * - Yaml (format + lint)
    * - PnpmWorkspace (sort + format)
    * - ShellScripts (chmod management)
+   * - TextFiles (NUL-byte / invalid UTF-8 check)
    * - TypeScript (TSDoc + typecheck)
    *
    * @param extend - Options to customize or extend the preset
@@ -8421,7 +8688,7 @@ declare const MARKDOWNLINT_CONFIG: {
   readonly "changeset-dependency-table-format": false;
 };
 declare namespace index_d_exports$2 {
-  export { BaseHandlerOptions, Biome, BiomeOptions, Command, CreateConfigOptions, DEFAULT_CONFIG_PATH, Filter, HUSKY_HOOK_PATH, Handler, LegacySavvyLintHygieneDef, LintStagedConfig, LintStagedEntry, LintStagedHandler, MARKDOWNLINT_CONFIG, MARKDOWNLINT_CONFIG_PATH, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE, Markdown, MarkdownOptions, POST_CHECKOUT_HOOK_PATH, POST_COMMIT_HOOK_PATH, POST_MERGE_HOOK_PATH, PackageJson, PackageJsonOptions, PackageManager, PnpmWorkspace, PnpmWorkspaceContent, PnpmWorkspaceOptions, Preset, PresetExtendOptions, PresetType, SavvyLintSectionDef, ShellScripts, ShellScriptsOptions, ToolSearchResult, TypeScript, TypeScriptCompiler, TypeScriptOptions, WorkspacePackageInfo, Yaml, YamlOptions, createConfig, generateManagedContent, getWorkspacePackagePaths, getWorkspacePackages, getWorkspaceRoot, isWorkspacePackagePath, resetWorkspaceCache, savvyLintBlock };
+  export { BaseHandlerOptions, Biome, BiomeOptions, Command, CreateConfigOptions, DEFAULT_CONFIG_PATH, Filter, HUSKY_HOOK_PATH, Handler, LegacySavvyLintHygieneDef, LintStagedConfig, LintStagedEntry, LintStagedHandler, MARKDOWNLINT_CONFIG, MARKDOWNLINT_CONFIG_PATH, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE, Markdown, MarkdownOptions, POST_CHECKOUT_HOOK_PATH, POST_COMMIT_HOOK_PATH, POST_MERGE_HOOK_PATH, PackageJson, PackageJsonOptions, PackageManager, PnpmWorkspace, PnpmWorkspaceContent, PnpmWorkspaceOptions, Preset, PresetExtendOptions, PresetType, SavvyLintSectionDef, ShellScripts, ShellScriptsOptions, TextFileFinding, TextFileStagedCheck, TextFileStagedReadError, TextFileStagedReadErrorBase, TextFileViolation, TextFileViolationReason, TextFiles, TextFilesListOptions, TextFilesOptions, ToolSearchResult, TypeScript, TypeScriptCompiler, TypeScriptOptions, WorkspacePackageInfo, Yaml, YamlOptions, createConfig, generateManagedContent, getWorkspacePackagePaths, getWorkspacePackages, getWorkspaceRoot, isWorkspacePackagePath, resetWorkspaceCache, savvyLintBlock };
 }
 //#endregion
 //#region src/repos/constants.d.ts

package/lint/config/Preset.js

@@ -46,6 +46,7 @@ var Preset = class Preset {
 			yaml: extend.yaml ?? false,
 			pnpmWorkspace: extend.pnpmWorkspace ?? false,
 			shellScripts: extend.shellScripts ?? false,
+			textFiles: extend.textFiles ?? false,
 			typescript: extend.typescript ?? false
 		};
 		if (extend.custom !== void 0) options.custom = extend.custom;
@@ -61,6 +62,7 @@ var Preset = class Preset {
 	* - Yaml (format + lint)
 	* - PnpmWorkspace (sort + format)
 	* - ShellScripts (chmod management)
+	* - TextFiles (NUL-byte / invalid UTF-8 check)
 	*
 	* @param extend - Options to customize or extend the preset
 	* @returns A lint-staged configuration object
@@ -82,6 +84,7 @@ var Preset = class Preset {
 			yaml: extend.yaml ?? {},
 			pnpmWorkspace: extend.pnpmWorkspace ?? {},
 			shellScripts: extend.shellScripts ?? {},
+			textFiles: extend.textFiles ?? {},
 			typescript: extend.typescript ?? false
 		};
 		if (extend.custom !== void 0) options.custom = extend.custom;
@@ -97,6 +100,7 @@ var Preset = class Preset {
 	* - Yaml (format + lint)
 	* - PnpmWorkspace (sort + format)
 	* - ShellScripts (chmod management)
+	* - TextFiles (NUL-byte / invalid UTF-8 check)
 	* - TypeScript (TSDoc + typecheck)
 	*
 	* @param extend - Options to customize or extend the preset
@@ -119,6 +123,7 @@ var Preset = class Preset {
 			yaml: extend.yaml ?? {},
 			pnpmWorkspace: extend.pnpmWorkspace ?? {},
 			shellScripts: extend.shellScripts ?? {},
+			textFiles: extend.textFiles ?? {},
 			typescript: extend.typescript ?? {}
 		};
 		if (extend.custom !== void 0) options.custom = extend.custom;

package/lint/config/createConfig.js

@@ -3,6 +3,7 @@ import { Markdown } from "../handlers/Markdown.js";
 import { PackageJson } from "../handlers/PackageJson.js";
 import { PnpmWorkspace } from "../handlers/PnpmWorkspace.js";
 import { ShellScripts } from "../handlers/ShellScripts.js";
+import { TextFiles } from "../handlers/TextFiles.js";
 import { TypeScript } from "../handlers/TypeScript.js";
 import { Yaml } from "../handlers/Yaml.js";
 
@@ -77,6 +78,10 @@ function createConfig(options = {}) {
 		const handlerOptions = typeof options.shellScripts === "object" ? options.shellScripts : {};
 		config[ShellScripts.glob] = ShellScripts.create(handlerOptions);
 	}
+	if (options.textFiles !== false) {
+		const handlerOptions = typeof options.textFiles === "object" ? options.textFiles : {};
+		config[TextFiles.glob] = TextFiles.create(handlerOptions);
+	}
 	if (options.typescript !== false) {
 		const handlerOptions = typeof options.typescript === "object" ? options.typescript : {};
 		config[TypeScript.glob] = TypeScript.create(handlerOptions);

package/lint/handlers/TextFiles.js

@@ -0,0 +1,391 @@
+import { Command } from "../utils/Command.js";
+import { Filter } from "../utils/Filter.js";
+import { Data, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { Git } from "@effected/git";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+
+//#region src/lint/handlers/TextFiles.ts
+/**
+* Why a file is not grep-visible text.
+*
+* @remarks
+* `"nul"` — the file contains a NUL byte, which ripgrep (anywhere) and
+* `git grep -I` (first 8000 bytes) take as the mark of a binary file and
+* silently skip. `"invalid-utf8"` — the bytes are not well-formed UTF-8.
+*
+* @public
+*/
+const TextFileViolationReason = Schema.Literals(["nul", "invalid-utf8"]);
+/**
+* The first occurrence of one {@link TextFileViolationReason} in a byte buffer.
+*
+* @remarks
+* `offset` is the 0-based byte offset of the offending byte (for
+* `"invalid-utf8"`, the first byte of the ill-formed sequence). `line` is
+* 1-based and unambiguous even in invalid input: LF never occurs inside a
+* multi-byte UTF-8 sequence. `column` is the 1-based character column,
+* counting code points on the line before the offset (a leading BOM is not
+* counted); when the line prefix itself holds invalid bytes it is an
+* approximation, and `offset` is the exact position.
+*
+* @public
+*/
+var TextFileViolation = class extends Schema.Class("TextFileViolation")({
+	reason: TextFileViolationReason,
+	offset: Schema.Number,
+	line: Schema.Number,
+	column: Schema.Number
+}) {};
+/**
+* A {@link TextFileViolation} found in a named file.
+*
+* @public
+*/
+var TextFileFinding = class extends Schema.Class("TextFileFinding")({
+	path: Schema.String,
+	reason: TextFileViolationReason,
+	offset: Schema.Number,
+	line: Schema.Number,
+	column: Schema.Number
+}) {
+	/** `path:line:column`, the form editors and terminals turn into a link. */
+	get location() {
+		return `${this.path}:${this.line}:${this.column}`;
+	}
+	/** A one-line explanation with the mechanical fix. */
+	get message() {
+		return this.reason === "nul" ? "contains a NUL byte — write it as the \\0 escape so grep and ripgrep do not skip the file" : `is not valid UTF-8 (byte offset ${this.offset}) — re-encode the file as UTF-8`;
+	}
+};
+/**
+* Base of {@link TextFileStagedReadError}, exported so downstream declaration
+* emit can name it (an unexported `Data.TaggedError` base fails TS4023 in any
+* package whose inferred types carry the error).
+*
+* @internal
+*/
+const TextFileStagedReadErrorBase = Data.TaggedError("TextFileStagedReadError");
+/**
+* A file's staged (index) content could not be read.
+*
+* @remarks
+* Raised by {@link TextFiles.readStaged} when `git cat-file` exits non-zero —
+* typically because the path has no stage-0 index entry (never added, or
+* mid-merge), or the directory is not inside a git repository.
+*
+* @public
+*/
+var TextFileStagedReadError = class extends TextFileStagedReadErrorBase {
+	get message() {
+		const detail = this.stderr.trim();
+		return `cannot read the staged content of ${this.path} (git cat-file exited ${this.exitCode})${detail ? `: ${detail}` : ""}`;
+	}
+};
+/**
+* The 0-based offset of the first byte of the first ill-formed UTF-8
+* sequence, or `-1` when the buffer is well-formed.
+*
+* Follows the Unicode well-formed byte-sequence table (Unicode Standard,
+* Table 3-7), which is exactly what a fatal `TextDecoder("utf-8")` accepts:
+* overlong forms, encoded surrogates, code points past U+10FFFF, stray
+* continuation bytes and truncated sequences are all ill-formed.
+*/
+const firstInvalidUtf8 = (bytes) => {
+	const n = bytes.length;
+	let i = 0;
+	while (i < n) {
+		const lead = bytes[i];
+		if (lead < 128) {
+			i++;
+			continue;
+		}
+		let length;
+		let lo = 128;
+		let hi = 191;
+		if (lead >= 194 && lead <= 223) length = 2;
+		else if (lead === 224) {
+			length = 3;
+			lo = 160;
+		} else if (lead === 237) {
+			length = 3;
+			hi = 159;
+		} else if (lead >= 225 && lead <= 239) length = 3;
+		else if (lead === 240) {
+			length = 4;
+			lo = 144;
+		} else if (lead === 244) {
+			length = 4;
+			hi = 143;
+		} else if (lead >= 241 && lead <= 243) length = 4;
+		else return i;
+		if (i + length > n) return i;
+		const second = bytes[i + 1];
+		if (second < lo || second > hi) return i;
+		for (let k = 2; k < length; k++) {
+			const next = bytes[i + k];
+			if (next < 128 || next > 191) return i;
+		}
+		i += length;
+	}
+	return -1;
+};
+const hasBom = (bytes) => bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191;
+/** Build the violation for `offset`, resolving its line and character column. */
+const locate = (bytes, reason, offset) => {
+	let line = 1;
+	let lineStart = 0;
+	for (let i = 0; i < offset; i++) if (bytes[i] === 10) {
+		line++;
+		lineStart = i + 1;
+	}
+	if (lineStart === 0 && hasBom(bytes) && offset >= 3) lineStart = 3;
+	let column = 1;
+	for (let i = lineStart; i < offset; i++) if ((bytes[i] & 192) !== 128) column++;
+	return TextFileViolation.make({
+		reason,
+		offset,
+		line,
+		column
+	});
+};
+/**
+* Handler for grep-visible text files.
+*
+* Fails a commit when a staged source file contains a NUL byte or is not
+* valid UTF-8 — the two ways a text file becomes invisible to `grep`/`rg`,
+* which then return false negatives instead of an error.
+*
+* @remarks
+* The check is read-only, so its glob may overlap the Biome `--write` key
+* without a staging conflict. The lint-staged handler shells out to
+* `savvy lint text --staged <files>` (reading the index, not the worktree),
+* the same command `savvy lint text` runs with no
+* arguments over every git-tracked file matching {@link TextFiles.glob}. The
+* fix is always mechanical: write `\0` as an escape, never a literal NUL.
+*
+* @example
+* ```typescript
+* import { TextFiles } from '\@savvy-web/silk/lint';
+*
+* export default {
+*   [TextFiles.glob]: TextFiles.create({ exclude: ['vendor/'] }),
+* };
+* ```
+*
+* @public
+*/
+var TextFiles = class TextFiles {
+	/**
+	* File extensions checked: source, config, docs and shell text.
+	*/
+	static extensions = [
+		"ts",
+		"tsx",
+		"mts",
+		"cts",
+		"js",
+		"jsx",
+		"mjs",
+		"cjs",
+		"json",
+		"jsonc",
+		"md",
+		"mdx",
+		"yml",
+		"yaml",
+		"toml",
+		"css",
+		"sh",
+		"bats"
+	];
+	/**
+	* Glob pattern for matching checked files, derived from {@link TextFiles.extensions}.
+	* @defaultValue `'**\/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc,md,mdx,yml,yaml,toml,css,sh,bats}'`
+	*/
+	static glob = `**/*.{${TextFiles.extensions.join(",")}}`;
+	/**
+	* Default patterns to exclude from checking.
+	* @defaultValue `[]`
+	*/
+	static defaultExcludes = [];
+	/**
+	* Pre-configured handler with default options.
+	*/
+	static handler = TextFiles.create();
+	/**
+	* Whether `path` has one of the checked {@link TextFiles.extensions}.
+	*
+	* @param path - A file path
+	* @returns `true` when the file is in scope
+	*/
+	static matches(path) {
+		return TextFiles.extensions.some((ext) => path.endsWith(`.${ext}`));
+	}
+	/**
+	* Classify a file's bytes.
+	*
+	* @remarks
+	* Pure. Returns the first NUL byte and the first ill-formed UTF-8 sequence,
+	* each at most once, ordered by offset; an empty array means the bytes are
+	* grep-visible text. A UTF-8 BOM is valid, and an empty buffer passes.
+	*
+	* @param bytes - The file contents
+	* @returns The violations found, empty when none
+	*/
+	static classify(bytes) {
+		const violations = [];
+		const invalid = firstInvalidUtf8(bytes);
+		if (invalid >= 0) violations.push(locate(bytes, "invalid-utf8", invalid));
+		const nul = bytes.indexOf(0);
+		if (nul >= 0) violations.push(locate(bytes, "nul", nul));
+		return violations.sort((a, b) => a.offset - b.offset);
+	}
+	/**
+	* Read and classify each file, in order.
+	*
+	* @param paths - Files to check
+	* @returns One finding per violation, empty when every file passes
+	*/
+	static checkFiles(paths) {
+		return Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			return (yield* Effect.forEach(paths, (path) => Effect.map(fs.readFile(path), (bytes) => TextFiles.classify(bytes).map((v) => TextFileFinding.make({
+				path,
+				...v
+			}))), { concurrency: 16 })).flat();
+		});
+	}
+	/**
+	* Read a file's staged bytes from the git index, not the working tree.
+	*
+	* @remarks
+	* Runs `git cat-file blob :./<name>` from the file's own directory, so an
+	* absolute path (what lint-staged passes) and a relative one both resolve
+	* against the right repository without computing a repo-relative path.
+	* When that directory is gone from the working tree (a staged file whose
+	* directory was deleted, deletion unstaged), it runs from the nearest
+	* existing ancestor with the path relative to it instead.
+	* Stdout is collected as raw bytes — `\@effected/git`'s `show` decodes to a
+	* string, which would erase exactly the NULs and invalid bytes this check
+	* looks for. Reading the index makes the lint-staged run race-free against
+	* concurrent `--write` tasks on the working tree, and checks exactly what
+	* the commit will record.
+	*
+	* @param path - File path, absolute or relative to the process cwd
+	* @returns The staged blob's bytes
+	*/
+	static readStaged(path) {
+		return Effect.scoped(Effect.gen(function* () {
+			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+			const fs = yield* FileSystem.FileSystem;
+			const pathService = yield* Path.Path;
+			let cwd = pathService.dirname(path);
+			while (!(yield* fs.exists(cwd))) {
+				const parent = pathService.dirname(cwd);
+				if (parent === cwd) break;
+				cwd = parent;
+			}
+			const relative = pathService.relative(cwd, path).split(pathService.sep).join("/");
+			const command = ChildProcess.make("git", [
+				"cat-file",
+				"blob",
+				`:./${relative}`
+			], { cwd });
+			const handle = yield* spawner.spawn(command);
+			const [chunks, stderr, exitCode] = yield* Effect.all([
+				Stream.runCollect(handle.stdout),
+				Stream.mkString(Stream.decodeText(handle.stderr)),
+				handle.exitCode
+			], { concurrency: "unbounded" });
+			if (exitCode !== 0) return yield* new TextFileStagedReadError({
+				path,
+				exitCode,
+				stderr
+			});
+			const out = new Uint8Array(chunks.reduce((n, chunk) => n + chunk.length, 0));
+			let at = 0;
+			for (const chunk of chunks) {
+				out.set(chunk, at);
+				at += chunk.length;
+			}
+			return out;
+		}));
+	}
+	/**
+	* Read each file's STAGED content (see {@link TextFiles.readStaged}) and
+	* classify it, in order.
+	*
+	* @remarks
+	* Every file is checked: a file whose staged content cannot be read is
+	* collected into {@link TextFileStagedCheck.unreadable} rather than
+	* failing the whole check, so it cannot hide findings in the others. Only
+	* a platform failure (git could not be spawned) fails the effect.
+	*
+	* @param paths - Files to check
+	* @returns The findings, and a read error per unreadable file; both empty when every staged blob passes
+	*/
+	static checkStagedFiles(paths) {
+		return Effect.map(Effect.forEach(paths, (path) => TextFiles.readStaged(path).pipe(Effect.map((bytes) => TextFiles.classify(bytes).map((v) => TextFileFinding.make({
+			path,
+			...v
+		}))), Effect.catchTag("TextFileStagedReadError", (error) => Effect.succeed(error))), { concurrency: 8 }), (perFile) => ({
+			findings: perFile.flatMap((outcome) => Array.isArray(outcome) ? outcome : []),
+			unreadable: perFile.filter((outcome) => !Array.isArray(outcome))
+		}));
+	}
+	/**
+	* List the git-tracked files under `cwd` that this check covers.
+	*
+	* @remarks
+	* Reads the index (`git ls-files`), keeping regular files (modes `100644`
+	* and `100755`) — gitlinks and symlinks are not file contents — that match
+	* {@link TextFiles.matches} and are not excluded. For a worktree check the
+	* file must also still exist in the working tree; with `staged: true` it
+	* need not, since a file deleted from the worktree without the deletion
+	* staged is still in the commit and {@link TextFiles.readStaged} reads its
+	* blob from the index. Paths come back joined onto `cwd`, deduplicated
+	* across the stages of an unresolved merge.
+	*
+	* @param cwd - Repository directory to list from
+	* @param options - `exclude` patterns (defaults to {@link TextFiles.defaultExcludes}) and `staged`
+	* @returns The files to check
+	*/
+	static listTracked(cwd, options = {}) {
+		return Effect.gen(function* () {
+			const git = yield* Git;
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const excludes = options.exclude ?? [...TextFiles.defaultExcludes];
+			const entries = yield* git.lsFiles(cwd);
+			const candidates = [...new Set(entries.filter((entry) => entry.mode === "100644" || entry.mode === "100755").map((entry) => entry.path).filter((file) => TextFiles.matches(file)))];
+			const kept = Filter.exclude(candidates, excludes).map((file) => path.join(cwd, file));
+			if (options.staged) return kept;
+			return yield* Effect.filter(kept, (file) => fs.exists(file), { concurrency: 16 });
+		});
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @remarks
+	* Returns a `savvy lint text --staged <files>` command rather than checking
+	* in the handler body, so the check runs with the same code as the CLI.
+	* `--staged` reads each file from the git index: lint-staged runs other
+	* glob keys (Biome `--write`) concurrently against the working tree, and a
+	* worktree read could observe a half-written file. The index only changes
+	* when lint-staged re-stages, after every task has finished.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...TextFiles.defaultExcludes];
+		return (filenames) => {
+			const filtered = Filter.exclude(filenames, excludes);
+			if (filtered.length === 0) return [];
+			return `${Command.findSavvyLint()} text --staged ${Filter.shellEscape(filtered)}`;
+		};
+	}
+};
+
+//#endregion
+export { TextFileFinding, TextFileStagedReadError, TextFileStagedReadErrorBase, TextFileViolation, TextFileViolationReason, TextFiles };

package/lint/index.js

@@ -9,6 +9,7 @@ import { Markdown } from "./handlers/Markdown.js";
 import { PackageJson } from "./handlers/PackageJson.js";
 import { PnpmWorkspace } from "./handlers/PnpmWorkspace.js";
 import { ShellScripts } from "./handlers/ShellScripts.js";
+import { TextFileFinding, TextFileStagedReadError, TextFileStagedReadErrorBase, TextFileViolation, TextFileViolationReason, TextFiles } from "./handlers/TextFiles.js";
 import { TypeScript } from "./handlers/TypeScript.js";
 import { Yaml } from "./handlers/Yaml.js";
 import { createConfig } from "./config/createConfig.js";
@@ -37,6 +38,12 @@ var lint_exports = /* @__PURE__ */ __exportAll({
 	Preset: () => Preset,
 	SavvyLintSectionDef: () => SavvyLintSectionDef,
 	ShellScripts: () => ShellScripts,
+	TextFileFinding: () => TextFileFinding,
+	TextFileStagedReadError: () => TextFileStagedReadError,
+	TextFileStagedReadErrorBase: () => TextFileStagedReadErrorBase,
+	TextFileViolation: () => TextFileViolation,
+	TextFileViolationReason: () => TextFileViolationReason,
+	TextFiles: () => TextFiles,
 	TypeScript: () => TypeScript,
 	Yaml: () => Yaml,
 	createConfig: () => createConfig,
@@ -50,4 +57,4 @@ var lint_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { Biome, Command, DEFAULT_CONFIG_PATH, Filter, HUSKY_HOOK_PATH, Handler, LegacySavvyLintHygieneDef, MARKDOWNLINT_CONFIG, MARKDOWNLINT_CONFIG_PATH, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE, Markdown, POST_CHECKOUT_HOOK_PATH, POST_COMMIT_HOOK_PATH, POST_MERGE_HOOK_PATH, PackageJson, PnpmWorkspace, Preset, SavvyLintSectionDef, ShellScripts, TypeScript, Yaml, createConfig, generateManagedContent, getWorkspacePackagePaths, getWorkspacePackages, getWorkspaceRoot, isWorkspacePackagePath, lint_exports, resetWorkspaceCache, savvyLintBlock };
+export { Biome, Command, DEFAULT_CONFIG_PATH, Filter, HUSKY_HOOK_PATH, Handler, LegacySavvyLintHygieneDef, MARKDOWNLINT_CONFIG, MARKDOWNLINT_CONFIG_PATH, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE, Markdown, POST_CHECKOUT_HOOK_PATH, POST_COMMIT_HOOK_PATH, POST_MERGE_HOOK_PATH, PackageJson, PnpmWorkspace, Preset, SavvyLintSectionDef, ShellScripts, TextFileFinding, TextFileStagedReadError, TextFileStagedReadErrorBase, TextFileViolation, TextFileViolationReason, TextFiles, TypeScript, Yaml, createConfig, generateManagedContent, getWorkspacePackagePaths, getWorkspacePackages, getWorkspaceRoot, isWorkspacePackagePath, lint_exports, resetWorkspaceCache, savvyLintBlock };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "9.2.1",
+	"version": "9.3.0",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
@@ -41,9 +41,9 @@
 		"@effected/glob": "^0.9.0",
 		"@effected/jsonc": "^0.14.0",
 		"@effected/markdown": "^0.14.0",
-		"@effected/package-json": "^0.19.0",
+		"@effected/package-json": "^0.19.1",
 		"@effected/toml": "^0.10.0",
-		"@effected/walker": "^0.13.0",
+		"@effected/walker": "^0.14.0",
 		"@effected/yaml": "^0.18.0",
 		"@manypkg/get-packages": "^3.1.0",
 		"@savvy-web/silk-core": "0.4.8",
@@ -59,7 +59,7 @@
 	},
 	"peerDependencies": {
 		"@effected/commands": "^0.10.0",
-		"@effected/git": "^0.18.0",
+		"@effected/git": "^0.19.0",
 		"@effected/templates": "^0.9.0",
 		"@effected/workspaces": "^0.30.0",
 		"effect": "4.0.0-rc.118"

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.check(Schema.isPattern(/^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/)).annotate({ identifier: "RepoName" });
+const RepoName = Schema.String.check(Schema.isPattern(/^(?!\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$/u)).annotate({ identifier: "RepoName" });
 /**
 * An agent-appended note: a discovered answer stamped with the pin it was written against.
 * @public