fix(contract): validate role names for stable machine output (#42)

Harden the role-name contract so machine-readable surfaces like
`status --short` stay predictable.

Also:
- centralize role-name validation in `src/domain/role.ts`
- require role names to match `^[a-z0-9_-]+$`
- add `InvalidRoleNameError` with clear user-facing messages
- enforce validation in role creation and import
- enforce validation on direct role-referencing commands
- make invalid persisted role data fail clearly during normalization
- add focused CLI and use-case coverage for valid/invalid names
- keep `status --short` exact and safe for valid names

Verified with:
- npm run build
- npm test
- npm run test:e2e
- npm run test:release

Author: saraeloop

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+### Breaking Changes
+
+* role names are now restricted to lowercase letters, numbers, `_`, and `-` so machine-readable output like `gitrole status --short` stays stable
+* existing saved roles with names outside that policy, such as `client acme`, `Work`, or `prod/main`, now fail clearly and should be renamed or recreated with a contract-safe name
+
 ## [0.7.0](https://github.com/synsoftworks/gitrole/compare/v0.6.0...v0.7.0) (2026-04-12)
 
 

src/application/use-cases/pin.ts

@@ -1,6 +1,7 @@
 /*
  * Creates a strict repo-local .gitrole policy for the current repository.
  */
+import { validateRoleName } from '../../domain/role.js';
 import type { PinRepoPolicyDependencies, PinRepoPolicyResult } from '../contracts.js';
 import { saveRepoPolicy } from '../repo-policy.js';
 import { ProfileNotFoundError } from './role.js';
@@ -29,10 +30,11 @@ export async function pinRepoPolicy(
   dependencies: PinRepoPolicyDependencies,
   name: string
 ): Promise<PinRepoPolicyResult> {
-  const role = await dependencies.roleStore.get(name);
+  const roleName = validateRoleName(name);
+  const role = await dependencies.roleStore.get(roleName);
 
   if (!role) {
-    throw new ProfileNotFoundError(name);
+    throw new ProfileNotFoundError(roleName);
   }
 
   if (!(await dependencies.repository.isInsideWorkTree())) {

src/application/use-cases/remote.ts

@@ -1,6 +1,7 @@
 /*
  * Rewrites repository remotes to match the selected role's GitHub SSH host.
  */
+import { validateRoleName } from '../../domain/role.js';
 import { type RemoteUseDependencies, type RemoteUseResult } from '../contracts.js';
 import { ProfileNotFoundError } from './role.js';
 
@@ -45,14 +46,15 @@ export async function useRemoteForRole(
   dependencies: RemoteUseDependencies,
   name: string
 ): Promise<RemoteUseResult> {
-  const role = await dependencies.roleStore.get(name);
+  const roleName = validateRoleName(name);
+  const role = await dependencies.roleStore.get(roleName);
 
   if (!role) {
-    throw new ProfileNotFoundError(name);
+    throw new ProfileNotFoundError(roleName);
   }
 
   if (!role.githubHost) {
-    throw new RoleMissingGithubHostError(name);
+    throw new RoleMissingGithubHostError(roleName);
   }
 
   const previousUrl = await dependencies.repository.getOriginUrl();

src/application/use-cases/role.ts

@@ -1,7 +1,12 @@
 /*
  * Implements role creation, activation, lookup, and removal workflows.
  */
-import { matchesIdentity, normalizeRole, type Role } from '../../domain/role.js';
+import {
+  matchesIdentity,
+  normalizeRole,
+  validateRoleName,
+  type Role
+} from '../../domain/role.js';
 import {
   type AppDependencies,
   type CurrentRoleDependencies,
@@ -81,11 +86,12 @@ export async function useRole(
   name: string,
   options: UseRoleOptions = {}
 ): Promise<UseRoleResult> {
-  const role = await dependencies.roleStore.get(name);
+  const roleName = validateRoleName(name);
+  const role = await dependencies.roleStore.get(roleName);
   const scope = options.scope ?? 'global';
 
   if (!role) {
-    throw new ProfileNotFoundError(name);
+    throw new ProfileNotFoundError(roleName);
   }
 
   if (scope === 'local') {
@@ -178,14 +184,15 @@ export async function importCurrentRole(
   dependencies: CurrentRoleDependencies,
   name: string
 ): Promise<ImportCurrentRoleResult> {
+  const roleName = validateRoleName(name);
   const currentIdentity = await getEffectiveCurrentIdentity(dependencies);
 
   if (!currentIdentity.fullName || !currentIdentity.email) {
     throw new IncompleteCurrentIdentityError();
   }
 
   const role = await addRole(dependencies, {
-    name,
+    name: roleName,
     fullName: currentIdentity.fullName,
     email: currentIdentity.email
   });
@@ -246,13 +253,14 @@ export async function removeRole(
   dependencies: AppDependencies,
   name: string
 ): Promise<Role> {
-  const role = await dependencies.roleStore.get(name);
+  const roleName = validateRoleName(name);
+  const role = await dependencies.roleStore.get(roleName);
 
   if (!role) {
-    throw new ProfileNotFoundError(name);
+    throw new ProfileNotFoundError(roleName);
   }
 
-  await dependencies.roleStore.remove(name);
+  await dependencies.roleStore.remove(roleName);
 
   return role;
 }

src/domain/role.ts

@@ -15,14 +15,31 @@ export interface GitIdentity {
   email?: string;
 }
 
+const roleNamePattern = /^[a-z0-9_-]+$/;
+
+export class InvalidRoleNameError extends Error {
+  constructor(input: string) {
+    super(`invalid role name "${input}"; use lowercase letters, numbers, "-" or "_"`);
+    this.name = 'InvalidRoleNameError';
+  }
+}
+
+export function validateRoleName(input: string): string {
+  if (!input || input.trim() !== input || !roleNamePattern.test(input)) {
+    throw new InvalidRoleNameError(input);
+  }
+
+  return input;
+}
+
 /**
  * Normalizes persisted role input so comparisons and storage stay stable.
  *
  * Trims all string fields and removes empty optional values.
  */
 export function normalizeRole(input: Role): Role {
   return {
-    name: input.name.trim(),
+    name: validateRoleName(input.name),
     fullName: input.fullName.trim(),
     email: input.email.trim(),
     sshKeyPath: input.sshKeyPath?.trim() || undefined,