getmyenv 0.11.1 → 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.
@@ -46,7 +49,7 @@ my-app/
 ```
 
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.11.1):
+Output of `npx getmyenv --help` (0.12.0):
 
 ```text
 Usage: getmyenv [options] [command]

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