reposets 0.4.2 → 1.0.0

package/index.js

@@ -1,19 +1,4 @@
-import { GitHubApiError, OnePasswordError, ResolveError, SyncError } from "./errors.js";
-import { encryptSecret } from "./lib/crypto.js";
-import { CleanupSchema, CleanupScopeSchema, SecretGroupSchema, VariableGroupSchema } from "./schemas/common.js";
-import { BypassActorSchema, ResolvedRefSchema, RulesetSchema, buildRulesetPayload } from "./schemas/ruleset.js";
-import { ConfigSchema, GroupSchema, LogLevelSchema } from "./schemas/config.js";
-import { CredentialProfileSchema, CredentialsSchema, ResolveSectionSchema } from "./schemas/credentials.js";
-import { CONFIG_FILENAME, CREDENTIALS_FILENAME, ConfigFilesLive, ReposetsConfigFile, ReposetsCredentialsFile, makeConfigFilesLive, validateConfigRefs } from "./services/ConfigFiles.js";
-import { OnePasswordClient, OnePasswordClientLive, OnePasswordClientTest } from "./services/OnePasswordClient.js";
-import { CredentialResolver, CredentialResolverLive } from "./services/CredentialResolver.js";
-import { GitHubClient, GitHubClientLive, GitHubClientTest } from "./services/GitHubClient.js";
-import { SyncLogger, SyncLoggerLive } from "./services/SyncLogger.js";
-import { SyncEngine, SyncEngineLive } from "./services/SyncEngine.js";
-import { AppDirs, ConfigError as XdgConfigError, ConfigFile } from "xdg-effect";
+import { ConfigSchema } from "./schemas/config.js";
+import { CONFIG_FILENAME, ConfigFlagNotFound, ReposetsConfigFile, makeConfigFilesLive } from "./services/ConfigFiles.js";
 
-//#region src/index.ts
-/* v8 ignore stop */
-
-//#endregion
-export { AppDirs, BypassActorSchema, CONFIG_FILENAME, CREDENTIALS_FILENAME, CleanupSchema, CleanupScopeSchema, ConfigFile, ConfigFilesLive, ConfigSchema, CredentialProfileSchema, CredentialResolver, CredentialResolverLive, CredentialsSchema, GitHubApiError, GitHubClient, GitHubClientLive, GitHubClientTest, GroupSchema, LogLevelSchema, OnePasswordClient, OnePasswordClientLive, OnePasswordClientTest, OnePasswordError, ReposetsConfigFile, ReposetsCredentialsFile, ResolveError, ResolveSectionSchema, ResolvedRefSchema, RulesetSchema, SecretGroupSchema, SyncEngine, SyncEngineLive, SyncError, SyncLogger, SyncLoggerLive, VariableGroupSchema, XdgConfigError, buildRulesetPayload, encryptSecret, makeConfigFilesLive, validateConfigRefs };
+export { CONFIG_FILENAME, ConfigFlagNotFound, ConfigSchema, ReposetsConfigFile, makeConfigFilesLive };

package/lib/config-refs.js

@@ -0,0 +1,76 @@
+//#region src/lib/config-refs.ts
+/**
+* Every reference in `[groups.*]` that points at a section which is not defined.
+*
+* @remarks
+* **This was lost in the v4 rebuild and is restored here.** v3 registered a
+* `validateConfigRefs` callback on the config spec, so a dangling reference
+* failed the load for every command. The rebuild dropped it and nothing took
+* its place — while every phase kept skipping unresolvable references silently
+* and *citing that callback by name* as the thing that owned the check.
+*
+* The result was the worst shape available: `settings = ["defualt"]` synced
+* nothing, reported nothing, and `validate` printed `Valid:` and exited 0. The
+* same failure as a misspelled `--repo` passing green, which is fixed
+* elsewhere in this codebase for exactly the reason it matters here — a filter
+* or a reference that silently matches nothing turns a destructive command into
+* a no-op that looks like success.
+*
+* Checked where the reference is **used**, not where a section is defined: an
+* unreferenced `[settings.*]` section is dead config, not an error, and a
+* config may legitimately define sections some groups do not take.
+*
+* `defined` is carried on each finding so the report can show the near-misses.
+* Nearly every one of these is a typo, and a typo is fixed by seeing the
+* correct spelling rather than by being told the wrong one is wrong.
+*
+* @public
+*/
+const danglingReferences = (config) => {
+	const found = [];
+	const sections = {
+		settings: Object.keys(config.settings),
+		rulesets: Object.keys(config.rulesets),
+		environments: Object.keys(config.environments ?? {}),
+		security: Object.keys(config.security ?? {}),
+		code_scanning: Object.keys(config.code_scanning ?? {}),
+		secrets: Object.keys(config.secrets),
+		variables: Object.keys(config.variables)
+	};
+	for (const [groupName, group] of Object.entries(config.groups)) {
+		const check = (where, names, defined) => {
+			for (const name of names) {
+				if (defined.includes(name)) continue;
+				found.push({
+					group: groupName,
+					where,
+					name,
+					defined
+				});
+			}
+		};
+		check(`groups.${groupName}.settings`, group.settings ?? [], sections.settings);
+		check(`groups.${groupName}.rulesets`, group.rulesets ?? [], sections.rulesets);
+		check(`groups.${groupName}.environments`, group.environments ?? [], sections.environments);
+		check(`groups.${groupName}.security`, group.security ?? [], sections.security);
+		check(`groups.${groupName}.code_scanning`, group.code_scanning ?? [], sections.code_scanning);
+		for (const scope of [
+			"actions",
+			"dependabot",
+			"codespaces"
+		]) check(`groups.${groupName}.secrets.${scope}`, group.secrets?.[scope] ?? [], sections.secrets);
+		check(`groups.${groupName}.variables.actions`, group.variables?.actions ?? [], sections.variables);
+		for (const [environment, names] of Object.entries(group.secrets?.environments ?? {})) {
+			check(`groups.${groupName}.secrets.environments`, [environment], sections.environments);
+			check(`groups.${groupName}.secrets.environments.${environment}`, names, sections.secrets);
+		}
+		for (const [environment, names] of Object.entries(group.variables?.environments ?? {})) {
+			check(`groups.${groupName}.variables.environments`, [environment], sections.environments);
+			check(`groups.${groupName}.variables.environments.${environment}`, names, sections.variables);
+		}
+	}
+	return found;
+};
+
+//#endregion
+export { danglingReferences };

package/lib/fingerprint.js

@@ -0,0 +1,52 @@
+import blakejs from "blakejs";
+
+//#region src/lib/fingerprint.ts
+const { blake2bHex } = blakejs;
+/**
+* Serializes a value to JSON with object keys sorted at every depth.
+*
+* @remarks
+* Two values that differ only in key order must hash identically, or every
+* config reordering would read as drift. `JSON.stringify` preserves insertion
+* order, so the sort has to be explicit.
+*
+* Arrays keep their order — element order is meaningful in this config (a
+* ruleset's `rules`, an environment's reviewers), so reordering one is a real
+* change and should register as drift.
+*
+* `undefined` is dropped from objects, matching `JSON.stringify`, so an absent
+* key and an explicitly-undefined key fingerprint the same. That is correct
+* here: both mean "not configured".
+*/
+const canonical = (value) => {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+};
+/**
+* The digest length, in bytes. 32 gives a 64-character hex string.
+*/
+const DIGEST_BYTES = 32;
+/**
+* Fingerprints the resolved desired state of one resource.
+*
+* @remarks
+* Pure, and deliberately not an `Effect` — it performs no I/O and cannot fail
+* for any input reposets produces. The argument is always already-decoded config
+* data, which by construction is acyclic (it came from TOML).
+*
+* The fingerprint records what reposets last *pushed*, so a later run can tell
+* "the config changed" from "someone changed this in the GitHub UI".
+*
+* @example
+* ```ts
+* fingerprint({ b: 1, a: 2 }) === fingerprint({ a: 2, b: 1 })  // key order is not drift
+* fingerprint([1, 2]) !== fingerprint([2, 1])                  // element order is
+* ```
+*
+* @public
+*/
+const fingerprint = (value) => blake2bHex(canonical(value), void 0, DIGEST_BYTES);
+
+//#endregion
+export { fingerprint };

package/lib/org-only.js

@@ -0,0 +1,61 @@
+import { profileOwner } from "../schemas/credentials.js";
+
+//#region src/lib/org-only.ts
+/**
+* Organization-only constructs assigned to personal-account groups.
+*
+* @remarks
+* **The whole point of declaring `username` or `org` on a profile.** Every check
+* here previously needed the owner's type, and the only way to learn it was to
+* ask GitHub — so `validate`, whose entire contract is that it touches no
+* network, could not make them at all. They surfaced as a 422 mid-sync instead,
+* after earlier repositories had already been written.
+*
+* Three constructs need an organization, and each is checked where it is
+* *referenced* rather than where it is defined: a ruleset with a team bypass
+* actor is perfectly valid sitting in `[rulesets.*]`, and only becomes an error
+* when a personal-account group assigns it. Reporting the definition would name
+* a section the user may share between groups and would have to leave alone.
+*
+* This does not replace the check against GitHub. A declaration can be wrong,
+* so `sync` still verifies the owner's type before writing; this catches the
+* config error earlier and without a token.
+*
+* @public
+*/
+const orgOnlyViolations = (config, credentials) => {
+	const violations = [];
+	for (const [groupName, group] of Object.entries(config.groups)) {
+		const profile = credentials.profiles[group.credentials];
+		if (profile === void 0) continue;
+		if (profileOwner(profile).ownerType !== "User") continue;
+		const add = (where, detail) => {
+			violations.push({
+				group: groupName,
+				profile: group.credentials,
+				where,
+				detail
+			});
+		};
+		for (const name of group.settings ?? []) {
+			const settings = config.settings[name];
+			if (settings === void 0) continue;
+			if (settings.secret_scanning_delegated_bypass !== void 0) add(`settings.${name}.secret_scanning_delegated_bypass`, "delegated bypass requires an organization");
+			if (settings.delegated_bypass_reviewers !== void 0) add(`settings.${name}.delegated_bypass_reviewers`, "bypass reviewers require an organization");
+		}
+		for (const name of group.rulesets ?? []) {
+			const ruleset = config.rulesets[name];
+			if (ruleset === void 0) continue;
+			for (const actor of ruleset.bypass_actors ?? []) if (actor.actor_type === "Team") add(`rulesets.${name}.bypass_actors`, "a Team bypass actor requires an organization");
+		}
+		for (const name of group.environments ?? []) {
+			const environment = config.environments?.[name];
+			if (environment === void 0) continue;
+			for (const reviewer of environment.reviewers ?? []) if (reviewer.type === "Team") add(`environments.${name}.reviewers`, "a Team reviewer requires an organization");
+		}
+	}
+	return violations;
+};
+
+//#endregion
+export { orgOnlyViolations };

package/lib/schema-issues.js

@@ -0,0 +1,50 @@
+import { SchemaIssue } from "effect";
+
+//#region src/lib/schema-issues.ts
+/**
+* Core's structured formatter: one entry per leaf, each with its property path.
+*
+* @remarks
+* Built once. It is a pure function of the issue tree, and `Formatter` carries
+* no state.
+*/
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag === "UnexpectedKey" ? "unknown key" : SchemaIssue.defaultLeafHook(issue) });
+/**
+* Render a `ConfigValidationError`'s `issue` as one line per rejected value.
+*
+* @remarks
+* **No walker of our own.** Core already ships one:
+* `SchemaIssue.makeFormatterStandardSchemaV1()` flattens the tree to
+* `{ message, path }` entries, which is exactly the shape this needs.
+* `defaultLeafHook` handles every leaf variant — `UnexpectedKey`,
+* `InvalidType`, `MissingKey`, `Forbidden`, `OneOf` — so a wrong *type* renders
+* as sensibly as an unknown key, and a variant added upstream is covered
+* without a change here. Hand-rolling this against the excess-property shape
+* alone would have got every other cause wrong.
+*
+* `issue` is declared `Schema.Defect`, so it arrives as `unknown`; the
+* `isIssue` guard is what makes reading it safe. Anything that is not an issue
+* tree yields no lines rather than a crash — a rendering helper on an error
+* path must never become the reason a command dies.
+*
+* Nodes are never stringified. Each carries the entire AST inline, annotations
+* included, so `String(node)` would dump the schema rather than describe the
+* failure. Only `message` and `path` are read.
+*
+* @param issue - the `issue` field of a `ConfigValidationError`, or any value
+* @returns one line per rejected value, deepest path last; empty if `issue` is
+* not an issue tree
+*
+* @public
+*/
+const formatSchemaIssue = (issue) => {
+	if (!SchemaIssue.isIssue(issue)) return [];
+	const lines = formatter(issue).issues.map((entry) => {
+		const path = (entry.path ?? []).map(String).join(".");
+		return path === "" ? entry.message : `${entry.message} at ${path}`;
+	});
+	return [...new Set(lines)];
+};
+
+//#endregion
+export { formatSchemaIssue };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "reposets",
-	"version": "0.4.2",
+	"version": "1.0.0",
 	"private": false,
 	"description": "CLI tool to sync GitHub repo settings, secrets and rulesets across personal repositories",
 	"keywords": [
@@ -38,7 +38,8 @@
 	"exports": {
 		".": {
 			"types": "./index.d.ts",
-			"import": "./index.js"
+			"import": "./index.js",
+			"default": "./index.js"
 		},
 		"./package.json": "./package.json"
 	},
@@ -47,15 +48,15 @@
 	},
 	"dependencies": {
 		"@1password/sdk": "^0.4.0",
-		"@effect/cli": "^0.75.2",
-		"@effect/platform": "^0.96.1",
-		"@effect/platform-node": "^0.107.0",
-		"@octokit/rest": "^22.0.1",
+		"@effect/platform-node": "4.0.0-beta.107",
+		"@effected/app": "^0.10.0",
+		"@effected/config-file": "^0.4.0",
+		"@effected/github": "^0.4.0",
+		"@effected/store": "^0.3.0",
+		"@effected/toml": "^0.4.0",
+		"@effected/xdg": "^0.2.1",
 		"blakejs": "^1.2.1",
-		"effect": "^3.21.3",
-		"smol-toml": ">=1.6.1",
-		"tweetnacl": "^1.0.3",
-		"xdg-effect": "^1.0.3"
+		"effect": "4.0.0-beta.107"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/schemas/annotations.js

@@ -0,0 +1,81 @@
+//#region src/schemas/annotations.ts
+/**
+* Build the `x-taplo` annotation key from typed options.
+*
+* @remarks
+* The v3 tree imported this from `xdg-effect`, which re-exported it from
+* `json-schema-effect`. Both are gone and `@effected/schemastore` ships no
+* replacement builder — what it ships is the other half: `KeywordFamilies`
+* declares `x-taplo*` and `x-tombi-*` as carried families, and
+* `StoreDocument.fromSchema` wires them into core's `includeAnnotationKey`
+* predicate so they survive the Draft-07 lowering. So the mechanism is intact
+* and only the two constructors needed rebuilding; they live here rather than
+* being inlined at ~30 call sites, which is where the exact key spellings would
+* otherwise drift.
+*
+* The other half of the change is where the result goes. v3 nested it under a
+* `jsonSchema` annotation; v4 has no such annotation, and non-standard keys are
+* written at the top level of `.annotate({ ... })` instead. Spread the result
+* in: `.annotate({ ...taplo({ ... }), title: "..." })`.
+*
+* Taplo ignores `x-taplo` on a node that also carries `$ref`. That is a Taplo
+* limitation and the helper does not work around it — the v3 helper did not
+* either.
+*
+* @public
+*/
+const taplo = (options) => {
+	const out = {};
+	if (options.hidden !== void 0) out.hidden = options.hidden;
+	if (options.docs !== void 0) out.docs = options.docs;
+	if (options.links !== void 0) out.links = options.links;
+	if (options.initKeys !== void 0) out.initKeys = options.initKeys;
+	for (const [key, value] of Object.entries(options.custom ?? {})) out[key] = value;
+	return { "x-taplo": out };
+};
+/** The `TombiOptions` field → `x-tombi-*` key mapping, in the v3 helper's order. */
+const tombiKeys = [
+	["additionalKeyLabel", "x-tombi-additional-key-label"],
+	["tableKeysOrder", "x-tombi-table-keys-order"],
+	["arrayValuesOrder", "x-tombi-array-values-order"],
+	["arrayValuesOrderBy", "x-tombi-array-values-order-by"],
+	["stringFormats", "x-tombi-string-formats"],
+	["tomlVersion", "x-tombi-toml-version"]
+];
+/**
+* Build the `x-tombi-*` annotation keys from typed options.
+*
+* @remarks
+* See {@link taplo} for why these helpers are local. Unlike `x-taplo`, tombi's
+* options are separate top-level keys rather than members of one object, so the
+* result usually spreads alongside other annotations:
+* `.annotate({ ...tombi({ tableKeysOrder: "schema" }), title: "..." })`.
+*
+* @public
+*/
+const tombi = (options) => {
+	const out = {};
+	for (const [field, key] of tombiKeys) {
+		const value = options[field];
+		if (value !== void 0) out[key] = value;
+	}
+	for (const [key, value] of Object.entries(options.custom ?? {})) out[key] = value;
+	return out;
+};
+/**
+* The URL of a page under the repository's `docs/`, for a `links.key`
+* annotation.
+*
+* @remarks
+* Every v3 call site spelled the same prefix by hand. Collapsing it here keeps
+* the annotations from drifting apart when the docs move. It returns the URL
+* rather than a finished `x-taplo` object on purpose: several call sites pass
+* `initKeys` in the same `taplo()` call, and two separate `taplo()` results
+* spread into one `annotate` would silently overwrite each other's `x-taplo`.
+*
+* @public
+*/
+const docs = (page) => `https://github.com/spencerbeggs/reposets/blob/main/docs/${page}`;
+
+//#endregion
+export { docs, taplo, tombi };

package/schemas/common.js

@@ -1,129 +1,164 @@
-import { Jsonifiable, taplo, tombi } from "xdg-effect";
-import { Schema } from "effect";
+import { docs, taplo, tombi } from "./annotations.js";
+import { Effect, Schema } from "effect";
 
 //#region src/schemas/common.ts
-const ResourceFileKind = Schema.Struct({ file: Schema.Record({
-	key: Schema.String,
-	value: Schema.String
-}).annotations({
+const ResourceFileKind = Schema.Struct({ file: Schema.Record(Schema.String, Schema.String).annotate({
+	...tombi({ additionalKeyLabel: "name" }),
 	title: "File entries",
-	description: "Named entries with file path values, resolved relative to config directory",
-	jsonSchema: tombi({ additionalKeyLabel: "name" })
+	description: "Named entries with file path values, resolved relative to config directory"
 }) });
-const ResourceValueKind = Schema.Struct({ value: Schema.Record({
-	key: Schema.String,
-	value: Schema.Union(Schema.String, Schema.Record({
-		key: Schema.String,
-		value: Jsonifiable
-	}))
-}).annotations({
+const ResourceValueKind = Schema.Struct({ value: Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Record(Schema.String, Schema.Json)])).annotate({
+	...tombi({ additionalKeyLabel: "name" }),
 	title: "Value entries",
-	description: "Named entries with inline values. Strings used as-is, objects JSON-stringified.",
-	jsonSchema: tombi({ additionalKeyLabel: "name" })
+	description: "Named entries with inline values. Strings used as-is, objects JSON-stringified."
 }) });
-const ResourceResolvedKind = Schema.Struct({ resolved: Schema.Record({
-	key: Schema.String,
-	value: Schema.String
-}).annotations({
+const ResourceResolvedKind = Schema.Struct({ resolved: Schema.Record(Schema.String, Schema.String).annotate({
+	...tombi({ additionalKeyLabel: "name" }),
 	title: "Resolved entries",
-	description: "Named entries mapped to credential labels. Values come from the active credential profile.",
-	jsonSchema: tombi({ additionalKeyLabel: "name" })
+	description: "Named entries mapped to credential labels. Values come from the active credential profile."
 }) });
-const SecretGroupSchema = Schema.Union(ResourceFileKind, ResourceValueKind, ResourceResolvedKind).annotations({
+/**
+* A group of secrets: exactly one of `file`, `value` or `resolved`.
+*
+* @public
+*/
+const SecretGroupSchema = Schema.Union([
+	ResourceFileKind,
+	ResourceValueKind,
+	ResourceResolvedKind
+]).annotate({
+	...taplo({ links: { key: docs("05-secrets-and-variables.md") } }),
 	identifier: "SecretGroup",
 	title: "Secret group",
-	description: "A group of secrets. Must be exactly one kind: file, value, or resolved.",
-	jsonSchema: taplo({ links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/secrets-and-variables.md" } })
+	description: "A group of secrets. Must be exactly one kind: file, value, or resolved."
 });
-const VariableGroupSchema = Schema.Union(ResourceFileKind, ResourceValueKind, ResourceResolvedKind).annotations({
+/**
+* A group of variables: exactly one of `file`, `value` or `resolved`.
+*
+* @public
+*/
+const VariableGroupSchema = Schema.Union([
+	ResourceFileKind,
+	ResourceValueKind,
+	ResourceResolvedKind
+]).annotate({
+	...taplo({ links: { key: docs("05-secrets-and-variables.md") } }),
 	identifier: "VariableGroup",
 	title: "Variable group",
-	description: "A group of variables. Must be exactly one kind: file, value, or resolved.",
-	jsonSchema: taplo({ links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/secrets-and-variables.md" } })
+	description: "A group of variables. Must be exactly one kind: file, value, or resolved."
 });
-const CleanupScopeSchema = Schema.Union(Schema.Boolean, Schema.Struct({ preserve: Schema.Array(Schema.String).annotations({
+/**
+* Cleanup policy for one resource scope.
+*
+* @remarks
+* Three-way on purpose: `false` disables cleanup, `true` deletes everything
+* undeclared, and `{ preserve }` deletes everything undeclared except the named
+* resources. Omitting the scope means `false` — leave it alone.
+*
+* @public
+*/
+const CleanupScopeSchema = Schema.Union([Schema.Boolean, Schema.Struct({ preserve: Schema.Array(Schema.String).annotate({
 	title: "Preserve list",
 	description: "Resource names that should never be deleted during cleanup",
 	examples: [["LEGACY_TOKEN", "DEPLOY_KEY"]]
-}) })).annotations({
+}) })]).annotate({
 	identifier: "CleanupScope",
 	title: "Cleanup scope",
 	description: "Controls cleanup for a single resource scope. false disables cleanup, true enables full cleanup, or specify names to preserve."
 });
+/**
+* A cleanup scope that defaults to `false` when the key is absent.
+*
+* @remarks
+* v3 wrote this as `Schema.optionalWith(CleanupScopeSchema, { default: () => false })`.
+* v4 splits that into `optionalKey` on the encoded side plus a decoding default;
+* `withDecodingDefaultKey` is the combinator that does both, and it takes the
+* default as an `Effect` rather than a thunk.
+*/
+const cleanupScopeDefaultingToFalse = CleanupScopeSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)));
 const CleanupSecretsSchema = Schema.Struct({
-	actions: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	actions: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up Actions secrets",
 		description: "Delete Actions secrets not declared in any referenced secret group",
 		default: false
 	}),
-	dependabot: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	dependabot: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up Dependabot secrets",
 		description: "Delete Dependabot secrets not declared in any referenced secret group",
 		default: false
 	}),
-	codespaces: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	codespaces: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up Codespaces secrets",
 		description: "Delete Codespaces secrets not declared in any referenced secret group",
 		default: false
 	}),
-	environments: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	environments: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up environment secrets",
 		description: "Delete environment secrets not declared in any referenced secret group",
 		default: false
 	})
-}).annotations({
+}).annotate({
 	identifier: "CleanupSecrets",
 	title: "Secrets cleanup configuration",
 	description: "Controls deletion of secrets by scope (Actions, Dependabot, Codespaces, environments)."
 });
 const CleanupVariablesSchema = Schema.Struct({
-	actions: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	actions: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up Actions variables",
 		description: "Delete Actions variables not declared in any referenced variable group",
 		default: false
 	}),
-	environments: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	environments: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up environment variables",
 		description: "Delete environment variables not declared in any referenced variable group",
 		default: false
 	})
-}).annotations({
+}).annotate({
 	identifier: "CleanupVariables",
 	title: "Variables cleanup configuration",
 	description: "Controls deletion of variables by scope (Actions, environments)."
 });
+/**
+* Per-group cleanup configuration.
+*
+* @remarks
+* Everything defaults to disabled. Deleting resources a config does not declare
+* is destructive and opt-in at every level.
+*
+* @public
+*/
 const CleanupSchema = Schema.Struct({
-	secrets: Schema.optionalWith(CleanupSecretsSchema, { default: () => ({
+	secrets: CleanupSecretsSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({
 		actions: false,
 		dependabot: false,
 		codespaces: false,
 		environments: false
-	}) }).annotations({
+	}))).annotate({
 		title: "Secrets cleanup",
 		description: "Controls cleanup of secrets by scope"
 	}),
-	variables: Schema.optionalWith(CleanupVariablesSchema, { default: () => ({
+	variables: CleanupVariablesSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({
 		actions: false,
 		environments: false
-	}) }).annotations({
+	}))).annotate({
 		title: "Variables cleanup",
 		description: "Controls cleanup of variables by scope"
 	}),
-	rulesets: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	rulesets: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up rulesets",
 		description: "Delete repository rulesets not declared in any referenced ruleset group",
 		default: false
 	}),
-	environments: Schema.optionalWith(CleanupScopeSchema, { default: () => false }).annotations({
+	environments: cleanupScopeDefaultingToFalse.annotate({
 		title: "Clean up environments",
 		description: "Delete repository environments not declared in config",
 		default: false
 	})
-}).annotations({
+}).annotate({
+	...taplo({ links: { key: docs("08-cleanup.md") } }),
 	identifier: "Cleanup",
 	title: "Cleanup configuration",
-	description: "Controls deletion of resources not declared in config. All disabled by default.",
-	jsonSchema: taplo({ links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/cleanup.md" } })
+	description: "Controls deletion of resources not declared in config. All disabled by default."
 });
 
 //#endregion