envspot 0.1.0

package/dist/init-flow.js

@@ -0,0 +1,411 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { clearStoredCredential, setStoredToken } from "./auth-store.js";
+import { cliApiError } from "./cli-api-error.js";
+import { apiBase } from "./config.js";
+import { approveUrl, pollForBearer, startDeviceFlow } from "./device-flow.js";
+import { discoverEnvFiles, parseEnvFile } from "./env-parse.js";
+import { CliError, ERR, ttyRequired } from "./errors.js";
+import { apiUrl, backoffTransport, fetchWithCliHeaders, parseJsonSafely, rethrowTransport, } from "./http.js";
+import { acquireInitLock, releaseInitLock } from "./init-lock.js";
+import { ensureGitignorePatterns } from "./link-flow.js";
+import { openApproveUrl } from "./open-browser.js";
+import * as out from "./output.js";
+import { writeLinkConfig } from "./paths.js";
+import { deriveProjectName, findPackageJsons, findProjectRoot, } from "./project-detect.js";
+import { executeRun, parseRunTailArgs } from "./run-handler.js";
+const NAME_MAX = 120;
+const SLUG_MAX = 40;
+/** Server appends `-N` on a slug collision, so the collision base is slug[:38]. */
+const SLUG_BASE_LEN = SLUG_MAX - 2;
+const PREVIEW_MASK = "••••••••";
+/** Mirrors the server's reserved project slugs (this package can't import server
+ *  code). The create endpoint rejects these, and the rejection lands AFTER the
+ *  user approves in-browser — so catch them here before the slug is ever sent. */
+const RESERVED_SLUGS = new Set(["new", "_dev", "archived"]);
+// ── Pure helpers ──────────────────────────────────────────────────────────
+function stripControl(s) {
+    return [...s].filter((c) => c.charCodeAt(0) >= 32).join("");
+}
+/** Coerce a derived name + slug into something the create endpoint accepts:
+ *  control-free name ≤120 chars, kebab-case slug ≤40 chars, no trailing dash. */
+export function clampForServer(rawName, rawSlug) {
+    const projectName = stripControl(rawName).trim().slice(0, NAME_MAX).trim() || "project";
+    const slug = rawSlug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX)
+        .replace(/-+$/, "") || "project";
+    const projectSlug = RESERVED_SLUGS.has(slug) ? `${slug}-app` : slug;
+    return { projectName, projectSlug };
+}
+/** Decide how to resolve the project root when several manifests are present.
+ *  A pinned `--cwd` or a single manifest needs no choice; `--yes` must never
+ *  silently pick one of several. */
+export function chooseProjectRoot(input) {
+    if (input.packageJsons.length <= 1 || input.cwdPinned)
+        return { kind: "single" };
+    if (input.yes)
+        return { kind: "ambiguous-yes" };
+    return { kind: "prompt", choices: input.packageJsons };
+}
+/** Find the just-created project in the org list. The approve step can suffix
+ *  the slug on collision (`api`→`api-2`) without telling the CLI, so resolution
+ *  must consider the whole `base-N` family — and refuse to guess when the exact
+ *  slug AND a suffixed sibling both exist (a real collision). */
+export function resolveCreatedProject(projects, postedSlug) {
+    const exact = projects.find((p) => p.slug === postedSlug);
+    const base = postedSlug.slice(0, SLUG_BASE_LEN).replace(/[^a-z0-9-]/g, "");
+    const familyRe = new RegExp(`^${base}-[2-9]$`);
+    const suffixed = projects.filter((p) => familyRe.test(p.slug));
+    if (exact && suffixed.length === 0)
+        return { kind: "unique", project: exact };
+    if (exact)
+        return { kind: "ambiguous", candidates: [exact, ...suffixed] };
+    if (suffixed.length === 1)
+        return { kind: "unique", project: suffixed[0] };
+    if (suffixed.length > 1)
+        return { kind: "ambiguous", candidates: suffixed };
+    return { kind: "none" };
+}
+/** Key names with masked values, capped to `maxShown` plus a `+ N more` tail. */
+export function redactedPreview(keys, maxShown = 4) {
+    const lines = keys.slice(0, maxShown).map((k) => `  ▸ ${k}=${PREVIEW_MASK}`);
+    if (keys.length > maxShown)
+        lines.push(`  + ${keys.length - maxShown} more`);
+    return lines;
+}
+/** Merge per-file key lists; later files win on a duplicate key. */
+export function mergeEnvKeys(files) {
+    const map = new Map();
+    for (const file of files)
+        for (const { key, value } of file)
+            map.set(key, value);
+    return [...map].map(([key, value]) => ({ key, value }));
+}
+export function summarizeIgnored(ignored) {
+    const n = ignored.length;
+    if (n === 0)
+        return "";
+    return `${n} line${n === 1 ? "" : "s"} ignored`;
+}
+/** True if `baseUrl` answers within `timeoutMs` (any HTTP status counts —
+ *  only a DNS/connect/timeout failure means offline). */
+export async function probeReachable(baseUrl, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 2000);
+    try {
+        await fetchImpl(baseUrl, { method: "GET", signal: ctrl.signal });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const isNo = (answer) => answer.trim().toLowerCase().startsWith("n");
+const isYes = (answer) => answer.trim().toLowerCase().startsWith("y");
+function relativeTime(iso, nowMs) {
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return "just now";
+    const s = Math.max(0, Math.round((nowMs - t) / 1000));
+    return s < 60 ? `${s}s ago` : `${Math.round(s / 60)}m ago`;
+}
+/** Ask for a 1-based list pick and return its 0-based index, or throw E0050. */
+async function promptChoice(prompt, count) {
+    const n = Number((await prompt("Enter number: ")).trim());
+    if (!Number.isInteger(n) || n < 1 || n > count) {
+        throw new CliError(ERR.INVALID_INPUT, "Invalid selection.");
+    }
+    return n - 1;
+}
+function readPackageScripts(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return pkg.scripts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Run a request through backoff, mapping transport faults to a typed E0003. */
+async function sendWithBackoff(exec) {
+    try {
+        return await backoffTransport(exec);
+    }
+    catch (e) {
+        rethrowTransport(e);
+    }
+}
+async function fetchOrgProjects(token) {
+    const res = await sendWithBackoff(async () => fetchWithCliHeaders(apiUrl("/api/cli/projects"), { method: "GET" }, token));
+    const { json } = await parseJsonSafely(res);
+    if (!res.ok)
+        throw await cliApiError(res.status, json);
+    const projects = json?.projects;
+    return Array.isArray(projects) ? projects : [];
+}
+async function postInitContext(body) {
+    const res = await sendWithBackoff(async () => fetchWithCliHeaders(apiUrl("/api/cli/init/context"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }));
+    if (res.ok)
+        return;
+    if (res.status === 429) {
+        throw new CliError(ERR.RATE_LIMITED, "Rate limit hit.", "Try again shortly.");
+    }
+    throw new CliError(ERR.UNEXPECTED, `Couldn't register the project for approval (${res.status}).`, "Run: envspot init");
+}
+async function importSecrets(token, projectId, secrets) {
+    const res = await sendWithBackoff(async () => fetchWithCliHeaders(apiUrl("/api/cli/secrets"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            project: projectId,
+            environment: "development",
+            secrets,
+        }),
+    }, token));
+    if (!res.ok) {
+        const { json } = await parseJsonSafely(res);
+        throw await cliApiError(res.status, json, projectId);
+    }
+}
+/** Resolve the effective project root, prompting on monorepo ambiguity. */
+async function resolveRoot(opts, deps) {
+    const start = resolve(opts.cwd ?? process.cwd());
+    const root = findProjectRoot(start);
+    if (!root) {
+        throw new CliError(ERR.INVALID_INPUT, "No project detected.", "Run inside a project directory (package.json, go.mod, .git, …) or pass --cwd <path>.");
+    }
+    const packageJsons = findPackageJsons(root);
+    const choice = chooseProjectRoot({
+        packageJsons,
+        cwdPinned: opts.cwd != null,
+        yes: opts.yes === true,
+    });
+    if (choice.kind === "single")
+        return root;
+    if (choice.kind === "ambiguous-yes") {
+        throw new CliError(ERR.MONOREPO_AMBIGUOUS, `Multiple projects detected in ${root}; can't pick one with --yes.`, "Pass --cwd <path> to pin a project, or drop --yes and pick interactively.");
+    }
+    out.step("Multiple projects detected. Which one are you initializing?");
+    choice.choices.forEach((p, i) => out.info(`  ${i + 1}. ${p}`));
+    const idx = await promptChoice(deps.prompt, choice.choices.length);
+    return join(root, dirname(choice.choices[idx]));
+}
+/** Collect the secrets to import from the discovered `.env*` files. */
+async function collectImport(root, opts, deps) {
+    if (opts.import === false)
+        return [];
+    const files = discoverEnvFiles(root).flatMap((name) => {
+        try {
+            return [
+                { name, parsed: parseEnvFile(readFileSync(join(root, name), "utf8")) },
+            ];
+        }
+        catch {
+            out.warn(`Skipped ${name} (could not read it).`);
+            return [];
+        }
+    });
+    if (files.length === 0)
+        return [];
+    const ignored = files.flatMap((f) => f.parsed.ignored);
+    if (opts.strict && ignored.length > 0) {
+        out.warn(`${ignored.length} .env line(s) could not be parsed:`);
+        for (const f of files) {
+            for (const ig of f.parsed.ignored) {
+                out.info(`  ${f.name}:${ig.lineNumber} — ${ig.reason}`);
+            }
+        }
+        if (opts.yes) {
+            throw new CliError(ERR.INVALID_INPUT, "Unparsed .env lines under --strict.", "Fix the lines, or drop --strict.");
+        }
+        if (!isYes(await deps.prompt("Continue anyway? [y/N] "))) {
+            throw new CliError(ERR.INVALID_INPUT, "Aborted due to unparsed .env lines.");
+        }
+    }
+    else if (ignored.length > 0) {
+        out.warn(`${summarizeIgnored(ignored)} — re-run with --strict to inspect.`);
+    }
+    const accepted = [];
+    for (const f of files) {
+        if (f.parsed.keys.length === 0)
+            continue;
+        if (opts.yes) {
+            accepted.push(f.parsed.keys);
+            continue;
+        }
+        out.step(`Found ${f.name} with ${f.parsed.keys.length} key(s):`);
+        for (const line of redactedPreview(f.parsed.keys.map((k) => k.key))) {
+            out.info(line);
+        }
+        if (!isNo(await deps.prompt(`Import ${f.name} to envspot? [Y/n] `))) {
+            accepted.push(f.parsed.keys);
+        }
+    }
+    // Later files win on a shared key; surface it so a .env.production value
+    // doesn't silently shadow a .env one without the user noticing.
+    const seen = new Set();
+    const collided = new Set();
+    for (const { key } of accepted.flat()) {
+        if (seen.has(key))
+            collided.add(key);
+        else
+            seen.add(key);
+    }
+    if (collided.size > 0) {
+        out.warn(`Defined in multiple files (last wins): ${[...collided].join(", ")}`);
+    }
+    return mergeEnvKeys(accepted);
+}
+/** Locate the just-created project. Prefers the projectId the poll handed back
+ *  (deterministic); falls back to slug resolution when the server didn't supply
+ *  one (the narrow redeem-before-write race, or a create that failed). */
+export function selectCreatedProject(projects, target) {
+    if (target.projectId) {
+        const wantedId = target.projectId.toLowerCase();
+        const byId = projects.find((p) => p.id.toLowerCase() === wantedId);
+        if (byId)
+            return { kind: "unique", project: byId };
+    }
+    return resolveCreatedProject(projects, target.slug);
+}
+/** Resolve the created project, prompting to disambiguate a slug collision when
+ *  the id path didn't apply. */
+async function pickCreatedProject(token, target, opts, deps) {
+    const projects = await fetchOrgProjects(token);
+    const resolved = selectCreatedProject(projects, target);
+    if (resolved.kind === "unique")
+        return resolved.project;
+    if (resolved.kind === "none") {
+        throw new CliError(ERR.UNEXPECTED, "Approved this device, but the project wasn't created server-side.", "You're logged in. Check the dashboard, then run `envspot link` — or re-run `envspot init`.");
+    }
+    // Ambiguous: a name collision produced suffixed siblings. Never guess which
+    // one to import secrets into.
+    if (opts.yes || !deps.isTTY) {
+        throw new CliError(ERR.UNEXPECTED, "The project name collided with an existing project; can't tell which is new.", "Run: envspot link to finish linking, then envspot set/run.");
+    }
+    out.step("Project name collided. Which project did you just create?");
+    resolved.candidates.forEach((p, i) => out.info(`  ${i + 1}. ${p.name} (${p.slug})`));
+    const idx = await promptChoice(deps.prompt, resolved.candidates.length);
+    return resolved.candidates[idx];
+}
+export async function runInit(opts, depsIn) {
+    const isTTY = depsIn?.isTTY ?? process.stdout.isTTY === true;
+    const interactive = isTTY && opts.yes !== true && !depsIn?.prompt;
+    const rl = interactive ? readline.createInterface({ input, output }) : null;
+    const deps = {
+        isTTY,
+        now: depsIn?.now ?? (() => Date.now()),
+        probeFetch: depsIn?.probeFetch ?? fetch,
+        openBrowser: depsIn?.openBrowser ?? openApproveUrl,
+        prompt: depsIn?.prompt ??
+            (rl
+                ? (q) => rl.question(q)
+                : async () => {
+                    throw new CliError(ERR.TTY_REQUIRED, "No interactive terminal.");
+                }),
+    };
+    let lockedRoot = null;
+    try {
+        // CI / non-interactive needs --yes; otherwise prompts would hang.
+        if (!isTTY && opts.yes !== true) {
+            throw ttyRequired("envspot init", "Pass --yes for non-interactive use, or mint a headless token for CI.");
+        }
+        if (!(await probeReachable(apiBase(), { fetchImpl: deps.probeFetch }))) {
+            throw new CliError(ERR.OFFLINE, `Could not reach ${apiBase()}.`, "Check your network. envspot init needs a browser for device authorization.");
+        }
+        const root = await resolveRoot(opts, deps);
+        const lock = acquireInitLock(root);
+        if (!lock.ok) {
+            throw new CliError(ERR.INIT_LOCKED, `Another envspot init is running here (PID ${lock.pid}, started ${relativeTime(lock.startedAt, deps.now())}).`, "Wait for it to finish, or delete .envspot.json.lock if it's stale.");
+        }
+        lockedRoot = root;
+        out.step(`Bootstrapping envspot in ${root}`);
+        const derived = deriveProjectName(root);
+        const { projectName, projectSlug } = clampForServer(derived.name, derived.slug);
+        out.info(`Project: ${projectName} (slug: ${projectSlug})`);
+        if (opts.yes !== true &&
+            isNo(await deps.prompt("Is this correct? [Y/n] "))) {
+            out.info("Cancelled.");
+            return 0;
+        }
+        const secrets = await collectImport(root, opts, deps);
+        const { userCode, deviceCode } = await startDeviceFlow();
+        await postInitContext({ userCode, projectName, projectSlug });
+        const url = approveUrl(userCode, { from: "cli-init" });
+        out.step("Opening browser to authorize this device…");
+        out.info(`  If it didn't open, visit: ${url}`);
+        out.info(`  Code: ${userCode}`);
+        deps.openBrowser(url);
+        const { bearerToken, projectId } = await pollForBearer(deviceCode, {
+            now: deps.now,
+        });
+        await clearStoredCredential();
+        await setStoredToken(bearerToken.trim());
+        const project = await pickCreatedProject(bearerToken, { projectId, slug: projectSlug }, opts, deps);
+        writeLinkConfig(root, { projectId: project.id, environment: "dev" });
+        const added = ensureGitignorePatterns(root, [".envspot.json", ".envspot"]);
+        out.success(`Linked ${project.name} (${project.slug}) · development`);
+        if (added.length > 0)
+            out.step(`Added ${added.join(", ")} to .gitignore`);
+        if (secrets.length > 0) {
+            await importSecrets(bearerToken, project.id, secrets);
+            out.success(`Imported ${secrets.length} secret(s) to development.`);
+        }
+        return await maybeRunDevServer(root, projectName, opts, deps);
+    }
+    finally {
+        if (lockedRoot)
+            releaseInitLock(lockedRoot);
+        rl?.close();
+    }
+}
+/** Offer to start the dev server, closing the terminal-to-running loop. */
+async function maybeRunDevServer(root, projectName, opts, deps) {
+    if (opts.run === false || !existsSync(join(root, "package.json"))) {
+        out.success("Ready. Run: envspot run -- <your start command>");
+        return 0;
+    }
+    const scripts = readPackageScripts(root);
+    let child = null;
+    if (scripts.start)
+        child = ["npm", "start"];
+    else if (scripts.dev)
+        child = ["npm", "run", "dev"];
+    if (!child) {
+        out.success("Ready. Run: envspot run -- <your start command>");
+        return 0;
+    }
+    // Only auto-run at an interactive terminal. Under --yes in CI (no TTY) this
+    // would spawn a foreground dev server that never exits, hanging the job.
+    const cmd = `envspot run -- ${child.join(" ")}`;
+    if (!deps.isTTY) {
+        out.success(`Ready. Run: ${cmd}`);
+        return 0;
+    }
+    const runNow = opts.yes === true ||
+        !isNo(await deps.prompt(`Start your dev server now? ${cmd} [Y/n] `));
+    if (!runNow) {
+        out.success(`Ready. Run: ${cmd}`);
+        return 0;
+    }
+    const parsed = parseRunTailArgs(["--", ...child]);
+    if (!parsed.ok) {
+        out.success(`Ready. Run: ${cmd}`);
+        return 0;
+    }
+    out.step(`Starting ${projectName}: ${cmd}`);
+    return executeRun(parsed);
+}

package/dist/init-lock.js

@@ -0,0 +1,64 @@
+import { closeSync, openSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { join } from "node:path";
+export const INIT_LOCK_FILE = ".envspot.json.lock";
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // ESRCH = no such process (dead); EPERM = exists but not signalable (alive).
+        return e.code === "EPERM";
+    }
+}
+function readLock(path) {
+    try {
+        const h = JSON.parse(readFileSync(path, "utf8"));
+        return typeof h.pid === "number"
+            ? { pid: h.pid, startedAt: h.startedAt ?? "" }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Acquire the per-directory init lock via an atomic exclusive create (`wx`).
+ * On contention, refuses when a live process owns it; reclaims a stale lock
+ * (dead pid or corrupt file) and retries.
+ */
+export function acquireInitLock(root) {
+    const path = join(root, INIT_LOCK_FILE);
+    for (let pass = 0; pass < 2; pass++) {
+        try {
+            const fd = openSync(path, "wx");
+            writeSync(fd, JSON.stringify({
+                pid: process.pid,
+                startedAt: new Date().toISOString(),
+            }));
+            closeSync(fd);
+            return { ok: true };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        const held = readLock(path);
+        if (held && isPidAlive(held.pid)) {
+            return { ok: false, pid: held.pid, startedAt: held.startedAt };
+        }
+        rmSync(path, { force: true }); // stale or corrupt → reclaim, then retry
+    }
+    const held = readLock(path);
+    return held
+        ? { ok: false, pid: held.pid, startedAt: held.startedAt }
+        : { ok: true };
+}
+export function releaseInitLock(root) {
+    try {
+        rmSync(join(root, INIT_LOCK_FILE), { force: true });
+    }
+    catch {
+        /* noop */
+    }
+}

package/dist/link-flow.js

@@ -0,0 +1,140 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import readline from "node:readline/promises";
+import { basename, join } from "node:path";
+import { stdin as input, stdout as output } from "node:process";
+import { getStoredToken } from "./auth-store.js";
+import { cliApiError } from "./cli-api-error.js";
+import { CliError, ERR, authRequired, deviceLoginRequired, ttyRequired, } from "./errors.js";
+import { apiUrl, backoffTransport, fetchWithCliHeaders, parseJsonSafely, rethrowTransport, } from "./http.js";
+import * as out from "./output.js";
+import { LINK_PRIMARY, isObjectIdHex, writeLinkConfig } from "./paths.js";
+import { isHeadlessToken } from "./token-kind.js";
+/** Convert transport faults into a typed E0003 so they bubble to the top-level handler. */
+async function withTransport(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        rethrowTransport(e);
+    }
+}
+async function fetchProjects(token) {
+    const res = await fetchWithCliHeaders(apiUrl("/api/cli/projects"), { method: "GET" }, token);
+    const { json } = await parseJsonSafely(res);
+    if (!res.ok)
+        throw await cliApiError(res.status, json);
+    const projects = json?.projects;
+    return Array.isArray(projects) ? projects : [];
+}
+/** `.envspot.json` uses short `dev` / `prod` when user picks MVP environments. */
+function persistEnvironmentLabel(answer) {
+    const s = answer.trim().toLowerCase();
+    if (s === "" || s === "dev" || s === "development" || s === "local")
+        return "dev";
+    if (s === "prod" || s === "production")
+        return "prod";
+    return s;
+}
+/** Append the given patterns to cwd's `.gitignore` when missing (non-fatal).
+ *  Returns the patterns it actually added. */
+export function ensureGitignorePatterns(cwd, patterns) {
+    const gitignorePath = join(cwd, ".gitignore");
+    let raw = "";
+    try {
+        raw = readFileSync(gitignorePath, "utf8");
+    }
+    catch {
+        /* no .gitignore */
+    }
+    const present = new Set(raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#")));
+    const toAdd = patterns.filter((pat) => !present.has(pat));
+    if (toAdd.length === 0)
+        return [];
+    const sep = raw.length === 0 ? "" : raw.endsWith("\n") ? "" : "\n";
+    writeFileSync(gitignorePath, `${raw}${sep}${toAdd.join("\n")}\n`, "utf8");
+    return toAdd;
+}
+/** Append link file paths to cwd's `.gitignore` when missing (non-fatal). */
+export function ensureLinkPatternsInGitignore(cwd) {
+    return ensureGitignorePatterns(cwd, [LINK_PRIMARY, ".envspot"]);
+}
+function pickProjectFromList(projects, slugOrId) {
+    const raw = slugOrId.trim();
+    if (isObjectIdHex(raw.toLowerCase())) {
+        const row = projects.find((p) => p.id.toLowerCase() === raw.toLowerCase());
+        if (row)
+            return row;
+    }
+    const bySlug = projects.find((p) => p.slug === raw);
+    if (bySlug)
+        return bySlug;
+    throw new CliError(ERR.INVALID_INPUT, `Project not found: ${raw}.`, "Use a slug from Dashboard → Projects or the project id.");
+}
+function finishLink(cwd, picked, environment) {
+    const filePath = writeLinkConfig(cwd, { projectId: picked.id, environment });
+    try {
+        const added = ensureLinkPatternsInGitignore(cwd);
+        if (added.length > 0)
+            out.step(`Updated .gitignore (${added.join(", ")})`);
+    }
+    catch (gErr) {
+        out.warn(`Could not update .gitignore: ${gErr.message}`);
+    }
+    out.success(`Linked ${basename(filePath)} → ${picked.name} (${picked.slug})`);
+    out.info(`Environment: ${environment}`);
+}
+export async function runLinkWithFlags(projectFlag, envFlag) {
+    const token = await getStoredToken();
+    if (!token)
+        throw authRequired();
+    if (isHeadlessToken(token))
+        throw deviceLoginRequired("Linking");
+    const projects = await withTransport(async () => backoffTransport(async () => fetchProjects(token)));
+    const picked = pickProjectFromList(projects, projectFlag);
+    const environment = persistEnvironmentLabel(envFlag);
+    finishLink(process.cwd(), picked, environment);
+}
+export async function runLinkInteractive() {
+    const token = await getStoredToken();
+    if (!token)
+        throw authRequired();
+    if (isHeadlessToken(token))
+        throw deviceLoginRequired("Linking");
+    if (!process.stdin.isTTY) {
+        throw ttyRequired("envspot link", "Use: envspot link --project <slug-or-id> [--env dev]");
+    }
+    const projects = await withTransport(async () => backoffTransport(async () => fetchProjects(token)));
+    if (projects.length === 0) {
+        throw new CliError(ERR.UNEXPECTED, "No projects in this workspace.", "Create one in the dashboard first.");
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        let picked;
+        if (projects.length === 1) {
+            picked = projects[0];
+            out.info(`Using project "${picked.name}" (${picked.slug}).`);
+        }
+        else {
+            console.log("Select a project:");
+            for (let i = 0; i < projects.length; i++) {
+                const p = projects[i];
+                console.log(`  ${i + 1}. ${p.name}  (${p.slug})`);
+            }
+            const ans = (await rl.question("Enter number: ")).trim();
+            const n = Number(ans);
+            if (!Number.isInteger(n) || n < 1 || n > projects.length) {
+                throw new CliError(ERR.INVALID_INPUT, "Invalid selection.");
+            }
+            picked = projects[n - 1];
+        }
+        const rawEnv = (await rl.question("Environment [dev/production/staging/custom, default dev]: ")).trim() || "dev";
+        const environment = persistEnvironmentLabel(rawEnv);
+        finishLink(process.cwd(), picked, environment);
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/open-browser.js

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+export function openApproveUrl(url) {
+    if (process.env.ENVSPOT_SKIP_BROWSER_OPEN === "1") {
+        console.log(`Skipping browser (${url}) — ENVSPOT_SKIP_BROWSER_OPEN=1`);
+        return;
+    }
+    try {
+        if (process.platform === "darwin") {
+            spawn("/usr/bin/open", [url], {
+                detached: true,
+                stdio: "ignore",
+            }).unref();
+            return;
+        }
+        if (process.platform === "win32") {
+            spawn("cmd.exe", ["/d", "/c", "start", "", url], {
+                detached: true,
+                stdio: "ignore",
+                shell: false,
+            }).unref();
+            return;
+        }
+        spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    catch (e) {
+        console.warn("Could not launch browser:", e.message);
+        console.warn("Open this URL in a signed-in browser:\n ", url);
+    }
+}

package/dist/output.js

@@ -0,0 +1,21 @@
+/** Color is on only for an interactive stdout with NO_COLOR unset (per the NO_COLOR standard: any presence disables). */
+export function colorEnabled() {
+    if (process.env.NO_COLOR != null)
+        return false;
+    return process.stdout.isTTY === true;
+}
+function paint(code, s) {
+    return colorEnabled() ? `\x1b[${code}m${s}\x1b[0m` : s;
+}
+const green = (s) => paint(32, s);
+const yellow = (s) => paint(33, s);
+const cyan = (s) => paint(36, s);
+const dim = (s) => paint(2, s);
+export const fmtSuccess = (msg) => `${green("✓")} ${msg}`;
+export const fmtWarn = (msg) => `${yellow("⚠")} ${msg}`;
+export const fmtStep = (msg) => `${cyan("▸")} ${msg}`;
+export const fmtInfo = (msg) => dim(msg);
+export const success = (msg) => console.log(fmtSuccess(msg));
+export const warn = (msg) => console.error(fmtWarn(msg));
+export const step = (msg) => console.log(fmtStep(msg));
+export const info = (msg) => console.log(fmtInfo(msg));