fix(sdk): http adapter — headers option, listVersions/loadFrom doc, flush-drains-two test

- Add optional headers?: HeadersInit | (() => HeadersInit) to HttpAdapterOptions
  for cross-origin / CLI / auth injection (function form refreshes on each PUT)
- Document listVersions/loadFrom as intentional no-ops (server versioning not exposed)
- Add flush-drains-two-concurrent-writes test to mirror fs adapter T13 coverage

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>

Author: vanceingalls

packages/sdk/src/adapters/http.test.ts

@@ -117,6 +117,39 @@ describe("write()", () => {
   });
 });
 
+// ── headers option ───────────────────────────────────────────────────────────
+
+describe("headers option", () => {
+  it("merges static headers into every PUT request", async () => {
+    const mock = stubFetch(() => ({ ok: true }));
+    const adapter = createHttpAdapter({
+      projectFilesUrl: BASE,
+      headers: { Authorization: "Bearer tok" },
+    });
+    await adapter.write("comp.html", "x");
+    expect(mock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: "Bearer tok" }),
+      }),
+    );
+  });
+
+  it("calls a headers function lazily on each write", async () => {
+    const mock = stubFetch(() => ({ ok: true }));
+    let n = 0;
+    const adapter = createHttpAdapter({
+      projectFilesUrl: BASE,
+      headers: () => ({ Authorization: `Bearer tok${++n}` }),
+    });
+    await adapter.write("comp.html", "a");
+    await adapter.write("comp.html", "b");
+    const calls = mock.mock.calls.filter((c) => c[1]?.method === "PUT");
+    expect((calls[0][1]?.headers as Record<string, string>)?.["Authorization"]).toBe("Bearer tok1");
+    expect((calls[1][1]?.headers as Record<string, string>)?.["Authorization"]).toBe("Bearer tok2");
+  });
+});
+
 // ── flush() ───────────────────────────────────────────────────────────────────
 
 describe("flush()", () => {
@@ -150,6 +183,35 @@ describe("flush()", () => {
     await flushDone;
     expect(flushed).toBe(true);
   });
+
+  it("waits for two concurrent in-flight writes before resolving", async () => {
+    const resolvers: Array<() => void> = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === "PUT") {
+          await new Promise<void>((r) => resolvers.push(r));
+        }
+        return { ok: true, status: 200, json: async () => ({}) };
+      }),
+    );
+    const adapter = createHttpAdapter({ projectFilesUrl: BASE });
+    void adapter.write("a.html", "1");
+    void adapter.write("b.html", "2");
+    await Promise.resolve(); // let both start
+    await Promise.resolve();
+    let flushed = false;
+    const flushDone = adapter.flush().then(() => {
+      flushed = true;
+    });
+    expect(flushed).toBe(false);
+    resolvers[0]();
+    await Promise.resolve();
+    expect(flushed).toBe(false); // still waiting for second write
+    resolvers[1]();
+    await flushDone;
+    expect(flushed).toBe(true);
+  });
 });
 
 // ── listVersions() / loadFrom() ───────────────────────────────────────────────

packages/sdk/src/adapters/http.ts

@@ -7,16 +7,24 @@ export interface HttpAdapterOptions {
    * E.g. "/api/projects/proj-abc"
    */
   projectFilesUrl: string;
+  /**
+   * Extra headers to include on every PUT write request.
+   * Pass a function to compute them lazily (e.g. to refresh a bearer token on each request).
+   * Useful for cross-origin or CLI contexts where ambient cookies are not available.
+   */
+  headers?: HeadersInit | (() => HeadersInit);
 }
 
 class HttpAdapter implements PersistAdapter {
   private readonly baseUrl: string;
+  private readonly extraHeaders?: HttpAdapterOptions["headers"];
   private readonly errorListeners: Array<(e: PersistErrorEvent) => void> = [];
   private readonly inflightWrites = new Set<Promise<void>>();
   private readonly pathQueues = new Map<string, Promise<void>>();
 
   constructor(opts: HttpAdapterOptions) {
     this.baseUrl = opts.projectFilesUrl;
+    this.extraHeaders = opts.headers;
   }
 
   async read(path: string): Promise<string | undefined> {
@@ -46,9 +54,11 @@ class HttpAdapter implements PersistAdapter {
     const url = `${this.baseUrl}/files/${encodeURIComponent(path)}`;
     let res: Response;
     try {
+      const extra =
+        typeof this.extraHeaders === "function" ? this.extraHeaders() : this.extraHeaders;
       res = await fetch(url, {
         method: "PUT",
-        headers: { "Content-Type": "text/plain" },
+        headers: { "Content-Type": "text/plain", ...extra },
         body: content,
       });
     } catch (err) {
@@ -64,10 +74,12 @@ class HttpAdapter implements PersistAdapter {
     await Promise.all([...this.inflightWrites]);
   }
 
+  /** Server-side versioning is not exposed by this adapter; returns [] intentionally. */
   async listVersions(_path: string): Promise<PersistVersionEntry[]> {
     return [];
   }
 
+  /** Server-side versioning is not exposed by this adapter; returns undefined intentionally. */
   async loadFrom(_path: string, _versionKey: string): Promise<string | undefined> {
     return undefined;
   }