@savvy-web/cli 3.5.1 → 3.7.0

package/commands/lint/init.js

@@ -1,4 +1,5 @@
-import { Output } from "../../internal/output.js";
+import { Report } from "../../internal/report.js";
+import { CommandError } from "../../internal/command-error.js";
 import { BIOME_VERSION } from "./biome-version.js";
 import { dirname, join } from "node:path";
 import { BiomeSchemaSync, LIFECYCLE_SCRIPTS_CONFIG_KEY, Lint, SavvyBaseSection, SavvyHooksSection, SavvyToolchainSection, publishesBuiltLinkDirectory, savvyBasePreamble, savvyHooksHygiene, savvyInstallBlock, savvyOkfBlock, savvyToolchainCheck } from "@savvy-web/silk-effects";
@@ -73,26 +74,27 @@ export default Preset.${preset}();
 * @param fs - FileSystem service
 * @param preset - The active preset
 * @param force - Whether to overwrite the entire file
-* @returns Effect that manages the markdownlint config
+* @returns Effect that manages the markdownlint config, yielding the report lines for what it did
 */
 function writeMarkdownlintConfig(fs, preset, force) {
 	return Effect.gen(function* () {
+		const blocks = [];
 		const configExists = yield* fs.exists(Lint.MARKDOWNLINT_CONFIG_PATH);
 		const fullTemplate = JSON.stringify(Lint.MARKDOWNLINT_TEMPLATE, null, "	");
 		if (!configExists) {
 			yield* fs.makeDirectory("lib/configs", { recursive: true });
 			yield* fs.writeFileString(Lint.MARKDOWNLINT_CONFIG_PATH, `${fullTemplate}\n`);
-			yield* Output.ok(`Created ${Lint.MARKDOWNLINT_CONFIG_PATH}`);
-			return;
+			blocks.push(Report.ok(`Created ${Lint.MARKDOWNLINT_CONFIG_PATH}`));
+			return blocks;
 		}
 		if (preset !== "silk") {
-			yield* Output.ok(`${Lint.MARKDOWNLINT_CONFIG_PATH}: exists (not managed by ${preset} preset)`);
-			return;
+			blocks.push(Report.ok(`${Lint.MARKDOWNLINT_CONFIG_PATH}: exists (not managed by ${preset} preset)`));
+			return blocks;
 		}
 		if (force) {
 			yield* fs.writeFileString(Lint.MARKDOWNLINT_CONFIG_PATH, `${fullTemplate}\n`);
-			yield* Output.ok(`Replaced ${Lint.MARKDOWNLINT_CONFIG_PATH} (--force)`);
-			return;
+			blocks.push(Report.ok(`Replaced ${Lint.MARKDOWNLINT_CONFIG_PATH} (--force)`));
+			return blocks;
 		}
 		const existingText = yield* fs.readFileString(Lint.MARKDOWNLINT_CONFIG_PATH);
 		const existingParsed = yield* Jsonc.parse(existingText);
@@ -113,11 +115,12 @@ function writeMarkdownlintConfig(fs, preset, force) {
 		}
 		const existingConfig = existingParsed.config;
 		const configMatches = existingConfig !== void 0 && isDeepStrictEqual(existingConfig, Lint.MARKDOWNLINT_CONFIG);
-		if (!configMatches) yield* Output.warn(`${Lint.MARKDOWNLINT_CONFIG_PATH}: config rules differ from template (use --force to overwrite)`);
+		if (!configMatches) blocks.push(Report.warn(`${Lint.MARKDOWNLINT_CONFIG_PATH}: config rules differ from template (use --force to overwrite)`));
 		if (applied.length > 0) {
 			yield* fs.writeFileString(Lint.MARKDOWNLINT_CONFIG_PATH, updatedText);
-			yield* Output.ok(`Updated ${applied.join(", ")} in ${Lint.MARKDOWNLINT_CONFIG_PATH}`);
-		} else if (configMatches) yield* Output.ok(`${Lint.MARKDOWNLINT_CONFIG_PATH}: up-to-date`);
+			blocks.push(Report.ok(`Updated ${applied.join(", ")} in ${Lint.MARKDOWNLINT_CONFIG_PATH}`));
+		} else if (configMatches) blocks.push(Report.ok(`${Lint.MARKDOWNLINT_CONFIG_PATH}: up-to-date`));
+		return blocks;
 	});
 }
 /**
@@ -168,6 +171,8 @@ function biomeConfigRoots() {
 *
 * Every failure reads as "say nothing": an unreadable or malformed manifest
 * cannot make the notice wrong, only absent.
+*
+* @returns Effect yielding the notice's report lines, empty when none is due
 */
 function noticeLifecycleScripts() {
 	return Effect.gen(function* () {
@@ -175,12 +180,9 @@ function noticeLifecycleScripts() {
 		const roots = yield* biomeConfigRoots();
 		for (const root of roots) {
 			const manifest = yield* fs.readFileString(join(root, "package.json")).pipe(Effect.map((raw) => JSON.parse(raw)), Effect.catch(() => Effect.succeed(void 0)));
-			if (publishesBuiltLinkDirectory(manifest)) {
-				yield* Output.warn("This workspace publishes through built link directories, so a hook-time install must run lifecycle scripts.");
-				yield* Output.detail(`Allow them with: git config --local ${LIFECYCLE_SCRIPTS_CONFIG_KEY} true`);
-				return;
-			}
+			if (publishesBuiltLinkDirectory(manifest)) return [Report.warn("This workspace publishes through built link directories, so a hook-time install must run lifecycle scripts.", `Allow them with: git config --local ${LIFECYCLE_SCRIPTS_CONFIG_KEY} true`)];
 		}
+		return [];
 	});
 }
 /**
@@ -197,26 +199,40 @@ function noticeLifecycleScripts() {
 * volume — `runLintInit` itself chmods hook files through `node:fs/promises`,
 * which no `FileSystem` double can intercept.
 *
-* @returns Effect that syncs biome schemas and logs results
+* @returns Effect that syncs biome schemas, yielding one report line per config
+* checked or updated and per root that could not be synced
 *
 * @internal
 */
 function syncBiomeSchemas() {
 	return Effect.gen(function* () {
+		const blocks = [];
 		const syncer = yield* BiomeSchemaSync;
 		const roots = yield* biomeConfigRoots();
 		const passes = roots.length > 0 ? roots.map((cwd) => ({ cwd })) : [{ cwd: process.cwd() }];
-		for (const options of passes) yield* syncer.sync(BIOME_VERSION, options).pipe(Effect.flatMap((result) => Effect.gen(function* () {
-			for (const configPath of result.current) yield* Output.ok(`${configPath}: biome $schema up-to-date`);
-			for (const configPath of result.updated) yield* Output.ok(`Updated $schema in ${configPath}`);
-		})), Effect.catchTag("BiomeSyncError", (e) => Output.warn(`Could not sync biome $schema: ${e.message}`)));
+		for (const options of passes) {
+			const passBlocks = yield* syncer.sync(BIOME_VERSION, options).pipe(Effect.map((result) => [...result.current.map((configPath) => Report.ok(`${configPath}: biome $schema up-to-date`)), ...result.updated.map((configPath) => Report.ok(`Updated $schema in ${configPath}`))]), Effect.catchTag("BiomeSyncError", (e) => Effect.succeed([Report.warn(`Could not sync biome $schema: ${e.message}`)])));
+			blocks.push(...passBlocks);
+		}
+		return blocks;
 	});
 }
 /** Make a file executable. */
 function makeExecutable(path) {
 	return Effect.tryPromise({
 		try: () => chmod(path, EXECUTABLE_MODE),
-		catch: (e) => new Error(String(e))
+		catch: (e) => CommandError.from(e, {
+			message: `could not make ${path} executable`,
+			hint: `Check that you own ${path}, then re-run the init.`
+		})
+	});
+}
+/** The failure for a `--config` path given as absolute. */
+function absoluteConfigError(config) {
+	return new CommandError({
+		message: "Config path must be relative to repository root, not absolute",
+		detail: [`got ${config}`],
+		hint: "Pass the config path relative to the repository root, e.g. lib/configs/<name>.config.ts."
 	});
 }
 /** Ensure a hook file exists, writing `header` if it does not. */
@@ -232,6 +248,10 @@ function ensureHookFile(path, header) {
 * 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
 *
@@ -242,8 +262,8 @@ function runLintInit(opts) {
 	return Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		const ms = yield* ManagedSection;
-		if (config.startsWith("/")) yield* Effect.fail(/* @__PURE__ */ new Error("Config path must be relative to repository root, not absolute"));
-		yield* Output.heading("lint-staged");
+		if (config.startsWith("/")) return yield* Effect.fail(absoluteConfigError(config));
+		yield* Report.print([Report.heading("lint-staged")]);
 		yield* fs.makeDirectory(".husky", { recursive: true });
 		if (force) yield* fs.writeFileString(Lint.HUSKY_HOOK_PATH, PRE_COMMIT_HEADER);
 		else yield* ensureHookFile(Lint.HUSKY_HOOK_PATH, PRE_COMMIT_HEADER);
@@ -253,7 +273,7 @@ function runLintInit(opts) {
 			savvyOkfBlock()
 		]);
 		yield* makeExecutable(Lint.HUSKY_HOOK_PATH);
-		yield* Output.ok(`${force ? "Replaced" : "Synced"} ${Lint.HUSKY_HOOK_PATH} (${preCommitResults.map((r) => r._tag).join(", ")})`);
+		yield* Report.print([Report.ok(`${force ? "Replaced" : "Synced"} ${Lint.HUSKY_HOOK_PATH} (${preCommitResults.map((r) => r._tag).join(", ")})`)]);
 		if (presetIncludesShellScripts(preset)) for (const [hookPath, installHook] of HYGIENE_HOOKS) {
 			yield* ensureHookFile(hookPath, HYGIENE_HEADER);
 			yield* ms.remove(hookPath, Lint.LegacySavvyLintHygieneDef);
@@ -264,20 +284,19 @@ function runLintInit(opts) {
 			}
 			yield* ms.syncAll(hookPath, sections);
 			yield* makeExecutable(hookPath);
-			yield* Output.ok(`Synced ${hookPath}`);
+			yield* Report.print([Report.ok(`Synced ${hookPath}`)]);
 		}
-		if (presetIncludesShellScripts(preset)) yield* noticeLifecycleScripts();
-		if (presetIncludesMarkdown(preset)) yield* writeMarkdownlintConfig(fs, preset, force);
-		yield* syncBiomeSchemas();
-		if ((yield* fs.exists(config)) && !force) yield* Output.warn(`${config} already exists (use --force to overwrite)`);
+		if (presetIncludesShellScripts(preset)) yield* Report.print(yield* noticeLifecycleScripts());
+		if (presetIncludesMarkdown(preset)) yield* Report.print(yield* writeMarkdownlintConfig(fs, preset, force));
+		yield* Report.print(yield* syncBiomeSchemas());
+		if ((yield* fs.exists(config)) && !force) yield* Report.print([Report.warn(`${config} already exists (use --force to overwrite)`)]);
 		else {
 			const configDir = dirname(config);
 			if (configDir && configDir !== ".") yield* fs.makeDirectory(configDir, { recursive: true });
 			yield* fs.writeFileString(config, generateConfigContent(preset));
-			yield* Output.ok(`Created ${config} (preset: ${preset})`);
+			yield* Report.print([Report.ok(`Created ${config} (preset: ${preset})`)]);
 		}
-		yield* Output.line("");
-		yield* Output.ok("lint-staged is ready to use");
+		yield* Report.print([Report.line(""), Report.ok("lint-staged is ready to use")]);
 	});
 }
 

package/commands/lint/text.js

@@ -1,8 +1,8 @@
-import { Output } from "../../internal/output.js";
+import { Report } from "../../internal/report.js";
 import { Argument, Command, Flag } from "effect/cli";
-import { CliExit } from "@effected/cli";
+import { CliExit, Doc } from "@effected/cli";
 import { Lint } from "@savvy-web/silk-effects";
-import { Effect } from "effect";
+import { Effect, Path } from "effect";
 
 //#region src/commands/lint/text.ts
 /**
@@ -32,32 +32,47 @@ import { Effect } from "effect";
 const filesArg = Argument.File("files", { mustExist: true }).pipe(Argument.withDescription("Files to check; omit to check every git-tracked source/text file"), Argument.variadic());
 const stagedFlag = Flag.Boolean("staged").pipe(Flag.withDescription("Read each file's staged content from the git index instead of the working tree"), Flag.withDefault(false));
 /**
-* Check `files` (or, when empty, every tracked file under `cwd`) and print one
-* line per finding; any finding sets exit code 1. Under `--staged`, every file
-* is still checked when one has no index entry: that file's read error is
-* logged to stderr, counted as failed, and also sets exit code 1. Exported for
-* tests.
+* Check `files` (or, when empty, every tracked file under `cwd`) and print the
+* findings as one document: a `✗ path:line:col  message` line per finding (the
+* form editors link and agents grep), a GitHub Actions error annotation per
+* finding (written only under Actions, with the path relative to `cwd`), and a
+* summary. Any finding sets exit code 1. Under `--staged`, every file is still
+* checked when one has no index entry: that file's read error is logged to
+* stderr (a diagnostic, not a finding in its content), counted as failed, and
+* also sets exit code 1. Exported for tests.
 *
 * @internal
 */
 const runLintText = (files, options = {}) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const cwd = options.cwd ?? ".";
 	const staged = options.staged ?? false;
-	const targets = files.length > 0 ? files : yield* Lint.TextFiles.listTracked(options.cwd ?? ".", { staged });
+	const targets = files.length > 0 ? files : yield* Lint.TextFiles.listTracked(cwd, { staged });
 	const { findings, unreadable } = staged ? yield* Lint.TextFiles.checkStagedFiles(targets) : {
 		findings: yield* Lint.TextFiles.checkFiles(targets),
 		unreadable: []
 	};
 	for (const error of unreadable) yield* Effect.logError(error.message);
 	if (findings.length === 0 && unreadable.length === 0) {
-		yield* Output.ok(`${targets.length} ${targets.length === 1 ? "file is" : "files are"} grep-visible text`);
+		yield* Report.print([Report.ok(`${targets.length} ${targets.length === 1 ? "file is" : "files are"} grep-visible text`)]);
 		return findings;
 	}
-	for (const finding of findings) yield* Output.fail(`${finding.location}  ${finding.message}`);
+	const root = path.resolve(cwd);
+	const annotationPath = (file) => {
+		const relative = path.relative(root, path.resolve(file));
+		return relative.startsWith("..") || path.isAbsolute(relative) ? file : relative;
+	};
 	const failedFiles = (/* @__PURE__ */ new Set([...findings.map((finding) => finding.path), ...unreadable.map((error) => error.path)])).size;
-	yield* Output.summary({
+	yield* Report.print([...findings.flatMap((finding) => [Report.fail(`${finding.location}  ${finding.message}`), Doc.annotation({
+		level: "error",
+		file: annotationPath(finding.path),
+		line: finding.line,
+		col: finding.column,
+		title: "grep-invisible text"
+	}, finding.message)]), Report.summary({
 		ok: targets.length - failedFiles,
 		fail: failedFiles
-	});
+	})]);
 	yield* CliExit.set(1);
 	return findings;
 });

package/commands/repos/commands/add.js

@@ -1,6 +1,7 @@
-import { Output } from "../../../internal/output.js";
-import { Argument, Command, Flag } from "effect/cli";
-import { CliExit } from "@effected/cli";
+import { Report } from "../../../internal/report.js";
+import { ReposCli } from "../shared.js";
+import { Argument, Command, Flag, Prompt } from "effect/cli";
+import { CliPrompt } from "@effected/cli";
 import { Repos } from "@savvy-web/silk-effects";
 import { Effect, Option } from "effect";
 
@@ -20,7 +21,11 @@ import { Effect, Option } from "effect";
 * manifest exists but is corrupt or unreadable, `GitSubmoduleError` means
 * the underlying git command failed, and `ReposLockdownError` means the
 * OS-permission lockdown pass on a vendored tree failed -- all three are
-* real failures, logged and reported via a non-zero exit code.
+* real failures, failing as a `CommandError` (exit 1) with a hint.
+*
+* `--ref` and `--purpose` are required. Left off at a terminal, each is asked
+* for with core's line prompt (`CliPrompt.fallback`); left off anywhere else
+* (an agent, CI, a pipe) it stays core's missing-flag usage error, exit 64.
 *
 * @example
 * ```bash
@@ -32,8 +37,8 @@ import { Effect, Option } from "effect";
 */
 /* v8 ignore start -- CLI option/arg definitions */
 const urlArg = Argument.String("url");
-const refOption = Flag.String("ref").pipe(Flag.withDescription("Ref (tag, branch, or commit) to check out"));
-const purposeOption = Flag.String("purpose").pipe(Flag.withDescription("Why this repo is vendored"));
+const refOption = Flag.String("ref").pipe(Flag.withDescription("Ref (tag, branch, or commit) to check out"), Flag.withFallbackPrompt(CliPrompt.fallback(Prompt.String({ message: "Ref to check out (tag, branch, or commit)" }), { flag: "ref" })));
+const purposeOption = Flag.String("purpose").pipe(Flag.withDescription("Why this repo is vendored"), Flag.withFallbackPrompt(CliPrompt.fallback(Prompt.String({ message: "Why is this repo vendored?" }), { flag: "purpose" })));
 const nameOption = Flag.String("name").pipe(Flag.withDescription("Vendored directory name; defaults to the URL's last path segment"), Flag.optional);
 const sparseOption = Flag.String("sparse").pipe(Flag.withDescription("Sparse-checkout path; repeatable"), Flag.atLeast(0));
 const cwdOption = Flag.Directory("cwd").pipe(Flag.withDescription("Repo root to add within"), Flag.withDefault("."));
@@ -45,17 +50,9 @@ const cwdOption = Flag.Directory("cwd").pipe(Flag.withDescription("Repo root to
 */
 const runReposAdd = (cwd, opts) => Effect.gen(function* () {
 	const result = yield* (yield* Repos.ReposManager).add(cwd, opts);
-	yield* Output.ok(`${result.name} @ ${result.ref} -> ${result.path}`);
-	yield* Output.detail("staged — review and commit");
-}).pipe(Effect.catchTag("ReposConfigError", (error) => {
-	if (error.kind === "missing") return Output.skip("no .repos/config.json — nothing vendored");
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}), Effect.catchTag("GitSubmoduleError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}), Effect.catchTag("ReposLockdownError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}));
-/* v8 ignore start -- CLI registration; handler tested via runReposAdd */
+	yield* Report.print([Report.ok(`${result.name} @ ${result.ref} -> ${result.path}`, "staged — review and commit")]);
+}).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? ReposCli.nothingVendored : ReposCli.fail(`vendor ${opts.url}`)(error)), Effect.catchTag(["GitSubmoduleError", "ReposLockdownError"], ReposCli.fail(`vendor ${opts.url}`)));
+/* v8 ignore start -- CLI registration; handler tested via runReposAdd, the fallbacks via the command itself */
 const addCommand = Command.make("add", {
 	url: urlArg,
 	ref: refOption,

package/commands/repos/commands/deregister.js

@@ -1,8 +1,10 @@
-import { Output } from "../../../internal/output.js";
+import { Report } from "../../../internal/report.js";
+import { ReposCli } from "../shared.js";
 import { Argument, Command, Flag } from "effect/cli";
-import { CliExit } from "@effected/cli";
+import { CliInteractive } from "@effected/cli";
 import { Repos } from "@savvy-web/silk-effects";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
+import { CliUi, Select } from "@effected/cli/ui";
 
 //#region src/commands/repos/commands/deregister.ts
 /**
@@ -26,9 +28,16 @@ import { Effect } from "effect";
 * the section still backs a live manifest entry (use `remove` to unvendor, or
 * `sync` to reconcile), the section is not registered at all (usually a
 * typo), or the manifest itself is unreadable; a `GitSubmoduleError` means
-* the underlying git command failed. There is no friendly missing-manifest
-* exit-0 case: the manager folds a missing manifest to "no live entries" and
-* proceeds, since a stale registration can outlive the manifest itself.
+* the underlying git command failed. Each fails as a `CommandError` with a
+* hint. There is no friendly missing-manifest exit-0 case: the manager folds
+* a missing manifest to "no live entries" and proceeds, since a stale
+* registration can outlive the manifest itself.
+*
+* Left off at a terminal, the section is picked (`Select`) from the stale
+* registrations `ReposDrift.check` reports — a `localRegistrationDivergence`
+* with no manifest value — never from the vendored repos, which this command
+* refuses. Anywhere else, or with nothing stale to pick, a missing section is
+* the usage error it always was, exit 64.
 *
 * @example
 * ```bash
@@ -38,29 +47,39 @@ import { Effect } from "effect";
 * @internal
 */
 /* v8 ignore start -- CLI option/arg definitions */
-const sectionArg = Argument.String("section");
+const sectionArg = Argument.String("section").pipe(Argument.optional);
 const cwdOption = Flag.Directory("cwd").pipe(Flag.withDescription("Repo root to deregister within"), Flag.withDefault("."));
 /* v8 ignore stop */
+/** The section given, or one picked from the stale registrations at a terminal; else a usage error. */
+const sectionOrPick = (cwd, given) => Effect.gen(function* () {
+	if (given !== void 0) return given;
+	if (!(yield* CliInteractive)) return yield* Effect.fail(ReposCli.missingArgument(["deregister"], "section"));
+	const stale = (yield* (yield* Repos.ReposDrift).check(cwd)).drifts.filter((item) => item.kind === "localRegistrationDivergence" && item.manifestValue === void 0);
+	if (stale.length === 0) return yield* Effect.fail(ReposCli.missingArgument(["deregister"], "section"));
+	return yield* CliUi.prompt(Select.screen({
+		message: "Deregister which stale registration?",
+		choices: stale.map((item) => ({
+			label: item.name,
+			value: item.name,
+			detail: item.detail
+		}))
+	})).pipe(Effect.catchTag("NotInteractive", () => Effect.fail(ReposCli.missingArgument(["deregister"], "section"))));
+});
 /**
-* Deregister handler; exported for tests.
+* Deregister handler; exported for tests. `section` is `undefined` when left off.
 *
 * @internal
 */
 const runReposDeregister = (cwd, section) => Effect.gen(function* () {
-	const result = yield* (yield* Repos.ReposManager).deregister(cwd, section);
-	yield* Output.ok(`${result.section}: deregistered (${result.removedKeys.length} config keys removed)`);
-	for (const key of result.removedKeys) yield* Output.detail(`removed ${key}`);
-	yield* Output.detail("local git config only — nothing to commit");
-}).pipe(Effect.catchTag("ReposConfigError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}), Effect.catchTag("GitSubmoduleError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}));
+	const target = yield* sectionOrPick(cwd, section);
+	const result = yield* (yield* Repos.ReposManager).deregister(cwd, target);
+	yield* Report.print([Report.ok(`${result.section}: deregistered (${result.removedKeys.length} config keys removed)`, ...result.removedKeys.map((key) => `removed ${key}`), "local git config only — nothing to commit")]);
+}).pipe(Effect.catchTag("ReposConfigError", ReposCli.fail("deregister the submodule registration", "it still backs a manifest entry (use `savvy repos remove`), is not registered, or the manifest is unreadable; `savvy repos status --drift` lists the stale ones")), Effect.catchTag("GitSubmoduleError", ReposCli.fail("deregister the submodule registration")));
 /* v8 ignore start -- CLI registration; handler tested via runReposDeregister */
 const deregisterCommand = Command.make("deregister", {
 	section: sectionArg,
 	cwd: cwdOption
-}, ({ section, cwd }) => runReposDeregister(cwd, section)).pipe(Command.withDescription("Clear a stale submodule registration (a submodule.<section> section matching no manifest entry) from the local git config"));
+}, ({ section, cwd }) => runReposDeregister(cwd, Option.getOrUndefined(section))).pipe(Command.withDescription("Clear a stale submodule registration (a submodule.<section> section matching no manifest entry) from the local git config"));
 /* v8 ignore stop */
 
 //#endregion

package/commands/repos/commands/note.js

@@ -1,8 +1,9 @@
-import { Output } from "../../../internal/output.js";
+import { Report } from "../../../internal/report.js";
+import { ReposCli } from "../shared.js";
 import { Argument, Command, Flag } from "effect/cli";
-import { CliExit } from "@effected/cli";
 import { Repos } from "@savvy-web/silk-effects";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
+import { CliUi, Select } from "@effected/cli/ui";
 
 //#region src/commands/repos/commands/note.ts
 /**
@@ -23,7 +24,14 @@ import { Effect } from "effect";
 * kind `"invalid"` means the manifest exists but is corrupt or unreadable,
 * `RepoNotFoundError` means the named repo isn't in the manifest, and
 * `NoteNotFoundError` means the note id doesn't exist on that repo -- all
-* three are real failures, logged and reported via a non-zero exit code.
+* three are real failures, failing as a `CommandError` (exit 1) with a hint.
+*
+* Each leaf's positionals are optional to the parser so a person can leave
+* them off: at a terminal a missing repo name is picked from the vendored
+* repos (`Select`) and a missing note text or id typed (`TextInput`), and a
+* missing `promote --into` is picked from `layout`/`startHere` while parsing
+* (`CliUi.fallback`). Anywhere else a missing one is the usage error it always
+* was, exit 64.
 *
 * @example
 * ```bash
@@ -34,27 +42,71 @@ import { Effect } from "effect";
 *
 * @internal
 */
+/** `request` with its missing text or id asked for (or a usage error), as `ReposManager.note` takes it. */
+const complete = (name, request) => {
+	switch (request.op) {
+		case "add": return Effect.map(ReposCli.textOrAsk(request.note, {
+			command: ["note", "add"],
+			argument: "text",
+			message: `Note to add to ${name}:`
+		}), (note) => ({
+			op: "add",
+			note
+		}));
+		case "remove": return Effect.map(ReposCli.textOrAsk(request.id, {
+			command: ["note", "remove"],
+			argument: "id",
+			message: `Id of the ${name} note to remove:`
+		}), (id) => ({
+			op: "remove",
+			id
+		}));
+		case "promote": return Effect.map(ReposCli.textOrAsk(request.id, {
+			command: ["note", "promote"],
+			argument: "id",
+			message: `Id of the ${name} note to promote:`
+		}), (id) => ({
+			op: "promote",
+			id,
+			into: request.into
+		}));
+	}
+};
 /**
-* Note handler; exported for tests.
+* Note handler; exported for tests. `name` is `undefined` when left off.
 *
 * @internal
 */
-const runReposNote = (cwd, name, op) => Effect.gen(function* () {
-	const result = yield* (yield* Repos.ReposManager).note(cwd, name, op);
-	yield* Output.ok(`${result.name}: ${result.op} note ${result.id} (${result.noteCount} notes)`);
-}).pipe(Effect.catchTag("ReposConfigError", (error) => {
-	if (error.kind === "missing") return Output.skip("no .repos/config.json — nothing vendored");
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}), Effect.catchTag("RepoNotFoundError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}), Effect.catchTag("NoteNotFoundError", (error) => {
-	return CliExit.set(1).pipe(Effect.andThen(Effect.logError(error.message)));
-}));
+const runReposNote = (cwd, name, request) => Effect.gen(function* () {
+	const target = yield* ReposCli.nameOrPick(cwd, name, {
+		command: ["note", request.op],
+		argument: "name",
+		message: `Which repo's notes (${request.op})?`
+	});
+	const op = yield* complete(target, request);
+	const result = yield* (yield* Repos.ReposManager).note(cwd, target, op);
+	yield* Report.print([Report.ok(`${result.name}: ${result.op} note ${result.id} (${result.noteCount} notes)`)]);
+}).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? ReposCli.nothingVendored : ReposCli.fail(`${request.op} the note`)(error)), Effect.catchTag([
+	"RepoNotFoundError",
+	"NoteNotFoundError",
+	"GitSubmoduleError"
+], ReposCli.fail(`${request.op} the note`)));
 /* v8 ignore start -- CLI registration; handler tested via runReposNote */
-const nameArg = Argument.String("name");
-const noteTextArg = Argument.String("text");
-const noteIdArg = Argument.String("id");
-const intoOption = Flag.Literals("into", ["layout", "startHere"]).pipe(Flag.withDescription("Curated orientation field to promote the note into"));
+const nameArg = Argument.String("name").pipe(Argument.optional);
+const noteTextArg = Argument.String("text").pipe(Argument.optional);
+const noteIdArg = Argument.String("id").pipe(Argument.optional);
+const intoOption = Flag.Literals("into", ["layout", "startHere"]).pipe(Flag.withDescription("Curated orientation field to promote the note into"), Flag.withFallbackPrompt(CliUi.fallback(Select.screen({
+	message: "Promote the note into which orientation field?",
+	choices: [{
+		label: "layout",
+		value: "layout",
+		detail: "where things live in the vendored tree"
+	}, {
+		label: "startHere",
+		value: "startHere",
+		detail: "where an agent should begin reading"
+	}]
+}), { flag: "into" })));
 const cwdOption = Flag.Directory("cwd").pipe(Flag.withDescription("Repo root whose manifest holds the notes"), Flag.withDefault("."));
 const _noteGroup = Command.make("note").pipe(Command.withSharedFlags({ cwd: cwdOption }));
 const addLeaf = Command.make("add", {
@@ -62,9 +114,9 @@ const addLeaf = Command.make("add", {
 	note: noteTextArg
 }, ({ name, note }) => Effect.gen(function* () {
 	const { cwd } = yield* _noteGroup;
-	yield* runReposNote(cwd, name, {
+	yield* runReposNote(cwd, Option.getOrUndefined(name), {
 		op: "add",
-		note
+		note: Option.getOrUndefined(note)
 	});
 })).pipe(Command.withDescription("Append an agent note to a vendored repo"));
 const removeLeaf = Command.make("remove", {
@@ -72,9 +124,9 @@ const removeLeaf = Command.make("remove", {
 	id: noteIdArg
 }, ({ name, id }) => Effect.gen(function* () {
 	const { cwd } = yield* _noteGroup;
-	yield* runReposNote(cwd, name, {
+	yield* runReposNote(cwd, Option.getOrUndefined(name), {
 		op: "remove",
-		id
+		id: Option.getOrUndefined(id)
 	});
 })).pipe(Command.withDescription("Remove an agent note from a vendored repo"));
 const promoteLeaf = Command.make("promote", {
@@ -83,9 +135,9 @@ const promoteLeaf = Command.make("promote", {
 	into: intoOption
 }, ({ name, id, into }) => Effect.gen(function* () {
 	const { cwd } = yield* _noteGroup;
-	yield* runReposNote(cwd, name, {
+	yield* runReposNote(cwd, Option.getOrUndefined(name), {
 		op: "promote",
-		id,
+		id: Option.getOrUndefined(id),
 		into
 	});
 })).pipe(Command.withDescription("Promote an agent note into curated orientation (layout or startHere)"));