@savvy-web/silk-effects 0.6.1 → 1.0.0

package/turbo/schemas/results.js

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+
+//#region src/turbo/schemas/results.ts
+/** Per-package cache outcome for one task. */
+const PackageCacheStatus = Schema.Struct({
+	package: Schema.String,
+	taskId: Schema.String,
+	hash: Schema.String,
+	status: Schema.Literal("HIT", "MISS"),
+	timeSaved: Schema.Number
+}).annotations({ identifier: "PackageCacheStatus" });
+/** The hash-contributor breakdown explaining a single MISS. */
+const MissExplanation = Schema.Struct({
+	package: Schema.String,
+	taskId: Schema.String,
+	hash: Schema.String,
+	inputFileCount: Schema.Number,
+	hashedEnvVars: Schema.Array(Schema.String),
+	externalDependenciesHash: Schema.String,
+	dependsOn: Schema.Array(Schema.String)
+}).annotations({ identifier: "MissExplanation" });
+/** Global-hash component summary (every task inherits this). */
+const GlobalHashSummary = Schema.Struct({
+	rootKey: Schema.String,
+	globalFileCount: Schema.Number,
+	externalDependenciesHash: Schema.String,
+	internalDependenciesHash: Schema.String,
+	globalEnvVars: Schema.Array(Schema.String)
+}).annotations({ identifier: "GlobalHashSummary" });
+/** Result of `TurboInspector.diagnoseCache`. */
+const CacheDiagnosis = Schema.Struct({
+	task: Schema.String,
+	totalTasks: Schema.Number,
+	hits: Schema.Number,
+	misses: Schema.Number,
+	statuses: Schema.Array(PackageCacheStatus),
+	explanations: Schema.Array(MissExplanation),
+	global: GlobalHashSummary
+}).annotations({ identifier: "CacheDiagnosis" });
+/** One node in the task graph. */
+const GraphNode = Schema.Struct({
+	taskId: Schema.String,
+	package: Schema.String,
+	dependsOn: Schema.Array(Schema.String)
+}).annotations({ identifier: "GraphNode" });
+/** Result of `TurboInspector.taskGraph`. */
+const TaskGraphResult = Schema.Struct({
+	task: Schema.optional(Schema.String),
+	nodeCount: Schema.Number,
+	nodes: Schema.Array(GraphNode),
+	criticalPath: Schema.Array(Schema.String)
+}).annotations({ identifier: "TaskGraphResult" });
+/** Result of `TurboInspector.affected`. */
+const AffectedResult = Schema.Struct({
+	base: Schema.String,
+	packages: Schema.Array(Schema.String),
+	dependents: Schema.Array(Schema.String)
+}).annotations({ identifier: "AffectedResult" });
+
+//#endregion
+export { AffectedResult, CacheDiagnosis, GlobalHashSummary, GraphNode, MissExplanation, PackageCacheStatus, TaskGraphResult };

package/turbo/services/TurboInspector.js

@@ -0,0 +1,100 @@
+import { ToolDefinition } from "../../schemas/ToolDefinition.js";
+import { ToolDiscovery } from "../../services/ToolDiscovery.js";
+import { TurboDigest } from "../digest.js";
+import { DryRunParseError, NotATurboRepoError, TurboExecError, TurboNotInstalledError } from "../errors.js";
+import { TurboDryRun } from "../schemas/DryRun.js";
+import { Context, Effect, Layer, Schema } from "effect";
+import { Command, CommandExecutor, FileSystem } from "@effect/platform";
+
+//#region src/turbo/services/TurboInspector.ts
+/**
+* Read-only Turborepo inspector. All operations use `--dry` and never execute tasks.
+* Surfaced through the MCP `turbo_inspect` tool.
+*
+* @remarks
+* Methods take an explicit `cwd` (the MCP tool handler resolves the workspace root
+* and passes it). Output is decoded with {@link TurboDryRun} and digested by
+* {@link TurboDigest}.
+*
+* @since 0.7.0
+*/
+var TurboInspector = class extends Context.Tag("@savvy-web/silk-effects/TurboInspector")() {};
+const TURBO = ToolDefinition.make({ name: "turbo" });
+/** Default task used by {@link TurboInspector.taskGraph} and {@link TurboInspector.affected}. */
+const DEFAULT_BUILD_TASK = "build:dev";
+/** Default git ref `affected` compares against — matches Turborepo's own `--affected` default. */
+const DEFAULT_AFFECTED_BASE = "main";
+/**
+* Live implementation of {@link TurboInspector}.
+*
+* @remarks
+* Requires {@link ToolDiscovery} to resolve the `turbo` binary, plus
+* `CommandExecutor` and `FileSystem` from `@effect/platform`. Mirrors
+* `ToolDiscoveryLive`: the executor is captured at layer construction and
+* discharged onto each command effect with `Effect.provideService`, keeping
+* the public method effects at `R = never`.
+*
+* @since 0.7.0
+*/
+const TurboInspectorLive = Layer.effect(TurboInspector, Effect.gen(function* () {
+	const discovery = yield* ToolDiscovery;
+	const executor = yield* CommandExecutor.CommandExecutor;
+	const fs = yield* FileSystem.FileSystem;
+	const runTurbo = (cwd, args, env) => discovery.require(TURBO).pipe(Effect.mapError((e) => new TurboNotInstalledError({ reason: e.reason })), Effect.flatMap((resolved) => {
+		const command = resolved.exec(...args).workingDirectory(cwd);
+		return Effect.provideService((env ? command.env(env) : command).string(), CommandExecutor.CommandExecutor, executor).pipe(Effect.mapError((e) => new TurboExecError({
+			args: [...args],
+			reason: String(e)
+		})));
+	}));
+	/** Run a read-only `git` command in `cwd` and return its non-empty output lines. */
+	const runGit = (cwd, args) => Effect.provideService(Command.string(Command.workingDirectory(Command.make("git", ...args), cwd)), CommandExecutor.CommandExecutor, executor).pipe(Effect.mapError((e) => new TurboExecError({
+		args: ["git", ...args],
+		reason: String(e)
+	})), Effect.map((stdout) => stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0)));
+	const ensureTurboRepo = (cwd) => fs.exists(`${cwd}/turbo.json`).pipe(Effect.catchAll(() => Effect.succeed(false)), Effect.flatMap((ok) => ok ? Effect.void : Effect.fail(new NotATurboRepoError({ cwd }))));
+	const dryRun = (task, cwd, args, env) => ensureTurboRepo(cwd).pipe(Effect.flatMap(() => runTurbo(cwd, args, env)), Effect.flatMap((stdout) => Effect.try({
+		try: () => JSON.parse(stdout),
+		catch: (e) => new DryRunParseError({
+			task,
+			reason: `invalid JSON: ${String(e)}`
+		})
+	})), Effect.flatMap((json) => Schema.decodeUnknown(TurboDryRun)(json).pipe(Effect.mapError((e) => new DryRunParseError({
+		task,
+		reason: String(e)
+	})))));
+	return TurboInspector.of({
+		diagnoseCache: (task, cwd) => dryRun(task, cwd, [
+			"run",
+			task,
+			"--dry=json"
+		]).pipe(Effect.map((dry) => TurboDigest.cacheDiagnosis(task, dry))),
+		taskGraph: (cwd, task) => {
+			const t = task ?? DEFAULT_BUILD_TASK;
+			return dryRun(t, cwd, [
+				"run",
+				t,
+				"--dry=json"
+			]).pipe(Effect.map((dry) => TurboDigest.taskGraph(dry, task)));
+		},
+		affected: (cwd, base) => {
+			const ref = base ?? DEFAULT_AFFECTED_BASE;
+			return Effect.all({
+				changedFiles: runGit(cwd, [
+					"diff",
+					"--name-only",
+					`${ref}...HEAD`
+				]),
+				dry: dryRun(`${DEFAULT_BUILD_TASK} --affected`, cwd, [
+					"run",
+					DEFAULT_BUILD_TASK,
+					"--affected",
+					"--dry=json"
+				], { TURBO_SCM_BASE: ref })
+			}).pipe(Effect.map(({ changedFiles, dry }) => TurboDigest.affected(ref, changedFiles, dry)));
+		}
+	});
+}));
+
+//#endregion
+export { TurboInspector, TurboInspectorLive };

package/utils/ToolCommand.js

@@ -0,0 +1,40 @@
+import { Command } from "@effect/platform";
+
+//#region src/utils/ToolCommand.ts
+/**
+* Wraps `@effect/platform` {@link Command.Command} with instance method ergonomics.
+*
+* Use `yield* cmd.string()` instead of `yield* Command.string(cmd)`.
+*
+* @since 0.2.0
+*/
+var ToolCommand = class ToolCommand {
+	command;
+	constructor(command) {
+		this.command = command;
+	}
+	string(encoding) {
+		return Command.string(this.command, encoding);
+	}
+	exitCode() {
+		return Command.exitCode(this.command);
+	}
+	lines(encoding) {
+		return Command.lines(this.command, encoding);
+	}
+	stream() {
+		return Command.stream(this.command);
+	}
+	env(environment) {
+		return new ToolCommand(Command.env(this.command, environment));
+	}
+	workingDirectory(cwd) {
+		return new ToolCommand(Command.workingDirectory(this.command, cwd));
+	}
+	stdin(input) {
+		return new ToolCommand(Command.feed(this.command, input));
+	}
+};
+
+//#endregion
+export { ToolCommand };