@savvy-web/silk-effects 0.1.0

package/index.d.ts

@@ -0,0 +1,1045 @@
+/**
+ * `@savvy-web/silk-effects` — shared Effect library for Silk Suite conventions.
+ *
+ * @remarks
+ * Platform-agnostic Effect services for publishability detection, versioning strategy,
+ * tag strategy, managed sections, config discovery, and Biome schema synchronization.
+ * Consumers provide their platform layer (NodeContext, BunContext, etc.).
+ *
+ * @packageDocumentation
+ */
+
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { FileSystem } from '@effect/platform';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import { VoidIfEmpty } from 'effect/Types';
+import { YieldableError } from 'effect/Cause';
+
+/**
+ * Authentication strategy used to obtain publish credentials.
+ *
+ * @remarks
+ * `"oidc"` relies on GitHub Actions OIDC provenance tokens (no explicit secret needed).
+ * `"token"` reads a long-lived token from an environment variable.
+ *
+ * @since 0.1.0
+ */
+export declare const AuthStrategy: Schema.Literal<["oidc", "token"]>;
+
+/** @since 0.1.0 */
+export declare type AuthStrategy = typeof AuthStrategy.Type;
+
+/**
+ * Service that keeps the `$schema` URL in Biome config files in sync with a target version.
+ *
+ * @remarks
+ * Locates `biome.json` and `biome.jsonc` files in the working directory, then compares
+ * each file's `$schema` field against the expected `biomejs.dev` URL for the given version.
+ * `sync` writes updates in-place; `check` returns the same result without modifying files.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const syncer = yield* BiomeSchemaSync;
+ *     return yield* syncer.sync("^1.9.3");
+ *   }).pipe(
+ *     Effect.provide(BiomeSchemaSyncLive),
+ *     Effect.provide(NodeContext.layer),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class BiomeSchemaSync extends BiomeSchemaSync_base {
+}
+
+declare const BiomeSchemaSync_base: Context.TagClass<BiomeSchemaSync, "@savvy-web/silk-effects/BiomeSchemaSync", {
+    /**
+     * Update the `$schema` URL in all located Biome config files to match `version`.
+     *
+     * @param version - Target Biome version (range operators are stripped automatically).
+     * @param options - Optional `cwd` and `gitignore` overrides.
+     * @returns An `Effect` that succeeds with a {@link BiomeSyncResult} or fails with {@link BiomeSyncError}.
+     *
+     * @since 0.1.0
+     */
+    readonly sync: (version: string, options?: {
+        cwd?: string;
+        gitignore?: boolean;
+    }) => Effect.Effect<BiomeSyncResult, BiomeSyncError>;
+    /**
+     * Check whether the `$schema` URL in Biome config files is current, without writing any changes.
+     *
+     * @param version - Target Biome version (range operators are stripped automatically).
+     * @param options - Optional `cwd` and `gitignore` overrides.
+     * @returns An `Effect` that succeeds with a {@link BiomeSyncResult} or fails with {@link BiomeSyncError}.
+     *   Files that would be updated appear in `updated`; no disk writes occur.
+     *
+     * @since 0.1.0
+     */
+    readonly check: (version: string, options?: {
+        cwd?: string;
+        gitignore?: boolean;
+    }) => Effect.Effect<BiomeSyncResult, BiomeSyncError>;
+}>;
+
+/**
+ * Live implementation of {@link BiomeSchemaSync}.
+ *
+ * @remarks
+ * Requires `FileSystem` from `@effect/platform`. Provide `NodeContext.layer` or
+ * `BunContext.layer` to satisfy this dependency.
+ *
+ * @since 0.1.0
+ */
+export declare const BiomeSchemaSyncLive: Layer.Layer<BiomeSchemaSync, never, FileSystem.FileSystem>;
+
+/**
+ * Raised when a Biome config file cannot be read or its `$schema` URL cannot be updated.
+ *
+ * @remarks
+ * Returned by {@link BiomeSchemaSync.sync} and {@link BiomeSchemaSync.check} when
+ * a `biome.json` or `biome.jsonc` file exists but cannot be read, contains invalid JSON,
+ * or cannot be written back to disk.
+ *
+ * @since 0.1.0
+ */
+export declare class BiomeSyncError extends BiomeSyncError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const BiomeSyncError_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: "BiomeSyncError";
+} & Readonly<A>;
+
+/**
+ * Options for {@link BiomeSchemaSync} operations.
+ *
+ * @remarks
+ * `cwd` overrides the working directory used to locate `biome.json` / `biome.jsonc`.
+ * `gitignore` is reserved for future use to skip gitignored config files (defaults to `true`).
+ *
+ * @since 0.1.0
+ */
+export declare const BiomeSyncOptions: Schema.Struct<{
+    cwd: Schema.optional<typeof Schema.String>;
+    gitignore: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => true;
+    }>;
+}>;
+
+/** @since 0.1.0 */
+export declare type BiomeSyncOptions = typeof BiomeSyncOptions.Type;
+
+/**
+ * Result of a Biome schema URL sync or check operation.
+ *
+ * @remarks
+ * - `updated` — paths of config files whose `$schema` URL was changed (or would be changed on `check`).
+ * - `skipped` — paths of config files with no `$schema` field or a non-biomejs.dev URL.
+ * - `current` — paths of config files already pointing to the expected schema URL.
+ *
+ * @since 0.1.0
+ */
+export declare const BiomeSyncResult: Schema.Struct<{
+    updated: Schema.Array$<typeof Schema.String>;
+    skipped: Schema.Array$<typeof Schema.String>;
+    current: Schema.Array$<typeof Schema.String>;
+}>;
+
+/** @since 0.1.0 */
+export declare type BiomeSyncResult = typeof BiomeSyncResult.Type;
+
+/**
+ * Standard changesets configuration matching the `@changesets/types` upstream spec.
+ *
+ * @remarks
+ * Represents the parsed `.changeset/config.json` file. All fields are optional
+ * to allow partial configs. Use {@link SilkChangesetConfig} when the Silk changelog
+ * adapter is detected.
+ *
+ * @since 0.1.0
+ */
+export declare const ChangesetConfig: Schema.Struct<{
+    changelog: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Array$<typeof Schema.Unknown>]>>;
+    commit: Schema.optional<typeof Schema.Boolean>;
+    fixed: Schema.optional<Schema.Array$<Schema.Array$<typeof Schema.String>>>;
+    linked: Schema.optional<Schema.Array$<Schema.Array$<typeof Schema.String>>>;
+    access: Schema.optional<Schema.Literal<["public", "restricted"]>>;
+    baseBranch: Schema.optional<typeof Schema.String>;
+    updateInternalDependencies: Schema.optional<Schema.Literal<["patch", "minor", "major"]>>;
+    ignore: Schema.optional<Schema.Array$<typeof Schema.String>>;
+}>;
+
+/** @since 0.1.0 */
+export declare type ChangesetConfig = typeof ChangesetConfig.Type;
+
+/**
+ * Raised when the `.changeset/config.json` file cannot be read or decoded.
+ *
+ * @remarks
+ * Returned by {@link ChangesetConfigReader.read} when the file is missing,
+ * contains invalid JSON, or fails Effect Schema validation.
+ *
+ * @since 0.1.0
+ */
+export declare class ChangesetConfigError extends ChangesetConfigError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const ChangesetConfigError_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: "ChangesetConfigError";
+} & Readonly<A>;
+
+/**
+ * Service that reads and decodes the `.changeset/config.json` for a given workspace root.
+ *
+ * @remarks
+ * Automatically detects whether the config uses the Silk changelog adapter
+ * (`@savvy-web/changesets`) and decodes as {@link SilkChangesetConfig} or the
+ * standard {@link ChangesetConfig} accordingly.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const reader = yield* ChangesetConfigReader;
+ *     return yield* reader.read(process.cwd());
+ *   }).pipe(
+ *     Effect.provide(ChangesetConfigReaderLive),
+ *     Effect.provide(NodeContext.layer),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class ChangesetConfigReader extends ChangesetConfigReader_base {
+}
+
+declare const ChangesetConfigReader_base: Context.TagClass<ChangesetConfigReader, "@savvy-web/silk-effects/ChangesetConfigReader", {
+    /**
+     * Read and decode `.changeset/config.json` from the given workspace root.
+     *
+     * @param root - Absolute path to the workspace root containing the `.changeset/` directory.
+     * @returns An `Effect` that succeeds with the decoded config or fails with {@link ChangesetConfigError}.
+     *
+     * @since 0.1.0
+     */
+    readonly read: (root: string) => Effect.Effect<ChangesetConfig | SilkChangesetConfig, ChangesetConfigError>;
+}>;
+
+/**
+ * Live implementation of {@link ChangesetConfigReader}.
+ *
+ * @remarks
+ * Requires `FileSystem` from `@effect/platform`. Provide `NodeContext.layer` or
+ * `BunContext.layer` to satisfy this dependency.
+ *
+ * @since 0.1.0
+ */
+export declare const ChangesetConfigReaderLive: Layer.Layer<ChangesetConfigReader, never, FileSystem.FileSystem>;
+
+/**
+ * Comment syntax used to write managed section markers.
+ *
+ * @remarks
+ * - `"#"` — shell/YAML style, suitable for hook scripts and `.env` files.
+ * - `"//"` — C-style, suitable for JavaScript/TypeScript files.
+ *
+ * @since 0.1.0
+ */
+export declare const CommentStyle: Schema.Literal<["#", "//"]>;
+
+/** @since 0.1.0 */
+export declare type CommentStyle = typeof CommentStyle.Type;
+
+/**
+ * Service that locates named config files within a workspace using priority-ordered search paths.
+ *
+ * @remarks
+ * Search priority (highest to lowest):
+ * 1. `lib/configs/{name}` — shared config provided by a dependency package.
+ * 2. `{cwd}/{name}` — local override at the workspace root.
+ *
+ * Missing files are silently skipped; only files that actually exist are returned.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const discovery = yield* ConfigDiscovery;
+ *     return yield* discovery.find("biome.json");
+ *   }).pipe(
+ *     Effect.provide(ConfigDiscoveryLive),
+ *     Effect.provide(NodeContext.layer),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class ConfigDiscovery extends ConfigDiscovery_base {
+}
+
+declare const ConfigDiscovery_base: Context.TagClass<ConfigDiscovery, "@savvy-web/silk-effects/ConfigDiscovery", {
+    /**
+     * Return the highest-priority {@link ConfigLocation} for the given config file name,
+     * or `null` when none of the candidate paths exist.
+     *
+     * @param name - Config file name (e.g. `"biome.json"`).
+     * @param options - Optional `cwd` override for path resolution.
+     * @returns An `Effect` that always succeeds with a {@link ConfigLocation} or `null`.
+     *
+     * @since 0.1.0
+     */
+    readonly find: (name: string, options?: {
+        cwd?: string;
+    }) => Effect.Effect<ConfigLocation | null>;
+    /**
+     * Return all existing {@link ConfigLocation} entries for the given config file name,
+     * ordered from highest to lowest priority.
+     *
+     * @param name - Config file name (e.g. `"biome.json"`).
+     * @param options - Optional `cwd` override for path resolution.
+     * @returns An `Effect` that always succeeds with an array of {@link ConfigLocation} records.
+     *
+     * @since 0.1.0
+     */
+    readonly findAll: (name: string, options?: {
+        cwd?: string;
+    }) => Effect.Effect<ReadonlyArray<ConfigLocation>>;
+}>;
+
+/**
+ * Live implementation of {@link ConfigDiscovery}.
+ *
+ * @remarks
+ * Requires `FileSystem` from `@effect/platform`. Provide `NodeContext.layer` or
+ * `BunContext.layer` to satisfy this dependency.
+ *
+ * @since 0.1.0
+ */
+export declare const ConfigDiscoveryLive: Layer.Layer<ConfigDiscovery, never, FileSystem.FileSystem>;
+
+/**
+ * Options passed to config discovery methods.
+ *
+ * @remarks
+ * `cwd` overrides the working directory for path resolution (defaults to `process.cwd()`).
+ * `tool` is reserved for future use as a tool-specific discovery hint.
+ *
+ * @since 0.1.0
+ */
+export declare const ConfigDiscoveryOptions: Schema.Struct<{
+    cwd: Schema.optional<typeof Schema.String>;
+    tool: Schema.optional<typeof Schema.String>;
+}>;
+
+/** @since 0.1.0 */
+export declare type ConfigDiscoveryOptions = typeof ConfigDiscoveryOptions.Type;
+
+/**
+ * The resolved location of a discovered config file.
+ *
+ * @remarks
+ * Produced by {@link ConfigDiscovery.find} and {@link ConfigDiscovery.findAll}.
+ * `path` is the absolute file path; `source` indicates how it was discovered.
+ *
+ * @since 0.1.0
+ */
+export declare const ConfigLocation: Schema.Struct<{
+    path: typeof Schema.String;
+    source: Schema.Literal<["lib", "root", "cosmiconfig"]>;
+}>;
+
+/** @since 0.1.0 */
+export declare type ConfigLocation = typeof ConfigLocation.Type;
+
+/**
+ * Raised when a config file cannot be located in any of the expected locations.
+ *
+ * @remarks
+ * Returned by consumers that require a config file to exist. {@link ConfigDiscovery.find}
+ * itself returns `null` instead of failing — callers that need a hard failure should
+ * map `null` to this error.
+ *
+ * @since 0.1.0
+ */
+export declare class ConfigNotFoundError extends ConfigNotFoundError_base<{
+    readonly name: string;
+    readonly searchedPaths: ReadonlyArray<string>;
+}> {
+    get message(): string;
+}
+
+declare const ConfigNotFoundError_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: "ConfigNotFoundError";
+} & Readonly<A>;
+
+/**
+ * The discovery strategy used to locate a config file.
+ *
+ * @remarks
+ * - `"lib"` — found under `lib/configs/{name}` relative to the workspace root.
+ * - `"root"` — found directly in the workspace root as `{name}`.
+ * - `"cosmiconfig"` — reserved for future cosmiconfig-based discovery.
+ *
+ * @since 0.1.0
+ */
+export declare const ConfigSource: Schema.Literal<["lib", "root", "cosmiconfig"]>;
+
+/** @since 0.1.0 */
+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),
+ *   )
+ * );
+ * ```
+ *
+ * @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 `"#"`.
+ *
+ * @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;
+
+/**
+ * Raised when a managed section cannot be parsed from a file.
+ *
+ * @remarks
+ * Returned by {@link ManagedSection.read} when the file exists but its content
+ * cannot be read (e.g. a filesystem permission error).
+ *
+ * @since 0.1.0
+ */
+export declare class ManagedSectionParseError extends ManagedSectionParseError_base<{
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+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;
+}>;
+
+/** @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.
+ *
+ * @since 0.1.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>;
+
+/**
+ * Raised when the `publishConfig` field in a `package.json` is present but invalid.
+ *
+ * @remarks
+ * Returned by {@link SilkPublishabilityPlugin.detect} when `publishConfig` exists
+ * but cannot be mapped to a valid set of publish targets.
+ *
+ * @since 0.1.0
+ */
+export declare class PublishConfigError extends PublishConfigError_base<{
+    readonly packageName: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const PublishConfigError_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: "PublishConfigError";
+} & Readonly<A>;
+
+/**
+ * The publish protocol used when pushing a package to a registry.
+ *
+ * @remarks
+ * `"npm"` covers all npm-compatible registries (npmjs.org, GitHub Packages, custom).
+ * `"jsr"` targets the JSR registry via its own publish tool.
+ *
+ * @since 0.1.0
+ */
+export declare const PublishProtocol: Schema.Literal<["npm", "jsr"]>;
+
+/** @since 0.1.0 */
+export declare type PublishProtocol = typeof PublishProtocol.Type;
+
+/**
+ * Union of all accepted publish-target representations.
+ *
+ * @remarks
+ * Accepts a {@link PublishTargetShorthand} string (`"npm"`, `"github"`, `"jsr"`),
+ * an `https://` URL pointing to a custom npm-compatible registry, or a full
+ * {@link PublishTargetObject} with explicit field overrides.
+ *
+ * @since 0.1.0
+ */
+export 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";
+    }>;
+    registry: Schema.optional<typeof Schema.String>;
+    directory: Schema.optional<typeof Schema.String>;
+    access: Schema.optional<Schema.Literal<["public", "restricted"]>>;
+    provenance: Schema.optional<typeof Schema.Boolean>;
+    tag: Schema.optional<typeof Schema.String>;
+}>]>;
+
+/** @since 0.1.0 */
+export declare type PublishTarget = typeof PublishTarget.Type;
+
+/**
+ * Full publish-target configuration expressed as a structured object.
+ *
+ * @remarks
+ * All fields are optional and fall back to sensible defaults when omitted.
+ * `protocol` defaults to `"npm"`. `access` defaults to the registry default.
+ *
+ * @since 0.1.0
+ */
+export declare const PublishTargetObject: Schema.Struct<{
+    protocol: Schema.optionalWith<Schema.Literal<["npm", "jsr"]>, {
+        default: () => "npm";
+    }>;
+    registry: Schema.optional<typeof Schema.String>;
+    directory: Schema.optional<typeof Schema.String>;
+    access: Schema.optional<Schema.Literal<["public", "restricted"]>>;
+    provenance: Schema.optional<typeof Schema.Boolean>;
+    tag: Schema.optional<typeof Schema.String>;
+}>;
+
+/** @since 0.1.0 */
+export declare type PublishTargetObject = typeof PublishTargetObject.Type;
+
+/**
+ * Shorthand string identifiers for common publish destinations.
+ *
+ * @remarks
+ * - `"npm"` — the public npm registry, authenticated via OIDC.
+ * - `"github"` — GitHub Packages, authenticated via `GITHUB_TOKEN`.
+ * - `"jsr"` — the JSR registry, authenticated via OIDC.
+ *
+ * @since 0.1.0
+ */
+export declare const PublishTargetShorthand: Schema.Literal<["npm", "github", "jsr"]>;
+
+/** @since 0.1.0 */
+export declare type PublishTargetShorthand = typeof PublishTargetShorthand.Type;
+
+/**
+ * Fully resolved publish target with all fields populated and defaults applied.
+ *
+ * @remarks
+ * Produced by {@link TargetResolver.resolve} from any {@link PublishTarget} input.
+ * All optional fields from {@link PublishTargetObject} become required here,
+ * and `auth` / `tokenEnv` are derived from the registry URL.
+ *
+ * @since 0.1.0
+ */
+export declare const ResolvedTarget: Schema.Struct<{
+    protocol: Schema.Literal<["npm", "jsr"]>;
+    registry: Schema.NullOr<typeof Schema.String>;
+    directory: typeof Schema.String;
+    access: Schema.Literal<["public", "restricted"]>;
+    provenance: typeof Schema.Boolean;
+    tag: typeof Schema.String;
+    auth: Schema.Literal<["oidc", "token"]>;
+    tokenEnv: Schema.NullOr<typeof Schema.String>;
+}>;
+
+/** @since 0.1.0 */
+export declare type ResolvedTarget = typeof ResolvedTarget.Type;
+
+/**
+ * Extended changeset config for repos using the `@savvy-web/changesets` changelog adapter.
+ *
+ * @remarks
+ * Extends {@link ChangesetConfig} with a `_isSilk` marker flag that is automatically
+ * set to `true`. Detected by {@link ChangesetConfigReader} when the `changelog` field
+ * references `@savvy-web/changesets`.
+ *
+ * @since 0.1.0
+ */
+export declare const SilkChangesetConfig: Schema.extend<Schema.Struct<{
+    changelog: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Array$<typeof Schema.Unknown>]>>;
+    commit: Schema.optional<typeof Schema.Boolean>;
+    fixed: Schema.optional<Schema.Array$<Schema.Array$<typeof Schema.String>>>;
+    linked: Schema.optional<Schema.Array$<Schema.Array$<typeof Schema.String>>>;
+    access: Schema.optional<Schema.Literal<["public", "restricted"]>>;
+    baseBranch: Schema.optional<typeof Schema.String>;
+    updateInternalDependencies: Schema.optional<Schema.Literal<["patch", "minor", "major"]>>;
+    ignore: Schema.optional<Schema.Array$<typeof Schema.String>>;
+}>, Schema.Struct<{
+    _isSilk: Schema.optionalWith<typeof Schema.Boolean, {
+        default: () => true;
+    }>;
+}>>;
+
+/** @since 0.1.0 */
+export declare type SilkChangesetConfig = typeof SilkChangesetConfig.Type;
+
+/**
+ * Service that determines whether a package is publishable and resolves its targets.
+ *
+ * @remarks
+ * Inspects the `package.json` object using the Silk publishability rules:
+ * - `private: true` with no `publishConfig` → not publishable (empty array).
+ * - `publishConfig` without `access` or `targets` → not publishable.
+ * - `publishConfig.targets` (array) → resolved via {@link TargetResolver}.
+ * - `publishConfig.registry` → resolved as a single registry target.
+ * - Default → resolved as `"npm"`.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const plugin = yield* SilkPublishabilityPlugin;
+ *     return yield* plugin.detect({ publishConfig: { access: "public" } });
+ *   }).pipe(
+ *     Effect.provide(SilkPublishabilityPluginLive),
+ *     Effect.provide(TargetResolverLive),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class SilkPublishabilityPlugin extends SilkPublishabilityPlugin_base {
+}
+
+declare const SilkPublishabilityPlugin_base: Context.TagClass<SilkPublishabilityPlugin, "@savvy-web/silk-effects/SilkPublishabilityPlugin", {
+    /**
+     * Inspect a parsed `package.json` object and return the resolved publish targets.
+     *
+     * @param pkgJson - The parsed `package.json` contents.
+     * @returns An `Effect` that succeeds with an array of {@link ResolvedTarget} records
+     *   (empty when the package is not publishable), or fails with {@link TargetResolutionError}.
+     *
+     * @since 0.1.0
+     */
+    readonly detect: (pkgJson: Record<string, unknown>) => Effect.Effect<ReadonlyArray<ResolvedTarget>, TargetResolutionError>;
+}>;
+
+/**
+ * Live implementation of {@link SilkPublishabilityPlugin}.
+ *
+ * @remarks
+ * Requires {@link TargetResolver} to resolve target strings and objects.
+ *
+ * @since 0.1.0
+ */
+export declare const SilkPublishabilityPluginLive: Layer.Layer<SilkPublishabilityPlugin, never, TargetResolver>;
+
+/**
+ * Raised when a git tag string cannot be formatted for the given package name and version.
+ *
+ * @remarks
+ * Returned by {@link TagStrategy.formatTag} when the `version` argument is an empty string
+ * or another invariant prevents tag construction.
+ *
+ * @since 0.1.0
+ */
+export declare class TagFormatError extends TagFormatError_base<{
+    readonly name: string;
+    readonly version: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const TagFormatError_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: "TagFormatError";
+} & Readonly<A>;
+
+/**
+ * Service that determines and applies the git-tag naming strategy for a release.
+ *
+ * @remarks
+ * Consumes a {@link VersioningStrategyResult} to pick between `"single"` and `"scoped"`
+ * tag formats, then formats tag strings accordingly. Independent versioning always
+ * produces scoped tags; single and fixed-group versioning produces a single shared tag.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const tags = yield* TagStrategy;
+ *     const strategyType = yield* tags.determine({ type: "independent", fixedGroups: [], publishablePackages: [] });
+ *     return yield* tags.formatTag("@my-org/pkg", "1.2.3", strategyType);
+ *   }).pipe(Effect.provide(TagStrategyLive))
+ * );
+ * // => "@my-org/pkg@1.2.3"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class TagStrategy extends TagStrategy_base {
+}
+
+declare const TagStrategy_base: Context.TagClass<TagStrategy, "@savvy-web/silk-effects/TagStrategy", {
+    /**
+     * Determine the appropriate tag strategy type from a versioning strategy result.
+     *
+     * @param versioningResult - The result of {@link VersioningStrategy.detect}.
+     * @returns An `Effect` that always succeeds with a {@link TagStrategyType}.
+     *
+     * @since 0.1.0
+     */
+    readonly determine: (versioningResult: VersioningStrategyResult) => Effect.Effect<TagStrategyType>;
+    /**
+     * Format a git tag string for a given package name, version, and strategy.
+     *
+     * @param name - The package name (e.g. `"@my-org/pkg"` or `"my-pkg"`).
+     * @param version - The semver version string (e.g. `"1.2.3"`). Must not be empty.
+     * @param strategy - The {@link TagStrategyType} to apply.
+     * @returns An `Effect` that resolves to the formatted tag string, or fails with
+     *   {@link TagFormatError} when `version` is empty.
+     *
+     * @since 0.1.0
+     */
+    readonly formatTag: (name: string, version: string, strategy: TagStrategyType) => Effect.Effect<string, TagFormatError>;
+}>;
+
+/**
+ * Live implementation of {@link TagStrategy} with no external dependencies.
+ *
+ * @remarks
+ * All logic is pure: strategy determination and tag formatting involve no I/O.
+ *
+ * @since 0.1.0
+ */
+export declare const TagStrategyLive: Layer.Layer<TagStrategy>;
+
+/**
+ * Git tag naming strategy for a workspace.
+ *
+ * @remarks
+ * - `"single"` — one shared tag for the entire release (e.g. `1.2.3`).
+ * - `"scoped"` — a per-package tag that includes the package name (e.g. `@my-org/pkg@1.2.3`).
+ *
+ * Determined by {@link TagStrategy.determine} based on the {@link VersioningStrategyResult}.
+ *
+ * @since 0.1.0
+ */
+export declare const TagStrategyType: Schema.Literal<["single", "scoped"]>;
+
+/** @since 0.1.0 */
+export declare type TagStrategyType = typeof TagStrategyType.Type;
+
+/**
+ * Raised when a publish target value cannot be resolved into a {@link ResolvedTarget}.
+ *
+ * @remarks
+ * Returned by {@link TargetResolver.resolve} when the input is not a recognised shorthand,
+ * a valid `https://` URL, or a well-formed object target.
+ *
+ * @since 0.1.0
+ */
+export declare class TargetResolutionError extends TargetResolutionError_base<{
+    readonly target: unknown;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const TargetResolutionError_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: "TargetResolutionError";
+} & Readonly<A>;
+
+/**
+ * Service that resolves raw publish-target values into fully-normalised {@link ResolvedTarget} records.
+ *
+ * @remarks
+ * Accepts a single target or an array of targets. Each item may be a
+ * {@link PublishTargetShorthand} string, an `https://` registry URL, or a
+ * {@link PublishTargetObject}. Unknown values produce a {@link TargetResolutionError}.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const resolver = yield* TargetResolver;
+ *     return yield* resolver.resolve("npm");
+ *   }).pipe(Effect.provide(TargetResolverLive))
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class TargetResolver extends TargetResolver_base {
+}
+
+declare const TargetResolver_base: Context.TagClass<TargetResolver, "@savvy-web/silk-effects/TargetResolver", {
+    /**
+     * Resolve one target (or an array of targets) into an array of {@link ResolvedTarget} records.
+     *
+     * @param target - A single publish-target value or an array of them.
+     * @returns An `Effect` that succeeds with the resolved targets or fails with {@link TargetResolutionError}.
+     *
+     * @since 0.1.0
+     */
+    readonly resolve: (target: unknown) => Effect.Effect<ReadonlyArray<ResolvedTarget>, TargetResolutionError>;
+}>;
+
+/**
+ * Live implementation of {@link TargetResolver} with no external dependencies.
+ *
+ * @remarks
+ * All resolution logic is pure: shorthand strings, `https://` URLs, and object targets
+ * are mapped to {@link ResolvedTarget} records without any I/O.
+ *
+ * @since 0.1.0
+ */
+export declare const TargetResolverLive: Layer.Layer<TargetResolver, never, never>;
+
+/**
+ * Raised when the versioning strategy cannot be determined from the workspace state.
+ *
+ * @remarks
+ * Returned by {@link VersioningStrategy.detect} when an unexpected condition
+ * prevents strategy classification.
+ *
+ * @since 0.1.0
+ */
+export declare class VersioningDetectionError extends VersioningDetectionError_base<{
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+
+declare const VersioningDetectionError_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: "VersioningDetectionError";
+} & Readonly<A>;
+
+/**
+ * Service that classifies the versioning strategy used by a workspace.
+ *
+ * @remarks
+ * Reads the changesets config to inspect `fixed` groups, then determines whether
+ * the workspace uses a single-package, fixed-group, or independent versioning strategy.
+ * Falls back to safe defaults when the changeset config is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(
+ *   Effect.gen(function* () {
+ *     const strategy = yield* VersioningStrategy;
+ *     return yield* strategy.detect(["@my-org/pkg-a", "@my-org/pkg-b"]);
+ *   }).pipe(
+ *     Effect.provide(VersioningStrategyLive),
+ *     Effect.provide(ChangesetConfigReaderLive),
+ *     Effect.provide(NodeContext.layer),
+ *   )
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare class VersioningStrategy extends VersioningStrategy_base {
+}
+
+declare const VersioningStrategy_base: Context.TagClass<VersioningStrategy, "@savvy-web/silk-effects/VersioningStrategy", {
+    /**
+     * Classify the versioning strategy for a list of publishable package names.
+     *
+     * @param publishablePackages - Package names (e.g. `"@my-org/pkg"`) that will be published.
+     * @param root - Workspace root directory to read changeset config from.
+     * @returns An `Effect` resolving to a {@link VersioningStrategyResult}, or failing with
+     *   {@link VersioningDetectionError} on unexpected errors.
+     *
+     * @since 0.1.0
+     */
+    readonly detect: (publishablePackages: ReadonlyArray<string>, root: string) => Effect.Effect<VersioningStrategyResult, VersioningDetectionError>;
+}>;
+
+/**
+ * Live implementation of {@link VersioningStrategy}.
+ *
+ * @remarks
+ * Requires {@link ChangesetConfigReader} to read the workspace changeset configuration.
+ * If the config file is absent, an empty `fixed` groups array is assumed.
+ *
+ * @since 0.1.0
+ */
+export declare const VersioningStrategyLive: Layer.Layer<VersioningStrategy, never, ChangesetConfigReader>;
+
+/**
+ * Output of the versioning strategy detection, combining the strategy type with group metadata.
+ *
+ * @remarks
+ * Produced by {@link VersioningStrategy.detect} and consumed by {@link TagStrategy.determine}
+ * to decide on the appropriate git-tag format.
+ *
+ * @since 0.1.0
+ */
+export declare const VersioningStrategyResult: Schema.Struct<{
+    type: Schema.Literal<["single", "fixed-group", "independent"]>;
+    fixedGroups: Schema.Array$<Schema.Array$<typeof Schema.String>>;
+    publishablePackages: Schema.Array$<typeof Schema.String>;
+}>;
+
+/** @since 0.1.0 */
+export declare type VersioningStrategyResult = typeof VersioningStrategyResult.Type;
+
+/**
+ * Versioning strategy classification for a workspace.
+ *
+ * @remarks
+ * - `"single"` — one publishable package; a single version tag is used.
+ * - `"fixed-group"` — all publishable packages are in the same changesets fixed group.
+ * - `"independent"` — multiple publishable packages with independent version bumps.
+ *
+ * @since 0.1.0
+ */
+export declare const VersioningStrategyType: Schema.Literal<["single", "fixed-group", "independent"]>;
+
+/** @since 0.1.0 */
+export declare type VersioningStrategyType = typeof VersioningStrategyType.Type;
+
+export { }