feat(cli): add org (-o) and token (-t) flags by wiiiimm · Pull Request #18 · wiiiimm/gh-manager-cli

wiiiimm · 2025-09-02T15:05:11Z

This PR combines two CLI enhancements and related UI wiring and docs.\n\nFeatures\n- Add organisation context flag: --org with short alias -o\n - Allows starting the app scoped to an accessible organisation\n - Waits for UI prefs to load; applies once per run\n- Add ephemeral token flag: --token with short alias -t\n - Token precedence: CLI > env (GITHUB_TOKEN/GH_TOKEN) > stored config\n - Does not persist when provided via CLI flag\n\nImplementation\n- src/index.tsx: flag parsing and help text updates\n- src/ui/App.tsx: prefer inline token; skip persistence when ephemeral\n- src/ui/RepoList.tsx: initial org flag application; stable onOrgContextChange ref\n\nDocs\n- README + wiki/Usage: document --org/-o and --token/-t with examples\n- wiki/Token-and-Security: add precedence and safety notes for CLI tokens\n- TODOs: track --token/-t work under CLI flags\n\nNotes\n- Includes RepoList optimizations (useCallback; stable handler ref)\n- Tested locally for flag parsing precedence and help output

Summary by CodeRabbit

New Features
- CLI flags: --org / -o (start in an organisation, optional leading @), --token / -t (ephemeral per-run PAT, precedence over env/stored), --help / -h, --version / -v.
- App accepts initialOrgSlug/inlineToken and can auto‑apply an organisation on startup; improved startup, shutdown, error and debug logging.
Documentation
- Expanded README, wiki and TODOs with CLI flags, navigation/view controls, repository actions, token precedence and security guidance (README contains duplicate block).

Co-authored-by: william <william@alt-x.ventures>

…<slug>\n- Update help text to show alias

…e --token and -t (value or =value)\n- Prefer inline token over env/config for this run\n- Do not persist when provided via CLI flag\n- Help text: document token flag in usage

…n\n- README: add usage, examples, and non-persistence\n- wiki/Usage: add flag, examples, precedence, and security note

…cument precedence and non-persistence of CLI token\n- Add security considerations and safer usage examples

…ontext Co-authored-by: william <william@alt-x.ventures>

coderabbitai · 2025-09-02T16:45:15Z

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Adds CLI flags (--org/-o, --token/-t) and related docs; index.tsx parses and normalises flags, adds startup/shutdown and fatal-error logging; App accepts initialOrgSlug/inlineToken and enforces token precedence and conditional persistence; RepoList applies initial organisation context on mount.

Changes

Cohort / File(s)	Summary
Docs: README & TODOs `README.md`, `TODOs.md`	Expanded CLI flags and interactive controls docs; documented `--org`/`-o` and `--token`/`-t` usage, examples, precedence and security notes; marked `--org`/`--token` behaviour in TODOs as implemented.
Wiki updates `wiki/Usage.md`, `wiki/Token-and-Security.md`	Added CLI Flags section and CLI token vs environment guidance; documented precedence (CLI > env > stored), non-persistence of inline tokens, examples and security caveats; minor formatting trim.
CLI bootstrap & runtime `src/index.tsx`	Added flag parsing helpers and support for `--org`/`-o` and `--token`/`-t` (with normalization); extended help output; pass `initialOrgSlug`, `inlineToken`, `inlineTokenEphemeral` to App; added GH_MANAGER_DEBUG, startup logs, signal handlers and uncaught exception/rejection handlers.
App auth precedence & persistence `src/ui/App.tsx`	App now accepts `initialOrgSlug`, `inlineToken`, `inlineTokenEphemeral`; introduced `sessionTokenOrigin`; implemented token selection precedence (cli > env > stored > prompt), conditional persistence logic, updated validation/logout logging, and forwards `initialOrgSlug` to RepoList.
RepoList initial org context `src/ui/RepoList.tsx`	Added optional `initialOrgSlug` prop; one-time init effect fetches viewer organisations and switches org context if slug matches (case-insensitive, optional leading @); uses stable handler ref, guards by token/prefs readiness, and emits debug messages.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User
  participant CLI as index.tsx
  participant App as App
  participant RepoList as RepoList
  participant GH as GitHub API

  Note over CLI: Parse flags (--org/-o, --token/-t)
  User->>CLI: Run gh-manager-cli [--org SLUG] [--token PAT]
  CLI->>App: Start App(initialOrgSlug, inlineToken, inlineTokenEphemeral)

  rect rgba(200,230,255,0.18)
  Note right of App: Token selection & validation
  App->>App: Determine token origin (cli > env > stored > prompt)
  alt Token present
    App->>GH: Validate token
    GH-->>App: Valid / Invalid
    alt Valid
      App->>App: Persist token? (!stored && !inlineTokenEphemeral)
    end
  else No token
    App->>User: Prompt for auth method/token
  end
  end

  App->>RepoList: Render with initialOrgSlug
  rect rgba(220,255,220,0.18)
  Note over RepoList: Apply initial --org if provided
  RepoList->>GH: Fetch viewer organisations
  GH-->>RepoList: Organisations list
  alt Slug matches accessible org
    RepoList->>RepoList: Switch org context
  else No match / inaccessible
    RepoList->>RepoList: Keep default context
  end
  end

sequenceDiagram
  autonumber
  participant Proc as Process
  participant Logger as Logger

  Proc->>Logger: Startup log (version, Node.js)
  Proc->>Logger: GH_MANAGER_DEBUG toggles verbose logs
  Proc->>Proc: Register SIGINT/SIGTERM/exit handlers
  Proc->>Logger: On signal -> log and exit
  Proc->>Logger: On uncaughtException/unhandledRejection -> log fatal and exit(1)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

I twitched my whiskers, parsed a flag,
Hopped to an org without a snag.
Tokens took their proper place,
Logs bowed out with calm, neat grace.
A rabbit ships, then naps — hooray! 🐇✨

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6883902 and 4bce3a2.

📒 Files selected for processing (1)

src/ui/App.tsx (9 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/ui/App.tsx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Cursor Bugbot

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feature/cli-org-flag

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

src/ui/RepoList.tsx (2)

627-629: Bug: visibilityFilter may be set to unsupported value “internal”

Type is 'all' | 'public' | 'private', but persisted value may be "internal". This leads to inconsistent filtering.

Apply this diff to normalise persisted "internal" to "private":

-    if (ui.visibilityFilter && ['all', 'public', 'private', 'internal'].includes(ui.visibilityFilter)) {
-      setVisibilityFilter(ui.visibilityFilter as VisibilityFilter);
-    }
+    if (ui.visibilityFilter && ['all', 'public', 'private', 'internal'].includes(ui.visibilityFilter)) {
+      const vf = ui.visibilityFilter === 'internal' ? 'private' : ui.visibilityFilter;
+      setVisibilityFilter(vf as VisibilityFilter);
+    }

756-776: Bug: orgLogin is undefined in search bootstrap effect

makeSearchKey call references orgLogin which isn’t defined in this scope. This will crash at runtime.

Apply this diff to keep the key consistent with other usages and remove the bad refs:

-      try {
-        const key = makeSearchKey({
-          viewer: viewerLogin || 'unknown',
-          q: filter.trim(),
-          sortKey,
-          sortDir,
-          pageSize: PAGE_SIZE,
-          forkTracking,
-          ownerContext: orgLogin ? `org:${orgLogin}` : 'personal',
-          affiliations: ownerAffiliations.join(',')
-        });
-        policy = isFresh(key, 90 * 1000) ? 'cache-first' : 'network-only';
-      } catch {}
+      try {
+        const key = makeSearchKey({
+          viewer: viewerLogin || 'unknown',
+          q: filter.trim(),
+          sortKey,
+          sortDir,
+          pageSize: PAGE_SIZE,
+          forkTracking,
+        });
+        policy = isFresh(key, 90 * 1000) ? 'cache-first' : 'network-only';
+      } catch {}

src/ui/App.tsx (1)

51-71: Do not persist env-provided tokens; set tokenSource for inline/env/stored

Currently, env tokens will be persisted if no stored token exists, which is a security footgun. Also, tokenSource isn’t set when using an inline token, which undermines downstream logic/telemetry.

   const env = getTokenFromEnv();
   const stored = getStoredToken();
   const source = getTokenSource();

   setTokenSource(source);

-  if (inlineToken) {
-    // Highest precedence: inline token from CLI flag; do not persist
-    setToken(inlineToken);
-    setMode('validating');
-  } else if (env) {
-    setToken(env);
-    setMode('validating');
-  } else if (stored) {
-    setToken(stored);
-    setMode('validating');
-  } else {
-    setMode('auth_method_selection');
-  }
+  if (inlineToken) {
+    // Highest precedence: inline token from CLI flag; do not persist
+    setTokenSource('inline');
+    setToken(inlineToken);
+    setMode('validating');
+  } else if (env) {
+    setTokenSource('env');
+    setToken(env);
+    setMode('validating');
+  } else if (stored) {
+    setTokenSource('stored');
+    setToken(stored);
+    setMode('validating');
+  } else {
+    setMode('auth_method_selection');
+  }

🧹 Nitpick comments (14)

TODOs.md (1)

345-347: Consistent English variant (“organisation” vs “organization”)

This file mixes variants. Pick one (project seems to prefer British English) and standardise across docs.
wiki/Usage.md (1)
7-10: Document case‑insensitive slug matching (align with code)

The app matches org slugs case‑insensitively. Add a note for users.

Apply this diff:
-  - Leading `@` is optional. Personal usernames are not supported by `--org`/`-o` (use default personal context).
+  - Leading `@` is optional. Personal usernames are not supported by `--org`/`-o` (use default personal context).
+  - Matching is case‑insensitive.
src/ui/RepoList.tsx (3)
345-351: Reuse existing GraphQL client instead of recreating

Avoid recreating the client in handleOrgContextChange.

Apply this diff:
-      const client = makeClient(token);
-      const isEnt = await checkOrganizationIsEnterprise(client, newContext.login);
+      const isEnt = await checkOrganizationIsEnterprise(client, newContext.login);
501-506: Reuse existing GraphQL client in fetchPage

No need to re-instantiate a client for the ENT check.

Apply this diff:
-        const client = makeClient(token);
-        checkOrganizationIsEnterprise(client, orgLogin).then(isEnt => {
+        checkOrganizationIsEnterprise(client, orgLogin).then(isEnt => {
           setIsEnterpriseOrg(isEnt);
         });
1336-1336: Include all modals in modalOpen to ensure consistent dimming

sortMode and changeVisibilityMode aren’t included; header/list may not dim consistently.

Apply this diff:
-  const modalOpen = deleteMode || archiveMode || syncMode || logoutMode || infoMode || visibilityMode;
+  const modalOpen = deleteMode || archiveMode || syncMode || logoutMode || infoMode || visibilityMode || changeVisibilityMode || sortMode;
README.md (3)
211-222: Standardise spelling: use “organization” consistently

README mixes “organisation” and “organization”. Given GitHub uses “organization”, stick to that for consistency.
-### CLI Flags
-
-- `--org, -o <slug>`: Start in a specific organisation context (if accessible). Ignores the flag if you don’t have access or if the slug isn’t an organisation.
+### CLI Flags
+
+- `--org, -o <slug>`: Start in a specific organization context (if accessible). Ignores the flag if you don’t have access or if the slug isn’t an organization.
223-233: Minor punctuation/formatting nits

Hyphenation and punctuation around list items can trip LanguageTool (“loose punctuation”). Not blocking, but consider a blank line before each bullet group and consistent punctuation at ends.

410-411: Fix command typo

There’s an extra “-cli” in the combined env example.
-REPOS_PER_FETCH=5 GH_MANAGER_DEBUG=1 npx gh-manager-cli-cli
+REPOS_PER_FETCH=5 GH_MANAGER_DEBUG=1 npx gh-manager-cli
src/ui/App.tsx (3)
170-175: Logging field inverted/misleading

tokenStored: !getStoredToken() reads as “token stored = true when none exists”. Rename and flip for clarity.
-          tokenStored: !getStoredToken()
+          hadStoredToken: Boolean(getStoredToken())
30-31: Unused state: deviceCodeResponse

deviceCodeResponse is set but never read. Remove state/import if not needed.

322-341: Header formatting nit

org/login renders like org/@viewer. Consider @viewer (org) or org • @viewer for readability. Non-blocking.
src/index.tsx (3)
13-40: CLI helpers are simple and robust

Covers --name=value, --name value, -x=value, -x value. Consider supporting -o@acme as a convenience in future.
-const getShortFlagValue = (short: string): string | undefined => {
+const getShortFlagValue = (short: string): string | undefined => {
   // Supports -x value and -x=value
   const exact = `-${short}`;
-  const idx = argv.findIndex(a => a === exact || a.startsWith(`${exact}=`));
+  const idx = argv.findIndex(a =>
+    a === exact || a.startsWith(`${exact}=`) || a.startsWith(`${exact}@`)
+  );
   if (idx === -1) return undefined;
   const at = argv[idx];
   if (at.includes('=')) {
     const [, v] = at.split('=');
     return v?.trim() || undefined;
   }
+  if (at.startsWith(`${exact}@`)) {
+    return at.slice(exact.length + 1).trim(); // -o@acme
+  }
   const next = argv[idx + 1];
   if (next && !next.startsWith('-')) return next.trim();
   return undefined;
 };
52-56: Help text: US spelling and short flags

Minor copyedit to align with README and GitHub’s terminology; include short flags in the help for symmetry.
-    `  gh-manager-cli --org, -o <slug>    Start in an organisation context (if accessible)\n` +
-    `  gh-manager-cli --token, -t <pat>   Use a token just for this run (not persisted)\n` +
-    `  gh-manager-cli --version           Print version\n` +
-    `  gh-manager-cli --help              Show help\n\n` +
+    `  gh-manager-cli --org, -o <slug>    Start in an organization context (if accessible)\n` +
+    `  gh-manager-cli --token, -t <pat>   Use a token just for this run (not persisted)\n` +
+    `  gh-manager-cli --version, -v       Print version\n` +
+    `  gh-manager-cli --help, -h          Show help\n\n` +
105-112: Normalise org slug to lowercase

GitHub org slugs are lowercase; normalising helps matching.
-  return v.replace(/^@/, '');
+  return v.replace(/^@/, '').toLowerCase();

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between cfadd7a and 48bf291.

📒 Files selected for processing (7)

README.md (1 hunks)
TODOs.md (1 hunks)
src/index.tsx (3 hunks)
src/ui/App.tsx (5 hunks)
src/ui/RepoList.tsx (3 hunks)
wiki/Token-and-Security.md (1 hunks)
wiki/Usage.md (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

src/ui/App.tsx (1)

src/config.ts (1)

getStoredToken (64-67)

src/index.tsx (1)

src/ui/App.tsx (1)

App (16-513)

src/ui/RepoList.tsx (2)

src/config.ts (1)

OwnerContext (7-7)

src/github.ts (2)

makeClient (10-14)

fetchViewerOrganizations (117-136)

🪛 LanguageTool

TODOs.md

[uncategorized] ~345-~345: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...nch with --org <slug> to jump to that organisation context if accessible; otherwise ignore...

(EN_WORD_COHERENCY)

wiki/Usage.md

[uncategorized] ~7-~7: Loose punctuation mark.
Context: ...ies. ## CLI Flags - --org, -o <slug>: Start in a specific organisation contex...