@savvy-web/silk-effects 0.4.1 → 0.5.0

package/README.md

@@ -9,7 +9,7 @@ Shared [Effect](https://effect.website/) library providing Silk Suite convention
 
 - Detect a package's publish targets from its `package.json` `publishConfig`, with multi-registry support and a changeset-ignore-aware override for `workspaces-effect`'s `PublishabilityDetector`
 - Read changeset config through a typed accessor service that reports silk vs vanilla mode, ignore patterns and fixed groups
-- Manage tool-owned sections in user-editable files without clobbering surrounding content
+- Manage tool-owned sections in user-editable files without clobbering surrounding content, including ordered multi-section sync for composing several managed regions per file
 - Discover and resolve CLI tools globally or locally with version enforcement and caching
 - Detect versioning strategy and format git tags from changeset configuration
 - Locate config files and keep Biome schema URLs in sync across workspaces
@@ -166,7 +166,7 @@ Manage tool-owned delimited sections inside user-editable files. Sections are bo
 
 `SectionBlock` represents the content between markers. It supports `diff()`, `prepend()` and `append()` operations and uses normalized content for equality comparison.
 
-Methods: `read`, `write`, `sync`, `check`, `isManaged` — all support dual API (data-first and data-last) for pipe composition.
+Methods: `read`, `write`, `sync`, `syncMany`, `check`, `remove`, `isManaged` — all support dual API (data-first and data-last) for pipe composition. `sync` manages one section; `syncMany` manages several ordered sections in one file; `remove` deletes a section including its markers.
 
 ```typescript
 import { Effect } from "effect";
@@ -192,6 +192,10 @@ await Effect.runPromise(
     // Check: compare file content against expected block
     const check = yield* ms.check(".husky/pre-commit", block);
     // => CheckResult: Found | NotFound
+
+    // Remove: delete the section and its markers, collapsing the leftover blank line
+    const removed = yield* ms.remove(".husky/pre-commit", def);
+    // => true if a section was removed, false if none was present
   }).pipe(
     Effect.provide(ManagedSectionLive),
     Effect.provide(NodeContext.layer),
@@ -207,6 +211,37 @@ const jsDef = SectionDefinition.make({ toolName: "MY-TOOL", commentStyle: "//" }
 
 Use `ShellSectionDefinition` when the comment style is always `#` and should not be configurable.
 
+`syncMany` keeps several sections in one file in their declared relative order. It updates existing sections in place, inserts a missing section next to its declared sibling, normalizes order when sections drift out of order and preserves user content and unrelated tool sections. It returns one `SyncResult` per input block in input order and is idempotent.
+
+The `SavvySections` exports compose ordered managed sections per husky hook file. A base section defines shared shell, then each consumer layers its own one-line tool section on top:
+
+- `SavvyBaseSection` is a `ShellSectionDefinition` (tool name `savvy-base`); pair it with `savvyBasePreamble()`, which defines `ROOT`, the `in_ci` predicate, `PM` via package-manager detection and `pm_exec`.
+- `SavvyHooksSection` (tool name `savvy-hooks`) pairs with `savvyHooksHygiene()`, a self-guarded repo-hygiene block that runs outside CI.
+- `savvyToolSection(toolName, command)` builds a consumer's one-line tool section whose content is exactly `in_ci || pm_exec <command>` — the command is appended verbatim, so shell tokens like `$ROOT` and `$1` survive into the output. A `savvy-base` section must precede it in the same hook file, so pass both to `syncMany` in that order.
+
+```typescript
+import { Effect } from "effect";
+import { NodeContext } from "@effect/platform-node";
+import {
+  ManagedSection, ManagedSectionLive,
+  SavvyBaseSection, savvyBasePreamble, savvyToolSection,
+} from "@savvy-web/silk-effects";
+
+await Effect.runPromise(
+  Effect.gen(function* () {
+    const ms = yield* ManagedSection;
+    const results = yield* ms.syncMany(".husky/commit-msg", [
+      SavvyBaseSection.block(savvyBasePreamble()),
+      savvyToolSection("savvy-commit", 'commitlint --config "$ROOT/lib/configs/commitlint.config.ts" --edit "$1"'),
+    ]);
+    // => ReadonlyArray<SyncResult>, one per input block in declared order
+  }).pipe(
+    Effect.provide(ManagedSectionLive),
+    Effect.provide(NodeContext.layer),
+  ),
+);
+```
+
 #### VersioningStrategy
 
 Classify the versioning strategy from changeset configuration. Outputs `"single"` (0-1 publishable packages), `"fixed-group"` (all packages in one fixed group) or `"independent"` (multiple packages, not in a single group). Falls back gracefully if config is missing.

package/index.d.ts

@@ -626,10 +626,18 @@ declare const ManagedSection_base: Context.TagClass<ManagedSection, "@savvy-web/
         (block: SectionBlock): (path: string) => Effect.Effect<SyncResult, SectionWriteError>;
         (path: string, block: SectionBlock): Effect.Effect<SyncResult, SectionWriteError>;
     };
+    readonly syncMany: {
+        (blocks: ReadonlyArray<SectionBlock>): (path: string) => Effect.Effect<ReadonlyArray<SyncResult>, SectionWriteError>;
+        (path: string, blocks: ReadonlyArray<SectionBlock>): Effect.Effect<ReadonlyArray<SyncResult>, SectionWriteError>;
+    };
     readonly check: {
         (block: SectionBlock): (path: string) => Effect.Effect<CheckResult, SectionParseError>;
         (path: string, block: SectionBlock): Effect.Effect<CheckResult, SectionParseError>;
     };
+    readonly remove: {
+        (definition: SectionDefinition): (path: string) => Effect.Effect<boolean, SectionWriteError>;
+        (path: string, definition: SectionDefinition): Effect.Effect<boolean, SectionWriteError>;
+    };
 }>;
 
 /**
@@ -796,6 +804,86 @@ declare const ResolvedTool_base: Schema.TaggedClass<ResolvedTool, "ResolvedTool"
     mismatch: typeof Schema.Boolean;
 }>;
 
+/**
+ * Package-manager detection preamble shared across Silk Suite hook files.
+ *
+ * @remarks
+ * Side-effect-free definitions meant to run unconditionally — no markers, no outer CI
+ * guard. Defines `ROOT`, the `in_ci` predicate, `PM` (via `detect_pm`), and `pm_exec`.
+ * `pm_exec` uses local/exec semantics for every package manager and `bun x` (space form),
+ * which works regardless of how bun was installed (the `bunx` shim is not always on PATH).
+ *
+ * @returns The preamble shell, with no surrounding markers or trailing newline.
+ *
+ * @since 0.5.0
+ */
+export declare function savvyBasePreamble(): string;
+
+/**
+ * Section identity for the shared package-manager preamble.
+ *
+ * `toolName` is `"savvy-base"`; pair with {@link savvyBasePreamble} to build the block:
+ *
+ * @example
+ * ```ts
+ * const block = SavvyBaseSection.block(savvyBasePreamble());
+ * ```
+ *
+ * @since 0.5.0
+ */
+export declare const SavvyBaseSection: ShellSectionDefinition;
+
+/**
+ * Repo-hygiene block shared across Silk Suite hook files.
+ *
+ * @remarks
+ * Self-guarded against CI and needs no package manager: disables Git's `core.fileMode`
+ * tracking and marks tracked shell scripts executable.
+ *
+ * @returns The hygiene shell, with no surrounding markers or trailing newline.
+ *
+ * @since 0.5.0
+ */
+export declare function savvyHooksHygiene(): string;
+
+/**
+ * Section identity for the shared repo-hygiene block.
+ *
+ * `toolName` is `"savvy-hooks"`; pair with {@link savvyHooksHygiene}.
+ *
+ * @since 0.5.0
+ */
+export declare const SavvyHooksSection: ShellSectionDefinition;
+
+/**
+ * Build a consumer's one-line tool section so every consumer calls the shared base
+ * helpers identically.
+ *
+ * @remarks
+ * The returned block's content is exactly `in_ci || pm_exec <command>` with `command`
+ * appended verbatim — it is not parsed, quoted, or interpolated, so shell tokens like
+ * `$ROOT` and `$1` survive into the generated literal.
+ *
+ * **Precondition:** a {@link SavvyBaseSection} block must precede this section in the same
+ * hook file so `in_ci` and `pm_exec` are defined. Consumers guarantee this by passing both
+ * to {@link ManagedSection.syncMany | ManagedSection.syncMany} in order:
+ *
+ * @example
+ * ```ts
+ * yield* ManagedSection.syncMany(".husky/commit-msg", [
+ *   SavvyBaseSection.block(savvyBasePreamble()),
+ *   savvyToolSection("savvy-commit", 'commitlint --config "$ROOT/lib/configs/commitlint.config.ts" --edit "$1"'),
+ * ]);
+ * ```
+ *
+ * @param toolName - Section identity; also drives the marker names (uppercased).
+ * @param command - The command passed verbatim to `pm_exec`, run only outside CI.
+ * @returns A shell {@link SectionBlock} (`commentStyle: "#"`) for `toolName`.
+ *
+ * @since 0.5.0
+ */
+export declare function savvyToolSection(toolName: string, command: string): SectionBlock;
+
 /**
  * The content between managed section markers.
  *

package/index.js

@@ -365,6 +365,49 @@ class ShellSectionDefinition extends Schema.TaggedClass()("ShellSectionDefinitio
         return `# --- END ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
     }
 }
+const SavvyBaseSection = ShellSectionDefinition.make({
+    toolName: "savvy-base"
+});
+const SavvyHooksSection = ShellSectionDefinition.make({
+    toolName: "savvy-hooks"
+});
+function savvyBasePreamble() {
+    return `ROOT=$(git rev-parse --show-toplevel)
+
+in_ci() { [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ]; }
+
+detect_pm() {
+  if [ -f "$ROOT/package.json" ]; then
+    pm=$(jq -r '.packageManager // empty' "$ROOT/package.json" 2>/dev/null | cut -d'@' -f1)
+    if [ -n "$pm" ]; then echo "$pm"; return; fi
+  fi
+  if   [ -f "$ROOT/pnpm-lock.yaml" ]; then echo "pnpm"
+  elif [ -f "$ROOT/yarn.lock" ];      then echo "yarn"
+  elif [ -f "$ROOT/bun.lock" ];       then echo "bun"
+  else echo "npm"; fi
+}
+PM=$(detect_pm)
+
+pm_exec() {
+  case "$PM" in
+    pnpm) pnpm exec "$@" ;;
+    yarn) yarn exec "$@" ;;
+    bun)  bun x "$@" ;;
+    *)    npx --no -- "$@" ;;
+  esac
+}`;
+}
+function savvyHooksHygiene() {
+    return `if ! { [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ]; }; then
+  git config core.fileMode false
+  git ls-files -z '*.sh' | xargs -0 chmod +x 2>/dev/null || true
+fi`;
+}
+function savvyToolSection(toolName, command) {
+    return ShellSectionDefinition.make({
+        toolName
+    }).block(`in_ci || pm_exec ${command}`);
+}
 function ToolDefinition_to_primitive(input, hint) {
     if ("object" !== ToolDefinition_type_of(input) || null === input) return input;
     var prim = input[Symbol.toPrimitive];
@@ -849,6 +892,34 @@ function assembleContent(before, managed, after, toolName, commentStyle) {
     const end = endMarker(toolName, commentStyle);
     return `${before}${begin}\n${managed}\n${end}${after}`;
 }
+const BEGIN_MARKER_RE = /^(#|\/\/) --- BEGIN (.+?) MANAGED SECTION ---$/gm;
+function sectionKey(toolName, commentStyle) {
+    return `${toolName.toUpperCase()}::${commentStyle}`;
+}
+function findAllSections(content) {
+    const results = [];
+    for (const match of content.matchAll(BEGIN_MARKER_RE)){
+        const style = match[1];
+        const name = match[2];
+        const beginStart = match.index;
+        const beginEnd = beginStart + match[0].length;
+        const end = `${style} --- END ${name} MANAGED SECTION ---`;
+        const endIdx = content.indexOf(end, beginEnd);
+        if (-1 === endIdx) continue;
+        let inner = content.slice(beginEnd, endIdx);
+        if (inner.startsWith("\n")) inner = inner.slice(1);
+        if (inner.endsWith("\n")) inner = inner.slice(0, -1);
+        results.push({
+            key: sectionKey(name, style),
+            commentStyle: style,
+            content: inner,
+            raw: content.slice(beginStart, endIdx + end.length),
+            start: beginStart,
+            end: endIdx + end.length
+        });
+    }
+    return results;
+}
 class ManagedSection extends Context.Tag("@savvy-web/silk-effects/ManagedSection")() {
 }
 const ManagedSectionLive = Layer.effect(ManagedSection, Effect.gen(function*() {
@@ -923,6 +994,107 @@ const ManagedSectionLive = Layer.effect(ManagedSection, Effect.gen(function*() {
                 diff: d
             });
         }));
+    const syncMany = Function.dual(2, (path, blocks)=>Effect.gen(function*() {
+            const exists = yield* fs.exists(path).pipe(Effect.orElseSucceed(()=>false));
+            const original = exists ? yield* fs.readFileString(path).pipe(Effect.mapError((cause)=>new SectionWriteError({
+                    path,
+                    reason: String(cause)
+                }))) : "";
+            const keyOf = (b)=>sectionKey(b.toolName, b.commentStyle);
+            const found = findAllSections(original);
+            const onDiskByKey = new Map();
+            for (const f of found)if (!onDiskByKey.has(f.key)) onDiskByKey.set(f.key, f);
+            const results = blocks.map((block)=>{
+                const onDisk = onDiskByKey.get(keyOf(block));
+                if (void 0 === onDisk) return SyncResult.Created();
+                const current = SectionBlock.make({
+                    toolName: block.toolName,
+                    commentStyle: block.commentStyle,
+                    content: onDisk.content
+                });
+                if (Equal.equals(current, block)) return SyncResult.Unchanged();
+                return SyncResult.Updated({
+                    diff: SectionBlock.diff(current, block)
+                });
+            });
+            const items = [];
+            let cursor = 0;
+            for (const f of found){
+                items.push({
+                    kind: "text",
+                    value: original.slice(cursor, f.start)
+                });
+                items.push({
+                    kind: "section",
+                    key: f.key,
+                    raw: f.raw,
+                    render: null
+                });
+                cursor = f.end;
+            }
+            items.push({
+                kind: "text",
+                value: original.slice(cursor)
+            });
+            const targetKeys = new Set(blocks.map(keyOf));
+            const slotIndices = [];
+            items.forEach((item, idx)=>{
+                if ("section" === item.kind && targetKeys.has(item.key)) slotIndices.push(idx);
+            });
+            const itemIndexByDeclared = new Map();
+            let slotCursor = 0;
+            blocks.forEach((block, declaredIdx)=>{
+                if (!onDiskByKey.has(keyOf(block))) return;
+                if (slotCursor >= slotIndices.length) return;
+                const itemIdx = slotIndices[slotCursor];
+                const item = items[itemIdx];
+                if ("section" === item.kind) item.render = block;
+                itemIndexByDeclared.set(declaredIdx, itemIdx);
+                slotCursor += 1;
+            });
+            const beforeAnchor = new Map();
+            const afterAnchor = new Map();
+            const appendList = [];
+            const pushInto = (map, anchor, block)=>{
+                const arr = map.get(anchor) ?? [];
+                arr.push(block);
+                map.set(anchor, arr);
+            };
+            blocks.forEach((block, i)=>{
+                if (onDiskByKey.has(keyOf(block))) return;
+                let placed = false;
+                for(let j = i + 1; j < blocks.length && !placed; j += 1){
+                    const itemIdx = itemIndexByDeclared.get(j);
+                    if (void 0 !== itemIdx) {
+                        pushInto(beforeAnchor, itemIdx, block);
+                        placed = true;
+                    }
+                }
+                for(let j = i - 1; j >= 0 && !placed; j -= 1){
+                    const itemIdx = itemIndexByDeclared.get(j);
+                    if (void 0 !== itemIdx) {
+                        pushInto(afterAnchor, itemIdx, block);
+                        placed = true;
+                    }
+                }
+                if (!placed) appendList.push(block);
+            });
+            const out = [];
+            items.forEach((item, idx)=>{
+                if ("text" === item.kind) return void out.push(item.value);
+                for (const block of beforeAnchor.get(idx) ?? [])out.push(block.rendered, "\n\n");
+                out.push(null === item.render ? item.raw : item.render.rendered);
+                for (const block of afterAnchor.get(idx) ?? [])out.push("\n\n", block.rendered);
+            });
+            let output = out.join("");
+            for (const block of appendList)output = "" === output.trim() ? `${block.rendered}\n` : `${output.replace(/\n+$/, "")}\n\n${block.rendered}\n`;
+            if ("" !== output && !output.endsWith("\n")) output += "\n";
+            if (output !== original) yield* fs.writeFileString(path, output).pipe(Effect.mapError((cause)=>new SectionWriteError({
+                    path,
+                    reason: String(cause)
+                })));
+            return results;
+        }));
     const check = Function.dual(2, (path, block)=>Effect.gen(function*() {
             const onDisk = yield* read(path, {
                 toolName: block.toolName,
@@ -936,12 +1108,33 @@ const ManagedSectionLive = Layer.effect(ManagedSection, Effect.gen(function*() {
                 diff: d
             });
         }));
+    const remove = Function.dual(2, (path, definition)=>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.mapError((cause)=>new SectionWriteError({
+                    path,
+                    reason: String(cause)
+                })));
+            const parsed = parseContent(raw, definition.toolName, definition.commentStyle);
+            if (null === parsed) return false;
+            const before = parsed.before.replace(/\n+$/, "");
+            const after = parsed.after.replace(/^\n+/, "");
+            let next;
+            next = "" !== before && "" !== after ? `${before}\n\n${after}` : "" !== before ? `${before}\n` : after;
+            yield* fs.writeFileString(path, next).pipe(Effect.mapError((cause)=>new SectionWriteError({
+                    path,
+                    reason: String(cause)
+                })));
+            return true;
+        }));
     return {
         read,
         write,
         isManaged,
         sync,
-        check
+        syncMany,
+        check,
+        remove
     };
 }));
 const NPM_DEFAULT = "https://registry.npmjs.org/";
@@ -1454,4 +1647,4 @@ const ToolDiscoveryLive = Layer.effect(ToolDiscovery, Effect.gen(function*() {
         clearCache
     };
 }));
-export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, CheckResult, ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError, ManagedSection, ManagedSectionLive, PublishabilityDetectorAdaptiveLive, ResolutionPolicy, ResolvedTool, SectionBlock, SectionDefinition, SectionDiff, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, SyncResult, TagFormatError, TagStrategy, TagStrategyLive, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, VersionExtractor, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver };
+export { AnalyzedWorkspace, BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError, ChangesetConfig, ChangesetConfigError, ChangesetConfigLive, ChangesetConfigReader, ChangesetConfigReaderLive, CheckResult, ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError, ManagedSection, ManagedSectionLive, PublishabilityDetectorAdaptiveLive, ResolutionPolicy, ResolvedTool, SavvyBaseSection, SavvyHooksSection, SectionBlock, SectionDefinition, SectionDiff, SectionParseError, SectionValidationError, SectionWriteError, ShellSectionDefinition, SilkPublishConfig, SilkPublishability, SilkPublishabilityDetectorLive, SilkWorkspaceAnalyzer, SilkWorkspaceAnalyzerLive, SourceRequirement, SyncResult, TagFormatError, TagStrategy, TagStrategyLive, ToolCommand, ToolDefinition, ToolDiscovery, ToolDiscoveryLive, ToolNotFoundError, ToolResolutionError, ToolSource, ToolVersionMismatchError, VersionExtractor, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive, WorkspaceAnalysis, WorkspaceAnalysisError, buildSchemaUrl, extractSemver, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/silk-effects",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
   "description": "Shared Effect library for Silk Suite conventions",
   "homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",