reposets 0.4.2 → 1.0.0

package/README.md

@@ -3,25 +3,13 @@
 [![npm](https://img.shields.io/npm/v/reposets?label=npm&color=cb3837)](https://www.npmjs.com/package/reposets)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
-[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Declarative GitHub repository management. Define your repo settings, secrets, variables, rulesets, deployment environments, advanced security toggles, and CodeQL default setup in a TOML config file, then apply them across all your repositories with a single command.
+Declarative GitHub repository management. Define repository settings, secrets, variables, rulesets, deployment environments, security toggles and CodeQL default setup in a TOML file, then apply them across every repository you own with one command.
 
 ## Why reposets
 
-Managing repository settings by hand doesn't scale. When you have dozens of repos that should share the same branch protection rules, CI secrets, and merge settings, clicking through the GitHub UI for each one is slow and error-prone. reposets lets you define that configuration once and sync it everywhere.
-
-## Features
-
-- **Git-committable config templates** — Your entire repo configuration lives in a TOML file that is safe to commit, review, and share. Sensitive values are never stored in the config itself.
-- **Resolvable values** — Secrets and integer fields reference named labels that resolve at sync time from 1Password, local files, or inline values in a separate credentials file. One config template works across environments.
-- **Multi-scope secret and variable management** — Assign the same secret group to Actions, Dependabot, Codespaces, and deployment environments with scoped targeting.
-- **Ruleset shorthand syntax** — Define branch and tag rulesets with compact inline syntax for pull request rules, status checks, and boolean flags instead of verbose API payloads.
-- **Deployment environment management** — Configure wait timers, reviewers, and branch policies for deployment environments alongside your other settings.
-- **Advanced security and CodeQL** — Toggle secret scanning, push protection, vulnerability alerts, automated security fixes, private vulnerability reporting, and CodeQL default setup. License- and ownership-aware: GHAS-licensed fields warn instead of failing on private repos without a license, and org-only fields are silently skipped on personal accounts.
-- **Group-based targeting** — Organize repos into groups that share settings, secrets, variables, rulesets, environments, security toggles, and code scanning configuration. Change the group config, sync once, and every repo updates.
-- **Cleanup policies** — Automatically remove undeclared resources per scope with optional preserve lists, so your repos converge to the declared state.
-- **Dry-run and validation** — Preview changes before applying, validate config locally without touching the GitHub API, and catch typos with built-in diagnostics.
+Managing repository settings by hand does not scale. Once a dozen repositories should share the same branch protection, CI secrets and merge settings, clicking through the GitHub UI for each one is slow and easy to get subtly wrong. reposets lets you declare that configuration once and converge every repository onto it, then tells you when someone changes a repository outside the tool.
 
 ## Install
 
@@ -29,7 +17,7 @@ Managing repository settings by hand doesn't scale. When you have dozens of repo
 npm install -g reposets
 ```
 
-Alternative (no install):
+Or run it without installing:
 
 ```bash
 npx reposets <command>
@@ -39,102 +27,126 @@ Requires the Node.js version shown in the badge above.
 
 ## Quick start
 
-1. Run `reposets init` to scaffold config files.
-2. Add a credential profile:
+Scaffold the config files in the current directory:
 
-   ```bash
-   reposets credentials create --profile personal --github-token ghp_...
-   ```
+```bash
+reposets init --project
+# Created: ./reposets.config.toml
+# Created: ./reposets.credentials.toml
+# Created .gitignore with reposets.credentials.toml
+```
 
-3. Edit `reposets.config.toml` with your repos and settings:
+Add a credential profile. It records *where* your token lives, never the token itself:
 
-   ```toml
-   owner = "your-username"
+```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.
+```
 
-   [settings.default]
-   has_wiki = false
-   delete_branch_on_merge = true
+Use `--env REPOSETS_GITHUB_TOKEN` in place of `--op` to read the token from the environment instead of 1Password.
 
-   [groups.my-repos]
-   repos = ["repo-one", "repo-two"]
-   settings = ["default"]
-   ```
+Declare what should apply to which repositories in `reposets.config.toml`:
 
-4. Validate your config:
+```toml
+[settings.default]
+has_wiki = false
+delete_branch_on_merge = true
 
-   ```bash
-   reposets validate
-   ```
+[groups.my-repos]
+repos = ["repo-one", "repo-two"]
+credentials = "personal"
+settings = ["default"]
+```
 
-5. Preview changes without applying them:
+Check it, preview it, then apply it:
 
-   ```bash
-   reposets sync --dry-run
-   ```
+```bash
+reposets validate
+# Valid: ./reposets.config.toml
+#   groups: 1
 
-6. Apply the config:
+reposets sync --dry-run
+reposets sync
+```
+
+The owner is not in the config. It belongs to the credential profile, which declares `username` or `org`, and every group names the profile it is synced as.
+
+## Features
 
-   ```bash
-   reposets sync
-   ```
+- **Config you can commit.** The whole declaration lives in one TOML file that is safe to review and share. No secret value is ever stored in it.
+- **References, not secrets.** Tokens and sensitive values are addresses resolved at sync time from 1Password, environment variables or files. The credentials file discloses nothing if it leaks.
+- **Multi-account in one run.** Each group names the credential profile it authenticates as, so a single config can span your personal account and an organization.
+- **Drift detection.** `reposets drift` reports resources changed outside the tool and exits non-zero, without writing anything, so it gates CI on its own.
+- **Multi-scope secrets and variables.** Assign the same group to Actions, Dependabot, Codespaces and deployment environments.
+- **Ruleset shorthand.** Branch and tag rulesets written as compact tables instead of raw API payloads, with resolved references for App and integration IDs.
+- **Deployment environments.** Wait timers, reviewers and branch policies alongside everything else, synced before the secrets scoped to them.
+- **Security and CodeQL.** Secret scanning, push protection, vulnerability alerts, automated fixes, private reporting and CodeQL default setup. License- and ownership-aware: unlicensed GHAS fields warn instead of failing, and organization-only fields are rejected offline for personal accounts.
+- **Cleanup policies.** Remove undeclared resources per scope, with preserve lists, so repositories converge on the declared state.
+- **Offline validation.** `reposets validate` checks schema, reference integrity, organization-only constructs and undeclared credential labels without a token or a network call.
+- **Run history.** Every run is journalled. `reposets history` shows what happened and `history show` lists every resource one run touched.
 
 ## Commands
 
 | Command | Description |
 | :--- | :--- |
-| `reposets sync` | Apply config to repos (supports --dry-run, --group, --repo, --no-cleanup) |
-| `reposets list` | Show config summary |
-| `reposets validate` | Validate config without API calls |
-| `reposets doctor` | Deep diagnostics with typo detection |
-| `reposets init` | Scaffold config files (--project for local) |
-| `reposets credentials` | Manage credential profiles (create, list, delete) |
-
-All commands accept `--log-level silent|info|verbose|debug`.
+| `reposets sync` | Apply the config. Supports `--dry-run`, `--group`, `--repo`, `--only`, `--skip`, `--no-cleanup`, `--fail-on-drift`, `--debug` |
+| `reposets drift` | Report resources changed outside reposets and exit non-zero. Changes nothing |
+| `reposets list` | Show a config summary by group |
+| `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 nuke` | Delete every local reposets file. Nothing on GitHub is touched |
+| `reposets credentials` | Manage credential profiles: `create`, `list`, `delete` |
+
+Every command accepts `--config` and the `--log-level` filter Effect core provides. `--log-level error` is quiet on success and loud on failure; `--log-level none` is the CI form.
 
 ## Configuration
 
-reposets uses two TOML files:
-
-- `reposets.config.toml` — defines settings, secrets, variables, rulesets, environments, security, code_scanning, and groups
-- `reposets.credentials.toml` — stores GitHub tokens and optional resolve sections for named values
+reposets reads two TOML files:
 
-Config lookup order (first match wins):
+- `reposets.config.toml` — settings, security, code scanning, environments, secrets, variables, rulesets and the groups tying them to repositories
+- `reposets.credentials.toml` — named profiles declaring the account each acts as and where its token lives
 
-1. `--config` flag (explicit path or directory)
-2. Walk up from current directory looking for `reposets.config.toml`
-3. XDG fallback: `~/.config/reposets/reposets.config.toml`
+Lookup order for the config, first match wins:
 
-See the [docs/](https://github.com/spencerbeggs/reposets/tree/main/docs) folder for full reference on configuration, credentials, secrets, rulesets, environments, cleanup, and token setup.
+1. The `--config` flag, a file path or a directory
+2. Walking up from the current directory
+3. `~/.config/reposets/reposets.config.toml`, respecting `$XDG_CONFIG_HOME`
 
 ## Token permissions
 
-reposets requires a fine-grained personal access token with:
+reposets needs a fine-grained personal access token with:
 
 - Repository > Administration (Read and write)
 - Repository > Secrets (Read and write)
 - Repository > Variables (Read and write)
 - Repository > Environments (Read and write)
+- Repository > Dependabot secrets (Read and write)
+- Repository > Actions (**Read**) — counts workflow files for the `actions` CodeQL language
 - Repository > Code scanning alerts (Read and write) — for `[code_scanning.*]`
 - Repository > Dependabot alerts (Read and write) — for `[security.*]`
 - Repository > Secret scanning alerts (Read and write) — for `security_and_analysis`
-- Organization > Members (Read) — for `delegated_bypass_reviewers` team slugs on org-owned repos
-- Account > GPG keys (Read and write)
+- Organization > Members (Read) — resolve team slugs on org-owned repositories
 
-The four security-related scopes are only required if you use the corresponding config sections.
+The last five are only needed if you use the matching config sections. No account-level permission is required. `reposets doctor` prints this list and checks that your token resolves and authenticates.
 
 ## Documentation
 
-Full reference guides are available in the [`docs/`](https://github.com/spencerbeggs/reposets/tree/main/docs) folder:
-
-- [Commands Reference](https://github.com/spencerbeggs/reposets/blob/main/docs/commands.md) - all commands, flags, and usage examples
-- [Configuration](https://github.com/spencerbeggs/reposets/blob/main/docs/configuration.md) - config file format, path resolution, and settings reference
-- [Credentials](https://github.com/spencerbeggs/reposets/blob/main/docs/credentials.md) - credential profiles, resolve sections, and 1Password integration
-- [Secrets and Variables](https://github.com/spencerbeggs/reposets/blob/main/docs/secrets-and-variables.md) - resource groups, three kinds (file/value/resolved), and scoping
-- [Rulesets](https://github.com/spencerbeggs/reposets/blob/main/docs/rulesets.md) - branch and tag ruleset configuration
-- [Environments](https://github.com/spencerbeggs/reposets/blob/main/docs/environments.md) - deployment environment setup
-- [Advanced Security](https://github.com/spencerbeggs/reposets/blob/main/docs/configuration.md#security-and-analysis-nested-block) - secret scanning, vulnerability alerts, automated security fixes, private vulnerability reporting, and CodeQL default setup
-- [Cleanup](https://github.com/spencerbeggs/reposets/blob/main/docs/cleanup.md) - automatic cleanup of undeclared resources
-- [Token Permissions](https://github.com/spencerbeggs/reposets/blob/main/docs/token-permissions.md) - GitHub PAT setup guide
+- [Migrating to 1.0](https://github.com/spencerbeggs/reposets/blob/main/docs/01-migrating-to-1.0.md) — before-and-after TOML for every breaking change
+- [Commands](https://github.com/spencerbeggs/reposets/blob/main/docs/02-commands.md) — every command and flag, with output
+- [Configuration](https://github.com/spencerbeggs/reposets/blob/main/docs/03-configuration.md) — file format, path resolution and the settings reference
+- [Credentials](https://github.com/spencerbeggs/reposets/blob/main/docs/04-credentials.md) — profiles, owners, token references and resolve sections
+- [Secrets and variables](https://github.com/spencerbeggs/reposets/blob/main/docs/05-secrets-and-variables.md) — the three group kinds and how scoping works
+- [Rulesets](https://github.com/spencerbeggs/reposets/blob/main/docs/06-rulesets.md) — branch and tag rulesets, every field and the shorthand forms
+- [Environments](https://github.com/spencerbeggs/reposets/blob/main/docs/07-environments.md) — deployment environments, reviewers and branch policies
+- [Advanced security](https://github.com/spencerbeggs/reposets/blob/main/docs/03-configuration.md#security-and-analysis-block) — secret scanning, vulnerability alerts and CodeQL default setup
+- [Cleanup](https://github.com/spencerbeggs/reposets/blob/main/docs/08-cleanup.md) — removing resources the config no longer declares
+- [Token permissions](https://github.com/spencerbeggs/reposets/blob/main/docs/09-token-permissions.md) — which scopes are needed, and why
+
+## 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.
 
 ## License
 

package/bin/reposets.js

@@ -1,34 +1,85 @@
 #!/usr/bin/env node
+import { CredentialsFilesLive } from "../services/ConfigFiles.js";
+import { formatSchemaIssue } from "../lib/schema-issues.js";
+import { migrations } from "../store/migrations.js";
+import { SyncJournalLive } from "../store/SyncJournal.js";
 import { credentialsCommand } from "../cli/commands/credentials.js";
+import { ConfigFlag, ConfigLive } from "../cli/flags.js";
 import { doctorCommand } from "../cli/commands/doctor.js";
+import { syncCommand } from "../cli/commands/sync.js";
+import { driftCommand } from "../cli/commands/drift.js";
+import { historyCommand } from "../cli/commands/history.js";
 import { initCommand } from "../cli/commands/init.js";
 import { listCommand } from "../cli/commands/list.js";
-import { syncCommand } from "../cli/commands/sync.js";
+import { nukeCommand } from "../cli/commands/nuke.js";
 import { validateCommand } from "../cli/commands/validate.js";
-import { Effect, LogLevel, Logger } from "effect";
-import { Command } from "@effect/cli";
-import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { CliLoggerLive } from "../cli/logger.js";
+import { Effect, Layer } from "effect";
+import { App } from "@effected/app";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Command } from "effect/unstable/cli";
 
 //#region src/cli/index.ts
-const CliLogger = Logger.replace(Logger.defaultLogger, Logger.make(({ logLevel, message }) => {
-	const text = typeof message === "string" ? message : String(message);
-	if (LogLevel.greaterThanEqual(logLevel, LogLevel.Error)) globalThis.console.error(text);
-	else globalThis.console.log(text);
-}));
-const rootCommand = Command.make("reposets").pipe(Command.withSubcommands([
+/**
+* The application control plane.
+*
+* @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.
+*
+* Migrations run during layer construction, so a fresh checkout gets its schema
+* on the first command rather than on first write.
+*/
+const AppLive = App.layer({
+	namespace: "reposets",
+	store: { migrations }
+});
+/**
+* The root command.
+*
+* @remarks
+* `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.
+*/
+const cli = Command.make("reposets", {}, () => Effect.void).pipe(Command.withDescription("Sync GitHub repository settings across repos from a TOML config"), Command.withSubcommands([
+	validateCommand,
 	syncCommand,
 	listCommand,
-	validateCommand,
 	doctorCommand,
+	driftCommand,
 	initCommand,
+	nukeCommand,
+	historyCommand,
 	credentialsCommand
-]));
-const cli = Command.run(rootCommand, {
-	name: "reposets",
-	version: "0.0.0"
+]), Command.provide(ConfigLive), Command.provide(CredentialsFilesLive), Command.provide(SyncJournalLive), Command.withGlobalFlags([ConfigFlag]));
+const MainLive = Layer.mergeAll(Layer.provideMerge(AppLive, NodeServices.layer), CliLoggerLive);
+/**
+* Report a failure through the CLI logger and exit non-zero.
+*
+* @remarks
+* `NodeRuntime.runMain` reports an unhandled failure with Effect's *default*
+* logger, which sits outside the layers the program was provided — so a failure
+* escaping to it prints `[23:05:56] ERROR (#2): …` **on stdout**, in the format
+* {@link CliLoggerLive} exists to replace, on the stream errors must not use.
+*
+* Catching here keeps the failure inside the logger's scope. The exit code is
+* then ours to set, since the effect now succeeds.
+*/
+const reportAndExit = (error) => Effect.gen(function* () {
+	yield* Effect.logError(String(error));
+	if (isTagged(error, "ConfigValidationError")) {
+		const lines = formatSchemaIssue(error.issue);
+		for (const line of lines) yield* Effect.logError(`  ${line}`);
+		if (lines.some((line) => line.startsWith("unknown key"))) yield* Effect.logError("  Run 'reposets doctor' for suggested spellings.");
+	}
+	yield* Effect.sync(() => {
+		process.exitCode = 1;
+	});
 });
-const program = Effect.suspend(() => cli(process.argv)).pipe(Effect.provide(NodeContext.layer), Effect.provide(CliLogger));
-NodeRuntime.runMain(program);
+/** Whether a caught value is a tagged error of a given tag. */
+const isTagged = (error, tag) => typeof error === "object" && error !== null && "_tag" in error && error._tag === tag;
+cli.pipe(Command.run({ version: "1.0.0" }), Effect.catch(reportAndExit), Effect.provide(MainLive), NodeRuntime.runMain);
 
 //#endregion
 export {  };

package/cli/commands/credentials.js

@@ -1,74 +1,195 @@
-import { ReposetsCredentialsFile, makeConfigFilesLive } from "../../services/ConfigFiles.js";
-import { AppDirs } from "xdg-effect";
+import { profileOwner } from "../../schemas/credentials.js";
+import { ReposetsCredentialsFile } from "../../services/ConfigFiles.js";
 import { Effect, Option } from "effect";
-import { Command, Options } from "@effect/cli";
+import { Command, Flag } from "effect/unstable/cli";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/cli/commands/credentials.ts
-const EMPTY_CREDENTIALS = { profiles: {} };
-const profileOption = Options.text("profile").pipe(Options.withDescription("Credential profile name"));
-const githubTokenOption = Options.text("github-token").pipe(Options.withDescription("GitHub personal access token"), Options.optional);
-const opTokenOption = Options.text("op-token").pipe(Options.withDescription("1Password service account token"), Options.optional);
-function redactToken(token) {
-	if (token.length <= 8) return "****";
-	return `${token.slice(0, 4)}...${token.slice(-4)}`;
-}
-const createCommand = Command.make("create", {
-	profile: profileOption,
-	githubToken: githubTokenOption,
-	opToken: opTokenOption
-}, ({ profile, githubToken, opToken }) => Effect.gen(function* () {
+const EMPTY = { profiles: {} };
+const profileFlag = Flag.string("profile").pipe(Flag.withDescription("Credential profile name"));
+const opFlag = Flag.string("op").pipe(Flag.withDescription("1Password secret reference, e.g. \"op://Vault/item/field\""), Flag.optional);
+const envFlag = Flag.string("env").pipe(Flag.withDescription("Name of an environment variable holding the token, e.g. \"REPOSETS_GITHUB_TOKEN\""), Flag.optional);
+const usernameFlag = Flag.string("username").pipe(Flag.withDescription("The personal account this profile acts as. Mutually exclusive with --org"), Flag.optional);
+const orgFlag = Flag.string("org").pipe(Flag.withDescription("The organization this profile acts within. Mutually exclusive with --username"), Flag.optional);
+/**
+* Recognisable credential prefixes, so an obvious paste-in-the-wrong-place is
+* caught rather than stored.
+*
+* @remarks
+* A heuristic, not a guarantee — `--env` legitimately takes a bare identifier
+* and a token can look like one. It costs nothing and catches the mistake this
+* command's entire premise is built to prevent.
+*/
+const SECRET_PREFIXES = [
+	"ghp_",
+	"gho_",
+	"ghu_",
+	"ghs_",
+	"ghr_",
+	"github_pat_",
+	"ops_",
+	"sk-",
+	"xoxb-"
+];
+const looksLikeSecret = (value) => SECRET_PREFIXES.some((prefix) => value.startsWith(prefix)) || value.length > 60;
+/**
+* Write credentials back to the file they were read from.
+*
+* @remarks
+* `ConfigFileShape.save` resolves its own default path — the XDG one — rather
+* than the path `discover` found. With a project-local
+* `reposets.credentials.toml` present, that splits reads from writes: `create`
+* lands in XDG while `list` keeps reading the local file, so a profile is
+* created that the user cannot see and that sync will not use. Writing back to
+* the discovered source keeps one file authoritative, and falls back to `save`
+* only when there is genuinely nothing to update.
+*/
+const saveWhereRead = (file, value) => Effect.gen(function* () {
+	const existing = (yield* file.discover.pipe(Effect.orElseSucceed(() => [])))[0];
+	if (existing === void 0) return yield* file.save(value);
+	yield* file.write(value, existing.path);
+	return existing.path;
+});
+/** 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}`;
+/**
+* `reposets credentials create` — record a *reference* to a GitHub token.
+*
+* @remarks
+* **This command never accepts a token.** v3 took `--github-token` and
+* `--op-token` and wrote both into the file; the schema now stores a reference
+* and nothing else, so there is no field to put a secret in and no prompt that
+* would read one. `--op` names a 1Password item, `--env` names an environment
+* variable — both are addresses, safe to appear in shell history and in this
+* command's own output.
+*
+* `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;
 	yield* (yield* AppDirs).ensureConfig;
 	const credentialsFile = yield* ReposetsCredentialsFile;
-	if ((yield* credentialsFile.loadOrDefault(EMPTY_CREDENTIALS)).profiles[profile]) {
-		yield* Effect.logError(`Profile '${profile}' already exists. Delete it first.`);
+	if (op !== void 0 && env !== void 0) {
+		yield* Effect.logError("Provide exactly one of --op or --env, not both.");
 		return;
 	}
-	const newProfile = {};
-	if (githubToken._tag === "Some") newProfile.github_token = githubToken.value;
-	if (opToken._tag === "Some") newProfile.op_service_account_token = opToken.value;
-	if (!newProfile.github_token && !newProfile.op_service_account_token) {
-		yield* Effect.logError("Provide at least --github-token or --op-token.");
+	if (op === void 0 && env === void 0) {
+		yield* Effect.logError("Provide a reference: --op \"op://Vault/item/field\" or --env REPOSETS_GITHUB_TOKEN. A token value is never accepted.");
 		return;
 	}
-	yield* credentialsFile.update((current) => ({ profiles: {
-		...current.profiles,
-		[profile]: {
-			github_token: newProfile.github_token ?? "",
-			...newProfile
-		}
-	} }), EMPTY_CREDENTIALS);
-	yield* Effect.log(`Created profile '${profile}'.`);
-}).pipe(Effect.provide(makeConfigFilesLive(Option.none())))).pipe(Command.withDescription("Add a credential profile"));
-const listCredsCommand = Command.make("list", {}, () => Effect.gen(function* () {
-	const creds = yield* (yield* ReposetsCredentialsFile).loadOrDefault(EMPTY_CREDENTIALS);
-	if (Object.keys(creds.profiles).length === 0) {
+	if (op !== void 0 && !op.startsWith("op://")) {
+		yield* Effect.logError("--op must be a 1Password reference starting with \"op://\". Value not echoed.");
+		return;
+	}
+	if (looksLikeSecret(op ?? env ?? "")) {
+		yield* Effect.logError("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.");
+		return;
+	}
+	if (username !== void 0 && org !== void 0) {
+		yield* Effect.logError("Provide exactly one of --username or --org, not both.");
+		return;
+	}
+	if (username === void 0 && org === void 0) {
+		yield* Effect.logError("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.");
+		return;
+	}
+	const existing = yield* credentialsFile.loadOrDefault(EMPTY);
+	if (existing.profiles[profile] !== void 0) {
+		yield* Effect.logError(`Profile '${profile}' already exists. Delete it first.`);
+		return;
+	}
+	const github_token = op !== void 0 ? { op } : { env };
+	const actsAs = username !== void 0 ? {
+		username,
+		github_token
+	} : {
+		org,
+		github_token
+	};
+	const path = yield* saveWhereRead(credentialsFile, { profiles: {
+		...existing.profiles,
+		[profile]: actsAs
+	} });
+	yield* Effect.log(`Created profile '${profile}' (${username !== void 0 ? `username: ${username}` : `org: ${org}`}, github_token: ${describeSource(github_token)}) in ${path}.`);
+});
+const createCommand = Command.make("create", {
+	profile: profileFlag,
+	op: opFlag,
+	env: envFlag,
+	username: usernameFlag,
+	org: orgFlag
+}, ({ profile, op, env, username, org }) => createHandler({
+	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"));
+/**
+* `reposets credentials list` — the profiles and what they point at.
+*
+* @remarks
+* There is nothing to redact. The file holds references, so printing it in full
+* discloses which vault items and environment variables reposets reads, never
+* their contents — which is exactly what someone running this needs to see.
+*
+* @public
+*/
+const listHandler = Effect.gen(function* () {
+	const credentials = yield* (yield* ReposetsCredentialsFile).loadOrDefault(EMPTY);
+	if (Object.keys(credentials.profiles).length === 0) {
 		yield* Effect.log("No credential profiles configured.");
 		return;
 	}
-	for (const [name, profile] of Object.entries(creds.profiles)) {
+	for (const [name, profile] of Object.entries(credentials.profiles)) {
+		const { owner, ownerType } = profileOwner(profile);
 		yield* Effect.log(`[${name}]`);
-		if (profile.github_token) yield* Effect.log(`  github_token: ${redactToken(profile.github_token)}`);
-		if (profile.op_service_account_token) yield* Effect.log(`  op_service_account_token: ${redactToken(profile.op_service_account_token)}`);
+		yield* Effect.log(`  acts as: ${owner} (${ownerType === "User" ? "user" : "organization"})`);
+		yield* Effect.log(`  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* Effect.log(`  resolve.${kind}.${label}: ${reference}`);
+		}
 		yield* Effect.log("");
 	}
-}).pipe(Effect.provide(makeConfigFilesLive(Option.none())))).pipe(Command.withDescription("List profiles (tokens redacted)"));
-const deleteCommand = Command.make("delete", { profile: profileOption }, ({ profile }) => Effect.gen(function* () {
+});
+const listCommand = Command.make("list", {}, () => listHandler).pipe(Command.withDescription("List credential profiles and the references they hold"));
+/**
+* `reposets credentials delete` — remove a profile.
+*
+* @public
+*/
+const deleteHandler = (profile) => Effect.gen(function* () {
 	yield* (yield* AppDirs).ensureConfig;
 	const credentialsFile = yield* ReposetsCredentialsFile;
-	const creds = yield* credentialsFile.loadOrDefault(EMPTY_CREDENTIALS);
-	if (!creds.profiles[profile]) {
+	const credentials = yield* credentialsFile.loadOrDefault(EMPTY);
+	if (credentials.profiles[profile] === void 0) {
 		yield* Effect.logError(`Profile '${profile}' not found.`);
 		return;
 	}
-	const { [profile]: _, ...remainingProfiles } = creds.profiles;
-	yield* credentialsFile.save({ profiles: remainingProfiles });
-	yield* Effect.log(`Deleted profile '${profile}'.`);
-}).pipe(Effect.provide(makeConfigFilesLive(Option.none())))).pipe(Command.withDescription("Remove a profile"));
-const credentialsCommand = Command.make("credentials").pipe(Command.withDescription("Manage credential profiles"), Command.withSubcommands([
+	const { [profile]: _removed, ...remaining } = credentials.profiles;
+	const path = yield* saveWhereRead(credentialsFile, { profiles: remaining });
+	yield* Effect.log(`Deleted profile '${profile}' from ${path}.`);
+});
+const deleteCommand = Command.make("delete", { profile: profileFlag }, ({ profile }) => deleteHandler(profile)).pipe(Command.withDescription("Remove a credential profile"));
+/**
+* `reposets credentials` — manage `reposets.credentials.toml`.
+*
+* @public
+*/
+const credentialsCommand = Command.make("credentials", {}, () => Effect.void).pipe(Command.withDescription("Manage credential profiles (references only — never token values)"), Command.withSubcommands([
 	createCommand,
-	listCredsCommand,
+	listCommand,
 	deleteCommand
 ]));
 
 //#endregion
-export { credentialsCommand };
+export { createHandler, credentialsCommand, deleteHandler, listHandler };