@savvy-web/silk-effects 0.1.0

package/index.js

@@ -0,0 +1,6 @@
+export { BiomeSchemaSync, BiomeSchemaSyncLive, BiomeSyncError } from "./biome.js";
+export { ChangesetConfigError, ChangesetConfigReader, ChangesetConfigReaderLive, VersioningDetectionError, VersioningStrategy, VersioningStrategyLive } from "./versioning.js";
+export { ConfigDiscovery, ConfigDiscoveryLive, ConfigNotFoundError } from "./config.js";
+export { ManagedSection, ManagedSectionLive, ManagedSectionParseError, ManagedSectionWriteError } from "./hooks.js";
+export { PublishConfigError, SilkPublishabilityPlugin, SilkPublishabilityPluginLive, TargetResolutionError, TargetResolver, TargetResolverLive } from "./publish.js";
+export { TagFormatError, TagStrategy, TagStrategyLive } from "./tags.js";

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@savvy-web/silk-effects",
+  "version": "0.1.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"
+    },
+    "./publish": {
+      "types": "./publish.d.ts",
+      "import": "./publish.js"
+    },
+    "./versioning": {
+      "types": "./versioning.d.ts",
+      "import": "./versioning.js"
+    },
+    "./tags": {
+      "types": "./tags.d.ts",
+      "import": "./tags.js"
+    },
+    "./hooks": {
+      "types": "./hooks.d.ts",
+      "import": "./hooks.js"
+    },
+    "./config": {
+      "types": "./config.d.ts",
+      "import": "./config.js"
+    },
+    "./biome": {
+      "types": "./biome.d.ts",
+      "import": "./biome.js"
+    }
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.0",
+    "jsonc-effect": "^0.2.1",
+    "semver-effect": "^0.2.1",
+    "workspaces-effect": "^0.1.0",
+    "yaml-effect": "^0.2.3"
+  },
+  "peerDependencies": {
+    "effect": ">=3.21.0"
+  },
+  "files": [
+    "!silk-effects.api.json",
+    "!tsconfig.json",
+    "!tsdoc.json",
+    "LICENSE",
+    "README.md",
+    "biome.d.ts",
+    "biome.js",
+    "config.d.ts",
+    "config.js",
+    "hooks.d.ts",
+    "hooks.js",
+    "index.d.ts",
+    "index.js",
+    "package.json",
+    "publish.d.ts",
+    "publish.js",
+    "tags.d.ts",
+    "tags.js",
+    "tsdoc-metadata.json",
+    "versioning.d.ts",
+    "versioning.js"
+  ]
+}

package/publish.d.ts

@@ -0,0 +1,260 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+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;
+
+/**
+ * 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;
+
+/**
+ * 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 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>;
+
+export { }

package/publish.js

@@ -0,0 +1,124 @@
+import { Context, Data, Effect, Layer } from "effect";
+class TargetResolutionError extends Data.TaggedError("TargetResolutionError") {
+    get message() {
+        return `Failed to resolve publish target: ${this.reason}`;
+    }
+}
+class PublishConfigError extends Data.TaggedError("PublishConfigError") {
+    get message() {
+        return `Invalid publishConfig for ${this.packageName}: ${this.reason}`;
+    }
+}
+class TargetResolver extends Context.Tag("@savvy-web/silk-effects/TargetResolver")() {
+}
+const DEFAULTS = {
+    directory: "dist/npm",
+    access: "public",
+    provenance: false,
+    tag: "latest"
+};
+function deriveTokenEnv(registryUrl) {
+    try {
+        const hostname = new URL(registryUrl).hostname;
+        return `NPM_TOKEN_${hostname.replace(/\./g, "_").toUpperCase()}`;
+    } catch  {
+        return "NPM_TOKEN";
+    }
+}
+function resolveOne(target) {
+    if ("npm" === target) return Effect.succeed({
+        ...DEFAULTS,
+        protocol: "npm",
+        registry: "https://registry.npmjs.org/",
+        auth: "oidc",
+        tokenEnv: null
+    });
+    if ("github" === target) return Effect.succeed({
+        ...DEFAULTS,
+        protocol: "npm",
+        registry: "https://npm.pkg.github.com/",
+        auth: "token",
+        tokenEnv: "GITHUB_TOKEN"
+    });
+    if ("jsr" === target) return Effect.succeed({
+        ...DEFAULTS,
+        protocol: "jsr",
+        registry: null,
+        auth: "oidc",
+        tokenEnv: null
+    });
+    if ("string" == typeof target && target.startsWith("https://")) return Effect.succeed({
+        ...DEFAULTS,
+        protocol: "npm",
+        registry: target,
+        auth: "token",
+        tokenEnv: deriveTokenEnv(target)
+    });
+    if ("object" == typeof target && null !== target && !Array.isArray(target)) {
+        const obj = target;
+        const protocol = obj.protocol ?? "npm";
+        const registry = obj.registry ?? null;
+        const directory = obj.directory ?? DEFAULTS.directory;
+        const access = obj.access ?? DEFAULTS.access;
+        const provenance = obj.provenance ?? DEFAULTS.provenance;
+        const tag = obj.tag ?? DEFAULTS.tag;
+        let auth;
+        let tokenEnv;
+        if (null !== registry) try {
+            const hostname = new URL(registry).hostname;
+            if ("npm.pkg.github.com" === hostname) {
+                auth = "token";
+                tokenEnv = "GITHUB_TOKEN";
+            } else {
+                auth = "oidc";
+                tokenEnv = null;
+            }
+        } catch  {
+            auth = "oidc";
+            tokenEnv = null;
+        }
+        else {
+            auth = "oidc";
+            tokenEnv = null;
+        }
+        return Effect.succeed({
+            protocol,
+            registry,
+            directory,
+            access,
+            provenance,
+            tag,
+            auth,
+            tokenEnv
+        });
+    }
+    return Effect.fail(new TargetResolutionError({
+        target,
+        reason: `Unsupported target type: ${typeof target}. Expected "npm", "github", "jsr", an https:// URL, or an object.`
+    }));
+}
+const TargetResolverLive = Layer.succeed(TargetResolver, {
+    resolve: (target)=>{
+        if (Array.isArray(target)) return Effect.all(target.map(resolveOne));
+        return resolveOne(target).pipe(Effect.map((resolved)=>[
+                resolved
+            ]));
+    }
+});
+class SilkPublishabilityPlugin extends Context.Tag("@savvy-web/silk-effects/SilkPublishabilityPlugin")() {
+}
+const SilkPublishabilityPluginLive = Layer.effect(SilkPublishabilityPlugin, Effect.gen(function*() {
+    const resolver = yield* TargetResolver;
+    return {
+        detect: (pkgJson)=>{
+            const isPrivate = true === pkgJson.private;
+            const publishConfig = pkgJson.publishConfig;
+            if (isPrivate && !publishConfig) return Effect.succeed([]);
+            if (!publishConfig || !publishConfig.access && !publishConfig.targets) return Effect.succeed([]);
+            if (Array.isArray(publishConfig.targets)) return resolver.resolve(publishConfig.targets);
+            if (publishConfig.registry) return resolver.resolve(publishConfig.registry);
+            return resolver.resolve("npm");
+        }
+    };
+}));
+export { PublishConfigError, SilkPublishabilityPlugin, SilkPublishabilityPluginLive, TargetResolutionError, TargetResolver, TargetResolverLive };

package/tags.d.ts

@@ -0,0 +1,122 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import { VoidIfEmpty } from 'effect/Types';
+import { YieldableError } from 'effect/Cause';
+
+/**
+ * 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;
+
+/**
+ * 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
+ */
+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 */
+declare type VersioningStrategyResult = typeof VersioningStrategyResult.Type;
+
+export { }

package/tags.js

@@ -0,0 +1,25 @@
+import { Context, Data, Effect, Layer } from "effect";
+class TagFormatError extends Data.TaggedError("TagFormatError") {
+    get message() {
+        return `Failed to format tag for ${this.name}@${this.version}: ${this.reason}`;
+    }
+}
+class TagStrategy extends Context.Tag("@savvy-web/silk-effects/TagStrategy")() {
+}
+const TagStrategyLive = Layer.succeed(TagStrategy, TagStrategy.of({
+    determine: (versioningResult)=>{
+        if ("independent" === versioningResult.type) return Effect.succeed("scoped");
+        return Effect.succeed("single");
+    },
+    formatTag: (name, version, strategy)=>{
+        if ("" === version) return Effect.fail(new TagFormatError({
+            name,
+            version,
+            reason: "version cannot be empty"
+        }));
+        if ("single" === strategy) return Effect.succeed(version);
+        name.startsWith("@");
+        return Effect.succeed(`${name}@${version}`);
+    }
+}));
+export { TagFormatError, TagStrategy, TagStrategyLive };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.7"
+    }
+  ]
+}