create-hq 10.8.0 → 10.9.0

package/dist/__tests__/auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.test.d.ts.map

package/dist/__tests__/auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/auth.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/auth.test.js

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from "vitest";
+import * as path from "path";
+import * as os from "os";
+import * as fs from "fs";
+/**
+ * Unit tests for auth.ts:
+ *   - githubApi error handling (403 on /user/installations)
+ *   - ~/.hq/app-token.json persistence (load / save / clear)
+ *   - Token validation via /user/installations probe
+ */
+// ─── Mocks ─────────────────────────────────────────────────────────────────
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+// Mock child_process so module-level execSync calls in auth.ts don't run
+vi.mock("child_process", () => ({
+    exec: vi.fn(),
+    execSync: vi.fn(),
+}));
+// Import after mocks are in place
+const { githubApi, loadGitHubAuth, saveGitHubAuth, clearGitHubAuth, isGitHubAuthValid, isAppScopedToken, HQ_APP_TOKEN_PATH, } = await import("../auth.js");
+// ─── Fixtures ──────────────────────────────────────────────────────────────
+const fakeAuth = {
+    access_token: "ghu_fake_app_token",
+    login: "testuser",
+    id: 12345,
+    name: "Test User",
+    email: "test@example.com",
+    issued_at: new Date().toISOString(),
+};
+// Use a temp directory so tests don't touch the real ~/.hq/
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-hq-auth-test-"));
+const tmpTokenPath = path.join(tmpDir, "app-token.json");
+// ─── githubApi ─────────────────────────────────────────────────────────────
+describe("githubApi", () => {
+    beforeEach(() => mockFetch.mockReset());
+    it("throws a user-friendly message on 403 for /user/installations", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 403,
+            text: async () => JSON.stringify({
+                message: "You must authenticate with an access token authorized to a GitHub App in order to list installations",
+                documentation_url: "https://docs.github.com/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token",
+                status: "403",
+            }),
+        });
+        await expect(githubApi("/user/installations?per_page=100", fakeAuth)).rejects.toThrow(/signed in with a regular GitHub token/i);
+    });
+    it("includes the re-run hint in the 403 installations error", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 403,
+            text: async () => JSON.stringify({
+                message: "You must authenticate with an access token authorized to a GitHub App",
+            }),
+        });
+        await expect(githubApi("/user/installations?per_page=100", fakeAuth)).rejects.toThrow(/npx create-hq/);
+    });
+    it("preserves the raw error for non-installation 403s", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 403,
+            text: async () => JSON.stringify({ message: "Resource not accessible by integration" }),
+        });
+        await expect(githubApi("/orgs/acme/repos", fakeAuth)).rejects.toThrow(/GitHub API 403 \/orgs\/acme\/repos/);
+    });
+    it("throws the raw error for non-403 failures", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 404,
+            text: async () => JSON.stringify({ message: "Not Found" }),
+        });
+        await expect(githubApi("/user/installations?per_page=100", fakeAuth)).rejects.toThrow(/GitHub API 404/);
+    });
+    it("returns parsed JSON on success", async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => ({ installations: [] }),
+        });
+        const result = await githubApi("/user/installations?per_page=100", fakeAuth);
+        expect(result).toEqual({ installations: [] });
+    });
+});
+// ─── ~/.hq/app-token.json persistence ──────────────────────────────────────
+describe("App token persistence", () => {
+    afterEach(() => {
+        // Clean up temp token file between tests
+        try {
+            fs.unlinkSync(tmpTokenPath);
+        }
+        catch { }
+    });
+    afterEach(() => {
+        // Clean up the real path if any test accidentally wrote there
+        // (shouldn't happen — we test with tmpTokenPath)
+    });
+    it("HQ_APP_TOKEN_PATH points to ~/.hq/app-token.json", () => {
+        const expected = path.join(os.homedir(), ".hq", "app-token.json");
+        expect(HQ_APP_TOKEN_PATH).toBe(expected);
+    });
+    it("saveGitHubAuth writes token file to disk", () => {
+        saveGitHubAuth(fakeAuth, tmpTokenPath);
+        // File was written
+        expect(fs.existsSync(tmpTokenPath)).toBe(true);
+        const stored = JSON.parse(fs.readFileSync(tmpTokenPath, "utf-8"));
+        expect(stored.login).toBe("testuser");
+        expect(stored.access_token).toBe("ghu_fake_app_token");
+    });
+    it("saveGitHubAuth creates ~/.hq/ directory if missing", () => {
+        const nested = path.join(tmpDir, "sub", "app-token.json");
+        saveGitHubAuth(fakeAuth, nested);
+        expect(fs.existsSync(nested)).toBe(true);
+    });
+    it("saveGitHubAuth sets restrictive file permissions (0600)", () => {
+        saveGitHubAuth(fakeAuth, tmpTokenPath);
+        const stat = fs.statSync(tmpTokenPath);
+        // Owner read+write only (0600 = 0o600 = 384 decimal)
+        expect(stat.mode & 0o777).toBe(0o600);
+    });
+    it("loadGitHubAuth reads from token file when present", () => {
+        // Write a valid token file
+        fs.writeFileSync(tmpTokenPath, JSON.stringify(fakeAuth), "utf-8");
+        const loaded = loadGitHubAuth(tmpTokenPath);
+        expect(loaded).not.toBeNull();
+        expect(loaded.login).toBe("testuser");
+        expect(loaded.access_token).toBe("ghu_fake_app_token");
+    });
+    it("loadGitHubAuth returns null when token file does not exist", () => {
+        const loaded = loadGitHubAuth(tmpTokenPath);
+        expect(loaded).toBeNull();
+    });
+    it("loadGitHubAuth returns null for corrupted JSON", () => {
+        fs.writeFileSync(tmpTokenPath, "NOT VALID JSON{{{", "utf-8");
+        const loaded = loadGitHubAuth(tmpTokenPath);
+        expect(loaded).toBeNull();
+    });
+    it("loadGitHubAuth returns null when token file is missing access_token", () => {
+        fs.writeFileSync(tmpTokenPath, JSON.stringify({ login: "x", id: 1 }), "utf-8");
+        const loaded = loadGitHubAuth(tmpTokenPath);
+        expect(loaded).toBeNull();
+    });
+    it("clearGitHubAuth removes the token file", () => {
+        fs.writeFileSync(tmpTokenPath, JSON.stringify(fakeAuth), "utf-8");
+        expect(fs.existsSync(tmpTokenPath)).toBe(true);
+        clearGitHubAuth(tmpTokenPath);
+        expect(fs.existsSync(tmpTokenPath)).toBe(false);
+    });
+    it("clearGitHubAuth is a no-op when file does not exist", () => {
+        // Should not throw
+        clearGitHubAuth(tmpTokenPath);
+    });
+});
+// ─── isGitHubAuthValid ─────────────────────────────────────────────────────
+describe("isGitHubAuthValid", () => {
+    beforeEach(() => mockFetch.mockReset());
+    it("returns true when /user responds 200", async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true });
+        expect(await isGitHubAuthValid(fakeAuth)).toBe(true);
+    });
+    it("returns false when /user responds non-ok", async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 401 });
+        expect(await isGitHubAuthValid(fakeAuth)).toBe(false);
+    });
+    it("returns false on network error", async () => {
+        mockFetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+        expect(await isGitHubAuthValid(fakeAuth)).toBe(false);
+    });
+});
+// ─── isAppScopedToken ──────────────────────────────────────────────────────
+describe("isAppScopedToken", () => {
+    beforeEach(() => mockFetch.mockReset());
+    it('returns "yes" when /user/installations responds 200', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true, status: 200 });
+        expect(await isAppScopedToken(fakeAuth)).toBe("yes");
+    });
+    it('returns "no" on 403 (definitive — wrong token type)', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 403 });
+        expect(await isAppScopedToken(fakeAuth)).toBe("no");
+    });
+    it('returns "unknown" on 5xx (transient server error)', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+        expect(await isAppScopedToken(fakeAuth)).toBe("unknown");
+    });
+    it('returns "unknown" on network error', async () => {
+        mockFetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+        expect(await isAppScopedToken(fakeAuth)).toBe("unknown");
+    });
+    it('returns "no" when access_token is empty', async () => {
+        expect(await isAppScopedToken({ ...fakeAuth, access_token: "" })).toBe("no");
+        // fetch should not have been called
+        expect(mockFetch).not.toHaveBeenCalled();
+    });
+});
+// ─── Cleanup ───────────────────────────────────────────────────────────────
+afterAll(() => {
+    try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    catch { }
+});
+//# sourceMappingURL=auth.test.js.map

package/dist/__tests__/auth.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.test.js","sourceRoot":"","sources":["../../src/__tests__/auth.test.ts"],"names":[],"mappings":"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"}

package/dist/auth.d.ts

@@ -7,17 +7,21 @@
  *   1. POST github.com/login/device/code with our App's client_id
  *   2. Display user_code, open verification_uri in browser
  *   3. Poll github.com/login/oauth/access_token at the GitHub-specified interval
- *   4. On success: GET api.github.com/user → configure gh CLI with the token
+ *   4. On success: GET api.github.com/user → save token to ~/.hq/app-token.json
  *
- * After authentication, the token is handed to `gh auth login --with-token`
- * so that subsequent sessions can use `gh` for all GitHub operations.
- * No credentials are persisted to disk by create-hq itself.
+ * The HQ App token is stored in ~/.hq/app-token.json (mode 0600) and is
+ * completely independent of the user's `gh` CLI auth. This means:
+ *   - Running `gh auth login` / `gh auth logout` does not affect HQ auth
+ *   - HQ auth does not overwrite the user's existing `gh` token
+ *   - The App token is only used for HQ-specific API calls (installations, etc.)
  *
  * Token values are NEVER written to stdout or logs.
  */
 /** hq-team-sync GitHub App client ID (public — safe to commit). */
 export declare const HQ_GITHUB_APP_CLIENT_ID = "Iv23liSdkCBQYhrNcRmI";
 export declare const HQ_GITHUB_APP_SLUG = "hq-team-sync";
+/** Where the HQ App token is persisted. Exported for tests. */
+export declare const HQ_APP_TOKEN_PATH: string;
 /** Authenticated GitHub user info. The access_token is held in-memory only. */
 export interface GitHubAuth {
     /** ghu_ user-to-server token from GitHub App device flow (in-memory only). */
@@ -39,22 +43,51 @@ export interface GitHubAuth {
  */
 export type AuthToken = GitHubAuth;
 /**
- * Save the GitHub auth to gh CLI. The token is handed to `gh auth login`
- * so it's stored in the OS keychain, not on disk as a plain file.
+ * Save the HQ App auth to ~/.hq/app-token.json.
+ *
+ * The file is written with mode 0600 (owner read+write only). The user's
+ * existing `gh` CLI auth is never touched.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
  */
-export declare function saveGitHubAuth(auth: GitHubAuth): void;
+export declare function saveGitHubAuth(auth: GitHubAuth, tokenPath?: string): void;
 /**
- * Load GitHub auth from `gh` CLI. Returns null if gh is not installed
- * or not authenticated. Fetches user profile from GitHub API via gh.
+ * Load HQ App auth from ~/.hq/app-token.json.
+ *
+ * Returns null if the file doesn't exist, is corrupted, or is missing
+ * required fields. Does NOT fall back to `gh` CLI — the HQ App token
+ * is separate from the user's personal GitHub auth.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
  */
-export declare function loadGitHubAuth(): GitHubAuth | null;
-/** Remove stored credentials by logging out of gh. */
-export declare function clearGitHubAuth(): void;
+export declare function loadGitHubAuth(tokenPath?: string): GitHubAuth | null;
+/**
+ * Remove stored HQ App credentials.
+ *
+ * Deletes ~/.hq/app-token.json. Does NOT touch `gh` CLI auth.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
+ */
+export declare function clearGitHubAuth(tokenPath?: string): void;
 /**
  * Quick liveness probe — does the stored token still work?
- * Uses `gh auth status` which validates the token against GitHub.
+ * Validates the token by hitting GET /user on api.github.com.
  */
 export declare function isGitHubAuthValid(auth: GitHubAuth): Promise<boolean>;
+/** Result of the App scope probe. */
+export type AppScopeResult = "yes" | "no" | "unknown";
+/**
+ * Probe whether a token has GitHub App scopes by hitting /user/installations.
+ *
+ * Returns:
+ *   - `"yes"`     — 2xx, token has App scopes
+ *   - `"no"`      — 403, token is definitively the wrong type
+ *   - `"unknown"` — transient failure (network error, 5xx, timeout)
+ *
+ * Callers should only delete cached tokens on `"no"`, not on `"unknown"`.
+ * This is a lightweight check — we request per_page=1 to minimise payload.
+ */
+export declare function isAppScopedToken(auth: GitHubAuth): Promise<AppScopeResult>;
 /** Open a URL in the user's default browser. Best-effort, never throws. */
 export declare function openBrowser(url: string): void;
 /**
@@ -62,7 +95,9 @@ export declare function openBrowser(url: string): void;
  *
  * On success, the token is:
  *   1. Returned in-memory as part of GitHubAuth (for the current session)
- *   2. Configured in `gh` CLI for future sessions (via gh auth login --with-token)
+ *   2. Persisted to ~/.hq/app-token.json for future sessions
+ *
+ * The user's existing `gh` CLI auth is never modified.
  *
  * Throws on:
  *   - Network errors talking to github.com

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAC9D,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAUjD,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AA8EnC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,UAAU,GAAG,IAAI,CA+BlD;AAED,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,IAAI,CAUtC;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB1E;AAID,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAkB7C;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,UAAU,CAAC,CA0HjE;AAID;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,CAAC,CAAC,CAwBZ"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAC9D,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAQjD,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAsC,CAAC;AAIrE,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AA4BnC;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,SAAoB,GAAG,IAAI,CASpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,SAAoB,GAAG,UAAU,GAAG,IAAI,CAW/E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,SAAoB,GAAG,IAAI,CAQnE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAe1E;AAED,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAuBhF;AAID,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAkB7C;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,UAAU,CAAC,CA0HjE;AAID;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,CAAC,CAAC,CAuCZ"}

package/dist/auth.js

@@ -7,17 +7,20 @@
  *   1. POST github.com/login/device/code with our App's client_id
  *   2. Display user_code, open verification_uri in browser
  *   3. Poll github.com/login/oauth/access_token at the GitHub-specified interval
- *   4. On success: GET api.github.com/user → configure gh CLI with the token
+ *   4. On success: GET api.github.com/user → save token to ~/.hq/app-token.json
  *
- * After authentication, the token is handed to `gh auth login --with-token`
- * so that subsequent sessions can use `gh` for all GitHub operations.
- * No credentials are persisted to disk by create-hq itself.
+ * The HQ App token is stored in ~/.hq/app-token.json (mode 0600) and is
+ * completely independent of the user's `gh` CLI auth. This means:
+ *   - Running `gh auth login` / `gh auth logout` does not affect HQ auth
+ *   - HQ auth does not overwrite the user's existing `gh` token
+ *   - The App token is only used for HQ-specific API calls (installations, etc.)
  *
  * Token values are NEVER written to stdout or logs.
  */
+import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { exec, execSync } from "child_process";
+import { exec } from "child_process";
 import chalk from "chalk";
 // ─── Constants ──────────────────────────────────────────────────────────────
 /** hq-team-sync GitHub App client ID (public — safe to commit). */
@@ -27,129 +30,126 @@ const GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code";
 const GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token";
 const GITHUB_API_USER_URL = "https://api.github.com/user";
 const HQ_DIR = path.join(os.homedir(), ".hq");
-// ─── gh CLI helpers ────────────────────────────────────────────────────────
-/** Check if `gh` CLI is installed. */
-function isGhInstalled() {
-    try {
-        execSync("gh --version", { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
+/** Where the HQ App token is persisted. Exported for tests. */
+export const HQ_APP_TOKEN_PATH = path.join(HQ_DIR, "app-token.json");
+// ─── Token persistence (~/.hq/app-token.json) ────────────────────────────
+/**
+ * Save the HQ App auth to ~/.hq/app-token.json.
+ *
+ * The file is written with mode 0600 (owner read+write only). The user's
+ * existing `gh` CLI auth is never touched.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
+ */
+export function saveGitHubAuth(auth, tokenPath = HQ_APP_TOKEN_PATH) {
+    const dir = path.dirname(tokenPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
     }
+    fs.writeFileSync(tokenPath, JSON.stringify(auth, null, 2), {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
 }
-/** Check if `gh` is authenticated with any GitHub host. */
-function isGhAuthenticated() {
+/**
+ * Load HQ App auth from ~/.hq/app-token.json.
+ *
+ * Returns null if the file doesn't exist, is corrupted, or is missing
+ * required fields. Does NOT fall back to `gh` CLI — the HQ App token
+ * is separate from the user's personal GitHub auth.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
+ */
+export function loadGitHubAuth(tokenPath = HQ_APP_TOKEN_PATH) {
     try {
-        execSync("gh auth status", { stdio: "ignore" });
-        return true;
+        if (!fs.existsSync(tokenPath))
+            return null;
+        const raw = fs.readFileSync(tokenPath, "utf-8");
+        const data = JSON.parse(raw);
+        // Minimal validation — must have at least a token and login
+        if (!data.access_token || !data.login)
+            return null;
+        return data;
     }
     catch {
-        return false;
+        return null;
     }
 }
 /**
- * Configure `gh` CLI with a token and set up git credential helper.
- * This makes the token available for all future `gh` and `git` operations.
+ * Remove stored HQ App credentials.
+ *
+ * Deletes ~/.hq/app-token.json. Does NOT touch `gh` CLI auth.
+ *
+ * @param tokenPath — override for testing; defaults to HQ_APP_TOKEN_PATH
  */
-function configureGhAuth(token) {
-    if (!isGhInstalled()) {
-        console.error(chalk.dim("  (gh CLI not found — install it from https://cli.github.com for team commands)"));
-        return;
-    }
+export function clearGitHubAuth(tokenPath = HQ_APP_TOKEN_PATH) {
     try {
-        // Pipe token to gh auth login (stdin, non-interactive)
-        execSync("gh auth login --with-token", {
-            input: token,
-            stdio: ["pipe", "ignore", "ignore"],
-        });
-        // Configure git to use gh for HTTPS auth
-        execSync("gh auth setup-git", { stdio: "ignore" });
+        if (fs.existsSync(tokenPath)) {
+            fs.unlinkSync(tokenPath);
+        }
     }
-    catch (err) {
-        console.error(chalk.dim("  (could not configure gh CLI — you can run `gh auth login` manually)"));
+    catch {
+        // ignore — may already be gone
     }
 }
 /**
- * Save the GitHub auth to gh CLI. The token is handed to `gh auth login`
- * so it's stored in the OS keychain, not on disk as a plain file.
- */
-export function saveGitHubAuth(auth) {
-    configureGhAuth(auth.access_token);
-}
-/**
- * Load GitHub auth from `gh` CLI. Returns null if gh is not installed
- * or not authenticated. Fetches user profile from GitHub API via gh.
+ * Quick liveness probe — does the stored token still work?
+ * Validates the token by hitting GET /user on api.github.com.
  */
-export function loadGitHubAuth() {
-    if (!isGhInstalled() || !isGhAuthenticated())
-        return null;
+export async function isGitHubAuthValid(auth) {
+    if (!auth.access_token)
+        return false;
     try {
-        // Get the token from gh
-        const token = execSync("gh auth token", {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "ignore"],
-        }).trim();
-        if (!token)
-            return null;
-        // Get user profile via gh api
-        const userJson = execSync('gh api user --jq \'{"login":.login,"id":.id,"name":.name,"email":.email}\'', {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "ignore"],
-        }).trim();
-        const user = JSON.parse(userJson);
-        return {
-            access_token: token,
-            login: user.login,
-            id: user.id,
-            name: user.name,
-            email: user.email,
-            issued_at: new Date().toISOString(),
-        };
+        const res = await fetch(GITHUB_API_USER_URL, {
+            headers: {
+                Authorization: `token ${auth.access_token}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "create-hq",
+            },
+            signal: AbortSignal.timeout(10_000),
+        });
+        return res.ok;
     }
     catch {
-        return null;
+        return false;
     }
 }
-/** Remove stored credentials by logging out of gh. */
-export function clearGitHubAuth() {
-    if (!isGhInstalled())
-        return;
+/**
+ * Probe whether a token has GitHub App scopes by hitting /user/installations.
+ *
+ * Returns:
+ *   - `"yes"`     — 2xx, token has App scopes
+ *   - `"no"`      — 403, token is definitively the wrong type
+ *   - `"unknown"` — transient failure (network error, 5xx, timeout)
+ *
+ * Callers should only delete cached tokens on `"no"`, not on `"unknown"`.
+ * This is a lightweight check — we request per_page=1 to minimise payload.
+ */
+export async function isAppScopedToken(auth) {
+    if (!auth.access_token)
+        return "no";
     try {
-        execSync("gh auth logout --hostname github.com", {
-            input: "Y\n",
-            stdio: ["pipe", "ignore", "ignore"],
+        const res = await fetch("https://api.github.com/user/installations?per_page=1", {
+            headers: {
+                Authorization: `token ${auth.access_token}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "create-hq",
+            },
+            signal: AbortSignal.timeout(10_000),
         });
+        if (res.ok)
+            return "yes";
+        // 401/403 = definitive "wrong token type"
+        if (res.status === 401 || res.status === 403)
+            return "no";
+        // Anything else (429, 5xx) = transient
+        return "unknown";
     }
     catch {
-        // ignore — may already be logged out
+        // Network error, timeout, DNS failure = transient
+        return "unknown";
     }
 }
-/**
- * Quick liveness probe — does the stored token still work?
- * Uses `gh auth status` which validates the token against GitHub.
- */
-export async function isGitHubAuthValid(auth) {
-    // If we have a token in memory, verify it directly
-    if (auth.access_token) {
-        try {
-            const res = await fetch(GITHUB_API_USER_URL, {
-                headers: {
-                    Authorization: `token ${auth.access_token}`,
-                    Accept: "application/vnd.github+json",
-                    "User-Agent": "create-hq",
-                },
-                signal: AbortSignal.timeout(10_000),
-            });
-            return res.ok;
-        }
-        catch {
-            return false;
-        }
-    }
-    // Fall back to gh auth status
-    return isGhAuthenticated();
-}
 // ─── Browser open (cross-platform) ──────────────────────────────────────────
 /** Open a URL in the user's default browser. Best-effort, never throws. */
 export function openBrowser(url) {
@@ -180,7 +180,9 @@ function sleep(ms) {
  *
  * On success, the token is:
  *   1. Returned in-memory as part of GitHubAuth (for the current session)
- *   2. Configured in `gh` CLI for future sessions (via gh auth login --with-token)
+ *   2. Persisted to ~/.hq/app-token.json for future sessions
+ *
+ * The user's existing `gh` CLI auth is never modified.
  *
  * Throws on:
  *   - Network errors talking to github.com
@@ -287,7 +289,7 @@ export async function startGitHubDeviceFlow() {
             email: user.email,
             issued_at: new Date().toISOString(),
         };
-        // Configure gh CLI with the token for future sessions
+        // Persist for future sessions (does not touch gh CLI)
         saveGitHubAuth(auth);
         return auth;
     }
@@ -314,6 +316,15 @@ export async function githubApi(pathname, auth, init = {}) {
     });
     if (!res.ok) {
         const body = await res.text().catch(() => "");
+        // Friendly error when a non-App token hits the App-only installations endpoint.
+        if (res.status === 403 &&
+            pathname.startsWith("/user/installations") &&
+            body.includes("authorized to a GitHub App")) {
+            throw new Error("You're signed in with a regular GitHub token that can't list App installations.\n" +
+                "  HQ Teams requires authentication through the HQ GitHub App.\n\n" +
+                "  To fix this, re-run the installer — it will prompt you to authorize the HQ App:\n" +
+                "    npx create-hq");
+        }
         throw new Error(`GitHub API ${res.status} ${pathname}: ${body}`);
     }
     // Some endpoints return 204