getmyenv 0.11.1 → 0.12.1

package/README.md

@@ -12,6 +12,9 @@ npx getmyenv run -- npm run dev       # start with the default context
 npx getmyenv run staging -- npm start # or pick one
 ```
 
+- Run getmyenv where your app starts: your machine, the server, the CI job, or the container's start command. It needs Node 24 or newer there. run is the default. If getmyenv can't run where the app starts, export writes a plaintext .env instead.
+- run fetches the values from getmyenv each time it starts. If it can't reach the server, the command does not start. A running process keeps its values.
+
 ## Commands
 
 - `getmyenv`: setup in a new folder, status in a linked one. Without a TTY it prints next steps and exits.
@@ -46,7 +49,7 @@ my-app/
 ```
 
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.11.1):
+Output of `npx getmyenv --help` (0.12.1):
 
 ```text
 Usage: getmyenv [options] [command]
@@ -108,7 +111,7 @@ One Vault password per account unlocks your private key on your device. Each con
 
 ## CI and servers
 
-Create a server token for one context on the dashboard CLI page. It holds that context's key.
+Create a server token for one context in Project settings, Tokens. It holds that context's key.
 
 ```bash
 export GETMYENV_TOKEN=...   # server token from the dashboard
@@ -117,7 +120,7 @@ npx getmyenv run -- node server.js
 
 Server tokens are read-only. `set` needs the folder token from browser sign-in, or a guest project. `printf %s "$VALUE" | npx getmyenv set API_KEY --stdin` keeps the value out of argv.
 
-- `GETMYENV_TOKEN`: a token from the dashboard CLI page.
+- `GETMYENV_TOKEN`: a server token from Project settings, Tokens.
 - `GETMYENV_CONFIG_DIR`: machine key and cache (default `~/.config/getmyenv`). Use a persistent volume in containers.
 - `GETMYENV_API_URL`: API origin. https only, http for localhost.
 - `GETMYENV_MACHINE_LABEL`: the machine name shown in approval requests.

package/dist/commands/import.js

@@ -166,7 +166,7 @@ export async function importCommand(file, opts) {
     }
     ensureGitignoreHasEnv();
     if (imported > 0) {
-        console.error(pc.dim("Your .env files are unchanged. getmyenv run does not need them. Delete them when you are ready.\n"));
+        console.error(pc.dim(`Your .env files are unchanged. ${FACTS.runIgnoresEnvFile}\n`));
         if (!opts.noRunLine) {
             console.error("Start your app with:");
             console.error(pc.cyan(`  ${runLine(explicitContext ?? defaultContextSlug(who, meta))}\n`));

package/dist/commands/run.js

@@ -4,6 +4,7 @@ import pc from "picocolors";
 import { decryptSecret, parsePayload } from "@getmyenv/crypto";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { resolveContext } from "../lib/context.js";
+import { pendingFirstRunHints } from "../lib/first-run.js";
 import { resolveValues } from "../lib/resolve.js";
 import { contextKey } from "../lib/vault.js";
 import { assertVariableNames, explainLines, mergeEnv, runContextLabel, signalExitCode, validationError, windowsCommandLine, } from "../lib/run-env.js";
@@ -51,6 +52,19 @@ export async function runCommand(opts, childArgs) {
     if (merged.unresolved.length > 0) {
         log(pc.yellow(`Not set: ${merged.unresolved.map((m) => m.name).join(", ")}`));
     }
+    const hints = opts.explain
+        ? { lines: [], markShown: () => undefined }
+        : pendingFirstRunHints({
+            isTTY: Boolean(process.stderr.isTTY),
+            env: process.env,
+            tokenKind: who.token.kind,
+            apiUrl: linked.apiUrl,
+            projectId: who.project.id,
+            childArgs,
+            cwd: process.cwd(),
+        });
+    for (const line of hints.lines)
+        log(pc.dim(line));
     const [cmd, ...args] = childArgs;
     const child = process.platform === "win32"
         ? spawn(windowsCommandLine(childArgs), { env: merged.env, stdio: "inherit", shell: true })
@@ -64,6 +78,7 @@ export async function runCommand(opts, childArgs) {
                 child.kill(sig);
         });
     }
+    child.once("spawn", hints.markShown);
     const code = await new Promise((resolve) => {
         child.on("error", (err) => {
             log(pc.red(`Could not start ${cmd}: ${err.message}`));

package/dist/lib/first-run.d.ts

@@ -0,0 +1,24 @@
+export type HintContext = {
+    isTTY: boolean;
+    env: NodeJS.ProcessEnv;
+    tokenKind: "folder" | "guest" | "server";
+};
+export declare function hintsEnabled({ isTTY, env, tokenKind }: HintContext): boolean;
+/** The package.json script a command like `npm start` or `pnpm run dev` starts, if any. */
+export declare function packageScriptName(childArgs: string[]): string | null;
+/** True when that script passes --env-file to node. */
+export declare function scriptUsesEnvFile(childArgs: string[], packageJson: unknown): boolean;
+export declare function hintLines(childArgs: string[], cwd: string): string[];
+/** One marker per server origin and project, in the CLI config dir. */
+export declare function hintMarkerPath(configDir: string, apiUrl: string, projectId: string): string;
+export type PendingHints = {
+    lines: string[];
+    markShown: () => void;
+};
+export declare function pendingFirstRunHints(input: HintContext & {
+    apiUrl: string;
+    projectId: string;
+    childArgs: string[];
+    cwd: string;
+    configDir?: () => string;
+}): PendingHints;

package/dist/lib/first-run.js

@@ -0,0 +1,92 @@
+/**
+ * Hints printed by the first `run` of a project on this machine. Never in CI,
+ * with GETMYENV_TOKEN or a server token, or when stderr is not a terminal.
+ * The marker is written once the child has spawned, so a run that fails before
+ * that shows the hints again. Marker errors never change what `run` does.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { FACTS } from "@getmyenv/shared";
+import { getConfigDir } from "./fs.js";
+import { keychainAccount } from "./keychain.js";
+export function hintsEnabled({ isTTY, env, tokenKind }) {
+    if (!isTTY || tokenKind === "server" || env.GETMYENV_TOKEN?.trim())
+        return false;
+    const ci = env.CI?.trim().toLowerCase();
+    return !ci || ci === "false" || ci === "0";
+}
+const MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+/** The package.json script a command like `npm start` or `pnpm run dev` starts, if any. */
+export function packageScriptName(childArgs) {
+    const [cmd, ...rest] = childArgs;
+    if (!cmd)
+        return null;
+    const manager = path.basename(cmd).replace(/\.(cmd|exe|ps1)$/i, "").toLowerCase();
+    if (!MANAGERS.has(manager))
+        return null;
+    const args = rest.filter((a) => !a.startsWith("-"));
+    if (args[0] === "run" || args[0] === "run-script")
+        return args[1] ?? null;
+    if (manager === "npm")
+        return args[0] === "start" || args[0] === "test" ? args[0] : null;
+    return args[0] ?? null;
+}
+/** True when that script passes --env-file to node. */
+export function scriptUsesEnvFile(childArgs, packageJson) {
+    const name = packageScriptName(childArgs);
+    if (!name)
+        return false;
+    const scripts = packageJson?.scripts;
+    const script = scripts?.[name];
+    return typeof script === "string" && /--env-file\b/.test(script);
+}
+function readPackageJson(cwd) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function hintLines(childArgs, cwd) {
+    const lines = [FACTS.runExplainHint];
+    if (fs.existsSync(path.join(cwd, ".env")))
+        lines.push(FACTS.runIgnoresEnvFile);
+    if (scriptUsesEnvFile(childArgs, readPackageJson(cwd)))
+        lines.push(FACTS.envFileScripts);
+    return lines;
+}
+/** One marker per server origin and project, in the CLI config dir. */
+export function hintMarkerPath(configDir, apiUrl, projectId) {
+    const id = createHash("sha256").update(keychainAccount(apiUrl, projectId)).digest("hex").slice(0, 32);
+    return path.join(configDir, "hints", `${id}.json`);
+}
+const NONE = { lines: [], markShown: () => undefined };
+export function pendingFirstRunHints(input) {
+    if (!hintsEnabled(input))
+        return NONE;
+    let marker = null;
+    try {
+        marker = hintMarkerPath((input.configDir ?? getConfigDir)(), input.apiUrl, input.projectId);
+        if (fs.existsSync(marker))
+            return NONE;
+    }
+    catch {
+        marker = null;
+    }
+    return {
+        lines: hintLines(input.childArgs, input.cwd),
+        markShown: () => {
+            if (!marker)
+                return;
+            try {
+                fs.mkdirSync(path.dirname(marker), { recursive: true, mode: 0o700 });
+                fs.writeFileSync(marker, `${JSON.stringify({ shownAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+            }
+            catch {
+                /* the hints show again next time */
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getmyenv",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "CLI for getmyenv, an encrypted store for environment variables and secrets. We store ciphertext only.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@getmyenv/crypto": "0.5.0",
-    "@getmyenv/shared": "0.10.1",
+    "@getmyenv/shared": "0.11.0",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",