camstack 1.2.180 → 1.2.181

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   FFMPEG_PATH_ENV,
   runDiscover
-} from "./chunk-5IZ6XS4J.js";
+} from "./chunk-4MQR56VQ.js";
 import "./chunk-LMMQX4CK.js";
 
 // src/cli.ts
@@ -39,7 +39,7 @@ async function runServe(args) {
     ...typeof values.data === "string" ? { data: values.data } : {}
   };
   Object.assign(process.env, buildServeEnv(opts));
-  await import("./launcher-QBPVDG54.js");
+  await import("./launcher-TUOJ3PCS.js");
 }
 
 // src/commands/agent.ts
@@ -84,7 +84,7 @@ async function runAgent(args) {
     ...typeof values.port === "string" ? { port: values.port } : {}
   };
   Object.assign(process.env, buildAgentEnv(opts));
-  await import("./launcher-QBPVDG54.js");
+  await import("./launcher-TUOJ3PCS.js");
 }
 
 // src/commands/setup.ts
@@ -136,7 +136,7 @@ function runSetup(args) {
 // src/commands/deploy.ts
 import { execSync } from "child_process";
 import { randomBytes } from "crypto";
-import * as fs2 from "fs";
+import * as fs3 from "fs";
 import * as path2 from "path";
 
 // src/http/hub-http.ts
@@ -187,6 +187,95 @@ function hubRequest(url, opts = {}) {
   });
 }
 
+// src/commands/credentials.ts
+import * as fs2 from "fs";
+var MissingCredentialsError = class extends Error {
+  constructor(server) {
+    super(
+      [
+        `Not logged in to ${server ?? "any hub"}.`,
+        "  Run `camstack login`: it caches a token in ~/.camstack/<host>.json that every",
+        "  command reuses automatically. For scripts/CI, pass --token-file <path> with a",
+        "  token issued on Identity \u2192 Tokens (or a copied ~/.camstack session file)."
+      ].join("\n")
+    );
+    this.name = "MissingCredentialsError";
+  }
+};
+var GROUP_OR_OTHER_BITS = 63;
+function readTokenFile(filePath) {
+  let raw;
+  let mode;
+  try {
+    raw = fs2.readFileSync(filePath, "utf8");
+    mode = fs2.statSync(filePath).mode;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot read token file ${filePath}: ${reason}`, { cause: err });
+  }
+  const warning = process.platform !== "win32" && (mode & GROUP_OR_OTHER_BITS) !== 0 ? `Token file ${filePath} is readable by other users \u2014 run \`chmod 600 ${filePath}\`.` : void 0;
+  const parsed = parseTokenFile(raw.trim(), filePath);
+  return warning ? { ...parsed, warning } : parsed;
+}
+function parseTokenFile(content, filePath) {
+  if (content.length === 0) throw new Error(`Token file ${filePath} is empty.`);
+  if (content.startsWith("{")) return parseSessionJson(content, filePath);
+  if (/\s/.test(content)) {
+    throw new Error(`Token file ${filePath} must hold exactly one token (found several lines).`);
+  }
+  return { token: content };
+}
+function parseSessionJson(content, filePath) {
+  let json;
+  try {
+    json = JSON.parse(content);
+  } catch {
+    throw new Error(`Token file ${filePath} looks like JSON but does not parse.`);
+  }
+  if (json === null || typeof json !== "object") {
+    throw new Error(`Token file ${filePath}: expected a JSON object with a "token" field.`);
+  }
+  const token = Reflect.get(json, "token");
+  const server = Reflect.get(json, "server");
+  if (typeof token !== "string" || token.length === 0) {
+    throw new Error(`Token file ${filePath}: the JSON has no string "token" field.`);
+  }
+  return typeof server === "string" && server.length > 0 ? { token, server } : { token };
+}
+function resolveCredentials(inputs) {
+  const env = inputs.env ?? process.env;
+  const file = inputs.tokenFile ? readTokenFile(inputs.tokenFile) : null;
+  const targeted = inputs.server ?? env["CAMSTACK_SERVER"] ?? file?.server;
+  const session = inputs.loadSession(targeted);
+  const server = targeted ?? session?.server;
+  const picked = pickToken(inputs.token, file, env["CAMSTACK_TOKEN"], session);
+  if (!picked) throw new MissingCredentialsError(server);
+  const warning = file?.warning;
+  return warning ? { server, ...picked, warning } : { server, ...picked };
+}
+function pickToken(flag, file, envToken, session) {
+  if (flag) return { token: flag, source: "flag" };
+  if (file) return { token: file.token, source: "token-file" };
+  if (envToken) return { token: envToken, source: "env" };
+  if (session) return { token: session.token, source: "session" };
+  return null;
+}
+var REJECTION_ADVICE = {
+  session: "The hub rejected the cached session token (revoked or expired). Run `camstack login` again.",
+  "token-file": "The hub rejected the token from the token file (revoked, expired or lacking scope) \u2014 ask the operator who issued it for a new one.",
+  env: "The hub rejected $CAMSTACK_TOKEN (revoked, expired or lacking scope).",
+  flag: "The hub rejected the --token value (revoked, expired or lacking scope)."
+};
+function authRejectedHint(status, source) {
+  if (status !== 401 && status !== 403) return null;
+  return REJECTION_ADVICE[source];
+}
+function withAuthHint(message, status, source) {
+  const hint = source ? authRejectedHint(status, source) : null;
+  return hint ? `${message}
+  ${hint}` : message;
+}
+
 // src/commands/deploy.ts
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -283,12 +372,12 @@ function toPackFilenames(raw) {
 }
 function resolveAddonPath(arg) {
   const absolute = path2.resolve(arg);
-  if (fs2.existsSync(absolute)) return absolute;
+  if (fs3.existsSync(absolute)) return absolute;
   for (const candidate of [
     path2.resolve("packages", `addon-${arg}`),
     path2.resolve("packages", arg)
   ]) {
-    if (fs2.existsSync(candidate) && fs2.existsSync(path2.join(candidate, "package.json"))) {
+    if (fs3.existsSync(candidate) && fs3.existsSync(path2.join(candidate, "package.json"))) {
       return candidate;
     }
   }
@@ -305,7 +394,7 @@ async function resolveAddonPathInteractive(arg) {
     return resolved;
   }
   const cwdAbs = path2.resolve(".");
-  if (fs2.existsSync(path2.join(cwdAbs, "package.json"))) {
+  if (fs3.existsSync(path2.join(cwdAbs, "package.json"))) {
     const { discoverAddonsInCwd: discoverAddonsInCwd2 } = await import("./discover-addons-3N32LTH7.js");
     const direct = discoverAddonsInCwd2(cwdAbs, 0);
     if (direct.length > 0 && direct[0].path === cwdAbs) {
@@ -343,9 +432,9 @@ async function resolveAddonPathInteractive(arg) {
 }
 function readBuildScript(addonDir, scriptName) {
   const pkgJsonPath = path2.join(addonDir, "package.json");
-  if (!fs2.existsSync(pkgJsonPath)) return null;
+  if (!fs3.existsSync(pkgJsonPath)) return null;
   try {
-    const parsed = JSON.parse(fs2.readFileSync(pkgJsonPath, "utf8"));
+    const parsed = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf8"));
     if (!parsed || typeof parsed !== "object") return null;
     const scripts = parsed.scripts;
     if (!scripts || typeof scripts !== "object") return null;
@@ -370,7 +459,7 @@ function buildAddon(addonDir, scriptName) {
 }
 function packAddon(addonDir) {
   const pkgJsonPath = path2.join(addonDir, "package.json");
-  if (!fs2.existsSync(pkgJsonPath)) {
+  if (!fs3.existsSync(pkgJsonPath)) {
     throw new Error(`No package.json found in: ${addonDir}`);
   }
   console.log(`[camstack] Packing addon from ${addonDir}...`);
@@ -389,7 +478,7 @@ function packAddon(addonDir) {
   }
   if (!tgzFilename) throw new Error("npm pack did not produce a .tgz file");
   const tgzPath = path2.join(addonDir, tgzFilename);
-  if (!fs2.existsSync(tgzPath)) {
+  if (!fs3.existsSync(tgzPath)) {
     throw new Error(`Expected tgz file not found: ${tgzPath}`);
   }
   console.log(`[camstack] Packed: ${tgzFilename}`);
@@ -397,7 +486,7 @@ function packAddon(addonDir) {
     tgzPath,
     cleanup: () => {
       try {
-        if (fs2.existsSync(tgzPath)) fs2.unlinkSync(tgzPath);
+        if (fs3.existsSync(tgzPath)) fs3.unlinkSync(tgzPath);
       } catch {
       }
     }
@@ -427,7 +516,7 @@ async function fetchOnlineAgents(serverUrl, token) {
 }
 async function uploadToTarget(args) {
   const { serverUrl, token, tgzPath, nodeId, addonId } = args;
-  const fileBuffer = fs2.readFileSync(tgzPath);
+  const fileBuffer = fs3.readFileSync(tgzPath);
   const boundary = `----camstackcli${randomBytes(16).toString("hex")}`;
   const CRLF = "\r\n";
   const parts = [];
@@ -464,17 +553,21 @@ async function uploadToTarget(args) {
   if (!response.ok) {
     return {
       success: false,
-      error: result.error ?? `Server returned ${response.status} ${response.statusText}`
+      error: withAuthHint(
+        result.error ?? `Server returned ${response.status} ${response.statusText}`,
+        response.status,
+        args.authSource
+      )
     };
   }
   return result;
 }
 async function deployAddon(addonPath, opts) {
-  const resolvedPath = path2.isAbsolute(addonPath) && fs2.existsSync(addonPath) ? addonPath : await resolveAddonPathInteractive(addonPath);
+  const resolvedPath = path2.isAbsolute(addonPath) && fs3.existsSync(addonPath) ? addonPath : await resolveAddonPathInteractive(addonPath);
   let tgzPath;
   let cleanup = null;
   if (resolvedPath.endsWith(".tgz") || resolvedPath.endsWith(".tar.gz")) {
-    if (!fs2.existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
+    if (!fs3.existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
     tgzPath = resolvedPath;
   } else {
     const buildMode = opts.buildMode ?? "auto";
@@ -531,7 +624,8 @@ async function deployAddon(addonPath, opts) {
           serverUrl: opts.serverUrl,
           token: opts.token,
           tgzPath,
-          ...t.nodeId ? { nodeId: t.nodeId } : {}
+          ...t.nodeId ? { nodeId: t.nodeId } : {},
+          ...opts.authSource ? { authSource: opts.authSource } : {}
         }),
         {
           attempts: 5,
@@ -591,12 +685,12 @@ async function deployAddon(addonPath, opts) {
 // src/commands/deploy-server.ts
 import { execSync as execSync2 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import * as fs4 from "fs";
+import * as fs5 from "fs";
 import * as os2 from "os";
 import * as path4 from "path";
 
 // src/commands/server-closure.ts
-import * as fs3 from "fs";
+import * as fs4 from "fs";
 import * as path3 from "path";
 var CAMSTACK_SCOPE_PREFIX = "@camstack/";
 function computeDevVersion(base, epochSeconds) {
@@ -605,7 +699,7 @@ function computeDevVersion(base, epochSeconds) {
 function readPackageManifest(dir) {
   const pkgJsonPath = path3.join(dir, "package.json");
   try {
-    const parsed = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+    const parsed = JSON.parse(fs4.readFileSync(pkgJsonPath, "utf-8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
     const raw = parsed;
     if (typeof raw["name"] !== "string") return null;
@@ -631,7 +725,7 @@ function loadWorkspacePackages(workspaceRoot) {
       const base = path3.join(workspaceRoot, pattern.slice(0, -2));
       let entries;
       try {
-        entries = fs3.readdirSync(base, { withFileTypes: true });
+        entries = fs4.readdirSync(base, { withFileTypes: true });
       } catch {
         continue;
       }
@@ -705,7 +799,7 @@ function discoverServerClosure(workspaceRoot) {
 }
 function withDevVersionPackageJson(pkgDir, devVersion, intraSetNames, fn) {
   const pkgJsonPath = path3.join(pkgDir, "package.json");
-  const originalBytes = fs3.readFileSync(pkgJsonPath);
+  const originalBytes = fs4.readFileSync(pkgJsonPath);
   const parsed = JSON.parse(originalBytes.toString("utf-8"));
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`Malformed package.json: ${pkgJsonPath}`);
@@ -723,12 +817,12 @@ function withDevVersionPackageJson(pkgDir, devVersion, intraSetNames, fn) {
     }
     manifest[field] = rewritten;
   }
-  fs3.writeFileSync(pkgJsonPath, `${JSON.stringify(manifest, null, 2)}
+  fs4.writeFileSync(pkgJsonPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf-8");
   try {
     return fn();
   } finally {
-    fs3.writeFileSync(pkgJsonPath, originalBytes);
+    fs4.writeFileSync(pkgJsonPath, originalBytes);
   }
 }
 
@@ -751,7 +845,7 @@ function hasBuildScript(pkgDir) {
 }
 function readJson(filePath) {
   try {
-    return JSON.parse(fs4.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs5.readFileSync(filePath, "utf-8"));
   } catch {
     return null;
   }
@@ -799,7 +893,7 @@ function packPackage(pkg, devVersion, intraSetNames, outDir) {
     throw new Error(`npm pack produced no tarball for ${pkg.name}`);
   }
   const tgzPath = path4.join(outDir, path4.basename(filename));
-  if (!fs4.existsSync(tgzPath)) {
+  if (!fs5.existsSync(tgzPath)) {
     throw new Error(`Expected tarball not found after pack: ${tgzPath}`);
   }
   return { name: pkg.name, tgzPath };
@@ -817,7 +911,7 @@ async function uploadClosure(args) {
       Buffer.from(
         `--${boundary}${CRLF}Content-Disposition: form-data; name="file"; filename="${path4.basename(tarball.tgzPath)}"${CRLF}Content-Type: application/gzip${CRLF}${CRLF}`
       ),
-      fs4.readFileSync(tarball.tgzPath),
+      fs5.readFileSync(tarball.tgzPath),
       Buffer.from(CRLF)
     );
   }
@@ -836,7 +930,9 @@ async function uploadClosure(args) {
   const payload = await response.json().catch(() => ({}));
   if (!response.ok || !isRecord2(payload) || payload["success"] !== true) {
     const detail = isRecord2(payload) && typeof payload["error"] === "string" ? payload["error"] : `${response.status} ${response.statusText}`;
-    throw new Error(`Server upload rejected: ${detail}`);
+    throw new Error(
+      withAuthHint(`Server upload rejected: ${detail}`, response.status, args.authSource)
+    );
   }
 }
 function toApplyResult(value) {
@@ -872,7 +968,13 @@ async function applyServerUpdate(args) {
   );
   const body = await res.json().catch(() => null);
   if (!res.ok) {
-    throw new Error(`applyServerUpdate returned ${res.status} ${res.statusText}`);
+    throw new Error(
+      withAuthHint(
+        `applyServerUpdate returned ${res.status} ${res.statusText}`,
+        res.status,
+        args.authSource
+      )
+    );
   }
   const result = toApplyResult(unwrapTrpcJson(body));
   if (result === null) {
@@ -950,7 +1052,7 @@ async function deployServer(opts) {
   console.log(`[camstack] Building ${closure.buildSet.length} packages (dependency order)...`);
   for (const pkg of closure.buildSet) buildPackage(pkg);
   const intraSetNames = new Set(closure.packSet.map((p) => p.name));
-  const outDir = fs4.mkdtempSync(path4.join(os2.tmpdir(), "camstack-deploy-server-"));
+  const outDir = fs5.mkdtempSync(path4.join(os2.tmpdir(), "camstack-deploy-server-"));
   try {
     console.log(`[camstack] Packing ${closure.packSet.length} packages at ${devVersion}...`);
     const tarballs = [];
@@ -964,14 +1066,16 @@ async function deployServer(opts) {
       serverUrl: opts.serverUrl,
       token: opts.token,
       version: devVersion,
-      tarballs
+      tarballs,
+      ...opts.authSource ? { authSource: opts.authSource } : {}
     });
     console.log("[camstack] \u2713 Upload accepted");
     console.log(`[camstack] Applying server update to ${devVersion}...`);
     const apply = await applyServerUpdate({
       serverUrl: opts.serverUrl,
       token: opts.token,
-      version: devVersion
+      version: devVersion,
+      ...opts.authSource ? { authSource: opts.authSource } : {}
     });
     if (!apply.accepted) {
       console.error(`[camstack] \u2717 applyServerUpdate refused: ${apply.message}`);
@@ -986,12 +1090,12 @@ async function deployServer(opts) {
     await pollUntilPromoted({ serverUrl: opts.serverUrl, token: opts.token, version: devVersion });
     console.log(`[camstack] \u2713 ${devVersion} promoted \u2014 the hub is running the dev closure`);
   } finally {
-    fs4.rmSync(outDir, { recursive: true, force: true });
+    fs5.rmSync(outDir, { recursive: true, force: true });
   }
 }
 
 // src/commands/auth.ts
-import * as fs5 from "fs";
+import * as fs6 from "fs";
 import * as path5 from "path";
 import * as os3 from "os";
 import * as clack from "@clack/prompts";
@@ -1003,12 +1107,12 @@ function sessionFileForServer(serverUrl) {
 function resolveSessionFile(serverUrl) {
   if (serverUrl) {
     const p = sessionFileForServer(serverUrl);
-    return fs5.existsSync(p) ? p : null;
+    return fs6.existsSync(p) ? p : null;
   }
-  if (!fs5.existsSync(SESSION_DIR)) return null;
-  const files = fs5.readdirSync(SESSION_DIR).filter((f) => f.endsWith(".json")).map((f) => path5.join(SESSION_DIR, f));
+  if (!fs6.existsSync(SESSION_DIR)) return null;
+  const files = fs6.readdirSync(SESSION_DIR).filter((f) => f.endsWith(".json")).map((f) => path5.join(SESSION_DIR, f));
   if (files.length === 0) return null;
-  return files.map((f) => ({ f, mtime: fs5.statSync(f).mtimeMs })).toSorted((a, b) => b.mtime - a.mtime)[0].f;
+  return files.map((f) => ({ f, mtime: fs6.statSync(f).mtimeMs })).toSorted((a, b) => b.mtime - a.mtime)[0].f;
 }
 function isSessionFile(value) {
   if (value === null || typeof value !== "object") return false;
@@ -1025,24 +1129,24 @@ function loadSession(serverUrl) {
   const file = resolveSessionFile(serverUrl);
   if (!file) return null;
   try {
-    const parsed = JSON.parse(fs5.readFileSync(file, "utf8"));
+    const parsed = JSON.parse(fs6.readFileSync(file, "utf8"));
     return isSessionFile(parsed) ? parsed : null;
   } catch {
     return null;
   }
 }
 function saveSession(session) {
-  if (!fs5.existsSync(SESSION_DIR)) {
-    fs5.mkdirSync(SESSION_DIR, { recursive: true, mode: 448 });
+  if (!fs6.existsSync(SESSION_DIR)) {
+    fs6.mkdirSync(SESSION_DIR, { recursive: true, mode: 448 });
   }
   const file = sessionFileForServer(session.server);
-  fs5.writeFileSync(file, JSON.stringify(session, null, 2), { mode: 384 });
+  fs6.writeFileSync(file, JSON.stringify(session, null, 2), { mode: 384 });
   return file;
 }
 function clearSession(serverUrl) {
   const file = sessionFileForServer(serverUrl);
-  if (fs5.existsSync(file)) {
-    fs5.unlinkSync(file);
+  if (fs6.existsSync(file)) {
+    fs6.unlinkSync(file);
     return true;
   }
   return false;
@@ -1132,7 +1236,7 @@ function isUnknown(_value) {
   return true;
 }
 async function resolveServerInteractive(presetNamespace) {
-  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-2RRBNIQP.js");
+  const { discoverNodes, resolveHubFromDiscovered, filterHubNodes, DEFAULT_HUB_HTTPS_PORT } = await import("./discover-LW74552N.js");
   if (presetNamespace) {
     const spinner4 = clack.spinner();
     spinner4.start(`Discovering hub on LAN (namespace "${presetNamespace}")`);
@@ -1381,7 +1485,7 @@ import { spawn } from "child_process";
 import * as clack2 from "@clack/prompts";
 
 // src/update-notifier.ts
-import * as fs6 from "fs";
+import * as fs7 from "fs";
 import * as path6 from "path";
 import * as os4 from "os";
 var CACHE_DIR = path6.join(os4.homedir(), ".camstack");
@@ -1391,8 +1495,8 @@ var REGISTRY_BASE = "https://registry.npmjs.org";
 var FETCH_TIMEOUT_MS = 2500;
 function readCache() {
   try {
-    if (!fs6.existsSync(CACHE_FILE)) return null;
-    const parsed = JSON.parse(fs6.readFileSync(CACHE_FILE, "utf8"));
+    if (!fs7.existsSync(CACHE_FILE)) return null;
+    const parsed = JSON.parse(fs7.readFileSync(CACHE_FILE, "utf8"));
     if (!parsed || typeof parsed !== "object") return null;
     const c = parsed;
     if (typeof c.lastCheckAt !== "number") return null;
@@ -1407,8 +1511,8 @@ function readCache() {
 }
 function writeCache(c) {
   try {
-    if (!fs6.existsSync(CACHE_DIR)) fs6.mkdirSync(CACHE_DIR, { recursive: true, mode: 448 });
-    fs6.writeFileSync(CACHE_FILE, JSON.stringify(c, null, 2));
+    if (!fs7.existsSync(CACHE_DIR)) fs7.mkdirSync(CACHE_DIR, { recursive: true, mode: 448 });
+    fs7.writeFileSync(CACHE_FILE, JSON.stringify(c, null, 2));
   } catch {
   }
 }
@@ -1567,7 +1671,7 @@ async function runUpdate(args) {
 }
 
 // src/commands/dev.ts
-import * as fs7 from "fs";
+import * as fs8 from "fs";
 import * as path7 from "path";
 import { parseArgs as parseArgs5 } from "util";
 import * as clack3 from "@clack/prompts";
@@ -1578,14 +1682,14 @@ function resolveAddonDir(arg) {
     throw new Error("`dev` requires a source directory, not a tarball (nothing to watch).");
   }
   const absolute = path7.resolve(arg);
-  if (fs7.existsSync(absolute) && fs7.statSync(absolute).isDirectory()) {
+  if (fs8.existsSync(absolute) && fs8.statSync(absolute).isDirectory()) {
     return absolute;
   }
   for (const candidate of [
     path7.resolve("packages", `addon-${arg}`),
     path7.resolve("packages", arg)
   ]) {
-    if (fs7.existsSync(candidate) && fs7.statSync(candidate).isDirectory()) {
+    if (fs8.existsSync(candidate) && fs8.statSync(candidate).isDirectory()) {
       return candidate;
     }
   }
@@ -1595,10 +1699,10 @@ function resolveAddonDir(arg) {
 }
 function watchRecursive(target, onEvent) {
   try {
-    const w = fs7.watch(target, { recursive: true }, onEvent);
+    const w = fs8.watch(target, { recursive: true }, onEvent);
     return { close: () => w.close(), recursive: true };
   } catch {
-    const w = fs7.watch(target, onEvent);
+    const w = fs8.watch(target, onEvent);
     return { close: () => w.close(), recursive: false };
   }
 }
@@ -1622,6 +1726,7 @@ async function runDev(args) {
     options: {
       server: { type: "string", short: "s" },
       token: { type: "string", short: "t" },
+      "token-file": { type: "string" },
       node: { type: "string", short: "n" },
       cluster: { type: "boolean", short: "c" },
       "watch-path": { type: "string", short: "w" },
@@ -1635,27 +1740,32 @@ async function runDev(args) {
   });
   const addonArg = positionals[0] ?? ".";
   const addonDir = resolveAddonDir(addonArg);
-  const explicitServer = typeof values.server === "string" ? values.server : void 0;
-  const explicitToken = typeof values.token === "string" ? values.token : void 0;
-  const session = loadSession(explicitServer);
-  const serverUrl = explicitServer ?? process.env.CAMSTACK_SERVER ?? session?.server;
-  const token = explicitToken ?? process.env.CAMSTACK_TOKEN ?? session?.token;
-  if (!serverUrl || !token) {
-    throw new Error("Missing server/token. Run `camstack login` first, or pass --server + --token.");
+  const creds = resolveCredentials({
+    ...typeof values.server === "string" ? { server: values.server } : {},
+    ...typeof values.token === "string" ? { token: values.token } : {},
+    ...typeof values["token-file"] === "string" ? { tokenFile: values["token-file"] } : {},
+    loadSession
+  });
+  if (creds.warning) console.error(`[camstack dev] Warning: ${creds.warning}`);
+  const serverUrl = creds.server;
+  const token = creds.token;
+  if (!serverUrl) {
+    throw new Error("No hub server known. Pass --server, or run `camstack login` first.");
   }
   const nodeId = typeof values.node === "string" ? values.node : void 0;
   const cluster = values.cluster === true;
   const deployOpts = {
     serverUrl,
     token,
+    authSource: creds.source,
     ...nodeId ? { nodeId } : {},
     ...cluster ? { cluster: true } : {},
     buildMode: values["no-build"] === true ? "skip" : "auto",
     ...typeof values["build-script"] === "string" ? { buildScript: values["build-script"] } : {}
   };
   const watchOverride = typeof values["watch-path"] === "string" ? values["watch-path"] : void 0;
-  const watchTarget = watchOverride ? path7.resolve(addonDir, watchOverride) : fs7.existsSync(path7.join(addonDir, DEFAULT_WATCH_SUBDIR)) ? path7.join(addonDir, DEFAULT_WATCH_SUBDIR) : addonDir;
-  if (!fs7.existsSync(watchTarget)) {
+  const watchTarget = watchOverride ? path7.resolve(addonDir, watchOverride) : fs8.existsSync(path7.join(addonDir, DEFAULT_WATCH_SUBDIR)) ? path7.join(addonDir, DEFAULT_WATCH_SUBDIR) : addonDir;
+  if (!fs8.existsSync(watchTarget)) {
     throw new Error(`Watch path does not exist: ${watchTarget}`);
   }
   const debounceMs = typeof values.debounce === "string" ? parseInt(values.debounce, 10) : DEFAULT_DEBOUNCE_MS;
@@ -1743,13 +1853,15 @@ function printLine(e, addonId) {
 `
   );
 }
-async function fetchLogs(server, token, addonId, limit) {
+async function fetchLogs(server, token, addonId, limit, authSource) {
   const input = encodeURIComponent(JSON.stringify({ json: { addonId, limit } }));
   const url = `${server}/trpc/addons.getLogs?input=${input}`;
   const res = await hubRequest(url, { headers: { Authorization: `Bearer ${token}` } });
   if (!res.ok) {
     const text2 = await res.text().catch(() => "");
-    throw new Error(`getLogs HTTP ${res.status}: ${text2.slice(0, 200)}`);
+    throw new Error(
+      withAuthHint(`getLogs HTTP ${res.status}: ${text2.slice(0, 200)}`, res.status, authSource)
+    );
   }
   const body = await res.json();
   return body.result?.data?.json ?? [];
@@ -1760,6 +1872,7 @@ async function runWatch(args) {
     options: {
       server: { type: "string", short: "s" },
       token: { type: "string", short: "t" },
+      "token-file": { type: "string" },
       node: { type: "string", short: "n" },
       cluster: { type: "boolean", short: "c" },
       "no-build": { type: "boolean" },
@@ -1771,17 +1884,24 @@ async function runWatch(args) {
     allowPositionals: true
   });
   const addonArg = positionals[0] ?? ".";
-  const session = loadSession(typeof values.server === "string" ? values.server : void 0);
-  const serverUrl = (typeof values.server === "string" ? values.server : void 0) ?? process.env.CAMSTACK_SERVER ?? session?.server;
-  const token = (typeof values.token === "string" ? values.token : void 0) ?? process.env.CAMSTACK_TOKEN ?? session?.token;
-  if (!serverUrl || !token) {
-    throw new Error("Missing server/token. Run `camstack login` first, or pass --server + --token.");
+  const creds = resolveCredentials({
+    ...typeof values.server === "string" ? { server: values.server } : {},
+    ...typeof values.token === "string" ? { token: values.token } : {},
+    ...typeof values["token-file"] === "string" ? { tokenFile: values["token-file"] } : {},
+    loadSession
+  });
+  if (creds.warning) console.error(`[camstack watch] Warning: ${creds.warning}`);
+  const serverUrl = creds.server;
+  const token = creds.token;
+  if (!serverUrl) {
+    throw new Error("No hub server known. Pass --server, or run `camstack login` first.");
   }
   const nodeId = typeof values.node === "string" ? values.node : void 0;
   const cluster = values.cluster === true;
   const deployOpts = {
     serverUrl,
     token,
+    authSource: creds.source,
     ...nodeId ? { nodeId } : {},
     ...cluster ? { cluster: true } : {},
     buildMode: values["no-build"] === true ? "skip" : "auto",
@@ -1807,7 +1927,7 @@ async function runWatch(args) {
   process.on("SIGTERM", shutdown);
   while (!stop) {
     try {
-      const entries = await fetchLogs(serverUrl, token, addonId, LOG_BATCH_LIMIT);
+      const entries = await fetchLogs(serverUrl, token, addonId, LOG_BATCH_LIMIT, creds.source);
       const sorted = [...entries].toSorted((a, b) => {
         const ta = typeof a.timestamp === "number" ? a.timestamp : new Date(a.timestamp).getTime();
         const tb = typeof b.timestamp === "number" ? b.timestamp : new Date(b.timestamp).getTime();
@@ -2210,6 +2330,10 @@ function printGlobalHelp(commands) {
   lines.push("  -h, --help       Show this help, or per-command help with `camstack <cmd> --help`");
   console.log(lines.join("\n"));
 }
+var TOKEN_RESOLUTION_HELP = [
+  "Token resolution (first hit wins): --token, --token-file, $CAMSTACK_TOKEN,",
+  "  then the session cached by `camstack login` for the target server."
+].join("\n");
 function buildCommands() {
   return [
     {
@@ -2331,10 +2455,13 @@ function buildCommands() {
         "      --no-verify         Skip the post-deploy hub /health gate",
         "",
         "Target options:",
-        "  -s, --server <url>      Server URL (default: cached session from `camstack login`)",
-        "  -t, --token <token>     Auth token override ($CAMSTACK_TOKEN, then cached scoped token)",
+        "  -s, --server <url>      Server URL (default: $CAMSTACK_SERVER, then the cached session)",
+        "  -t, --token <token>     Auth token override",
+        "      --token-file <path> Read the token from a file (bare token or a ~/.camstack session file)",
         "  -n, --node <id>         Push to a specific node. Mutually exclusive with --cluster",
-        "  -c, --cluster           Push to hub + every online agent (requires admin token)"
+        "  -c, --cluster           Push to hub + every online agent (requires admin token)",
+        "",
+        TOKEN_RESOLUTION_HELP
       ].join("\n")
     },
     {
@@ -2352,9 +2479,12 @@ function buildCommands() {
         "  and waits for the probation boot to promote.",
         "",
         "Options:",
-        "  -s, --server <url>     Server URL (default: cached session from `camstack login`)",
-        "  -t, --token <token>    Auth token override ($CAMSTACK_TOKEN, then cached scoped token)",
-        "      --no-verify        Do not wait for promotion after applyServerUpdate is accepted"
+        "  -s, --server <url>     Server URL (default: $CAMSTACK_SERVER, then the cached session)",
+        "  -t, --token <token>    Auth token override",
+        "      --token-file <path> Read the token from a file (bare token or a ~/.camstack session file)",
+        "      --no-verify        Do not wait for promotion after applyServerUpdate is accepted",
+        "",
+        TOKEN_RESOLUTION_HELP
       ].join("\n")
     },
     {
@@ -2370,6 +2500,7 @@ function buildCommands() {
         "Options:",
         "  -s, --server <url>         Server URL (default: cached session)",
         "  -t, --token <token>        Auth token override",
+        "      --token-file <path>    Read the token from a file",
         "  -n, --node <id>            Push to a specific node",
         "  -c, --cluster              Push to hub + every online agent",
         "      --no-build             Skip `npm run build`",
@@ -2378,7 +2509,9 @@ function buildCommands() {
         "      --no-initial-deploy    Skip initial deploy \u2014 only tail existing addon",
         "",
         "Each round polls the last 100 entries; new entries (by timestamp+content)",
-        "are printed. Ctrl-C to stop."
+        "are printed. Ctrl-C to stop.",
+        "",
+        TOKEN_RESOLUTION_HELP
       ].join("\n")
     },
     {
@@ -2403,11 +2536,14 @@ function buildCommands() {
         "Target options:",
         "  -s, --server <url>        Server URL (default: cached session)",
         "  -t, --token <token>       Auth token override",
+        "      --token-file <path>   Read the token from a file",
         "  -n, --node <id>           Push to a specific node",
         "  -c, --cluster             Push to hub + every online agent",
         "",
         "Stop with Ctrl-C. Each cycle is sequential \u2014 concurrent changes during",
-        "a push are coalesced into the next cycle."
+        "a push are coalesced into the next cycle.",
+        "",
+        TOKEN_RESOLUTION_HELP
       ].join("\n")
     },
     {
@@ -2528,6 +2664,7 @@ async function runDeploy(args) {
     {
       server: { type: "string", short: "s" },
       token: { type: "string", short: "t" },
+      "token-file": { type: "string" },
       node: { type: "string", short: "n" },
       cluster: { type: "boolean", short: "c" },
       build: { type: "string", short: "b" },
@@ -2542,15 +2679,9 @@ async function runDeploy(args) {
     return;
   }
   const addonPath = parsed.positionals[0] ?? ".";
-  const session = loadSession(stringOpt(parsed.values, "server"));
-  const server = stringOpt(parsed.values, "server") ?? process.env.CAMSTACK_SERVER ?? session?.server ?? "https://localhost:4443";
-  const token = stringOpt(parsed.values, "token") ?? process.env.CAMSTACK_TOKEN ?? session?.token;
-  if (!token) {
-    console.error(
-      "[camstack] Error: No token. Run `camstack login` first, pass --token, or set CAMSTACK_TOKEN."
-    );
-    process.exit(1);
-  }
+  const creds = resolveCommandCredentials(parsed.values);
+  const server = creds.server ?? DEFAULT_SERVER_URL;
+  const token = creds.token;
   const nodeId = stringOpt(parsed.values, "node");
   const cluster = boolOpt(parsed.values, "cluster");
   if (nodeId && cluster) {
@@ -2572,6 +2703,7 @@ async function runDeploy(args) {
   await deployAddon(addonPath, {
     serverUrl: server,
     token,
+    authSource: creds.source,
     ...nodeId ? { nodeId } : {},
     ...cluster ? { cluster: true } : {},
     buildMode,
@@ -2585,6 +2717,7 @@ async function runDeployServer(args) {
     {
       server: { type: "string", short: "s" },
       token: { type: "string", short: "t" },
+      "token-file": { type: "string" },
       "no-verify": { type: "boolean" }
     },
     false
@@ -2593,21 +2726,36 @@ async function runDeployServer(args) {
     console.log(commandHelp("deploy-server"));
     return;
   }
-  const session = loadSession(stringOpt(parsed.values, "server"));
-  const server = stringOpt(parsed.values, "server") ?? process.env.CAMSTACK_SERVER ?? session?.server ?? "https://localhost:4443";
-  const token = stringOpt(parsed.values, "token") ?? process.env.CAMSTACK_TOKEN ?? session?.token;
-  if (!token) {
-    console.error(
-      "[camstack] Error: No token. Run `camstack login` first, pass --token, or set CAMSTACK_TOKEN."
-    );
-    process.exit(1);
-  }
+  const creds = resolveCommandCredentials(parsed.values);
   await deployServer({
-    serverUrl: server,
-    token,
+    serverUrl: creds.server ?? DEFAULT_SERVER_URL,
+    token: creds.token,
+    authSource: creds.source,
     verify: !boolOpt(parsed.values, "no-verify")
   });
 }
+var DEFAULT_SERVER_URL = "https://localhost:4443";
+function resolveCommandCredentials(values) {
+  const server = stringOpt(values, "server");
+  const token = stringOpt(values, "token");
+  const tokenFile = stringOpt(values, "token-file");
+  try {
+    const creds = resolveCredentials({
+      ...server ? { server } : {},
+      ...token ? { token } : {},
+      ...tokenFile ? { tokenFile } : {},
+      loadSession
+    });
+    if (creds.warning) console.error(`[camstack] Warning: ${creds.warning}`);
+    return creds;
+  } catch (err) {
+    if (err instanceof MissingCredentialsError) {
+      console.error(`[camstack] ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
 function commandHelp(name) {
   const cmd = buildCommands().find((c) => c.name === name);
   return cmd ? cmd.help() : "";