@skaile/forge-settings 0.0.0-stage → 1.0.0

package/src/runtime/server/env-layers.ts

@@ -0,0 +1,290 @@
+/**
+ * Layered `.env` files — the server half of the settings modal's Providers
+ * tab (credential picker, Enter a key, environment disclosure).
+ *
+ * A registry entry references its secret as `env:NAME`; the host resolves that
+ * name against a layered environment where the nearest layer wins:
+ * `process` (boot env) < `instance` (`$FORGE_HOME/.env`) < `workspace`
+ * (`<workspace root>/.env`). This module reads and edits those files and builds
+ * the document the browser sees — names, masked hints and lengths, never
+ * values.
+ *
+ * The vocabulary (layer ids, name rules, document shapes) lives in the
+ * browser-safe `utils/env-vars.ts` and is re-exported here, so client and
+ * server refuse the same names from one source.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AI_PROVIDER_PRESETS } from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderRegistryView } from "../shared/provider-registry";
+import { parseCredentialRef, registryEntries } from "../shared/provider-registry";
+import {
+  ENV_LAYER_ORDER,
+  type EnvLayerId,
+  type EnvSettingsDocument,
+  type EnvSettingsMissing,
+  type EnvSettingsUpdate,
+  type EnvVarView,
+  validateEnvVarName,
+} from "../shared/env-vars";
+
+export * from "../shared/env-vars";
+
+// ── Parsing ────────────────────────────────────────────────────────────────
+
+/** `KEY=VALUE`, optionally prefixed with `export `. Group 1 = key, group 2 = raw value. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=(.*)$/;
+
+/** Characters that force a written value into double quotes. */
+const NEEDS_QUOTES = /[\s#"'=\\]/;
+
+/** Value part of one assignment line, quotes and inline comments resolved. */
+function parseValue(raw: string): string {
+  const value = raw.trim();
+  if (value.startsWith('"')) {
+    for (let i = 1; i < value.length; i++) {
+      if (value[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (value[i] === '"') {
+        return value
+          .slice(1, i)
+          .replace(/\\([nr"\\])/g, (_, ch: string) => (ch === "n" ? "\n" : ch === "r" ? "\r" : ch));
+      }
+    }
+    return value;
+  }
+  if (value.startsWith("'")) {
+    const end = value.indexOf("'", 1);
+    return end === -1 ? value : value.slice(1, end);
+  }
+  const comment = value.search(/\s#/);
+  return (comment === -1 ? value : value.slice(0, comment)).trim();
+}
+
+/**
+ * Parse `.env` text: blank and `#` lines skipped, optional `export ` prefix,
+ * single-quoted values literal, double-quoted values unescape `\n`, `\"`, `\\`,
+ * unquoted values lose an inline ` #` comment. A later duplicate wins.
+ */
+export function parseDotenv(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  // Blank and `#` lines never match: a key must start the (trimmed) line.
+  for (const line of text.split(/\r?\n/)) {
+    const match = ASSIGNMENT.exec(line);
+    if (match) env[match[1]] = parseValue(match[2]);
+  }
+  return env;
+}
+
+/** Parsed `.env` file; `{}` when it is missing or unreadable. */
+export function readDotenvFile(path: string): Record<string, string> {
+  try {
+    return parseDotenv(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+// ── Writing ────────────────────────────────────────────────────────────────
+
+/** One value as it is written after `KEY=` — round-trips through {@link parseDotenv}. */
+function serializeValue(value: string): string {
+  if (!NEEDS_QUOTES.test(value)) return value;
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r");
+  return `"${escaped}"`;
+}
+
+function readTextIfExists(path: string): string {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return "";
+    throw err;
+  }
+}
+
+/** Write `content` to `path` atomically (tmp file + rename), mode 0600. */
+function writeFileAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  chmodSync(path, 0o600);
+}
+
+/**
+ * Apply `patch` to the `.env` file at `path`, preserving every line it does not
+ * touch. A patched key's first `KEY=` / `export KEY=` line is rewritten in
+ * place and its later duplicates dropped; `null` deletes the key; keys the file
+ * lacks are appended. The file is created (parents included) when missing and
+ * always left at mode 0600.
+ */
+export function updateDotenvFile(path: string, patch: Record<string, string | null>): void {
+  const text = readTextIfExists(path);
+  const lines = text === "" ? [] : text.replace(/\r?\n$/, "").split("\n");
+  const written = new Set<string>();
+  const out: string[] = [];
+
+  for (const line of lines) {
+    const key = ASSIGNMENT.exec(line)?.[1];
+    if (key === undefined || !Object.hasOwn(patch, key)) {
+      out.push(line);
+      continue;
+    }
+    if (written.has(key)) continue;
+    written.add(key);
+    const value = patch[key];
+    if (value === null) continue;
+    const prefix = /^\s*export\s/.test(line) ? "export " : "";
+    out.push(`${prefix}${key}=${serializeValue(value)}`);
+  }
+
+  for (const [key, value] of Object.entries(patch)) {
+    if (written.has(key) || value === null) continue;
+    out.push(`${key}=${serializeValue(value)}`);
+  }
+
+  writeFileAtomic(path, out.length > 0 ? `${out.join("\n")}\n` : "");
+}
+
+/** `.gitignore` lines that already keep a directory's `.env` out of git. */
+const DOTENV_IGNORE_LINES: Record<string, true> = {
+  ".env": true,
+  "/.env": true,
+  "*.env": true,
+  ".env*": true,
+};
+
+/**
+ * Make sure `<dir>/.gitignore` ignores `.env`: appends the line unless an
+ * equivalent pattern is already present, creating the file when missing.
+ */
+export function ensureDotenvIgnored(dir: string): void {
+  const path = join(dir, ".gitignore");
+  const text = readTextIfExists(path);
+  if (text.split(/\r?\n/).some((line) => DOTENV_IGNORE_LINES[line.trim()])) return;
+  const separator = text !== "" && !text.endsWith("\n") ? "\n" : "";
+  writeFileSync(path, `${text}${separator}.env\n`);
+}
+
+// ── Settings document ──────────────────────────────────────────────────────
+
+/** Input of {@link buildEnvSettingsDocument}. */
+export interface EnvSettingsDocumentInput {
+  scope: "instance" | "workspace";
+  editable: boolean;
+  /** The layers visible from this scope; absent layers are ignored. */
+  layers: Partial<Record<EnvLayerId, Record<string, string | undefined>>>;
+  /** Registry whose `env:` references are reported (`referencedBy`, `missing`). */
+  registry: AIProviderRegistryView;
+}
+
+/**
+ * The browser's view of a scope's environment. Lists every name an editable
+ * layer (instance, workspace) holds, every name a registry `env:` reference
+ * uses, and every catalog preset's conventional key name that some layer sets
+ * — so the credential picker can tell a set `OPENROUTER_API_KEY` from an unset
+ * one. Other process variables stay unlisted. Values never leave: each row
+ * carries only a hint and a length.
+ */
+export function buildEnvSettingsDocument(input: EnvSettingsDocumentInput): EnvSettingsDocument {
+  const { layers } = input;
+
+  const referencedBy = new Map<string, string[]>();
+  for (const [id, entry] of registryEntries(input.registry)) {
+    const ref = entry.credential?.ref;
+    const parsed = ref ? parseCredentialRef(ref) : undefined;
+    if (parsed?.form !== "env") continue;
+    const ids = referencedBy.get(parsed.name) ?? [];
+    ids.push(id);
+    referencedBy.set(parsed.name, ids);
+  }
+
+  const names = new Set<string>(referencedBy.keys());
+  for (const layer of ["instance", "workspace"] as const) {
+    for (const name of Object.keys(layers[layer] ?? {})) names.add(name);
+  }
+  for (const preset of Object.values(AI_PROVIDER_PRESETS)) {
+    const name = preset.credential.env;
+    if (name && ENV_LAYER_ORDER.some((layer) => layers[layer]?.[name])) names.add(name);
+  }
+
+  const vars: EnvVarView[] = [];
+  const missing: EnvSettingsMissing[] = [];
+  for (const name of [...names].sort()) {
+    const refs = [...(referencedBy.get(name) ?? [])].sort();
+    const defining = ENV_LAYER_ORDER.filter((layer) => {
+      const value = layers[layer]?.[name];
+      return value !== undefined && value !== "";
+    });
+    const source = defining.at(-1);
+    if (source === undefined) {
+      if (refs.length > 0) missing.push({ name, referencedBy: refs });
+      continue;
+    }
+    const value = layers[source]?.[name] ?? "";
+    vars.push({
+      name,
+      hint: value.length >= 8 ? value.slice(-4) : "",
+      length: value.length,
+      source,
+      shadows: defining.slice(0, -1),
+      referencedBy: refs,
+    });
+  }
+
+  return { scope: input.scope, editable: input.editable, layer: input.scope, vars, missing };
+}
+
+// ── Update validation ──────────────────────────────────────────────────────
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate a `PUT <environmentUrl>` body. Returns the normalized update, or a
+ * refusal string suitable as an HTTP 400 status message.
+ */
+export function validateEnvSettingsUpdate(body: unknown): EnvSettingsUpdate | string {
+  if (!isPlainObject(body)) return "Body must be an object with `set` and/or `unset`";
+
+  const set: Record<string, string> = {};
+  if (body.set !== undefined) {
+    if (!isPlainObject(body.set)) return "`set` must be an object of variable names to values";
+    for (const [name, value] of Object.entries(body.set)) {
+      const refusal = validateEnvVarName(name);
+      if (refusal) return refusal;
+      if (typeof value !== "string") return `Value of "${name}" must be a string`;
+      if (/[\r\n]/.test(value)) return `Value of "${name}" must be a single line`;
+      set[name] = value;
+    }
+  }
+
+  const unset: string[] = [];
+  if (body.unset !== undefined) {
+    if (!Array.isArray(body.unset)) return "`unset` must be an array of variable names";
+    for (const name of body.unset) {
+      if (typeof name !== "string") return "`unset` must be an array of variable names";
+      const refusal = validateEnvVarName(name);
+      if (refusal) return refusal;
+      if (Object.hasOwn(set, name)) return `"${name}" cannot be both set and unset`;
+      if (!unset.includes(name)) unset.push(name);
+    }
+  }
+
+  if (Object.keys(set).length === 0 && unset.length === 0) return "Nothing to change";
+  return { set, unset };
+}

package/src/runtime/server/env.ts

@@ -0,0 +1,46 @@
+/**
+ * .env file loading utilities for forge apps.
+ *
+ * Nuxt's built-in dotenv only injects NUXT_* variables into runtime config.
+ * API keys and provider preferences (ANTHROPIC_API_KEY, PREFERRED_PROVIDER,
+ * PREFERRED_MODEL, etc.) are plain env vars read directly via process.env, so
+ * forge apps need to load them explicitly at server startup.
+ *
+ * Usage pattern (in a Nitro plugin named 00.env-load.ts):
+ *
+ *   import { injectEnvFiles } from '@skaile/forge-settings/server'
+ *   injectEnvFiles([appRoot])
+ *
+ * ~/.env is always included as the lowest-priority source automatically.
+ */
+
+import { homedir } from "node:os";
+import path from "node:path";
+import { readDotenvFile } from "./env-layers";
+
+/**
+ * Parse the `.env` file in the given directory (see `parseDotenv` for the
+ * syntax). Returns an empty object if the file does not exist or cannot be read.
+ */
+export function loadEnvFile(dir: string): Record<string, string> {
+  return readDotenvFile(path.join(dir, ".env"));
+}
+
+/**
+ * Load `.env` files and inject missing keys into process.env.
+ *
+ * Directories are merged in order — later directories take precedence.
+ * `~/.env` is always prepended as the lowest-priority source.
+ * Real environment variables (already in process.env) are never overwritten.
+ *
+ * @param appDirs - App-specific directories to scan (e.g. app root, project root)
+ */
+export function injectEnvFiles(appDirs: string[]): void {
+  const merged: Record<string, string> = {};
+  for (const dir of [homedir(), ...appDirs]) {
+    Object.assign(merged, loadEnvFile(dir));
+  }
+  for (const [k, v] of Object.entries(merged)) {
+    if (!process.env[k] && v) process.env[k] = v;
+  }
+}