reposets 2.0.4 → 3.0.0

package/README.md

@@ -31,16 +31,16 @@ Scaffold the config files in the current directory:
 
 ```bash
 reposets init --project
-# Created: ./reposets.config.toml
-# Created: ./reposets.credentials.toml
-# Created .gitignore with reposets.credentials.toml
+# ✓ Created: ./reposets.config.toml
+# ✓ Created: ./reposets.credentials.toml
+# ✓ Created .gitignore with reposets.credentials.toml
 ```
 
 Add a credential profile. It records *where* your token lives, never the token itself:
 
 ```bash
 reposets credentials create --profile personal --username your-username --op "op://Private/github/token"
-# Created profile 'personal' (username: your-username, github_token: op op://Private/github/token) in ./reposets.credentials.toml.
+# ✓ Created profile 'personal' (username: your-username, github_token: op op://Private/github/token) in ./reposets.credentials.toml.
 ```
 
 Use `--env REPOSETS_GITHUB_TOKEN` in place of `--op` to read the token from the environment instead of 1Password.
@@ -62,7 +62,7 @@ Check it, preview it, then apply it:
 
 ```bash
 reposets validate
-# Valid: ./reposets.config.toml
+# ✓ Valid: ./reposets.config.toml
 #   groups: 1
 
 reposets sync --dry-run
@@ -95,11 +95,13 @@ The owner is not in the config. It belongs to the credential profile, which decl
 | `reposets validate` | Validate the config with no API calls |
 | `reposets doctor` | Diagnose config, credentials and token, and print required permissions |
 | `reposets history` | Show past runs. Subcommands: `show`, `prune`, `clear` |
-| `reposets init` | Scaffold the config files. `--project` for the current directory |
+| `reposets init` | Scaffold the config files. `--project` for the current directory, `--no-project` for the XDG config directory; asked on a terminal when omitted |
 | `reposets nuke` | Delete every local reposets file. Nothing on GitHub is touched |
 | `reposets credentials` | Manage credential profiles: `create`, `list`, `delete` |
 
-Every command accepts `--config`. Command output goes to stdout and diagnostics and errors to stderr, so `reposets sync > /dev/null` is quiet on success and loud on failure. Usage errors exit `64`; findings exit `1`.
+Every command accepts `--config`. Command output goes to stdout and diagnostics and errors to stderr, so `reposets sync > /dev/null` is quiet on success and loud on failure. Usage errors exit `64`; findings exit `1`; a cancelled prompt exits `130`.
+
+Output adapts to who is reading. On a terminal, a person gets colour, prompts for anything a command needs and was not given, and a live progress footer during `sync` and `drift`. A coding agent or CI job gets plain text and is never prompted — a missing answer is a usage error naming the flag that supplies it. Override the detection with `--human`, `--agent` or `--ci` (or `REPOSETS_AUDIENCE`).
 
 ## Configuration
 
@@ -146,7 +148,13 @@ The last five are only needed if you use the matching config sections. No accoun
 
 ## Editor support
 
-JSON schemas for both config files are published to [SchemaStore](https://www.schemastore.org/), so editors validate and autocomplete `reposets.config.toml` and `reposets.credentials.toml` with no setup. The schemas carry annotations for the Tombi and Taplo TOML language servers.
+Both files have versioned JSON schemas, and `reposets init` stamps a `#:schema` line at the top of each file it creates so editors validate and autocomplete it:
+
+```toml
+#:schema https://raw.githubusercontent.com/spencerbeggs/reposets/main/schemas/3.0/config.json
+```
+
+The credentials file uses `https://raw.githubusercontent.com/spencerbeggs/reposets/main/schemas/3.0/credentials.json`. The schemas are also listed in [SchemaStore](https://www.schemastore.org/), and carry annotations for the Tombi and Taplo TOML language servers.
 
 ## License
 

package/bin/reposets.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { CredentialsFilesLive } from "../services/ConfigFiles.js";
 import { Invocation } from "../services/Invocation.js";
+import { CACHE_DB_FILENAME, STATE_DB_FILENAME } from "../store/files.js";
 import { migrations } from "../store/migrations.js";
 import { SyncJournalLive } from "../store/SyncJournal.js";
 import { credentialsCommand } from "../cli/commands/credentials.js";
@@ -14,9 +15,10 @@ import { listCommand } from "../cli/commands/list.js";
 import { nukeCommand } from "../cli/commands/nuke.js";
 import { validateCommand } from "../cli/commands/validate.js";
 import { Effect, Layer } from "effect";
-import { App } from "@effected/app";
+import { AppCache, AppStore } from "@effected/app";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { CliColor, CliRuntime, ConfigIssueRenderer } from "@effected/cli";
+import { CliAudience, CliRuntime, ConfigIssueRenderer, Fmt } from "@effected/cli";
+import { AppDirs, Xdg } from "@effected/xdg";
 import { Command } from "effect/cli";
 
 //#region src/cli/index.ts
@@ -31,22 +33,56 @@ import { Command } from "effect/cli";
 * `0.0.0 (dev build)` from every build until the version was threaded down
 * from here through {@link Invocation}.
 */
-const VERSION = "2.0.4";
+const VERSION = "3.0.0";
 /**
-* The application control plane.
+* The application's directories: XDG resolution and the `reposets` namespace
+* under it.
 *
 * @remarks
-* Bound once, at module scope. `App.layer` opens both SQLite databases, so a
-* second call would open a second pair with split event streams.
+* Built the way `App.layer` builds its own (`AppDirs.layer` `provideMerge`
+* `Xdg.layer`), but without the two databases `App.layer` always opens. Every
+* command can resolve a path through this; resolving one creates nothing —
+* only an `ensure*` member does, and only the command that writes calls it.
+*/
+const DirsLive = Layer.provideMerge(AppDirs.layer({ namespace: "reposets" }), Xdg.layer);
+/**
+* The state database, `store.db` under the XDG state directory.
+*
+* @remarks
+* Bound once, at module scope: `AppStore.layer` is a layer-returning function,
+* and a second call would open a second connection onto the same file with a
+* second migration ledger.
 *
-* Migrations run during layer construction, so a fresh checkout gets its schema
-* on the first command rather than on first write.
+* It is attached only to the commands that read or write it
+* ({@link DatabasesLive}, {@link HistoryLive}), not to the platform. When it sat in the
+* platform, every command — `init`, `list`, `validate`, `nuke` — opened (and so
+* created) `store.db` as a side effect, and `nuke` deleted the database while
+* its own process held it open, leaving its `-wal` and `-shm` files behind.
+* Migrations still run during layer construction, so they now run on the first
+* command that uses the database rather than on the first command of any kind.
 */
-const AppLive = App.layer({
-	namespace: "reposets",
-	store: { migrations }
+const StoreLive = AppStore.layer({
+	migrations,
+	filename: STATE_DB_FILENAME
 });
 /**
+* Both databases, for the commands that run the sync engine.
+*
+* @remarks
+* `sync` and `drift` read and write the applied state and memoize GitHub reads
+* in `cache.db`. The engine builds its own journal over `Store`, so nothing
+* else is needed here.
+*/
+const DatabasesLive = Layer.mergeAll(StoreLive, AppCache.layer({ filename: CACHE_DB_FILENAME }));
+/**
+* The run journal over the state database, for `history` and its subcommands.
+*
+* @remarks
+* `history` reads only the journal, so it opens `store.db` and never
+* `cache.db`.
+*/
+const HistoryLive = SyncJournalLive.pipe(Layer.provide(StoreLive));
+/**
 * Everything this module reads from `process`, handed down as plain values.
 *
 * @remarks
@@ -68,29 +104,41 @@ const InvocationLive = Invocation.layer({
 * `Command.provide(ConfigLive)` sits here, once, rather than in each subcommand:
 * subcommand requirements bubble into the parent's `R` through
 * `withSubcommands`, so one provide covers all of them.
+*
+* The databases are the deliberate exception. They are provided per command,
+* to `sync`, `drift` and `history` only, because providing them here would
+* open both files for every command again — see {@link StoreLive}. A command
+* that does not name `Store` or `Cache` in its requirements never opens one.
+*
+* `CliAudience.flags()` adds `--audience`, `--human`, `--agent` and `--ci` to
+* every command. `CliAudience.run` resolves them before core parses, so the
+* audience is known to every prompt, report and failure line the run writes.
 */
 const cli = Command.make("reposets", {}, () => Effect.void).pipe(Command.withDescription("Sync GitHub repository settings across repos from a TOML config"), Command.withSubcommands([
 	validateCommand,
-	syncCommand,
+	syncCommand.pipe(Command.provide(DatabasesLive)),
 	listCommand,
 	doctorCommand,
-	driftCommand,
+	driftCommand.pipe(Command.provide(DatabasesLive)),
 	initCommand,
 	nukeCommand,
-	historyCommand,
+	historyCommand.pipe(Command.provide(HistoryLive)),
 	credentialsCommand
-]), Command.provide(ConfigLive), Command.provide(CredentialsFilesLive), Command.provide(SyncJournalLive), Command.withGlobalFlags([ConfigFlag]));
+]), Command.provide(ConfigLive), Command.provide(CredentialsFilesLive), Command.withGlobalFlags([ConfigFlag]), Command.withSharedFlags(CliAudience.flags()));
 /**
-* The platform: Node's services, the application control plane over them, the
-* invocation facts, and one colour-aware help/error formatter.
+* The platform: Node's services, the application's directories over them, and
+* the invocation facts.
 *
 * @remarks
-* `provideMerge` rather than `provide` at each step, because commands require
-* the platform services (`FileSystem`, `Path`, `Stdio`) directly as well as
-* through `App`. `CliColor.formatterLayer()` needs `Stdio` to decide whether
-* colour is on, so it sits above `NodeServices.layer` rather than beside it.
+* `provideMerge` rather than `provide`, because commands require the platform
+* services (`FileSystem`, `Path`, `Stdio`) directly as well as through
+* `AppDirs`, and the per-command database layers need `FileSystem`, `Path` and
+* `AppDirs` from here. No database is opened at this level.
+* There is no formatter here: under `env`, `CliRuntime.main` installs the
+* colour-aware help formatter itself, closer to the program, and one set here
+* would be shadowed.
 */
-const PlatformLive = Layer.mergeAll(AppLive, CliColor.formatterLayer(), InvocationLive).pipe(Layer.provideMerge(NodeServices.layer));
+const PlatformLive = Layer.mergeAll(DirsLive, InvocationLive).pipe(Layer.provideMerge(NodeServices.layer));
 /** Whether a failure is a tagged error of a given tag. */
 const isTagged = (error, tag) => typeof error === "object" && error !== null && "_tag" in error && error._tag === tag;
 /**
@@ -98,34 +146,44 @@ const isTagged = (error, tag) => typeof error === "object" && error !== null &&
 *
 * @remarks
 * `CliRuntime.main` hands this every failure it does not already know how to
-* skip — a usage error `Command.runWith` printed itself never reaches it — and
-* logs each returned line through `CliLogger` before exiting `1`.
+* skip — a usage error `Command.runWith` printed itself never reaches it, and a
+* cancelled prompt is drawn by the kit — and logs each returned line before
+* exiting `1`.
+*
+* A config that fails to decode arrives here as a `ConfigValidationError`.
+* The kit's default report already draws its issue as a tree of rejected keys,
+* so the failure describes itself rather than telling a CI log to go run
+* another command; this adds only the `doctor` pointer, and only when
+* something was misspelled (`ConfigIssueRenderer` names it an `unknown key`).
+* A missing key has no near-match to suggest, and pointing a confused user at
+* a command that cannot help them is worse than saying nothing.
 *
-* A config that fails to decode arrives here as a `ConfigValidationError`,
-* whose message names the file and stops there. The structured cause is on its
-* `issue`, which `ConfigIssueRenderer` turns into `unknown key at …` lines, so
-* the failure describes itself rather than telling a CI log to go run another
-* command. The `doctor` pointer stays only when something was misspelled — a
-* missing key has no near-match to suggest, and pointing a confused user at a
-* command that cannot help them is worse than saying nothing.
+* Any other typed failure that carries a `cause` gets it printed under the
+* kit's own status line. A TOML syntax error is a `ConfigCodecError` whose own
+* message is the bare "toml parse failed" — the line and column live on the
+* cause, and printing it is the difference between "your config is broken
+* somewhere" and a position plus what the parser expected there. The cause
+* reports a 0-based `line:column`: an unclosed `[groups` header on the first
+* line reads "ExpectedTableHeaderClose at 0:7 expected ] to close the table
+* header".
 *
-* Any other failure that carries a `cause` gets it printed on a second line. A
-* TOML syntax error is a `ConfigCodecError` whose own message is the bare
-* "toml parse failed" — the line and column live on the cause, and printing it
-* is the difference between "your config is broken somewhere" and "1:9,
-* expected ] to close the table header".
+* Everything else, defects included, is the kit's default report. Lines built
+* here from data are sanitised: the kit keeps a person's escapes, so it cannot
+* strip an injected one from a `render`'s output.
 */
-const render = (error) => {
-	const lines = [String(error)];
-	if (isTagged(error, "ConfigValidationError")) {
-		const issues = ConfigIssueRenderer.render(error);
-		lines.push(...issues.map((line) => `  ${line}`));
-		if (issues.some((line) => line.startsWith("unknown key"))) lines.push("  Run 'reposets doctor' for suggested spellings.");
-	} else if (typeof error === "object" && error !== null && "cause" in error && error.cause !== void 0) lines.push(`  ${String(error.cause)}`);
-	return lines;
+const render = (error, details) => {
+	if (details.isDefect) return details.defaultLines;
+	if (isTagged(error, "ConfigValidationError")) return ConfigIssueRenderer.render(error).some((line) => line.startsWith("unknown key")) ? [...details.defaultLines, "Run 'reposets doctor' for suggested spellings."] : details.defaultLines;
+	if (typeof error === "object" && error !== null && "cause" in error && error.cause !== void 0) return [...details.defaultLines, `  ${Fmt.sanitize(String(error.cause))}`];
+	return details.defaultLines;
 };
-NodeRuntime.runMain(CliRuntime.main(Command.run(cli, { version: VERSION }), {
+NodeRuntime.runMain(CliRuntime.main(CliAudience.run(cli, { version: VERSION }), {
 	platform: PlatformLive,
+	env: {
+		audienceEnvVar: "REPOSETS_AUDIENCE",
+		log: { envVar: "REPOSETS_LOG_LEVEL" },
+		stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true)
+	},
 	render,
 	helpOnUsageError: "stderr"
 }));

package/cli/commands/credentials.js

@@ -1,12 +1,19 @@
 import { profileOwner } from "../../schemas/credentials.js";
 import { ReposetsCredentialsFile } from "../../services/ConfigFiles.js";
-import { Console, Effect, Option } from "effect";
-import { CliError, Command, Flag } from "effect/cli";
+import { Effect, Option } from "effect";
+import { CliInteractive, CliMessage, Doc } from "@effected/cli";
 import { AppDirs } from "@effected/xdg";
+import { CliError, Command, Flag } from "effect/cli";
+import { CliUi, Select, TextInput } from "@effected/cli/ui";
 
 //#region src/cli/commands/credentials.ts
 const EMPTY = { profiles: {} };
-const profileFlag = Flag.String("profile").pipe(Flag.withDescription("Credential profile name"));
+/**
+* Optional on both `create` and `delete`: an interactive run asks for a
+* missing name, a non-interactive one is refused with a message naming the
+* flag, exactly as a missing required flag would be (exit 64).
+*/
+const profileFlag = Flag.String("profile").pipe(Flag.optional, Flag.withDescription("Credential profile name. Asked when omitted on a terminal"));
 const opFlag = Flag.String("op").pipe(Flag.optional, Flag.withDescription("1Password secret reference, e.g. \"op://Vault/item/field\""));
 const envFlag = Flag.String("env").pipe(Flag.optional, Flag.withDescription("Name of an environment variable holding the token, e.g. \"REPOSETS_GITHUB_TOKEN\""));
 const usernameFlag = Flag.String("username").pipe(Flag.optional, Flag.withDescription("The personal account this profile acts as. Mutually exclusive with --org"));
@@ -31,7 +38,38 @@ const SECRET_PREFIXES = [
 	"sk-",
 	"xoxb-"
 ];
-const looksLikeSecret = (value) => SECRET_PREFIXES.some((prefix) => value.startsWith(prefix)) || value.length > 60;
+/**
+* Whether a value looks like a pasted token rather than a reference or a name.
+*
+* @remarks
+* A known token prefix, or anything longer than 60 characters. The length rule
+* catches the tokens that carry no recognisable prefix, but it never applies to
+* an `op://` value: that is a 1Password reference by construction, none of the
+* token prefixes begins that way, and a real reference crosses 60 characters
+* easily once a vault or item name has spaces in it
+* (`op://Engineering Shared Vault/GitHub Production Deploy Token/credential`).
+*/
+const looksLikeSecret = (value) => SECRET_PREFIXES.some((prefix) => value.startsWith(prefix)) || !value.startsWith("op://") && value.length > 60;
+/**
+* The explanation for a flag value {@link looksLikeSecret} catches — in any
+* flag, since a token pasted into `--profile` or `--username` would otherwise
+* be stored as a TOML key and printed back in the confirmation. It never
+* contains the value.
+*/
+const LOOKS_LIKE_SECRET = "That looks like a credential value, not a reference. This command stores references only — pass --op \"op://Vault/item/field\" or --env VAR_NAME. Value not echoed.";
+/**
+* The prompt path's versions of {@link LOOKS_LIKE_SECRET}.
+*
+* @remarks
+* Shorter, because a widget truncates its validation line to the terminal and
+* the flag path's explanation loses its point at 80 columns; and phrased for
+* someone typing into a field rather than passing a flag. Neither contains
+* the value.
+*/
+const SECRET_IN_REFERENCE = "That looks like a token, not a reference — enter where it lives.";
+const SECRET_IN_NAME = "That looks like a token, not a name. It was not stored.";
+/** What `--env` names, and what the prompt accepts for it: a shell variable identifier. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
 * Write credentials back to the file they were read from.
 *
@@ -63,6 +101,46 @@ const refuse = (message) => Effect.fail(new CliError.UserError({ cause: message
 /** How a profile's `github_token` is sourced, for display. Never a value. */
 const describeSource = (source) => "op" in source ? `op ${source.op}` : `env ${source.env}`;
 /**
+* Show a screen, mapping "nobody is there to answer" to a refusal.
+*
+* @remarks
+* The handlers decide interactivity up front with `CliInteractive` and refuse
+* before any screen when a run cannot prompt, so the `NotInteractive` mapped
+* here is defensive: should a screen ever be reached in such a run, it is the
+* same usage error (exit 64) naming the flag that would have answered it.
+* A cancel is the kit's `Cancelled` and is left alone, so `CliRuntime.main`
+* renders it as one line and exits 130.
+*/
+const ask = (screen, refusal, options) => CliUi.run(screen, options).pipe(Effect.catchTag("NotInteractive", () => refuse(refusal)));
+const MISSING_REFERENCE = "Provide a reference: --op \"op://Vault/item/field\" or --env REPOSETS_GITHUB_TOKEN. A token value is never accepted.";
+const MISSING_ACTS_AS = "Provide --username <you> for a personal account or --org <name> for an organization. It is what the profile acts as, and it decides which settings are even valid.";
+const MISSING_PROFILE = "Provide --profile <name>: the name a group's 'credentials' field refers to.";
+/**
+* Validate a token reference typed at the prompt.
+*
+* @remarks
+* The secret check runs first and on both kinds, so a pasted token is called
+* a token rather than getting a complaint about its shape. Every message here
+* fits a narrow terminal, is shown inside the screen, and none contains the
+* typed value.
+*/
+const validateReference = (kind) => (value) => {
+	if (value === "") return "A reference is required.";
+	if (looksLikeSecret(value)) return SECRET_IN_REFERENCE;
+	if (kind === "op" && !value.startsWith("op://")) return "A 1Password reference starts with \"op://\".";
+	if (kind === "env" && !ENV_NAME.test(value)) return "Letters, digits and underscores only, not starting with a digit.";
+};
+/**
+* A name typed at a prompt: anything but blank, and never a token.
+*
+* @remarks
+* A profile name becomes a TOML key and an owner name a stored value, and both
+* are printed in the confirmation — so a token pasted into either field would
+* be written to disk and echoed, the exact outcome the reference prompt
+* guards against.
+*/
+const validName = (what) => (value) => value.trim() === "" ? `${what} is required.` : looksLikeSecret(value) ? SECRET_IN_NAME : void 0;
+/**
 * `reposets credentials create` — record a *reference* to a GitHub token.
 *
 * @remarks
@@ -73,36 +151,109 @@ const describeSource = (source) => "op" in source ? `op ${source.op}` : `env ${s
 * variable — both are addresses, safe to appear in shell history and in this
 * command's own output.
 *
+* Whatever the flags leave out, an interactive run asks for, in order: the
+* profile name, who it acts as (personal account or organization, then the
+* name), and where the token is (1Password or an environment variable, then
+* the reference). The flags given are validated **before** any question, so a
+* person is never walked through a wizard only to be refused for a flag; two
+* conflicting flags (`--op` with `--env`, `--username` with `--org`) are
+* refused even on a terminal, since there is no question that resolves them.
+* A non-interactive run is refused exactly as before, the message naming the
+* flag to pass (exit 64).
+*
+* A token can be pasted into any text field, not only the reference: every
+* value — each flag and each typed answer — is checked with `looksLikeSecret`
+* and refused without being repeated, so nothing token-shaped becomes a
+* profile key, an owner or a reference, or reaches the confirmation line. The
+* text prompts' frames are cleared when they close, so a token typed and then
+* abandoned is not left in the terminal's scrollback; the accepted answers are
+* recorded in the confirmation line instead. While a value is being typed it
+* is visible — the kit's `TextInput` has no masked mode.
+*
 * `op_service_account_token` is likewise not accepted: it comes from the
 * environment, so there is nothing to write here.
 *
 * @public
 */
 const createHandler = (input) => Effect.gen(function* () {
-	const { profile, op, env, username, org } = input;
+	const { op, env, username, org } = input;
 	yield* (yield* AppDirs).ensureConfig;
 	const credentialsFile = yield* ReposetsCredentialsFile;
 	if (op !== void 0 && env !== void 0) return yield* refuse("Provide exactly one of --op or --env, not both.");
-	if (op === void 0 && env === void 0) return yield* refuse("Provide a reference: --op \"op://Vault/item/field\" or --env REPOSETS_GITHUB_TOKEN. A token value is never accepted.");
+	const interactive = yield* CliInteractive;
+	if (op === void 0 && env === void 0 && !interactive) return yield* refuse(MISSING_REFERENCE);
 	if (op !== void 0 && !op.startsWith("op://")) return yield* refuse("--op must be a 1Password reference starting with \"op://\". Value not echoed.");
-	if (looksLikeSecret(op ?? env ?? "")) return yield* refuse("That looks like a credential value, not a reference. This command stores references only — pass --op \"op://Vault/item/field\" or --env VAR_NAME. Value not echoed.");
+	if ([
+		op,
+		env,
+		input.profile,
+		username,
+		org
+	].some((value) => value !== void 0 && looksLikeSecret(value))) return yield* refuse(LOOKS_LIKE_SECRET);
 	if (username !== void 0 && org !== void 0) return yield* refuse("Provide exactly one of --username or --org, not both.");
-	if (username === void 0 && org === void 0) return yield* refuse("Provide --username <you> for a personal account or --org <name> for an organization. It is what the profile acts as, and it decides which settings are even valid.");
+	if (username === void 0 && org === void 0 && !interactive) return yield* refuse(MISSING_ACTS_AS);
+	if (input.profile === void 0 && !interactive) return yield* refuse(MISSING_PROFILE);
 	const existing = yield* credentialsFile.loadOrDefault(EMPTY);
-	if (existing.profiles[profile] !== void 0) return yield* refuse(`Profile '${profile}' already exists. Delete it first.`);
-	const github_token = op !== void 0 ? { op } : { env };
-	const actsAs = username !== void 0 ? {
-		username,
-		github_token
-	} : {
-		org,
+	const taken = (name) => existing.profiles[name] === void 0 ? void 0 : `Profile '${name}' already exists. Delete it first.`;
+	if (input.profile !== void 0) {
+		const problem = taken(input.profile);
+		if (problem !== void 0) return yield* refuse(problem);
+	}
+	const profile = input.profile ?? (yield* ask(TextInput.screen({
+		message: "Profile name",
+		placeholder: "personal",
+		validate: (value) => validName("A profile name")(value) ?? taken(value)
+	}), MISSING_PROFILE, { clear: true }));
+	const actsAs = username !== void 0 ? { username } : org !== void 0 ? { org } : yield* Effect.gen(function* () {
+		const kind = yield* ask(Select.screen({
+			message: "Who does this profile act as?",
+			choices: [{
+				label: "A personal account",
+				value: "username",
+				detail: "repositories you own"
+			}, {
+				label: "An organization",
+				value: "org",
+				detail: "repositories an organization owns"
+			}]
+		}), MISSING_ACTS_AS);
+		const what = kind === "username" ? "GitHub username" : "Organization name";
+		const name = yield* ask(TextInput.screen({
+			message: what,
+			validate: validName(`A ${what.toLowerCase()}`)
+		}), MISSING_ACTS_AS, { clear: true });
+		return kind === "username" ? { username: name } : { org: name };
+	});
+	const github_token = op !== void 0 ? { op } : env !== void 0 ? { env } : yield* Effect.gen(function* () {
+		const kind = yield* ask(Select.screen({
+			message: "Where is the GitHub token?",
+			choices: [{
+				label: "1Password",
+				value: "op",
+				detail: "an op:// secret reference"
+			}, {
+				label: "An environment variable",
+				value: "env",
+				detail: "e.g. in CI"
+			}]
+		}), MISSING_REFERENCE);
+		const reference = yield* ask(TextInput.screen({
+			message: kind === "op" ? "1Password reference" : "Environment variable name",
+			placeholder: kind === "op" ? "op://Vault/item/field" : "REPOSETS_GITHUB_TOKEN",
+			validate: validateReference(kind)
+		}), MISSING_REFERENCE, { clear: true });
+		return kind === "op" ? { op: reference } : { env: reference };
+	});
+	const record = {
+		...actsAs,
 		github_token
 	};
 	const path = yield* saveWhereRead(credentialsFile, { profiles: {
 		...existing.profiles,
-		[profile]: actsAs
+		[profile]: record
 	} });
-	yield* Console.log(`Created profile '${profile}' (${username !== void 0 ? `username: ${username}` : `org: ${org}`}, github_token: ${describeSource(github_token)}) in ${path}.`);
+	const { owner, ownerType } = profileOwner(record);
+	yield* CliMessage.success(`Created profile '${profile}' (${ownerType === "User" ? "username" : "org"}: ${owner}, github_token: ${describeSource(github_token)}) in ${path}.`);
 });
 const createCommand = Command.make("create", {
 	profile: profileFlag,
@@ -111,12 +262,17 @@ const createCommand = Command.make("create", {
 	username: usernameFlag,
 	org: orgFlag
 }, ({ profile, op, env, username, org }) => createHandler({
-	profile,
+	profile: Option.getOrUndefined(profile),
 	op: Option.getOrUndefined(op),
 	env: Option.getOrUndefined(env),
 	username: Option.getOrUndefined(username),
 	org: Option.getOrUndefined(org)
 })).pipe(Command.withDescription("Add a credential profile holding a reference to a GitHub token"));
+/** Who a profile acts as, for display. */
+const describeOwner = (profile) => {
+	const { owner, ownerType } = profileOwner(profile);
+	return `${owner} (${ownerType === "User" ? "user" : "organization"})`;
+};
 /**
 * `reposets credentials list` — the profiles and what they point at.
 *
@@ -125,47 +281,71 @@ const createCommand = Command.make("create", {
 * discloses which vault items and environment variables reposets reads, never
 * their contents — which is exactly what someone running this needs to see.
 *
+* Printed as one document, a section per profile, so the audience decides the
+* rendering: plain for an agent or a pipe, styled on a terminal.
+*
 * @public
 */
 const listHandler = Effect.gen(function* () {
 	const credentials = yield* (yield* ReposetsCredentialsFile).loadOrDefault(EMPTY);
-	if (Object.keys(credentials.profiles).length === 0) {
-		yield* Console.log("No credential profiles configured.");
+	const entries = Object.entries(credentials.profiles);
+	if (entries.length === 0) {
+		yield* CliMessage.info("No credential profiles configured.");
 		return;
 	}
-	for (const [name, profile] of Object.entries(credentials.profiles)) {
-		const { owner, ownerType } = profileOwner(profile);
-		yield* Console.log(`[${name}]`);
-		yield* Console.log(`  acts as: ${owner} (${ownerType === "User" ? "user" : "organization"})`);
-		yield* Console.log(`  github_token: ${describeSource(profile.github_token)}`);
+	yield* Doc.print(entries.map(([name, profile]) => {
+		const lines = [`acts as: ${describeOwner(profile)}`, `github_token: ${describeSource(profile.github_token)}`];
 		for (const kind of [
 			"op",
 			"env",
 			"file"
 		]) {
-			const entries = profile.resolve?.[kind];
-			if (entries === void 0) continue;
-			for (const [label, reference] of Object.entries(entries)) yield* Console.log(`  resolve.${kind}.${label}: ${reference}`);
+			const resolved = profile.resolve?.[kind];
+			if (resolved === void 0) continue;
+			for (const [label, reference] of Object.entries(resolved)) lines.push(`resolve.${kind}.${label}: ${reference}`);
 		}
-		yield* Console.log("");
-	}
+		return Doc.section(`[${name}]`, [Doc.lines(lines)]);
+	}));
 });
 const listCommand = Command.make("list", {}, () => listHandler).pipe(Command.withDescription("List credential profiles and the references they hold"));
 /**
 * `reposets credentials delete` — remove a profile.
 *
+* @remarks
+* Without `--profile`, an interactive run picks from the existing profiles —
+* each shown with who it acts as and its token reference, never a value — and
+* a non-interactive run is refused naming `--profile` (exit 64). With no
+* profiles at all there is nothing to pick, which is said and succeeds.
+*
+* @param profile - the profile to remove, or `undefined` when the flag was omitted
+*
 * @public
 */
 const deleteHandler = (profile) => Effect.gen(function* () {
 	yield* (yield* AppDirs).ensureConfig;
+	if (profile === void 0 && !(yield* CliInteractive)) return yield* refuse("Provide --profile <name>: the profile to delete.");
+	if (profile !== void 0 && looksLikeSecret(profile)) return yield* refuse(LOOKS_LIKE_SECRET);
 	const credentialsFile = yield* ReposetsCredentialsFile;
 	const credentials = yield* credentialsFile.loadOrDefault(EMPTY);
-	if (credentials.profiles[profile] === void 0) return yield* refuse(`Profile '${profile}' not found.`);
-	const { [profile]: _removed, ...remaining } = credentials.profiles;
+	const entries = Object.entries(credentials.profiles);
+	if (profile === void 0 && entries.length === 0) {
+		yield* CliMessage.info("No credential profiles configured — nothing to delete.");
+		return;
+	}
+	const name = profile ?? (yield* ask(Select.screen({
+		message: "Delete which profile?",
+		choices: entries.map(([key, value]) => ({
+			label: key,
+			value: key,
+			detail: `${describeOwner(value)} · github_token: ${describeSource(value.github_token)}`
+		}))
+	}), "Provide --profile <name>: the profile to delete."));
+	if (credentials.profiles[name] === void 0) return yield* refuse(`Profile '${name}' not found.`);
+	const { [name]: _removed, ...remaining } = credentials.profiles;
 	const path = yield* saveWhereRead(credentialsFile, { profiles: remaining });
-	yield* Console.log(`Deleted profile '${profile}' from ${path}.`);
+	yield* CliMessage.success(`Deleted profile '${name}' from ${path}.`);
 });
-const deleteCommand = Command.make("delete", { profile: profileFlag }, ({ profile }) => deleteHandler(profile)).pipe(Command.withDescription("Remove a credential profile"));
+const deleteCommand = Command.make("delete", { profile: profileFlag }, ({ profile }) => deleteHandler(Option.getOrUndefined(profile))).pipe(Command.withDescription("Remove a credential profile"));
 /**
 * `reposets credentials` — manage `reposets.credentials.toml`.
 *