@ratio-app/cli 0.1.1

package/dist/commands/app/link.js

@@ -0,0 +1,1120 @@
+// src/commands/app/link.ts
+import { createInterface } from "readline/promises";
+import fs3 from "fs";
+import { Flags as Flags2 } from "@oclif/core";
+import { z as z2 } from "zod";
+
+// src/lib/credentials/clock.ts
+var SystemClock = class {
+  now() {
+    return Date.now();
+  }
+};
+
+// src/lib/credentials/path.ts
+import os from "os";
+import path from "path";
+function snapshotPathEnv() {
+  const snapshot = {};
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
+  if (xdgConfigHome !== void 0) {
+    snapshot.XDG_CONFIG_HOME = xdgConfigHome;
+  }
+  const appData = process.env["APPDATA"];
+  if (appData !== void 0) {
+    snapshot.APPDATA = appData;
+  }
+  return snapshot;
+}
+function defaultCredentialsPath(platform, homedir, env) {
+  const resolvedPlatform = platform ?? process.platform;
+  const resolvedHome = homedir ?? os.homedir();
+  const resolvedEnv = env ?? snapshotPathEnv();
+  if (resolvedPlatform === "win32") {
+    const appData = resolvedEnv.APPDATA;
+    const base2 = appData !== void 0 && appData !== "" ? appData : path.win32.join(resolvedHome, "AppData", "Roaming");
+    return path.win32.join(base2, "ratio", "credentials");
+  }
+  const xdgConfigHome = resolvedEnv.XDG_CONFIG_HOME;
+  const base = typeof xdgConfigHome === "string" && xdgConfigHome !== "" ? xdgConfigHome : path.posix.join(resolvedHome, ".config");
+  return path.posix.join(base, "ratio", "credentials");
+}
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var NotLoggedInError = class extends RatioCLIError {
+  constructor(message, hint = "Run 'ratio auth login' to sign in.") {
+    super({ code: "NOT_LOGGED_IN", exitCode: 3, message, hint });
+  }
+};
+var TokenExpiredError = class extends RatioCLIError {
+  constructor(message, hint = "Run 'ratio auth login' to refresh your session.") {
+    super({ code: "TOKEN_EXPIRED", exitCode: 3, message, hint });
+  }
+};
+var NetworkError = class extends RatioCLIError {
+  constructor(message, hint = "Check your network and retry.") {
+    super({ code: "NETWORK_ERROR", exitCode: 5, message, hint });
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+function isRatioCLIError(err) {
+  return err instanceof RatioCLIError;
+}
+
+// src/lib/credentials/refresher.ts
+var NotImplementedRefresher = class {
+  async refresh(refreshToken) {
+    void refreshToken;
+    throw new NotLoggedInError(
+      "Token refresh is not available yet in this CLI version."
+    );
+  }
+};
+
+// src/lib/credentials/store.ts
+import crypto from "crypto";
+import fs from "fs";
+import { dirname } from "path";
+
+// src/lib/credentials/schema.ts
+import { z } from "zod";
+var identitySchema = z.object({
+  developerId: z.string(),
+  email: z.string(),
+  // Token-derived fields captured at login. Optional (additive) so files
+  // written before these fields existed still validate as version 1.
+  merchantId: z.string().optional(),
+  scopes: z.array(z.string()).optional()
+}).strict();
+var profileSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresAt: z.string().datetime({ offset: true }),
+  identity: identitySchema,
+  obtainedAt: z.string().datetime({ offset: true })
+}).strict();
+var developerSessionSchema = z.object({
+  jwt: z.string(),
+  developerId: z.string(),
+  email: z.string(),
+  expiresAt: z.string().datetime({ offset: true }),
+  obtainedAt: z.string().datetime({ offset: true })
+}).strict();
+var credentialsSchema = z.object({
+  version: z.literal(1),
+  server: z.string(),
+  clientId: z.string(),
+  profiles: z.record(z.string(), profileSchema),
+  // Optional cached developer session. Additive so files written before
+  // this field existed still validate as version 1.
+  developer: developerSessionSchema.optional()
+}).strict();
+function parseCredentials(input) {
+  if (typeof input === "object" && input !== null && "version" in input) {
+    const version = input.version;
+    if (version !== 1) {
+      const label = typeof version === "number" ? String(version) : "unknown";
+      throw new ValidationError(
+        `credentials file version ${label} is unsupported by this CLI \u2014 upgrade the CLI or sign in again`
+      );
+    }
+  }
+  const result = credentialsSchema.safeParse(input);
+  if (!result.success) {
+    throw new ValidationError(
+      "credentials file schema mismatch \u2014 expected v1 shape"
+    );
+  }
+  return result.data;
+}
+
+// src/lib/credentials/store.ts
+var REFRESH_WINDOW_MS = 3e5;
+var ENV_TOKEN_VAR = "RATIO_API_TOKEN";
+var ENV_DEVELOPER_TOKEN_VAR = "RATIO_DEVELOPER_TOKEN";
+function hasErrnoCode(err, code) {
+  return err instanceof Error && err.code === code;
+}
+var FileCredentialStore = class {
+  filePath;
+  clock;
+  refresher;
+  envReader;
+  platform;
+  constructor(opts) {
+    this.filePath = opts?.filePath ?? defaultCredentialsPath();
+    this.clock = opts?.clock ?? new SystemClock();
+    this.refresher = opts?.refresher ?? new NotImplementedRefresher();
+    this.envReader = opts?.envReader ?? (() => process.env);
+    this.platform = opts?.platform ?? process.platform;
+  }
+  async load() {
+    this.reapplyFileModeIfDrifted();
+    let raw;
+    try {
+      raw = fs.readFileSync(this.filePath, "utf8");
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        throw new NotLoggedInError("You are not signed in.");
+      }
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new ValidationError(
+        'credentials file is not valid JSON \u2014 run "ratio auth login" to reset'
+      );
+    }
+    return parseCredentials(parsed);
+  }
+  async save(creds) {
+    const dir = dirname(this.filePath);
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    if (this.platform !== "win32") {
+      fs.chmodSync(dir, 448);
+    }
+    const tmpPath = `${this.filePath}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
+    try {
+      fs.writeFileSync(tmpPath, JSON.stringify(creds, null, 2), {
+        mode: 384
+      });
+      fs.renameSync(tmpPath, this.filePath);
+    } catch (err) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+      }
+      throw err;
+    }
+    if (this.platform !== "win32") {
+      fs.chmodSync(this.filePath, 384);
+    }
+  }
+  async clear() {
+    try {
+      fs.unlinkSync(this.filePath);
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        return;
+      }
+      throw err;
+    }
+  }
+  async getValidAccessToken(profileName) {
+    const envToken = this.envReader()[ENV_TOKEN_VAR];
+    if (typeof envToken === "string" && envToken.length > 0) {
+      return envToken;
+    }
+    const creds = await this.load();
+    const name = profileName ?? "default";
+    const profile = creds.profiles[name];
+    if (profile === void 0) {
+      throw new NotLoggedInError("You are not signed in.");
+    }
+    const msUntilExpiry = new Date(profile.expiresAt).getTime() - this.clock.now();
+    if (msUntilExpiry < REFRESH_WINDOW_MS) {
+      return this.refreshAndPersist(creds, name, profile);
+    }
+    return profile.accessToken;
+  }
+  async getValidDeveloperToken() {
+    const envToken = this.envReader()[ENV_DEVELOPER_TOKEN_VAR];
+    if (typeof envToken === "string" && envToken.length > 0) {
+      return envToken;
+    }
+    let creds;
+    try {
+      creds = await this.load();
+    } catch (err) {
+      if (err instanceof NotLoggedInError) {
+        throw new NotLoggedInError("Developer signin required.");
+      }
+      throw err;
+    }
+    const session = creds.developer;
+    if (session === void 0) {
+      throw new NotLoggedInError("Developer signin required.");
+    }
+    const msUntilExpiry = new Date(session.expiresAt).getTime() - this.clock.now();
+    if (msUntilExpiry < REFRESH_WINDOW_MS) {
+      throw new NotLoggedInError("Developer signin required.");
+    }
+    return session.jwt;
+  }
+  async saveDeveloperSession(session) {
+    let creds;
+    try {
+      creds = await this.load();
+    } catch (err) {
+      if (err instanceof NotLoggedInError) {
+        creds = { version: 1, server: "", clientId: "", profiles: {} };
+      } else {
+        throw err;
+      }
+    }
+    const updated = {
+      ...creds,
+      developer: session
+    };
+    await this.save(updated);
+  }
+  /**
+   * Exchange the profile's refresh token for a fresh token set, merge it
+   * into the loaded credentials (preserving every other profile), persist
+   * atomically, and return the new access token. A refresher failure is
+   * wrapped in TokenExpiredError; the underlying message is deliberately
+   * discarded so a secret can never leak through the error surface.
+   */
+  async refreshAndPersist(creds, name, profile) {
+    let refreshed;
+    try {
+      refreshed = await this.refresher.refresh(profile.refreshToken);
+    } catch {
+      throw new TokenExpiredError(
+        "Your session has expired and could not be refreshed."
+      );
+    }
+    const updated = {
+      ...creds,
+      profiles: {
+        ...creds.profiles,
+        [name]: {
+          ...profile,
+          accessToken: refreshed.accessToken,
+          refreshToken: refreshed.refreshToken,
+          expiresAt: refreshed.expiresAt
+        }
+      }
+    };
+    await this.save(updated);
+    return refreshed.accessToken;
+  }
+  /**
+   * POSIX-only startup permission check: if the file exists with a mode
+   * other than 0600, re-apply 0600 and emit a warning to stderr. Never
+   * runs on Windows (stat modes there do not map to POSIX bits and chmod
+   * must not be called). Missing file is NOT an error here — load()
+   * reports it as NotLoggedInError.
+   */
+  reapplyFileModeIfDrifted() {
+    if (this.platform === "win32") {
+      return;
+    }
+    let stat;
+    try {
+      stat = fs.statSync(this.filePath);
+    } catch (err) {
+      if (hasErrnoCode(err, "ENOENT")) {
+        return;
+      }
+      throw err;
+    }
+    const mode = stat.mode & 511;
+    if (mode !== 384) {
+      fs.chmodSync(this.filePath, 384);
+      process.stderr.write(
+        `[warn] credentials file permissions were 0o${mode.toString(8)}; corrected to 0600.
+`
+      );
+    }
+  }
+};
+
+// src/lib/manifest/write-client-id.ts
+import crypto2 from "crypto";
+import fs2 from "fs";
+import path2 from "path";
+var MANIFEST_FILE_NAME = "ratio.config.jsonc";
+var CLIENT_ID_ROW = /^(\s*"clientId"\s*:\s*")([^"]*)("\s*,?)/m;
+var APP_NAME_ROW = /^\s*"appName"\s*:\s*"([^"]*)"/m;
+async function writeClientId(cwd, clientId) {
+  const filePath = path2.join(cwd, MANIFEST_FILE_NAME);
+  let content;
+  try {
+    content = fs2.readFileSync(filePath, "utf8");
+  } catch {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} not found in ${cwd}.`,
+      `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`
+    );
+  }
+  const appNameMatch = APP_NAME_ROW.exec(content);
+  const appName = appNameMatch?.[1];
+  const rowMatch = CLIENT_ID_ROW.exec(content);
+  if (rowMatch === null) {
+    throw new ValidationError(
+      `${MANIFEST_FILE_NAME} has no top-level "clientId" entry.`,
+      'Restore the "clientId" line from the app template, then re-run.'
+    );
+  }
+  const existing = rowMatch[2] ?? "";
+  const base = {
+    written: false,
+    path: filePath,
+    ...appName !== void 0 ? { appName } : {}
+  };
+  if (existing === clientId) {
+    return base;
+  }
+  const updated = content.replace(
+    CLIENT_ID_ROW,
+    (_row, open, _old, close) => `${open}${clientId}${close}`
+  );
+  const tmpPath = `${filePath}.${process.pid}.${crypto2.randomBytes(8).toString("hex")}.tmp`;
+  try {
+    fs2.writeFileSync(tmpPath, updated, { mode: 384 });
+    fs2.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs2.unlinkSync(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+  if (process.platform !== "win32") {
+    fs2.chmodSync(filePath, 384);
+  }
+  return {
+    ...base,
+    written: true,
+    ...existing !== "" ? { previousClientId: existing } : {}
+  };
+}
+
+// src/lib/ratio-command.ts
+import { Command, Errors } from "@oclif/core";
+
+// src/lib/render-error.ts
+function isOclifParserError(err) {
+  return err instanceof Error && "parse" in err && err.parse !== null && err.parse !== void 0;
+}
+function buildErrorEnvelope(code, message, hint, docsUrl) {
+  const obj = { ok: false, code, message };
+  if (hint !== void 0) obj["hint"] = hint;
+  if (docsUrl !== void 0) obj["docsUrl"] = docsUrl;
+  return JSON.stringify(obj) + "\n";
+}
+function renderError(input) {
+  const { err, verbose, json } = input;
+  if (isRatioCLIError(err)) {
+    const ratioErr = err;
+    if (ratioErr.exitCode === 0) {
+      if (json) {
+        return {
+          stdout: JSON.stringify({ ok: true, data: null }) + "\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+      return {
+        stdout: ratioErr.message + "\n",
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    let stderrLines = `${ratioErr.code}: ${ratioErr.message}
+`;
+    if (ratioErr.hint !== void 0) stderrLines += `${ratioErr.hint}
+`;
+    if (ratioErr.docsUrl !== void 0) stderrLines += `${ratioErr.docsUrl}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),
+        stderr: verbose && ratioErr.stack ? ratioErr.stack + "\n" : "",
+        exitCode: ratioErr.exitCode
+      };
+    }
+    if (verbose && ratioErr.stack) {
+      stderrLines += ratioErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrLines, exitCode: ratioErr.exitCode };
+  }
+  if (isOclifParserError(err)) {
+    const parserErr = err;
+    const msg = parserErr.message || "Unknown parse error";
+    const coercedErr = new ValidationError(msg);
+    let stderrText2 = `${coercedErr.code}: ${msg}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(coercedErr.code, msg),
+        stderr: verbose && parserErr.stack ? parserErr.stack + "\n" : "",
+        exitCode: 8
+      };
+    }
+    if (verbose && parserErr.stack) {
+      stderrText2 += parserErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrText2, exitCode: 8 };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error ? err.stack : void 0;
+  const stderrPrefix = `INTERNAL: ${message}
+`;
+  if (json) {
+    return {
+      stdout: buildErrorEnvelope("INTERNAL", message),
+      stderr: verbose && stack ? stack + "\n" : "",
+      exitCode: 1
+    };
+  }
+  let stderrText = stderrPrefix;
+  if (verbose && stack) {
+    stderrText += stack + "\n";
+  }
+  return { stdout: "", stderr: stderrText, exitCode: 1 };
+}
+
+// src/lib/ratio-command.ts
+var RatioCommand = class extends Command {
+  _getRenderFlags() {
+    const argv = this.argv;
+    return {
+      verbose: argv.includes("--verbose"),
+      json: argv.includes("--json")
+    };
+  }
+  async catch(err) {
+    const { verbose, json } = this._getRenderFlags();
+    const output = renderError({ err, verbose, json });
+    if (output.stdout) process.stdout.write(output.stdout);
+    if (output.stderr) process.stderr.write(output.stderr);
+    if (output.exitCode === 0) {
+      throw new Errors.ExitError(0);
+    }
+    err.skipOclifErrorHandling = true;
+    err.oclif = { exit: output.exitCode };
+    throw err;
+  }
+};
+
+// src/lib/verbose-flag.ts
+import { Flags } from "@oclif/core";
+var verboseFlag = {
+  verbose: Flags.boolean({
+    description: "Show diagnostic detail: HTTP status/timing lines for auth requests (stderr) and stack traces for internal errors."
+  })
+};
+var jsonFlag = {
+  json: Flags.boolean({
+    description: "Emit machine-readable JSON on stdout."
+  })
+};
+
+// src/commands/app/link.ts
+var REQUEST_TIMEOUT_MS = 1e4;
+var DEFAULT_LINK_SERVER = "https://api.ratio.app";
+var SERVER_ENV_VAR = "RATIO_SERVER";
+var DEVELOPER_TOKEN_ENV_VAR = "RATIO_DEVELOPER_TOKEN";
+var DEVELOPER_SESSION_TTL_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_APP_DESCRIPTION = "A Ratio app scaffolded via ratio-cli.";
+var DEFAULT_CATEGORY_SLUG = "general";
+var MANIFEST_APP_NAME_ROW = /^\s*"appName"\s*:\s*"([^"]*)"/m;
+var MANIFEST_CLIENT_ID_ROW = /^(\s*"clientId"\s*:\s*")([^"]*)("\s*,?)/m;
+var signinResponseSchema = z2.object({
+  "accessToken": z2.string().min(1),
+  "developer": z2.object({
+    "id": z2.string().min(1),
+    "email": z2.string()
+  }).passthrough()
+});
+var applicationSummarySchema = z2.object({
+  "id": z2.string().min(1),
+  "name": z2.string(),
+  "clientId": z2.string().nullish()
+}).passthrough();
+var listApplicationsResponseSchema = z2.object({
+  "data": z2.object({
+    "applications": z2.array(applicationSummarySchema)
+  }).passthrough()
+}).passthrough();
+var createApplicationResponseSchema = z2.object({
+  "data": z2.object({
+    "id": z2.string().min(1),
+    "clientId": z2.string().nullish()
+  }).passthrough()
+}).passthrough();
+var credentialsResponseSchema = z2.object({
+  "data": z2.object({
+    "clientId": z2.string().min(1)
+  }).passthrough()
+}).passthrough();
+function computeSessionExpiresAt(obtainedAtIso) {
+  return new Date(
+    new Date(obtainedAtIso).getTime() + DEVELOPER_SESSION_TTL_MS
+  ).toISOString();
+}
+function defaultLinkPrompter() {
+  return {
+    async text(question) {
+      const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr
+      });
+      try {
+        return (await rl.question(question)).trim();
+      } finally {
+        rl.close();
+      }
+    },
+    async masked(question) {
+      return new Promise((resolvePromise, rejectPromise) => {
+        const stdin = process.stdin;
+        process.stderr.write(question);
+        stdin.setRawMode?.(true);
+        stdin.resume();
+        let value = "";
+        const finish = (err) => {
+          stdin.off("data", onData);
+          stdin.setRawMode?.(false);
+          stdin.pause();
+          process.stderr.write("\n");
+          if (err !== void 0) {
+            rejectPromise(err);
+          } else {
+            resolvePromise(value);
+          }
+        };
+        const onData = (chunk) => {
+          for (const ch of chunk.toString("utf8")) {
+            if (ch === "\r" || ch === "\n") {
+              finish();
+              return;
+            }
+            if (ch === "") {
+              finish(new ValidationError("Sign-in cancelled."));
+              return;
+            }
+            if (ch === "\x7F" || ch === "\b") {
+              value = value.slice(0, -1);
+              continue;
+            }
+            if (ch >= " ") {
+              value += ch;
+            }
+          }
+        };
+        stdin.on("data", onData);
+      });
+    }
+  };
+}
+var SessionRejectedError = class extends Error {
+  constructor() {
+    super("session rejected");
+  }
+};
+async function httpJson(url, pathLabel, init, trace) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const method = init.method ?? "GET";
+  const started = Date.now();
+  let response;
+  try {
+    response = await fetch(url, { ...init, signal: controller.signal });
+  } catch {
+    throw new NetworkError("Could not reach the Ratio platform.");
+  } finally {
+    clearTimeout(timer);
+  }
+  trace(`${method} ${pathLabel} \u2192 ${response.status} (${Date.now() - started}ms)`);
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    body = void 0;
+  }
+  return { status: response.status, body };
+}
+function serverMessage(body) {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const message = body.message;
+    if (typeof message === "string" && message.length > 0) {
+      return message;
+    }
+  }
+  return void 0;
+}
+var AppLink = class _AppLink extends RatioCommand {
+  static description = "Link the app in the current directory to a Ratio app registration (sign in, pick or create the app, and write its clientId into ratio.config.jsonc).";
+  static examples = [
+    "<%= config.bin %> app link",
+    "<%= config.bin %> app link --email dev@example.com",
+    "<%= config.bin %> app link --app-id 4f9d2c31-8a6b-4f2e-9c1d-3e5a7b9d0f12 --json",
+    "<%= config.bin %> app link --client-id ratio_ci_1234"
+  ];
+  static flags = {
+    ...verboseFlag,
+    ...jsonFlag,
+    email: Flags2.string({
+      description: "Developer email for sign-in (prompted when omitted)."
+    }),
+    "client-id": Flags2.string({
+      description: "Write this clientId directly into ratio.config.jsonc without contacting the server."
+    }),
+    "app-id": Flags2.string({
+      description: "Attach to an existing app by id; its clientId is fetched and written."
+    }),
+    category: Flags2.string({
+      description: `Category slug used when creating a new app (default: ${DEFAULT_CATEGORY_SLUG}).`
+    })
+  };
+  // ── Seams: overridable in tests; defaults hit the real process. ──────────
+  writeOut = (chunk) => {
+    process.stdout.write(chunk);
+  };
+  writeErr = (chunk) => {
+    process.stderr.write(chunk);
+  };
+  makeCredentialStore = () => new FileCredentialStore();
+  prompter = defaultLinkPrompter();
+  isInteractive = () => process.stdin.isTTY === true;
+  envReader = () => process.env;
+  getCwd = () => process.cwd();
+  async run() {
+    const { flags } = await this.parse(_AppLink);
+    const jsonMode = flags.json === true;
+    const verbose = flags.verbose === true;
+    const trace = (message) => {
+      if (verbose) {
+        this.writeErr(`[verbose] ${message}
+`);
+      }
+    };
+    const cwd = this.getCwd();
+    const manifest = this.readManifest(cwd);
+    const directClientId = flags["client-id"];
+    if (directClientId !== void 0 && directClientId !== "") {
+      await this.writeAndReport(cwd, directClientId, manifest.appName, jsonMode, trace);
+      return;
+    }
+    const store = this.makeCredentialStore();
+    const server = await this.resolveServer(store);
+    const bearer = await this.acquireBearer(store, server, flags.email, trace);
+    let clientId;
+    let appName = manifest.appName;
+    const appId = flags["app-id"];
+    if (appId !== void 0 && appId !== "") {
+      clientId = await this.withAuthRetry(
+        store,
+        server,
+        bearer,
+        trace,
+        (token) => this.fetchAppClientId(server, token, appId, trace)
+      );
+    } else {
+      const picked = await this.pickOrCreateApp(
+        store,
+        server,
+        bearer,
+        manifest.appName,
+        flags.category,
+        trace
+      );
+      clientId = picked.clientId;
+      appName = picked.appName ?? manifest.appName;
+    }
+    await this.writeAndReport(cwd, clientId, appName, jsonMode, trace);
+  }
+  // ── Manifest ──────────────────────────────────────────────────────────────
+  readManifest(cwd) {
+    let content;
+    try {
+      content = fs3.readFileSync(`${cwd}/${MANIFEST_FILE_NAME}`, "utf8");
+    } catch {
+      throw new ValidationError(
+        `${MANIFEST_FILE_NAME} not found in ${cwd}.`,
+        `Run this command from the app's repo root; ${MANIFEST_FILE_NAME} not found in ${cwd}.`
+      );
+    }
+    if (!MANIFEST_CLIENT_ID_ROW.test(content)) {
+      throw new ValidationError(
+        `${MANIFEST_FILE_NAME} has no top-level "clientId" entry.`,
+        'Restore the "clientId" line from the app template, then re-run.'
+      );
+    }
+    const appName = MANIFEST_APP_NAME_ROW.exec(content)?.[1];
+    return appName !== void 0 ? { appName } : {};
+  }
+  async writeAndReport(cwd, clientId, appName, jsonMode, trace) {
+    const result = await writeClientId(cwd, clientId);
+    if (result.previousClientId !== void 0) {
+      this.writeErr(
+        `Warning: replacing existing clientId ${result.previousClientId} with ${clientId}
+`
+      );
+    }
+    if (result.written) {
+      const bytes = fs3.statSync(result.path).size;
+      trace(`write ${MANIFEST_FILE_NAME} (${bytes}b)`);
+    }
+    const displayName = result.appName ?? appName ?? clientId;
+    if (jsonMode) {
+      const data = { "clientId": clientId };
+      if (result.appName !== void 0) {
+        data["appName"] = result.appName;
+      } else if (appName !== void 0) {
+        data["appName"] = appName;
+      }
+      data["written"] = result.written;
+      data["path"] = result.path;
+      this.writeOut(`${JSON.stringify({ ok: true, data })}
+`);
+      return;
+    }
+    if (result.written) {
+      this.writeOut(
+        `Linked to app '${displayName}' (clientId: ${clientId}). Wrote to ${result.path}.
+`
+      );
+    } else {
+      this.writeOut(
+        `Already linked to '${displayName}' (clientId: ${clientId}). No changes.
+`
+      );
+    }
+  }
+  // ── Server + bearer acquisition ───────────────────────────────────────────
+  async resolveServer(store) {
+    try {
+      const creds = await store.load();
+      if (typeof creds.server === "string" && creds.server.length > 0) {
+        return creds.server;
+      }
+    } catch {
+    }
+    const envServer = this.envReader()[SERVER_ENV_VAR];
+    if (typeof envServer === "string" && envServer.length > 0) {
+      return envServer;
+    }
+    return DEFAULT_LINK_SERVER;
+  }
+  async acquireBearer(store, server, emailFlag, trace) {
+    const envToken = this.envReader()[DEVELOPER_TOKEN_ENV_VAR];
+    if (typeof envToken === "string" && envToken.length > 0) {
+      return { token: envToken, source: "env" };
+    }
+    try {
+      const token = await store.getValidDeveloperToken();
+      const state = { token, source: "file" };
+      let cachedEmail;
+      try {
+        const creds = await store.load();
+        cachedEmail = creds.developer?.email;
+      } catch {
+      }
+      const email = emailFlag ?? cachedEmail;
+      if (email !== void 0) {
+        state.email = email;
+      }
+      return state;
+    } catch (err) {
+      if (!(err instanceof NotLoggedInError)) {
+        throw err;
+      }
+    }
+    return this.signinInteractive(store, server, emailFlag, trace);
+  }
+  async signinInteractive(store, server, knownEmail, trace) {
+    if (!this.isInteractive()) {
+      throw new ValidationError(
+        "Developer sign-in needs an interactive terminal.",
+        "Non-interactive shell \u2014 set RATIO_DEVELOPER_TOKEN or run interactively."
+      );
+    }
+    const email = knownEmail !== void 0 && knownEmail !== "" ? knownEmail : await this.prompter.text("Developer email: ");
+    const password = await this.prompter.masked("Developer password: ");
+    const session = await this.signin(server, email, password, trace);
+    await store.saveDeveloperSession(session);
+    return { token: session.jwt, source: "signin", email };
+  }
+  async signin(server, email, password, trace) {
+    const base = server.replace(/\/+$/, "");
+    const { status, body } = await httpJson(
+      `${base}/api/v1/developers/signin`,
+      "/developers/signin",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ "email": email, "password": password })
+      },
+      trace
+    );
+    if (status === 401) {
+      throw new NotLoggedInError(
+        "Invalid credentials or account not verified. Sign in via the developer portal to verify your email if you have not done so."
+      );
+    }
+    if (status === 429) {
+      throw new NetworkError(
+        "Too many signin attempts. Wait 60 seconds or set RATIO_DEVELOPER_TOKEN for CI usage."
+      );
+    }
+    if (status < 200 || status >= 300) {
+      throw new NetworkError(
+        `The server had a problem processing your request (status: ${status}); try again.`
+      );
+    }
+    const parsed = signinResponseSchema.safeParse(body);
+    if (!parsed.success) {
+      throw new NetworkError("The server response was not the expected shape.");
+    }
+    const obtainedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      jwt: parsed.data.accessToken,
+      developerId: parsed.data.developer.id,
+      email: parsed.data.developer.email,
+      expiresAt: computeSessionExpiresAt(obtainedAt),
+      obtainedAt
+    };
+  }
+  /**
+   * Run one app-management call; on a 401 re-prompt the password ONCE
+   * (email already known when possible), retry ONCE, and fail typed on a
+   * second 401. Unattended runs (env token / non-TTY) fail typed directly.
+   */
+  async withAuthRetry(store, server, bearer, trace, call) {
+    const expired = () => new NotLoggedInError(
+      "Your developer session expired.",
+      "Your developer session expired. Sign in again by re-running `ratio app link`."
+    );
+    try {
+      return await call(bearer.token);
+    } catch (err) {
+      if (!(err instanceof SessionRejectedError)) {
+        throw err;
+      }
+      if (bearer.source === "env" || !this.isInteractive()) {
+        throw expired();
+      }
+      const email = bearer.email !== void 0 && bearer.email !== "" ? bearer.email : await this.prompter.text("Developer email: ");
+      const password = await this.prompter.masked("Developer password: ");
+      const session = await this.signin(server, email, password, trace);
+      await store.saveDeveloperSession(session);
+      bearer.token = session.jwt;
+      bearer.source = "signin";
+      bearer.email = email;
+      try {
+        return await call(bearer.token);
+      } catch (err2) {
+        if (err2 instanceof SessionRejectedError) {
+          throw expired();
+        }
+        throw err2;
+      }
+    }
+  }
+  // ── App-management calls ──────────────────────────────────────────────────
+  async fetchAppClientId(server, token, appId, trace) {
+    const base = server.replace(/\/+$/, "");
+    const { status, body } = await httpJson(
+      `${base}/api/v1/applications/${appId}/credentials`,
+      `/applications/${appId}/credentials`,
+      { method: "GET", headers: { Authorization: `Bearer ${token}` } },
+      trace
+    );
+    if (status === 401) {
+      throw new SessionRejectedError();
+    }
+    if (status === 404) {
+      throw new ValidationError("Selected app not found. It may have been deleted.");
+    }
+    if (status < 200 || status >= 300) {
+      throw new NetworkError(
+        `The server had a problem processing your request (status: ${status}); try again.`
+      );
+    }
+    const parsed = credentialsResponseSchema.safeParse(body);
+    if (!parsed.success) {
+      throw new NetworkError("The server response was not the expected shape.");
+    }
+    return parsed.data.data.clientId;
+  }
+  async listApplications(server, token, trace) {
+    const base = server.replace(/\/+$/, "");
+    const { status, body } = await httpJson(
+      `${base}/api/v1/applications`,
+      "/applications",
+      { method: "GET", headers: { Authorization: `Bearer ${token}` } },
+      trace
+    );
+    if (status === 401) {
+      throw new SessionRejectedError();
+    }
+    if (status < 200 || status >= 300) {
+      throw new NetworkError(
+        `The server had a problem processing your request (status: ${status}); try again.`
+      );
+    }
+    const parsed = listApplicationsResponseSchema.safeParse(body);
+    if (!parsed.success) {
+      throw new NetworkError("The server response was not the expected shape.");
+    }
+    return parsed.data.data.applications;
+  }
+  async createApplication(server, token, payload, trace) {
+    const base = server.replace(/\/+$/, "");
+    const { status, body } = await httpJson(
+      `${base}/api/v1/applications`,
+      "/applications",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          "name": payload.name,
+          "description": payload.description,
+          "categoryIds": payload.categoryIds
+        })
+      },
+      trace
+    );
+    if (status === 401) {
+      throw new SessionRejectedError();
+    }
+    if (status === 400) {
+      throw new ValidationError(
+        serverMessage(body) ?? "The server rejected the request.",
+        "Category resolution failed \u2014 visit the portal to seed categories or pass --category <slug> with a known slug."
+      );
+    }
+    if (status < 200 || status >= 300) {
+      throw new NetworkError(
+        `The server had a problem processing your request (status: ${status}); try again.`
+      );
+    }
+    const parsed = createApplicationResponseSchema.safeParse(body);
+    if (!parsed.success) {
+      throw new NetworkError("The server response was not the expected shape.");
+    }
+    const clientId = parsed.data.data.clientId;
+    return {
+      id: parsed.data.data.id,
+      ...typeof clientId === "string" && clientId.length > 0 ? { clientId } : {}
+    };
+  }
+  // ── Interactive pick / create flow ────────────────────────────────────────
+  async pickOrCreateApp(store, server, bearer, manifestAppName, categoryFlag, trace) {
+    if (!this.isInteractive()) {
+      throw new ValidationError(
+        "Choosing an app needs an interactive terminal.",
+        "Non-interactive shell \u2014 pass --app-id <id> or --client-id <x>."
+      );
+    }
+    const apps = await this.withAuthRetry(
+      store,
+      server,
+      bearer,
+      trace,
+      (token) => this.listApplications(server, token, trace)
+    );
+    this.writeErr("0. Create new app\n");
+    apps.forEach((app, index) => {
+      const shortId = app.id.slice(0, 8);
+      const shortClientId = typeof app.clientId === "string" && app.clientId.length > 0 ? app.clientId.slice(0, 8) : "-";
+      this.writeErr(
+        `${index + 1}. ${app.name} (id: ${shortId}, clientId: ${shortClientId})
+`
+      );
+    });
+    const answer = await this.prompter.text("Select a number: ");
+    const selection = Number.parseInt(answer, 10);
+    if (Number.isNaN(selection) || selection < 0 || selection > apps.length || String(selection) !== answer.trim()) {
+      throw new ValidationError(
+        `Invalid selection: enter a number between 0 and ${apps.length}.`
+      );
+    }
+    if (selection === 0) {
+      return this.createFlow(store, server, bearer, manifestAppName, categoryFlag, trace);
+    }
+    const chosen = apps[selection - 1];
+    if (chosen === void 0) {
+      throw new ValidationError(
+        `Invalid selection: enter a number between 0 and ${apps.length}.`
+      );
+    }
+    const clientId = await this.withAuthRetry(
+      store,
+      server,
+      bearer,
+      trace,
+      (token) => this.fetchAppClientId(server, token, chosen.id, trace)
+    );
+    return { clientId, appName: chosen.name };
+  }
+  async createFlow(store, server, bearer, manifestAppName, categoryFlag, trace) {
+    const nameDefault = manifestAppName !== void 0 && manifestAppName !== "" ? manifestAppName : void 0;
+    const nameAnswer = await this.prompter.text(
+      nameDefault !== void 0 ? `App name [${nameDefault}]: ` : "App name: "
+    );
+    const name = nameAnswer !== "" ? nameAnswer : nameDefault ?? "";
+    if (name === "") {
+      throw new ValidationError("An app name is required.");
+    }
+    const descriptionAnswer = await this.prompter.text(
+      `Description [${DEFAULT_APP_DESCRIPTION}]: `
+    );
+    const description = descriptionAnswer !== "" ? descriptionAnswer : DEFAULT_APP_DESCRIPTION;
+    const categoryIds = [
+      categoryFlag !== void 0 && categoryFlag !== "" ? categoryFlag : DEFAULT_CATEGORY_SLUG
+    ];
+    const created = await this.withAuthRetry(
+      store,
+      server,
+      bearer,
+      trace,
+      (token) => this.createApplication(server, token, { name, description, categoryIds }, trace)
+    );
+    if (created.clientId !== void 0) {
+      return { clientId: created.clientId, appName: name };
+    }
+    const clientId = await this.withAuthRetry(
+      store,
+      server,
+      bearer,
+      trace,
+      (token) => this.fetchAppClientId(server, token, created.id, trace)
+    );
+    return { clientId, appName: name };
+  }
+};
+export {
+  DEFAULT_APP_DESCRIPTION,
+  DEFAULT_CATEGORY_SLUG,
+  DEFAULT_LINK_SERVER,
+  DEVELOPER_SESSION_TTL_MS,
+  REQUEST_TIMEOUT_MS,
+  computeSessionExpiresAt,
+  AppLink as default,
+  defaultLinkPrompter
+};
+//# sourceMappingURL=link.js.map