gigabuddy 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gigabuddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/cli.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
 // libs/gigabuddy/src/bin/cli.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 import { dirname, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 
+// libs/gigabuddy/src/lib/commands.ts
+import { execFileSync } from "node:child_process";
+import { readFileSync as readFileSync3 } from "node:fs";
+
 // libs/client-core/dist/lib/credentials.js
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -57,6 +61,17 @@ async function openBrowser(url) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function emailFromPlatformToken(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload)
+      return void 0;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    return typeof claims.email === "string" ? claims.email : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function deviceLogin(options) {
   const { authUrl } = options;
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -94,7 +109,8 @@ async function deviceLogin(options) {
       return {
         refreshToken: pollData.refreshToken,
         platformToken: pollData.platformToken,
-        userId: pollData.userId
+        userId: pollData.userId,
+        userEmail: emailFromPlatformToken(pollData.platformToken)
       };
     }
     if (pollData.status === "expired") {
@@ -125,14 +141,18 @@ function upsertNpmrc(existing, entries) {
   ]);
   const lines = existing.length > 0 ? existing.split("\n") : [];
   const written = /* @__PURE__ */ new Set();
-  const merged = lines.map((line) => {
+  const merged = [];
+  for (const line of lines) {
     const key = lineKey(line);
-    if (key && desired.has(key) && !written.has(key)) {
+    if (key && desired.has(key)) {
+      if (written.has(key))
+        continue;
       written.add(key);
-      return desired.get(key);
+      merged.push(desired.get(key));
+      continue;
     }
-    return line;
-  });
+    merged.push(line);
+  }
   const additions = [...desired.entries()].filter(([key]) => !written.has(key)).map(([, line]) => line);
   if (additions.length === 0)
     return merged.join("\n");
@@ -181,6 +201,19 @@ async function mintRegistryCredential(options) {
   }
   return { token: data.token, expiresIn: data.expiresIn ?? 0, registryUrl: data.registryUrl };
 }
+async function revokeSessionByRefreshToken(options) {
+  try {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${options.authUrl}/api/auth/signout`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: options.refreshToken })
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
 function npmrcPath() {
   return process.env["NPM_CONFIG_USERCONFIG"] ?? path2.join(os2.homedir(), ".npmrc");
 }
@@ -209,6 +242,216 @@ function removeRegistryCredentialFromNpmrc(registryUrl, file = npmrcPath()) {
   return file;
 }
 
+// libs/client-core/dist/lib/token-manager.js
+var TokenManager = class {
+  refreshToken;
+  authUrl;
+  platformToken = null;
+  tokenExpiresAt = 0;
+  refreshPromise = null;
+  onRefreshTokenRotated;
+  fetchImpl;
+  constructor(options) {
+    this.refreshToken = options.refreshToken;
+    this.authUrl = options.authUrl;
+    this.onRefreshTokenRotated = options.onRefreshTokenRotated;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async getToken() {
+    if (this.platformToken && Date.now() < this.tokenExpiresAt - 6e4) {
+      return this.platformToken;
+    }
+    return this.refresh();
+  }
+  invalidate() {
+    this.platformToken = null;
+    this.tokenExpiresAt = 0;
+  }
+  async refresh() {
+    if (this.refreshPromise)
+      return this.refreshPromise;
+    this.refreshPromise = this.doRefresh().finally(() => {
+      this.refreshPromise = null;
+    });
+    return this.refreshPromise;
+  }
+  async doRefresh() {
+    const res = await this.fetchImpl(`${this.authUrl}/api/token/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: this.refreshToken })
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Token refresh failed (${res.status}): ${text}. Sign in again with 'gigabuddy login'.`);
+    }
+    const data = await res.json();
+    this.platformToken = data.token;
+    this.tokenExpiresAt = Date.now() + data.expiresIn * 1e3;
+    if (data.refreshToken && data.refreshToken !== this.refreshToken) {
+      this.refreshToken = data.refreshToken;
+      this.onRefreshTokenRotated?.(data.refreshToken);
+    }
+    return data.token;
+  }
+};
+
+// libs/gigabuddy/src/lib/doctor.ts
+var SCOPE = "@gigabuddy";
+var MIN_NODE_MAJOR = 20;
+function expiryOf(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload)
+      return null;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    return typeof claims.exp === "number" ? new Date(claims.exp * 1e3) : null;
+  } catch {
+    return null;
+  }
+}
+function npmrcValue(contents, key) {
+  let found = null;
+  for (const line of contents.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";"))
+      continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1)
+      continue;
+    if (trimmed.slice(0, eq).trim().toLowerCase() === key.toLowerCase()) {
+      found = trimmed.slice(eq + 1).trim();
+    }
+  }
+  return found;
+}
+async function runDoctor(deps, packageName) {
+  const checks = [];
+  const advice = [];
+  const add = (label, status, detail) => checks.push({ label, status, detail });
+  const major = Number(deps.nodeVersion.replace(/^v/, "").split(".")[0]);
+  if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
+    add("Node version", "fail", `${deps.nodeVersion} \u2014 gigabuddy needs Node ${MIN_NODE_MAJOR} or newer`);
+    advice.push(`Upgrade Node to ${MIN_NODE_MAJOR}+ \u2014 nothing below that is supported.`);
+  } else {
+    add("Node version", "ok", deps.nodeVersion);
+  }
+  const credentials = deps.loadCredentials(false) ?? deps.loadCredentials(true);
+  if (!credentials) {
+    add("Signed in", "fail", "no credentials found");
+    advice.push("Run `gigabuddy login --npm` \u2014 you are not signed in, so the registry cannot know who you are.");
+    return { checks, advice };
+  }
+  const signedIn = { label: "Signed in", status: "ok", detail: credentials.userEmail ?? credentials.userId };
+  checks.push(signedIn);
+  let platformToken = null;
+  try {
+    platformToken = await new TokenManager({
+      refreshToken: credentials.refreshToken,
+      authUrl: credentials.authUrl,
+      fetchImpl: deps.fetchImpl
+    }).getToken();
+    const email = emailFromPlatformToken(platformToken);
+    if (email)
+      signedIn.detail = email;
+    add("Session", "ok", "live");
+  } catch (err) {
+    add("Session", "fail", `not accepted by auth \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    advice.push("Run `gigabuddy login` \u2014 your session was revoked or expired, so every credential from it is dead.");
+  }
+  const npmrc = deps.readNpmrc();
+  const scopeRegistry = npmrcValue(npmrc, `${SCOPE}:registry`);
+  if (!scopeRegistry) {
+    add(`${SCOPE} registry`, "fail", `not set in ${npmrcPath()}`);
+    advice.push("Run `gigabuddy login --npm` \u2014 npm has no registry configured for @gigabuddy packages.");
+  } else {
+    add(`${SCOPE} registry`, "ok", scopeRegistry);
+  }
+  const authKey = scopeRegistry ? registryAuthKey(scopeRegistry) : null;
+  const authToken = authKey ? npmrcValue(npmrc, authKey) : null;
+  if (scopeRegistry && !authToken) {
+    add("Registry credential", "fail", `no ${authKey} in ${npmrcPath()}`);
+    advice.push("Run `gigabuddy login --npm` \u2014 the registry is configured but has no credential to authenticate with.");
+  } else if (authToken) {
+    const expiry = expiryOf(authToken);
+    if (expiry && expiry.getTime() < Date.now()) {
+      add("Registry credential", "fail", `expired ${expiry.toISOString().slice(0, 10)}`);
+      advice.push("Run `gigabuddy login --npm` \u2014 your npm credential expired. They are long-lived, not permanent.");
+    } else {
+      add("Registry credential", "ok", expiry ? `valid until ${expiry.toISOString().slice(0, 10)}` : "present");
+    }
+  }
+  const effective = deps.npmEffectiveRegistry();
+  if (effective && scopeRegistry && effective.replace(/\/+$/, "") !== scopeRegistry.replace(/\/+$/, "")) {
+    add("npm resolves @gigabuddy to", "fail", `${effective} \u2014 NOT what we configured`);
+    advice.push(
+      `Something is overriding your user-level .npmrc \u2014 most often a project .npmrc, or an npm_config_ env var. npm is sending @gigabuddy installs to ${effective}.`
+    );
+  } else if (effective) {
+    add("npm resolves @gigabuddy to", "ok", effective);
+  }
+  if (scopeRegistry && authToken) {
+    const base = scopeRegistry.replace(/\/+$/, "");
+    try {
+      const res = await deps.fetchImpl(`${base}/-/ping`, { headers: { authorization: `Bearer ${authToken}` } });
+      if (res.ok) {
+        add("Registry reachable", "ok", base);
+      } else if (res.status === 401) {
+        add("Registry reachable", "fail", "reachable, but rejected the credential (401)");
+        advice.push("Run `gigabuddy login --npm` \u2014 the registry did not accept your credential.");
+      } else {
+        add("Registry reachable", "warn", `responded ${res.status}`);
+      }
+    } catch (err) {
+      add("Registry reachable", "fail", `cannot reach ${base} \u2014 ${err instanceof Error ? err.message : String(err)}`);
+      advice.push("Check your network or proxy \u2014 the registry is unreachable from here.");
+    }
+    if (packageName) {
+      try {
+        const res = await deps.fetchImpl(`${base}/${packageName.replace("/", "%2F")}`, {
+          headers: { authorization: `Bearer ${authToken}` }
+        });
+        if (res.ok) {
+          add(`Access to ${packageName}`, "ok", "you can install it");
+        } else if (res.status === 404) {
+          add(`Access to ${packageName}`, "fail", "the registry will not serve it to you");
+          advice.push(
+            `The registry answers "no such package" for ${packageName}. That single answer covers BOTH "this name does not exist" and "you do not have access" \u2014 deliberately, so private names stay private. Everything else above is healthy, so: check the spelling first, and if it is right, ask whoever owns the package to grant you access.`
+          );
+        } else if (res.status === 401) {
+          add(`Access to ${packageName}`, "fail", "credential rejected (401)");
+        } else {
+          add(`Access to ${packageName}`, "warn", `registry responded ${res.status}`);
+        }
+      } catch (err) {
+        add(`Access to ${packageName}`, "fail", err instanceof Error ? err.message : String(err));
+      }
+    }
+  }
+  return { checks, advice };
+}
+var MARK = { ok: "\u2713", warn: "!", fail: "\u2717", skip: "-" };
+function formatDoctor(result, colour) {
+  const paint = (code, text) => colour ? `\x1B[${code}m${text}\x1B[0m` : text;
+  const colourFor = { ok: "32", warn: "33", fail: "31", skip: "90" };
+  const width = Math.max(...result.checks.map((c) => c.label.length));
+  const lines = result.checks.map(
+    (c) => `  ${paint(colourFor[c.status], MARK[c.status])} ${c.label.padEnd(width)}  ${c.detail ?? ""}`.trimEnd()
+  );
+  if (result.advice.length === 0) {
+    lines.push("", `  ${paint("32", "Everything checks out.")}`);
+    return lines.join("\n");
+  }
+  lines.push("", paint("1", "  What to do:"));
+  for (const item of result.advice) {
+    const wrapped = item.replace(/(.{1,74})(\s|$)/g, "$1\n").trimEnd().split("\n");
+    lines.push(`  \u2022 ${wrapped[0]}`);
+    for (const rest of wrapped.slice(1))
+      lines.push(`    ${rest}`);
+  }
+  return lines.join("\n");
+}
+
 // libs/gigabuddy/src/lib/commands.ts
 var PRODUCTION_AUTH_URL = "https://auth.gigabuddy.com";
 var PRODUCTION_API_URL = "https://api.gigabuddy.com";
@@ -305,16 +548,77 @@ function npmLogoutCommand(env) {
   }
   say(`Removed ${GIGABUDDY_NPM_SCOPE} registry credentials from ${file}`);
 }
-function logoutCommand(env) {
+async function logoutCommand(env) {
+  const credentials = loadUserCredentials(env.staging);
   npmLogoutCommand(env);
-  if (!loadUserCredentials(env.staging)) {
+  if (!credentials) {
     say("Not signed in.");
     return;
   }
+  const revoked = await revokeSessionByRefreshToken({
+    authUrl: credentials.authUrl,
+    refreshToken: credentials.refreshToken
+  });
   clearUserCredentials(env.staging);
-  say(`Signed out${env.staging ? " of staging" : ""}.`);
+  if (revoked) {
+    say(`Signed out${env.staging ? " of staging" : ""}. Any npm credential from this session stops working shortly.`);
+  } else {
+    say(
+      `Signed out locally${env.staging ? " of staging" : ""} \u2014 but could not reach the server to revoke the session.`
+    );
+    say("  Credentials already copied elsewhere may keep working. Sign out again when you are back online,");
+    say("  or revoke the session from your account settings.");
+  }
+}
+async function resolveAccountLabel(creds, staging) {
+  if (creds.userEmail)
+    return creds.userEmail;
+  try {
+    const token = await new TokenManager({ refreshToken: creds.refreshToken, authUrl: creds.authUrl }).getToken();
+    const email = emailFromPlatformToken(token);
+    if (!email)
+      return creds.userId;
+    saveUserCredentials({ ...creds, userEmail: email }, staging);
+    return email;
+  } catch {
+    return creds.userId;
+  }
 }
-function statusCommand() {
+async function doctorCommand(env, packageName) {
+  const result = await runDoctor(
+    {
+      readNpmrc: () => {
+        try {
+          return readFileSync3(npmrcPath(), "utf-8");
+        } catch {
+          return "";
+        }
+      },
+      npmEffectiveRegistry: () => {
+        try {
+          const value = execFileSync("npm", ["config", "get", `${GIGABUDDY_NPM_SCOPE}:registry`], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"]
+          }).trim();
+          return value && value !== "undefined" && value !== "null" ? value : null;
+        } catch {
+          return null;
+        }
+      },
+      fetchImpl: fetch,
+      nodeVersion: process.version,
+      loadCredentials: (staging) => loadUserCredentials(staging)
+    },
+    packageName
+  );
+  const colour = process.stderr.isTTY === true && !process.env["NO_COLOR"];
+  say();
+  say(formatDoctor(result, colour));
+  say();
+  if (result.advice.length > 0)
+    process.exitCode = 1;
+}
+async function statusCommand() {
   const production = loadUserCredentials(false);
   const staging = loadUserCredentials(true);
   if (!production && !staging) {
@@ -323,14 +627,14 @@ function statusCommand() {
     say("  gigabuddy login");
     return;
   }
-  for (const [label, creds] of [
-    ["Production", production],
-    ["Staging", staging]
+  for (const [label, creds, isStaging] of [
+    ["Production", production, false],
+    ["Staging", staging, true]
   ]) {
     if (!creds)
       continue;
     say(`${label}:`);
-    say(`  Account: ${creds.userEmail ?? creds.userId}`);
+    say(`  Account: ${await resolveAccountLabel(creds, isStaging)}`);
     say(`  Since: ${creds.createdAt}`);
   }
 }
@@ -339,7 +643,7 @@ function statusCommand() {
 function version() {
   try {
     const pkgPath = join3(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-    return JSON.parse(readFileSync3(pkgPath, "utf-8")).version;
+    return JSON.parse(readFileSync4(pkgPath, "utf-8")).version;
   } catch {
     return "unknown";
   }
@@ -356,6 +660,7 @@ Commands:
   login --npm        Set up npm to install @gigabuddy packages as you
   logout             Sign out (--npm clears only the npm credential)
   status             Show who you are signed in as
+  doctor [pkg]       Diagnose why installs are not working
 
 Options:
   --npm              Act on npm registry access in ~/.npmrc
@@ -371,6 +676,12 @@ Installing packages:
 
   The npm credential is registry-scoped: it installs what you can install,
   and cannot do anything else on the platform.
+
+If an install fails:
+  gigabuddy doctor @gigabuddy/some-package
+
+  npm answers a denied read with "not found", which looks the same as a typo.
+  doctor tells you which it is.
 `);
 }
 async function main() {
@@ -411,10 +722,13 @@ async function main() {
       if (values.npm)
         npmLogoutCommand(env);
       else
-        logoutCommand(env);
+        await logoutCommand(env);
       return;
     case "status":
-      statusCommand();
+      await statusCommand();
+      return;
+    case "doctor":
+      await doctorCommand(env, positionals[1]);
       return;
     default:
       console.error(`Unknown command: ${command}`);

package/index.js

@@ -1,3 +1,7 @@
+// libs/gigabuddy/src/lib/commands.ts
+import { execFileSync } from "node:child_process";
+import { readFileSync as readFileSync3 } from "node:fs";
+
 // libs/client-core/dist/lib/credentials.js
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -49,6 +53,17 @@ async function openBrowser(url) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function emailFromPlatformToken(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload)
+      return void 0;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    return typeof claims.email === "string" ? claims.email : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function deviceLogin(options) {
   const { authUrl } = options;
   const fetchImpl = options.fetchImpl ?? fetch;
@@ -86,7 +101,8 @@ async function deviceLogin(options) {
       return {
         refreshToken: pollData.refreshToken,
         platformToken: pollData.platformToken,
-        userId: pollData.userId
+        userId: pollData.userId,
+        userEmail: emailFromPlatformToken(pollData.platformToken)
       };
     }
     if (pollData.status === "expired") {
@@ -117,14 +133,18 @@ function upsertNpmrc(existing, entries) {
   ]);
   const lines = existing.length > 0 ? existing.split("\n") : [];
   const written = /* @__PURE__ */ new Set();
-  const merged = lines.map((line) => {
+  const merged = [];
+  for (const line of lines) {
     const key = lineKey(line);
-    if (key && desired.has(key) && !written.has(key)) {
+    if (key && desired.has(key)) {
+      if (written.has(key))
+        continue;
       written.add(key);
-      return desired.get(key);
+      merged.push(desired.get(key));
+      continue;
     }
-    return line;
-  });
+    merged.push(line);
+  }
   const additions = [...desired.entries()].filter(([key]) => !written.has(key)).map(([, line]) => line);
   if (additions.length === 0)
     return merged.join("\n");
@@ -173,6 +193,19 @@ async function mintRegistryCredential(options) {
   }
   return { token: data.token, expiresIn: data.expiresIn ?? 0, registryUrl: data.registryUrl };
 }
+async function revokeSessionByRefreshToken(options) {
+  try {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${options.authUrl}/api/auth/signout`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: options.refreshToken })
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
 function npmrcPath() {
   return process.env["NPM_CONFIG_USERCONFIG"] ?? path2.join(os2.homedir(), ".npmrc");
 }
@@ -201,6 +234,216 @@ function removeRegistryCredentialFromNpmrc(registryUrl, file = npmrcPath()) {
   return file;
 }
 
+// libs/client-core/dist/lib/token-manager.js
+var TokenManager = class {
+  refreshToken;
+  authUrl;
+  platformToken = null;
+  tokenExpiresAt = 0;
+  refreshPromise = null;
+  onRefreshTokenRotated;
+  fetchImpl;
+  constructor(options) {
+    this.refreshToken = options.refreshToken;
+    this.authUrl = options.authUrl;
+    this.onRefreshTokenRotated = options.onRefreshTokenRotated;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async getToken() {
+    if (this.platformToken && Date.now() < this.tokenExpiresAt - 6e4) {
+      return this.platformToken;
+    }
+    return this.refresh();
+  }
+  invalidate() {
+    this.platformToken = null;
+    this.tokenExpiresAt = 0;
+  }
+  async refresh() {
+    if (this.refreshPromise)
+      return this.refreshPromise;
+    this.refreshPromise = this.doRefresh().finally(() => {
+      this.refreshPromise = null;
+    });
+    return this.refreshPromise;
+  }
+  async doRefresh() {
+    const res = await this.fetchImpl(`${this.authUrl}/api/token/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: this.refreshToken })
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Token refresh failed (${res.status}): ${text}. Sign in again with 'gigabuddy login'.`);
+    }
+    const data = await res.json();
+    this.platformToken = data.token;
+    this.tokenExpiresAt = Date.now() + data.expiresIn * 1e3;
+    if (data.refreshToken && data.refreshToken !== this.refreshToken) {
+      this.refreshToken = data.refreshToken;
+      this.onRefreshTokenRotated?.(data.refreshToken);
+    }
+    return data.token;
+  }
+};
+
+// libs/gigabuddy/src/lib/doctor.ts
+var SCOPE = "@gigabuddy";
+var MIN_NODE_MAJOR = 20;
+function expiryOf(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload)
+      return null;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    return typeof claims.exp === "number" ? new Date(claims.exp * 1e3) : null;
+  } catch {
+    return null;
+  }
+}
+function npmrcValue(contents, key) {
+  let found = null;
+  for (const line of contents.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";"))
+      continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1)
+      continue;
+    if (trimmed.slice(0, eq).trim().toLowerCase() === key.toLowerCase()) {
+      found = trimmed.slice(eq + 1).trim();
+    }
+  }
+  return found;
+}
+async function runDoctor(deps, packageName) {
+  const checks = [];
+  const advice = [];
+  const add = (label, status, detail) => checks.push({ label, status, detail });
+  const major = Number(deps.nodeVersion.replace(/^v/, "").split(".")[0]);
+  if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
+    add("Node version", "fail", `${deps.nodeVersion} \u2014 gigabuddy needs Node ${MIN_NODE_MAJOR} or newer`);
+    advice.push(`Upgrade Node to ${MIN_NODE_MAJOR}+ \u2014 nothing below that is supported.`);
+  } else {
+    add("Node version", "ok", deps.nodeVersion);
+  }
+  const credentials = deps.loadCredentials(false) ?? deps.loadCredentials(true);
+  if (!credentials) {
+    add("Signed in", "fail", "no credentials found");
+    advice.push("Run `gigabuddy login --npm` \u2014 you are not signed in, so the registry cannot know who you are.");
+    return { checks, advice };
+  }
+  const signedIn = { label: "Signed in", status: "ok", detail: credentials.userEmail ?? credentials.userId };
+  checks.push(signedIn);
+  let platformToken = null;
+  try {
+    platformToken = await new TokenManager({
+      refreshToken: credentials.refreshToken,
+      authUrl: credentials.authUrl,
+      fetchImpl: deps.fetchImpl
+    }).getToken();
+    const email = emailFromPlatformToken(platformToken);
+    if (email)
+      signedIn.detail = email;
+    add("Session", "ok", "live");
+  } catch (err) {
+    add("Session", "fail", `not accepted by auth \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    advice.push("Run `gigabuddy login` \u2014 your session was revoked or expired, so every credential from it is dead.");
+  }
+  const npmrc = deps.readNpmrc();
+  const scopeRegistry = npmrcValue(npmrc, `${SCOPE}:registry`);
+  if (!scopeRegistry) {
+    add(`${SCOPE} registry`, "fail", `not set in ${npmrcPath()}`);
+    advice.push("Run `gigabuddy login --npm` \u2014 npm has no registry configured for @gigabuddy packages.");
+  } else {
+    add(`${SCOPE} registry`, "ok", scopeRegistry);
+  }
+  const authKey = scopeRegistry ? registryAuthKey(scopeRegistry) : null;
+  const authToken = authKey ? npmrcValue(npmrc, authKey) : null;
+  if (scopeRegistry && !authToken) {
+    add("Registry credential", "fail", `no ${authKey} in ${npmrcPath()}`);
+    advice.push("Run `gigabuddy login --npm` \u2014 the registry is configured but has no credential to authenticate with.");
+  } else if (authToken) {
+    const expiry = expiryOf(authToken);
+    if (expiry && expiry.getTime() < Date.now()) {
+      add("Registry credential", "fail", `expired ${expiry.toISOString().slice(0, 10)}`);
+      advice.push("Run `gigabuddy login --npm` \u2014 your npm credential expired. They are long-lived, not permanent.");
+    } else {
+      add("Registry credential", "ok", expiry ? `valid until ${expiry.toISOString().slice(0, 10)}` : "present");
+    }
+  }
+  const effective = deps.npmEffectiveRegistry();
+  if (effective && scopeRegistry && effective.replace(/\/+$/, "") !== scopeRegistry.replace(/\/+$/, "")) {
+    add("npm resolves @gigabuddy to", "fail", `${effective} \u2014 NOT what we configured`);
+    advice.push(
+      `Something is overriding your user-level .npmrc \u2014 most often a project .npmrc, or an npm_config_ env var. npm is sending @gigabuddy installs to ${effective}.`
+    );
+  } else if (effective) {
+    add("npm resolves @gigabuddy to", "ok", effective);
+  }
+  if (scopeRegistry && authToken) {
+    const base = scopeRegistry.replace(/\/+$/, "");
+    try {
+      const res = await deps.fetchImpl(`${base}/-/ping`, { headers: { authorization: `Bearer ${authToken}` } });
+      if (res.ok) {
+        add("Registry reachable", "ok", base);
+      } else if (res.status === 401) {
+        add("Registry reachable", "fail", "reachable, but rejected the credential (401)");
+        advice.push("Run `gigabuddy login --npm` \u2014 the registry did not accept your credential.");
+      } else {
+        add("Registry reachable", "warn", `responded ${res.status}`);
+      }
+    } catch (err) {
+      add("Registry reachable", "fail", `cannot reach ${base} \u2014 ${err instanceof Error ? err.message : String(err)}`);
+      advice.push("Check your network or proxy \u2014 the registry is unreachable from here.");
+    }
+    if (packageName) {
+      try {
+        const res = await deps.fetchImpl(`${base}/${packageName.replace("/", "%2F")}`, {
+          headers: { authorization: `Bearer ${authToken}` }
+        });
+        if (res.ok) {
+          add(`Access to ${packageName}`, "ok", "you can install it");
+        } else if (res.status === 404) {
+          add(`Access to ${packageName}`, "fail", "the registry will not serve it to you");
+          advice.push(
+            `The registry answers "no such package" for ${packageName}. That single answer covers BOTH "this name does not exist" and "you do not have access" \u2014 deliberately, so private names stay private. Everything else above is healthy, so: check the spelling first, and if it is right, ask whoever owns the package to grant you access.`
+          );
+        } else if (res.status === 401) {
+          add(`Access to ${packageName}`, "fail", "credential rejected (401)");
+        } else {
+          add(`Access to ${packageName}`, "warn", `registry responded ${res.status}`);
+        }
+      } catch (err) {
+        add(`Access to ${packageName}`, "fail", err instanceof Error ? err.message : String(err));
+      }
+    }
+  }
+  return { checks, advice };
+}
+var MARK = { ok: "\u2713", warn: "!", fail: "\u2717", skip: "-" };
+function formatDoctor(result, colour) {
+  const paint = (code, text) => colour ? `\x1B[${code}m${text}\x1B[0m` : text;
+  const colourFor = { ok: "32", warn: "33", fail: "31", skip: "90" };
+  const width = Math.max(...result.checks.map((c) => c.label.length));
+  const lines = result.checks.map(
+    (c) => `  ${paint(colourFor[c.status], MARK[c.status])} ${c.label.padEnd(width)}  ${c.detail ?? ""}`.trimEnd()
+  );
+  if (result.advice.length === 0) {
+    lines.push("", `  ${paint("32", "Everything checks out.")}`);
+    return lines.join("\n");
+  }
+  lines.push("", paint("1", "  What to do:"));
+  for (const item of result.advice) {
+    const wrapped = item.replace(/(.{1,74})(\s|$)/g, "$1\n").trimEnd().split("\n");
+    lines.push(`  \u2022 ${wrapped[0]}`);
+    for (const rest of wrapped.slice(1))
+      lines.push(`    ${rest}`);
+  }
+  return lines.join("\n");
+}
+
 // libs/gigabuddy/src/lib/commands.ts
 var PRODUCTION_AUTH_URL = "https://auth.gigabuddy.com";
 var PRODUCTION_API_URL = "https://api.gigabuddy.com";
@@ -297,16 +540,77 @@ function npmLogoutCommand(env) {
   }
   say(`Removed ${GIGABUDDY_NPM_SCOPE} registry credentials from ${file}`);
 }
-function logoutCommand(env) {
+async function logoutCommand(env) {
+  const credentials = loadUserCredentials(env.staging);
   npmLogoutCommand(env);
-  if (!loadUserCredentials(env.staging)) {
+  if (!credentials) {
     say("Not signed in.");
     return;
   }
+  const revoked = await revokeSessionByRefreshToken({
+    authUrl: credentials.authUrl,
+    refreshToken: credentials.refreshToken
+  });
   clearUserCredentials(env.staging);
-  say(`Signed out${env.staging ? " of staging" : ""}.`);
+  if (revoked) {
+    say(`Signed out${env.staging ? " of staging" : ""}. Any npm credential from this session stops working shortly.`);
+  } else {
+    say(
+      `Signed out locally${env.staging ? " of staging" : ""} \u2014 but could not reach the server to revoke the session.`
+    );
+    say("  Credentials already copied elsewhere may keep working. Sign out again when you are back online,");
+    say("  or revoke the session from your account settings.");
+  }
+}
+async function resolveAccountLabel(creds, staging) {
+  if (creds.userEmail)
+    return creds.userEmail;
+  try {
+    const token = await new TokenManager({ refreshToken: creds.refreshToken, authUrl: creds.authUrl }).getToken();
+    const email = emailFromPlatformToken(token);
+    if (!email)
+      return creds.userId;
+    saveUserCredentials({ ...creds, userEmail: email }, staging);
+    return email;
+  } catch {
+    return creds.userId;
+  }
+}
+async function doctorCommand(env, packageName) {
+  const result = await runDoctor(
+    {
+      readNpmrc: () => {
+        try {
+          return readFileSync3(npmrcPath(), "utf-8");
+        } catch {
+          return "";
+        }
+      },
+      npmEffectiveRegistry: () => {
+        try {
+          const value = execFileSync("npm", ["config", "get", `${GIGABUDDY_NPM_SCOPE}:registry`], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"]
+          }).trim();
+          return value && value !== "undefined" && value !== "null" ? value : null;
+        } catch {
+          return null;
+        }
+      },
+      fetchImpl: fetch,
+      nodeVersion: process.version,
+      loadCredentials: (staging) => loadUserCredentials(staging)
+    },
+    packageName
+  );
+  const colour = process.stderr.isTTY === true && !process.env["NO_COLOR"];
+  say();
+  say(formatDoctor(result, colour));
+  say();
+  if (result.advice.length > 0)
+    process.exitCode = 1;
 }
-function statusCommand() {
+async function statusCommand() {
   const production = loadUserCredentials(false);
   const staging = loadUserCredentials(true);
   if (!production && !staging) {
@@ -315,14 +619,14 @@ function statusCommand() {
     say("  gigabuddy login");
     return;
   }
-  for (const [label, creds] of [
-    ["Production", production],
-    ["Staging", staging]
+  for (const [label, creds, isStaging] of [
+    ["Production", production, false],
+    ["Staging", staging, true]
   ]) {
     if (!creds)
       continue;
     say(`${label}:`);
-    say(`  Account: ${creds.userEmail ?? creds.userId}`);
+    say(`  Account: ${await resolveAccountLabel(creds, isStaging)}`);
     say(`  Since: ${creds.createdAt}`);
   }
 }
@@ -331,6 +635,7 @@ export {
   PRODUCTION_AUTH_URL,
   STAGING_API_URL,
   STAGING_AUTH_URL,
+  doctorCommand,
   loginCommand,
   logoutCommand,
   npmLoginCommand,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "gigabuddy",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "The Gigabuddy CLI — sign in, and install @gigabuddy packages as yourself.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "homepage": "https://gigabuddy.com",
   "bin": {
     "gigabuddy": "bin/cli.js"
@@ -16,7 +16,8 @@
     "bin/**/*.js",
     "index.js",
     "src/**/*.d.ts",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"

package/src/lib/commands.d.ts

@@ -1,11 +1,3 @@
-/**
- * The `gigabuddy` commands. Kept separate from bin/cli.ts (which only parses
- * argv and dispatches) so each one is testable without spawning a process.
- *
- * Everything here is deliberately thin: sign in, prove who you are to the npm
- * door, say what state you're in, sign out. The platform's actual capabilities
- * live behind hosted doors — this client never grows tool implementations.
- */
 import { type UserCredentials } from '@gigabuddy/client-core';
 export declare const PRODUCTION_AUTH_URL = "https://auth.gigabuddy.com";
 export declare const PRODUCTION_API_URL = "https://api.gigabuddy.com";
@@ -33,5 +25,11 @@ export declare function loginCommand(env: Env): Promise<void>;
  */
 export declare function npmLoginCommand(env: Env): Promise<void>;
 export declare function npmLogoutCommand(env: Env): void;
-export declare function logoutCommand(env: Env): void;
-export declare function statusCommand(): void;
+export declare function logoutCommand(env: Env): Promise<void>;
+/**
+ * `gigabuddy doctor [package]` — why isn't this working?
+ *
+ * Exits non-zero when it found something wrong, so CI can gate on it.
+ */
+export declare function doctorCommand(env: Env, packageName?: string): Promise<void>;
+export declare function statusCommand(): Promise<void>;

package/src/lib/doctor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `gigabuddy doctor` — answer "why doesn't my install work?" in one command.
+ *
+ * This exists because of a deliberate property of the registry door: a denied
+ * read is answered as an npm-shaped `404 no such package`, so that private
+ * package names don't enumerate to people who can't read them. Correct for the
+ * door, miserable for the human — "not found" looks identical whether you typed
+ * the name wrong, aren't signed in, have an expired credential, or simply
+ * haven't been given access. npm cannot tell you which, and neither can the
+ * registry without leaking the thing it's protecting.
+ *
+ * So the client says it instead. It holds the pieces the door can't safely
+ * reveal — who you are signed in as, whether that session is live, what npm
+ * will actually resolve — and turns a bare 404 into a sentence with a next
+ * action in it.
+ *
+ * Every check is independent and never throws: a doctor that dies on the first
+ * problem is useless precisely when you need it.
+ */
+import { type UserCredentials } from '@gigabuddy/client-core';
+export type CheckStatus = 'ok' | 'warn' | 'fail' | 'skip';
+export interface Check {
+    label: string;
+    status: CheckStatus;
+    detail?: string;
+}
+export interface DoctorResult {
+    checks: Check[];
+    /** What to actually do next, in order. Empty when everything is healthy. */
+    advice: string[];
+}
+export interface DoctorDeps {
+    readNpmrc: () => string;
+    /** `npm config get @gigabuddy:registry` — the EFFECTIVE value, all layers merged. */
+    npmEffectiveRegistry: () => string | null;
+    fetchImpl: typeof fetch;
+    nodeVersion: string;
+    loadCredentials: (staging: boolean) => UserCredentials | null;
+}
+export declare function runDoctor(deps: DoctorDeps, packageName?: string): Promise<DoctorResult>;
+/** Render for a terminal. Colour only when one is attached and NO_COLOR is unset. */
+export declare function formatDoctor(result: DoctorResult, colour: boolean): string;