reposets 0.4.2 → 1.0.0

package/cli/commands/doctor.js

@@ -1,14 +1,19 @@
-import { ReposetsConfigFile, makeConfigFilesLive } from "../../services/ConfigFiles.js";
-import { Effect } from "effect";
-import { readFileSync } from "node:fs";
-import { Command, Options } from "@effect/cli";
-import { parse } from "smol-toml";
+import { SettingsGroupSchema } from "../../schemas/config.js";
+import { profileOwner } from "../../schemas/credentials.js";
+import { CONFIG_FILENAME, CREDENTIALS_FILENAME, ReposetsConfigFile, ReposetsCredentialsFile } from "../../services/ConfigFiles.js";
+import { formatSchemaIssue } from "../../lib/schema-issues.js";
+import { OP_SERVICE_ACCOUNT_TOKEN, OnePasswordClientLive } from "../../services/OnePasswordClient.js";
+import { CredentialResolver, CredentialResolverLive } from "../../services/CredentialResolver.js";
+import { ConfigFlag } from "../flags.js";
+import { Effect, FileSystem, Layer, Option, Path, Result } from "effect";
+import { Command } from "effect/unstable/cli";
+import { AppDirs } from "@effected/xdg";
+import { cwd, env } from "node:process";
+import { GitHubClient } from "@effected/github";
+import { Toml } from "@effected/toml";
 
 //#region src/cli/commands/doctor.ts
-const configOption = Options.file("config").pipe(Options.withDescription("Path to config directory or reposets.config.toml file"), Options.optional);
-const KNOWN_CONFIG_KEYS = new Set([
-	"owner",
-	"log_level",
+const KNOWN_CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"settings",
 	"secrets",
 	"variables",
@@ -18,8 +23,7 @@ const KNOWN_CONFIG_KEYS = new Set([
 	"code_scanning",
 	"groups"
 ]);
-const KNOWN_GROUP_KEYS = new Set([
-	"owner",
+const KNOWN_GROUP_KEYS = /* @__PURE__ */ new Set([
 	"repos",
 	"credentials",
 	"settings",
@@ -31,20 +35,141 @@ const KNOWN_GROUP_KEYS = new Set([
 	"code_scanning",
 	"cleanup"
 ]);
-const KNOWN_CLEANUP_KEYS = new Set([
+/**
+* Keys 1.0 removed, and where each one went.
+*
+* @remarks
+* Every config written before 1.0 carries at least one of these, so this is the
+* upgrade path rather than an edge case. Strict decoding already rejects them —
+* the schema section says so — but "unknown key" is the wrong sentence for a key
+* that did not vanish so much as move, and the nearest-match hint is actively
+* misleading for one: `owner` is three edits from `repos`.
+*
+* Keyed by the same `where` suffix the warning uses, because `owner` was removed
+* from two places and means something different in each.
+*/
+const REMOVED_KEYS = {
+	owner: "removed in 1.0 — the owner now belongs to the credential profile, which declares `username` or `org`",
+	"owner (in groups)": "removed in 1.0 — a group's owner comes from the profile named by its `credentials`, so a group cannot override it",
+	log_level: "removed in 1.0 — output is one level; use --debug for diagnostics, or core's --log-level to filter by severity"
+};
+/**
+* The settings fields the schema names, derived rather than listed.
+*
+* @remarks
+* `SettingsGroupSchema` is a struct **with a rest schema**, so an unrecognised
+* field is absorbed and passed through to GitHub deliberately — that is how a
+* setting GitHub adds tomorrow works without a release here.
+*
+* The cost is that a typo is indistinguishable from a new field: `has_wikkis`
+* decodes cleanly, gets PATCHed, is ignored by GitHub because it recognises no
+* such field, and is then **reported as applied**. Two gates miss it — strict
+* decoding cannot object, and doctor's hand-written key sets never covered
+* settings — so a misspelled setting silently does nothing for as long as it
+* stays in the file.
+*
+* A warning rather than an error, because pass-through is intentional and this
+* cannot tell a typo from a field newer than our schema. Read off the schema so
+* it cannot drift from it; a second hand-maintained list is how the first one
+* went stale.
+*/
+const KNOWN_SETTINGS_FIELDS = new Set(Object.keys(SettingsGroupSchema.schema.fields));
+const KNOWN_CLEANUP_KEYS = /* @__PURE__ */ new Set([
 	"secrets",
 	"variables",
 	"rulesets",
 	"environments"
 ]);
-const KNOWN_CLEANUP_SECRETS_KEYS = new Set([
+const KNOWN_CLEANUP_SECRETS_KEYS = /* @__PURE__ */ new Set([
 	"actions",
 	"dependabot",
 	"codespaces",
 	"environments"
 ]);
-const KNOWN_CLEANUP_VARIABLES_KEYS = new Set(["actions", "environments"]);
-function findClosestMatch(key, known) {
+const KNOWN_CLEANUP_VARIABLES_KEYS = /* @__PURE__ */ new Set(["actions", "environments"]);
+/**
+* The fine-grained token permissions a full sync needs.
+*
+* @remarks
+* Corrected from v3, which listed `Account permissions > GPG keys` as the
+* "secrets encryption key" scope. That is wrong. The public keys used to seal
+* secrets come from repository-scoped endpoints
+* (`GET /repos/{o}/{r}/actions/secrets/public-key` and the dependabot,
+* codespaces and environment equivalents) and are covered by the corresponding
+* Secrets permissions. Account-level GPG keys governs `/user/gpg_keys` — a
+* user's commit-signing keys — which reposets never touches. Following the old
+* list granted an unnecessary account-wide scope and did not grant anything the
+* tool actually used.
+*
+* `Metadata: Read` is mandatory for every fine-grained token and is granted
+* automatically, so it is not listed as something to enable.
+*/
+const REQUIRED_PERMISSIONS = [
+	[
+		"Repository",
+		"Administration (Read and write)",
+		"settings sync"
+	],
+	[
+		"Repository",
+		"Secrets (Read and write)",
+		"Actions, Codespaces and environment secrets"
+	],
+	[
+		"Repository",
+		"Variables (Read and write)",
+		"Actions and environment variables"
+	],
+	[
+		"Repository",
+		"Environments (Read and write)",
+		"deployment environment sync"
+	],
+	[
+		"Repository",
+		"Dependabot secrets (Read and write)",
+		"Dependabot secrets"
+	],
+	[
+		"Repository",
+		"Code scanning alerts (Read and write)",
+		"CodeQL default setup"
+	],
+	[
+		"Repository",
+		"Actions (Read)",
+		"count workflow files for the CodeQL actions language"
+	],
+	[
+		"Repository",
+		"Dependabot alerts (Read and write)",
+		"vulnerability alerts and automated fixes"
+	],
+	[
+		"Repository",
+		"Secret scanning alerts (Read and write)",
+		"secret scanning and delegated bypass"
+	],
+	[
+		"Organization",
+		"Members (Read)",
+		"resolve team slugs (org-owned repos only)"
+	]
+];
+const levenshtein = (a, b) => {
+	const matrix = [];
+	for (let i = 0; i <= a.length; i++) matrix[i] = [i];
+	for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+		const row = matrix[i];
+		const prev = matrix[i - 1];
+		row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + cost);
+	}
+	return matrix[a.length][b.length];
+};
+/** The nearest known key within edit distance 3, if any. */
+const findClosestMatch = (key, known) => {
 	let best;
 	let bestDist = Number.POSITIVE_INFINITY;
 	for (const candidate of known) {
@@ -55,100 +180,248 @@ function findClosestMatch(key, known) {
 		}
 	}
 	return best;
-}
-function levenshtein(a, b) {
-	const matrix = [];
-	for (let i = 0; i <= a.length; i++) matrix[i] = [i];
-	for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
-	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
-		const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-		matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+};
+/**
+* Find the config file without decoding it.
+*
+* @remarks
+* The same two tiers the loader uses — walk up from the working directory, then
+* the XDG config directory — but testing only for existence.
+*
+* This was written on the belief that `discover` skips a source that fails to
+* decode. **That was wrong** — it propagates, and a validation failure now
+* reports its own path and its structured issue. The duplication survives for a
+* different and narrower reason, measured rather than assumed:
+* `ConfigCodecError` carries `codec` and `operation` and **no path**, so a TOML
+* *syntax* error cannot name the file it failed to parse. That is the most
+* ordinary config mistake there is, and this command exists to say which file
+* is wrong — so it finds the file itself and parses it for the line and column.
+*
+* Delete this when the codec error carries a path.
+*
+* `appDirs.dirs.config` rather than `ensureConfig`: the latter *creates* the
+* directory, and a read-only diagnostic must not.
+*/
+const locateConfig = (fs, path, appDirs, configFlag) => Effect.gen(function* () {
+	const candidates = [];
+	if (configFlag !== void 0) candidates.push(configFlag, path.join(configFlag, CONFIG_FILENAME));
+	let dir = cwd();
+	for (;;) {
+		candidates.push(path.join(dir, CONFIG_FILENAME));
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
 	}
-	return matrix[a.length][b.length];
-}
-const doctorCommand = Command.make("doctor", { config: configOption }, ({ config }) => Effect.gen(function* () {
+	candidates.push(path.join(appDirs.dirs.config, CONFIG_FILENAME));
+	for (const candidate of candidates) {
+		const info = yield* fs.stat(candidate).pipe(Effect.option);
+		if (info._tag === "Some" && info.value.type === "File") return candidate;
+	}
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* `reposets doctor` — config diagnostics, typo detection, credential posture.
+*
+* @remarks
+* The typo pass reads the **raw** TOML rather than the decoded config, because
+* decoding silently drops keys the schema does not know. A misspelled
+* `has_issues` would validate cleanly and then do nothing; only the raw text
+* shows it.
+*
+* Nothing here prints a credential. The credentials section reports which
+* *form* each profile uses — `op://…` addresses and environment variable
+* *names* — and whether the 1Password service account variable is present. It
+* never resolves a reference, so there is no value in scope to leak.
+*
+* @public
+*/
+/**
+* What `GET /user` proves about a profile, worded for the kind it declares.
+*
+* @remarks
+* The endpoint returns the account that **owns** the token, which is a user even
+* for a token whose whole purpose is an organization. Reporting that as
+* "authenticates as spencerbeggs" next to a profile declaring `org = "..."`
+* reads as a contradiction, so the two kinds are worded differently.
+*
+* For a `username` profile the owner IS the declared owner, which makes this the
+* one exact check available for free: a typo becomes a named error here instead
+* of a 404 partway through a sync.
+*
+* For an `org` profile there is no equivalent. Nothing in `GET /user` says
+* whether the token reaches that organization — answering it needs a request
+* against the org, which a token without org read cannot make even when it can
+* administer every repository in it. So the absence of a check is deliberate,
+* and is not dressed up as reassurance.
+*
+* Extracted because both branches sit behind a live request: `doctor` builds its
+* own `GitHubClient` from the resolved token, so nothing outside it can reach
+* these lines.
+*
+* @public
+*/
+const describeIdentity = (name, profile, login) => {
+	const { owner, ownerType } = profileOwner(profile);
+	if (ownerType !== "User") return {
+		ok: true,
+		text: `Token [${name}]: resolved, owned by ${login}, for org ${owner}`
+	};
+	return login === owner ? {
+		ok: true,
+		text: `Token [${name}]: resolved, authenticates as ${login} — matches username`
+	} : {
+		ok: false,
+		text: `Token [${name}]: resolved, but authenticates as ${login} while the profile declares username = "${owner}"`
+	};
+};
+const doctorHandler = (configFlag) => Effect.gen(function* () {
 	const configFile = yield* ReposetsConfigFile;
-	const discoverResult = yield* Effect.either(configFile.discover);
-	if (discoverResult._tag === "Left") {
+	const credentialsFile = yield* ReposetsCredentialsFile;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const appDirs = yield* AppDirs;
+	const discovered = yield* configFile.discover.pipe(Effect.result);
+	const sources = discovered._tag === "Success" ? discovered.success : [];
+	const schemaValid = discovered._tag === "Success" && sources.length > 0;
+	const validationIssue = discovered._tag === "Failure" ? discovered.failure.issue : void 0;
+	const configPath = sources[0]?.path ?? (yield* locateConfig(fs, path, appDirs, configFlag));
+	if (configPath === void 0) {
 		yield* Effect.logError("No config found. Run 'reposets init' to create one.");
 		return;
 	}
-	const sources = discoverResult.right;
-	if (sources.length === 0) {
-		yield* Effect.logError("No config found. Run 'reposets init' to create one.");
+	yield* Effect.log(`Config: ${configPath}`);
+	const text = yield* fs.readFileString(configPath).pipe(Effect.option);
+	if (text._tag === "None") {
+		yield* Effect.logError(`Could not read ${configPath}`);
 		return;
 	}
-	const configPath = sources[0].path;
-	let raw;
-	try {
-		raw = parse(readFileSync(configPath, "utf-8"));
-	} catch (err) {
-		yield* Effect.logError(`TOML parse error: ${err instanceof Error ? err.message : String(err)}`);
+	const parsed = Toml.parseResult(text.value);
+	if (Result.isFailure(parsed)) {
+		yield* Effect.logError(`TOML parse error: ${String(parsed.failure)}`);
 		return;
 	}
+	const raw = isRecord(parsed.success) ? parsed.success : {};
 	let warnings = 0;
-	for (const key of Object.keys(raw)) if (!KNOWN_CONFIG_KEYS.has(key)) {
-		const suggestion = findClosestMatch(key, KNOWN_CONFIG_KEYS);
-		const hint = suggestion ? ` -- did you mean '${suggestion}'?` : "";
-		yield* Effect.log(`Warning: unknown top-level key '${key}'${hint}`);
-		warnings++;
-	}
-	const groups = raw.groups;
-	if (groups && typeof groups === "object") {
-		for (const [groupName, group] of Object.entries(groups)) if (group && typeof group === "object") {
-			for (const key of Object.keys(group)) if (!KNOWN_GROUP_KEYS.has(key)) {
-				const suggestion = findClosestMatch(key, KNOWN_GROUP_KEYS);
-				const hint = suggestion ? ` -- did you mean '${suggestion}'?` : "";
-				yield* Effect.log(`Warning: unknown key '${key}' in groups.${groupName}${hint}`);
-				warnings++;
+	const checkKeys = (target, known, where) => Effect.gen(function* () {
+		if (!isRecord(target)) return;
+		for (const key of Object.keys(target)) {
+			if (known.has(key)) continue;
+			const removedFrom = REMOVED_KEYS[where === "" ? key : `${key} (in groups)`] ?? REMOVED_KEYS[key];
+			if (removedFrom !== void 0) {
+				yield* Effect.log(`Warning: '${key}'${where} ${removedFrom}`);
+				warnings += 1;
+				continue;
 			}
+			const suggestion = findClosestMatch(key, known);
+			const hint = suggestion === void 0 ? "" : ` — did you mean '${suggestion}'?`;
+			yield* Effect.log(`Warning: unknown key '${key}'${where}${hint}`);
+			warnings += 1;
+		}
+	});
+	yield* checkKeys(raw, KNOWN_CONFIG_KEYS, "");
+	const settingsSection = isRecord(raw.settings) ? raw.settings : {};
+	for (const [groupName, body] of Object.entries(settingsSection)) {
+		if (!isRecord(body)) continue;
+		for (const field of Object.keys(body)) {
+			if (KNOWN_SETTINGS_FIELDS.has(field)) continue;
+			const suggestion = findClosestMatch(field, KNOWN_SETTINGS_FIELDS);
+			const hint = suggestion === void 0 ? " — it will be sent to GitHub as-is, which ignores fields it does not recognise" : ` — did you mean '${suggestion}'?`;
+			yield* Effect.log(`Warning: unrecognised setting '${field}' in settings.${groupName}${hint}`);
+			warnings += 1;
 		}
 	}
-	if (groups && typeof groups === "object") for (const [groupName, group] of Object.entries(groups)) {
-		if (!group || typeof group !== "object") continue;
+	const groups = raw.groups;
+	if (isRecord(groups)) for (const [groupName, group] of Object.entries(groups)) {
+		yield* checkKeys(group, KNOWN_GROUP_KEYS, ` in groups.${groupName}`);
+		if (!isRecord(group)) continue;
 		const cleanup = group.cleanup;
-		if (!cleanup || typeof cleanup !== "object") continue;
-		const cleanupObj = cleanup;
+		if (!isRecord(cleanup)) continue;
 		const prefix = `groups.${groupName}.cleanup`;
-		for (const key of Object.keys(cleanupObj)) if (!KNOWN_CLEANUP_KEYS.has(key)) {
-			const suggestion = findClosestMatch(key, KNOWN_CLEANUP_KEYS);
-			const hint = suggestion ? ` -- did you mean '${suggestion}'?` : "";
-			yield* Effect.log(`Warning: unknown key '${key}' in ${prefix}${hint}`);
-			warnings++;
-		}
-		const secrets = cleanupObj.secrets;
-		if (secrets && typeof secrets === "object") {
-			for (const key of Object.keys(secrets)) if (!KNOWN_CLEANUP_SECRETS_KEYS.has(key)) {
-				const suggestion = findClosestMatch(key, KNOWN_CLEANUP_SECRETS_KEYS);
-				const hint = suggestion ? ` -- did you mean '${suggestion}'?` : "";
-				yield* Effect.log(`Warning: unknown key '${key}' in ${prefix}.secrets${hint}`);
-				warnings++;
+		yield* checkKeys(cleanup, KNOWN_CLEANUP_KEYS, ` in ${prefix}`);
+		yield* checkKeys(cleanup.secrets, KNOWN_CLEANUP_SECRETS_KEYS, ` in ${prefix}.secrets`);
+		yield* checkKeys(cleanup.variables, KNOWN_CLEANUP_VARIABLES_KEYS, ` in ${prefix}.variables`);
+	}
+	if (schemaValid) yield* Effect.log("Schema validation: passed");
+	else {
+		yield* Effect.logError("Schema validation: FAILED — these values are rejected, not ignored");
+		for (const line of formatSchemaIssue(validationIssue)) yield* Effect.logError(`  ${line}`);
+	}
+	yield* Effect.log("");
+	const loaded = yield* credentialsFile.loadOrDefault({ profiles: {} }).pipe(Effect.result);
+	const credentials = loaded._tag === "Success" ? loaded.success : { profiles: {} };
+	const profileNames = Object.keys(credentials.profiles);
+	if (loaded._tag === "Failure") {
+		yield* Effect.logError(`Credentials: FAILED to load — ${String(loaded.failure.message ?? loaded.failure)}`);
+		yield* Effect.logError("  Unknown keys are rejected. `op_service_account_token` was removed — that token now comes from OP_SERVICE_ACCOUNT_TOKEN in the environment.");
+	} else if (profileNames.length === 0) yield* Effect.log("Credentials: no profiles configured");
+	else {
+		yield* Effect.log(`Credentials: ${profileNames.length} profile(s)`);
+		let usesOnePassword = false;
+		for (const [name, profile] of Object.entries(credentials.profiles)) {
+			const token = "op" in profile.github_token ? `op ${profile.github_token.op}` : `env ${profile.github_token.env}`;
+			if ("op" in profile.github_token) usesOnePassword = true;
+			const sections = [];
+			for (const kind of [
+				"op",
+				"env",
+				"file"
+			]) {
+				const entries = profile.resolve?.[kind];
+				if (entries !== void 0 && Object.keys(entries).length > 0) {
+					sections.push(`${kind}:${Object.keys(entries).length}`);
+					if (kind === "op") usesOnePassword = true;
+				}
 			}
+			const resolveSummary = sections.length === 0 ? "" : `, resolve ${sections.join(" ")}`;
+			yield* Effect.log(`  [${name}] github_token: ${token}${resolveSummary}`);
 		}
-		const variables = cleanupObj.variables;
-		if (variables && typeof variables === "object") {
-			for (const key of Object.keys(variables)) if (!KNOWN_CLEANUP_VARIABLES_KEYS.has(key)) {
-				const suggestion = findClosestMatch(key, KNOWN_CLEANUP_VARIABLES_KEYS);
-				const hint = suggestion ? ` -- did you mean '${suggestion}'?` : "";
-				yield* Effect.log(`Warning: unknown key '${key}' in ${prefix}.variables${hint}`);
-				warnings++;
-			}
+		const hasServiceAccount = env["OP_SERVICE_ACCOUNT_TOKEN"] !== void 0 && env["OP_SERVICE_ACCOUNT_TOKEN"] !== "";
+		if (usesOnePassword) yield* Effect.log(hasServiceAccount ? `  ${OP_SERVICE_ACCOUNT_TOKEN}: set` : `  ${OP_SERVICE_ACCOUNT_TOKEN}: NOT SET — op:// references cannot be resolved`);
+	}
+	yield* Effect.log("");
+	yield* Effect.log(`Version: ${env.__PACKAGE_VERSION__ ?? "0.0.0 (dev build)"}`);
+	const credentialDiscovery = yield* credentialsFile.discover.pipe(Effect.result);
+	const credentialSources = credentialDiscovery._tag === "Success" ? credentialDiscovery.success : [];
+	const credentialsLine = credentialDiscovery._tag === "Failure" ? "(failed to load — the error above names the file)" : credentialSources.length === 0 ? `${path.join(appDirs.dirs.config, CREDENTIALS_FILENAME)} (not created yet)` : credentialSources[0]?.path ?? "";
+	yield* Effect.log(`Credentials file: ${credentialsLine}`);
+	yield* Effect.log(`State database: ${path.join(appDirs.dirs.state, "store.db")}`);
+	yield* Effect.log("");
+	for (const [name, profile] of Object.entries(credentials.profiles)) {
+		const resolverLayer = Layer.provide(CredentialResolverLive, OnePasswordClientLive);
+		const resolved = yield* Effect.gen(function* () {
+			return yield* (yield* CredentialResolver).resolveGitHubToken(profile);
+		}).pipe(Effect.provide(resolverLayer), Effect.result);
+		if (resolved._tag === "Failure") {
+			yield* Effect.logError(`Token [${name}]: could not resolve — ${String(resolved.failure)}`);
+			continue;
+		}
+		const identity = yield* Effect.gen(function* () {
+			return yield* (yield* GitHubClient).request("GET /user", {});
+		}).pipe(Effect.provide(GitHubClient.layerFromToken({ token: resolved.success })), Effect.result);
+		if (identity._tag !== "Success") {
+			yield* Effect.logError(`Token [${name}]: resolved but REJECTED by GitHub — ${String(identity.failure)}`);
+			continue;
 		}
+		const line = describeIdentity(name, profile, identity.success.login);
+		yield* line.ok ? Effect.log(line.text) : Effect.logError(line.text);
 	}
-	yield* Effect.log("Schema validation: passed");
-	yield* Effect.log("\nRequired fine-grained token permissions:");
-	yield* Effect.log("  Repository permissions > Administration (Read and write) -- settings sync");
-	yield* Effect.log("  Repository permissions > Secrets (Read and write) -- Actions secrets");
-	yield* Effect.log("  Repository permissions > Variables (Read and write) -- Actions variables");
-	yield* Effect.log("  Repository permissions > Environments (Read and write) -- environment sync");
-	yield* Effect.log("  Repository permissions > Code scanning alerts (Read and write) -- code_scanning sync");
-	yield* Effect.log("  Repository permissions > Dependabot alerts (Read and write) -- security feature sync");
-	yield* Effect.log("  Repository permissions > Secret scanning alerts (Read and write) -- secret scanning delegation");
-	yield* Effect.log("  Account permissions > GPG keys (Read and write) -- secrets encryption key");
-	yield* Effect.log("  Organization permissions > Members (Read) -- resolve team slugs (org-level only)");
-	if (warnings === 0) yield* Effect.log("\nNo unknown keys detected.");
-	else yield* Effect.log(`\n${warnings} warning(s) found.`);
-}).pipe(Effect.provide(makeConfigFilesLive(config)))).pipe(Command.withDescription("Deep config diagnostics with typo detection"));
+	yield* Effect.log("");
+	yield* Effect.log("Required fine-grained token permissions:");
+	for (const [scope, permission, why] of REQUIRED_PERMISSIONS) yield* Effect.log(`  ${scope} > ${permission} — ${why}`);
+	yield* Effect.log("  (Metadata: Read is mandatory and granted automatically)");
+	yield* Effect.log("  These are NOT verified — GitHub does not expose a fine-grained token's own scopes.");
+	yield* Effect.log("");
+	yield* Effect.log(warnings === 0 ? "No unknown keys detected." : `${warnings} warning(s) found.`);
+});
+/**
+* `reposets doctor`.
+*
+* @public
+*/
+const doctorCommand = Command.make("doctor", {}, () => Effect.gen(function* () {
+	const flag = yield* ConfigFlag;
+	yield* doctorHandler(Option.getOrUndefined(flag));
+})).pipe(Command.withDescription("Diagnose the config: unknown keys, credential posture, required token permissions"));
 
 //#endregion
-export { doctorCommand };
+export { describeIdentity, doctorCommand, doctorHandler };

package/cli/commands/drift.js

@@ -0,0 +1,48 @@
+import { syncHandler } from "./sync.js";
+import { Option } from "effect";
+import { Command, Flag } from "effect/unstable/cli";
+
+//#region src/cli/commands/drift.ts
+/**
+* `reposets drift` — report resources changed outside reposets, and change
+* nothing.
+*
+* @remarks
+* This is `sync --dry-run --no-cleanup --fail-on-drift` under a name that says
+* what it is for, and it is deliberately the *same* handler rather than a
+* second pipeline. Drift is decided by comparing three fingerprints — desired,
+* live, and last-applied — and that comparison happens inside the phases. A
+* separate read-only implementation would be a second copy of that decision,
+* free to disagree with the one that actually converges, which is the worst
+* possible outcome for a command whose entire job is to be believed.
+*
+* **It writes nothing, to GitHub or to the baseline.** Every phase gates its
+* writes on `dryRun`, and that includes recording the applied-state fingerprint
+* — so a drift check does not quietly accept the drift it just reported by
+* adopting the live state as the new baseline. The run does appear in
+* `reposets history`, flagged as a dry run.
+*
+* Cleanup is off because a resource the config never declared is not drift. It
+* is undeclared, which is a different question and one `sync` answers.
+*
+* Exits non-zero when drift is found, so it works as a CI gate without a flag.
+*
+* @public
+*/
+const driftCommand = Command.make("drift", {
+	group: Flag.string("group").pipe(Flag.withDescription("Check only this group"), Flag.optional),
+	repo: Flag.string("repo").pipe(Flag.withDescription("Check only this repository"), Flag.optional),
+	debug: Flag.boolean("debug").pipe(Flag.withDescription("Show the applied and live fingerprints behind each drift report"))
+}, (input) => syncHandler({
+	dryRun: true,
+	noCleanup: true,
+	failOnDrift: true,
+	group: Option.getOrUndefined(input.group),
+	repo: Option.getOrUndefined(input.repo),
+	only: [],
+	skip: [],
+	debug: input.debug
+})).pipe(Command.withDescription("Report resources changed outside reposets, without changing anything"));
+
+//#endregion
+export { driftCommand };