@localpulse/cli 0.0.1

package/src/index.ts

@@ -0,0 +1,469 @@
+#!/usr/bin/env bun
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+import { hasOption, parseArgv, readNumberOption, readStringArrayOption, readStringOption } from "./lib/argv";
+import { requireToken } from "./lib/auth";
+import { searchCliEvents } from "./lib/cli-read-client";
+import type { SearchEventCard } from "./lib/cli-read-types";
+import {
+  deleteCredentials,
+  getCredentialsPath,
+  getDefaultApiUrl,
+  resolveApiUrl,
+} from "./lib/credentials";
+import { loginWithToken } from "./lib/login";
+import { exitCodeForError, printError } from "./lib/output";
+import { readResearchPayload } from "./lib/research-reader";
+import {
+  generateResearchSkeleton,
+  mapResearchToUploadFields,
+  stitchResearchContext,
+} from "./lib/research-schema";
+import { isLikelyCliToken } from "./lib/token";
+import {
+  type UploadPosterResult,
+  type DraftResult,
+  uploadPoster,
+  createDraft,
+  uploadDraftMedia,
+  detectMediaType,
+} from "./lib/upload-client";
+import packageJson from "../package.json";
+
+const VERSION = packageJson.version;
+
+void main(process.argv.slice(2));
+
+async function main(argv: string[]): Promise<void> {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    stdout.write(rootHelp());
+    return;
+  }
+
+  if (argv[0] === "--version") {
+    stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const [command, ...rest] = argv;
+  const parsed = parseArgv(rest);
+
+  try {
+    switch (command) {
+      case "auth":
+        await runAuth(parsed);
+        break;
+      case "ingest":
+        await runIngest(parsed);
+        break;
+      case "search":
+        await runSearch(parsed);
+        break;
+      default:
+        throw new Error(`Unknown command: ${command}. Run \`localpulse --help\` for usage.`);
+    }
+  } catch (error) {
+    printError(error);
+    process.exitCode = exitCodeForError(error);
+  }
+}
+
+async function runAuth(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help") && parsed.positionals.length === 0) {
+    stdout.write(authHelp());
+    return;
+  }
+
+  const subcommand = parsed.positionals[0];
+  if (!subcommand || (subcommand !== "login" && subcommand !== "logout")) {
+    throw new Error("Usage: localpulse auth <login|logout>. Run `localpulse auth --help` for details.");
+  }
+
+  if (subcommand === "login") {
+    await runAuthLogin(parsed);
+  } else {
+    await runAuthLogout();
+  }
+}
+
+async function runAuthLogin(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help")) {
+    stdout.write(authLoginHelp());
+    return;
+  }
+
+  const apiUrl = readStringOption(parsed, "api-url")?.trim() || getDefaultApiUrl();
+  const token = await resolveLoginToken(readStringOption(parsed, "token"));
+  if (!isLikelyCliToken(token)) {
+    throw new Error("Invalid token format. Expected lp_cli_<uuid>_<secret> or lp_mcp_<uuid>_<secret>.");
+  }
+
+  const result = await loginWithToken(apiUrl, token);
+  stdout.write(`Authenticated. Credentials saved to ${result.credentials_path}\n`);
+}
+
+async function runAuthLogout(): Promise<void> {
+  const deleted = await deleteCredentials();
+  if (deleted) {
+    stdout.write("Logged out. Credentials removed.\n");
+  } else {
+    stdout.write("No credentials found.\n");
+  }
+}
+
+async function runIngest(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help")) {
+    stdout.write(ingestHelp());
+    return;
+  }
+
+  if (hasOption(parsed, "generate-skeleton")) {
+    stdout.write(`${JSON.stringify(generateResearchSkeleton(), null, 2)}\n`);
+    return;
+  }
+
+  if (parsed.positionals.length !== 1) {
+    throw new Error("Usage: localpulse ingest <file> --research <payload.json>. Run `localpulse ingest --help` for details.");
+  }
+
+  const file = parsed.positionals[0];
+  const researchPath = readStringOption(parsed, "research");
+
+  if (!researchPath) {
+    throw new Error("--research <file|-> is required. Run `localpulse ingest --generate-skeleton` for the expected format.");
+  }
+
+  const payload = await readResearchPayload(researchPath);
+  const mapped = mapResearchToUploadFields(payload);
+  const stitched = stitchResearchContext(payload);
+  const explicitContext = readStringOption(parsed, "context");
+  const context = [stitched, explicitContext].filter(Boolean).join("\n\n") || undefined;
+
+  const apiUrl = await resolveApiUrl();
+  const dryRun = hasOption(parsed, "dry-run");
+  const force = hasOption(parsed, "force");
+  const token = dryRun ? "" : await requireToken();
+
+  const uploadOptions = {
+    file,
+    urls: readStringArrayOption(parsed, "urls") ?? mapped.urls,
+    city: readStringOption(parsed, "city") ?? mapped.city,
+    venuePlaceId: readStringOption(parsed, "google-place-id") ?? mapped.venuePlaceId,
+    context,
+    ticketUrl: readStringOption(parsed, "ticket-url") ?? mapped.ticketUrl,
+    title: readStringOption(parsed, "title") ?? mapped.title,
+    datetime: readStringOption(parsed, "date") ?? mapped.datetime,
+    venue: readStringOption(parsed, "venue") ?? mapped.venue,
+    extraMedia: readStringArrayOption(parsed, "extra-media"),
+    dryRun,
+    force,
+  };
+
+  if (dryRun) {
+    const result = await uploadPoster(apiUrl, token, uploadOptions);
+    if ("dry_run" in result) {
+      stdout.write(`Dry run passed: ${result.file} (${result.extra_media_count} extra media)\n`);
+    }
+    return;
+  }
+
+  if (force) {
+    const result = await uploadPoster(apiUrl, token, uploadOptions);
+    if (!("dry_run" in result)) {
+      printIngestResult(result);
+    }
+    return;
+  }
+
+  // Default: draft flow
+  const draft = await runDraftIngest(apiUrl, token, file, uploadOptions);
+  printDraftResult(draft, apiUrl);
+}
+
+async function validateFilePaths(primaryFile: string, extraMedia?: string[]): Promise<void> {
+  const { existsSync } = await import("node:fs");
+  const missing: string[] = [];
+  if (!existsSync(primaryFile)) missing.push(primaryFile);
+  for (const p of extraMedia ?? []) {
+    if (!existsSync(p)) missing.push(p);
+  }
+  if (missing.length) {
+    throw new Error(`File(s) not found: ${missing.join(", ")}`);
+  }
+}
+
+async function runDraftIngest(
+  apiUrl: string,
+  token: string,
+  primaryFile: string,
+  options: Pick<import("./lib/upload-client").IngestUploadOptions, "extraMedia" | "urls" | "city" | "venuePlaceId" | "context" | "ticketUrl" | "title" | "datetime" | "venue">,
+): Promise<DraftResult> {
+  await validateFilePaths(primaryFile, options.extraMedia);
+
+  stdout.write("Creating draft...\n");
+  const draft = await createDraft(apiUrl, token, options);
+
+  stdout.write(`Draft created: ${draft.id}\n`);
+  stdout.write("Uploading primary media...\n");
+  await uploadDraftMedia(apiUrl, token, draft.id, primaryFile, {
+    mediaType: detectMediaType(primaryFile),
+    sortOrder: 0,
+    isPrimary: true,
+  });
+
+  if (options.extraMedia?.length) {
+    for (const [index, path] of options.extraMedia.entries()) {
+      stdout.write(`Uploading extra media ${index + 1}...\n`);
+      await uploadDraftMedia(apiUrl, token, draft.id, path, {
+        mediaType: detectMediaType(path),
+        sortOrder: index + 1,
+        isPrimary: false,
+      });
+    }
+  }
+
+  return draft;
+}
+
+function printDraftResult(draft: DraftResult, apiUrl: string): void {
+  const baseUrl = apiUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+  stdout.write(`\nDraft saved: ${draft.id}\n`);
+  stdout.write("Open the publish dashboard to review and submit:\n");
+  stdout.write(`  ${baseUrl}/publish/edit/${draft.id}\n`);
+}
+
+function printIngestResult(result: UploadPosterResult): void {
+  stdout.write(`${result.message}\n`);
+  if (result.run_id) {
+    stdout.write(`Run ID: ${result.run_id}\n`);
+  }
+  if (result.event_url) {
+    stdout.write(`Event: ${result.event_url}\n`);
+  }
+  if (result.is_duplicate && result.existing_event_url) {
+    stdout.write(`Duplicate of: ${result.existing_event_url}\n`);
+  }
+}
+
+async function runSearch(parsed: ReturnType<typeof parseArgv>): Promise<void> {
+  if (hasOption(parsed, "help")) {
+    stdout.write(searchHelp());
+    return;
+  }
+
+  const query = parsed.positionals.join(" ").trim();
+  if (!query) {
+    throw new Error("Search query is required. Run `localpulse search --help` for usage.");
+  }
+
+  const apiUrl = await resolveApiUrl();
+  const result = await searchCliEvents(apiUrl, {
+    query,
+    city: readStringOption(parsed, "city"),
+    time_intent: readDateFilterOption(parsed),
+    timezone: readStringOption(parsed, "tz"),
+    limit: readNumberOption(parsed, "limit") ?? 10,
+    cursor: readNumberOption(parsed, "cursor") ?? 0,
+  });
+
+  if (result.results.length === 0) {
+    stdout.write("No events found.\n");
+    return;
+  }
+
+  for (const card of result.results) {
+    printSearchCard(card);
+  }
+
+  if (result.next_cursor !== null) {
+    stdout.write(`\n(more results: localpulse search "${query}" --cursor ${result.next_cursor})\n`);
+  }
+}
+
+function printSearchCard(card: SearchEventCard): void {
+  const parts = [card.title ?? "Untitled"];
+  if (card.event_datetime) {
+    parts.push(card.event_datetime);
+  }
+  if (card.venue_name && card.venue_city) {
+    parts.push(`${card.venue_name}, ${card.venue_city}`);
+  } else if (card.location) {
+    parts.push(card.location);
+  }
+  stdout.write(`${parts.join(" — ")}\n`);
+  stdout.write(`  ${card.frontend_url}\n`);
+}
+
+async function resolveLoginToken(explicitToken?: string): Promise<string> {
+  if (explicitToken?.trim()) {
+    return explicitToken.trim();
+  }
+
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error(
+      `No token provided. Visit https://localpulse.nl/dev and rerun with --token, or set LP_TOKEN. Credentials path: ${getCredentialsPath()}`,
+    );
+  }
+
+  stdout.write("Create or copy a token from https://localpulse.nl/dev\n");
+  const readline = createInterface({ input: stdin, output: stdout });
+  try {
+    const token = await readline.question("Paste token: ");
+    if (!token.trim()) {
+      throw new Error("Token is required.");
+    }
+    return token.trim();
+  } finally {
+    readline.close();
+  }
+}
+
+function readDateFilterOption(
+  parsed: ReturnType<typeof parseArgv>,
+): "today" | "weekend" | undefined {
+  const value = readStringOption(parsed, "date");
+  if (!value) {
+    return undefined;
+  }
+  if (value === "today" || value === "weekend") {
+    return value;
+  }
+  throw new Error("`--date` must be `today` or `weekend`.");
+}
+
+function rootHelp(): string {
+  return `Usage: localpulse <command> [options]
+
+Commands:
+  ingest   Ingest an event poster into Local Pulse
+  search   Search existing events
+  auth     Login and logout
+
+Options:
+  --help     Show help
+  --version  Show version
+
+Environment:
+  LP_TOKEN    Override stored auth token
+  LP_API_URL  Override API base URL (default: https://localpulse.nl)
+`;
+}
+
+function authHelp(): string {
+  return `Usage: localpulse auth <command>
+
+Commands:
+  login    Authenticate with a Local Pulse CLI token
+  logout   Remove stored credentials
+
+Run \`localpulse auth login --help\` for login options.
+`;
+}
+
+function authLoginHelp(): string {
+  return `Usage: localpulse auth login [--token <token>]
+
+Options:
+  --token <token>        Local Pulse CLI token
+  --api-url <url>        Override API base URL
+  --help                 Show this help
+
+Without --token, prompts interactively (visit https://localpulse.nl/dev to create a token).
+`;
+}
+
+function ingestHelp(): string {
+  return `Usage: localpulse ingest <file> --research <payload.json> [options]
+
+Ingest an event poster into Local Pulse. By default, creates a draft that
+can be reviewed on the publish dashboard before processing. Use --force
+to bypass drafts and submit directly to the ingestion pipeline.
+
+Arguments:
+  file                    Path to primary poster image (JPEG, PNG, WebP)
+
+Research payload:
+  --research <file|->     JSON research payload (required)
+  --generate-skeleton     Print an example research template and exit
+
+  The payload is JSON with five top-level sections. All are optional,
+  but the more you provide, the better the enrichment.
+
+  performers[]            Who is performing or presenting
+    .name                 Full name (required per performer)
+    .type                 What they are: "DJ", "band", "speaker", "visual artist"
+    .genre                Style or genre: "techno", "jazz", "stand-up comedy"
+    .socials[]            Profile URLs: Instagram, RA, Bandcamp, personal site
+    .context              Anything else: bio, residencies, notable releases
+
+  organizer               Who is putting on the event
+    .name                 Collective, promoter, or brand name (required)
+    .socials[]            Profile URLs
+    .context              History, reputation, previous events, affiliation
+
+  venue                   Where the event happens
+    .name                 Venue name
+    .city                 City name
+    .google_place_id      Google Places ID (skips venue matching if provided)
+    .context              Capacity, room layout, vibe, accessibility, location tips
+
+  event                   What the event is
+    .title                Event name
+    .date                 ISO 8601 datetime (e.g. "2026-03-14T22:00:00+01:00")
+    .type                 Kind of event: "club night", "festival", "exhibition",
+                          "workshop", "concert", "open air", "listening session"
+    .price                Ticket price info: "€15-25", "Free", "Sold out"
+    .urls[]               Source pages: RA, venue site, Facebook event
+    .ticket_url           Direct ticketing / purchase URL
+    .context              Schedule, door policy, age restrictions, special notes
+
+  context                 Anything that doesn't fit above: background on the
+                          scene, cross-references to other events, corrections
+
+  Run \`localpulse ingest --generate-skeleton\` for a complete example.
+
+Override fields (take precedence over research values):
+  --title <text>          Override event title
+  --date <iso8601>        Override event date/time
+  --city <text>           Override city
+  --venue <text>          Override venue name
+  --google-place-id <id>  Override Google Places ID
+  --urls <url>...         Override source URLs
+  --ticket-url <url>      Override ticketing URL
+  --context <text>        Append extra context to research payload
+
+Modes:
+  --force                 Bypass draft and submit directly to ingestion
+  --dry-run               Check that all inputs are valid without uploading
+
+Extra:
+  --extra-media <file>... Up to 2 additional poster or flyer images
+
+Options:
+  --help                  Show this help
+
+Example:
+  localpulse ingest --generate-skeleton > research.json
+  # research and fill in the payload
+  localpulse ingest ./poster.jpg --research research.json
+`;
+}
+
+function searchHelp(): string {
+  return `Usage: localpulse search <query> [options]
+
+Search existing events on Local Pulse.
+
+Arguments:
+  query                 Free-text search query
+
+Options:
+  --city <text>         Filter by city
+  --date <today|weekend> Time intent filter
+  --tz <timezone>       IANA timezone (requires --date)
+  --limit <n>           Results per page (1-25, default 10)
+  --cursor <n>          Pagination offset
+  --help                Show this help
+`;
+}

package/src/lib/api-response.ts

@@ -0,0 +1,63 @@
+export type ApiResponseBody = Record<string, unknown> & {
+  detail?: unknown;
+  error?: unknown;
+  bodySnippet?: unknown;
+};
+
+export class CliApiError extends Error {
+  readonly httpStatus: number;
+  readonly body?: ApiResponseBody;
+
+  constructor(message: string, options: { httpStatus: number; body?: ApiResponseBody }) {
+    super(message);
+    this.name = "CliApiError";
+    this.httpStatus = options.httpStatus;
+    this.body = options.body;
+  }
+}
+
+export function extractApiErrorMessage(payload: ApiResponseBody, fallback: string): string {
+  if (typeof payload.detail === "string") {
+    return payload.detail;
+  }
+  if (typeof payload.error === "string") {
+    return payload.error;
+  }
+  return fallback;
+}
+
+export async function parseApiJsonBody(response: Response): Promise<ApiResponseBody> {
+  const text = await response.text();
+  if (!text.trim()) {
+    return {};
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    const bodySnippet = text.slice(0, 200);
+    if (!response.ok) {
+      throw new CliApiError("API returned a non-JSON error response", {
+        httpStatus: response.status,
+        body: bodySnippet ? { bodySnippet } : undefined,
+      });
+    }
+    throw new Error("API returned a non-JSON response");
+  }
+
+  if (!isApiResponseBody(parsed)) {
+    if (!response.ok) {
+      throw new CliApiError("API returned a non-object error response", {
+        httpStatus: response.status,
+      });
+    }
+    throw new Error("API returned a non-object JSON response");
+  }
+
+  return parsed;
+}
+
+export function isApiResponseBody(value: unknown): value is ApiResponseBody {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/lib/api-url.ts

@@ -0,0 +1,15 @@
+export const DEFAULT_API_URL = "https://localpulse.nl";
+
+export function normalizeApiUrl(value?: string | null): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return DEFAULT_API_URL;
+  }
+
+  return trimmed.replace(/\/+$/, "");
+}
+
+export function buildApiUrl(apiUrl: string, path: string): string {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizeApiUrl(apiUrl)}${normalizedPath}`;
+}

package/src/lib/argv.ts

@@ -0,0 +1,126 @@
+export type ParsedArgv = {
+  options: Map<string, Array<string | true>>;
+  positionals: string[];
+};
+
+export function parseArgv(argv: string[]): ParsedArgv {
+  const options = new Map<string, Array<string | true>>();
+  const positionals: string[] = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+
+    if (token === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (token === "-h") {
+      appendOption(options, "help", true);
+      continue;
+    }
+
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+
+    const trimmed = token.slice(2);
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex >= 0) {
+      const name = trimmed.slice(0, equalsIndex);
+      const value = trimmed.slice(equalsIndex + 1);
+      appendOption(options, name, value);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("-")) {
+      appendOption(options, trimmed, next);
+      index += 1;
+      continue;
+    }
+
+    appendOption(options, trimmed, true);
+  }
+
+  return { options, positionals };
+}
+
+export function hasOption(parsed: ParsedArgv, name: string): boolean {
+  return parsed.options.has(name);
+}
+
+export function readStringOption(parsed: ParsedArgv, name: string): string | undefined {
+  const values = parsed.options.get(name);
+  if (!values || values.length === 0) {
+    return undefined;
+  }
+  const value = values.at(-1);
+  if (value === true) {
+    throw new Error(`\`--${name}\` requires a value.`);
+  }
+  return value;
+}
+
+export function readStringArrayOption(parsed: ParsedArgv, name: string): string[] | undefined {
+  const values = parsed.options.get(name);
+  if (!values || values.length === 0) {
+    return undefined;
+  }
+  return values.map((value) => {
+    if (value === true) {
+      throw new Error(`\`--${name}\` requires a value.`);
+    }
+    return value;
+  });
+}
+
+export function readBooleanOption(parsed: ParsedArgv, name: string): boolean | undefined {
+  const values = parsed.options.get(name);
+  if (!values || values.length === 0) {
+    return undefined;
+  }
+
+  const value = values.at(-1);
+  if (value === true) {
+    return true;
+  }
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`\`--${name}\` must be true or false.`);
+}
+
+export function readNumberOption(parsed: ParsedArgv, name: string): number | undefined {
+  const value = readStringOption(parsed, name);
+  if (value === undefined) {
+    return undefined;
+  }
+  const parsedNumber = Number(value);
+  if (!Number.isFinite(parsedNumber)) {
+    throw new Error(`\`--${name}\` must be a number.`);
+  }
+  return parsedNumber;
+}
+
+function appendOption(
+  options: Map<string, Array<string | true>>,
+  name: string,
+  value: string | true,
+): void {
+  const existing = options.get(name) ?? [];
+  existing.push(value);
+  options.set(name, existing);
+}

package/src/lib/auth.ts

@@ -0,0 +1,9 @@
+import { resolveToken } from "./credentials";
+
+export async function requireToken(): Promise<string> {
+  const token = await resolveToken();
+  if (!token) {
+    throw new Error("Authentication token is missing. Run `localpulse auth login` or set LP_TOKEN.");
+  }
+  return token;
+}