@savvy-web/silk-effects 0.1.0

package/hooks.d.ts

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

package/hooks.js

@@ -0,0 +1,96 @@
+import { Context, Data, Effect, Layer } from "effect";
+import { FileSystem } from "@effect/platform";
+class ManagedSectionParseError extends Data.TaggedError("ManagedSectionParseError") {
+    get message() {
+        return `Failed to parse managed section in ${this.path}: ${this.reason}`;
+    }
+}
+class ManagedSectionWriteError extends Data.TaggedError("ManagedSectionWriteError") {
+    get message() {
+        return `Failed to write managed section to ${this.path}: ${this.reason}`;
+    }
+}
+function beginMarker(toolName, commentStyle) {
+    return `${commentStyle} --- BEGIN ${toolName.toUpperCase()} MANAGED SECTION ---`;
+}
+function endMarker(toolName, commentStyle) {
+    return `${commentStyle} --- END ${toolName.toUpperCase()} MANAGED SECTION ---`;
+}
+function parseContent(content, toolName, commentStyle) {
+    const begin = beginMarker(toolName, commentStyle);
+    const end = endMarker(toolName, commentStyle);
+    const beginIndex = content.indexOf(begin);
+    const endIndex = content.indexOf(end);
+    if (-1 === beginIndex || -1 === endIndex || endIndex <= beginIndex) return null;
+    const before = content.slice(0, beginIndex);
+    const managed = content.slice(beginIndex + begin.length, endIndex);
+    const after = content.slice(endIndex + end.length);
+    return {
+        before,
+        managed,
+        after
+    };
+}
+function assembleContent(before, managed, after, toolName, commentStyle) {
+    const begin = beginMarker(toolName, commentStyle);
+    const end = endMarker(toolName, commentStyle);
+    return `${before}${begin}${managed}${end}${after}`;
+}
+class ManagedSection extends Context.Tag("@savvy-web/silk-effects/ManagedSection")() {
+}
+const ManagedSectionLive = Layer.effect(ManagedSection, Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem;
+    const read = (path, toolName, commentStyle = "#")=>Effect.gen(function*() {
+            const exists = yield* fs.exists(path).pipe(Effect.orElseSucceed(()=>false));
+            if (!exists) return null;
+            const raw = yield* fs.readFileString(path).pipe(Effect.mapError((cause)=>new ManagedSectionParseError({
+                    path,
+                    reason: String(cause)
+                })));
+            return parseContent(raw, toolName, commentStyle);
+        });
+    const write = (path, toolName, content, commentStyle = "#")=>Effect.gen(function*() {
+            const exists = yield* fs.exists(path).pipe(Effect.orElseSucceed(()=>false));
+            let fileContent;
+            if (exists) {
+                const raw = yield* fs.readFileString(path).pipe(Effect.mapError((cause)=>new ManagedSectionWriteError({
+                        path,
+                        reason: String(cause)
+                    })));
+                const parsed = parseContent(raw, toolName, commentStyle);
+                if (null !== parsed) fileContent = assembleContent(parsed.before, content, parsed.after, toolName, commentStyle);
+                else {
+                    const trimmed = raw.trimEnd();
+                    const begin = beginMarker(toolName, commentStyle);
+                    const end = endMarker(toolName, commentStyle);
+                    fileContent = `${trimmed}\n\n${begin}${content}${end}\n`;
+                }
+            } else {
+                const begin = beginMarker(toolName, commentStyle);
+                const end = endMarker(toolName, commentStyle);
+                fileContent = `${begin}${content}${end}\n`;
+            }
+            yield* fs.writeFileString(path, fileContent).pipe(Effect.mapError((cause)=>new ManagedSectionWriteError({
+                    path,
+                    reason: String(cause)
+                })));
+        });
+    const update = (path, toolName, content, commentStyle = "#")=>write(path, toolName, content, commentStyle);
+    const isManaged = (path, toolName, commentStyle = "#")=>Effect.gen(function*() {
+            const exists = yield* fs.exists(path).pipe(Effect.orElseSucceed(()=>false));
+            if (!exists) return false;
+            const raw = yield* fs.readFileString(path).pipe(Effect.orElseSucceed(()=>""));
+            const begin = beginMarker(toolName, commentStyle);
+            const end = endMarker(toolName, commentStyle);
+            const beginIdx = raw.indexOf(begin);
+            const endIdx = raw.indexOf(end);
+            return -1 !== beginIdx && -1 !== endIdx && endIdx > beginIdx;
+        });
+    return {
+        read,
+        write,
+        update,
+        isManaged
+    };
+}));
+export { ManagedSection, ManagedSectionLive, ManagedSectionParseError, ManagedSectionWriteError };