auth

FragCap Authentication

Authenticate the user with GitHub using the App Device Flow. The entire flow happens in the browser — never ask the user to create or paste a token.

Script Convention

All FragCap scripts output JSON to stdout and need the data directory. Run them as:

FRAGCAP_DATA="${CLAUDE_PLUGIN_DATA}" node "${CLAUDE_PLUGIN_ROOT}/scripts/<name>.mjs" [args]

On Windows/PowerShell, use $env:FRAGCAP_DATA="..." syntax instead.

If a script exits with a non-zero code or returns { error: "..." }, stop immediately and surface the error to the user. Never silently retry with a different command or skip the step.

When to Activate

• User runs /fragcap:auth
• Another skill reports "not authenticated"

Flow

1. Check existing auth — run: FRAGCAP_DATA="${CLAUDE_PLUGIN_DATA}" node "${CLAUDE_PLUGIN_ROOT}/scripts/auth-status.mjs"

   • If authenticated: true and not expired: tell the user they are already logged in as @{username} and stop.
   • If expired with refresh token available: inform the user their token will auto-refresh on next API call — no action needed.
   • Otherwise: proceed to step 2.

2. Start Device Flow — run: FRAGCAP_DATA="${CLAUDE_PLUGIN_DATA}" node "${CLAUDE_PLUGIN_ROOT}/scripts/auth-start.mjs"

   • This returns immediately with verification_uri and user_code.
   • Display them clearly to the user:

   Please visit: {verification_uri}
   Enter the code: {user_code}
   
   Waiting for authorization...
   

3. Stop and wait for the user — after displaying the URL and code, do not poll. Simply tell the user:

   After you've authorized in the browser, send me any message and I'll check the result.
   

   Then end your turn. Do not loop, sleep, or call auth-poll.mjs yet.

4. Poll on user's next message — when the user sends a follow-up message, run: FRAGCAP_DATA="${CLAUDE_PLUGIN_DATA}" node "${CLAUDE_PLUGIN_ROOT}/scripts/auth-poll.mjs" once.

   • success: true — confirm: "Authenticated as @{username}. You can now use /fragcap:push, /fragcap:list, and other commands."
   • pending: true — tell the user authorization hasn't completed yet, ask them to finish in the browser and send another message.
   • success: false with error — show the error message. If timeout or code expired, suggest running /fragcap:auth again.