@savvy-web/cli 3.5.0 → 3.6.0

package/commands/repos/shared.js

@@ -0,0 +1,129 @@
+import { Report } from "../../internal/report.js";
+import { FailureLine } from "../../internal/failure-line.js";
+import { CommandError } from "../../internal/command-error.js";
+import { CliError } from "effect/cli";
+import { CliInteractive } from "@effected/cli";
+import { Repos } from "@savvy-web/silk-effects";
+import { Effect } from "effect";
+import { CliUi, MultiSelect, Select, TextInput } from "@effected/cli/ui";
+
+//#region src/commands/repos/shared.ts
+/** What a person can do about each repos failure. */
+const hints = {
+	ReposConfigError: "fix .repos/config.json (it is versioned: git diff / git checkout it), then run `savvy repos status`",
+	GitSubmoduleError: "run `savvy repos status --drift` to see what git disagrees with, then `savvy repos sync` to repair",
+	RepoNotFoundError: "run `savvy repos status` to list the vendored repos",
+	NoteNotFoundError: "the note ids are under the repo's `notes` in .repos/config.json",
+	ReposLockdownError: "run `savvy repos sync` to re-assert the read-only lockdown on the vendored trees"
+};
+/**
+* Helpers shared by the `savvy repos` subcommands.
+*
+* @internal
+*/
+var ReposCli = class ReposCli {
+	constructor() {}
+	/** The line every mutating repos command prints, exit 0, when there is no manifest yet. */
+	static nothingVendored = Report.print([Report.skip("no .repos/config.json — nothing vendored")]);
+	/**
+	* `error` as the {@link CommandError} a command fails with: `could not <action>`,
+	* the error's own description (a git failure's lines kept apart), and a hint
+	* for its kind. `hint` overrides the kind's own.
+	*/
+	static toCommandError = (action, error, hint) => new CommandError({
+		message: `could not ${action}`,
+		detail: FailureLine.describe(error).split("\n"),
+		hint: hint ?? hints[error._tag],
+		cause: error
+	});
+	/** Fail with {@link ReposCli.toCommandError}; for `Effect.catchTags`/`catchTag` arms. */
+	static fail = (action, hint) => (error) => Effect.fail(ReposCli.toCommandError(action, error, hint));
+	/**
+	* A missing required positional exactly as core's parser reports one: a
+	* `ShowHelp` carrying `MissingArgument`, which `Command.runWith` renders as
+	* the error followed by the subcommand's help (on stderr under
+	* `helpOnUsageError: "stderr"`) and `CliRuntime.main` exits `64` on.
+	*
+	* @param command - The path below `savvy repos`, e.g. `["pin"]` or `["note", "add"]`.
+	*/
+	static missingArgument = (command, argument) => new CliError.ShowHelp({
+		commandPath: [
+			"savvy",
+			"repos",
+			...command
+		],
+		errors: [new CliError.MissingArgument({ argument })]
+	});
+	/**
+	* The vendored repos (name, ref, and whether dirty), read from
+	* `ReposManager.status` for a picker.
+	*/
+	static vendored = (cwd) => Effect.gen(function* () {
+		return (yield* (yield* Repos.ReposManager).status(cwd)).repos;
+	});
+	/**
+	* The repo name a command was given, or — when it was left off — one picked
+	* from the vendored repos on a `Select` when a person is at the terminal.
+	*
+	* @remarks
+	* Not interactive (an agent, CI, a pipe), a missing name stays what it was
+	* when the argument was required: a usage error, exit `64`, and the manifest
+	* is never read. With nothing vendored there is nothing to pick from, which
+	* is also the usage error. Esc on the picker is the kit's `Cancelled` (exit
+	* `130`).
+	*/
+	static nameOrPick = (cwd, given, options) => Effect.gen(function* () {
+		if (given !== void 0) return given;
+		if (!(yield* CliInteractive)) return yield* Effect.fail(ReposCli.missingArgument(options.command, options.argument));
+		const repos = yield* ReposCli.vendored(cwd);
+		if (repos.length === 0) return yield* Effect.fail(ReposCli.missingArgument(options.command, options.argument));
+		return yield* CliUi.prompt(Select.screen({
+			message: options.message,
+			choices: repos.map((repo) => ({
+				label: repo.name,
+				value: repo.name,
+				detail: `@ ${repo.ref}`
+			}))
+		})).pipe(Effect.catchTag("NotInteractive", () => Effect.fail(ReposCli.missingArgument(options.command, options.argument))));
+	});
+	/**
+	* A positional the command was given, or — when it was left off at a
+	* terminal — typed on a `TextInput`; a usage error anywhere else.
+	*
+	* @remarks
+	* For the positional that follows an optional repo name (`pin <name> <ref>`):
+	* core binds a lone argument to the first optional positional, so once the
+	* name is optional the one after it must be optional too, and asked for here.
+	*/
+	static textOrAsk = (given, options) => Effect.gen(function* () {
+		if (given !== void 0) return given;
+		if (!(yield* CliInteractive)) return yield* Effect.fail(ReposCli.missingArgument(options.command, options.argument));
+		return yield* CliUi.prompt(TextInput.screen({
+			message: options.message,
+			...options.initial === void 0 ? {} : { initial: options.initial },
+			validate: (value) => value.trim() === "" ? `${options.argument} is required` : void 0
+		})).pipe(Effect.map((value) => value.trim()), Effect.catchTag("NotInteractive", () => Effect.fail(ReposCli.missingArgument(options.command, options.argument))));
+	});
+	/**
+	* Which dirty repos to restore, asked on a `MultiSelect` with every dirty
+	* repo preselected. Only called when a person is at the terminal.
+	*/
+	static pickDirty = (names) => {
+		const items = names.map((name) => ({
+			key: name,
+			label: name,
+			value: name,
+			selected: true
+		}));
+		return CliUi.prompt(MultiSelect.screen({
+			message: "Restore which repos? (uncommitted edits are lost)",
+			sections: [{
+				title: "dirty",
+				items
+			}]
+		}), { otherwise: names }).pipe(Effect.catchTag("NotInteractive", () => Effect.succeed(names)));
+	};
+};
+
+//#endregion
+export { ReposCli };

package/index.d.ts

@@ -1,37 +1,130 @@
-import { CliExit } from "@effected/cli";
+import { Block, Cancelled, CliDoc, CliDocSource, CliExit, CliLinks, CliTheme, Document } from "@effected/cli";
 import { BiomeSchemaSync, ChangesetConfigReader, Changesets, ConfigDiscovery, Repos } from "@savvy-web/silk-effects";
-import { Cause, Effect, FileSystem, Path, Stdio } from "effect";
-import { Command } from "effect/cli";
+import { Cause, Effect, FileSystem, Path } from "effect";
+import { CliError, Command } from "effect/cli";
 import { ChildProcessSpawner } from "effect/process";
+import { Audience, TerminalEnv } from "@effected/env";
 import { Git } from "@effected/git";
 import { PublishabilityDetector, WorkspaceDiscovery, WorkspaceRoot } from "@effected/workspaces";
 import { ManagedSection, SectionFileError, SectionParseError, SectionRenderError } from "@effected/templates";
 import { PlatformError } from "effect/PlatformError";
 import { ToolDiscovery } from "@effected/commands";
-import { JsoncParseError } from "@effected/jsonc";
-//#region src/commands/changeset/commands/check.d.ts
+import { JsoncModificationError, JsoncParseError } from "@effected/jsonc";
+//#region src/internal/command-error.d.ts
+/** What {@link CommandError} carries besides its tag. */
+interface CommandErrorFields {
+  /** One line saying what failed, e.g. `could not read .changeset/config.json`. */
+  readonly message: string;
+  /** Supporting lines under the message: what was found, which files, the underlying error. */
+  readonly detail?: ReadonlyArray<string> | undefined;
+  /** What to do about it, drawn as a tip callout. */
+  readonly hint?: string | undefined;
+  /** The error this one stands for, kept as `Error.cause` for diagnostics; never drawn. */
+  readonly cause?: unknown;
+}
+/** Options for {@link CommandError.from}. */
+interface CommandErrorFromOptions {
+  /** One line saying what failed, in the command's words. */
+  readonly message: string;
+  /** Lines drawn before the foreign error's own description. */
+  readonly detail?: ReadonlyArray<string> | undefined;
+  /** What to do about it. */
+  readonly hint?: string | undefined;
+}
+declare const CommandError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "CommandError";
+} & Readonly<A>;
+/**
+ * A command's failure that draws itself: a failure status line, indented
+ * detail lines, and an optional remediation as a tip callout.
+ *
+ * @remarks
+ * Replaces the `Effect.logError(...)` + `CliExit.set(1)` pair: fail with it
+ * and `CliRuntime.main` reports it on stderr through `FailureLine.render`,
+ * which hands an error implementing `CliDoc` the kit's report of its
+ * document, rendered for the run's audience (ANSI for a person, plain for an
+ * agent, a GitHub Actions log under Actions). It is a typed failure, so the
+ * run exits `1`. A finding (a lint problem, a dirty repo) is still output
+ * plus `CliExit.set(1)`, never this.
+ *
+ * Map a silk-effects error at the command edge with
+ * {@link CommandError.from}, inside the handler's `catchTag`s.
+ *
+ * @example
+ * ```ts
+ * Effect.catchTag("ChangesetConfigError", (error) =>
+ *   Effect.fail(CommandError.from(error, { message: "could not read the changeset config", hint: "run savvy init" })),
+ * )
+ * ```
+ *
+ * @internal
+ */
+declare class CommandError extends CommandError_base<CommandErrorFields> implements CliDocSource {
+  /** Wrap a foreign (silk-effects, kit) error: its own description becomes the last detail line, and it is kept as `cause`. */
+  static readonly from: (error: unknown, options: CommandErrorFromOptions) => CommandError;
+  [CliDoc](): Document;
+}
+//#endregion
+//#region src/internal/report.d.ts
+/** What {@link Report.print} reads to pick a renderer: the audience, the terminal, the theme and editor links. */
+type ReportEnv = CliTheme | TerminalEnv | Audience | CliLinks;
+//#endregion
+//#region src/commands/check-section.d.ts
+/**
+ * A tool's verdict: `failure` when it found a misconfiguration (exit 1),
+ * `warning` when it only has advice, `success` otherwise.
+ */
+type CheckVerdict = "success" | "warning" | "failure";
 /**
- * Run the check validation pipeline on all changeset files in `dir`.
+ * One tool's check, as blocks the caller places: `savvy check` folds each into
+ * a collapsible (a `::group::` under GitHub Actions); a standalone run prints
+ * the title as a heading over the blocks.
  *
- * Groups lint messages by file and logs a human-readable summary. Sets
- * exit code 1 through `CliExit.set` when one or more errors are found.
+ * @internal
+ */
+interface CheckSection {
+  /** The section title, e.g. `commitlint`. */
+  readonly title: string;
+  /** The section body. */
+  readonly blocks: ReadonlyArray<Block>;
+  /** The tool's verdict. */
+  readonly verdict: CheckVerdict;
+  /** Whether `savvy init` is the remediation for what was found. */
+  readonly fixedByInit: boolean;
+}
+//#endregion
+//#region src/commands/changeset/commands/check.d.ts
+/**
+ * Run the check validation pipeline on all changeset files in `dir` and
+ * print {@link changesetCheckSection}'s blocks (no title heading: the
+ * standalone `savvy changeset check` output). Sets exit code 1 through
+ * `CliExit.set` when one or more errors are found.
  *
  * @param dir - Path to the changeset directory (resolved relative to cwd)
- * @returns An Effect that performs validation and logs results
+ * @returns An Effect that performs validation and prints the report
  *
  * @internal
  */
-export declare function runChangesetCheck(dir: string): Effect.Effect<void, Error, CliExit | Stdio.Stdio>;
+export declare function runChangesetCheck(dir: string): Effect.Effect<void, Error, CliExit | ReportEnv>;
 //#endregion
 //#region src/commands/changeset/commands/init.d.ts
 /**
- * Run the full init pipeline.
+ * Run the changeset init as one step of the orchestrated `savvy init`: a
+ * failure is reported, not propagated, so the commit and lint steps still
+ * run.
  *
- * Exported so Task B5's unified `savvy init` orchestrator can invoke the
- * changeset init step directly without going through the CLI command layer.
+ * @remarks
+ * Runs {@link runChangesetInitOrFail}. Its {@link CommandError} is drawn on
+ * stderr exactly as the runtime draws a failure (its `CliDoc` document,
+ * rendered for the audience; never wrapped off a terminal), exit code 1 is
+ * set through `CliExit.set`, and the step succeeds. A caller that wants the
+ * failure to end the run calls {@link runChangesetInitOrFail} instead.
+ *
+ * Exported so the unified `savvy init` orchestrator can invoke the changeset
+ * init step directly without going through the CLI command layer.
  *
  * @param opts - The same options the CLI command receives
- * @returns An Effect that performs initialization
+ * @returns An Effect that never fails
  *
  * @internal
  */
@@ -40,7 +133,7 @@ export declare function runChangesetInit(opts: {
   quiet: boolean;
   skipMarkdownlint: boolean;
   check: boolean;
-}): Effect.Effect<void, never, WorkspaceRoot | Git | CliExit | Stdio.Stdio>;
+}): Effect.Effect<void, never, WorkspaceRoot | Git | CliExit | ReportEnv>;
 //#endregion
 //#region src/commands/changeset/index.d.ts
 /**
@@ -58,26 +151,29 @@ export declare function runChangesetInit(opts: {
  * `Command.withSubcommands` propagates each subcommand's requirements up into
  * the group's `R`, which the root assembly discharges via `AppLive`.
  */
-export declare const changesetCommand: Command.Command<"changeset", Record<string, never>, Record<string, never>, Changesets.ConfigurationError | Error | Changesets.ReleasePlanError | Cause.UnknownError | Changesets.DepsRegenPlanError, ChildProcessSpawner.ChildProcessSpawner | Changesets.ConfigInspector | FileSystem.FileSystem | Path.Path | Changesets.ReleasePlanner | CliExit | Stdio.Stdio>;
+export declare const changesetCommand: Command.Command<"changeset", Record<string, never>, Record<string, never>, CommandError | Error | Changesets.ReleasePlanError | Cause.UnknownError | Changesets.DepsRegenPlanError, ChildProcessSpawner.ChildProcessSpawner | Changesets.ConfigInspector | FileSystem.FileSystem | Path.Path | Changesets.ReleasePlanner | CliExit | ReportEnv>;
 //#endregion
 //#region src/commands/check.d.ts
 /**
- * Run all three check step Effects without short-circuiting.
- *
- * All three checks always run, sequentially (concurrency 1) so per-tool
- * output stays grouped. If any fail, the combined Effect fails with all
- * accumulated errors. Uses `Effect.all` with `{ concurrency: 1, mode: "validate" }`
- * to collect every failure rather than stopping at the first.
+ * Run the three checks without short-circuiting and print them as one
+ * document.
  *
- * @param steps - The three step Effects to run. Injected for testability.
- * @returns An Effect that resolves to `void` on success, or fails with the
- *   union of all failing steps' errors.
+ * @remarks
+ * Each step builds a {@link CheckSection}; each section is folded into a
+ * collapsible (a `::group::` under GitHub Actions, whose body is where a
+ * section's annotations are written, so its blocks are never nested deeper).
+ * A step that fails still lets the others run and report; the first failure
+ * is re-raised after the document is printed.
+ *
+ * @param steps - The three step Effects. Injected for testability.
+ * @returns An Effect that prints the report and sets exit code 1 on any
+ *   finding, or fails with the first failing step's error.
  */
 export declare function runCheck<EChangeset, RChangeset, ECommit, RCommit, ELint, RLint>(steps: {
-  changeset: Effect.Effect<unknown, EChangeset, RChangeset>;
-  commit: Effect.Effect<unknown, ECommit, RCommit>;
-  lint: Effect.Effect<unknown, ELint, RLint>;
-}): Effect.Effect<void, EChangeset | ECommit | ELint, RChangeset | RCommit | RLint>;
+  changeset: Effect.Effect<CheckSection, EChangeset, RChangeset>;
+  commit: Effect.Effect<CheckSection, ECommit, RCommit>;
+  lint: Effect.Effect<CheckSection, ELint, RLint>;
+}): Effect.Effect<void, EChangeset | ECommit | ELint, RChangeset | RCommit | RLint | CliExit | ReportEnv>;
 /**
  * The `savvy check` command for use in the Task B7 root assembly.
  *
@@ -89,20 +185,20 @@ export declare function runCheck<EChangeset, RChangeset, ECommit, RCommit, ELint
 export declare const checkCommand: Command.Command<"check", {
   readonly changesetDir: string;
   readonly quiet: boolean;
-}, {}, Error | import("@effected/jsonc").JsoncParseError | import("effect/PlatformError").PlatformError | import("@effected/templates").SectionFileError | import("@effected/templates").SectionParseError, import("@savvy-web/silk-effects").ChangesetConfigReader | import("@effected/cli").CliExit | import("@savvy-web/silk-effects").ConfigDiscovery | import("effect/FileSystem").FileSystem | import("@effected/templates").ManagedSection | import("@effected/workspaces").PublishabilityDetector | import("effect/Stdio").Stdio | import("@effected/commands").ToolDiscovery | import("@effected/workspaces").WorkspaceDiscovery>;
+}, {}, Error | import("@effected/jsonc").JsoncParseError | import("effect/PlatformError").PlatformError | import("@effected/templates").SectionFileError | import("@effected/templates").SectionParseError, import("@effected/env").Audience | import("@savvy-web/silk-effects").ChangesetConfigReader | CliExit | import("@effected/cli").CliLinks | import("@effected/cli").CliTheme | import("@savvy-web/silk-effects").ConfigDiscovery | import("effect/FileSystem").FileSystem | import("@effected/templates").ManagedSection | import("@effected/workspaces").PublishabilityDetector | import("@effected/env").TerminalEnv | import("@effected/commands").ToolDiscovery | import("@effected/workspaces").WorkspaceDiscovery>;
 //#endregion
 //#region src/commands/commit/check.d.ts
+/** What {@link commitCheckSection} needs from the environment. */
+type CommitCheckRequirements = ManagedSection | FileSystem.FileSystem | ChangesetConfigReader | PublishabilityDetector | WorkspaceDiscovery;
 /**
- * Run the check validation pipeline.
+ * Check the commitlint setup, print its report on stdout, and set exit code 1
+ * when it found a misconfiguration (see {@link commitCheckSection}).
  *
- * Exported so Task B6's unified `savvy check` orchestrator can invoke the
- * commitlint check step directly without going through the CLI command layer.
- *
- * @returns An Effect that performs validation and logs results
+ * @returns An Effect that performs validation and prints its report
  *
  * @internal
  */
-export declare function runCommitCheck(): Effect.Effect<void, SectionParseError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | ChangesetConfigReader | PublishabilityDetector | WorkspaceDiscovery | Stdio.Stdio>;
+export declare function runCommitCheck(): Effect.Effect<void, SectionParseError | SectionFileError | PlatformError, CommitCheckRequirements | ReportEnv | CliExit>;
 //#endregion
 //#region src/commands/commit/init.d.ts
 /**
@@ -119,7 +215,7 @@ export declare function runCommitCheck(): Effect.Effect<void, SectionParseError
 export declare function runCommitInit(opts: {
   force: boolean;
   config: string;
-}): Effect.Effect<void, Error | SectionParseError | SectionRenderError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | Stdio.Stdio>;
+}): Effect.Effect<void, CommandError | SectionParseError | SectionRenderError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | ReportEnv>;
 //#endregion
 //#region src/commands/commit/index.d.ts
 /**
@@ -130,9 +226,11 @@ export declare function runCommitInit(opts: {
  * errors from Effect's internal types. Task B7 should import and use this directly
  * as `Command.withSubcommands([commitCommand])` — the cast is for declaration emit only.
  */
-export declare const commitCommand: Command.Command<"commit", {}, {}, import("effect/cli/CliError").UserError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("@effected/git").Git | import("effect/Stdio").Stdio>;
+export declare const commitCommand: Command.Command<"commit", {}, {}, import("effect/cli/CliError").UserError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("@effected/git").Git | ReportEnv>;
 //#endregion
 //#region src/commands/init.d.ts
+/** The lint-staged presets `--lint-preset` accepts. */
+type LintPreset = "minimal" | "standard" | "silk";
 /**
  * Run the three init step Effects in order: changeset → commit → lint.
  *
@@ -158,26 +256,28 @@ export declare function runInit<EChangeset, RChangeset, ECommit, RCommit, ELint,
  */
 export declare const initCommand: Command.Command<"init", {
   readonly force: boolean;
+  readonly yes: boolean;
   readonly commitConfig: string;
   readonly lintConfig: string;
-  readonly lintPreset: "minimal" | "silk" | "standard";
-}, {}, Error | import("effect/PlatformError").PlatformError | import("@effected/templates").SectionFileError | import("@effected/templates").SectionParseError | import("@effected/templates").SectionRenderError, import("@savvy-web/silk-effects").BiomeSchemaSync | import("@effected/cli").CliExit | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@effected/templates").ManagedSection | import("effect/Stdio").Stdio | import("@effected/workspaces").WorkspaceDiscovery | import("@effected/workspaces").WorkspaceRoot>;
+  readonly lintPreset: LintPreset;
+}, {}, Cancelled | CommandError, import("@savvy-web/silk-effects").BiomeSchemaSync | import("@effected/cli").CliExit | FileSystem.FileSystem | import("@effected/git").Git | import("@effected/templates").ManagedSection | import("@effected/workspaces").WorkspaceDiscovery | import("@effected/workspaces").WorkspaceRoot | ReportEnv>;
 //#endregion
 //#region src/commands/lint/check.d.ts
+/** What {@link lintCheckSection} needs from the environment. */
+type LintCheckRequirements = ManagedSection | FileSystem.FileSystem | ToolDiscovery | ConfigDiscovery;
 /**
- * Run the lint check validation pipeline.
- *
- * Exported so Task B6's unified `savvy check` orchestrator can invoke the
- * lint check step directly without going through the CLI command layer.
+ * Check the lint-staged setup, print its report on stdout, and set exit code
+ * 1 when it found a misconfiguration (see {@link lintCheckSection} for the
+ * severity rule). Under `quiet` only the warnings are printed.
  *
  * @param opts - Options for the check command
- * @returns An Effect that performs validation and logs results
+ * @returns An Effect that performs validation and prints its report
  *
  * @internal
  */
 export declare function runLintCheck(opts: {
   quiet: boolean;
-}): Effect.Effect<void, JsoncParseError | SectionParseError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | ToolDiscovery | ConfigDiscovery | Stdio.Stdio>;
+}): Effect.Effect<void, JsoncParseError | SectionParseError | SectionFileError | PlatformError, LintCheckRequirements | ReportEnv | CliExit>;
 //#endregion
 //#region src/commands/lint/init.d.ts
 /**
@@ -186,6 +286,10 @@ export declare function runLintCheck(opts: {
  * Exported so Task B5's unified `savvy init` orchestrator can invoke the
  * lint-staged init step directly without going through the CLI command layer.
  *
+ * @remarks
+ * Prints a `lint-staged` report section on stdout, one step at a time as each
+ * completes, so a later step's failure still leaves what was written on screen.
+ *
  * @param opts - The same options the CLI command receives
  * @returns An Effect that performs initialization
  *
@@ -195,7 +299,7 @@ export declare function runLintInit(opts: {
   force: boolean;
   config: string;
   preset: "minimal" | "standard" | "silk";
-}): Effect.Effect<void, Error | SectionParseError | SectionRenderError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | BiomeSchemaSync | WorkspaceDiscovery | Stdio.Stdio>;
+}): Effect.Effect<void, CommandError | JsoncParseError | JsoncModificationError | SectionParseError | SectionRenderError | SectionFileError | PlatformError, ManagedSection | FileSystem.FileSystem | BiomeSchemaSync | WorkspaceDiscovery | ReportEnv>;
 //#endregion
 //#region src/commands/lint/index.d.ts
 /**
@@ -206,7 +310,7 @@ export declare function runLintInit(opts: {
  * errors from Effect's internal types. Task B7 should import and use this directly
  * as `Command.withSubcommands([lintCommand])` — the cast is for declaration emit only.
  */
-export declare const lintCommand: Command.Command<"lint", {}, {}, import("@effected/git").GitCommandError | import("@effected/git").NotARepositoryError | import("effect/PlatformError").PlatformError | import("@effected/git").UnknownRefError | import("@effected/yaml").YamlParseError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("@effected/cli").CliExit | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("effect/Path").Path | import("effect/Stdio").Stdio>;
+export declare const lintCommand: Command.Command<"lint", {}, {}, import("@effected/git").GitCommandError | import("@effected/git").NotARepositoryError | import("effect/PlatformError").PlatformError | import("@effected/git").UnknownRefError | import("@effected/yaml").YamlParseError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("@effected/cli").CliExit | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("effect/Path").Path | ReportEnv>;
 //#endregion
 //#region src/commands/repos/commands/status.d.ts
 /**
@@ -214,7 +318,7 @@ export declare const lintCommand: Command.Command<"lint", {}, {}, import("@effec
  *
  * @internal
  */
-export declare const runReposStatus: (cwd: string, json: boolean, drift?: boolean) => Effect.Effect<void, Repos.GitSubmoduleError, CliExit | Repos.ReposDrift | Repos.ReposManager | Stdio.Stdio>;
+export declare const runReposStatus: (cwd: string, json: boolean, drift?: boolean) => Effect.Effect<void, CommandError, CliExit | Repos.ReposDrift | Repos.ReposManager | ReportEnv>;
 //#endregion
 //#region src/commands/repos/commands/sync.d.ts
 /**
@@ -222,7 +326,7 @@ export declare const runReposStatus: (cwd: string, json: boolean, drift?: boolea
  *
  * @internal
  */
-export declare const runReposSync: (cwd: string) => Effect.Effect<void, never, CliExit | Repos.ReposManager | Stdio.Stdio>;
+export declare const runReposSync: (cwd: string) => Effect.Effect<void, CommandError, Repos.ReposManager | ReportEnv>;
 //#endregion
 //#region src/commands/repos/index.d.ts
 /**
@@ -242,17 +346,14 @@ export declare const runReposSync: (cwd: string) => Effect.Effect<void, never, C
  * discharges via `AppLive`. `Repos.ReposDrift` joins the union because
  * `status --drift` runs `Repos.ReposDrift.check` after the status check.
  *
- * The error channel is `Repos.GitSubmoduleError` alone: `add`/`pin`/`note`/
- * `remove`/`rename`/`restore`/`sync`/`deregister` each `catchTag` every error
- * their underlying `ReposManager` method can produce — `ReposConfigError`,
- * `GitSubmoduleError`, `RepoNotFoundError`, `NoteNotFoundError`, and (for the
- * six ops that unlock/re-lock the vendored tree around a git mutation)
- * `ReposLockdownError` — down to a logged message and a non-zero exit code,
- * so none of those propagate past the handler. `status` only `catchTag`s
- * `ReposConfigError`; `GitSubmoduleError` from either `ReposManager.status`
- * or (under `--drift`) `Repos.ReposDrift.check` is the sole channel that
- * escapes uncaught, so it is the only member left in this union.
+ * The error channel is what a handler fails with, never a raw `Repos` error:
+ * every handler maps each error its `ReposManager` method (or the picker's
+ * `status` read) can produce to a self-rendering `CommandError` (exit 1),
+ * except the friendly missing-manifest case and `status --json`'s JSON error
+ * document. A repo name or other positional left off is a
+ * `CliError.ShowHelp` (exit 64) when no one can be asked, and backing out of
+ * a picker or a confirm is the kit's `Cancelled` (exit 130).
  */
-export declare const reposCommand: Command.Command<"repos", Record<string, never>, Record<string, never>, Repos.GitSubmoduleError, Repos.ReposManager | Repos.ReposDrift | CliExit | Stdio.Stdio>;
+export declare const reposCommand: Command.Command<"repos", Record<string, never>, Record<string, never>, CommandError | CliError.ShowHelp | Cancelled, Repos.ReposManager | Repos.ReposDrift | CliExit | ReportEnv>;
 //#endregion
 //# sourceMappingURL=index.d.ts.map

package/internal/command-error.js

@@ -0,0 +1,60 @@
+import { FailureLine } from "./failure-line.js";
+import { CliDoc, Doc, Status } from "@effected/cli";
+import { Data } from "effect";
+
+//#region src/internal/command-error.ts
+/**
+* A command's failure that draws itself: a failure status line, indented
+* detail lines, and an optional remediation as a tip callout.
+*
+* @remarks
+* Replaces the `Effect.logError(...)` + `CliExit.set(1)` pair: fail with it
+* and `CliRuntime.main` reports it on stderr through `FailureLine.render`,
+* which hands an error implementing `CliDoc` the kit's report of its
+* document, rendered for the run's audience (ANSI for a person, plain for an
+* agent, a GitHub Actions log under Actions). It is a typed failure, so the
+* run exits `1`. A finding (a lint problem, a dirty repo) is still output
+* plus `CliExit.set(1)`, never this.
+*
+* Map a silk-effects error at the command edge with
+* {@link CommandError.from}, inside the handler's `catchTag`s.
+*
+* @example
+* ```ts
+* Effect.catchTag("ChangesetConfigError", (error) =>
+*   Effect.fail(CommandError.from(error, { message: "could not read the changeset config", hint: "run savvy init" })),
+* )
+* ```
+*
+* @internal
+*/
+var CommandError = class CommandError extends Data.TaggedError("CommandError") {
+	/** Wrap a foreign (silk-effects, kit) error: its own description becomes the last detail line, and it is kept as `cause`. */
+	static from = (error, options) => {
+		const own = FailureLine.describe(error);
+		const detail = [...options.detail ?? [], ...own === options.message ? [] : [own]];
+		return new CommandError({
+			message: options.message,
+			cause: error,
+			...detail.length > 0 ? { detail } : {},
+			...options.hint === void 0 ? {} : { hint: options.hint }
+		});
+	};
+	[CliDoc]() {
+		const head = Doc.line([
+			Doc.status(Status.core, "failure"),
+			" ",
+			this.message
+		]);
+		const detail = this.detail === void 0 || this.detail.length === 0 ? [] : [Doc.lines(this.detail.map((line) => Doc.text(`  ${line}`, "muted")))];
+		const hint = this.hint === void 0 ? [] : [Doc.callout("tip", [Doc.paragraph(this.hint)])];
+		return [
+			head,
+			...detail,
+			...hint
+		];
+	}
+};
+
+//#endregion
+export { CommandError };

package/internal/confirm.js

@@ -0,0 +1,52 @@
+import { Flag } from "effect/cli";
+import { Effect } from "effect";
+import { CliUi, Confirm } from "@effected/cli/ui";
+
+//#region src/internal/confirm.ts
+/**
+* `--yes` / `-y`: answer yes to a destructive command's confirmation.
+*
+* @remarks
+* Defaults to `false` explicitly — core's `Flag.Boolean` has no implicit
+* `false`, so an omitted boolean would otherwise be a usage error. Add it to a
+* command's flags as `yes: yesFlag` and pass the parsed value to
+* {@link confirmDestructive}.
+*
+* @internal
+*/
+const yesFlag = Flag.Boolean("yes").pipe(Flag.withAlias("y"), Flag.withDescription("Answer yes to the confirmation and proceed"), Flag.withDefault(false));
+/**
+* Whether a destructive command may proceed.
+*
+* @remarks
+* - `yes` (the `--yes` flag) → `true`, without asking.
+* - A run that cannot prompt (`CliInteractive` false: an agent, CI, a pipe,
+*   `TERM=dumb`) → `true`, without asking and without loading Ink or React:
+*   savvy has always proceeded there, and an agent or a script has no one to
+*   ask.
+* - A person at a terminal → the kit's `Confirm` screen (`Enter` alone answers
+*   no). Its answer is a whole `{ confirmed, toggles }`, of which this
+*   returns `confirmed`.
+*
+* Esc, `q` or Ctrl-C on the screen fails with the kit's `Cancelled`, which
+* `CliRuntime.main` reports as one line with exit `130`; a handler that wants
+* cancel to mean "no" catches it with `Effect.catchTag("Cancelled", ...)`.
+* A `false` answer is the handler's to report (a line saying nothing was
+* changed) — it is not a failure.
+*
+* @example
+* ```ts
+* if (!(yield* confirmDestructive({ message: `Remove ${name}?`, yes }))) {
+*   return yield* Report.print([Report.skip(`${name} kept`)]);
+* }
+* ```
+*
+* @internal
+*/
+const confirmDestructive = (options) => options.yes ? Effect.succeed(true) : CliUi.prompt(Confirm.screen({ message: options.message }), { otherwise: {
+	confirmed: true,
+	toggles: {}
+} }).pipe(Effect.map((result) => result.confirmed), Effect.catchTag("NotInteractive", () => Effect.succeed(true)));
+
+//#endregion
+export { confirmDestructive, yesFlag };