@intelli-1113/stratos-sdk 1.3.4 → 1.3.6

package/src/claude-code/settings.js

@@ -0,0 +1,155 @@
+// Shared Claude Code settings helpers: where Stratos keeps its own config,
+// the hook block written into ~/.claude/settings.json, and a merge that never
+// drops the user's own hooks.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_URL = "http://localhost:4000";
+export const HOOK_EVENTS = {
+  SessionStart: { arg: "session-start", timeout: 10 },
+  Stop: { arg: "stop", timeout: 30, async: true },
+  SubagentStop: { arg: "subagent-stop", timeout: 30, async: true },
+  SessionEnd: { arg: "session-end", timeout: 15 },
+};
+
+/** ~/.stratos — token, URL, cursors and the outbox live here, not in settings.json. */
+export function stratosDir() {
+  return process.env.STRATOS_HOME || join(homedir(), ".stratos");
+}
+
+export function claudeSettingsPath() {
+  return join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "settings.json");
+}
+
+const configPath = () => join(stratosDir(), "config.json");
+
+function flag(v, fallback = false) {
+  if (v == null || v === "") return fallback;
+  return !["0", "false", "off", "no"].includes(String(v).toLowerCase());
+}
+
+/** Config file, overridden by STRATOS_* environment variables when set. */
+export function loadConfig() {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    /* not set up yet */
+  }
+  const env = process.env;
+  return {
+    token: env.STRATOS_TOKEN || file.token || "",
+    url: (env.STRATOS_URL || file.url || DEFAULT_URL).replace(/\/+$/, ""),
+    appName: env.STRATOS_APP_NAME || file.appName || "claude-code",
+    recordInputs: flag(env.STRATOS_RECORD_INPUTS, !!file.recordInputs),
+    recordOutputs: flag(env.STRATOS_RECORD_OUTPUTS, !!file.recordOutputs),
+  };
+}
+
+export function saveConfig(cfg) {
+  const file = configPath();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(file, 0o600); // no-op on Windows, where the profile folder is already per-user
+  } catch {
+    /* ignore */
+  }
+  return file;
+}
+
+export function configExists() {
+  return existsSync(configPath());
+}
+
+export function configFile() {
+  return configPath();
+}
+
+/** Absolute path of this package's CLI entry. */
+export function cliPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+}
+
+const fwd = (p) => p.replace(/\\/g, "/");
+
+/**
+ * The command Claude Code runs for one hook event. The script path is absolute
+ * (no global install needed); the program is bare `node` because a command that
+ * starts with a quoted path is a parse error in PowerShell, which Claude Code
+ * may use for hooks on Windows. `node "<path>" hook stop` works in bash, cmd and
+ * PowerShell alike.
+ */
+export function hookCommand(arg, { node = "node", cli = cliPath() } = {}) {
+  return `${node} "${fwd(cli)}" hook ${arg}`;
+}
+
+const OUR_HOOK = /cli\.js"?\s+hook\s+(session-start|stop|subagent-stop|session-end)\b/;
+
+export function isStratosHook(h) {
+  return !!(h && typeof h.command === "string" && OUR_HOOK.test(h.command) && /stratos/i.test(h.command));
+}
+
+/** Hook block in Claude Code's schema: { Event: [ { matcher, hooks: [ {type, command, ...} ] } ] } */
+export function buildClaudeCodeHooks(opts = {}) {
+  const hooks = {};
+  for (const [event, spec] of Object.entries(HOOK_EVENTS)) {
+    const handler = { type: "command", command: hookCommand(spec.arg, opts), timeout: spec.timeout };
+    if (spec.async) handler.async = true;
+    hooks[event] = [{ matcher: "*", hooks: [handler] }];
+  }
+  return hooks;
+}
+
+/** Remove our handlers from a hooks object, keeping everything else the user has. */
+export function removeStratosHooks(hooks = {}) {
+  const out = {};
+  for (const [event, groups] of Object.entries(hooks || {})) {
+    if (!Array.isArray(groups)) {
+      out[event] = groups;
+      continue;
+    }
+    const kept = groups
+      .map((g) => (g && Array.isArray(g.hooks) ? { ...g, hooks: g.hooks.filter((h) => !isStratosHook(h)) } : g))
+      .filter((g) => !(g && Array.isArray(g.hooks) && g.hooks.length === 0));
+    if (kept.length) out[event] = kept;
+  }
+  return out;
+}
+
+/** Add our hooks; re-running replaces our old entries instead of duplicating them. */
+export function mergeStratosHooks(hooks = {}, opts = {}) {
+  const out = removeStratosHooks(hooks);
+  for (const [event, groups] of Object.entries(buildClaudeCodeHooks(opts))) {
+    out[event] = [...(Array.isArray(out[event]) ? out[event] : []), ...groups];
+  }
+  return out;
+}
+
+/** Earlier setup versions wrote these into settings.env; they must go. */
+export const LEGACY_ENV_KEYS = ["STRATOS_TOKEN", "STRATOS_URL", "STRATOS_RECORD_INPUTS", "STRATOS_RECORD_OUTPUTS"];
+
+export function hasLegacyNodeOptions(env = {}) {
+  return typeof env.NODE_OPTIONS === "string" && env.NODE_OPTIONS.includes("stratos-sdk/register");
+}
+
+export function cleanLegacyEnv(env = {}) {
+  const out = { ...env };
+  for (const k of LEGACY_ENV_KEYS) delete out[k];
+  if (hasLegacyNodeOptions(out)) {
+    const rest = out.NODE_OPTIONS.replace(/--import[= ]\S*stratos-sdk\/register\S*/g, "").trim();
+    if (rest) out.NODE_OPTIONS = rest;
+    else delete out.NODE_OPTIONS;
+  }
+  return out;
+}
+
+/** Managed-settings.json locations for admins deploying to every developer. */
+export const MANAGED_SETTINGS_PATHS = {
+  win32: "C:\\Program Files\\ClaudeCode\\managed-settings.json",
+  darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
+  linux: "/etc/claude-code/managed-settings.json",
+};

package/src/claude-code/transcript.js

@@ -0,0 +1,259 @@
+// Claude Code transcript → Stratos spans (pure, no I/O).
+//
+// Claude Code writes every session to a JSONL transcript
+// (~/.claude/projects/<project>/<session>.jsonl, subagents in
+// <session>/subagents/agent-<id>.jsonl). Each assistant API call carries the
+// model and token usage; tool calls appear as tool_use blocks, answered later
+// by tool_result blocks. The format is internal to Claude Code and not
+// documented, so everything here is defensive: unknown shapes are skipped and
+// nothing throws.
+//
+// Spans use the same OpenLLMetry/Traceloop attribute names the rest of the SDK
+// sends (see mcp-proxy.js reportTool), so /api/ingest needs no changes.
+
+import { createHash } from "node:crypto";
+
+const MAX_TEXT = 2048;
+
+const hash = (s, n) => createHash("sha256").update(String(s)).digest("hex").slice(0, n);
+const attr = (k, v) => ({ key: k, value: { stringValue: String(v) } });
+const clip = (s) => {
+  const str = typeof s === "string" ? s : JSON.stringify(s ?? "");
+  return str.length > MAX_TEXT ? str.slice(0, MAX_TEXT) + "…" : str;
+};
+
+function toNano(iso) {
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? (BigInt(ms) * 1000000n).toString() : null;
+}
+
+export const traceIdFor = (sessionId) => hash(`session:${sessionId}`, 32);
+export const llmSpanIdFor = (messageId) => hash(`msg:${messageId}`, 16);
+export const toolSpanIdFor = (toolUseId) => hash(`tool:${toolUseId}`, 16);
+
+/** Parse JSONL text into objects, skipping blank or malformed lines. */
+export function parseLines(text) {
+  const out = [];
+  for (const line of String(text || "").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (o && typeof o === "object") out.push(o);
+    } catch {
+      /* partial or foreign line — skip */
+    }
+  }
+  return out;
+}
+
+function contentBlocks(message) {
+  return Array.isArray(message?.content) ? message.content : [];
+}
+
+function promptText(entry) {
+  const c = entry?.message?.content;
+  if (typeof c === "string") return c;
+  return contentBlocks(entry?.message)
+    .filter((b) => b?.type === "text")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+function splitMcp(name) {
+  const m = /^mcp__(.+?)__(.+)$/.exec(name || "");
+  return m ? { server: m[1], tool: m[2] } : null;
+}
+
+/**
+ * Build spans from transcript entries.
+ *
+ * @param {object[]} entries     parsed transcript lines (one batch, in order)
+ * @param {object}   opts
+ * @param {string}   opts.sessionId
+ * @param {{id?:string,type?:string,parentToolUseId?:string}} [opts.agent]  set for subagent transcripts
+ * @param {Set<string>} [opts.sentMessages]  message ids already reported (dedupe across runs)
+ * @param {Set<string>} [opts.sentTools]     tool_use ids already reported
+ * @param {object} [opts.pending]  tool_use ids seen earlier without a result: { id: {name, ts, input} }
+ * @param {boolean} [opts.recordInputs]
+ * @param {boolean} [opts.recordOutputs]
+ * @returns {{ spans: object[], messageIds: string[], toolIds: string[], pending: object }}
+ */
+export function buildSpans(entries, opts = {}) {
+  const sessionId = opts.sessionId || entries.find((e) => e?.sessionId)?.sessionId || "unknown";
+  const traceId = traceIdFor(sessionId);
+  const sentMessages = opts.sentMessages || new Set();
+  const sentTools = opts.sentTools || new Set();
+  const pending = { ...(opts.pending || {}) };
+  const agent = opts.agent || null;
+  const parentSpanId = agent?.parentToolUseId ? toolSpanIdFor(agent.parentToolUseId) : undefined;
+
+  const common = [attr("stratos.surface", "claude-code"), attr("session.id", sessionId)];
+  if (agent) {
+    common.push(attr("stratos.subagent", "true"));
+    if (agent.id) common.push(attr("stratos.agent.id", agent.id));
+    if (agent.type) common.push(attr("stratos.agent.type", agent.type));
+  }
+
+  // Streaming writes one line per content block, each repeating the same
+  // usage — group lines by message id and report each API call once.
+  const calls = new Map();
+  let lastInputTs = null;
+  let lastPrompt = null;
+
+  for (const e of entries) {
+    if (e?.type === "user") {
+      const blocks = contentBlocks(e.message);
+      const results = blocks.filter((b) => b?.type === "tool_result");
+      if (!results.length) {
+        lastPrompt = promptText(e);
+      }
+      for (const r of results) {
+        const id = r.tool_use_id;
+        if (id && pending[id]) pending[id].result = { ts: e.timestamp, isError: !!r.is_error, content: r.content };
+      }
+      if (e.timestamp) lastInputTs = e.timestamp;
+      continue;
+    }
+    if (e?.type !== "assistant" || !e.message) continue;
+
+    const msg = e.message;
+    const key = msg.id || e.requestId || e.uuid;
+    if (!key) continue;
+    let call = calls.get(key);
+    if (!call) {
+      call = {
+        id: key,
+        requestId: e.requestId,
+        model: msg.model,
+        usage: msg.usage || {},
+        stopReason: msg.stop_reason,
+        startTs: lastInputTs || e.timestamp,
+        endTs: e.timestamp,
+        text: [],
+        prompt: lastPrompt,
+        version: e.version,
+      };
+      calls.set(key, call);
+      lastPrompt = null;
+    }
+    call.endTs = e.timestamp || call.endTs;
+    if ((msg.usage?.output_tokens || 0) >= (call.usage.output_tokens || 0)) call.usage = msg.usage || call.usage;
+    if (msg.stop_reason) call.stopReason = msg.stop_reason;
+
+    for (const b of contentBlocks(msg)) {
+      if (b?.type === "text" && b.text) call.text.push(b.text);
+      if (b?.type === "tool_use" && b.id && !sentTools.has(b.id) && !pending[b.id]) {
+        pending[b.id] = { name: b.name || "tool", ts: e.timestamp, input: b.input };
+      }
+    }
+  }
+
+  const spans = [];
+  const messageIds = [];
+
+  for (const call of calls.values()) {
+    if (sentMessages.has(call.id)) continue;
+    if (call.model === "<synthetic>") continue; // local error placeholders, not API calls
+    const u = call.usage || {};
+    const input = u.input_tokens || 0;
+    const output = u.output_tokens || 0;
+    const cacheRead = u.cache_read_input_tokens || 0;
+    const cacheWrite = u.cache_creation_input_tokens || 0;
+    const start = toNano(call.startTs) || toNano(call.endTs);
+    const end = toNano(call.endTs) || start;
+    if (!start) continue;
+
+    const attributes = [
+      attr("traceloop.span.kind", "llm"),
+      attr("traceloop.entity.name", "claude-code"),
+      attr("gen_ai.system", "anthropic"),
+      attr("gen_ai.request.model", call.model || "unknown"),
+      attr("gen_ai.response.model", call.model || "unknown"),
+      attr("gen_ai.usage.input_tokens", input),
+      attr("gen_ai.usage.output_tokens", output),
+      attr("gen_ai.usage.prompt_tokens", input),
+      attr("gen_ai.usage.completion_tokens", output),
+      attr("gen_ai.usage.cache_read_input_tokens", cacheRead),
+      attr("gen_ai.usage.cache_creation_input_tokens", cacheWrite),
+      attr("llm.usage.total_tokens", input + output + cacheRead + cacheWrite),
+      ...common,
+    ];
+    if (u.output_tokens_details?.thinking_tokens != null) {
+      attributes.push(attr("gen_ai.usage.thinking_tokens", u.output_tokens_details.thinking_tokens));
+    }
+    if (call.stopReason) attributes.push(attr("gen_ai.response.finish_reason", call.stopReason));
+    if (call.requestId) attributes.push(attr("stratos.request_id", call.requestId));
+    if (call.version) attributes.push(attr("claude_code.version", call.version));
+    if (opts.recordInputs && call.prompt) attributes.push(attr("traceloop.entity.input", clip(call.prompt)));
+    if (opts.recordOutputs && call.text.length) attributes.push(attr("traceloop.entity.output", clip(call.text.join("\n"))));
+
+    spans.push({
+      traceId,
+      spanId: llmSpanIdFor(call.id),
+      ...(parentSpanId ? { parentSpanId } : {}),
+      name: "anthropic.chat",
+      kind: 3,
+      startTimeUnixNano: start,
+      endTimeUnixNano: end,
+      attributes,
+    });
+    messageIds.push(call.id);
+  }
+
+  const toolIds = [];
+  for (const [id, t] of Object.entries(pending)) {
+    if (!t.result || sentTools.has(id)) continue;
+    const start = toNano(t.ts) || toNano(t.result.ts);
+    const end = toNano(t.result.ts) || start;
+    if (!start) continue;
+    const attributes = [
+      attr("traceloop.span.kind", "tool"),
+      attr("traceloop.entity.name", t.name),
+      attr("stratos.tool.is_error", t.result.isError),
+      ...common,
+    ];
+    const mcp = splitMcp(t.name);
+    if (mcp) attributes.push(attr("mcp.server", mcp.server), attr("mcp.tool", mcp.tool));
+    if (opts.recordInputs) {
+      attributes.push(attr("traceloop.entity.input", clip({ tool_name: t.name, arguments: t.input ?? {} })));
+    }
+    if (opts.recordOutputs) {
+      attributes.push(attr("traceloop.entity.output", clip({ content: t.result.content, is_error: t.result.isError })));
+    }
+    spans.push({
+      traceId,
+      spanId: toolSpanIdFor(id),
+      ...(parentSpanId ? { parentSpanId } : {}),
+      name: `${t.name}.tool`,
+      kind: 1,
+      startTimeUnixNano: start,
+      endTimeUnixNano: end,
+      attributes,
+      ...(t.result.isError ? { status: { code: 2 } } : {}),
+    });
+    toolIds.push(id);
+    delete pending[id];
+  }
+
+  // Strip bulky inputs from what is carried over to the next run.
+  for (const t of Object.values(pending)) {
+    if (!opts.recordInputs) delete t.input;
+    if (t.result && !opts.recordOutputs) delete t.result.content;
+  }
+
+  return { spans, messageIds, toolIds, pending };
+}
+
+/** Wrap spans in an OTLP/JSON body for POST /api/ingest. */
+export function toOtlpPayload(spans, { serviceName = "claude-code", version } = {}) {
+  const resource = [attr("service.name", serviceName), attr("stratos.surface", "claude-code")];
+  if (version) resource.push(attr("claude_code.version", version));
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: resource },
+        scopeSpans: [{ scope: { name: "stratos-sdk.claude-code" }, spans }],
+      },
+    ],
+  };
+}

package/src/cli-doctor.js

@@ -0,0 +1,127 @@
+// `stratos doctor` — check the Claude Code ↔ Stratos connection.
+// Reads the files setup writes (not this shell's environment), so it gives the
+// same answer no matter where it is run from.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import spawn from "cross-spawn";
+import {
+  HOOK_EVENTS,
+  claudeSettingsPath,
+  configExists,
+  configFile,
+  hasLegacyNodeOptions,
+  isStratosHook,
+  loadConfig,
+  stratosDir,
+} from "./claude-code/settings.js";
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Paths quoted in a hook command, e.g. node "C:/…/cli.js" hook stop */
+const quotedPaths = (cmd) => [...cmd.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+
+export async function doctorCommand() {
+  console.log("[stratos-doctor] Checking Claude Code → Stratos…\n");
+  let failed = 0;
+  const fixes = [];
+  const ok = (m) => console.log(`✓ ${m}`);
+  const warn = (m, fix) => {
+    console.log(`⚠ ${m}`);
+    if (fix) fixes.push(fix);
+  };
+  const fail = (m, fix) => {
+    console.log(`✗ ${m}`);
+    failed++;
+    if (fix) fixes.push(fix);
+  };
+
+  const cfg = loadConfig();
+  if (configExists()) ok(`Config: ${configFile()}`);
+  else if (cfg.token) warn("No config file — using STRATOS_* environment variables", "Run: stratos setup claude-code");
+  else fail("No Stratos config", "Run: stratos setup claude-code --token <token> --url <url>");
+
+  // The token format is the server's business; whether it is valid is checked below against Stratos itself.
+  if (cfg.token) ok("Token present");
+  else fail("Token missing", "Run: stratos setup claude-code --token <token>");
+
+  const local = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(cfg.url);
+  if (cfg.url.startsWith("https://") || local) ok(`Server: ${cfg.url}`);
+  else warn(`Server ${cfg.url} is plain http — token is sent unencrypted`);
+
+  const settingsPath = claudeSettingsPath();
+  const settings = existsSync(settingsPath) ? readJson(settingsPath) : null;
+  if (!settings) {
+    fail(`Cannot read ${settingsPath}`, "Run: stratos setup claude-code");
+  } else {
+    for (const event of Object.keys(HOOK_EVENTS)) {
+      const handlers = (settings.hooks?.[event] || []).flatMap((g) => g?.hooks || []);
+      const ours = handlers.find(isStratosHook);
+      if (!ours) {
+        fail(`Hook ${event} missing`, "Run: stratos setup claude-code");
+        continue;
+      }
+      const missing = quotedPaths(ours.command).filter((p) => !existsSync(p));
+      if (missing.length) fail(`Hook ${event} points at missing file: ${missing.join(", ")}`, "Re-run: stratos setup claude-code");
+      else ok(`Hook ${event}`);
+    }
+    const nodeOnPath = spawn.sync("node", ["--version"], { encoding: "utf8", timeout: 5000 });
+    if (nodeOnPath.status === 0) ok(`node on PATH (${nodeOnPath.stdout.trim()}) — hooks can start`);
+    else fail("`node` is not on PATH, so the hooks cannot start", "Add Node.js to PATH, then restart Claude Code");
+    if (hasLegacyNodeOptions(settings.env)) {
+      fail(
+        "settings.json env still sets NODE_OPTIONS=--import …stratos-sdk/register (breaks Node commands Claude runs)",
+        "Re-run: stratos setup claude-code (removes it)"
+      );
+    }
+    if (settings.env?.STRATOS_TOKEN) {
+      warn("settings.json env contains STRATOS_TOKEN — visible to every command Claude runs", "Re-run: stratos setup claude-code (moves it)");
+    }
+  }
+
+  const status = readJson(join(stratosDir(), "status.json")) || {};
+  if (status.lastSendAt) ok(`Last successful send: ${status.lastSendAt}`);
+  else console.log("· No usage sent yet (expected until a Claude Code session finishes a turn)");
+  if (status.lastError) warn(`Last error: ${status.lastError}`);
+
+  const outbox = join(stratosDir(), "outbox");
+  if (existsSync(outbox)) {
+    const files = readdirSync(outbox).filter((f) => f.endsWith(".json"));
+    if (files.length) {
+      const kb = Math.round(files.reduce((n, f) => n + statSync(join(outbox, f)).size, 0) / 1024);
+      warn(`${files.length} undelivered batch(es) waiting in outbox (${kb} KB) — sent on the next hook once Stratos is reachable`);
+    }
+  }
+
+  if (cfg.token) {
+    try {
+      const res = await fetch(`${cfg.url}/api/heartbeat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-stratos-token": cfg.token },
+        body: JSON.stringify({ framework: "claude-code", model: null, tools: [], doctor: true }),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) ok("Stratos accepted the token");
+      else if (res.status === 401 || res.status === 403) fail(`Stratos rejected the token (${res.status})`, "Check the token in Stratos > Add agent");
+      else fail(`Stratos returned ${res.status}`, `Check the URL: ${cfg.url}`);
+    } catch (err) {
+      fail(`Cannot reach ${cfg.url}: ${err.cause?.code || err.message}`, "Check network, VPN or firewall, and the URL");
+    }
+  }
+
+  console.log("\n" + "=".repeat(60));
+  if (!failed) {
+    console.log("✓ All checks passed — new Claude Code sessions report usage to Stratos.");
+  } else {
+    console.log(`✗ ${failed} check(s) failed`);
+    [...new Set(fixes)].forEach((f, i) => console.log(`  ${i + 1}. ${f}`));
+    process.exitCode = 1;
+  }
+  console.log("=".repeat(60));
+}

package/src/cli-env.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+class EnvError extends Error {}
+
+function isNodeProject() {
+  return existsSync(join(process.cwd(), "package.json"));
+}
+
+function envPath() {
+  return join(process.cwd(), ".env");
+}
+
+function readEnvFile(path) {
+  if (!existsSync(path)) return "";
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function backup(path) {
+  if (!existsSync(path)) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dest = `${path}.stratos-backup-${stamp}`;
+  try {
+    copyFileSync(path, dest);
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+function parseEnvFile(content) {
+  const lines = content.split("\n");
+  const vars = new Map();
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const [key, ...valueParts] = trimmed.split("=");
+    if (key) vars.set(key, valueParts.join("="));
+  }
+  return vars;
+}
+
+function buildEnvContent(vars) {
+  return Array.from(vars.entries())
+    .map(([key, value]) => `${key}=${value}`)
+    .join("\n") + "\n";
+}
+
+export async function envAddCommand(...varStrings) {
+  try {
+    // Check if in a Node.js project
+    if (!isNodeProject()) {
+      throw new EnvError(
+        "Not a Node.js project. Run this command from your project root (where package.json is)."
+      );
+    }
+
+    // Validate we have at least one var
+    if (varStrings.length === 0) {
+      throw new EnvError("Invalid format. Use: stratos env add KEY=value [KEY2=value2 ...]");
+    }
+
+    // Parse and validate all variables
+    const newVars = new Map();
+    for (const varString of varStrings) {
+      if (!varString || !varString.includes("=")) {
+        throw new EnvError(`Invalid format: ${varString}. Use: KEY=value`);
+      }
+
+      const [key, ...valueParts] = varString.split("=");
+      if (!key || !key.match(/^[A-Z_][A-Z0-9_]*$/i)) {
+        throw new EnvError(`Invalid variable name: ${key}`);
+      }
+
+      newVars.set(key, valueParts.join("="));
+    }
+
+    const path = envPath();
+
+    // Read existing .env if it exists
+    const existingContent = readEnvFile(path);
+    const vars = parseEnvFile(existingContent);
+
+    // Create directory if needed
+    const dir = process.cwd();
+    await mkdir(dir, { recursive: true });
+
+    // Backup existing .env if present
+    let backupPath = null;
+    if (existsSync(path)) {
+      backupPath = backup(path);
+    }
+
+    // Process each new variable
+    for (const [key, value] of newVars.entries()) {
+      if (vars.has(key)) {
+        const oldValue = vars.get(key);
+        if (oldValue === value) {
+          console.log(`✓ ${key}=${value} already set`);
+        } else {
+          console.log(`✓ Updated ${key} (was: ${oldValue})`);
+          vars.set(key, value);
+        }
+      } else {
+        console.log(`✓ Added ${key}=${value}`);
+        vars.set(key, value);
+      }
+    }
+
+    // Show backup message if one was created
+    if (backupPath) {
+      console.log(`  backup: ${backupPath}`);
+    }
+
+    // Write new .env file
+    const newContent = buildEnvContent(vars);
+    writeFileSync(path, newContent, "utf8");
+    console.log(`✓ Updated .env`);
+  } catch (err) {
+    if (err instanceof EnvError) {
+      console.error(`[stratos] ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}