getmyenv 0.13.0 → 0.14.0

package/dist/lib/api.js

@@ -2,25 +2,79 @@
  * CLI API client. Never prints plaintext values.
  */
 import { createRequire } from "node:module";
-import { readFolderToken } from "./credentials.js";
+import { readFolderToken, readFolderTokenLenient } from "./credentials.js";
 import { pickApiUrl } from "./api-url.js";
 /** From package.json, which ships with the package: src/lib and dist/lib are both two levels down. */
 export const CLI_VERSION = createRequire(import.meta.url)("../../package.json").version;
 export { isDefaultApiUrl, parseSafeUrl } from "./api-url.js";
-export const API_TIMEOUT_MS = 30_000;
+/** Short on purpose: a stuck process keeps npx's cache lock, so a second `npx getmyenv` waits silently. */
+export const API_TIMEOUT_MS = 8_000;
+/** A request still running after this prints one "Contacting" line on stderr. */
+export const CONTACTING_AFTER_MS = 1_000;
+let contactingPrinted = false;
+/** Error thrown when a request runs past `API_TIMEOUT_MS`, headers and body together. */
+export class RequestTimeoutError extends Error {
+    constructor() {
+        super("timed out");
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Runs `work` with an abort signal and a hard deadline. The deadline rejects even
+ * if the socket ignores the abort, and covers reading the body, not only the
+ * headers. Timers are cleared when `work` settles, so nothing outlives the request.
+ */
+export async function withDeadline(work, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? API_TIMEOUT_MS;
+    const controller = new AbortController();
+    let deadline;
+    let contacting;
+    const timedOut = new Promise((_, reject) => {
+        deadline = setTimeout(() => {
+            const err = new RequestTimeoutError();
+            controller.abort(err);
+            reject(err);
+        }, timeoutMs);
+    });
+    if (opts.contacting && !contactingPrinted) {
+        const origin = opts.contacting;
+        contacting = setTimeout(() => {
+            contactingPrinted = true;
+            process.stderr.write(`Contacting ${origin}...\n`);
+        }, CONTACTING_AFTER_MS);
+        contacting.unref?.();
+    }
+    try {
+        const running = work(controller.signal);
+        // After the deadline wins, the aborted work still rejects. Nobody awaits it then.
+        running.catch(() => { });
+        return await Promise.race([running, timedOut]);
+    }
+    finally {
+        clearTimeout(deadline);
+        clearTimeout(contacting);
+    }
+}
+/** Test hook: lets the "Contacting" line print again. */
+export function resetContactingForTests() {
+    contactingPrinted = false;
+}
 export class ApiError extends Error {
     status;
-    constructor(message, status) {
+    /** Machine-readable reason from the server, like `token_ended`. */
+    code;
+    constructor(message, status, code) {
         super(message);
         this.name = "ApiError";
         this.status = status;
+        this.code = code;
     }
 }
 export function resolveApiUrl(cliOverride) {
     return pickApiUrl({
         override: cliOverride,
         env: process.env.GETMYENV_API_URL,
-        tokenFile: readFolderToken()?.apiUrl,
+        tokenFile: readFolderTokenLenient()?.apiUrl,
     });
 }
 export class ApiClient {
@@ -42,47 +96,67 @@ export class ApiClient {
         return h;
     }
     async request(method, path, body, extraHeaders) {
-        let res;
+        const url = `${this.baseUrl.replace(/\/$/, "")}${path}`;
+        let origin = this.baseUrl;
         try {
-            res = await fetch(`${this.baseUrl.replace(/\/$/, "")}${path}`, {
-                method,
-                headers: this.headers(extraHeaders),
-                body: body === undefined ? undefined : JSON.stringify(body),
-                // The token must never follow a redirect to another host.
-                redirect: "error",
-                signal: AbortSignal.timeout(API_TIMEOUT_MS),
-            });
-        }
-        catch (err) {
-            throw networkError(err, `Could not reach ${this.baseUrl}`);
+            origin = new URL(url).origin;
         }
-        if (!res.ok) {
-            let serverMessage;
-            try {
-                const data = (await res.json());
-                serverMessage = data.error;
-            }
-            catch {
-                /* ignore */
-            }
-            const message = res.status >= 500
-                ? `The getmyenv server had an error (HTTP ${res.status}). Try again in a moment.`
-                : (serverMessage ?? `HTTP ${res.status}`);
-            throw new ApiError(message, res.status);
+        catch {
+            /* keep baseUrl */
         }
-        if (res.status === 204)
-            return undefined;
         try {
-            return (await res.json());
+            return await withDeadline(async (signal) => {
+                let res;
+                try {
+                    res = await fetch(url, {
+                        method,
+                        headers: this.headers(extraHeaders),
+                        body: body === undefined ? undefined : JSON.stringify(body),
+                        // The token must never follow a redirect to another host.
+                        redirect: "error",
+                        signal,
+                    });
+                }
+                catch (err) {
+                    throw networkError(err, `Could not reach ${this.baseUrl}. Check your connection, or the API URL (GETMYENV_API_URL or --api-url).`);
+                }
+                if (!res.ok) {
+                    let serverMessage;
+                    let code;
+                    try {
+                        const data = (await res.json());
+                        serverMessage = data.error;
+                        if (typeof data.code === "string")
+                            code = data.code;
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    const message = res.status >= 500
+                        ? `The getmyenv server had an error (HTTP ${res.status}). Try again in a moment.`
+                        : (serverMessage ?? `HTTP ${res.status}`);
+                    throw new ApiError(message, res.status, code);
+                }
+                if (res.status === 204)
+                    return undefined;
+                try {
+                    return (await res.json());
+                }
+                catch (err) {
+                    throw networkError(err, `The connection to ${this.baseUrl} closed before the answer arrived. Try again in a moment.`);
+                }
+            }, { contacting: origin });
         }
         catch (err) {
-            throw networkError(err, `The connection to ${this.baseUrl} closed before the answer arrived. Try again in a moment.`);
+            if (err instanceof RequestTimeoutError)
+                throw networkError(err, "");
+            throw err;
         }
     }
 }
 function networkError(err, fallback) {
     if (err instanceof Error && err.name === "TimeoutError") {
-        return new ApiError(`The getmyenv server did not answer within ${API_TIMEOUT_MS / 1000} seconds. Try again in a moment.`, 0);
+        return new ApiError(`The getmyenv server did not answer within ${API_TIMEOUT_MS / 1000} seconds. Try again in a moment.`, 0, "timeout");
     }
     return new ApiError(fallback, 0);
 }

package/dist/lib/authorize.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import pc from "picocolors";
+import { pcErr as pc } from "./colors.js";
 import { ensureGitignoreHasEnv, readLine, readProjectMeta, writeProjectMeta, } from "./fs.js";
 import { writeFolderToken } from "./credentials.js";
 import { ApiClient, parseSafeUrl, resolveApiUrl } from "./api.js";
@@ -97,7 +97,7 @@ async function authorizeViaBrowser(apiUrl, newProject) {
     });
     console.error("Open this URL to sign in and pick a project:\n");
     console.error(`  ${verifyUrl}\n`);
-    console.error(`Check the page shows this code: ${pc.bold(start.userCode)}\n`);
+    console.error(`Enter this code on the page: ${pc.bold(start.userCode)}\n`);
     openBrowser(verifyUrl);
     console.error(pc.dim("Opened in your browser. Waiting...\n"));
     const deadline = new Date(start.expiresAt).getTime();

package/dist/lib/bootstrap.d.ts

@@ -8,6 +8,11 @@ export type Linked = {
     meta: ProjectMeta | null;
 };
 export declare const NOT_LINKED_STEPS: string;
+/**
+ * Next steps for a folder with no token on this machine. A clone with a
+ * committed project.json gets its project named: it is not a new folder.
+ */
+export declare function notLinkedMessage(meta?: ProjectMeta | null): string;
 export declare function printGuestBanner(who: WhoamiResponse): void;
 export declare function fetchWhoami(client: ApiClient): Promise<WhoamiResponse>;
 /**

package/dist/lib/bootstrap.js

@@ -1,6 +1,8 @@
-import pc from "picocolors";
-import { GUEST_GRACE_MS } from "@getmyenv/shared";
-import { ensureGitignoreHasEnv, readClaimFile, readProjectMeta, writeProjectMeta, } from "./fs.js";
+import { pcErr as pc } from "./colors.js";
+import fs from "node:fs";
+import path from "node:path";
+import { GUEST_ACTIVE_DAYS, GUEST_GRACE_MS, TEMPLATE_FILE, TOKEN_ENDED_CODE } from "@getmyenv/shared";
+import { ensureGitignoreHasEnv, getLocalDir, readClaimFile, readProjectMeta, writeProjectMeta, } from "./fs.js";
 import { ApiClient, ApiError, getSessionToken, resolveApiUrl, } from "./api.js";
 import { assertTokenNotCommitted } from "./credentials.js";
 export const NOT_LINKED_STEPS = [
@@ -9,6 +11,21 @@ export const NOT_LINKED_STEPS = [
     "Without an account: npx getmyenv guest",
     "In CI: set GETMYENV_TOKEN",
 ].join("\n");
+/**
+ * Next steps for a folder with no token on this machine. A clone with a
+ * committed project.json gets its project named: it is not a new folder.
+ */
+export function notLinkedMessage(meta = readProjectMeta()) {
+    if (!meta?.projectId)
+        return NOT_LINKED_STEPS;
+    const hasTemplate = fs.existsSync(path.join(getLocalDir(), "template.json"));
+    return [
+        `This folder belongs to ${meta.projectName ?? meta.projectId}, but this machine has no token for it.`,
+        "In a terminal: npx getmyenv (sign in)",
+        ...(hasTemplate ? [`Or start your own project from ${TEMPLATE_FILE}: npx getmyenv guest`] : []),
+        "In CI: set GETMYENV_TOKEN",
+    ].join("\n");
+}
 export function printGuestBanner(who) {
     if (!who.isGuest)
         return;
@@ -22,8 +39,12 @@ export function printGuestBanner(who) {
         return;
     }
     const daysLeft = Number.isFinite(expires) ? Math.max(0, Math.ceil((expires - Date.now()) / DAY)) : null;
-    const days = daysLeft == null ? "soon" : plural(daysLeft);
-    console.error(pc.yellow(`Guest project. Expires in ${days}. Keep it: npx getmyenv claim.${needClaim}\n`));
+    // Each use moves the date to GUEST_ACTIVE_DAYS from now, so a countdown only means
+    // something once the cap after creation is closer than that.
+    const when = daysLeft != null && daysLeft < GUEST_ACTIVE_DAYS
+        ? `Expires in ${plural(daysLeft)}.`
+        : `Expires after ${plural(GUEST_ACTIVE_DAYS)} without use.`;
+    console.error(pc.yellow(`Guest project. ${when} Keep it: npx getmyenv claim.${needClaim}\n`));
 }
 export async function fetchWhoami(client) {
     try {
@@ -33,6 +54,9 @@ export async function fetchWhoami(client) {
         if (err instanceof ApiError && err.status === 410) {
             throw new Error(err.message);
         }
+        if (err instanceof ApiError && err.status === 401 && err.code === TOKEN_ENDED_CODE) {
+            throw new Error(err.message);
+        }
         if (err instanceof ApiError && err.status === 401) {
             throw new Error(process.env.GETMYENV_TOKEN?.trim()
                 ? "GETMYENV_TOKEN no longer works. It was revoked or expired. Create a new token in Project settings, Tokens."
@@ -49,14 +73,14 @@ export async function fetchWhoami(client) {
 export async function ensureTokenAndLink(opts = {}) {
     if (!getSessionToken()) {
         if (!process.stdin.isTTY) {
-            throw new Error(NOT_LINKED_STEPS);
+            throw new Error(notLinkedMessage());
         }
         const { startSetup } = await import("../commands/start.js");
         await startSetup({ apiUrl: opts.apiUrl, thenContinue: true });
     }
     const token = getSessionToken();
     if (!token)
-        throw new Error(NOT_LINKED_STEPS);
+        throw new Error(notLinkedMessage());
     if (!process.env.GETMYENV_TOKEN?.trim())
         assertTokenNotCommitted();
     const apiUrl = resolveApiUrl(opts.apiUrl);
@@ -68,7 +92,7 @@ export async function ensureTokenAndLink(opts = {}) {
     if (meta?.projectId && meta.projectId !== who.project.id) {
         throw new Error([
             `project.json points at ${meta.projectName ?? meta.projectId}, but the token is for ${who.project.name}.`,
-            "Run: npx getmyenv unlink   (then run the command again)",
+            "Run: npx getmyenv unlink, then run the command again.",
         ].join("\n"));
     }
     const usingEnvToken = Boolean(process.env.GETMYENV_TOKEN?.trim());

package/dist/lib/colors.d.ts

@@ -0,0 +1,14 @@
+type Stream = {
+    isTTY?: boolean;
+};
+/**
+ * Color only for a terminal. picocolors alone turns color on for every Windows
+ * process, so piped or redirected output would hold escape codes.
+ * NO_COLOR turns it off, FORCE_COLOR turns it on.
+ */
+export declare function colorEnabled(stream: Stream, env?: Record<string, string | undefined>): boolean;
+/** Colors for text written to stdout. */
+export declare const pc: import("picocolors/types").Colors;
+/** Colors for text written to stderr: prompts, status lines and warnings. */
+export declare const pcErr: import("picocolors/types").Colors;
+export {};

package/dist/lib/colors.js

@@ -0,0 +1,17 @@
+import picocolors from "picocolors";
+/**
+ * Color only for a terminal. picocolors alone turns color on for every Windows
+ * process, so piped or redirected output would hold escape codes.
+ * NO_COLOR turns it off, FORCE_COLOR turns it on.
+ */
+export function colorEnabled(stream, env = process.env) {
+    if (env.NO_COLOR)
+        return false;
+    if (env.FORCE_COLOR && env.FORCE_COLOR !== "0")
+        return true;
+    return Boolean(stream.isTTY) && env.TERM !== "dumb";
+}
+/** Colors for text written to stdout. */
+export const pc = picocolors.createColors(colorEnabled(process.stdout));
+/** Colors for text written to stderr: prompts, status lines and warnings. */
+export const pcErr = picocolors.createColors(colorEnabled(process.stderr));

package/dist/lib/confirm.d.ts

@@ -4,13 +4,17 @@ export type ConflictItem = {
     detail?: string;
 };
 /**
- * Prompt only when there are conflicts. Returns true to proceed.
- * Non-TTY: requires `yes` to be true when conflicts exist.
+ * Prompt only when something would be lost. Returns true to proceed.
+ * `conflicts` are names whose value changes, `removed` names that go away.
+ * Each list is counted on its own. Non-TTY: requires `yes`.
  */
 export declare function confirmDiff(opts: {
     conflicts: ConflictItem[];
+    removed?: ConflictItem[];
+    /** Heading after the count of `removed`. */
+    removedLabel?: string;
     /** What will happen if the user confirms, e.g. "Overwrite local values". */
     action: string;
-    /** Skip the prompt when true (still returns false if conflicts and non-TTY without yes). */
+    /** Skip the prompt when true. */
     yes?: boolean;
 }): Promise<boolean>;

package/dist/lib/confirm.js

@@ -1,25 +1,34 @@
-import pc from "picocolors";
+import { plural } from "@getmyenv/shared";
+import { pcErr as pc } from "./colors.js";
 import { promptConfirm } from "./fs.js";
+function printItems(title, items) {
+    if (items.length === 0)
+        return;
+    console.error(pc.yellow(`\n${title}:`));
+    for (const c of items.slice(0, 20)) {
+        console.error(`  ${c.name}${c.detail ? pc.dim(` - ${c.detail}`) : ""}`);
+    }
+    if (items.length > 20) {
+        console.error(pc.dim(`  …and ${items.length - 20} more`));
+    }
+}
 /**
- * Prompt only when there are conflicts. Returns true to proceed.
- * Non-TTY: requires `yes` to be true when conflicts exist.
+ * Prompt only when something would be lost. Returns true to proceed.
+ * `conflicts` are names whose value changes, `removed` names that go away.
+ * Each list is counted on its own. Non-TTY: requires `yes`.
  */
 export async function confirmDiff(opts) {
     const { conflicts, action, yes } = opts;
-    if (conflicts.length === 0)
+    const removed = opts.removed ?? [];
+    if (conflicts.length === 0 && removed.length === 0)
         return true;
-    console.error(pc.yellow(`\n${conflicts.length} conflict(s):`));
-    for (const c of conflicts.slice(0, 20)) {
-        console.error(`  ${c.name}${c.detail ? pc.dim(` - ${c.detail}`) : ""}`);
-    }
-    if (conflicts.length > 20) {
-        console.error(pc.dim(`  …and ${conflicts.length - 20} more`));
-    }
+    printItems(plural(conflicts.length, "conflict"), conflicts);
+    printItems(`${plural(removed.length, "name")} ${opts.removedLabel ?? "will be removed"}`, removed);
     console.error("");
     if (yes)
         return true;
     if (!process.stdin.isTTY) {
-        throw new Error(`Conflicts require confirmation. Re-run with --yes to ${action.toLowerCase()}.`);
+        throw new Error(`${conflicts.length > 0 ? "Conflicts require" : "Removing them requires"} confirmation. Re-run with --yes to ${action.toLowerCase()}.`);
     }
     return promptConfirm(`${action}?`, { defaultYes: false });
 }

package/dist/lib/context.js

@@ -35,7 +35,7 @@ export function resolveContext(who, meta, explicit) {
     if (found)
         return found;
     if (who.token.kind === "server") {
-        throw new Error(`This server token reads ${who.token.context ?? "one read-only context"} only.`);
+        throw new Error(`This server token reads ${who.token.context ?? "one Read-only context"} only.`);
     }
     const available = who.contexts.map((c) => c.slug).join(", ") || "none";
     const next = who.isGuest

package/dist/lib/credentials.d.ts

@@ -15,7 +15,11 @@ export type FolderToken = {
     addedAt: string;
 };
 export declare function tokenFilePath(cwd?: string): string;
+export declare const TOKEN_JSON_INVALID = ".getmyenv/token.json is not valid JSON. Fix it, or run: npx getmyenv unlink --yes, then npx getmyenv";
+/** Null when there is no token.json. Throws TOKEN_JSON_INVALID when it is not JSON. */
 export declare function readFolderToken(cwd?: string): FolderToken | null;
+/** `readFolderToken`, with an invalid token.json read as none. For unlink and the API URL only. */
+export declare function readFolderTokenLenient(cwd?: string): FolderToken | null;
 export declare function writeFolderToken(entry: {
     token: string;
     apiUrl?: string;

package/dist/lib/credentials.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { getLocalDir, getProjectRoot } from "./fs.js";
+import { getLocalDir, getProjectRoot, readJsonFile } from "./fs.js";
 import { apiUrlForDisk } from "./api-url.js";
 /** True when git tracks this file. False without git or outside a repo. */
 export function isTrackedByGit(file, cwd = process.cwd()) {
@@ -31,17 +31,10 @@ export function assertTokenNotCommitted(cwd = process.cwd()) {
 export function tokenFilePath(cwd = process.cwd()) {
     return path.join(getLocalDir(cwd), "token.json");
 }
+export const TOKEN_JSON_INVALID = ".getmyenv/token.json is not valid JSON. Fix it, or run: npx getmyenv unlink --yes, then npx getmyenv";
+/** Null when there is no token.json. Throws TOKEN_JSON_INVALID when it is not JSON. */
 export function readFolderToken(cwd = process.cwd()) {
-    const file = tokenFilePath(cwd);
-    if (!fs.existsSync(file))
-        return null;
-    let raw;
-    try {
-        raw = JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        return null;
-    }
+    const raw = readJsonFile(tokenFilePath(cwd), TOKEN_JSON_INVALID);
     if (!raw || typeof raw !== "object")
         return null;
     const d = raw;
@@ -63,6 +56,15 @@ export function readFolderToken(cwd = process.cwd()) {
         addedAt: d.addedAt,
     };
 }
+/** `readFolderToken`, with an invalid token.json read as none. For unlink and the API URL only. */
+export function readFolderTokenLenient(cwd = process.cwd()) {
+    try {
+        return readFolderToken(cwd);
+    }
+    catch {
+        return null;
+    }
+}
 export function writeFolderToken(entry, cwd = process.cwd()) {
     const file = tokenFilePath(cwd);
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });

package/dist/lib/fs.d.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 /**
  * `.getmyenv/project.json`, committed so a clone knows its project.
  * Holds no API URL: a committed file must not redirect where tokens go.
@@ -15,8 +16,22 @@ export type ProjectMeta = {
  */
 export declare function getProjectRoot(cwd?: string): string;
 export declare function getLocalDir(cwd?: string): string;
+/** Text of a file as UTF-8, without a byte order mark (Notepad and PowerShell 5.1 add one). */
+export declare function readTextFile(file: string): string;
+/**
+ * Parse a JSON file. Null when it does not exist. Invalid JSON throws
+ * `invalid`: a broken file is never read as missing, so it is never
+ * silently replaced.
+ */
+export declare function readJsonFile(file: string, invalid: string): unknown;
+export declare const PROJECT_JSON_INVALID = ".getmyenv/project.json is not valid JSON. Fix it, or restore it: git checkout -- .getmyenv/project.json";
 export declare function readProjectMeta(cwd?: string): ProjectMeta | null;
 export declare function writeProjectMeta(meta: ProjectMeta, cwd?: string): void;
+/**
+ * Check that `file` can be written as a plain file: not a symlink, not a
+ * folder, and its folder exists. Returns its stats, or null when it is new.
+ */
+export declare function assertFileTarget(file: string): fs.Stats | null;
 /**
  * Write a file only this user can read. Never through a symlink. A new file
  * is created with `wx`; an existing one is replaced only when `overwrite`.
@@ -58,8 +73,28 @@ export declare function claimFilePath(cwd?: string): string;
 export declare function readClaimFile(cwd?: string): ClaimFile | null;
 export declare function writeClaimFile(data: Omit<ClaimFile, "version">, cwd?: string): string;
 export declare function clearClaimFile(cwd?: string): boolean;
-/** dotenv rules (multiline values, inline comments, BOM), valid names only. */
+/** dotenv rules (multiline values, inline comments, BOM). Invalid names land in `skipped`. */
+export declare function readEnvText(text: string): {
+    values: Record<string, string>;
+    skipped: string[];
+};
+/** `readEnvText`, valid names only. */
 export declare function parseEnvText(text: string): Record<string, string>;
+/**
+ * Text from bytes, by byte order mark: UTF-16 LE or BE (PowerShell 5.1 `>`
+ * writes UTF-16 LE), else UTF-8 without its BOM.
+ */
+export declare function decodeText(buf: Buffer): string;
+/** `readEnvText` for a file, UTF-8 or UTF-16. A missing file reads as empty. */
+export declare function readEnvFile(filePath: string): {
+    values: Record<string, string>;
+    skipped: string[];
+};
+/** Names that appear more than once in an env file, with their count. dotenv keeps the last one. */
+export declare function duplicateEnvNames(filePath: string): Array<{
+    name: string;
+    count: number;
+}>;
 /** `parseEnvText` for a file. A missing file reads as empty. */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
 /** `.example`, `.sample` and `.template` files hold placeholders, not values. */