@savvy-web/silk-effects 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savvy Web Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @savvy-web/silk-effects
+
+[![npm version](https://img.shields.io/npm/v/@savvy-web/silk-effects)](https://www.npmjs.com/package/@savvy-web/silk-effects)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Shared [Effect](https://effect.website/) library providing Silk Suite conventions for publishability detection, versioning strategy, tag formatting, managed sections, config discovery, and Biome schema synchronization. Platform-agnostic: consumers provide their own runtime layer (Node.js, Bun, etc.).
+
+## Features
+
+- Resolve publish targets from shorthand strings, URLs, or objects with sensible defaults
+- Detect versioning strategy (single, fixed-group, independent) from changeset config
+- Format git tags consistently based on workspace structure
+- Manage tool-owned sections inside user-editable files without clobbering user content
+- Discover config files using a priority-based search convention
+- Keep Biome `$schema` URLs in sync across config files
+
+## Installation
+
+```bash
+pnpm add @savvy-web/silk-effects effect @effect/platform @effect/platform-node
+```
+
+`effect` is a peer dependency -- install it alongside the package.
+
+## Quick Start
+
+```typescript
+import { Effect } from "effect";
+import { TargetResolver, TargetResolverLive } from "@savvy-web/silk-effects/publish";
+
+const targets = await Effect.runPromise(
+  Effect.gen(function* () {
+    const resolver = yield* TargetResolver;
+    return yield* resolver.resolve(["npm", "github"]);
+  }).pipe(Effect.provide(TargetResolverLive)),
+);
+```
+
+Modules that access the filesystem require a platform layer:
+
+```typescript
+import { NodeContext } from "@effect/platform-node";
+import { ManagedSection, ManagedSectionLive } from "@savvy-web/silk-effects/hooks";
+
+await Effect.runPromise(
+  Effect.gen(function* () {
+    const section = yield* ManagedSection;
+    yield* section.write(".husky/pre-commit", "silk", "\nnpx lint-staged\n");
+  }).pipe(
+    Effect.provide(ManagedSectionLive),
+    Effect.provide(NodeContext.layer),
+  ),
+);
+```
+
+## Modules
+
+Each module has its own entry point -- import only what you need:
+
+| Module | Entry Point | Platform Layer | Docs |
+| ------ | ----------- | -------------- | ---- |
+| Publish | `@savvy-web/silk-effects/publish` | No | [docs/publish.md](./docs/publish.md) |
+| Versioning | `@savvy-web/silk-effects/versioning` | Yes | [docs/versioning.md](./docs/versioning.md) |
+| Tags | `@savvy-web/silk-effects/tags` | No | [docs/tags.md](./docs/tags.md) |
+| Hooks | `@savvy-web/silk-effects/hooks` | Yes | [docs/hooks.md](./docs/hooks.md) |
+| Config | `@savvy-web/silk-effects/config` | Yes | [docs/config.md](./docs/config.md) |
+| Biome | `@savvy-web/silk-effects/biome` | Yes | [docs/biome.md](./docs/biome.md) |
+
+## Documentation
+
+For service API reference, schemas, error types, and advanced usage, see [docs/](./docs/).
+
+## License
+
+[MIT](./LICENSE)

package/biome.d.ts

@@ -0,0 +1,135 @@
+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';
+
+/**
+ * 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;
+
+export { }

package/biome.js

@@ -0,0 +1,84 @@
+import { FileSystem } from "@effect/platform";
+import { Context, Data, Effect, Layer } from "effect";
+import { parse } from "jsonc-effect";
+class BiomeSyncError extends Data.TaggedError("BiomeSyncError") {
+    get message() {
+        return `Failed to sync biome schema in ${this.path}: ${this.reason}`;
+    }
+}
+function extractSemver(version) {
+    return version.replace(/^[\^~>=<v]+/, "");
+}
+function buildSchemaUrl(version) {
+    return `https://biomejs.dev/schemas/${version}/schema.json`;
+}
+const BIOME_SCHEMA_HOSTNAME = "biomejs.dev";
+function findBiomeConfigs(cwd, fs) {
+    const candidates = [
+        `${cwd}/biome.json`,
+        `${cwd}/biome.jsonc`
+    ];
+    return Effect.gen(function*() {
+        const results = [];
+        for (const candidate of candidates){
+            const exists = yield* fs.exists(candidate).pipe(Effect.orElseSucceed(()=>false));
+            if (exists) results.push(candidate);
+        }
+        return results;
+    });
+}
+class BiomeSchemaSync extends Context.Tag("@savvy-web/silk-effects/BiomeSchemaSync")() {
+}
+const BiomeSchemaSyncLive = Layer.effect(BiomeSchemaSync, Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem;
+    const run = (version, options, write)=>Effect.gen(function*() {
+            const cwd = options?.cwd ?? process.cwd();
+            const semver = extractSemver(version);
+            const expectedUrl = buildSchemaUrl(semver);
+            const configs = yield* findBiomeConfigs(cwd, fs);
+            const updated = [];
+            const skipped = [];
+            const current = [];
+            for (const configPath of configs){
+                const raw = yield* fs.readFileString(configPath).pipe(Effect.mapError((cause)=>new BiomeSyncError({
+                        path: configPath,
+                        reason: String(cause)
+                    })));
+                const parsed = yield* parse(raw).pipe(Effect.mapError((e)=>new BiomeSyncError({
+                        path: configPath,
+                        reason: `Failed to parse JSONC: ${String(e)}`
+                    })));
+                const schema = parsed.$schema;
+                if ("string" != typeof schema) {
+                    skipped.push(configPath);
+                    continue;
+                }
+                if (!schema.includes(BIOME_SCHEMA_HOSTNAME)) {
+                    skipped.push(configPath);
+                    continue;
+                }
+                if (schema === expectedUrl) {
+                    current.push(configPath);
+                    continue;
+                }
+                if (write) {
+                    const updated_content = raw.replaceAll(schema, expectedUrl);
+                    yield* fs.writeFileString(configPath, updated_content).pipe(Effect.mapError((cause)=>new BiomeSyncError({
+                            path: configPath,
+                            reason: String(cause)
+                        })));
+                }
+                updated.push(configPath);
+            }
+            return {
+                updated,
+                skipped,
+                current
+            };
+        });
+    return {
+        sync: (version, options)=>run(version, options, true),
+        check: (version, options)=>run(version, options, false)
+    };
+}));
+export { BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError };

package/config.d.ts

@@ -0,0 +1,147 @@
+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';
+
+/**
+ * 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;
+
+export { }

package/config.js

@@ -0,0 +1,38 @@
+import { FileSystem } from "@effect/platform";
+import { Context, Data, Effect, Layer } from "effect";
+class ConfigDiscovery extends Context.Tag("@savvy-web/silk-effects/ConfigDiscovery")() {
+}
+function safeExists(fs, path) {
+    return fs.exists(path).pipe(Effect.orElseSucceed(()=>false));
+}
+const ConfigDiscoveryLive = Layer.effect(ConfigDiscovery, Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem;
+    const findAll = (name, options)=>Effect.gen(function*() {
+            const cwd = options?.cwd ?? process.cwd();
+            const results = [];
+            const libPath = `${cwd}/lib/configs/${name}`;
+            const libExists = yield* safeExists(fs, libPath);
+            if (libExists) results.push({
+                path: libPath,
+                source: "lib"
+            });
+            const rootPath = `${cwd}/${name}`;
+            const rootExists = yield* safeExists(fs, rootPath);
+            if (rootExists) results.push({
+                path: rootPath,
+                source: "root"
+            });
+            return results;
+        });
+    const find = (name, options)=>findAll(name, options).pipe(Effect.map((results)=>results[0] ?? null));
+    return {
+        find,
+        findAll
+    };
+}));
+class ConfigNotFoundError extends Data.TaggedError("ConfigNotFoundError") {
+    get message() {
+        return `Config '${this.name}' not found. Searched: ${this.searchedPaths.join(", ")}`;
+    }
+}
+export { ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError };