@localpulse/cli 0.0.1

package/src/lib/cli-read-client.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it, mock } from "bun:test";
+
+import { CliApiError } from "./api-response";
+import {
+  fetchCliInfo,
+  searchCliEvents,
+} from "./cli-read-client";
+
+const ORIGINAL_FETCH = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = ORIGINAL_FETCH;
+});
+
+describe("cli-read-client", () => {
+  it("fetches CLI info over REST", async () => {
+    globalThis.fetch = mock(async (input, init) => {
+      expect(String(input)).toBe("https://localpulse.nl/api/cli/info");
+      expect(init?.method).toBe("GET");
+      return new Response(
+        JSON.stringify({
+          version: "v1",
+          mode: "read_write",
+          surface: "rest",
+          ingest_directives_version: "2026-03-11",
+          links: {
+            onboarding_url: "https://localpulse.nl/dev",
+            website_url: "https://localpulse.nl/",
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    expect(await fetchCliInfo("https://localpulse.nl")).toMatchObject({
+      version: "v1",
+      mode: "read_write",
+      surface: "rest",
+    });
+  });
+
+  it("encodes search query params", async () => {
+    globalThis.fetch = mock(async (input) => {
+      expect(String(input)).toBe(
+        "https://localpulse.nl/api/cli/events/search?query=amsterdam&limit=10&cursor=2&city=Amsterdam&time_intent=today&timezone=Europe%2FAmsterdam",
+      );
+      return new Response(
+        JSON.stringify({
+          results: [],
+          cursor: 2,
+          next_cursor: null,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    expect(
+      await searchCliEvents("https://localpulse.nl", {
+        query: "amsterdam",
+        city: "Amsterdam",
+        time_intent: "today",
+        timezone: "Europe/Amsterdam",
+        limit: 10,
+        cursor: 2,
+      }),
+    ).toEqual({
+      results: [],
+      cursor: 2,
+      next_cursor: null,
+    });
+  });
+
+  it("surfaces REST error responses", async () => {
+    globalThis.fetch = mock(async () => {
+      return new Response(
+        JSON.stringify({
+          detail: "Search failed",
+        }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    await expect(
+      searchCliEvents("https://localpulse.nl", {
+        query: "test",
+        limit: 10,
+        cursor: 0,
+      }),
+    ).rejects.toMatchObject({
+      message: "Search failed",
+      httpStatus: 500,
+    } satisfies Partial<CliApiError>);
+  });
+});

package/src/lib/cli-read-client.ts

@@ -0,0 +1,97 @@
+import {
+  CliApiError,
+  type ApiResponseBody,
+  extractApiErrorMessage,
+  parseApiJsonBody,
+} from "./api-response";
+import { buildApiUrl } from "./api-url";
+import type {
+  CliInfoResult,
+  SearchEventsResult,
+} from "./cli-read-types";
+
+export async function fetchCliInfo(apiUrl: string): Promise<CliInfoResult> {
+  const payload = await getJson(apiUrl, "/api/cli/info", "CLI info failed");
+  return parseCliInfoResult(payload);
+}
+
+export async function searchCliEvents(
+  apiUrl: string,
+  args: {
+    query: string;
+    city?: string;
+    time_intent?: "today" | "weekend";
+    timezone?: string;
+    limit: number;
+    cursor: number;
+  },
+): Promise<SearchEventsResult> {
+  const search = new URLSearchParams({
+    query: args.query,
+    limit: String(args.limit),
+    cursor: String(args.cursor),
+  });
+  if (args.city) {
+    search.set("city", args.city);
+  }
+  if (args.time_intent) {
+    search.set("time_intent", args.time_intent);
+  }
+  if (args.timezone) {
+    search.set("timezone", args.timezone);
+  }
+
+  const payload = await getJson(
+    apiUrl,
+    `/api/cli/events/search?${search.toString()}`,
+    "CLI search failed",
+  );
+  return parseSearchEventsResult(payload);
+}
+
+async function getJson(
+  apiUrl: string,
+  path: string,
+  fallbackMessage: string,
+): Promise<ApiResponseBody> {
+  const response = await fetch(buildApiUrl(apiUrl, path), {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+    },
+  });
+
+  const payload = await parseApiJsonBody(response);
+  if (!response.ok) {
+    throw new CliApiError(extractApiErrorMessage(payload, `${fallbackMessage} (${response.status})`), {
+      httpStatus: response.status,
+      body: payload,
+    });
+  }
+  return payload;
+}
+
+function parseCliInfoResult(payload: ApiResponseBody): CliInfoResult {
+  const result = payload as Partial<CliInfoResult>;
+  if (
+    typeof result.version !== "string" ||
+    result.mode !== "read_write" ||
+    result.surface !== "rest" ||
+    typeof result.ingest_directives_version !== "string"
+  ) {
+    throw new Error("Invalid API response: expected CLI info payload.");
+  }
+  return result as CliInfoResult;
+}
+
+function parseSearchEventsResult(payload: ApiResponseBody): SearchEventsResult {
+  const result = payload as Partial<SearchEventsResult>;
+  if (
+    !Array.isArray(result.results) ||
+    typeof result.cursor !== "number" ||
+    (typeof result.next_cursor !== "number" && result.next_cursor !== null)
+  ) {
+    throw new Error("Invalid API response: expected CLI search payload.");
+  }
+  return result as SearchEventsResult;
+}

package/src/lib/cli-read-types.ts

@@ -0,0 +1,27 @@
+export type CliInfoResult = {
+  version: string;
+  mode: "read_write";
+  surface: "rest";
+  ingest_directives_version: string;
+  links: {
+    onboarding_url: string;
+    website_url: string;
+  };
+};
+
+export type SearchEventCard = {
+  poster_id: string;
+  title: string | null;
+  event_datetime: string | null;
+  location: string | null;
+  venue_name: string | null;
+  venue_city: string | null;
+  genres: string[] | null;
+  frontend_url: string;
+};
+
+export type SearchEventsResult = {
+  results: SearchEventCard[];
+  cursor: number;
+  next_cursor: number | null;
+};

package/src/lib/credentials.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import {
+  deleteCredentials,
+  getCredentialsPath,
+  loadStoredCredentials,
+  resolveApiUrl,
+  saveCredentials,
+} from "./credentials";
+import { normalizeApiUrl } from "./api-url";
+
+const ORIGINAL_ENV = { ...process.env };
+
+afterEach(async () => {
+  process.env = { ...ORIGINAL_ENV };
+  await Bun.file(getCredentialsPath()).delete().catch(() => undefined);
+});
+
+describe("credentials", () => {
+  it("normalizes api urls", () => {
+    expect(normalizeApiUrl("https://localpulse.nl///")).toBe("https://localpulse.nl");
+    expect(normalizeApiUrl(undefined)).toBe("https://localpulse.nl");
+  });
+
+  it("persists and reloads stored credentials", async () => {
+    await saveCredentials({
+      api_url: "https://staging.localpulse.nl/",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+
+    expect(await loadStoredCredentials()).toEqual({
+      api_url: "https://staging.localpulse.nl",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+  });
+
+  it("writes credentials with owner-only permissions", async () => {
+    await saveCredentials({
+      api_url: "https://localpulse.nl",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+
+    const fileStat = await stat(getCredentialsPath());
+
+    expect(fileStat.mode & 0o777).toBe(0o600);
+  });
+
+  it("prefers env api urls over stored credentials", async () => {
+    await saveCredentials({
+      api_url: "https://staging.localpulse.nl",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+    process.env.LP_API_URL = "https://localpulse.nl/";
+
+    expect(await resolveApiUrl()).toBe("https://localpulse.nl");
+  });
+
+  it("deletes stored credentials", async () => {
+    await saveCredentials({
+      api_url: "https://localpulse.nl",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+
+    expect(await deleteCredentials()).toBe(true);
+    expect(await loadStoredCredentials()).toBeNull();
+  });
+
+  it("returns false when deleting non-existent credentials", async () => {
+    expect(await deleteCredentials()).toBe(false);
+  });
+
+  it("warns and returns null for corrupted JSON in credentials file", async () => {
+    const path = getCredentialsPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, "not-valid-json{{{", "utf8");
+
+    const chunks: string[] = [];
+    const original = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: unknown) => {
+      chunks.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const result = await loadStoredCredentials();
+      expect(result).toBeNull();
+      expect(chunks.join("")).toContain("corrupted");
+    } finally {
+      process.stderr.write = original;
+    }
+  });
+
+  it("warns and returns null for missing api_url in credentials file", async () => {
+    const path = getCredentialsPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ token: "some-token" }), "utf8");
+
+    const chunks: string[] = [];
+    const original = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: unknown) => {
+      chunks.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const result = await loadStoredCredentials();
+      expect(result).toBeNull();
+      expect(chunks.join("")).toContain("missing api_url");
+    } finally {
+      process.stderr.write = original;
+    }
+  });
+});

package/src/lib/credentials.ts

@@ -0,0 +1,113 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { DEFAULT_API_URL, normalizeApiUrl } from "./api-url";
+
+export type StoredCredentials = {
+  token?: string;
+  api_url: string;
+};
+
+export function getDefaultApiUrl(): string {
+  return normalizeApiUrl(process.env.LP_API_URL?.trim());
+}
+
+export function getCredentialsPath(): string {
+  return join(process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "localpulse", "credentials.json");
+}
+
+export async function loadStoredCredentials(): Promise<StoredCredentials | null> {
+  const path = getCredentialsPath();
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write(
+      `Warning: credentials file is corrupted (${path}). Run \`localpulse auth login\` to re-authenticate.\n`,
+    );
+    return null;
+  }
+
+  const creds = parsed as Partial<StoredCredentials>;
+  if (!creds.api_url || typeof creds.api_url !== "string") {
+    process.stderr.write(
+      `Warning: credentials file is missing api_url (${path}). Run \`localpulse auth login\` to re-authenticate.\n`,
+    );
+    return null;
+  }
+
+  return {
+    api_url: normalizeApiUrl(creds.api_url),
+    token: typeof creds.token === "string" ? creds.token.trim() || undefined : undefined,
+  };
+}
+
+export async function saveCredentials(credentials: StoredCredentials): Promise<string> {
+  const path = getCredentialsPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(
+    path,
+    JSON.stringify(
+      {
+        api_url: normalizeApiUrl(credentials.api_url),
+        token: credentials.token?.trim() || undefined,
+      },
+      null,
+      2,
+    ) + "\n",
+    {
+      encoding: "utf8",
+      mode: 0o600,
+    },
+  );
+  await chmod(path, 0o600);
+  return path;
+}
+
+export async function deleteCredentials(): Promise<boolean> {
+  const path = getCredentialsPath();
+  try {
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function resolveApiUrl(): Promise<string> {
+  const envApiUrl = process.env.LP_API_URL?.trim();
+  if (envApiUrl) {
+    return normalizeApiUrl(envApiUrl);
+  }
+
+  const stored = await loadStoredCredentials();
+  return stored?.api_url ?? DEFAULT_API_URL;
+}
+
+export async function resolveToken(): Promise<string | undefined> {
+  const envToken = process.env.LP_TOKEN?.trim();
+  if (envToken) {
+    return envToken;
+  }
+
+  const stored = await loadStoredCredentials();
+  return stored?.token?.trim() || undefined;
+}
+
+function isMissingFileError(error: unknown): error is NodeJS.ErrnoException {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/src/lib/login.test.ts

@@ -0,0 +1,73 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { getCredentialsPath, loadStoredCredentials } from "./credentials";
+import { loginWithToken } from "./login";
+
+const ORIGINAL_FETCH = globalThis.fetch;
+const ORIGINAL_XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+
+beforeEach(async () => {
+  process.env.XDG_CONFIG_HOME = await mkdtemp(join(tmpdir(), "lp-cli-login-"));
+});
+
+afterEach(() => {
+  globalThis.fetch = ORIGINAL_FETCH;
+  process.env.XDG_CONFIG_HOME = ORIGINAL_XDG_CONFIG_HOME;
+});
+
+describe("login", () => {
+  it("saves credentials even when CLI info fetch fails", async () => {
+    let requestCount = 0;
+    globalThis.fetch = mock(async (input, init) => {
+      requestCount += 1;
+      const url = String(input);
+
+      if (url === "https://localpulse.nl/api/v1/token/verify") {
+        expect(init?.method).toBe("GET");
+        expect(init?.headers).toEqual({
+          authorization: "Bearer lp_cli_11111111-1111-4111-8111-111111111111_secret",
+          accept: "application/json",
+        });
+        return new Response(
+          JSON.stringify({
+            authenticated: true,
+            email: "test@example.com",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        );
+      }
+
+      if (url === "https://localpulse.nl/api/cli/info") {
+        expect(init?.method).toBe("GET");
+        return new Response("temporarily unavailable", {
+          status: 503,
+          headers: { "Content-Type": "text/plain" },
+        });
+      }
+
+      throw new Error(`unexpected fetch: ${url}`);
+    }) as typeof fetch;
+
+    const result = await loginWithToken(
+      "https://localpulse.nl",
+      "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    );
+
+    expect(requestCount).toBe(2);
+    expect(result).toMatchObject({
+      saved: true,
+      api_url: "https://localpulse.nl",
+      validation: "authenticated_cli_probe",
+      cli_api_version: null,
+      credentials_path: getCredentialsPath(),
+    });
+    expect(await loadStoredCredentials()).toEqual({
+      api_url: "https://localpulse.nl",
+      token: "lp_cli_11111111-1111-4111-8111-111111111111_secret",
+    });
+  });
+});

package/src/lib/login.ts

@@ -0,0 +1,42 @@
+import { saveCredentials } from "./credentials";
+import { fetchCliInfo } from "./cli-read-client";
+import { verifyCliToken } from "./upload-client";
+
+export type LoginResult = {
+  saved: true;
+  validation: "authenticated_cli_probe";
+  api_url: string;
+  credentials_path: string;
+  cli_api_version: string | null;
+};
+
+export async function loginWithToken(
+  apiUrl: string,
+  token: string,
+): Promise<LoginResult> {
+  await verifyCliToken(apiUrl, token);
+  const credentialsPath = await saveCredentials({
+    api_url: apiUrl,
+    token,
+  });
+
+  return {
+    saved: true,
+    validation: "authenticated_cli_probe",
+    api_url: apiUrl,
+    credentials_path: credentialsPath,
+    cli_api_version: await fetchCliInfoVersion(apiUrl),
+  };
+}
+
+async function fetchCliInfoVersion(apiUrl: string): Promise<string | null> {
+  try {
+    const info = await fetchCliInfo(apiUrl);
+    return info.version ?? null;
+  } catch (error) {
+    if (error instanceof Error) {
+      return null;
+    }
+    throw error;
+  }
+}

package/src/lib/output.ts

@@ -0,0 +1,16 @@
+import { CliApiError } from "./api-response";
+
+export function printError(error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Error: ${message}\n`);
+}
+
+export function exitCodeForError(error: unknown): number {
+  if (error instanceof CliApiError) {
+    if (error.httpStatus === 401 || error.httpStatus === 403) return 2;
+    if (error.httpStatus >= 500) return 3;
+    return 1;
+  }
+  if (error instanceof Error && error.message.includes("token")) return 2;
+  return 1;
+}

package/src/lib/research-reader.ts

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+
+import { type ResearchPayload, validateResearchPayload } from "./research-schema";
+
+export async function readResearchPayload(pathOrDash: string): Promise<ResearchPayload> {
+  const raw = pathOrDash === "-" ? await readStdin() : await readFile(pathOrDash, "utf8");
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Research payload is not valid JSON.");
+  }
+
+  return validateResearchPayload(parsed);
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: string[] = [];
+  const decoder = new TextDecoder();
+  for await (const chunk of process.stdin) {
+    chunks.push(decoder.decode(chunk as Uint8Array, { stream: true }));
+  }
+  const result = chunks.join("") + decoder.decode();
+  if (!result.trim()) {
+    throw new Error("No input received on stdin. Pipe a JSON research payload.");
+  }
+  return result;
+}