@xdelivered/emberflow 0.2.0

package/server/infrastructure.test.ts

@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadInfrastructure } from './infrastructure';
+
+function project(): string {
+  const root = mkdtempSync(join(tmpdir(), 'infra-'));
+  mkdirSync(join(root, 'emberflow'), { recursive: true });
+  return root;
+}
+
+function writeManifest(root: string, contents: string): void {
+  writeFileSync(join(root, 'emberflow', 'infrastructure.json'), contents);
+}
+
+describe('loadInfrastructure', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = project();
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('returns null (no warning) when the file is absent', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(loadInfrastructure(root)).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('loads a well-formed manifest, preserving fields', () => {
+    writeManifest(
+      root,
+      JSON.stringify({
+        version: 1,
+        scannedAt: '2026-07-12T00:00:00Z',
+        greenfield: false,
+        summary: 'Express app with Postgres (Prisma) and Stripe.',
+        items: [
+          {
+            id: 'postgres-main',
+            kind: 'database',
+            name: 'Postgres (Prisma)',
+            evidence: [{ file: 'prisma/schema.prisma', note: 'datasource db provider=postgresql' }],
+            suggestedSecretRefs: ['DATABASE_URL'],
+            suggestedVars: [],
+            notes: 'Schema defines User, Order, Invoice models.',
+          },
+        ],
+      }),
+    );
+    const manifest = loadInfrastructure(root);
+    expect(manifest).not.toBeNull();
+    expect(manifest!.summary).toContain('Postgres');
+    expect(manifest!.items).toHaveLength(1);
+    expect(manifest!.items[0]).toMatchObject({
+      id: 'postgres-main',
+      kind: 'database',
+      name: 'Postgres (Prisma)',
+      suggestedSecretRefs: ['DATABASE_URL'],
+    });
+    expect(manifest!.items[0].evidence[0]).toEqual({ file: 'prisma/schema.prisma', note: 'datasource db provider=postgresql' });
+  });
+
+  it('preserves unknown top-level and item fields (forward compatibility)', () => {
+    writeManifest(
+      root,
+      JSON.stringify({
+        version: 2,
+        greenfield: false,
+        futureTopField: 'keep me',
+        items: [{ id: 'x', kind: 'cache', name: 'Redis', futureItemField: 42 }],
+      }),
+    );
+    const manifest = loadInfrastructure(root);
+    expect(manifest!.futureTopField).toBe('keep me');
+    expect(manifest!.items[0].futureItemField).toBe(42);
+    expect(manifest!.version).toBe(2);
+  });
+
+  it('clamps an unknown item kind to "other" and defaults missing required fields', () => {
+    writeManifest(
+      root,
+      JSON.stringify({
+        greenfield: false,
+        items: [{ kind: 'blockchain' }],
+      }),
+    );
+    const manifest = loadInfrastructure(root);
+    expect(manifest!.items[0].kind).toBe('other');
+    expect(manifest!.items[0].name).toBe('Unnamed');
+    expect(manifest!.items[0].id).toBe('item-0');
+    expect(manifest!.items[0].evidence).toEqual([]);
+    expect(manifest!.items[0].suggestedSecretRefs).toEqual([]);
+    // version defaults to 1 when absent.
+    expect(manifest!.version).toBe(1);
+  });
+
+  it('supports a greenfield manifest with empty items', () => {
+    writeManifest(root, JSON.stringify({ version: 1, greenfield: true, summary: 'Empty project.', items: [] }));
+    const manifest = loadInfrastructure(root);
+    expect(manifest!.greenfield).toBe(true);
+    expect(manifest!.items).toEqual([]);
+  });
+
+  it('returns null + one warning on invalid JSON', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeManifest(root, '{ not json');
+    expect(loadInfrastructure(root)).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(1);
+    // Repeat load: deduped, no second warning.
+    expect(loadInfrastructure(root)).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it('the invalid-JSON warning never echoes the parse error message (no file-content leakage)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // A "secret" fragment near the break point — JSON.parse's own error
+    // message would normally quote a few characters around here.
+    writeManifest(root, '{ "token": "sk_live_super_secret_value丹');
+    expect(loadInfrastructure(root)).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const message = warn.mock.calls[0][0] as string;
+    expect(message).toContain('is not valid JSON');
+    expect(message).not.toContain('sk_live_super_secret_value');
+    warn.mockRestore();
+  });
+
+  it('returns null + warning when items is not an array', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    writeManifest(root, JSON.stringify({ version: 1, greenfield: false, items: 'nope' }));
+    expect(loadInfrastructure(root)).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it('drops non-object items but keeps the valid siblings', () => {
+    writeManifest(
+      root,
+      JSON.stringify({
+        version: 1,
+        greenfield: false,
+        items: [null, 'bad', { id: 'ok', kind: 'llm', name: 'OpenAI' }],
+      }),
+    );
+    const manifest = loadInfrastructure(root);
+    expect(manifest!.items).toHaveLength(1);
+    expect(manifest!.items[0].name).toBe('OpenAI');
+  });
+});

package/server/infrastructure.ts

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The committed, secrets-free infrastructure manifest the scout writes to
+ * `emberflow/infrastructure.json` and agents/studio read back. It describes
+ * what a (usually brownfield) project already uses — databases, external APIs,
+ * providers — with evidence pointing at the files that prove it. Env-var
+ * NAMES only ever appear here; never values.
+ */
+
+/** The closed set of infrastructure categories the scout classifies items into. */
+export const INFRASTRUCTURE_KINDS = [
+  'database',
+  'http-api',
+  'queue',
+  'cache',
+  'email',
+  'llm',
+  'auth',
+  'framework',
+  'storage',
+  'other',
+] as const;
+
+export type InfrastructureKind = (typeof INFRASTRUCTURE_KINDS)[number];
+
+/** A single file:note pointer proving an item exists. `note` is optional. */
+export interface InfrastructureEvidence {
+  file: string;
+  note?: string;
+  /** Unknown fields are preserved on read (forward-compatibility). */
+  [key: string]: unknown;
+}
+
+/** One discovered piece of infrastructure. */
+export interface InfrastructureItem {
+  id: string;
+  kind: InfrastructureKind;
+  name: string;
+  evidence: InfrastructureEvidence[];
+  /** Env-var NAMES this item likely needs (e.g. "DATABASE_URL") — never values. */
+  suggestedSecretRefs: string[];
+  /** Non-secret config var NAMES this item likely needs. */
+  suggestedVars: string[];
+  notes?: string;
+  /** Unknown fields are preserved on read (forward-compatibility). */
+  [key: string]: unknown;
+}
+
+export interface InfrastructureManifest {
+  version: number;
+  scannedAt?: string;
+  greenfield: boolean;
+  summary?: string;
+  items: InfrastructureItem[];
+  /** Unknown top-level fields are preserved on read (forward-compatibility). */
+  [key: string]: unknown;
+}
+
+export const INFRASTRUCTURE_FILENAME = join('emberflow', 'infrastructure.json');
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isInfrastructureKind(value: unknown): value is InfrastructureKind {
+  return typeof value === 'string' && (INFRASTRUCTURE_KINDS as readonly string[]).includes(value);
+}
+
+/**
+ * Leniently coerces one raw item into an `InfrastructureItem`. Missing/invalid
+ * required fields are defaulted rather than rejected (name/id fall back,
+ * unknown `kind` normalizes to "other") and unknown fields pass through, so a
+ * slightly-off item from the agent still renders instead of nuking the whole
+ * manifest. Returns null only when the item isn't an object at all.
+ */
+function coerceItem(raw: unknown, index: number): InfrastructureItem | null {
+  if (!isPlainObject(raw)) return null;
+  const evidenceRaw = Array.isArray(raw.evidence) ? raw.evidence : [];
+  const evidence: InfrastructureEvidence[] = evidenceRaw
+    .filter(isPlainObject)
+    .map((e) => ({ ...e, file: typeof e.file === 'string' ? e.file : '', note: typeof e.note === 'string' ? e.note : undefined }));
+  const secretRefs = Array.isArray(raw.suggestedSecretRefs)
+    ? raw.suggestedSecretRefs.filter((s): s is string => typeof s === 'string')
+    : [];
+  const vars = Array.isArray(raw.suggestedVars)
+    ? raw.suggestedVars.filter((s): s is string => typeof s === 'string')
+    : [];
+  return {
+    ...raw,
+    id: typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : `item-${index}`,
+    kind: isInfrastructureKind(raw.kind) ? raw.kind : 'other',
+    name: typeof raw.name === 'string' && raw.name.length > 0 ? raw.name : 'Unnamed',
+    evidence,
+    suggestedSecretRefs: secretRefs,
+    suggestedVars: vars,
+    ...(typeof raw.notes === 'string' ? { notes: raw.notes } : {}),
+  };
+}
+
+/** One-shot per-path warn dedupe so repeated GETs don't spam the log. */
+const warnedOnce = new Set<string>();
+
+/**
+ * Reads `emberflow/infrastructure.json` from `projectRoot`.
+ *
+ * - Absent file → `null` (no warning: not-scouted-yet is a normal state).
+ * - Malformed (unreadable, invalid JSON, or not the expected shape) → `null`
+ *   plus a single warning per path per process. The CALLER decides keep-last-good.
+ * - Valid → a leniently-normalized `InfrastructureManifest`: required fields
+ *   defaulted, item `kind`s clamped to the enum, unknown fields preserved.
+ */
+export function loadInfrastructure(projectRoot: string): InfrastructureManifest | null {
+  const path = join(projectRoot, INFRASTRUCTURE_FILENAME);
+  if (!existsSync(path)) return null;
+
+  const warn = (message: string): null => {
+    if (!warnedOnce.has(path)) {
+      warnedOnce.add(path);
+      console.warn(`[emberflow] ${INFRASTRUCTURE_FILENAME} ${message} — ignoring it (keeping last good state). Re-run the infrastructure scout to regenerate it.`);
+    }
+    return null;
+  };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    // Deliberately NOT interpolating the parse error's message: on malformed
+    // JSON, JSON.parse's error text often echoes a fragment of the file
+    // content around the failure point (e.g. "Unexpected token o in JSON at
+    // position 5 ... <10 chars of the file>"), which could leak a fragment of
+    // a secret value if one was pasted into this file. Keep the warning generic.
+    return warn('is not valid JSON');
+  }
+  if (!isPlainObject(parsed)) {
+    return warn('is not a JSON object at the top level');
+  }
+  if (parsed.items !== undefined && !Array.isArray(parsed.items)) {
+    return warn('has an "items" field that is not an array');
+  }
+
+  // A successful read clears any prior warning for this path, so a fixed file
+  // warns again cleanly if it later regresses.
+  warnedOnce.delete(path);
+
+  const rawItems = Array.isArray(parsed.items) ? parsed.items : [];
+  const items = rawItems
+    .map((item, i) => coerceItem(item, i))
+    .filter((item): item is InfrastructureItem => item !== null);
+
+  return {
+    ...parsed,
+    version: typeof parsed.version === 'number' ? parsed.version : 1,
+    ...(typeof parsed.scannedAt === 'string' ? { scannedAt: parsed.scannedAt } : {}),
+    greenfield: parsed.greenfield === true,
+    ...(typeof parsed.summary === 'string' ? { summary: parsed.summary } : {}),
+    items,
+  };
+}

package/server/infrastructureRoute.test.ts

@@ -0,0 +1,105 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Boots a real runner subprocess over a temp project (the setupStatus.test.ts
+// pattern) and drives GET /infrastructure + the /setup-status infrastructure
+// field. The route re-reads per request, so one runner covers absent → present
+// → malformed (keep-last-good) by rewriting the file between fetches.
+
+const PORT = 8154;
+const base = `http://127.0.0.1:${PORT}`;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+let proc: ChildProcess;
+let projectDir: string;
+
+const manifestPath = (): string => join(projectDir, 'emberflow', 'infrastructure.json');
+
+const GOOD_MANIFEST = {
+  version: 1,
+  scannedAt: '2026-07-12T00:00:00Z',
+  greenfield: false,
+  summary: 'Express app with Postgres (Prisma).',
+  items: [
+    {
+      id: 'postgres-main',
+      kind: 'database',
+      name: 'Postgres (Prisma)',
+      evidence: [{ file: 'prisma/schema.prisma', note: 'datasource db provider=postgresql' }],
+      suggestedSecretRefs: ['DATABASE_URL'],
+      suggestedVars: [],
+    },
+  ],
+};
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'infraroute-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+
+  proc = spawn('npx', ['tsx', 'server/index.ts'], {
+    env: {
+      ...process.env,
+      EMBERFLOW_RUNNER_PORT: String(PORT),
+      EMBERFLOW_PROJECT: projectDir,
+    },
+    stdio: 'ignore',
+  });
+
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('GET /infrastructure', () => {
+  it('reports not present when no manifest exists', async () => {
+    const res = await fetch(`${base}/infrastructure`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ present: false });
+
+    // /setup-status agrees.
+    const status = await (await fetch(`${base}/setup-status`)).json();
+    expect(status.infrastructure).toEqual({ present: false });
+  });
+
+  it('serves the manifest once written (re-read per request)', async () => {
+    writeFileSync(manifestPath(), JSON.stringify(GOOD_MANIFEST));
+    const body = await (await fetch(`${base}/infrastructure`)).json();
+    expect(body.present).toBe(true);
+    expect(body.manifest.items).toHaveLength(1);
+    expect(body.manifest.items[0].name).toBe('Postgres (Prisma)');
+
+    // /setup-status carries the shallow summary from the same loader.
+    const status = await (await fetch(`${base}/setup-status`)).json();
+    expect(status.infrastructure).toEqual({
+      present: true,
+      scannedAt: '2026-07-12T00:00:00Z',
+      itemCount: 1,
+    });
+  });
+
+  it('keeps the last good manifest when the file becomes malformed', async () => {
+    writeFileSync(manifestPath(), '{ broken json');
+    const body = await (await fetch(`${base}/infrastructure`)).json();
+    // Still present, still the last good manifest.
+    expect(body.present).toBe(true);
+    expect(body.manifest.items[0].name).toBe('Postgres (Prisma)');
+  });
+});

package/server/login.test.ts

@@ -0,0 +1,153 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { performLogin } from './login';
+import type { EnvironmentDefinition } from './environments';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'emberflow-login-test-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function write(name: string, contents: unknown): void {
+  writeFileSync(join(dir, name), typeof contents === 'string' ? contents : JSON.stringify(contents));
+}
+
+function baseEnvDef(): EnvironmentDefinition {
+  return {
+    vars: {},
+    secrets: {},
+    auth: {
+      attach: { as: 'cookie', name: 'session', secretRef: 'sessionCookie' },
+      login: {
+        request: { method: 'POST', url: 'https://example.test/login' },
+        capture: { from: 'set-cookie', cookieName: 'session' },
+      },
+    },
+  };
+}
+
+describe('performLogin', () => {
+  it('fires the login request, captures the credential, and stores it', async () => {
+    write('emberflow.environments.json', {
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: {} } },
+    });
+    const envDef = baseEnvDef();
+
+    const fetchMock = async () => ({
+      status: 200,
+      headers: new Headers({ 'set-cookie': 'session=zzz; Path=/' }),
+      json: async () => ({}),
+    });
+
+    const result = await performLogin(dir, 'local', envDef, { fetch: fetchMock as unknown as typeof fetch });
+
+    expect(result).toEqual({ secretRef: 'sessionCookie' });
+
+    // The captured credential VALUE lands in the secrets file (keyed by env),
+    // never in environments.json — which now records only the key name.
+    const secrets = JSON.parse(readFileSync(join(dir, 'emberflow.secrets.json'), 'utf8'));
+    expect(secrets.local.sessionCookie).toBe('zzz');
+    const stored = JSON.parse(readFileSync(join(dir, 'emberflow.environments.json'), 'utf8'));
+    expect(stored.environments.local.secrets).toContain('sessionCookie');
+    expect(JSON.stringify(stored)).not.toContain('zzz');
+  });
+
+  it('sends the parsed bodyRef secret as the request body (default content-type)', async () => {
+    write('emberflow.environments.json', {
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: {} } },
+    });
+    const envDef = baseEnvDef();
+    envDef.secrets.loginBody = '{"email":"a@b.test","password":"pw"}';
+    envDef.auth!.login!.request.bodyRef = 'loginBody';
+
+    let capturedInit: RequestInit | undefined;
+    const fetchMock = async (_url: string, init?: RequestInit) => {
+      capturedInit = init;
+      return {
+        status: 200,
+        headers: new Headers({ 'set-cookie': 'session=zzz; Path=/' }),
+        json: async () => ({}),
+      };
+    };
+
+    await performLogin(dir, 'local', envDef, { fetch: fetchMock as unknown as typeof fetch });
+
+    expect(capturedInit?.body).toBe(JSON.stringify({ email: 'a@b.test', password: 'pw' }));
+    expect((capturedInit?.headers as Record<string, string>)['content-type']).toBe('application/json');
+  });
+
+  it('lets an explicitly cased request content-type header override the default', async () => {
+    write('emberflow.environments.json', {
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: {} } },
+    });
+    const envDef = baseEnvDef();
+    envDef.secrets.loginBody = '{"email":"a@b.test"}';
+    envDef.auth!.login!.request.bodyRef = 'loginBody';
+    envDef.auth!.login!.request.headers = { 'Content-Type': 'application/vnd.api+json' };
+
+    let capturedInit: RequestInit | undefined;
+    const fetchMock = async (_url: string, init?: RequestInit) => {
+      capturedInit = init;
+      return {
+        status: 200,
+        headers: new Headers({ 'set-cookie': 'session=zzz; Path=/' }),
+        json: async () => ({}),
+      };
+    };
+
+    await performLogin(dir, 'local', envDef, { fetch: fetchMock as unknown as typeof fetch });
+
+    const headers = capturedInit?.headers as Record<string, string>;
+    // Caller's content-type wins, and there is no duplicate differently-cased key.
+    expect(headers['content-type']).toBe('application/vnd.api+json');
+    expect(headers['Content-Type']).toBeUndefined();
+  });
+
+  it('throws when the bodyRef secret is not valid JSON', async () => {
+    write('emberflow.environments.json', {
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: {} } },
+    });
+    const envDef = baseEnvDef();
+    envDef.secrets.loginBody = 'not-json{';
+    envDef.auth!.login!.request.bodyRef = 'loginBody';
+
+    const fetchMock = async () => ({
+      status: 200,
+      headers: new Headers({ 'set-cookie': 'session=zzz' }),
+      json: async () => ({}),
+    });
+
+    await expect(
+      performLogin(dir, 'local', envDef, { fetch: fetchMock as unknown as typeof fetch }),
+    ).rejects.toThrow('login body secret "loginBody" for environment "local" is not valid JSON');
+  });
+
+  it('throws when the login response is non-2xx', async () => {
+    write('emberflow.environments.json', {
+      defaultEnvironment: 'local',
+      environments: { local: { vars: {}, secrets: {} } },
+    });
+    const envDef = baseEnvDef();
+
+    const fetchMock = async () => ({
+      status: 401,
+      headers: new Headers(),
+      json: async () => ({}),
+    });
+
+    await expect(
+      performLogin(dir, 'local', envDef, { fetch: fetchMock as unknown as typeof fetch }),
+    ).rejects.toThrow('login failed: 401');
+  });
+});

package/server/login.ts

@@ -0,0 +1,67 @@
+import { captureCredential } from './authAttach';
+import { setEnvironmentSecret, type EnvironmentDefinition } from './environments';
+
+/** Minimal response shape performLogin needs from the injected fetch. */
+interface LoginResponse {
+  status: number;
+  headers: Headers;
+  json: () => Promise<any>;
+}
+
+export interface PerformLoginDeps {
+  fetch: (url: string, init?: RequestInit) => Promise<LoginResponse>;
+}
+
+/**
+ * Fires the configured login request for `envName`, captures the resulting
+ * credential per `envDef.auth.login.capture`, and persists it into the
+ * environment's secrets under `envDef.auth.attach.secretRef`.
+ *
+ * Never returns or logs the captured value — only the secretRef name.
+ */
+export async function performLogin(
+  cwd: string,
+  envName: string,
+  envDef: EnvironmentDefinition,
+  deps: PerformLoginDeps = { fetch: globalThis.fetch },
+): Promise<{ secretRef: string }> {
+  const login = envDef.auth?.login;
+  if (!login) {
+    throw new Error(`environment "${envName}" has no auth.login configured`);
+  }
+
+  const { method, url, headers, bodyRef } = login.request;
+  const init: RequestInit = { method, ...(headers ? { headers } : {}) };
+  if (bodyRef !== undefined) {
+    const rawBody = envDef.secrets[bodyRef];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+      // Never include the secret content in the message — only names.
+      throw new Error(`login body secret "${bodyRef}" for environment "${envName}" is not valid JSON`);
+    }
+    init.body = JSON.stringify(parsed);
+    // Lowercase all caller header keys so an explicit content-type (any casing)
+    // wins over — and never duplicates — the auto-added default.
+    const callerHeaders = Object.fromEntries(
+      Object.entries(headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]),
+    );
+    init.headers = { 'content-type': 'application/json', ...callerHeaders };
+  }
+
+  const res = await deps.fetch(url, init);
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error(`login failed: ${res.status}`);
+  }
+
+  const value = await captureCredential(res, login.capture);
+  if (value === null) {
+    throw new Error('login succeeded but no credential captured');
+  }
+
+  const secretRef = envDef.auth!.attach.secretRef;
+  await setEnvironmentSecret(cwd, envName, secretRef, value);
+
+  return { secretRef };
+}