getmyenv 0.11.0 → 0.12.0

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.
@@ -34,8 +37,19 @@ Prompts and status lines go to stderr, so `export --stdout > .env` stays clean.
 
 Commit `.getmyenv/project.json` and `.getmyenv/template.json`. `token.json` and `claim.json` stay local and are gitignored. `template.json` lists the variable names, never values. In a fresh clone, `npx getmyenv` can start a new project from it and asks for each value.
 
+What the CLI writes. Not every folder has all four:
+
+```text
+my-app/
+  .getmyenv/
+    project.json   committed. Project id, name and the folder's default context. Written by setup, guest or sign-in.
+    template.json  committed. Variable names, never values. Written once the project has a variable name.
+    token.json     gitignored. The folder token. Written by sign-in or guest. Not used with GETMYENV_TOKEN.
+    claim.json     gitignored, guest only. Claim code and guest passphrase. Keep it private. Written by guest. Deleted by claim.
+```
+
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.11.0):
+Output of `npx getmyenv --help` (0.12.0):
 
 ```text
 Usage: getmyenv [options] [command]
@@ -88,7 +102,7 @@ Environment:
 
 ## Vault password
 
-Each context has its own key, sealed to your account. Your Vault password opens your account key. For open contexts, after you enter the Vault password in a terminal, the unlocked context keys stay in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for 8 hours. The password is never stored.
+One Vault password per account unlocks your private key on your device. Each context has its own key, and each reader gets their own sealed copy. Forgot the Vault password? Your recovery code sets a new one in the dashboard. For open contexts, after you enter the Vault password in a terminal, the unlocked context keys stay in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for 8 hours. The password is never stored.
 
 - `npx getmyenv lock` removes every entry. `unlink` removes this project's.
 - Server tokens hold their context key and never ask.

package/dist/commands/backup.js

@@ -33,6 +33,6 @@ export async function backupCommand(opts) {
     writePrivateFile(out, serializeBackup(envelope), { overwrite: false });
     console.log(`${pc.green("✓")} Encrypted backup: ${out} (${data.values.length} values, ${data.contexts.length} open contexts)`);
     console.log(pc.dim(data.recoveryWrappedKey
-        ? "It opens with your current Vault password or recovery code. Read-only contexts are backed up from the dashboard."
-        : "It opens with your current Vault password. Read-only contexts are backed up from the dashboard."));
+        ? "It opens with your Vault password or recovery code as they are now, not with newer ones. Read-only contexts are backed up from the dashboard."
+        : "It opens with your Vault password as it is now, not with a newer one. Read-only contexts are backed up from the dashboard."));
 }

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.0",
+  "version": "0.12.0",
   "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.0",
+    "@getmyenv/shared": "0.11.0",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",