@danieljvdm/dev-kit 0.2.0

package/src/catalog-manager.ts

@@ -0,0 +1,345 @@
+import { applyEdits, modify, parse as parseJsonc, type ParseError } from "jsonc-parser";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { Prompt } from "effect/unstable/cli";
+
+import { isInteractiveTerminal, printLine, printStatus } from "./cli-ui.ts";
+import {
+  SkillSourcesLockSchema,
+  SkillSourcesManifestSchema,
+  type ExternalSkillSource,
+  type SkillSourcesLock,
+  type SkillSourcesManifest,
+} from "./source-manifest.ts";
+import {
+  inspectCatalogRepository,
+  refreshSkillCatalog,
+  type CatalogInspection,
+} from "./vendor.ts";
+
+type CatalogPaths = {
+  readonly repoDir: string;
+  readonly sourcesPath: string;
+  readonly lockfilePath: string;
+};
+
+export type CatalogCommandOptions = {
+  readonly repoDir?: string;
+  readonly sourcesPath?: string;
+  readonly lockfilePath?: string;
+};
+
+export type CatalogAddOptions = CatalogCommandOptions & {
+  readonly repository: string;
+  readonly id?: string;
+  readonly ref?: string;
+  readonly skillsPath?: string;
+  readonly skills?: ReadonlyArray<string>;
+  readonly all?: boolean;
+  readonly licensePath?: string;
+  readonly stripFrontmatter?: ReadonlyArray<string>;
+  readonly dryRun?: boolean;
+};
+
+class CatalogManagerError extends Schema.TaggedErrorClass<CatalogManagerError>()(
+  "CatalogManagerError",
+  { message: Schema.String },
+) {}
+
+const formattingOptions = { insertSpaces: true, tabSize: 2 } as const;
+
+const resolvePaths = Effect.fn("resolveCatalogManagerPaths")(function* (
+  options: CatalogCommandOptions,
+) {
+  const path = yield* Path.Path;
+  const repoDir = path.resolve(options.repoDir ?? ".");
+  return {
+    repoDir,
+    sourcesPath: path.resolve(repoDir, options.sourcesPath ?? "skill-sources.jsonc"),
+    lockfilePath: path.resolve(repoDir, options.lockfilePath ?? "skill-sources.lock.json"),
+  } satisfies CatalogPaths;
+});
+
+const readJsonc = Effect.fn("readCatalogManagerJsonc")(function* <A>(
+  filePath: string,
+  schema: Schema.ConstraintDecoder<A>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(filePath))) {
+    return yield* new CatalogManagerError({ message: `file not found: ${filePath}` });
+  }
+  const raw = yield* fs.readFileString(filePath);
+  const errors: Array<ParseError> = [];
+  const parsed = parseJsonc(raw, errors, { allowTrailingComma: true });
+  if (errors.length > 0) {
+    return yield* new CatalogManagerError({ message: `could not parse ${filePath}` });
+  }
+  const value = yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
+    Effect.mapError((error) => new CatalogManagerError({ message: error.message })),
+  );
+  return { raw, value };
+});
+
+const readState = Effect.fn("readCatalogManagerState")(function* (
+  options: CatalogCommandOptions,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const paths = yield* resolvePaths(options);
+  const sources = yield* readJsonc(paths.sourcesPath, SkillSourcesManifestSchema);
+  const lock = (yield* fs.exists(paths.lockfilePath))
+    ? yield* readJsonc(paths.lockfilePath, SkillSourcesLockSchema)
+    : undefined;
+  return { ...paths, sources, lock };
+});
+
+const compactDescription = (description: string): string => {
+  const first = description.match(/^.*?[.!?](?:\s|$)/)?.[0]?.trim() ?? description;
+  return first.length > 90 ? `${first.slice(0, 87).trimEnd()}…` : first;
+};
+
+const selectSkills = Effect.fn("selectCatalogSkills")(function* (
+  inspection: CatalogInspection,
+  requested: ReadonlyArray<string>,
+  all: boolean,
+) {
+  const available = new Set(inspection.skills.map((skill) => skill.name));
+  const unknown = requested.filter((skill) => !available.has(skill));
+  if (unknown.length > 0) {
+    return yield* new CatalogManagerError({
+      message: `repository does not contain: ${unknown.join(", ")}`,
+    });
+  }
+  if (all) {
+    const selected = inspection.skills.map((skill) => skill.name);
+    return { include: selected, selected };
+  }
+  if (requested.length > 0) return { include: [...new Set(requested)], selected: [...new Set(requested)] };
+  if (!(yield* isInteractiveTerminal)) {
+    return yield* new CatalogManagerError({
+      message: "choose skills with --skill <name>, or pass --all",
+    });
+  }
+  const selected = yield* Prompt.multiSelect({
+    message: `Approve skills from ${inspection.id}`,
+    choices: inspection.skills.map((skill) => ({
+      title: skill.name,
+      value: skill.name,
+      ...(skill.description ? { description: compactDescription(skill.description) } : {}),
+    })),
+    min: 1,
+  });
+  return { include: selected, selected };
+});
+
+const refreshWithRollback = Effect.fn("refreshCatalogWithRollback")(function* (
+  paths: CatalogPaths,
+  previousSources: string,
+  previousLock: string | undefined,
+  updateSourceIds: ReadonlyArray<string>,
+  pinSourceIds: ReadonlyArray<string>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  yield* refreshSkillCatalog({
+    repoDir: paths.repoDir,
+    sourcesPath: paths.sourcesPath,
+    lockfilePath: paths.lockfilePath,
+    updateSourceIds,
+    pinSourceIds,
+  }).pipe(
+    Effect.catchCause((cause) =>
+      Effect.gen(function* () {
+        yield* fs.writeFileString(paths.sourcesPath, previousSources);
+        if (previousLock === undefined) {
+          yield* fs.remove(paths.lockfilePath, { force: true });
+        } else {
+          yield* fs.writeFileString(paths.lockfilePath, previousLock);
+        }
+        return yield* Effect.failCause(cause);
+      }),
+    ),
+  );
+});
+
+const writeAndRefresh = Effect.fn("writeAndRefreshCatalog")(function* (
+  state: {
+    readonly repoDir: string;
+    readonly sourcesPath: string;
+    readonly lockfilePath: string;
+    readonly sources: { readonly raw: string; readonly value: SkillSourcesManifest };
+    readonly lock: { readonly raw: string; readonly value: SkillSourcesLock } | undefined;
+  },
+  nextSources: string,
+  updateSourceIds: ReadonlyArray<string>,
+  pinSourceIds: ReadonlyArray<string> = [],
+) {
+  const fs = yield* FileSystem.FileSystem;
+  if (nextSources === state.sources.raw) {
+    yield* printStatus("info", "Catalog already contains that selection");
+    return;
+  }
+  const previousLock = state.lock?.raw;
+  yield* fs.writeFileString(state.sourcesPath, nextSources);
+  yield* refreshWithRollback(state, state.sources.raw, previousLock, updateSourceIds, pinSourceIds);
+});
+
+export const addCatalogSource = Effect.fn("addCatalogSource")(function* (
+  options: CatalogAddOptions,
+) {
+  if (options.all && (options.skills?.length ?? 0) > 0) {
+    return yield* new CatalogManagerError({ message: "use either --all or --skill, not both" });
+  }
+  const state = yield* readState(options);
+  const inspection = yield* inspectCatalogRepository({
+    repository: options.repository,
+    repoDir: state.repoDir,
+    ...(options.id ? { id: options.id } : {}),
+    ...(options.ref ? { ref: options.ref } : {}),
+    ...(options.skillsPath ? { skillsPath: options.skillsPath } : {}),
+  });
+  const selection = yield* selectSkills(
+    inspection,
+    options.skills ?? [],
+    options.all ?? false,
+  );
+  const sources = state.sources.value.sources;
+  const byId = sources.findIndex((source) => source.id === inspection.id);
+  const byRepository = sources.findIndex((source) => source.repository === inspection.repository);
+  if (byId >= 0 && sources[byId]?.repository !== inspection.repository) {
+    return yield* new CatalogManagerError({
+      message: `source id ${inspection.id} is already used by ${sources[byId]?.repository}`,
+    });
+  }
+  if (byRepository >= 0 && sources[byRepository]?.id !== inspection.id) {
+    return yield* new CatalogManagerError({
+      message: `repository is already cataloged as ${sources[byRepository]?.id}`,
+    });
+  }
+  const existingIndex = byId >= 0 ? byId : byRepository;
+  let next = state.sources.raw;
+  if (existingIndex >= 0) {
+    const existing = sources[existingIndex]!;
+    const approved = state.lock?.value.sources.find((source) => source.id === existing.id)?.skills ?? [];
+    const currentInclude = existing.include.includes("*") ? approved : existing.include;
+    const include = [...new Set([...currentInclude, ...selection.include])].sort();
+    const exclude = (existing.exclude ?? []).filter((skill) => !selection.selected.includes(skill));
+    next = applyEdits(next, modify(next, ["sources", existingIndex, "include"], include, { formattingOptions }));
+    if (exclude.length > 0 || existing.exclude !== undefined) {
+      next = applyEdits(next, modify(next, ["sources", existingIndex, "exclude"], exclude, { formattingOptions }));
+    }
+    if (existing.ref === "HEAD" && inspection.ref !== "HEAD") {
+      next = applyEdits(next, modify(next, ["sources", existingIndex, "ref"], inspection.ref, { formattingOptions }));
+    }
+  } else {
+    const source: ExternalSkillSource = {
+      id: inspection.id,
+      repository: inspection.repository,
+      ref: inspection.ref,
+      skillsPath: inspection.skillsPath,
+      include: selection.include,
+      ...(options.licensePath
+        ? { licensePath: options.licensePath }
+        : inspection.licensePath
+        ? { licensePath: inspection.licensePath }
+        : {}),
+      ...(options.stripFrontmatter?.length
+        ? { stripFrontmatter: [...new Set(options.stripFrontmatter)] }
+        : {}),
+    };
+    next = applyEdits(next, modify(next, ["sources", sources.length], source, {
+      formattingOptions,
+      isArrayInsertion: true,
+    }));
+  }
+  if (options.dryRun) {
+    yield* printStatus(
+      "plan",
+      existingIndex >= 0 ? "Would update catalog source" : "Would add catalog source",
+      `${inspection.id} · ${selection.selected.length} skill${selection.selected.length === 1 ? "" : "s"}`,
+    );
+    return;
+  }
+  yield* writeAndRefresh(state, next, [inspection.id]);
+});
+
+export const removeCatalogEntry = Effect.fn("removeCatalogEntry")(function* (
+  name: string,
+  options: CatalogCommandOptions & { readonly dryRun?: boolean; readonly yes?: boolean },
+) {
+  const state = yield* readState(options);
+  const sources = state.sources.value.sources;
+  const sourceIndex = sources.findIndex((source) => source.id === name);
+  let next = state.sources.raw;
+  let label: string;
+  let pinSourceIds: ReadonlyArray<string> = [];
+  if (sourceIndex >= 0) {
+    next = applyEdits(next, modify(next, ["sources", sourceIndex], undefined, { formattingOptions }));
+    label = `source ${name}`;
+  } else {
+    const owner = state.lock?.value.sources.find((source) => source.skills.includes(name));
+    if (!owner) return yield* new CatalogManagerError({ message: `catalog entry not found: ${name}` });
+    const index = sources.findIndex((source) => source.id === owner.id);
+    const source = sources[index];
+    if (!source) return yield* new CatalogManagerError({ message: `source not found: ${owner.id}` });
+    if (source.include.includes("*")) {
+      const exclude = [...new Set([...(source.exclude ?? []), name])];
+      next = applyEdits(next, modify(next, ["sources", index, "exclude"], exclude, { formattingOptions }));
+    } else {
+      const include = source.include.filter((skill) => skill !== name);
+      next = include.length === 0
+        ? applyEdits(next, modify(next, ["sources", index], undefined, { formattingOptions }))
+        : applyEdits(next, modify(next, ["sources", index, "include"], include, { formattingOptions }));
+    }
+    label = `skill ${name}`;
+    pinSourceIds = [owner.id];
+  }
+  if (options.dryRun) {
+    yield* printStatus("plan", "Would remove catalog entry", label);
+    return;
+  }
+  if (!options.yes) {
+    if (!(yield* isInteractiveTerminal)) {
+      return yield* new CatalogManagerError({
+        message: "catalog removal requires --yes outside a terminal",
+      });
+    }
+    const confirmed = yield* Prompt.confirm({
+      message: `Remove ${label} from the approved catalog?`,
+      initial: false,
+    });
+    if (!confirmed) {
+      yield* printStatus("info", "Cancelled");
+      return;
+    }
+  }
+  yield* writeAndRefresh(state, next, [], pinSourceIds);
+});
+
+export const listCatalogSources = Effect.fn("listCatalogSources")(function* (
+  options: CatalogCommandOptions,
+) {
+  const state = yield* readState(options);
+  if (state.sources.value.sources.length === 0) {
+    yield* printStatus("info", "Catalog has no external sources");
+    return;
+  }
+  for (const source of state.sources.value.sources) {
+    const locked = state.lock?.value.sources.find((candidate) => candidate.id === source.id);
+    yield* printLine(`${source.id}  ${source.repository}`);
+    yield* printLine(`  ${locked?.skills.length ?? 0} skills · ${locked?.resolved.slice(0, 12) ?? "not refreshed"}`);
+  }
+});
+
+export const showCatalogSource = Effect.fn("showCatalogSource")(function* (
+  id: string,
+  options: CatalogCommandOptions,
+) {
+  const state = yield* readState(options);
+  const source = state.sources.value.sources.find((candidate) => candidate.id === id);
+  if (!source) return yield* new CatalogManagerError({ message: `catalog source not found: ${id}` });
+  const locked = state.lock?.value.sources.find((candidate) => candidate.id === id);
+  yield* printLine(source.id);
+  yield* printLine(`Repository: ${source.repository}`);
+  yield* printLine(`Tracking: ${source.ref}`);
+  if (locked) yield* printLine(`Approved commit: ${locked.resolved}`);
+  yield* printLine(`Skills: ${locked?.skills.join(", ") ?? "run catalog refresh"}`);
+  if (source.exclude?.length) yield* printLine(`Excluded: ${source.exclude.join(", ")}`);
+});

package/src/catalog.ts

@@ -0,0 +1,246 @@
+import { parse as parseJsonc, type ParseError } from "jsonc-parser";
+import { Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+
+import { observePath } from "./path-digest.ts";
+import {
+  SkillSourcesLockSchema,
+  type LockedSkillSource,
+  type SkillSourcesLock,
+} from "./source-manifest.ts";
+
+export type CatalogSkill = {
+  readonly name: string;
+  readonly description: string;
+  readonly source: string;
+  readonly bundled: boolean;
+};
+
+export type SkillCatalog = {
+  readonly skills: ReadonlyArray<CatalogSkill>;
+  readonly families: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly lock?: SkillSourcesLock;
+};
+
+export type ResolvedSkillSource = {
+  readonly path: string;
+  readonly catalog?: {
+    readonly source: string;
+    readonly repository: string;
+    readonly resolved: string;
+  };
+};
+
+class CatalogError extends Schema.TaggedErrorClass<CatalogError>()("CatalogError", {
+  message: Schema.String,
+}) {}
+
+const runGit = Effect.fn("runCatalogGit")(function* (
+  cwd: string,
+  args: ReadonlyArray<string>,
+) {
+  const child = yield* ChildProcess.make("git", args, {
+    cwd,
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const [output, exitCode] = yield* Effect.all([
+    Stream.mkString(Stream.decodeText(child.all)),
+    child.exitCode,
+  ]);
+  if (exitCode !== 0) {
+    return yield* new CatalogError({
+      message: `git ${args.join(" ")} failed: ${output.trim()}`,
+    });
+  }
+  return output.trim();
+});
+
+const readCatalogLock = Effect.fn("readCatalogLock")(function* (packageRoot: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const lockPath = path.join(packageRoot, "skill-sources.lock.json");
+  if (!(yield* fs.exists(lockPath))) return undefined;
+  const raw = yield* fs.readFileString(lockPath);
+  const errors: Array<ParseError> = [];
+  const value = parseJsonc(raw, errors, { allowTrailingComma: true });
+  if (errors.length > 0) {
+    return yield* new CatalogError({ message: `invalid skill catalog lock: ${lockPath}` });
+  }
+  return yield* Schema.decodeUnknownEffect(SkillSourcesLockSchema)(value).pipe(
+    Effect.mapError((error) => new CatalogError({ message: error.message })),
+  );
+});
+
+const readDescription = Effect.fn("readSkillDescription")(function* (skillPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const text = yield* fs.readFileString(path.join(skillPath, "SKILL.md"));
+  return text
+    .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1]
+    ?.split(/\r?\n/)
+    .find((line) => line.startsWith("description:"))
+    ?.slice("description:".length)
+    .trim()
+    .replace(/^(['"])(.*)\1$/, "$2") ?? "";
+});
+
+export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
+  packageRoot: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const skillsDir = path.join(packageRoot, "skills");
+  const skills: Array<CatalogSkill> = [];
+  if (yield* fs.exists(skillsDir)) {
+    for (const name of (yield* fs.readDirectory(skillsDir)).sort()) {
+      const skillPath = path.join(skillsDir, name);
+      if ((yield* fs.exists(path.join(skillPath, "SKILL.md")))) {
+        skills.push({
+          name,
+          description: yield* readDescription(skillPath),
+          source: "built-in",
+          bundled: true,
+        });
+      }
+    }
+  }
+  const lock = yield* readCatalogLock(packageRoot);
+  for (const source of lock?.sources ?? []) {
+    for (const name of source.skills) {
+      skills.push({
+        name,
+        description: source.descriptions?.[name] ?? "",
+        source: source.id,
+        bundled: false,
+      });
+    }
+  }
+  const duplicates = skills.filter(
+    (skill, index) => skills.findIndex((candidate) => candidate.name === skill.name) !== index,
+  );
+  if (duplicates.length > 0) {
+    return yield* new CatalogError({
+      message: `duplicate catalog skill: ${duplicates[0]?.name ?? "unknown"}`,
+    });
+  }
+  const families: Readonly<Record<string, ReadonlyArray<string>>> = {
+    effect: ["effect-ts"],
+    ...Object.fromEntries(
+      (lock?.sources ?? []).map((source) => [source.id, source.skills]),
+    ),
+  };
+  return {
+    skills: skills.sort((left, right) => left.name.localeCompare(right.name)),
+    families,
+    ...(lock ? { lock } : {}),
+  } satisfies SkillCatalog;
+});
+
+const stripFrontmatterKeys = (text: string, keys: ReadonlyArray<string>): string => {
+  if (keys.length === 0) return text;
+  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!frontmatter?.[1]) return text;
+  const stripped = new Set(keys);
+  let skipping = false;
+  const lines = frontmatter[1].split(/\r?\n/).filter((line) => {
+    const key = line.match(/^([A-Za-z0-9_-]+):/)?.[1];
+    if (key) skipping = stripped.has(key);
+    return !skipping;
+  });
+  return `---\n${lines.join("\n")}\n---${frontmatter[2]}${text.slice(frontmatter[0].length)}`;
+};
+
+const materializeSource = Effect.fn("materializeCatalogSource")(function* (
+  projectDir: string,
+  source: LockedSkillSource,
+  selected: ReadonlyArray<string>,
+  cache: boolean,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const root = cache
+    ? path.join(projectDir, ".dev-kit", "cache", "catalog", source.id, source.resolved)
+    : path.join(
+        yield* fs.makeTempDirectoryScoped({ prefix: "dev-kit-catalog-plan-" }),
+        source.id,
+        source.resolved,
+      );
+  const checkout = path.join(root, "checkout");
+  const ready = path.join(root, ".ready");
+  if (!(yield* fs.exists(ready))) {
+    yield* fs.remove(root, { force: true, recursive: true });
+    yield* fs.makeDirectory(checkout, { recursive: true });
+    yield* runGit(checkout, ["init", "--quiet"]);
+    yield* runGit(checkout, ["remote", "add", "origin", source.repository]);
+    yield* runGit(checkout, ["fetch", "--quiet", "--depth", "1", "origin", source.resolved]);
+    yield* runGit(checkout, ["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
+    const actual = yield* runGit(checkout, ["rev-parse", "HEAD"]);
+    if (actual !== source.resolved) {
+      return yield* new CatalogError({ message: `source ${source.id} resolved to ${actual}, expected ${source.resolved}` });
+    }
+    const symlinks = yield* runGit(checkout, ["ls-files", "--stage", "--", source.skillsPath]);
+    if (symlinks.split(/\r?\n/).some((line) => line.startsWith("120000 "))) {
+      return yield* new CatalogError({ message: `source ${source.id} contains symlinks; refusing to install it` });
+    }
+    for (const skill of source.skills) {
+      const from = path.join(checkout, source.skillsPath, skill);
+      const to = path.join(root, "skills", skill);
+      const observation = yield* observePath(from);
+      if (observation.kind !== "directory") {
+        return yield* new CatalogError({ message: `source ${source.id} is missing skill ${skill}` });
+      }
+      yield* fs.copy(from, to, { overwrite: true });
+      if (source.stripFrontmatter?.length) {
+        const document = path.join(to, "SKILL.md");
+        yield* fs.writeFileString(
+          document,
+          stripFrontmatterKeys(yield* fs.readFileString(document), source.stripFrontmatter),
+        );
+      }
+    }
+    yield* fs.writeFileString(ready, `${source.resolved}\n`);
+  }
+  for (const skill of selected) {
+    const observation = yield* observePath(path.join(root, "skills", skill));
+    const approvedDigest = source.digests?.[skill];
+    if (approvedDigest !== undefined &&
+      (observation.kind !== "directory" || observation.digest !== approvedDigest)) {
+      return yield* new CatalogError({
+        message: `cached skill ${skill} does not match the approved catalog; remove ${root} and retry`,
+      });
+    }
+  }
+  return new Map(selected.map((skill) => [skill, {
+    path: path.join(root, "skills", skill),
+    catalog: {
+      source: source.id,
+      repository: source.repository,
+      resolved: source.resolved,
+    },
+  } satisfies ResolvedSkillSource]));
+});
+
+export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
+  packageRoot: string,
+  projectDir: string,
+  selected: ReadonlyArray<string>,
+  cache = true,
+) {
+  const path = yield* Path.Path;
+  const catalog = yield* loadSkillCatalog(packageRoot);
+  const sources = new Map<string, ResolvedSkillSource>();
+  for (const skill of catalog.skills.filter((skill) => skill.bundled)) {
+    if (selected.includes(skill.name)) {
+      sources.set(skill.name, { path: path.join(packageRoot, "skills", skill.name) });
+    }
+  }
+  for (const source of catalog.lock?.sources ?? []) {
+    const wanted = source.skills.filter((skill) => selected.includes(skill));
+    if (wanted.length === 0) continue;
+    for (const [name, sourcePath] of yield* materializeSource(projectDir, source, wanted, cache)) {
+      sources.set(name, sourcePath);
+    }
+  }
+  return sources;
+});

package/src/cli-ui.ts

@@ -0,0 +1,110 @@
+import { Config, Console, Effect, Option, Terminal } from "effect";
+
+const ANSI = {
+  clearLine: "\r\u001b[2K",
+  cyan: "\u001b[36m",
+  dim: "\u001b[2m",
+  green: "\u001b[32m",
+  red: "\u001b[31m",
+  reset: "\u001b[0m",
+  yellow: "\u001b[33m",
+} as const;
+
+type StatusKind = "success" | "info" | "plan" | "error";
+
+const statusAppearance: Readonly<Record<StatusKind, readonly [string, string]>> = {
+  success: ["✓", ANSI.green],
+  info: ["•", ANSI.cyan],
+  plan: ["→", ANSI.yellow],
+  error: ["✗", ANSI.red],
+};
+
+const terminalCapabilities = Effect.fn("terminalCapabilities")(function* () {
+  const terminal = yield* Terminal.Terminal;
+  const columns = yield* terminal.columns;
+  const noColor = yield* Config.string("NO_COLOR").pipe(Config.option, Effect.orDie);
+  const term = yield* Config.string("TERM").pipe(Config.withDefault(""), Effect.orDie);
+  const ci = yield* Config.string("CI").pipe(Config.withDefault(""), Effect.orDie);
+  const interactive = columns > 0 && term !== "dumb" && ci !== "true" && ci !== "1";
+  return {
+    color: interactive && Option.isNone(noColor),
+    interactive,
+    terminal,
+  };
+});
+
+export const isInteractiveTerminal = terminalCapabilities().pipe(
+  Effect.map((capabilities) => capabilities.interactive),
+);
+
+const formatDetail = (detail: string | undefined, color: boolean): string =>
+  detail === undefined || detail.length === 0
+    ? ""
+    : color
+    ? ` ${ANSI.dim}${detail}${ANSI.reset}`
+    : ` ${detail}`;
+
+export const printStatus = Effect.fn("printCliStatus")(function* (
+  kind: StatusKind,
+  label: string,
+  detail?: string,
+) {
+  const capabilities = yield* terminalCapabilities();
+  const [symbol, color] = statusAppearance[kind];
+  const prefix = capabilities.color ? `${color}${symbol}${ANSI.reset}` : symbol;
+  yield* capabilities.terminal.display(
+    `${prefix} ${label}${formatDetail(detail, capabilities.color)}\n`,
+  ).pipe(Effect.orDie);
+});
+
+export const printDetail = Effect.fn("printCliDetail")(function* (text: string) {
+  const capabilities = yield* terminalCapabilities();
+  yield* capabilities.terminal.display(
+    capabilities.color
+      ? `  ${ANSI.dim}${text}${ANSI.reset}\n`
+      : `  ${text}\n`,
+  ).pipe(Effect.orDie);
+});
+
+export const printLine = Effect.fn("printCliLine")(function* (text = "") {
+  const capabilities = yield* terminalCapabilities();
+  yield* capabilities.terminal.display(`${text}\n`).pipe(Effect.orDie);
+});
+
+export const withSpinner = <A, E, R>(
+  label: string,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R | Terminal.Terminal> =>
+  Effect.gen(function* () {
+    const capabilities = yield* terminalCapabilities();
+    if (!capabilities.interactive) return yield* effect;
+
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let index = 0;
+    const animate = Effect.forever(
+      Effect.suspend(() => {
+        const frame = frames[index++ % frames.length];
+        const symbol = capabilities.color
+          ? `${ANSI.cyan}${frame}${ANSI.reset}`
+          : frame;
+        return capabilities.terminal.display(
+          `${ANSI.clearLine}${symbol} ${label}`,
+        ).pipe(Effect.orDie, Effect.andThen(Effect.sleep("80 millis")));
+      }),
+    );
+    const fiber = yield* Effect.forkChild(animate);
+    return yield* effect.pipe(
+      Effect.ensuring(
+        Effect.sync(() => fiber.interruptUnsafe()).pipe(
+          Effect.andThen(capabilities.terminal.display(ANSI.clearLine).pipe(Effect.orDie)),
+        ),
+      ),
+    );
+  });
+
+export const printError = Effect.fn("printCliError")(function* (message: string) {
+  const capabilities = yield* terminalCapabilities();
+  const [symbol, color] = statusAppearance.error;
+  const prefix = capabilities.color ? `${color}${symbol}${ANSI.reset}` : symbol;
+  yield* Console.error(`${prefix} ${message}`);
+});