@cvr/stacked 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cvr/stacked",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/stacked"
@@ -32,20 +32,20 @@
     "prepare": "effect-language-service patch && lefthook install"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-beta.12",
-    "effect": "4.0.0-beta.12",
+    "@effect/platform-bun": "4.0.0-beta.27",
+    "effect": "4.0.0-beta.27",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8",
-    "@effect/language-service": "^0.76.0",
-    "@types/bun": "^1.3.9",
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@effect/language-service": "^0.77.0",
+    "@types/bun": "^1.3.10",
     "concurrently": "^9.2.1",
     "effect-bun-test": "^0.2.1",
-    "lefthook": "^2.1.1",
-    "oxfmt": "^0.35.0",
-    "oxlint": "^1.50.0",
+    "lefthook": "^2.1.2",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
     "typescript": "^5.9.3"
   }
 }

package/skills/stacked/SKILL.md

@@ -45,7 +45,7 @@ What do you need?
 | `stacked down`               | Move down one branch in the stack                                                           |
 | `stacked top`                | Jump to top of stack                                                                        |
 | `stacked bottom`             | Jump to bottom of stack                                                                     |
-| `stacked sync`               | Fetch + rebase stack on trunk (`--from`, `--dry-run`, `--json`)                             |
+| `stacked sync`               | Fetch + rebase + force-push stack on trunk (`--from`, `--dry-run`, `--json`)                |
 | `stacked detect`             | Detect branch chains and register as stacks (`--dry-run`, `--json`)                         |
 | `stacked clean`              | Remove merged branches + remote branches (`--dry-run`, `--json`)                            |
 | `stacked delete <name>`      | Remove branch from stack + git + remote (`--keep-remote`, `--force`, `--dry-run`, `--json`) |
@@ -140,13 +140,13 @@ stacked bottom               # jump to bottom (trunk-adjacent)
 
 All navigation commands support `--json` for structured output. `checkout` falls through to `git checkout` for branches not in any stack.
 
-## Syncing / Rebasing
+## Syncing / Rebasing / Pushing
 
-Fetch latest trunk and rebase the entire stack bottom-to-top:
+Fetch latest trunk, rebase the entire stack bottom-to-top, then force-push each rebased branch (`--force-with-lease`):
 
 ```sh
 stacked sync
-stacked sync --dry-run    # preview rebase plan without executing
+stacked sync --dry-run    # preview rebase/push plan without executing
 stacked sync --json       # structured output: { branches: [{ name, action, base }] }
 ```
 
@@ -355,7 +355,7 @@ stacked down  # go to previous branch
 ## Gotchas
 
 - `stacked sync` requires a clean working tree — commit or stash first (except `--dry-run`)
-- `stacked sync` rebases bottom-to-top — resolve conflicts one branch at a time
+- `stacked sync` rebases bottom-to-top and force-pushes each rebased branch with lease
 - `stacked sync` leaves rebase in progress on conflict — resolve with `git rebase --continue`, then resume with `stacked sync --from <parent>`
 - `stacked submit` force-pushes by default (use `--no-force` to disable)
 - `stacked submit` and `stacked clean` require `gh` CLI authenticated (`gh auth login`)

package/src/commands/adopt.ts

@@ -94,7 +94,8 @@ export const adopt = Command.make("adopt", {
         yield* Console.log(JSON.stringify({ adopted: branch, stack: stackName }, null, 2));
       } else {
         yield* Console.error(`Adopted ${branch} into stack`);
-        yield* Console.error(dim("Run 'stacked sync' to rebase onto the new parent."));
+        const hint = yield* dim("Run 'stacked sync' to rebase onto the new parent.");
+        yield* Console.error(hint);
       }
     }),
   ),

package/src/commands/amend.ts

@@ -37,14 +37,21 @@ export const amend = Command.make("amend", {
         });
       }
 
-      yield* git.commitAmend({ edit });
-
       const fromBranch = Option.isSome(from) ? from.value : currentBranch;
 
       // Find children to rebase
       const { branches } = result.stack;
       const idx = branches.indexOf(fromBranch);
-      if (idx === -1 || idx >= branches.length - 1) {
+      if (idx === -1) {
+        return yield* new StackError({
+          code: ErrorCode.BRANCH_NOT_FOUND,
+          message: `Branch "${fromBranch}" not found in stack "${result.name}"`,
+        });
+      }
+
+      yield* git.commitAmend({ edit });
+
+      if (idx >= branches.length - 1) {
         if (json) {
           // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
           yield* Console.log(JSON.stringify({ amended: currentBranch, synced: [] }, null, 2));

package/src/commands/clean.ts

@@ -79,7 +79,8 @@ export const clean = Command.make("clean", { dryRun: dryRunFlag, json: jsonFlag
               `${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
             );
             for (const { branch, stackName } of skippedMerged) {
-              yield* Console.error(dim(`  ${branch} (${stackName})`));
+              const line = yield* dim(`  ${branch} (${stackName})`);
+              yield* Console.error(line);
             }
           }
         }
@@ -88,7 +89,8 @@ export const clean = Command.make("clean", { dryRun: dryRunFlag, json: jsonFlag
 
       if (!dryRun) {
         for (const { branch } of toRemove) {
-          yield* Console.error(dim(`  ${branch}`));
+          const line = yield* dim(`  ${branch}`);
+          yield* Console.error(line);
         }
         const confirmed = yield* confirm(
           `Remove ${toRemove.length} merged branch${toRemove.length === 1 ? "" : "es"}?`,
@@ -146,16 +148,18 @@ export const clean = Command.make("clean", { dryRun: dryRunFlag, json: jsonFlag
         yield* success(
           `Cleaned ${removed.length} merged branch${removed.length === 1 ? "" : "es"}`,
         );
-        yield* Console.error(
-          dim("Run 'stacked sync' then 'stacked submit' to rebase and retarget PRs."),
+        const hint = yield* dim(
+          "Run 'stacked sync' then 'stacked submit' to rebase and retarget PRs.",
         );
+        yield* Console.error(hint);
 
         if (skippedMerged.length > 0) {
           yield* warn(
             `${skippedMerged.length} merged branch${skippedMerged.length === 1 ? "" : "es"} skipped (non-merged branches below):`,
           );
           for (const { branch, stackName } of skippedMerged) {
-            yield* Console.error(dim(`  ${branch} (${stackName})`));
+            const line = yield* dim(`  ${branch} (${stackName})`);
+            yield* Console.error(line);
           }
         }
       }

package/src/commands/detect.ts

@@ -3,6 +3,7 @@ import { Console, Effect } from "effect";
 import { GitService } from "../services/Git.js";
 import { StackService } from "../services/Stack.js";
 import { success, warn, info } from "../ui.js";
+import { detectLimitConfig, limitUntrackedBranches } from "./helpers/detect.js";
 
 const dryRunFlag = Flag.boolean("dry-run").pipe(
   Flag.withDescription("Show what would be detected without making changes"),
@@ -26,13 +27,21 @@ export const detect = Command.make("detect", { dryRun: dryRunFlag, json: jsonFla
 
       const data = yield* stacks.load();
       const alreadyTracked = new Set(Object.values(data.stacks).flatMap((s) => [...s.branches]));
-      const untracked = candidates.filter((b) => !alreadyTracked.has(b));
+      const untrackedAll = candidates.filter((b) => !alreadyTracked.has(b));
+      const detectLimit = yield* detectLimitConfig;
+      const { untracked, skipped } = limitUntrackedBranches(untrackedAll, detectLimit);
 
       if (untracked.length === 0) {
         yield* Console.error("No untracked branches found");
         return;
       }
 
+      if (skipped > 0) {
+        yield* warn(
+          `Analyzing ${untracked.length}/${untrackedAll.length} untracked branches (set STACKED_DETECT_MAX_BRANCHES to adjust)`,
+        );
+      }
+
       // Build parent map: for each branch, find its direct parent among other branches
       // A parent is the closest ancestor — i.e., an ancestor that is not an ancestor of another ancestor
       const childOf = new Map<string, string>();
@@ -75,15 +84,24 @@ export const detect = Command.make("detect", { dryRun: dryRunFlag, json: jsonFla
 
       // Build linear chains from trunk
       // Find branches whose parent is trunk (chain roots)
+      const childrenByParent = new Map<string, string[]>();
+      for (const branch of untracked) {
+        const parent = childOf.get(branch);
+        if (parent === undefined) continue;
+        const children = childrenByParent.get(parent) ?? [];
+        children.push(branch);
+        childrenByParent.set(parent, children);
+      }
+
       const chains: string[][] = [];
-      const roots = untracked.filter((b) => childOf.get(b) === trunk);
+      const roots = childrenByParent.get(trunk) ?? [];
 
       for (const root of roots) {
         const chain = [root];
         let current = root;
 
         while (true) {
-          const children = untracked.filter((b) => childOf.get(b) === current);
+          const children = childrenByParent.get(current) ?? [];
           const child = children[0];
           if (children.length === 1 && child !== undefined) {
             chain.push(child);
@@ -98,13 +116,10 @@ export const detect = Command.make("detect", { dryRun: dryRunFlag, json: jsonFla
       }
 
       // Report forks
-      const forkPoints = untracked.filter((b) => {
-        const children = untracked.filter((c) => childOf.get(c) === b);
-        return children.length > 1;
-      });
+      const forkPoints = untracked.filter((b) => (childrenByParent.get(b)?.length ?? 0) > 1);
       const forks = forkPoints.map((b) => ({
         branch: b,
-        children: untracked.filter((c) => childOf.get(c) === b),
+        children: childrenByParent.get(b) ?? [],
       }));
 
       if (json) {

package/src/commands/helpers/detect.ts

@@ -0,0 +1,22 @@
+import { Config } from "effect";
+
+export const DEFAULT_MAX_DETECT_BRANCHES = 200;
+
+export interface LimitedBranches {
+  readonly untracked: readonly string[];
+  readonly skipped: number;
+}
+
+export const detectLimitConfig = Config.int("STACKED_DETECT_MAX_BRANCHES").pipe(
+  Config.withDefault(DEFAULT_MAX_DETECT_BRANCHES),
+  Config.orElse(() => Config.succeed(DEFAULT_MAX_DETECT_BRANCHES)),
+  Config.map((value) => (value > 0 ? value : DEFAULT_MAX_DETECT_BRANCHES)),
+);
+
+export const limitUntrackedBranches = (
+  untrackedAll: readonly string[],
+  limit: number,
+): LimitedBranches => {
+  const untracked = untrackedAll.slice(0, limit);
+  return { untracked, skipped: untrackedAll.length - untracked.length };
+};

package/src/commands/init.ts

@@ -1,5 +1,5 @@
 import { Command } from "effect/unstable/cli";
-import { Console, Effect } from "effect";
+import { Config, Console, Effect } from "effect";
 import { StackError } from "../errors/index.js";
 import { mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
@@ -18,7 +18,9 @@ export const init = Command.make("init").pipe(
         });
       }
 
-      const skillsDir = process.env["STACKED_SKILLS_DIR"] ?? join(homedir(), ".claude", "skills");
+      const skillsDir = yield* Config.string("STACKED_SKILLS_DIR").pipe(
+        Config.withDefault(join(homedir(), ".claude", "skills")),
+      );
       const targetDir = join(skillsDir, "stacked");
       const targetPath = join(targetDir, "SKILL.md");
 

package/src/commands/list.ts

@@ -84,27 +84,27 @@ export const list = Command.make("list", { stackName: stackNameArg, json: jsonFl
 
       const lines: string[] = [];
 
-      lines.push(`Stack: ${stdout.bold(targetStackName)}`);
-      lines.push(`Trunk: ${stdout.dim(trunk)}`);
+      lines.push(`Stack: ${yield* stdout.bold(targetStackName)}`);
+      lines.push(`Trunk: ${yield* stdout.dim(trunk)}`);
       lines.push("");
 
       for (let i = targetStack.branches.length - 1; i >= 0; i--) {
         const branch = targetStack.branches[i];
         if (branch === undefined) continue;
         const isCurrent = branch === currentBranch;
-        const marker = isCurrent ? stdout.green("* ") : "  ";
-        const prefix = stdout.dim(i === 0 ? "└─" : "├─");
-        const name = isCurrent ? stdout.bold(branch) : branch;
+        const marker = isCurrent ? yield* stdout.green("* ") : "  ";
+        const prefix = yield* stdout.dim(i === 0 ? "└─" : "├─");
+        const name = isCurrent ? yield* stdout.bold(branch) : branch;
 
         const pr = prMap.get(branch) ?? null;
         const status =
           pr === null
             ? ""
             : pr.state === "MERGED"
-              ? stdout.green(" [merged]")
+              ? yield* stdout.green(" [merged]")
               : pr.state === "CLOSED"
-                ? stdout.dim(" [closed]")
-                : stdout.cyan(` [#${pr.number}]`);
+                ? yield* stdout.dim(" [closed]")
+                : yield* stdout.cyan(` [#${pr.number}]`);
 
         lines.push(`${marker}${prefix} ${name}${status}`);
       }

package/src/commands/reorder.ts

@@ -56,6 +56,16 @@ export const reorder = Command.make("reorder", {
       if (currentIdx === -1) return;
 
       const target = Option.isSome(before) ? before.value : Option.getOrElse(after, () => "");
+      if (target === branch) {
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ branch, stack: stackName, branches }, null, 2));
+        } else {
+          yield* warn(`"${branch}" is already at the requested position`);
+        }
+        return;
+      }
+
       const targetIdx = branches.indexOf(target);
       if (targetIdx === -1) {
         return yield* new StackError({

package/src/commands/stacks.ts

@@ -45,12 +45,11 @@ export const stacks = Command.make("stacks", { json: jsonFlag }).pipe(
       const lines: string[] = [];
       for (const [name, stack] of entries) {
         const isCurrent = stack.branches.includes(currentBranch);
-        const marker = isCurrent ? stdout.green("* ") : "  ";
-        const label = isCurrent ? stdout.bold(name) : name;
+        const marker = isCurrent ? yield* stdout.green("* ") : "  ";
+        const label = isCurrent ? yield* stdout.bold(name) : name;
         const count = stack.branches.length;
-        lines.push(
-          `${marker}${label} ${stdout.dim(`(${count} branch${count === 1 ? "" : "es"})`)}`,
-        );
+        const countText = yield* stdout.dim(`(${count} branch${count === 1 ? "" : "es"})`);
+        lines.push(`${marker}${label} ${countText}`);
       }
 
       yield* Console.log(lines.join("\n"));

package/src/commands/status.ts

@@ -36,17 +36,19 @@ export const status = Command.make("status", { json: jsonFlag }).pipe(
       }
 
       const lines: string[] = [];
-      lines.push(`Branch: ${stdout.bold(currentBranch)}`);
-      lines.push(`Working tree: ${clean ? stdout.green("clean") : stdout.yellow("dirty")}`);
+      lines.push(`Branch: ${yield* stdout.bold(currentBranch)}`);
+      lines.push(
+        `Working tree: ${clean ? yield* stdout.green("clean") : yield* stdout.yellow("dirty")}`,
+      );
 
       if (result !== null) {
         const { branches } = result.stack;
         const idx = branches.indexOf(currentBranch);
-        lines.push(
-          `Stack: ${stdout.bold(result.name)} ${stdout.dim(`(${idx + 1} of ${branches.length})`)}`,
-        );
+        const stackName = yield* stdout.bold(result.name);
+        const position = yield* stdout.dim(`(${idx + 1} of ${branches.length})`);
+        lines.push(`Stack: ${stackName} ${position}`);
       } else {
-        lines.push(stdout.dim("Not in a stack. Run 'stacked create <name>' to start one."));
+        lines.push(yield* stdout.dim("Not in a stack. Run 'stacked create <name>' to start one."));
       }
 
       yield* Console.log(lines.join("\n"));

package/src/commands/submit.ts

@@ -32,9 +32,10 @@ const onlyFlag = Flag.boolean("only").pipe(Flag.withDescription("Only submit the
 
 interface SubmitResult {
   branch: string;
-  number: number;
-  url: string;
-  action: "created" | "updated" | "unchanged";
+  base: string;
+  number?: number;
+  url?: string;
+  action: "created" | "updated" | "unchanged" | "would-create" | "would-update" | "would-unchanged";
 }
 
 const STACKED_MARKER_START = "<!-- stacked -->";
@@ -210,7 +211,23 @@ export const submit = Command.make("submit", {
         if (only && branch !== currentBranch) continue;
 
         if (dryRun) {
-          yield* Console.error(`Would push ${branch} and create/update PR (base: ${base})`);
+          const existingPR = yield* gh.getPR(branch);
+          const action =
+            existingPR === null
+              ? "would-create"
+              : existingPR.base !== base
+                ? "would-update"
+                : "would-unchanged";
+          results.push({
+            branch,
+            base,
+            number: existingPR?.number,
+            url: existingPR?.url,
+            action,
+          });
+          if (!json) {
+            yield* Console.error(`Would push ${branch} and create/update PR (base: ${base})`);
+          }
           continue;
         }
 
@@ -225,6 +242,7 @@ export const submit = Command.make("submit", {
             yield* gh.updatePR({ branch, base });
             results.push({
               branch,
+              base,
               number: existingPR.number,
               url: existingPR.url,
               action: "updated",
@@ -233,6 +251,7 @@ export const submit = Command.make("submit", {
             yield* Console.error(`PR #${existingPR.number} already exists: ${existingPR.url}`);
             results.push({
               branch,
+              base,
               number: existingPR.number,
               url: existingPR.url,
               action: "unchanged",
@@ -257,6 +276,7 @@ export const submit = Command.make("submit", {
           yield* success(`Created PR #${pr.number}: ${pr.url}`);
           results.push({
             branch,
+            base,
             number: pr.number,
             url: pr.url,
             action: "created",
@@ -264,16 +284,23 @@ export const submit = Command.make("submit", {
         }
       }
 
-      if (dryRun) return;
+      if (dryRun) {
+        if (json) {
+          // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
+          yield* Console.log(JSON.stringify({ results }, null, 2));
+        }
+        return;
+      }
 
-      // Update existing PRs with stack metadata
+      // Update all processed PRs with complete stack metadata.
+      // This includes newly created PRs so placeholders get replaced in one submit run.
       for (let i = 0; i < branches.length; i++) {
         const branch = branches[i];
         if (branch === undefined) continue;
         if (only && branch !== currentBranch) continue;
 
         const entry = results.find((x) => x.branch === branch);
-        if (entry === undefined || entry.action === "created") continue;
+        if (entry === undefined) continue;
 
         const metadata = generateStackMetadata(branches, prMap, i, result.name);
         const existingPrData = prMap.get(branch) ?? null;

package/src/commands/sync.ts

@@ -32,7 +32,9 @@ export const sync = Command.make("sync", {
   json: jsonFlag,
   dryRun: dryRunFlag,
 }).pipe(
-  Command.withDescription("Fetch and rebase stack on trunk. Use --from to start from a branch."),
+  Command.withDescription(
+    "Fetch, rebase, and force-push stack branches. Use --from to start from a branch.",
+  ),
   Command.withExamples([
     { command: "stacked sync", description: "Rebase entire stack on trunk" },
     { command: "stacked sync --from feat-auth", description: "Resume from a specific branch" },
@@ -93,7 +95,7 @@ export const sync = Command.make("sync", {
           const base = i === 0 ? `origin/${trunk}` : (branches[i - 1] ?? `origin/${trunk}`);
           results.push({ name: branch, action: "skipped", base });
           if (!json) {
-            yield* Console.error(`Would rebase ${branch} onto ${base}`);
+            yield* Console.error(`Would rebase and force-push ${branch} onto ${base}`);
           }
         }
 
@@ -137,6 +139,7 @@ export const sync = Command.make("sync", {
               );
             }),
           );
+          yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: true }));
           results.push({ name: branch, action: "rebased", base: newBase });
         }
       }).pipe(

package/src/errors/index.ts

@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import { Runtime, Schema } from "effect";
 
 // ============================================================================
 // Error Codes
@@ -43,3 +43,9 @@ export class GitHubError extends Schema.TaggedErrorClass<GitHubError>()("GitHubE
   command: Schema.optional(Schema.String),
   code: Schema.optional(Schema.String),
 }) {}
+
+export class GlobalFlagConflictError extends Error {
+  override readonly name = "GlobalFlagConflictError";
+  override readonly [Runtime.errorExitCode] = 2;
+  override readonly [Runtime.errorReported] = false;
+}

package/src/main.ts

@@ -7,6 +7,7 @@ import { GitService } from "./services/Git.js";
 import { StackService } from "./services/Stack.js";
 import { GitHubService } from "./services/GitHub.js";
 import { OutputConfig } from "./ui.js";
+import { GlobalFlagConflictError } from "./errors/index.js";
 
 const version = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
 
@@ -25,10 +26,12 @@ const isYes = flagArgs.has("--yes") || flagArgs.has("-y");
 
 if (isNoColor) process.env["NO_COLOR"] = "1";
 
-if (isVerbose && isQuiet) {
-  process.stderr.write("Error: --verbose and --quiet are mutually exclusive\n");
-  process.exitCode = 2;
-}
+const preflight =
+  isVerbose && isQuiet
+    ? Console.error("Error: --verbose and --quiet are mutually exclusive").pipe(
+        Effect.andThen(Effect.fail(new GlobalFlagConflictError())),
+      )
+    : Effect.void;
 
 // ============================================================================
 // CLI
@@ -70,7 +73,8 @@ const handleKnownError = (e: { message: string; code?: string | undefined }) =>
 
 // @effect-diagnostics-next-line effect/strictEffectProvide:off
 BunRuntime.runMain(
-  cli.pipe(
+  preflight.pipe(
+    Effect.andThen(cli),
     Effect.provideService(OutputConfig, { verbose: isVerbose, quiet: isQuiet, yes: isYes }),
     Effect.provide(AppLayer),
     Effect.catchTags({
@@ -78,12 +82,16 @@ BunRuntime.runMain(
       StackError: (e) => handleKnownError(e),
       GitHubError: (e) => handleKnownError(e),
     }),
-    Effect.catch((e) => {
-      const msg =
-        e !== null && typeof e === "object" && "message" in e
-          ? String(e.message)
-          : JSON.stringify(e, null, 2);
-      return handleKnownError({ message: `Unexpected error: ${msg}` });
-    }),
+    Effect.catchIf(
+      (e): e is GlobalFlagConflictError => e instanceof GlobalFlagConflictError,
+      Effect.fail,
+      (e) => {
+        const msg =
+          e !== null && typeof e === "object" && "message" in e
+            ? String(e.message)
+            : JSON.stringify(e, null, 2);
+        return handleKnownError({ message: `Unexpected error: ${msg}` });
+      },
+    ),
   ),
 );

package/src/services/Git.ts

@@ -93,7 +93,12 @@ export class GitService extends ServiceMap.Service<
         ),
 
       listBranches: () =>
-        run(["branch", "--format=%(refname:short)"]).pipe(
+        run([
+          "for-each-ref",
+          "--sort=-committerdate",
+          "--format=%(refname:short)",
+          "refs/heads",
+        ]).pipe(
           Effect.map((output) =>
             output
               .split("\n")

package/src/ui.ts

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline";
 import pc from "picocolors";
-import { Effect, ServiceMap } from "effect";
+import { Config, Effect, ServiceMap } from "effect";
 
 // ============================================================================
 // TTY & Color Detection
@@ -13,24 +13,43 @@ const stdoutIsTTY = process.stdout.isTTY === true;
 let _stderrColors: ReturnType<typeof pc.createColors> | null = null;
 let _stdoutColors: ReturnType<typeof pc.createColors> | null = null;
 
-const isColorEnabled = (isTTY: boolean) => {
-  if (process.env["NO_COLOR"] !== undefined) return false;
-  if (process.env["FORCE_COLOR"] !== undefined) return true;
-  if (process.env["TERM"] === "dumb") return false;
+const colorRuntimeConfig = Config.all({
+  noColor: Config.string("NO_COLOR").pipe(
+    Config.map(() => true),
+    Config.orElse(() => Config.succeed(false)),
+  ),
+  forceColor: Config.string("FORCE_COLOR").pipe(
+    Config.map(() => true),
+    Config.orElse(() => Config.succeed(false)),
+  ),
+  term: Config.string("TERM").pipe(Config.withDefault("")),
+});
+
+const isColorEnabled = Effect.fn("ui.isColorEnabled")(function* (isTTY: boolean) {
+  const runtime = yield* colorRuntimeConfig;
+  if (runtime.noColor) return false;
+  if (runtime.forceColor) return true;
+  if (runtime.term === "dumb") return false;
   return isTTY;
-};
+});
 
-const getColors = () => {
+const getColors = Effect.fn("ui.getColors")(function* () {
   if (_stderrColors !== null) return _stderrColors;
-  _stderrColors = isColorEnabled(stderrIsTTY) ? pc : pc.createColors(false);
+  const enabled = yield* isColorEnabled(stderrIsTTY).pipe(
+    Effect.catchTag("ConfigError", () => Effect.succeed(false)),
+  );
+  _stderrColors = enabled ? pc : pc.createColors(false);
   return _stderrColors;
-};
+});
 
-const getStdoutColors = () => {
+const getStdoutColors = Effect.fn("ui.getStdoutColors")(function* () {
   if (_stdoutColors !== null) return _stdoutColors;
-  _stdoutColors = isColorEnabled(stdoutIsTTY) ? pc : pc.createColors(false);
+  const enabled = yield* isColorEnabled(stdoutIsTTY).pipe(
+    Effect.catchTag("ConfigError", () => Effect.succeed(false)),
+  );
+  _stdoutColors = enabled ? pc : pc.createColors(false);
   return _stdoutColors;
-};
+});
 
 // ============================================================================
 // Output Config (verbose/quiet, set by global flags)
@@ -84,27 +103,34 @@ const write = (msg: string) =>
 export const success = Effect.fn("ui.success")(function* (msg: string) {
   const config = yield* OutputConfig;
   if (config.quiet) return;
-  yield* write(getColors().green(`✓ ${msg}`));
+  const colors = yield* getColors();
+  yield* write(colors.green(`✓ ${msg}`));
 });
 
 export const warn = Effect.fn("ui.warn")(function* (msg: string) {
   const config = yield* OutputConfig;
   if (config.quiet) return;
-  yield* write(getColors().yellow(`⚠ ${msg}`));
+  const colors = yield* getColors();
+  yield* write(colors.yellow(`⚠ ${msg}`));
 });
 
 export const info = Effect.fn("ui.info")(function* (msg: string) {
   const config = yield* OutputConfig;
   if (config.quiet) return;
-  yield* write(getColors().cyan(msg));
+  const colors = yield* getColors();
+  yield* write(colors.cyan(msg));
 });
 
-export const error = (msg: string) => write(getColors().red(msg));
+export const error = Effect.fn("ui.error")(function* (msg: string) {
+  const colors = yield* getColors();
+  yield* write(colors.red(msg));
+});
 
 export const verbose = Effect.fn("ui.verbose")(function* (msg: string) {
   const config = yield* OutputConfig;
   if (!config.verbose) return;
-  yield* write(getColors().dim(msg));
+  const colors = yield* getColors();
+  yield* write(colors.dim(msg));
 });
 
 // ============================================================================
@@ -122,7 +148,7 @@ export const withSpinner = <A, E, R>(
   }
 
   return Effect.gen(function* () {
-    const c = getColors();
+    const c = yield* getColors();
     let frame = 0;
     const interval = setInterval(() => {
       const spinner = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
@@ -150,24 +176,72 @@ export const withSpinner = <A, E, R>(
 // Color Helpers — stderr (for tree views, status badges, etc.)
 // ============================================================================
 
-export const dim = (s: string) => getColors().dim(s);
-export const bold = (s: string) => getColors().bold(s);
-export const green = (s: string) => getColors().green(s);
-export const yellow = (s: string) => getColors().yellow(s);
-export const cyan = (s: string) => getColors().cyan(s);
-export const red = (s: string) => getColors().red(s);
-export const magenta = (s: string) => getColors().magenta(s);
+export const dim = Effect.fn("ui.dim")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.dim(s);
+});
+
+export const bold = Effect.fn("ui.bold")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.bold(s);
+});
+
+export const green = Effect.fn("ui.green")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.green(s);
+});
+
+export const yellow = Effect.fn("ui.yellow")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.yellow(s);
+});
+
+export const cyan = Effect.fn("ui.cyan")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.cyan(s);
+});
+
+export const red = Effect.fn("ui.red")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.red(s);
+});
+
+export const magenta = Effect.fn("ui.magenta")(function* (s: string) {
+  const colors = yield* getColors();
+  return colors.magenta(s);
+});
 
 // ============================================================================
 // Color Helpers — stdout (for Console.log output that may be piped)
 // ============================================================================
 
 export const stdout = {
-  dim: (s: string) => getStdoutColors().dim(s),
-  bold: (s: string) => getStdoutColors().bold(s),
-  green: (s: string) => getStdoutColors().green(s),
-  yellow: (s: string) => getStdoutColors().yellow(s),
-  cyan: (s: string) => getStdoutColors().cyan(s),
-  red: (s: string) => getStdoutColors().red(s),
-  magenta: (s: string) => getStdoutColors().magenta(s),
+  dim: Effect.fn("ui.stdout.dim")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.dim(s);
+  }),
+  bold: Effect.fn("ui.stdout.bold")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.bold(s);
+  }),
+  green: Effect.fn("ui.stdout.green")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.green(s);
+  }),
+  yellow: Effect.fn("ui.stdout.yellow")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.yellow(s);
+  }),
+  cyan: Effect.fn("ui.stdout.cyan")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.cyan(s);
+  }),
+  red: Effect.fn("ui.stdout.red")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.red(s);
+  }),
+  magenta: Effect.fn("ui.stdout.magenta")(function* (s: string) {
+    const colors = yield* getStdoutColors();
+    return colors.magenta(s);
+  }),
 };