reposets 0.4.2 → 1.0.0

package/schemas/credentials.js

@@ -1,78 +1,214 @@
-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/credentials.ts
+const CREDENTIALS_DOCS = docs("04-credentials.md");
+/**
+* A 1Password secret reference.
+*
+* @public
+*/
+const OpReferenceSchema = Schema.Struct({ op: Schema.String.annotate({
+	title: "1Password reference",
+	description: "An op:// secret reference, resolved through the 1Password SDK at run time",
+	examples: ["op://Vault/item/field", "op://Vault/item/section/field"]
+}) }).annotate({
+	identifier: "OpReference",
+	title: "1Password reference",
+	description: "Resolved through the 1Password SDK using OP_SERVICE_ACCOUNT_TOKEN from the environment"
+});
+/**
+* An environment-variable reference.
+*
+* @public
+*/
+const EnvReferenceSchema = Schema.Struct({ env: Schema.String.annotate({
+	title: "Environment variable",
+	description: "The name of an environment variable holding the value",
+	examples: ["REPOSETS_GITHUB_TOKEN"]
+}) }).annotate({
+	identifier: "EnvReference",
+	title: "Environment variable reference",
+	description: "For CI, where the platform's secret store injects the value"
+});
+/**
+* Where a credential comes from.
+*
+* @remarks
+* **Deliberately never an inline value.** A credentials file holds references,
+* not secrets: every variant here points somewhere else, so the file itself is
+* safe to read, back up, and sit in a terminal scrollback.
+*
+* `{ op }` is the intended form. `{ env }` exists for CI, where a platform
+* secret store injects the value and no 1Password service account is available.
+*
+* @public
+*/
+const CredentialSourceSchema = Schema.Union([OpReferenceSchema, EnvReferenceSchema]).annotate({
+	identifier: "CredentialSource",
+	title: "Credential source",
+	description: "Exactly one of op (1Password reference) or env (environment variable name)"
+});
+/**
+* Named values referenced by `resolved` secret and variable groups.
+*
+* @remarks
+* **`value` holds named values, not only secrets.** An earlier revision removed
+* it by generalising the token rule — `github_token` and the service-account
+* token are unambiguously credentials and must be references. This section is
+* not: real configs use it for structured, non-secret data such as an SBOM
+* supplier block or a registry list, and forcing those into 1Password buys no
+* security and costs a round trip.
+*
+* The rule that does hold: a *credential* is never inlined. That is enforced
+* where credentials are declared, not here.
+*
+* `file` and `env` are pointers — the value lives outside this file.
+*
+* @public
+*/
 const ResolveSectionSchema = Schema.Struct({
-	op: Schema.optional(Schema.Record({
-		key: Schema.String,
-		value: Schema.String
-	}).annotations({
+	op: Schema.optional(Schema.Record(Schema.String, Schema.String).annotate({
+		...tombi({ additionalKeyLabel: "label" }),
 		title: "1Password references",
-		description: "Named values resolved via 1Password SDK. Values are op:// reference strings.",
-		jsonSchema: tombi({ additionalKeyLabel: "label" })
+		description: "Named values resolved via the 1Password SDK. Values are op:// reference strings."
+	})),
+	env: Schema.optional(Schema.Record(Schema.String, Schema.String).annotate({
+		...tombi({ additionalKeyLabel: "label" }),
+		title: "Environment variable references",
+		description: "Named values read from the environment. Values are variable names, not values."
 	})),
-	file: Schema.optional(Schema.Record({
-		key: Schema.String,
-		value: Schema.String
-	}).annotations({
+	file: Schema.optional(Schema.Record(Schema.String, Schema.String).annotate({
+		...tombi({ additionalKeyLabel: "label" }),
 		title: "File references",
-		description: "Named values read from files. Values are file paths relative to the credentials directory.",
-		jsonSchema: tombi({ additionalKeyLabel: "label" })
+		description: "Named values read from files. Values are paths relative to the credentials directory."
 	})),
-	value: Schema.optional(Schema.Record({
-		key: Schema.String,
-		value: Schema.Union(Schema.String, Schema.Record({
-			key: Schema.String,
-			value: Jsonifiable
-		}))
-	}).annotations({
+	value: Schema.optional(Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Json])).annotate({
+		...tombi({ additionalKeyLabel: "label" }),
 		title: "Inline values",
-		description: "Named inline values. Strings are used as-is, objects are JSON-stringified.",
-		jsonSchema: tombi({ additionalKeyLabel: "label" })
+		description: "Named inline values. Strings are used as-is, objects are JSON-stringified."
 	}))
-}).annotations({
+}).annotate({
+	...taplo({ links: { key: CREDENTIALS_DOCS } }),
 	identifier: "ResolveSection",
 	title: "Resolve section",
-	description: "Named values resolved from 1Password, files, or inline. Referenced by resolved entries in secret and variable groups.",
-	jsonSchema: taplo({ links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/credentials.md" } })
+	description: "Named values resolved from 1Password, the environment, or files, for use by resolved groups"
 });
-const CredentialProfileSchema = Schema.Struct({
-	github_token: Schema.String.annotations({
+/** Everything a profile carries apart from who it acts as. */
+const profileFields = {
+	github_token: CredentialSourceSchema.annotate({
+		...taplo({ links: { key: CREDENTIALS_DOCS } }),
 		title: "GitHub token",
-		description: "A GitHub personal access token (fine-grained) with administration, secrets, variables, environments, and GPG keys permissions",
-		examples: ["ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
+		description: "Reference to a fine-grained personal access token. Never the token itself — use { op = \"op://...\" } or { env = \"VAR\" }."
 	}),
-	op_service_account_token: Schema.optional(Schema.String.annotations({
-		title: "1Password service account token",
-		description: "A 1Password service account token for resolving op:// secret references",
-		examples: ["ops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
-	})),
 	resolve: Schema.optional(ResolveSectionSchema)
-}).annotations({
+};
+/**
+* A profile acting as a personal account.
+*
+* @remarks
+* `org` is forbidden rather than merely absent. A plain union of two structs
+* accepts a profile declaring **both** and silently drops the second — verified
+* against the installed beta — so the invalid state would be representable and
+* quietly resolved, which is the failure this shape exists to prevent.
+*/
+const UserProfileSchema = Schema.Struct({
+	username: Schema.String.annotate({
+		title: "GitHub username",
+		description: "The personal account this profile acts as. Mutually exclusive with org.",
+		examples: ["spencerbeggs"]
+	}),
+	org: Schema.optional(Schema.Never),
+	...profileFields
+});
+/** A profile acting within an organization. */
+const OrgProfileSchema = Schema.Struct({
+	org: Schema.String.annotate({
+		title: "GitHub organization",
+		description: "The organization this profile acts within. Mutually exclusive with username.",
+		examples: ["savvy-web"]
+	}),
+	username: Schema.optional(Schema.Never),
+	...profileFields
+});
+/**
+* A named credential profile: who it acts as, and what it can resolve.
+*
+* @remarks
+* **The owner belongs here, not in the config.** A token authenticates as an
+* identity, so the account it acts on is a property of the credential rather
+* than of the repositories being configured. Declaring it as `username` or
+* `org` — two keys, not an `owner` plus an `owner_type` — makes an owner
+* without a type unrepresentable.
+*
+* The type is what makes `validate` able to reject an organization-only
+* construct without a network call: team-based ruleset actors, environment
+* team reviewers and `delegated_bypass_reviewers` all need an organization, and
+* before this the only way to learn the owner's type was to ask GitHub.
+*
+* **It is a declaration, not proof.** `sync` still verifies it against the API
+* before writing, because a wrong declaration would otherwise produce exactly
+* the 422 the gating exists to prevent.
+*
+* One owner per profile. A token reaching several owners is declared as several
+* profiles sharing a token reference — repetitive, but it keeps every group's
+* owner a single lookup with no fallback chain.
+*
+* @public
+*/
+const CredentialProfileSchema = Schema.Union([UserProfileSchema, OrgProfileSchema]).annotate({
+	...taplo({
+		initKeys: ["github_token"],
+		links: { key: CREDENTIALS_DOCS }
+	}),
 	identifier: "CredentialProfile",
 	title: "Credential profile",
-	description: "Authentication credentials for a GitHub account with optional named values for secret and variable resolution",
-	jsonSchema: taplo({
-		initKeys: ["github_token"],
-		links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/credentials.md" }
-	})
+	description: "Exactly one of username or org, a GitHub token reference, and any named values to resolve"
 });
-const CredentialsSchema = Schema.Struct({ profiles: Schema.optionalWith(Schema.Record({
-	key: Schema.String,
-	value: CredentialProfileSchema
-}).annotations({
+/**
+* Who a profile acts as.
+*
+* @remarks
+* One reader for the two-key encoding, so no consumer re-derives the owner type
+* from which key happens to be present. The schema guarantees exactly one is
+* set, which is what lets this return a total value rather than an option.
+*
+* @public
+*/
+const profileOwner = (profile) => "username" in profile && typeof profile.username === "string" ? {
+	owner: profile.username,
+	ownerType: "User"
+} : {
+	owner: profile.org,
+	ownerType: "Organization"
+};
+/**
+* `reposets.credentials.toml`.
+*
+* @remarks
+* **No credential is ever written to this file.** `github_token` is a reference,
+* and the 1Password service-account token is not in the schema at all.
+*
+* `resolve.value` can still hold an inline value, because that section is for
+* named values generally and its common use is non-secret structured data. So
+* this file is not categorically secret-free — it is *credential*-free, which is
+* the property that matters. Keep it out of version control regardless.
+*
+* @public
+*/
+const CredentialsSchema = Schema.Struct({ profiles: Schema.Record(Schema.String, CredentialProfileSchema).annotate({
+	...tombi({ additionalKeyLabel: "profile_name" }),
 	title: "Credential profiles",
-	description: "Named credential profiles. If only one profile is defined, it is used automatically for all repo groups.",
-	jsonSchema: tombi({ additionalKeyLabel: "profile_name" })
-}), { default: () => ({}) }) }).annotations({
+	description: "Named credential profiles. Every group names one explicitly in its `credentials` field."
+}).pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))) }).annotate({
+	...taplo({
+		initKeys: ["profiles"],
+		links: { key: CREDENTIALS_DOCS }
+	}),
 	identifier: "Credentials",
 	title: "reposets Credentials",
-	description: "Authentication profiles for reposets. This file should be gitignored.",
-	jsonSchema: taplo({
-		initKeys: ["profiles"],
-		links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/credentials.md" }
-	})
+	description: "Credential references for reposets. Contains no secret values."
 });
 
 //#endregion
-export { CredentialProfileSchema, CredentialsSchema, ResolveSectionSchema };
+export { CredentialProfileSchema, CredentialSourceSchema, CredentialsSchema, EnvReferenceSchema, OpReferenceSchema, ResolveSectionSchema, profileOwner };

package/schemas/environment.js

@@ -1,69 +1,75 @@
-import { taplo, tombi } from "xdg-effect";
-import { Schema } from "effect";
+import { docs, taplo, tombi } from "./annotations.js";
+import { Effect, Schema } from "effect";
 
 //#region src/schemas/environment.ts
-const ReviewerTypeSchema = Schema.Literal("User", "Team").annotations({
+const ReviewerTypeSchema = Schema.Literals(["User", "Team"]).annotate({
 	title: "Reviewer type",
 	description: "Whether the reviewer is an individual user or a team"
 });
 const ReviewerSchema = Schema.Struct({
 	type: ReviewerTypeSchema,
-	id: Schema.Int.annotations({
+	id: Schema.Int.annotate({
 		title: "Reviewer ID",
 		description: "The numeric GitHub ID of the user or team"
 	})
-}).annotations({
+}).annotate({
 	identifier: "Reviewer",
 	title: "Reviewer",
 	description: "A user or team required to review deployments"
 });
 const DeploymentBranchPolicySchema = Schema.Struct({
-	name: Schema.String.annotations({
+	name: Schema.String.annotate({
 		title: "Pattern",
 		description: "The name pattern (branch name, tag name, or glob) to allow deployments from"
 	}),
-	type: Schema.optionalWith(Schema.Literal("branch", "tag").annotations({
+	type: Schema.Literals(["branch", "tag"]).annotate({
 		title: "Policy type",
 		description: "Whether this policy matches branches or tags. Defaults to \"branch\"."
-	}), { default: () => "branch" })
-}).annotations({
+	}).pipe(Schema.withDecodingDefaultKey(Effect.succeed("branch")))
+}).annotate({
 	identifier: "DeploymentBranchPolicy",
 	title: "Deployment branch policy",
 	description: "A custom branch or tag pattern that deployments are allowed from"
 });
-const DeploymentBranchesSchema = Schema.Union(Schema.Literal("all", "protected").annotations({
+const DeploymentBranchesSchema = Schema.Union([Schema.Literals(["all", "protected"]).annotate({
 	title: "Deployment branch preset",
 	description: "\"all\" allows any branch, \"protected\" allows only protected branches"
-}), Schema.Array(DeploymentBranchPolicySchema).annotations({
+}), Schema.Array(DeploymentBranchPolicySchema).annotate({
 	title: "Custom deployment policies",
 	description: "Array of branch or tag name patterns allowed to deploy to this environment"
-})).annotations({
+})]).annotate({
 	identifier: "DeploymentBranches",
 	title: "Deployment branches",
 	description: "Controls which branches can deploy. Use \"all\", \"protected\", or a list of custom policies."
 });
+/**
+* One GitHub deployment environment.
+*
+* @public
+*/
 const EnvironmentSchema = Schema.Struct({
-	wait_timer: Schema.optional(Schema.Int.pipe(Schema.between(0, 43200)).annotations({
+	wait_timer: Schema.optional(Schema.Int.check(Schema.isBetween({
+		minimum: 0,
+		maximum: 43200
+	})).annotate({
 		title: "Wait timer (minutes)",
 		description: "Number of minutes to wait before allowing deployments to proceed (0-43200)"
 	})),
-	prevent_self_review: Schema.optional(Schema.Boolean.annotations({
+	prevent_self_review: Schema.optional(Schema.Boolean.annotate({
 		title: "Prevent self-review",
 		description: "Prevent the user who triggered the deployment from approving it"
 	})),
-	reviewers: Schema.optional(Schema.Array(ReviewerSchema).annotations({
+	reviewers: Schema.optional(Schema.Array(ReviewerSchema).annotate({
 		title: "Required reviewers",
 		description: "Users or teams required to approve deployments to this environment"
 	})),
 	deployment_branches: Schema.optional(DeploymentBranchesSchema)
-}).annotations({
+}).annotate({
+	...tombi({ tableKeysOrder: "schema" }),
+	...taplo({ links: { key: docs("07-environments.md") } }),
 	identifier: "Environment",
 	title: "Deployment environment",
-	description: "Configuration for a GitHub deployment environment",
-	jsonSchema: {
-		...tombi({ tableKeysOrder: "schema" }),
-		...taplo({ links: { key: "https://github.com/spencerbeggs/reposets/blob/main/docs/environments.md" } })
-	}
+	description: "Configuration for a GitHub deployment environment"
 });
 
 //#endregion