@savvy-web/silk-effects 0.6.0 → 1.0.0

package/package.json

@@ -1,65 +1,54 @@
 {
-  "name": "@savvy-web/silk-effects",
-  "version": "0.6.0",
-  "private": false,
-  "description": "Shared Effect library for Silk Suite conventions",
-  "homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
-  "bugs": {
-    "url": "https://github.com/savvy-web/systems/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/savvy-web/systems.git",
-    "directory": "packages/silk-effects"
-  },
-  "license": "MIT",
-  "author": {
-    "name": "C. Spencer Beggs",
-    "email": "spencer@savvyweb.systems",
-    "url": "https://savvyweb.systems"
-  },
-  "sideEffects": false,
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
-    }
-  },
-  "dependencies": {
-    "@changesets/get-github-info": "^0.8.0",
-    "jsonc-effect": "^0.2.1",
-    "mdast-util-heading-range": "^4.0.0",
-    "mdast-util-to-string": "^4.0.0",
-    "prettier": "^3.8.3",
-    "remark-gfm": "^4.0.1",
-    "remark-parse": "^11.0.0",
-    "remark-stringify": "^11.0.0",
-    "semver-effect": "^0.2.1",
-    "shell-quote": "^1.8.4",
-    "sort-package-json": "^3.6.1",
-    "tinyglobby": "^0.2.16",
-    "unified": "^11.0.5",
-    "unified-lint-rule": "^3.0.1",
-    "unist-util-visit": "^5.1.0",
-    "workspaces-effect": "^1.1.0",
-    "yaml": "^2.9.0",
-    "yaml-effect": "^0.6.0",
-    "yaml-lint": "^1.7.0"
-  },
-  "peerDependencies": {
-    "@effect/platform": ">=0.96.0",
-    "effect": ">=3.21.0"
-  },
-  "files": [
-    "!silk-effects.api.json",
-    "!tsconfig.json",
-    "!tsdoc.json",
-    "LICENSE",
-    "README.md",
-    "index.d.ts",
-    "index.js",
-    "package.json",
-    "tsdoc-metadata.json"
-  ]
+	"name": "@savvy-web/silk-effects",
+	"version": "1.0.0",
+	"private": false,
+	"description": "Shared Effect library for Silk Suite conventions",
+	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
+	"bugs": {
+		"url": "https://github.com/savvy-web/systems/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/savvy-web/systems.git",
+		"directory": "packages/silk-effects"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@savvyweb.systems",
+		"url": "https://savvyweb.systems"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		}
+	},
+	"dependencies": {
+		"@changesets/get-github-info": "^0.8.0",
+		"jsonc-effect": "^0.2.1",
+		"mdast-util-heading-range": "^4.0.0",
+		"mdast-util-to-string": "^4.0.0",
+		"prettier": "^3.8.3",
+		"remark-gfm": "^4.0.1",
+		"remark-parse": "^11.0.0",
+		"remark-stringify": "^11.0.0",
+		"semver-effect": "^0.2.1",
+		"shell-quote": "^1.8.4",
+		"sort-package-json": "^3.6.1",
+		"tinyglobby": "^0.2.16",
+		"unified": "^11.0.5",
+		"unified-lint-rule": "^3.0.1",
+		"unist-util-visit": "^5.1.0",
+		"workspaces-effect": "^1.1.0",
+		"yaml": "^2.9.0",
+		"yaml-effect": "^0.6.0",
+		"yaml-lint": "^1.7.0"
+	},
+	"peerDependencies": {
+		"@effect/platform": ">=0.96.0",
+		"effect": ">=3.21.0"
+	}
 }

package/schemas/CommentStyle.js

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+
+//#region src/schemas/CommentStyle.ts
+/**
+* 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
+*/
+const CommentStyle = Schema.Literal("#", "//");
+
+//#endregion
+export { CommentStyle };

package/schemas/ResolvedTool.js

@@ -0,0 +1,63 @@
+import { ToolCommand } from "../utils/ToolCommand.js";
+import { ToolSource } from "./ToolResults.js";
+import { Equal, Hash, Schema } from "effect";
+import { Command } from "@effect/platform";
+
+//#region src/schemas/ResolvedTool.ts
+const PackageManager = Schema.Literal("npm", "pnpm", "yarn", "bun");
+/**
+* Result of resolving a {@link ToolDefinition}.
+*
+* Provides {@link exec} and {@link dlx} to build commands for the resolved tool.
+*
+* @since 0.2.0
+*/
+var ResolvedTool = class ResolvedTool extends Schema.TaggedClass()("ResolvedTool", {
+	name: Schema.String,
+	source: ToolSource,
+	version: Schema.OptionFromSelf(Schema.String),
+	globalVersion: Schema.OptionFromSelf(Schema.String),
+	localVersion: Schema.OptionFromSelf(Schema.String),
+	packageManager: PackageManager,
+	mismatch: Schema.Boolean
+}) {
+	get isGlobal() {
+		return this.source === "global";
+	}
+	get isLocal() {
+		return this.source === "local";
+	}
+	get hasVersionMismatch() {
+		return this.mismatch;
+	}
+	exec(...args) {
+		if (this.source === "global") return new ToolCommand(Command.make(this.name, ...args));
+		switch (this.packageManager) {
+			case "pnpm": return new ToolCommand(Command.make("pnpm", "exec", this.name, ...args));
+			case "npm": return new ToolCommand(Command.make("npx", "--no", "--", this.name, ...args));
+			case "yarn": return new ToolCommand(Command.make("yarn", "exec", this.name, ...args));
+			case "bun": return new ToolCommand(Command.make("bun", "x", "--no-install", this.name, ...args));
+		}
+	}
+	dlx(...args) {
+		switch (this.packageManager) {
+			case "pnpm": return new ToolCommand(Command.make("pnpm", "dlx", this.name, ...args));
+			case "npm": return new ToolCommand(Command.make("npx", this.name, ...args));
+			case "yarn": return new ToolCommand(Command.make("yarn", "dlx", this.name, ...args));
+			case "bun": return new ToolCommand(Command.make("bun", "x", this.name, ...args));
+		}
+	}
+	[Equal.symbol](that) {
+		if (!(that instanceof ResolvedTool)) return false;
+		return this.name === that.name && this.source === that.source && Equal.equals(this.version, that.version);
+	}
+	[Hash.symbol]() {
+		let h = Hash.hash(this.name);
+		h = Hash.combine(h)(Hash.hash(this.source));
+		h = Hash.combine(h)(Hash.hash(this.version));
+		return Hash.cached(this)(h);
+	}
+};
+
+//#endregion
+export { ResolvedTool };

package/schemas/SavvySections.js

@@ -0,0 +1,113 @@
+import { ShellSectionDefinition } from "./SectionDefinition.js";
+
+//#region src/schemas/SavvySections.ts
+/**
+* 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
+*/
+const SavvyBaseSection = ShellSectionDefinition.make({ toolName: "savvy-base" });
+/**
+* Section identity for the shared repo-hygiene block.
+*
+* `toolName` is `"savvy-hooks"`; pair with {@link savvyHooksHygiene}.
+*
+* @since 0.5.0
+*/
+const SavvyHooksSection = ShellSectionDefinition.make({ toolName: "savvy-hooks" });
+/**
+* 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
+*/
+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
+}`;
+}
+/**
+* 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
+*/
+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`;
+}
+/**
+* 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
+*/
+function savvyToolSection(toolName, command) {
+	return ShellSectionDefinition.make({ toolName }).block(`in_ci || pm_exec ${command}`);
+}
+
+//#endregion
+export { SavvyBaseSection, SavvyHooksSection, savvyBasePreamble, savvyHooksHygiene, savvyToolSection };

package/schemas/SectionBlock.js

@@ -0,0 +1,70 @@
+import { CommentStyle } from "./CommentStyle.js";
+import { SectionDiff } from "./SectionResults.js";
+import { Equal, Function, Hash, Schema } from "effect";
+
+//#region src/schemas/SectionBlock.ts
+/**
+* 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
+*/
+var SectionBlock = class SectionBlock extends Schema.TaggedClass()("SectionBlock", {
+	toolName: Schema.String,
+	commentStyle: CommentStyle,
+	content: Schema.String
+}) {
+	static diff = Function.dual(2, (self, that) => self.diff(that));
+	static prepend = Function.dual(2, (self, lines) => self.prepend(lines));
+	static append = Function.dual(2, (self, lines) => self.append(lines));
+	get text() {
+		return this.content;
+	}
+	get normalized() {
+		return this.content.trim().replace(/\s+/g, " ");
+	}
+	get rendered() {
+		const begin = `${this.commentStyle} --- BEGIN ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+		const end = `${this.commentStyle} --- END ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+		return `${begin}\n${this.content}\n${end}`;
+	}
+	prepend(lines) {
+		return SectionBlock.make({
+			toolName: this.toolName,
+			commentStyle: this.commentStyle,
+			content: `${lines}\n${this.content}`
+		});
+	}
+	append(lines) {
+		return SectionBlock.make({
+			toolName: this.toolName,
+			commentStyle: this.commentStyle,
+			content: `${this.content}\n${lines}`
+		});
+	}
+	diff(that) {
+		if (this.normalized === that.normalized) return SectionDiff.Unchanged();
+		const selfLines = this.content.trim().split("\n");
+		const thatLines = that.content.trim().split("\n");
+		const selfSet = new Set(selfLines);
+		const thatSet = new Set(thatLines);
+		const removed = selfLines.filter((line) => !thatSet.has(line));
+		const added = thatLines.filter((line) => !selfSet.has(line));
+		return SectionDiff.Changed({
+			added,
+			removed
+		});
+	}
+	[Equal.symbol](that) {
+		if (!(that instanceof SectionBlock)) return false;
+		return this.normalized === that.normalized;
+	}
+	[Hash.symbol]() {
+		return Hash.cached(this)(Hash.hash(this.normalized));
+	}
+};
+
+//#endregion
+export { SectionBlock };

package/schemas/SectionDefinition.js

@@ -0,0 +1,121 @@
+import { SectionValidationError } from "../errors/SectionValidationError.js";
+import { CommentStyle } from "./CommentStyle.js";
+import { SectionDiff } from "./SectionResults.js";
+import { SectionBlock } from "./SectionBlock.js";
+import { Effect, Equal, Function, Hash, Schema } from "effect";
+
+//#region src/schemas/SectionDefinition.ts
+/**
+* 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
+*/
+var SectionDefinition = class SectionDefinition extends Schema.TaggedClass()("SectionDefinition", {
+	toolName: Schema.String,
+	commentStyle: Schema.optionalWith(CommentStyle, { default: () => "#" })
+}) {
+	_validate;
+	static generate = Function.dual(2, (self, fn) => {
+		return (config) => self.block(fn(config));
+	});
+	static generateEffect = Function.dual(2, (self, fn) => {
+		return (config) => Effect.flatMap(fn(config), (content) => {
+			try {
+				return Effect.succeed(self.block(content));
+			} catch (e) {
+				return Effect.fail(e);
+			}
+		});
+	});
+	static withValidation = Function.dual(2, (self, fn) => {
+		const copy = SectionDefinition.make({
+			toolName: self.toolName,
+			commentStyle: self.commentStyle
+		});
+		copy._validate = fn;
+		return copy;
+	});
+	static diff = Function.dual(2, (self, that) => self.diff(that));
+	block(content) {
+		const block = SectionBlock.make({
+			toolName: this.toolName,
+			commentStyle: this.commentStyle,
+			content
+		});
+		if (this._validate && !this._validate(block)) throw new SectionValidationError({
+			toolName: this.toolName,
+			reason: "Content failed validation"
+		});
+		return block;
+	}
+	generate(fn) {
+		return (config) => this.block(fn(config));
+	}
+	generateEffect(fn) {
+		return (config) => Effect.flatMap(fn(config), (content) => {
+			try {
+				return Effect.succeed(this.block(content));
+			} catch (e) {
+				return Effect.fail(e);
+			}
+		});
+	}
+	diff(that) {
+		if (Equal.equals(this, that)) return SectionDiff.Unchanged();
+		return SectionDiff.Changed({
+			added: [that.toolName !== this.toolName ? `toolName: ${that.toolName}` : "", that.commentStyle !== this.commentStyle ? `commentStyle: ${that.commentStyle}` : ""].filter(Boolean),
+			removed: [that.toolName !== this.toolName ? `toolName: ${this.toolName}` : "", that.commentStyle !== this.commentStyle ? `commentStyle: ${this.commentStyle}` : ""].filter(Boolean)
+		});
+	}
+	get beginMarker() {
+		return `${this.commentStyle} --- BEGIN ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+	}
+	get endMarker() {
+		return `${this.commentStyle} --- END ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+	}
+	[Equal.symbol](that) {
+		if (!(that instanceof SectionDefinition)) return false;
+		return this.toolName === that.toolName && this.commentStyle === that.commentStyle;
+	}
+	[Hash.symbol]() {
+		return Hash.cached(this)(Hash.combine(Hash.hash(this.toolName))(Hash.hash(this.commentStyle)));
+	}
+};
+/**
+* Convenience section definition for shell hooks.
+*
+* `commentStyle` is always `"#"` — only `toolName` is required.
+*
+* @since 0.2.0
+*/
+var ShellSectionDefinition = class extends Schema.TaggedClass()("ShellSectionDefinition", { toolName: Schema.String }) {
+	get commentStyle() {
+		return "#";
+	}
+	block(content) {
+		return SectionBlock.make({
+			toolName: this.toolName,
+			commentStyle: "#",
+			content
+		});
+	}
+	generate(fn) {
+		return (config) => this.block(fn(config));
+	}
+	generateEffect(fn) {
+		return (config) => Effect.map(fn(config), (content) => this.block(content));
+	}
+	get beginMarker() {
+		return `# --- BEGIN ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+	}
+	get endMarker() {
+		return `# --- END ${this.toolName.toUpperCase()} MANAGED SECTION ---`;
+	}
+};
+
+//#endregion
+export { SectionDefinition, ShellSectionDefinition };

package/schemas/SectionResults.js

@@ -0,0 +1,12 @@
+import { Data } from "effect";
+
+//#region src/schemas/SectionResults.ts
+/** @since 0.2.0 */
+const SectionDiff = Data.taggedEnum();
+/** @since 0.2.0 */
+const SyncResult = Data.taggedEnum();
+/** @since 0.2.0 */
+const CheckResult = Data.taggedEnum();
+
+//#endregion
+export { CheckResult, SectionDiff, SyncResult };

package/schemas/TagStrategySchemas.js

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+
+//#region src/schemas/TagStrategySchemas.ts
+/**
+* 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
+*/
+const TagStrategyType = Schema.Literal("single", "scoped");
+
+//#endregion
+export { TagStrategyType };

package/schemas/ToolDefinition.js

@@ -0,0 +1,39 @@
+import { ResolutionPolicy, SourceRequirement, VersionExtractor } from "./ToolResults.js";
+import { Equal, Hash, Schema } from "effect";
+
+//#region src/schemas/ToolDefinition.ts
+const NameSchema = Schema.Struct({ name: Schema.String });
+/**
+* Declares a CLI tool's identity and resolution constraints.
+*
+* {@link Equal} compares on `name` only (identity).
+*
+* @since 0.2.0
+*/
+var ToolDefinition = class ToolDefinition {
+	_tag = "ToolDefinition";
+	name;
+	versionExtractor;
+	policy;
+	source;
+	constructor(name, versionExtractor, policy, source) {
+		this.name = name;
+		this.versionExtractor = versionExtractor;
+		this.policy = policy;
+		this.source = source;
+	}
+	static make(options) {
+		Schema.decodeUnknownSync(NameSchema)({ name: options.name });
+		return new ToolDefinition(options.name, options.versionExtractor ?? VersionExtractor.Flag({ flag: "--version" }), options.policy ?? ResolutionPolicy.Report(), options.source ?? SourceRequirement.Any());
+	}
+	[Equal.symbol](that) {
+		if (!(that instanceof ToolDefinition)) return false;
+		return this.name === that.name;
+	}
+	[Hash.symbol]() {
+		return Hash.cached(this)(Hash.hash(this.name));
+	}
+};
+
+//#endregion
+export { ToolDefinition };

package/schemas/ToolResults.js

@@ -0,0 +1,14 @@
+import { Data, Schema } from "effect";
+
+//#region src/schemas/ToolResults.ts
+/** Where a tool was resolved from. @since 0.2.0 */
+const ToolSource = Schema.Literal("global", "local");
+/** @since 0.2.0 */
+const VersionExtractor = Data.taggedEnum();
+/** @since 0.2.0 */
+const ResolutionPolicy = Data.taggedEnum();
+/** @since 0.2.0 */
+const SourceRequirement = Data.taggedEnum();
+
+//#endregion
+export { ResolutionPolicy, SourceRequirement, ToolSource, VersionExtractor };