@savvy-web/silk-effects 0.1.0 → 0.2.1

package/index.d.ts

@@ -9,12 +9,22 @@
  * @packageDocumentation
  */
 
+import { Command } from '@effect/platform';
+import { CommandExecutor } from '@effect/platform';
 import { Context } from 'effect';
+import { Data } from 'effect';
 import { Effect } from 'effect';
+import { Equal } from 'effect';
 import { FileSystem } from '@effect/platform';
+import { Hash } from 'effect';
 import { Layer } from 'effect';
+import { PackageManagerDetector } from 'workspaces-effect';
+import type { PlatformError } from '@effect/platform/Error';
 import { Schema } from 'effect';
+import type { Stream } from 'effect';
+import { Unify } from 'effect/Unify';
 import { VoidIfEmpty } from 'effect/Types';
+import { WorkspaceRoot } from 'workspaces-effect';
 import { YieldableError } from 'effect/Cause';
 
 /**
@@ -157,6 +167,16 @@ export declare const BiomeSyncResult: Schema.Struct<{
 /** @since 0.1.0 */
 export declare type BiomeSyncResult = typeof BiomeSyncResult.Type;
 
+/**
+ * Build the expected Biome JSON schema URL for a given version.
+ *
+ * @param version - Bare semver string (e.g. `"1.9.3"`).
+ * @returns The canonical `biomejs.dev` schema URL for that version.
+ *
+ * @since 0.1.0
+ */
+export declare function buildSchemaUrl(version: string): string;
+
 /**
  * Standard changesets configuration matching the `@changesets/types` upstream spec.
  *
@@ -250,6 +270,77 @@ declare const ChangesetConfigReader_base: Context.TagClass<ChangesetConfigReader
  */
 export declare const ChangesetConfigReaderLive: Layer.Layer<ChangesetConfigReader, never, FileSystem.FileSystem>;
 
+/** @since 0.2.0 */
+export declare type CheckResult = Data.TaggedEnum<CheckResultDefinition>;
+
+/** @since 0.2.0 */
+export declare const CheckResult: {
+    readonly $is: <Tag extends "Found" | "NotFound">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Found";
+        readonly isUpToDate: boolean;
+        readonly diff: SectionDiff;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "NotFound";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Found" | "NotFound"]: (args: Extract<{
+                readonly _tag: "Found";
+                readonly isUpToDate: boolean;
+                readonly diff: SectionDiff;
+            } | {
+                readonly _tag: "NotFound";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Found" | "NotFound">]: never; }): (value: {
+            readonly _tag: "Found";
+            readonly isUpToDate: boolean;
+            readonly diff: SectionDiff;
+        } | {
+            readonly _tag: "NotFound";
+        }) => Unify<ReturnType<Cases["Found" | "NotFound"]>>;
+        <const Cases extends { readonly [Tag in "Found" | "NotFound"]: (args: Extract<{
+                readonly _tag: "Found";
+                readonly isUpToDate: boolean;
+                readonly diff: SectionDiff;
+            } | {
+                readonly _tag: "NotFound";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "Found";
+            readonly isUpToDate: boolean;
+            readonly diff: SectionDiff;
+        } | {
+            readonly _tag: "NotFound";
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Found" | "NotFound">]: never; }): Unify<ReturnType<Cases["Found" | "NotFound"]>>;
+    };
+    readonly Found: Data.Case.Constructor<{
+        readonly _tag: "Found";
+        readonly isUpToDate: boolean;
+        readonly diff: SectionDiff;
+    }, "_tag">;
+    readonly NotFound: Data.Case.Constructor<{
+        readonly _tag: "NotFound";
+    }, "_tag">;
+};
+
+/**
+ * Result of a check operation.
+ *
+ * @since 0.2.0
+ */
+export declare type CheckResultDefinition = {
+    readonly Found: {
+        readonly isUpToDate: boolean;
+        readonly diff: SectionDiff;
+    };
+    readonly NotFound: {};
+};
+
 /**
  * Comment syntax used to write managed section markers.
  *
@@ -403,178 +494,56 @@ export declare const ConfigSource: Schema.Literal<["lib", "root", "cosmiconfig"]
 export declare type ConfigSource = typeof ConfigSource.Type;
 
 /**
- * Service providing managed section operations for tool-owned regions
- * within user-editable files (e.g. husky hooks).
- *
- * @remarks
- * A managed section is a delimited block in a file bounded by BEGIN/END marker comments.
- * The markers embed the tool name so multiple tools can manage independent sections in
- * the same file. User content outside the markers is always preserved.
- *
- * @example
- * ```typescript
- * const result = await Effect.runPromise(
- *   Effect.gen(function* () {
- *     const section = yield* ManagedSection;
- *     yield* section.write(".husky/pre-commit", "silk", "\nnpx lint-staged\n");
- *     return yield* section.read(".husky/pre-commit", "silk");
- *   }).pipe(
- *     Effect.provide(ManagedSectionLive),
- *     Effect.provide(NodeContext.layer),
- *   )
- * );
- * ```
+ * Strip leading semver range operators from a version string.
  *
- * @since 0.1.0
- */
-export declare class ManagedSection extends ManagedSection_base {
-}
-
-declare const ManagedSection_base: Context.TagClass<ManagedSection, "@savvy-web/silk-effects/ManagedSection", {
-    /**
-     * Read and parse the managed section from a file.
-     *
-     * @param path - Absolute path to the file.
-     * @param toolName - Tool identifier embedded in the section markers.
-     * @param commentStyle - Comment prefix to use (`"#"` or `"//"`, defaults to `"#"`).
-     * @returns An `Effect` that succeeds with a {@link ManagedSectionResult} when markers
-     *   are found, `null` when the file has no markers, or fails with
-     *   {@link ManagedSectionParseError} on I/O errors.
-     *
-     * @since 0.1.0
-     */
-    readonly read: (path: string, toolName: string, commentStyle?: string) => Effect.Effect<ManagedSectionResult | null, ManagedSectionParseError>;
-    /**
-     * Write managed content to a file.
-     *
-     * @remarks
-     * - Replaces the existing managed section when markers are already present.
-     * - Appends a new managed section when the file exists but has no markers.
-     * - Creates the file when it does not exist.
-     *
-     * @param path - Absolute path to the file.
-     * @param toolName - Tool identifier embedded in the section markers.
-     * @param content - Content to place inside the managed section (between markers).
-     * @param commentStyle - Comment prefix to use (`"#"` or `"//"`, defaults to `"#"`).
-     * @returns An `Effect` that succeeds with `void` or fails with {@link ManagedSectionWriteError}.
-     *
-     * @since 0.1.0
-     */
-    readonly write: (path: string, toolName: string, content: string, commentStyle?: string) => Effect.Effect<void, ManagedSectionWriteError>;
-    /**
-     * Read-then-write convenience method that replaces managed content while
-     * preserving surrounding user content.
-     *
-     * @param path - Absolute path to the file.
-     * @param toolName - Tool identifier embedded in the section markers.
-     * @param content - Replacement content for the managed section.
-     * @param commentStyle - Comment prefix to use (`"#"` or `"//"`, defaults to `"#"`).
-     * @returns An `Effect` that succeeds with `void` or fails with {@link ManagedSectionWriteError}.
-     *
-     * @since 0.1.0
-     */
-    readonly update: (path: string, toolName: string, content: string, commentStyle?: string) => Effect.Effect<void, ManagedSectionWriteError>;
-    /**
-     * Return `true` when the file contains both BEGIN and END markers for the given tool.
-     *
-     * @param path - Absolute path to the file.
-     * @param toolName - Tool identifier to search for in the markers.
-     * @param commentStyle - Comment prefix to match (`"#"` or `"//"`, defaults to `"#"`).
-     * @returns An `Effect` that always succeeds with a boolean.
-     *
-     * @since 0.1.0
-     */
-    readonly isManaged: (path: string, toolName: string, commentStyle?: string) => Effect.Effect<boolean>;
-}>;
-
-/**
- * Live implementation of {@link ManagedSection} backed by `@effect/platform` FileSystem.
- *
- * @remarks
- * Requires `FileSystem` from `@effect/platform`. Provide `NodeContext.layer` or
- * `BunContext.layer` to satisfy this dependency.
- *
- * @since 0.1.0
- */
-export declare const ManagedSectionLive: Layer.Layer<ManagedSection, never, FileSystem.FileSystem>;
-
-/**
- * Options controlling how managed sections are identified in a file.
- *
- * @remarks
- * `toolName` is embedded in the BEGIN/END markers so multiple tools can coexist
- * in the same file without collision. `commentStyle` defaults to `"#"`.
+ * @param version - Raw version string that may include `^`, `~`, `>=`, `<`, `=`, or `v` prefixes.
+ * @returns The bare semver string (e.g. `"1.9.3"`).
  *
  * @since 0.1.0
  */
-export declare const ManagedSectionOptions: Schema.Struct<{
-    toolName: typeof Schema.String;
-    commentStyle: Schema.optionalWith<Schema.Literal<["#", "//"]>, {
-        default: () => "#";
-    }>;
-}>;
-
-/** @since 0.1.0 */
-export declare type ManagedSectionOptions = typeof ManagedSectionOptions.Type;
+export declare function extractSemver(version: string): string;
 
 /**
- * Raised when a managed section cannot be parsed from a file.
+ * Service for managing delimited sections in user-editable files.
  *
- * @remarks
- * Returned by {@link ManagedSection.read} when the file exists but its content
- * cannot be read (e.g. a filesystem permission error).
+ * All methods use dual API (data-first and data-last).
+ * Identity-only operations (`read`, `isManaged`) take a {@link SectionDefinition}.
+ * Content operations (`write`, `sync`, `check`) take a {@link SectionBlock}.
  *
- * @since 0.1.0
+ * @since 0.2.0
  */
-export declare class ManagedSectionParseError extends ManagedSectionParseError_base<{
-    readonly path: string;
-    readonly reason: string;
-}> {
-    get message(): string;
+export declare class ManagedSection extends ManagedSection_base {
 }
 
-declare const ManagedSectionParseError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
-    readonly _tag: "ManagedSectionParseError";
-} & Readonly<A>;
-
-/**
- * Parsed result of reading a managed section from a file.
- *
- * @remarks
- * Produced by {@link ManagedSection.read}. The `before` and `after` strings
- * contain the file content surrounding the managed block; `managed` holds the
- * content between the BEGIN and END markers (excluding the markers themselves).
- *
- * @since 0.1.0
- */
-export declare const ManagedSectionResult: Schema.Struct<{
-    before: typeof Schema.String;
-    managed: typeof Schema.String;
-    after: typeof Schema.String;
+declare const ManagedSection_base: Context.TagClass<ManagedSection, "@savvy-web/silk-effects/ManagedSection", {
+    readonly read: {
+        (definition: SectionDefinition): (path: string) => Effect.Effect<SectionBlock | null, SectionParseError>;
+        (path: string, definition: SectionDefinition): Effect.Effect<SectionBlock | null, SectionParseError>;
+    };
+    readonly isManaged: {
+        (definition: SectionDefinition): (path: string) => Effect.Effect<boolean>;
+        (path: string, definition: SectionDefinition): Effect.Effect<boolean>;
+    };
+    readonly write: {
+        (block: SectionBlock): (path: string) => Effect.Effect<void, SectionWriteError>;
+        (path: string, block: SectionBlock): Effect.Effect<void, SectionWriteError>;
+    };
+    readonly sync: {
+        (block: SectionBlock): (path: string) => Effect.Effect<SyncResult, SectionWriteError>;
+        (path: string, block: SectionBlock): Effect.Effect<SyncResult, SectionWriteError>;
+    };
+    readonly check: {
+        (block: SectionBlock): (path: string) => Effect.Effect<CheckResult, SectionParseError>;
+        (path: string, block: SectionBlock): Effect.Effect<CheckResult, SectionParseError>;
+    };
 }>;
 
-/** @since 0.1.0 */
-export declare type ManagedSectionResult = typeof ManagedSectionResult.Type;
-
 /**
- * Raised when a managed section cannot be written to a file.
- *
- * @remarks
- * Returned by {@link ManagedSection.write} and {@link ManagedSection.update} when
- * the file cannot be read for content replacement or when the write itself fails.
+ * Live implementation of {@link ManagedSection} backed by `@effect/platform` FileSystem.
  *
- * @since 0.1.0
+ * @since 0.2.0
  */
-export declare class ManagedSectionWriteError extends ManagedSectionWriteError_base<{
-    readonly path: string;
-    readonly reason: string;
-}> {
-    get message(): string;
-}
-
-declare const ManagedSectionWriteError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
-    readonly _tag: "ManagedSectionWriteError";
-} & Readonly<A>;
+export declare const ManagedSectionLive: Layer.Layer<ManagedSection, never, FileSystem.FileSystem>;
 
 /**
  * Raised when the `publishConfig` field in a `package.json` is present but invalid.
@@ -620,7 +589,7 @@ export declare type PublishProtocol = typeof PublishProtocol.Type;
  *
  * @since 0.1.0
  */
-export declare const PublishTarget: Schema.Union<[Schema.Literal<["npm", "github", "jsr"]>, Schema.filter<typeof Schema.String>, Schema.Struct<{
+declare const PublishTarget: Schema.Union<[Schema.Literal<["npm", "github", "jsr"]>, Schema.filter<typeof Schema.String>, Schema.Struct<{
     protocol: Schema.optionalWith<Schema.Literal<["npm", "jsr"]>, {
         default: () => "npm";
     }>;
@@ -632,7 +601,9 @@ export declare const PublishTarget: Schema.Union<[Schema.Literal<["npm", "github
 }>]>;
 
 /** @since 0.1.0 */
-export declare type PublishTarget = typeof PublishTarget.Type;
+declare type PublishTarget = typeof PublishTarget.Type;
+export { PublishTarget }
+export { PublishTarget as PublishTargetSchema }
 
 /**
  * Full publish-target configuration expressed as a structured object.
@@ -667,10 +638,96 @@ export declare type PublishTargetObject = typeof PublishTargetObject.Type;
  *
  * @since 0.1.0
  */
-export declare const PublishTargetShorthand: Schema.Literal<["npm", "github", "jsr"]>;
+declare const PublishTargetShorthand: Schema.Literal<["npm", "github", "jsr"]>;
 
 /** @since 0.1.0 */
-export declare type PublishTargetShorthand = typeof PublishTargetShorthand.Type;
+declare type PublishTargetShorthand = typeof PublishTargetShorthand.Type;
+export { PublishTargetShorthand }
+export { PublishTargetShorthand as PublishTargetShorthandSchema }
+
+/** @since 0.2.0 */
+export declare type ResolutionPolicy = Data.TaggedEnum<ResolutionPolicyDefinition>;
+
+/** @since 0.2.0 */
+export declare const ResolutionPolicy: {
+    readonly $is: <Tag extends "PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "PreferGlobal";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "PreferLocal";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Report";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "RequireMatch";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch"]: (args: Extract<{
+                readonly _tag: "PreferGlobal";
+            } | {
+                readonly _tag: "PreferLocal";
+            } | {
+                readonly _tag: "Report";
+            } | {
+                readonly _tag: "RequireMatch";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch">]: never; }): (value: {
+            readonly _tag: "PreferGlobal";
+        } | {
+            readonly _tag: "PreferLocal";
+        } | {
+            readonly _tag: "Report";
+        } | {
+            readonly _tag: "RequireMatch";
+        }) => Unify<ReturnType<Cases["PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch"]>>;
+        <const Cases extends { readonly [Tag in "PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch"]: (args: Extract<{
+                readonly _tag: "PreferGlobal";
+            } | {
+                readonly _tag: "PreferLocal";
+            } | {
+                readonly _tag: "Report";
+            } | {
+                readonly _tag: "RequireMatch";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "PreferGlobal";
+        } | {
+            readonly _tag: "PreferLocal";
+        } | {
+            readonly _tag: "Report";
+        } | {
+            readonly _tag: "RequireMatch";
+        }, cases: Cases & { [K in Exclude<keyof Cases, "PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch">]: never; }): Unify<ReturnType<Cases["PreferGlobal" | "PreferLocal" | "Report" | "RequireMatch"]>>;
+    };
+    readonly PreferGlobal: Data.Case.Constructor<{
+        readonly _tag: "PreferGlobal";
+    }, "_tag">;
+    readonly PreferLocal: Data.Case.Constructor<{
+        readonly _tag: "PreferLocal";
+    }, "_tag">;
+    readonly Report: Data.Case.Constructor<{
+        readonly _tag: "Report";
+    }, "_tag">;
+    readonly RequireMatch: Data.Case.Constructor<{
+        readonly _tag: "RequireMatch";
+    }, "_tag">;
+};
+
+/** What to do when both global and local versions differ. @since 0.2.0 */
+export declare type ResolutionPolicyDefinition = {
+    readonly Report: {};
+    readonly PreferLocal: {};
+    readonly PreferGlobal: {};
+    readonly RequireMatch: {};
+};
 
 /**
  * Fully resolved publish target with all fields populated and defaults applied.
@@ -682,7 +739,7 @@ export declare type PublishTargetShorthand = typeof PublishTargetShorthand.Type;
  *
  * @since 0.1.0
  */
-export declare const ResolvedTarget: Schema.Struct<{
+declare const ResolvedTarget: Schema.Struct<{
     protocol: Schema.Literal<["npm", "jsr"]>;
     registry: Schema.NullOr<typeof Schema.String>;
     directory: typeof Schema.String;
@@ -694,7 +751,268 @@ export declare const ResolvedTarget: Schema.Struct<{
 }>;
 
 /** @since 0.1.0 */
-export declare type ResolvedTarget = typeof ResolvedTarget.Type;
+declare type ResolvedTarget = typeof ResolvedTarget.Type;
+export { ResolvedTarget }
+export { ResolvedTarget as ResolvedTargetSchema }
+
+/**
+ * Result of resolving a {@link ToolDefinition}.
+ *
+ * Provides {@link exec} and {@link dlx} to build commands for the resolved tool.
+ *
+ * @since 0.2.0
+ */
+export declare class ResolvedTool extends ResolvedTool_base {
+    get isGlobal(): boolean;
+    get isLocal(): boolean;
+    get hasVersionMismatch(): boolean;
+    exec(...args: string[]): ToolCommand;
+    dlx(...args: string[]): ToolCommand;
+    [Equal.symbol](that: Equal.Equal): boolean;
+    [Hash.symbol](): number;
+}
+
+declare const ResolvedTool_base: Schema.TaggedClass<ResolvedTool, "ResolvedTool", {
+    readonly _tag: Schema.tag<"ResolvedTool">;
+} & {
+    name: typeof Schema.String;
+    source: Schema.Literal<["global", "local"]>;
+    version: Schema.OptionFromSelf<typeof Schema.String>;
+    globalVersion: Schema.OptionFromSelf<typeof Schema.String>;
+    localVersion: Schema.OptionFromSelf<typeof Schema.String>;
+    packageManager: Schema.Literal<["npm", "pnpm", "yarn", "bun"]>;
+    mismatch: typeof Schema.Boolean;
+}>;
+
+/**
+ * The content between managed section markers.
+ *
+ * {@link Equal} compares normalized content only (trimmed, whitespace-collapsed).
+ * Use {@link SectionBlock.diff | diff} to compute line-level differences.
+ *
+ * @since 0.2.0
+ */
+export declare class SectionBlock extends SectionBlock_base {
+    static diff: {
+        (that: SectionBlock): (self: SectionBlock) => SectionDiff;
+        (self: SectionBlock, that: SectionBlock): SectionDiff;
+    };
+    static prepend: {
+        (lines: string): (self: SectionBlock) => SectionBlock;
+        (self: SectionBlock, lines: string): SectionBlock;
+    };
+    static append: {
+        (lines: string): (self: SectionBlock) => SectionBlock;
+        (self: SectionBlock, lines: string): SectionBlock;
+    };
+    get text(): string;
+    get normalized(): string;
+    get rendered(): string;
+    prepend(lines: string): SectionBlock;
+    append(lines: string): SectionBlock;
+    diff(that: SectionBlock): SectionDiff;
+    [Equal.symbol](that: Equal.Equal): boolean;
+    [Hash.symbol](): number;
+}
+
+declare const SectionBlock_base: Schema.TaggedClass<SectionBlock, "SectionBlock", {
+    readonly _tag: Schema.tag<"SectionBlock">;
+} & {
+    toolName: typeof Schema.String;
+    commentStyle: Schema.Literal<["#", "//"]>;
+    content: typeof Schema.String;
+}>;
+
+/**
+ * Identity envelope for a managed section type.
+ *
+ * {@link Equal} compares on `toolName` + `commentStyle`.
+ * Use {@link SectionDefinition.block | block()} to create a {@link SectionBlock},
+ * or {@link SectionDefinition.generate | generate()} for a typed factory.
+ *
+ * @since 0.2.0
+ */
+export declare class SectionDefinition extends SectionDefinition_base {
+    private _validate?;
+    static generate: {
+        <C>(fn: (config: C) => string): (self: SectionDefinition) => (config: C) => SectionBlock;
+        <C>(self: SectionDefinition, fn: (config: C) => string): (config: C) => SectionBlock;
+    };
+    static generateEffect: {
+        <C, E, R>(fn: (config: C) => Effect.Effect<string, E, R>): (self: SectionDefinition) => (config: C) => Effect.Effect<SectionBlock, E | SectionValidationError, R>;
+        <C, E, R>(self: SectionDefinition, fn: (config: C) => Effect.Effect<string, E, R>): (config: C) => Effect.Effect<SectionBlock, E | SectionValidationError, R>;
+    };
+    static withValidation: {
+        (fn: (block: SectionBlock) => boolean): (self: SectionDefinition) => SectionDefinition;
+        (self: SectionDefinition, fn: (block: SectionBlock) => boolean): SectionDefinition;
+    };
+    static diff: {
+        (that: SectionDefinition): (self: SectionDefinition) => SectionDiff;
+        (self: SectionDefinition, that: SectionDefinition): SectionDiff;
+    };
+    block(content: string): SectionBlock;
+    generate<C>(fn: (config: C) => string): (config: C) => SectionBlock;
+    generateEffect<C, E, R>(fn: (config: C) => Effect.Effect<string, E, R>): (config: C) => Effect.Effect<SectionBlock, E | SectionValidationError, R>;
+    diff(that: SectionDefinition): SectionDiff;
+    get beginMarker(): string;
+    get endMarker(): string;
+    [Equal.symbol](that: Equal.Equal): boolean;
+    [Hash.symbol](): number;
+}
+
+declare const SectionDefinition_base: Schema.TaggedClass<SectionDefinition, "SectionDefinition", {
+    readonly _tag: Schema.tag<"SectionDefinition">;
+} & {
+    toolName: typeof Schema.String;
+    commentStyle: Schema.optionalWith<Schema.Literal<["#", "//"]>, {
+        default: () => "#";
+    }>;
+}>;
+
+/** @since 0.2.0 */
+export declare type SectionDiff = Data.TaggedEnum<SectionDiffDefinition>;
+
+/** @since 0.2.0 */
+export declare const SectionDiff: {
+    readonly $is: <Tag extends "Changed" | "Unchanged">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Changed";
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Unchanged";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Changed" | "Unchanged"]: (args: Extract<{
+                readonly _tag: "Changed";
+                readonly added: ReadonlyArray<string>;
+                readonly removed: ReadonlyArray<string>;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "Unchanged";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Changed" | "Unchanged">]: never; }): (value: {
+            readonly _tag: "Changed";
+            readonly added: ReadonlyArray<string>;
+            readonly removed: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Unchanged";
+        }) => Unify<ReturnType<Cases["Changed" | "Unchanged"]>>;
+        <const Cases extends { readonly [Tag in "Changed" | "Unchanged"]: (args: Extract<{
+                readonly _tag: "Changed";
+                readonly added: ReadonlyArray<string>;
+                readonly removed: ReadonlyArray<string>;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "Unchanged";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "Changed";
+            readonly added: ReadonlyArray<string>;
+            readonly removed: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Unchanged";
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Changed" | "Unchanged">]: never; }): Unify<ReturnType<Cases["Changed" | "Unchanged"]>>;
+    };
+    readonly Changed: Data.Case.Constructor<{
+        readonly _tag: "Changed";
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+    }, "_tag">;
+    readonly Unchanged: Data.Case.Constructor<{
+        readonly _tag: "Unchanged";
+    }, "_tag">;
+};
+
+/**
+ * Result of comparing two section contents.
+ *
+ * @since 0.2.0
+ */
+export declare type SectionDiffDefinition = {
+    readonly Unchanged: {};
+    readonly Changed: {
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+    };
+};
+
+/**
+ * Raised when a managed section cannot be parsed from a file.
+ *
+ * @since 0.2.0
+ */
+export declare class SectionParseError extends SectionParseError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const SectionParseError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "SectionParseError";
+} & Readonly<A>;
+
+/**
+ * Raised when a {@link SectionBlock} fails validation at creation time.
+ *
+ * @since 0.2.0
+ */
+export declare class SectionValidationError extends SectionValidationError_base<{
+    readonly toolName: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const SectionValidationError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "SectionValidationError";
+} & Readonly<A>;
+
+/**
+ * Raised when a managed section cannot be written to a file.
+ *
+ * @since 0.2.0
+ */
+export declare class SectionWriteError extends SectionWriteError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const SectionWriteError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "SectionWriteError";
+} & Readonly<A>;
+
+/**
+ * Convenience section definition for shell hooks.
+ *
+ * `commentStyle` is always `"#"` — only `toolName` is required.
+ *
+ * @since 0.2.0
+ */
+export declare class ShellSectionDefinition extends ShellSectionDefinition_base {
+    get commentStyle(): CommentStyle;
+    block(content: string): SectionBlock;
+    generate<C>(fn: (config: C) => string): (config: C) => SectionBlock;
+    generateEffect<C, E, R>(fn: (config: C) => Effect.Effect<string, E, R>): (config: C) => Effect.Effect<SectionBlock, E, R>;
+    get beginMarker(): string;
+    get endMarker(): string;
+}
+
+declare const ShellSectionDefinition_base: Schema.TaggedClass<ShellSectionDefinition, "ShellSectionDefinition", {
+    readonly _tag: Schema.tag<"ShellSectionDefinition">;
+} & {
+    toolName: typeof Schema.String;
+}>;
 
 /**
  * Extended changeset config for repos using the `@savvy-web/changesets` changelog adapter.
@@ -776,6 +1094,170 @@ declare const SilkPublishabilityPlugin_base: Context.TagClass<SilkPublishability
  */
 export declare const SilkPublishabilityPluginLive: Layer.Layer<SilkPublishabilityPlugin, never, TargetResolver>;
 
+/** @since 0.2.0 */
+export declare type SourceRequirement = Data.TaggedEnum<SourceRequirementDefinition>;
+
+/** @since 0.2.0 */
+export declare const SourceRequirement: {
+    readonly $is: <Tag extends "Any" | "Both" | "OnlyGlobal" | "OnlyLocal">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Any";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Both";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "OnlyGlobal";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "OnlyLocal";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Any" | "Both" | "OnlyGlobal" | "OnlyLocal"]: (args: Extract<{
+                readonly _tag: "Any";
+            } | {
+                readonly _tag: "Both";
+            } | {
+                readonly _tag: "OnlyGlobal";
+            } | {
+                readonly _tag: "OnlyLocal";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Any" | "Both" | "OnlyGlobal" | "OnlyLocal">]: never; }): (value: {
+            readonly _tag: "Any";
+        } | {
+            readonly _tag: "Both";
+        } | {
+            readonly _tag: "OnlyGlobal";
+        } | {
+            readonly _tag: "OnlyLocal";
+        }) => Unify<ReturnType<Cases["Any" | "Both" | "OnlyGlobal" | "OnlyLocal"]>>;
+        <const Cases extends { readonly [Tag in "Any" | "Both" | "OnlyGlobal" | "OnlyLocal"]: (args: Extract<{
+                readonly _tag: "Any";
+            } | {
+                readonly _tag: "Both";
+            } | {
+                readonly _tag: "OnlyGlobal";
+            } | {
+                readonly _tag: "OnlyLocal";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "Any";
+        } | {
+            readonly _tag: "Both";
+        } | {
+            readonly _tag: "OnlyGlobal";
+        } | {
+            readonly _tag: "OnlyLocal";
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Any" | "Both" | "OnlyGlobal" | "OnlyLocal">]: never; }): Unify<ReturnType<Cases["Any" | "Both" | "OnlyGlobal" | "OnlyLocal"]>>;
+    };
+    readonly Any: Data.Case.Constructor<{
+        readonly _tag: "Any";
+    }, "_tag">;
+    readonly Both: Data.Case.Constructor<{
+        readonly _tag: "Both";
+    }, "_tag">;
+    readonly OnlyGlobal: Data.Case.Constructor<{
+        readonly _tag: "OnlyGlobal";
+    }, "_tag">;
+    readonly OnlyLocal: Data.Case.Constructor<{
+        readonly _tag: "OnlyLocal";
+    }, "_tag">;
+};
+
+/** Where the tool must be found. @since 0.2.0 */
+export declare type SourceRequirementDefinition = {
+    readonly Any: {};
+    readonly OnlyLocal: {};
+    readonly OnlyGlobal: {};
+    readonly Both: {};
+};
+
+/** @since 0.2.0 */
+export declare type SyncResult = Data.TaggedEnum<SyncResultDefinition>;
+
+/** @since 0.2.0 */
+export declare const SyncResult: {
+    readonly $is: <Tag extends "Created" | "Unchanged" | "Updated">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Created";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Unchanged";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Updated";
+        readonly diff: SectionDiff;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Created" | "Unchanged" | "Updated"]: (args: Extract<{
+                readonly _tag: "Created";
+            } | {
+                readonly _tag: "Unchanged";
+            } | {
+                readonly _tag: "Updated";
+                readonly diff: SectionDiff;
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Created" | "Unchanged" | "Updated">]: never; }): (value: {
+            readonly _tag: "Created";
+        } | {
+            readonly _tag: "Unchanged";
+        } | {
+            readonly _tag: "Updated";
+            readonly diff: SectionDiff;
+        }) => Unify<ReturnType<Cases["Created" | "Unchanged" | "Updated"]>>;
+        <const Cases extends { readonly [Tag in "Created" | "Unchanged" | "Updated"]: (args: Extract<{
+                readonly _tag: "Created";
+            } | {
+                readonly _tag: "Unchanged";
+            } | {
+                readonly _tag: "Updated";
+                readonly diff: SectionDiff;
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "Created";
+        } | {
+            readonly _tag: "Unchanged";
+        } | {
+            readonly _tag: "Updated";
+            readonly diff: SectionDiff;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Created" | "Unchanged" | "Updated">]: never; }): Unify<ReturnType<Cases["Created" | "Unchanged" | "Updated"]>>;
+    };
+    readonly Created: Data.Case.Constructor<{
+        readonly _tag: "Created";
+    }, "_tag">;
+    readonly Unchanged: Data.Case.Constructor<{
+        readonly _tag: "Unchanged";
+    }, "_tag">;
+    readonly Updated: Data.Case.Constructor<{
+        readonly _tag: "Updated";
+        readonly diff: SectionDiff;
+    }, "_tag">;
+};
+
+/**
+ * Result of a sync operation.
+ *
+ * @since 0.2.0
+ */
+export declare type SyncResultDefinition = {
+    readonly Created: {};
+    readonly Updated: {
+        readonly diff: SectionDiff;
+    };
+    readonly Unchanged: {};
+};
+
 /**
  * Raised when a git tag string cannot be formatted for the given package name and version.
  *
@@ -938,6 +1420,264 @@ declare const TargetResolver_base: Context.TagClass<TargetResolver, "@savvy-web/
  */
 export declare const TargetResolverLive: Layer.Layer<TargetResolver, never, never>;
 
+/**
+ * Wraps `@effect/platform` {@link Command.Command} with instance method ergonomics.
+ *
+ * Use `yield* cmd.string()` instead of `yield* Command.string(cmd)`.
+ *
+ * @since 0.2.0
+ */
+export declare class ToolCommand {
+    readonly command: Command.Command;
+    constructor(command: Command.Command);
+    string(encoding?: string): Effect.Effect<string, PlatformError, CommandExecutor.CommandExecutor>;
+    exitCode(): Effect.Effect<number, PlatformError, CommandExecutor.CommandExecutor>;
+    lines(encoding?: string): Effect.Effect<Array<string>, PlatformError, CommandExecutor.CommandExecutor>;
+    stream(): Stream.Stream<Uint8Array, PlatformError, CommandExecutor.CommandExecutor>;
+    env(environment: Record<string, string | undefined>): ToolCommand;
+    workingDirectory(cwd: string): ToolCommand;
+    stdin(input: string): ToolCommand;
+}
+
+/**
+ * Declares a CLI tool's identity and resolution constraints.
+ *
+ * {@link Equal} compares on `name` only (identity).
+ *
+ * @since 0.2.0
+ */
+export declare class ToolDefinition implements Equal.Equal {
+    readonly _tag: "ToolDefinition";
+    readonly name: string;
+    readonly versionExtractor: VersionExtractor;
+    readonly policy: ResolutionPolicy;
+    readonly source: SourceRequirement;
+    private constructor();
+    static make(options: {
+        readonly name: string;
+        readonly versionExtractor?: VersionExtractor;
+        readonly policy?: ResolutionPolicy;
+        readonly source?: SourceRequirement;
+    }): ToolDefinition;
+    [Equal.symbol](that: Equal.Equal): boolean;
+    [Hash.symbol](): number;
+}
+
+/**
+ * Service that resolves CLI tools — locating them globally (PATH) or locally
+ * (via package manager), extracting versions, enforcing source and version
+ * constraints, and caching results.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const td = yield* ToolDiscovery;
+ *     return yield* td.resolve(
+ *       ToolDefinition.make({ name: "biome" })
+ *     );
+ *   }).pipe(
+ *     Effect.provide(ToolDiscoveryLive),
+ *     Effect.provide(NodeContext.layer),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.2.0
+ */
+export declare class ToolDiscovery extends ToolDiscovery_base {
+}
+
+declare const ToolDiscovery_base: Context.TagClass<ToolDiscovery, "@savvy-web/silk-effects/ToolDiscovery", {
+    /**
+     * Resolve a tool definition to a {@link ResolvedTool}, enforcing source
+     * requirements and resolution policies. Results are cached by tool name.
+     *
+     * @since 0.2.0
+     */
+    readonly resolve: (definition: ToolDefinition) => Effect.Effect<ResolvedTool, ToolResolutionError>;
+    /**
+     * Like {@link resolve} but maps failures to {@link ToolNotFoundError}.
+     * Accepts an optional custom error message.
+     *
+     * @since 0.2.0
+     */
+    readonly require: {
+        (definition: ToolDefinition): Effect.Effect<ResolvedTool, ToolNotFoundError>;
+        (definition: ToolDefinition, message: string): Effect.Effect<ResolvedTool, ToolNotFoundError>;
+    };
+    /**
+     * Quick availability check — returns `true` if the tool can be found
+     * either globally or locally. Does not cache.
+     *
+     * @since 0.2.0
+     */
+    readonly isAvailable: (definition: ToolDefinition) => Effect.Effect<boolean>;
+    /**
+     * Clear the internal resolution cache so subsequent calls re-run discovery.
+     *
+     * @since 0.2.0
+     */
+    readonly clearCache: Effect.Effect<void>;
+}>;
+
+/**
+ * Live implementation of {@link ToolDiscovery}.
+ *
+ * @remarks
+ * Requires `CommandExecutor` from `@effect/platform`, `PackageManagerDetector`
+ * and `WorkspaceRoot` from `workspaces-effect`.
+ *
+ * @since 0.2.0
+ */
+export declare const ToolDiscoveryLive: Layer.Layer<ToolDiscovery, never, CommandExecutor.CommandExecutor | PackageManagerDetector | WorkspaceRoot>;
+
+export declare class ToolNotFoundError extends ToolNotFoundError_base<{
+    readonly name: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const ToolNotFoundError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "ToolNotFoundError";
+} & Readonly<A>;
+
+export declare class ToolResolutionError extends ToolResolutionError_base<{
+    readonly name: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const ToolResolutionError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "ToolResolutionError";
+} & Readonly<A>;
+
+/** Where a tool was resolved from. @since 0.2.0 */
+export declare const ToolSource: Schema.Literal<["global", "local"]>;
+
+/** @since 0.2.0 */
+export declare type ToolSource = typeof ToolSource.Type;
+
+export declare class ToolVersionMismatchError extends ToolVersionMismatchError_base<{
+    readonly name: string;
+    readonly globalVersion: string;
+    readonly localVersion: string;
+}> {
+    get message(): string;
+}
+
+declare const ToolVersionMismatchError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<    { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "ToolVersionMismatchError";
+} & Readonly<A>;
+
+/** @since 0.2.0 */
+export declare type VersionExtractor = Data.TaggedEnum<VersionExtractorDefinition>;
+
+/** @since 0.2.0 */
+export declare const VersionExtractor: {
+    readonly $is: <Tag extends "Flag" | "Json" | "None">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Flag";
+        readonly flag: string;
+        readonly parse?: ((output: string) => string) | undefined;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Json";
+        readonly flag: string;
+        readonly path: string;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "None";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends { readonly [Tag in "Flag" | "Json" | "None"]: (args: Extract<{
+                readonly _tag: "Flag";
+                readonly flag: string;
+                readonly parse?: ((output: string) => string) | undefined;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "Json";
+                readonly flag: string;
+                readonly path: string;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "None";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(cases: Cases & { [K in Exclude<keyof Cases, "Flag" | "Json" | "None">]: never; }): (value: {
+            readonly _tag: "Flag";
+            readonly flag: string;
+            readonly parse?: ((output: string) => string) | undefined;
+        } | {
+            readonly _tag: "Json";
+            readonly flag: string;
+            readonly path: string;
+        } | {
+            readonly _tag: "None";
+        }) => Unify<ReturnType<Cases["Flag" | "Json" | "None"]>>;
+        <const Cases extends { readonly [Tag in "Flag" | "Json" | "None"]: (args: Extract<{
+                readonly _tag: "Flag";
+                readonly flag: string;
+                readonly parse?: ((output: string) => string) | undefined;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "Json";
+                readonly flag: string;
+                readonly path: string;
+            }, {
+                readonly _tag: Tag;
+            }> | Extract<{
+                readonly _tag: "None";
+            }, {
+                readonly _tag: Tag;
+            }>) => any; }>(value: {
+            readonly _tag: "Flag";
+            readonly flag: string;
+            readonly parse?: ((output: string) => string) | undefined;
+        } | {
+            readonly _tag: "Json";
+            readonly flag: string;
+            readonly path: string;
+        } | {
+            readonly _tag: "None";
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Flag" | "Json" | "None">]: never; }): Unify<ReturnType<Cases["Flag" | "Json" | "None"]>>;
+    };
+    readonly Flag: Data.Case.Constructor<{
+        readonly _tag: "Flag";
+        readonly flag: string;
+        readonly parse?: ((output: string) => string) | undefined;
+    }, "_tag">;
+    readonly Json: Data.Case.Constructor<{
+        readonly _tag: "Json";
+        readonly flag: string;
+        readonly path: string;
+    }, "_tag">;
+    readonly None: Data.Case.Constructor<{
+        readonly _tag: "None";
+    }, "_tag">;
+};
+
+/** How to extract a version string from a CLI tool. @since 0.2.0 */
+export declare type VersionExtractorDefinition = {
+    readonly Flag: {
+        readonly flag: string;
+        readonly parse?: ((output: string) => string) | undefined;
+    };
+    readonly Json: {
+        readonly flag: string;
+        readonly path: string;
+    };
+    readonly None: {};
+};
+
 /**
  * Raised when the versioning strategy cannot be determined from the workspace state.
  *