@sprid/cli 0.1.2

package/src/commands/status.mjs

@@ -0,0 +1,217 @@
+import { readLocalApp } from "../profiles.mjs";
+// status / next / queue. Every line here is one field of the StatusView the
+// server computes; the web Home card and the Monday mail print the same list.
+// This file only lays it out.
+
+import { BAD, C, NONE, OK, capOf, dayTime, healthMark, hhmm, pad, table, wrap } from "../format.mjs";
+
+const isHttp = (s) => typeof s === "string" && /^https?:\/\//.test(s);
+
+async function fetchStatus(ctx) {
+  const app = ctx.flags.app || readLocalApp(ctx.cwd)?.data?.appId || readLocalApp(ctx.cwd)?.data?.slug;
+  return ctx.api().get(`/api/status?workspaceId=${await ctx.workspaceId()}${app ? `&app=${encodeURIComponent(app)}` : ""}${ctx.flags.account ? `&account=${encodeURIComponent(ctx.flags.account)}` : ""}`);
+}
+
+export async function status(ctx) {
+  const view = await fetchStatus(ctx);
+  if (ctx.json) {
+    ctx.out(view);
+    return 0;
+  }
+  // A person with several workspaces needs to know which dashboard this is.
+  const several = (await ctx.workspaces().catch(() => [])).length > 1;
+  ctx.print(renderStatus(view, { header: several }));
+  return 0;
+}
+
+/** The dashboard in the terminal (plan doc §4). */
+export function renderStatus(view, { header = false } = {}) {
+  const lines = [];
+  const L = (label, body) => `  ${pad(label, 13)}${body}`;
+  if (header && view.workspace?.name) {
+    lines.push(`  ${C.bold(view.workspace.name)} (${view.workspace.tier ?? view.workspace.slug})`);
+  }
+
+  // NEXT: top 3, numbered, with the cli line right-aligned in a column.
+  const top = (view.next ?? []).slice(0, 3);
+  if (top.length === 0) {
+    lines.push(L("NEXT", C.dim("nothing needs you")));
+  } else {
+    const rows = top.map((a, i) => [`${i + 1}`, a.title, C.dim(a.cli)]);
+    const t = table(rows, { indent: "", gap: 2 }).split("\n");
+    t.forEach((row, i) => {
+      lines.push(L(i === 0 ? "NEXT" : "", row));
+      if (isHttp(top[i].href)) lines.push(L("", `   → ${top[i].href}`));
+    });
+    if ((view.next ?? []).length > 3) lines.push(L("", C.dim(`+${view.next.length - 3} more · sprid next`)));
+  }
+
+  // CONNECTIONS: one line per account (channels), then one per App Profile
+  // (sensors). Flattened it read "instagram ✗ instagram ✓ instagram ✓" and
+  // nobody could tell which account was the broken one.
+  const conns = view.connections ?? [];
+  if (conns.length === 0) {
+    lines.push(L("CONNECTIONS", C.dim("none yet · sprid connect")));
+  } else {
+    const rows = connectionRows(conns);
+    const t = table(rows, { indent: "", gap: 2 }).split("\n");
+    t.forEach((row, i) => lines.push(L(i === 0 ? "CONNECTIONS" : "", row)));
+  }
+
+  // QUEUE
+  const q = view.queue ?? { scheduled: 0, nextAt: null, nextAccount: null, failed7d: 0 };
+  const next = q.nextAt ? `next ${dayTime(q.nextAt)}${q.nextAccount ? ` @${q.nextAccount}` : ""}` : "nothing scheduled";
+  lines.push(L("QUEUE", `${q.scheduled} scheduled · ${next} · ${q.failed7d} failed`));
+
+  // APPS: one line per App Profile, sensors as marks.
+  const apps = view.apps ?? [];
+  if (apps.length === 0) {
+    lines.push(L("APPS", C.dim("none · sprid init")));
+  } else {
+    const rows = apps.map((a) => [a.slug, sensorsLine(a.sensors, failingServices(conns, a.slug))]);
+    const t = table(rows, { indent: "", gap: 2 }).split("\n");
+    t.forEach((row, i) => lines.push(L(i === 0 ? "APPS" : "", row)));
+  }
+
+  // PLAN
+  const ws = view.workspace ?? {};
+  const u = view.usage ?? {};
+  const caps = view.caps ?? {};
+  // The plan as the server reads it (billing/plan.ts), not as the raw status
+  // column reads: "trial" alone never said how long was left, and "expired"
+  // means the fourteen days ran out rather than that anybody cancelled.
+  const plan = ws.plan ?? null;
+  const statusWord = plan
+    ? plan.state === "trialing"
+      ? ` trial, ${plan.daysLeft === 0 ? "last day" : `${plan.daysLeft}d left`}`
+      : plan.state === "trial_expired"
+        ? " trial ended"
+        : plan.state === "active"
+          ? ""
+          : ` ${plan.state.replace("_", " ")}`
+    : ws.status && ws.status !== "active"
+      ? ` ${ws.status.replace("_", " ")}`
+      : "";
+  lines.push(
+    L(
+      "PLAN",
+      `${ws.tierName ?? ws.tier ?? ""}${statusWord} · ${u.appProfiles ?? 0}/${capOf(caps.appProfiles)} apps · ${u.accounts ?? 0}/${capOf(caps.accounts)} accounts · ${u.channels ?? 0}/${capOf(caps.channels)} channels${byokWord(conns)}`,
+    ),
+  );
+  // One line under PLAN when the server has stopped, or is about to. It says
+  // the command, because a terminal user should never have to open a browser
+  // to find out what to type.
+  if (plan && (!plan.active || (plan.state === "trialing" && plan.endingSoon))) {
+    lines.push(L("", `${plan.reason} → sprid upgrade pulse`));
+  }
+  return lines.join("\n");
+}
+
+const PROVIDER_SERVICES = new Set(["anthropic", "openai", "fal", "google", "replicate"]);
+
+/** ` · BYOK anthropic ✓` / ` · BYOK –` from the workspace-level provider-key rows; nothing when the server sends none. */
+export function byokWord(conns = []) {
+  const rows = conns.filter((c) => c.kind === "sensor" && PROVIDER_SERVICES.has(c.service));
+  if (rows.length === 0) return "";
+  const ok = rows.filter((c) => c.health === "ok").map((c) => c.service);
+  return ok.length ? ` · BYOK ${ok.map((s) => `${s} ${OK}`).join(" ")}` : ` · BYOK ${NONE}`;
+}
+
+/** [scopeLabel, "service mark  service mark …"] per account, then per App Profile. */
+export function connectionRows(conns) {
+  const groups = new Map();
+  for (const c of conns) {
+    if (PROVIDER_SERVICES.has(c.service)) continue; // workspace-level; shown on the PLAN line
+    const isSensor = c.kind === "sensor";
+    const key = `${isSensor ? "1" : "0"}:${c.scope}`;
+    if (!groups.has(key)) {
+      // Sensors are labelled "App Store Connect · My App": the app's name is after the dot.
+      const name = isSensor ? (c.label?.split(" · ")[1] ?? c.scope) : c.scope;
+      groups.set(key, { name, cells: [] });
+    }
+    const g = groups.get(key);
+    const mark = healthMark(c.health);
+    const note = c.health === "revoked" || c.health === "expiring" ? ` (${c.health})` : "";
+    const time = isSensor && c.health === "ok" && c.lastOkAt ? ` ${hhmm(c.lastOkAt)}` : "";
+    g.cells.push(`${c.service} ${mark}${note}${time}`);
+  }
+  return [...groups.keys()].sort().map((k) => [groups.get(k).name, groups.get(k).cells.join("  ")]);
+}
+
+const SENSOR_ORDER = [
+  ["appStoreReviews", "asc"],
+  ["playReviews", "play"],
+  ["posthog", "posthog"],
+  ["revenuecat", "revenuecat"],
+  ["searchConsole", "gsc"],
+  ["cloudflare", "cloudflare"],
+];
+
+/** Sensor services whose last pull failed (`health: "error"`) for one App Profile. */
+export function failingServices(conns = [], slug) {
+  return new Set(conns.filter((c) => c.kind === "sensor" && c.scope === slug && c.health === "error").map((c) => c.service));
+}
+
+/** A key that is set but whose last pull failed shows ✗, not ✓. */
+export function sensorsLine(sensors = {}, failing = new Set()) {
+  return SENSOR_ORDER.map(([k, label]) => `${label} ${failing.has(label) ? BAD : sensors[k] ? OK : NONE}`).join("  ");
+}
+
+export async function next(ctx) {
+  const params = new URLSearchParams({ workspaceId: String(await ctx.workspaceId()) });
+  if (ctx.flags.limit) params.set("limit", String(ctx.flags.limit));
+  const qs = params.toString();
+  const res = await ctx.api().get(`/api/next${qs ? `?${qs}` : ""}`);
+  const actions = res.actions ?? [];
+  if (ctx.json) {
+    ctx.out(res);
+    return 0;
+  }
+  if (actions.length === 0) {
+    ctx.print("  Nothing needs you.");
+    return 0;
+  }
+  const n = String(actions.length).length;
+  for (const [i, a] of actions.entries()) {
+    const num = String(i + 1).padStart(n);
+    ctx.print(`  ${num}  ${a.title}`);
+    const indent = " ".repeat(n + 5);
+    if (a.why) for (const l of wrap(a.why, 100)) ctx.print(C.dim(`${indent}${l}`));
+    if (a.fix) for (const l of wrap(`Fix: ${a.fix}`, 100)) ctx.print(`${indent}${l}`);
+    if (isHttp(a.href)) ctx.print(`${indent}${a.href}`);
+    if (a.cli) ctx.print(`${indent}${C.dim(a.cli)}`);
+  }
+  return 0;
+}
+
+export async function queue(ctx) {
+  const [sub, arg] = ctx.positionals;
+  if (sub === "retry") {
+    const id = Number(arg);
+    if (!Number.isInteger(id) || id <= 0) throw usage("sprid queue retry <publishId>");
+    const row = await ctx.api().post(`/api/publishes/${id}/retry`);
+    if (ctx.json) ctx.out({ ok: true, publish: row });
+    else ctx.print(`  ${C.ok(OK)} Publish ${id} is back on the queue${row?.scheduledFor ? ` for ${dayTime(row.scheduledFor)}` : ""}.`);
+    return 0;
+  }
+  if (sub) throw usage("sprid queue [retry <publishId>]");
+  const view = await fetchStatus(ctx);
+  const q = view.queue ?? {};
+  if (ctx.json) {
+    ctx.out({ workspaceId: view.workspace?.id ?? null, queue: q, failed: (view.next ?? []).filter((a) => a.kind === "publish-failed") });
+    return 0;
+  }
+  const next = q.nextAt ? `next ${dayTime(q.nextAt)}${q.nextAccount ? ` @${q.nextAccount}` : ""}` : "nothing scheduled";
+  ctx.print(`  ${q.scheduled ?? 0} scheduled · ${next} · ${q.failed7d ?? 0} failed in 7 days`);
+  const failed = (view.next ?? []).filter((a) => a.kind === "publish-failed");
+  for (const f of failed) ctx.print(`  ${C.bad("✗")} ${f.title}  ${C.dim(f.cli)}`);
+  const dry = (view.next ?? []).find((a) => a.kind === "queue-dry");
+  if (dry) ctx.print(`  ${C.warn(NONE)} ${dry.title}  ${C.dim(dry.cli)}`);
+  return 0;
+}
+
+function usage(s) {
+  const e = new Error(`Usage: ${s}`);
+  e.exitCode = 2;
+  return e;
+}

package/src/commands/studio.mjs

@@ -0,0 +1,69 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, resolve, extname } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { UsageError } from '../args.mjs';
+import { localPost } from './post.mjs';
+
+const show = (ctx, result) => ctx.json ? ctx.out(result) : ctx.print(JSON.stringify(result, null, 2));
+async function payload(ctx) {
+  if (typeof ctx.flags.file !== 'string') throw new UsageError('Supply --file <payload.json>.');
+  return JSON.parse(await readFile(resolve(ctx.cwd, ctx.flags.file), 'utf8'));
+}
+export async function remotePost(ctx) {
+  const [verb, ref] = ctx.positionals;
+  const id = ctx.flags.id ?? ref;
+  if (!['create', 'get', 'update', 'deliveries', 'handoff'].includes(verb) && !(verb === 'preview' && ctx.flags.id)) return false;
+  if (verb !== 'create' && !/^[1-9]\d*$/.test(String(id))) throw new UsageError('Supply the positive server post ID. Local preview slugs remain unchanged.');
+  const api = ctx.api();
+  const result = verb === 'create' ? await api.post('/api/studio/posts', await payload(ctx))
+    : verb === 'update' ? await api.patch(`/api/posts/${id}`, await payload(ctx))
+    : verb === 'preview' ? await api.get(`/api/studio/posts/${id}/preview`)
+    : verb === 'deliveries' ? await api.get(`/api/studio/posts/${id}/publications`)
+    // The prompt you paste into an agent. Built on the server so this and the
+    // editor's "Hand off to agent" button print the same string.
+    : verb === 'handoff' ? await api.get(`/api/posts/${id}/handoff`)
+    : await api.get(`/api/posts/${id}`);
+  // Human output is the prompt itself, not a JSON envelope around it: the
+  // point of the command is that its stdout is pasteable.
+  if (verb === 'handoff' && !ctx.json) { ctx.out ? console.log(result.prompt) : console.log(result.prompt); return true; }
+  show(ctx, result); return true;
+}
+export async function capabilities(ctx) { show(ctx, await ctx.api().get('/api/studio/capabilities')); return 0; }
+export async function media(ctx) {
+  const [verb, ...files] = ctx.positionals;
+  if (!verb || verb === 'help' || ctx.flags.help) {
+    show(ctx, { usage: 'sprid media upload <file...> --account <slug> [--request-id UUID] | import --file sources.json | reel --file recipe.json | job <UUID>',
+      local: 'sprid media init|new|build|register|check|push|draft|sync|pull|preview|status|doctor …',
+      guide: 'sprid docs local', aliases: 'Historical local sprid post commands remain supported. Shared server preview uses sprid post preview --id <postId>.' });
+    return 0;
+  }
+  if (verb === 'job') {
+    if (!files[0] || !/^[0-9a-f-]{36}$/i.test(files[0])) throw new UsageError('sprid media job <requestId>');
+    show(ctx, await ctx.api().get(`/api/studio/jobs/${files[0]}`)); return 0;
+  }
+  if (verb === 'import') { show(ctx, await ctx.api().post('/api/studio/assets/import', await payload(ctx))); return 0; }
+  if (verb === 'reel') { show(ctx, await ctx.api().post('/api/studio/reels', await payload(ctx))); return 0; }
+  if (verb !== 'upload') return localPost(ctx);
+  if (!files.length || typeof ctx.flags.account !== 'string') throw new UsageError('sprid media upload <file...> --account <slug> [--request-id UUID]');
+  if (files.length > 20) throw new UsageError('Upload at most 20 files per session.');
+  const requestId = ctx.flags['request-id'] ?? randomUUID();
+  // Print the retry key before the first network call; a disconnect can always resume.
+  ctx.warn(`Upload request ID: ${requestId}`);
+  const api = ctx.api();
+  await api.post('/api/studio/uploads', { account: ctx.flags.account, requestId });
+  const assets = [];
+  for (const [position, file] of files.entries()) {
+    if ((await stat(resolve(ctx.cwd, file))).size > 32 * 1024 * 1024) throw new UsageError(`${file} exceeds 32 MiB. Use the existing local push pipeline for larger videos.`);
+    const bytes = await readFile(resolve(ctx.cwd, file));
+    const contentType = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.mp4': 'video/mp4' }[extname(file).toLowerCase()];
+    if (!contentType) throw new UsageError(`Unsupported media: ${file}`);
+    const slot = await api.post(`/api/studio/uploads/${requestId}/files`, { position, filename: basename(file), contentType, sizeBytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') });
+    if (slot.ready) { assets.push(slot.asset); continue; }
+    const res = await (ctx.fetch ?? fetch)(slot.uploadUrl, { method: 'PUT', headers: slot.headers, body: bytes, redirect: 'error', signal: AbortSignal.timeout(120000) });
+    if (!res.ok) throw new Error(`File ${position + 1} upload failed (${res.status}); retry with --request-id ${requestId}.`);
+    const confirmed = await api.post(`/api/studio/uploads/${requestId}/files/${position}/confirm`, {});
+    assets.push(confirmed.asset);
+  }
+  show(ctx, { requestId, account: ctx.flags.account, assets, next: 'Create a draft with sprid post create --file draft.json. Use kind/id from these assets in their selected order.' });
+  return 0;
+}

package/src/commands/update.mjs

@@ -0,0 +1,69 @@
+import { checkVersion, detectInstallation, autoEnabled, setAuto, performUpdate, installationCommand } from '../updates.mjs';
+import { UsageError } from '../args.mjs';
+
+function validate(ctx, allowed) {
+  if (ctx.positionals.length) throw new UsageError('Unexpected argument. Use sprid help for update syntax.');
+  for (const [key, value] of Object.entries(ctx.flags)) {
+    if (!allowed.includes(key)) throw new UsageError(`Unknown option --${key}. No update attempted.`);
+    if (key !== 'auto' && value !== true) throw new UsageError(`--${key} takes no value. No update attempted.`);
+  }
+}
+
+async function report(ctx, force = false) {
+  const options = { env: ctx.env, ...ctx.updateOptions };
+  const [version, installation] = await Promise.all([
+    checkVersion({ ...options, current: ctx.version, offline: Boolean(ctx.flags.offline), force }),
+    detectInstallation(options),
+  ]);
+  return { ...version, installation, auto: autoEnabled(installation, ctx.env),
+    updateCommand: installation.kind === 'unsupported' ? null : `sprid update${version.requiresApproval ? ' --yes' : ''}`,
+    install: installationCommand(installation, version.recommended) };
+}
+function output(ctx, result) {
+  if (ctx.json) return ctx.out(result);
+  if (result.configured !== undefined) return ctx.print(`Automatic compatible updates: ${result.configured ? 'on' : 'off'} for this installation.`);
+  ctx.print(`Sprid ${result.current}. ${result.check === 'verified' ? `Recommended: ${result.recommended}.` : 'Version check unavailable; ordinary work can continue.'}`);
+  if (result.updated) ctx.print(`Updated to ${result.version}. Start a new CLI process before continuing.`);
+  else if (result.updateAvailable) ctx.warn(`${result.requiresApproval ? 'Potentially breaking update. ' : ''}${result.updateCommand || result.installation.reason}`);
+  else if (result.installation.kind === 'unsupported') ctx.print(result.installation.reason);
+  if (result.skipped) ctx.print(`Update skipped: ${result.skipped}.`);
+}
+export async function doctor(ctx) {
+  validate(ctx, ['json', 'offline', 'apply-updates']);
+  const result = await report(ctx);
+  // This flag marks an explicit between-jobs boundary. Ordinary commands never install.
+  if (ctx.flags['apply-updates'] && result.auto && result.check === 'verified' && result.compatible && result.installation.kind !== 'unsupported') {
+    const { 'apply-updates': _, ...flags } = ctx.flags;
+    return update({ ...ctx, flags: { ...flags, 'auto-run': true } });
+  }
+  output(ctx, result);
+  return 0;
+}
+export async function update(ctx) {
+  validate(ctx, ['json', 'offline', 'auto', 'auto-run', 'check', 'yes']);
+  if (ctx.flags.auto !== undefined) {
+    if (!['on', 'off'].includes(ctx.flags.auto)) throw new UsageError('Use sprid update --auto on|off.');
+    if (ctx.flags['auto-run'] || ctx.flags.check) throw new UsageError('--auto cannot be combined with --auto-run or --check.');
+    const installation = await detectInstallation({ env: ctx.env, ...ctx.updateOptions });
+    setAuto(installation, ctx.flags.auto === 'on', ctx.env);
+    output(ctx, { configured: ctx.flags.auto === 'on', installation });
+    return 0;
+  }
+  const result = await report(ctx, !ctx.flags.check);
+  if (ctx.flags.check) { output(ctx, result); return 0; }
+  if (ctx.flags['auto-run'] && (!result.auto || !result.compatible || result.check !== 'verified' || result.installation.kind === 'unsupported')) {
+    output(ctx, { ...result, skipped: !result.auto ? 'automatic updates are off' : 'no verified compatible update' }); return 0;
+  }
+  if (result.check !== 'verified') throw new Error('Cannot verify the recommended version. No update attempted; retry when the registry is available.');
+  if (!result.updateAvailable) { output(ctx, result); return 0; }
+  if (result.installation.kind === 'unsupported') throw new UsageError(result.installation.reason);
+  if (result.requiresApproval && !ctx.flags.yes) throw new UsageError('Potentially breaking update. Review the release, then run sprid update --yes to approve it.');
+  const updated = await performUpdate(result.installation, result.recommended, { env: ctx.env, ...ctx.updateOptions });
+  output(ctx, { ...result, ...updated });
+  return 0;
+}
+
+export async function notifyUpdate(ctx) {
+  const version = await checkVersion({ current: ctx.version, env: ctx.env });
+  if (version.check === 'verified' && version.updateAvailable) ctx.warn(`Sprid ${version.recommended} is available${version.requiresApproval ? ' (potentially breaking)' : ''}. Run sprid doctor for update instructions.`);
+}

package/src/creds.mjs

@@ -0,0 +1,126 @@
+// Credentials: where the token lives and how every command finds it.
+//
+//   SPRID_PAT      wins. An agent, a CI job or a workspace-pinned batch session
+//                  sets it and the login file is never consulted.
+//   the file       ~/.sprid/credentials.json, written by `sprid login`, 0600 in
+//                  a 0700 dir. { apiUrl, token, tokenId, workspace, email? }.
+//   SPRID_URL      overrides the API base wherever the token came from.
+//
+// Nothing else reads the token. The CLI is the one trusted local process that
+// opens key files, so a secret never has to pass through an agent's context.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { apiUrl as validateApiUrl } from './endpoint.mjs';
+
+export const DEFAULT_API_URL = "https://api.sprid.studio";
+
+export function credentialsPath(env = process.env) {
+  if (env.SPRID_CREDENTIALS_FILE) return env.SPRID_CREDENTIALS_FILE;
+  return join(env.HOME || homedir(), ".sprid", "credentials.json");
+}
+
+export function secretsPath(slug, env = process.env) {
+  if (env.SPRID_SECRETS_FILE) return env.SPRID_SECRETS_FILE;
+  if (!/^[a-z0-9-]+$/.test(slug)) throw new Error('Invalid app slug.');
+  return join(env.HOME || homedir(), ".sprid", "secrets", `${slug}.json`);
+}
+
+export function readCredentials(env = process.env) {
+  const p = credentialsPath(env);
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    // The file may hold only a `workspace` (written by `sprid use` for an
+    // SPRID_PAT user); a token is not required for it to count.
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCredentials(creds, env = process.env) {
+  const p = credentialsPath(env);
+  const dir = dirname(p);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    // Windows has no POSIX modes; the write below still lands.
+  }
+  writeFileSync(p, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(p, 0o600);
+  } catch {
+    // see above
+  }
+  return p;
+}
+
+export function deleteCredentials(env = process.env) {
+  const p = credentialsPath(env);
+  if (existsSync(p)) rmSync(p);
+  return p;
+}
+
+/** True when the file is readable by nobody but its owner (POSIX only; true elsewhere). */
+export function credentialsModeOk(env = process.env) {
+  const p = credentialsPath(env);
+  if (!existsSync(p)) return true;
+  if (process.platform === "win32") return true;
+  return (statSync(p).mode & 0o077) === 0;
+}
+
+export class NotLoggedIn extends Error {
+  constructor() {
+    super("Not logged in. Run `sprid login`, or set SPRID_PAT to a token from Settings → Tokens.");
+    this.name = "NotLoggedIn";
+    this.exitCode = 1;
+  }
+}
+
+/**
+ * The token, its source, and the API base.
+ * `flags.api` is `sprid login --api`; for every other command SPRID_URL is the
+ * only override, so a stored dev login is not silently sent to production.
+ */
+export function resolveAuth(env = process.env, flags = {}) {
+  const file = readCredentials(env);
+  const envToken = env.SPRID_PAT && env.SPRID_PAT.trim();
+  const apiUrl = validateApiUrl(env.SPRID_URL || flags.api || (envToken ? DEFAULT_API_URL : file?.apiUrl) || DEFAULT_API_URL);
+  if (envToken) {
+    // The token is the environment's; the chosen workspace (`sprid use`) may still be the file's.
+    return { token: envToken, source: "env", apiUrl, workspace: file?.workspace ?? null, tokenId: null, email: null };
+  }
+  if (file && typeof file.token === "string") {
+    return {
+      token: file.token,
+      source: "file",
+      apiUrl,
+      workspace: file.workspace ?? null,
+      tokenId: file.tokenId ?? null,
+      email: file.email ?? null,
+    };
+  }
+  throw new NotLoggedIn();
+}
+
+/** app.sprid.studio for api.sprid.studio; SPRID_APP_URL wins; a dev API keeps its own origin. */
+export function appUrlFor(apiUrl, env = process.env) {
+  if (env.SPRID_APP_URL) return stripSlash(env.SPRID_APP_URL);
+  try {
+    const u = new URL(apiUrl);
+    if (u.hostname.startsWith("api.")) {
+      u.hostname = "app." + u.hostname.slice(4);
+      return stripSlash(u.origin);
+    }
+    return stripSlash(u.origin);
+  } catch {
+    return "https://app.sprid.studio";
+  }
+}
+
+export function stripSlash(s) {
+  return String(s).replace(/\/+$/, "");
+}