@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/api/commands.ts

@@ -0,0 +1,330 @@
+// `vfrey login`, `logout`, `whoami`, and the doctor account line.
+import os from "node:os";
+import { ApiClient, ApiFailure, clean, type FetchLike } from "./client.js";
+import { apiHost, ApiConfigError, resolveApiUrl } from "./config.js";
+import { deleteToken, loadStoredToken, loadToken, readHint, saveHint, saveToken, type CredentialDeps, type Runner } from "./credentials.js";
+import { formatUserCode, type MeResponse, type OrgSummary } from "./types.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface ApiIo {
+  env: Env;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  homedir?: string;
+  platform?: NodeJS.Platform;
+  run?: Runner;
+  fetch?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** Opens a URL in the browser. Defaults to the `open` package. */
+  openUrl?: (url: string) => Promise<void>;
+  timeoutMs?: number;
+}
+
+const NOT_LIVE_FIX = "free features work without an account. If you run your own vfrey server, set VFREY_API_URL or pass --api <url>.";
+
+function creds(io: ApiIo): CredentialDeps {
+  return { env: io.env, homedir: io.homedir ?? os.homedir(), ...(io.platform ? { platform: io.platform } : {}), ...(io.run ? { run: io.run } : {}) };
+}
+
+function refuse(io: ApiIo, message: string, fix: string): number {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+}
+
+function failure(io: ApiIo, error: unknown): number {
+  if (error instanceof ApiFailure || error instanceof ApiConfigError) return refuse(io, error.message, error.fix);
+  return refuse(io, error instanceof Error ? clean(error.message) : "Something went wrong.", "run `npx vfrey doctor` and check the line above.");
+}
+
+function client(io: ApiIo, base: string, token?: string | null): ApiClient {
+  return new ApiClient({ baseUrl: base, token: token ?? null, ...(io.fetch ? { fetch: io.fetch } : {}), ...(io.timeoutMs ? { timeoutMs: io.timeoutMs } : {}) });
+}
+
+/** The flag value after `--api`, or `--api=URL`. */
+function flagValue(args: string[], name: string): string | null | undefined {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    if (arg === name) return args[i + 1] && !args[i + 1]!.startsWith("--") ? args[i + 1]! : null;
+    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+  }
+  return undefined;
+}
+
+/** Parses the flags these commands share. Returns an error text for an unknown or malformed flag. */
+function parse(args: string[], allowed: string[], valued: string[]): { flags: Set<string>; api?: string; error?: string } {
+  const flags = new Set<string>();
+  let api: string | undefined;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    const name = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    if (!allowed.includes(name) && !valued.includes(name)) return { flags, error: `Unknown option "${arg}".` };
+    if (valued.includes(name)) {
+      const value = flagValue(args, name);
+      if (!value) return { flags, error: `${name} needs a value.` };
+      api = value;
+      if (!arg.includes("=")) i += 1;
+    } else flags.add(name);
+  }
+  return { flags, ...(api ? { api } : {}) };
+}
+
+function resolve(io: ApiIo, api?: string): string | null {
+  return resolveApiUrl(io.env, api ?? null);
+}
+
+function notLive(io: ApiIo): number {
+  return refuse(io, "vfrey accounts are not live yet.", NOT_LIVE_FIX);
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((done) => setTimeout(done, ms));
+
+async function defaultOpen(url: string): Promise<void> {
+  const { default: open } = await import("open");
+  await open(url);
+}
+
+function browserUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function runLogin(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, ["--no-browser"], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey login [--api URL] [--no-browser].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const api = client(io, base);
+    const sleep = io.sleep ?? defaultSleep;
+    const now = io.now ?? Date.now;
+
+    const code = await api.deviceCode();
+    const link = browserUrl(code.verification_uri_complete);
+    if (!link) return refuse(io, "The server sent a sign-in link that is not a web address.", "check the API address and try again.");
+    io.stdout(`Open ${link} and confirm the code ${formatUserCode(code.user_code)}\n`);
+    if (!parsed.flags.has("--no-browser") && !io.env.VFREY_NO_BROWSER) {
+      try {
+        await (io.openUrl ?? defaultOpen)(link);
+      } catch {
+        /* the link is printed: the person can open it themselves */
+      }
+    }
+
+    const deadline = now() + (Number.isFinite(code.expires_in) ? code.expires_in : 600) * 1000;
+    let intervalSec = Number.isFinite(code.interval) && code.interval >= 0 ? code.interval : 5;
+    let networkErrors = 0;
+    for (;;) {
+      await sleep(intervalSec * 1000);
+      if (now() >= deadline) return refuse(io, "The sign-in code expired.", "run `npx vfrey login` again.");
+      let answer;
+      try {
+        answer = await api.deviceToken(code.device_code);
+        networkErrors = 0;
+      } catch (error) {
+        if (error instanceof ApiFailure && error.status === undefined && (networkErrors += 1) < 3) continue;
+        if (error instanceof ApiFailure && error.status === 429) {
+          intervalSec += 5;
+          continue;
+        }
+        throw error;
+      }
+      if ("access_token" in answer) {
+        const org = clean(answer.org.name);
+        let plan = "";
+        try {
+          plan = clean((await client(io, base, answer.access_token).me()).plan);
+        } catch {
+          /* signed in all the same; the plan shows on whoami */
+        }
+        let saved;
+        try {
+          saved = saveToken(host, answer.access_token, { org, plan }, creds(io));
+        } catch {
+          return refuse(io, "Signed in, but the token could not be saved on this machine.", "make the vfrey home folder writable (VFREY_HOME), then run `npx vfrey login` again.");
+        }
+        io.stdout(`✓ Signed in to ${org}${plan ? ` (${plan})` : ""}\n`);
+        if (saved.where === "file") io.stdout(`Token saved in ${saved.file} (readable only by you).\n`);
+        if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell and overrides the token you just saved.\n");
+        return 0;
+      }
+      if (answer.error === "slow_down") intervalSec += 5;
+      else if (answer.error === "access_denied") return refuse(io, "Sign-in was denied in the browser.", "run `npx vfrey login` again and choose Approve.");
+      else if (answer.error === "expired_token") return refuse(io, "The sign-in code expired.", "run `npx vfrey login` again.");
+    }
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+export async function runLogout(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, [], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey logout [--api URL].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) {
+      io.stdout("✓ Not signed in (vfrey accounts are not live yet).\n");
+      return 0;
+    }
+    const host = apiHost(base);
+    const stored = loadStoredToken(host, creds(io));
+    if (!stored) {
+      io.stdout(`✓ Not signed in to ${host}.\n`);
+      if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell; unset it to stop using that token.\n");
+      return 0;
+    }
+    try {
+      await client(io, base, stored.token).revokeCurrentToken();
+    } catch (error) {
+      // 401 means the server already treats the token as revoked. Anything else leaves it live: say so, still sign out here.
+      if (!(error instanceof ApiFailure && error.status === 401)) {
+        io.stderr(`! Could not revoke the token on ${host} (${error instanceof ApiFailure ? error.message : "unknown error"}). It stays valid there until you revoke it at ${base}/settings/tokens.\n`);
+      }
+    }
+    deleteToken(host, creds(io));
+    io.stdout(`✓ Signed out of ${host}\n`);
+    if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell; unset it to stop using that token.\n");
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+function formatMe(me: MeResponse): string {
+  const lines = [
+    `✓ Signed in as ${clean(me.user.email)}`,
+    `Org: ${clean(me.org.name)} (${clean(me.org.role)})`,
+    `Plan: ${clean(me.plan)}`,
+    `Entitlements: ${Object.entries(me.entitlements).map(([name, on]) => `${clean(name)} ${on ? "yes" : "no"}`).join(", ")}`,
+  ];
+  if (me.credits) {
+    const soon = me.credits.expiringSoon > 0 ? ` (${me.credits.expiringSoon} expiring soon)` : "";
+    lines.push(`Credits: ${me.credits.balance}${soon}`);
+  }
+  const meters = Object.entries(me.usage ?? {});
+  if (meters.length > 0) {
+    lines.push("Usage this month:");
+    for (const [meter, reading] of meters) {
+      lines.push(`  ${clean(meter)}: ${reading.used} of ${reading.limit ?? "unlimited"}, resets ${clean(reading.resetsAt)}`);
+    }
+  }
+  if (me.upgradeUrl) lines.push(`Upgrade or manage: ${clean(me.upgradeUrl)}`);
+  return lines.join("\n") + "\n";
+}
+
+export async function runWhoami(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, ["--json"], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey whoami [--json] [--api URL].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const found = loadToken(host, creds(io));
+    if (!found) return refuse(io, "You are not signed in.", "run `npx vfrey login`.");
+    const me = await client(io, base, found.token).me();
+    if (found.source !== "env") saveHint(host, { org: clean(me.org.name), plan: clean(me.plan) }, creds(io));
+    io.stdout(parsed.flags.has("--json") ? JSON.stringify(me, null, 2) + "\n" : formatMe(me));
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+const ORG_USAGE = "usage: npx vfrey org list [--json] [--api URL] | npx vfrey org use ORG [--api URL].";
+
+/** The org named by an id or an exact name (any case). Null when none match; "many" when a name is not unique. */
+function pickOrg(orgs: OrgSummary[], wanted: string): OrgSummary | null | "many" {
+  const byId = orgs.find((o) => o.id === wanted);
+  if (byId) return byId;
+  const byName = orgs.filter((o) => o.name.toLowerCase() === wanted.toLowerCase());
+  return byName.length === 1 ? byName[0]! : byName.length > 1 ? "many" : null;
+}
+
+/**
+ * `vfrey org list` and `vfrey org use ORG` (spec 019 A). A token is bound to one org for life, so `use` asks the server
+ * to trade the stored token for one bound to the chosen org (the server checks membership and revokes the old one),
+ * then stores the new token. A token from VFREY_TOKEN is never replaced: it stays what the shell says it is.
+ */
+export async function runOrg(args: string[], io: ApiIo): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub !== "list" && sub !== "use") return refuse(io, sub ? `Unknown org command "${clean(sub)}".` : "Say what to do with orgs.", ORG_USAGE);
+  const positional: string[] = [];
+  const flagArgs: string[] = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]!;
+    if (arg.startsWith("--")) {
+      flagArgs.push(arg);
+      if (arg === "--api" && rest[i + 1] !== undefined) flagArgs.push(rest[(i += 1)]!);
+    } else positional.push(arg);
+  }
+  const parsed = parse(flagArgs, sub === "list" ? ["--json"] : [], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, ORG_USAGE);
+  if (positional.length > (sub === "use" ? 1 : 0)) return refuse(io, `Unexpected "${clean(positional[sub === "use" ? 1 : 0])}".`, ORG_USAGE);
+  const wanted = sub === "use" ? positional[0] : undefined;
+  if (sub === "use" && !wanted) return refuse(io, "Say which org to use.", "run `npx vfrey org list`, then `npx vfrey org use ORG` with its name or id.");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const found = loadToken(host, creds(io));
+    if (!found) return refuse(io, "You are not signed in.", "run `npx vfrey login`.");
+    const api = client(io, base, found.token);
+    const { orgs } = await api.orgs();
+    if (sub === "list") {
+      if (parsed.flags.has("--json")) io.stdout(JSON.stringify({ orgs }, null, 2) + "\n");
+      else io.stdout(orgs.map((o) => `${o.current ? "*" : " "} ${clean(o.name)} (${clean(o.role)})  ${clean(o.id)}`).join("\n") + "\n");
+      return 0;
+    }
+    const target = pickOrg(orgs, wanted!);
+    if (target === "many") return refuse(io, `More than one org is named "${clean(wanted)}".`, "use the id from `npx vfrey org list`.");
+    if (!target) return refuse(io, `You are not in an org called "${clean(wanted)}".`, "run `npx vfrey org list` to see yours.");
+    if (target.current) {
+      io.stdout(`✓ Already using ${clean(target.name)} (${clean(target.role)})\n`);
+      return 0;
+    }
+    if (found.source === "env") return refuse(io, "VFREY_TOKEN is set, and that token is bound to one org.", "unset VFREY_TOKEN, run `npx vfrey login`, then `npx vfrey org use` again.");
+    let switched;
+    try {
+      switched = await api.switchOrg(target.id);
+    } catch (error) {
+      if (error instanceof ApiFailure && error.status === 403) return refuse(io, "This token is fixed to its org.", `run \`npx vfrey login\` while ${clean(target.name)} is selected in the vfrey console.`);
+      throw error;
+    }
+    let plan = "";
+    try {
+      plan = clean((await client(io, base, switched.access_token).me()).plan);
+    } catch {
+      /* switched all the same; the plan shows on whoami */
+    }
+    try {
+      saveToken(host, switched.access_token, { org: clean(switched.org.name), plan }, creds(io));
+    } catch {
+      return refuse(io, "Switched, but the new token could not be saved on this machine.", "make the vfrey home folder writable (VFREY_HOME), then run `npx vfrey login`.");
+    }
+    io.stdout(`✓ Now using ${clean(switched.org.name)} (${clean(switched.org.role)})\n`);
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+/** The doctor line. Local only (no network, no Keychain), and never a failure. */
+export function accountLine(env: Env, homedir: string = os.homedir()): string {
+  const none = "not signed in (free features work without it)";
+  try {
+    const base = resolveApiUrl(env, null);
+    if (!base) return none;
+    const host = apiHost(base);
+    const hint = readHint(host, { env, homedir });
+    if (env.VFREY_TOKEN?.trim()) return hint ? `signed in as ${hint.org} (${hint.plan}) with VFREY_TOKEN` : "signed in with VFREY_TOKEN";
+    return hint ? `signed in as ${hint.org} (${hint.plan})` : none;
+  } catch {
+    return none;
+  }
+}

package/src/api/config.ts

@@ -0,0 +1,34 @@
+// Where the vfrey accounts server is. Set DEFAULT_API_URL at release, when the console is deployed.
+
+type Env = Record<string, string | undefined>;
+
+/** The release-time default. Unset until the server is live: `login` then refuses without any network call. */
+export const DEFAULT_API_URL: string | null = null;
+
+export class ApiConfigError extends Error {
+  constructor(message: string, readonly fix: string) {
+    super(message);
+  }
+}
+
+/** `--api URL`, else VFREY_API_URL, else the release default. Null means accounts are not live. */
+export function resolveApiUrl(env: Env, flag?: string | null): string | null {
+  const raw = (flag ?? env.VFREY_API_URL ?? DEFAULT_API_URL ?? "").trim();
+  if (!raw) return null;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ApiConfigError(`"${raw}" is not a URL.`, "pass a full address such as https://vfrey.example.com with --api or VFREY_API_URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new ApiConfigError(`${url.origin} is not https. vfrey sends your token only over https (or to this machine).`, "use an https:// address.");
+  }
+  return url.origin;
+}
+
+/** The key a token is stored under: the API's host (with port when it has one). */
+export function apiHost(base: string): string {
+  return new URL(base).host;
+}