starcite 0.0.1

package/dist/index.js

@@ -0,0 +1,1078 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import {
+  createStarciteClient,
+  normalizeBaseUrl,
+  StarciteApiError
+} from "@starcite/sdk";
+import { Command, InvalidArgumentError } from "commander";
+import { createConsola } from "consola";
+import { z as z2 } from "zod";
+
+// src/store.ts
+import { randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { homedir, hostname } from "os";
+import { join, resolve } from "path";
+import Conf from "conf";
+import { cosmiconfig, defaultLoaders } from "cosmiconfig";
+import { lock } from "proper-lockfile";
+import { parse as parseToml } from "toml";
+import { z } from "zod";
+var DEFAULT_CONFIG_DIRECTORY_NAME = ".starcite";
+var CONFIG_JSON_FILENAME = "config.json";
+var CONFIG_TOML_FILENAME = "config.toml";
+var CREDENTIALS_FILENAME = "credentials";
+var IDENTITY_FILENAME = "identity";
+var STATE_FILENAME = "state";
+var STATE_LOCK_FILENAME = ".state.lock";
+var TILDE_PREFIX_REGEX = /^~(?=\/|$)/;
+var ConfigFileSchema = z.object({
+  baseUrl: z.string().optional(),
+  base_url: z.string().optional(),
+  producerId: z.string().optional(),
+  producer_id: z.string().optional(),
+  apiKey: z.string().optional(),
+  api_key: z.string().optional()
+}).passthrough();
+var IdentityFileSchema = z.object({
+  producerId: z.string().trim().min(1),
+  hostname: z.string().trim().min(1),
+  uuid: z.string().uuid(),
+  createdAt: z.string()
+});
+var StateFileSchema = z.object({
+  nextSeqByContext: z.record(z.number().int().positive()).default({})
+});
+var CredentialsFileSchema = z.object({
+  apiKey: z.string().trim().min(1).optional()
+});
+function trimString(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeConfig(input) {
+  const parsed = ConfigFileSchema.safeParse(input);
+  if (!parsed.success) {
+    return {};
+  }
+  return {
+    baseUrl: trimString(parsed.data.baseUrl ?? parsed.data.base_url),
+    producerId: trimString(parsed.data.producerId ?? parsed.data.producer_id),
+    apiKey: trimString(parsed.data.apiKey ?? parsed.data.api_key)
+  };
+}
+function defaultConfigDirectory() {
+  const home = homedir();
+  if (home.trim().length > 0) {
+    return join(home, DEFAULT_CONFIG_DIRECTORY_NAME);
+  }
+  return resolve(DEFAULT_CONFIG_DIRECTORY_NAME);
+}
+function resolveConfigDir(input) {
+  const configured = trimString(input) ?? trimString(process.env.STARCITE_HOME);
+  const withTilde = configured?.startsWith("~") ? configured.replace(TILDE_PREFIX_REGEX, homedir()) : configured;
+  return resolve(withTilde ?? defaultConfigDirectory());
+}
+function buildSeqContextKey(baseUrl, sessionId, producerId) {
+  return `${baseUrl}::${sessionId}::${producerId}`;
+}
+var StarciteCliStore = class {
+  directory;
+  lockPath;
+  configExplorer = cosmiconfig("starcite", {
+    cache: false,
+    searchStrategy: "none",
+    searchPlaces: [CONFIG_JSON_FILENAME, CONFIG_TOML_FILENAME],
+    loaders: {
+      ...defaultLoaders,
+      ".toml": (_filepath, content) => parseToml(content)
+    }
+  });
+  identityStore;
+  credentialsStore;
+  stateStore;
+  constructor(directory) {
+    this.directory = directory;
+    this.lockPath = join(directory, STATE_LOCK_FILENAME);
+    this.identityStore = new Conf({
+      cwd: directory,
+      clearInvalidConfig: true,
+      configName: IDENTITY_FILENAME,
+      fileExtension: "json"
+    });
+    this.credentialsStore = new Conf({
+      cwd: directory,
+      clearInvalidConfig: true,
+      configName: CREDENTIALS_FILENAME,
+      fileExtension: "json",
+      defaults: {}
+    });
+    this.stateStore = new Conf({
+      cwd: directory,
+      clearInvalidConfig: true,
+      configName: STATE_FILENAME,
+      fileExtension: "json",
+      defaults: { nextSeqByContext: {} }
+    });
+  }
+  async readConfig() {
+    await this.ensureConfigDirectory();
+    const result = await this.configExplorer.search(this.directory);
+    if (!result) {
+      return {};
+    }
+    return normalizeConfig(result.config);
+  }
+  async writeConfig(config) {
+    await this.ensureConfigDirectory();
+    const normalized = normalizeConfig(config);
+    const serialized = {};
+    if (normalized.baseUrl) {
+      serialized.baseUrl = normalized.baseUrl;
+    }
+    if (normalized.producerId) {
+      serialized.producerId = normalized.producerId;
+    }
+    if (normalized.apiKey) {
+      serialized.apiKey = normalized.apiKey;
+    }
+    await writeFile(
+      join(this.directory, CONFIG_JSON_FILENAME),
+      `${JSON.stringify(serialized, null, 2)}
+`,
+      "utf8"
+    );
+  }
+  async updateConfig(patch) {
+    const current = await this.readConfig();
+    const merged = normalizeConfig({
+      ...current,
+      ...patch
+    });
+    await this.writeConfig(merged);
+    return merged;
+  }
+  async readApiKey() {
+    const fromEnv = trimString(process.env.STARCITE_API_KEY);
+    if (fromEnv) {
+      return fromEnv;
+    }
+    const parsed = CredentialsFileSchema.safeParse(this.credentialsStore.store);
+    const fromCredentials = parsed.success ? trimString(parsed.data.apiKey) : void 0;
+    if (fromCredentials) {
+      return fromCredentials;
+    }
+    const config = await this.readConfig();
+    return trimString(config.apiKey);
+  }
+  async saveApiKey(apiKey) {
+    await this.ensureConfigDirectory();
+    const normalized = trimString(apiKey);
+    if (!normalized) {
+      throw new Error("API key cannot be empty");
+    }
+    this.credentialsStore.set("apiKey", normalized);
+  }
+  async clearApiKey() {
+    await this.ensureConfigDirectory();
+    this.credentialsStore.delete("apiKey");
+  }
+  async resolveProducerId(explicitProducerId) {
+    const explicit = trimString(explicitProducerId);
+    if (explicit) {
+      return explicit;
+    }
+    const fromEnv = trimString(process.env.STARCITE_PRODUCER_ID);
+    if (fromEnv) {
+      return fromEnv;
+    }
+    const config = await this.readConfig();
+    const fromConfig = trimString(config.producerId);
+    if (fromConfig) {
+      return fromConfig;
+    }
+    const identity = await this.readOrCreateIdentity();
+    return identity.producerId;
+  }
+  async withStateLock(action) {
+    await this.ensureConfigDirectory();
+    const release = await lock(this.directory, {
+      lockfilePath: this.lockPath,
+      realpath: false,
+      retries: {
+        retries: 50,
+        minTimeout: 20,
+        maxTimeout: 60
+      }
+    });
+    try {
+      return await action();
+    } finally {
+      await release();
+    }
+  }
+  readNextSeq(contextKey) {
+    const state = this.readState();
+    return Promise.resolve(state.nextSeqByContext[contextKey] ?? 1);
+  }
+  bumpNextSeq(contextKey, usedSeq) {
+    const state = this.readState();
+    const nextSeqByContext = {
+      ...state.nextSeqByContext,
+      [contextKey]: Math.max(
+        state.nextSeqByContext[contextKey] ?? 1,
+        usedSeq + 1
+      )
+    };
+    this.stateStore.set("nextSeqByContext", nextSeqByContext);
+    return Promise.resolve();
+  }
+  readState() {
+    const parsed = StateFileSchema.safeParse(this.stateStore.store);
+    if (parsed.success) {
+      return parsed.data;
+    }
+    this.stateStore.clear();
+    return { nextSeqByContext: {} };
+  }
+  readOrCreateIdentity() {
+    const parsed = IdentityFileSchema.safeParse(this.identityStore.store);
+    if (parsed.success) {
+      return parsed.data;
+    }
+    const host = hostname();
+    const uuid = randomUUID();
+    const identity = {
+      producerId: `cli:${host}:${uuid}`,
+      hostname: host,
+      uuid,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.identityStore.store = identity;
+    return identity;
+  }
+  async ensureConfigDirectory() {
+    await mkdir(this.directory, { recursive: true });
+  }
+};
+
+// src/up.ts
+import { spawn } from "child_process";
+import { mkdir as mkdir2, stat, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
+import {
+  cancel as clackCancel,
+  confirm as clackConfirm,
+  password as clackPassword,
+  text as clackText,
+  isCancel
+} from "@clack/prompts";
+var DEFAULT_API_PORT = 45187;
+var DEFAULT_DB_PORT = 5433;
+var MIN_PORT = 1;
+var MAX_PORT = 65535;
+var RUNTIME_DIRECTORY_NAME = "runtime";
+var DEFAULT_COMPOSE_FILE = `services:
+  app:
+    image: \${STARCITE_IMAGE:-ghcr.io/fastpaca/starcite:latest}
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      SECRET_KEY_BASE: \${SECRET_KEY_BASE:-xuQnOFm6sH5Qdd7x4WJv5smuG2Xf2nG0BL8rJ4yX6HnKGeTjo6n8r5hQKsxNkZWz}
+      PHX_HOST: \${PHX_HOST:-localhost}
+      PORT: 4000
+      DATABASE_URL: \${DATABASE_URL:-ecto://postgres:postgres@db:5432/starcite_dev}
+      MIGRATE_ON_BOOT: \${MIGRATE_ON_BOOT:-true}
+      DNS_CLUSTER_QUERY: \${DNS_CLUSTER_QUERY:-}
+      DNS_CLUSTER_NODE_BASENAME: \${DNS_CLUSTER_NODE_BASENAME:-starcite}
+      DNS_POLL_INTERVAL_MS: \${DNS_POLL_INTERVAL_MS:-5000}
+    ports:
+      - "\${STARCITE_API_PORT:-45187}:4000"
+    restart: unless-stopped
+
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: starcite_dev
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    ports:
+      - "\${STARCITE_DB_PORT:-5433}:5432"
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+volumes:
+  db-data:
+`;
+function parsePort(value, optionName) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < MIN_PORT || parsed > MAX_PORT) {
+    throw new Error(
+      `${optionName} must be an integer between ${MIN_PORT} and ${MAX_PORT}`
+    );
+  }
+  return parsed;
+}
+function baseUrlPort(baseUrl) {
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.port) {
+      return parsePort(parsed.port, "base URL port");
+    }
+  } catch {
+    return DEFAULT_API_PORT;
+  }
+  return DEFAULT_API_PORT;
+}
+async function ensureSuccess(runCommand, command, args) {
+  const result = await runCommand(command, args);
+  return result.code === 0;
+}
+async function ensureDockerReady(logger, runCommand) {
+  const hasDocker = await ensureSuccess(runCommand, "docker", ["--version"]);
+  if (!hasDocker) {
+    logger.error("You don't have Docker installed, please install it.");
+    throw new Error("Docker is required to run this command.");
+  }
+  const hasDockerCompose = await ensureSuccess(runCommand, "docker", [
+    "compose",
+    "version"
+  ]);
+  if (!hasDockerCompose) {
+    logger.error(
+      "Docker Compose is not available. Install Docker Compose and retry."
+    );
+    throw new Error("Docker Compose is required to run this command.");
+  }
+  const daemonRunning = await ensureSuccess(runCommand, "docker", ["info"]);
+  if (!daemonRunning) {
+    logger.error("Docker is installed but the daemon is not running.");
+    throw new Error("Start Docker and retry.");
+  }
+}
+async function selectApiPort(baseUrl, options, prompt) {
+  if (options.port !== void 0) {
+    return options.port;
+  }
+  const fallbackPort = baseUrlPort(baseUrl);
+  if (options.yes) {
+    return fallbackPort;
+  }
+  while (true) {
+    const answer = await prompt.input(
+      "What port do you want it on?",
+      `${fallbackPort}`
+    );
+    try {
+      return parsePort(answer, "port");
+    } catch (error) {
+      if (error instanceof Error) {
+      }
+    }
+  }
+}
+function runtimeDirectory(store) {
+  return join2(store.directory, RUNTIME_DIRECTORY_NAME);
+}
+async function runtimeDirectoryExists(store) {
+  try {
+    const result = await stat(runtimeDirectory(store));
+    return result.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function writeComposeFiles(store, options) {
+  const directory = runtimeDirectory(store);
+  await mkdir2(directory, { recursive: true });
+  await writeFile2(
+    join2(directory, "docker-compose.yml"),
+    DEFAULT_COMPOSE_FILE,
+    "utf8"
+  );
+  const envLines = [
+    `STARCITE_API_PORT=${options.apiPort}`,
+    `STARCITE_DB_PORT=${options.dbPort}`
+  ];
+  if (options.image?.trim()) {
+    envLines.push(`STARCITE_IMAGE=${options.image.trim()}`);
+  }
+  await writeFile2(join2(directory, ".env"), `${envLines.join("\n")}
+`, "utf8");
+  return directory;
+}
+function parsePortOption(value, optionName) {
+  try {
+    return parsePort(value, optionName);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(error.message);
+    }
+    throw error;
+  }
+}
+async function runUpWizard(input) {
+  const { baseUrl, logger, options, prompt, runCommand, store } = input;
+  await ensureDockerReady(logger, runCommand);
+  const confirmed = options.yes ? true : await prompt.confirm(
+    "Are you sure you want to create the docker containers?",
+    true
+  );
+  if (!confirmed) {
+    logger.info("Cancelled.");
+    return;
+  }
+  const apiPort = await selectApiPort(baseUrl, options, prompt);
+  const dbPort = options.dbPort ?? DEFAULT_DB_PORT;
+  const composeDirectory = await writeComposeFiles(store, {
+    apiPort,
+    dbPort,
+    image: options.image
+  });
+  const result = await runCommand("docker", ["compose", "up", "-d"], {
+    cwd: composeDirectory
+  });
+  if (result.code !== 0) {
+    const message = result.stderr || result.stdout || "docker compose up failed";
+    throw new Error(message.trim());
+  }
+  logger.info(`Starcite is starting on http://localhost:${apiPort}`);
+  logger.info(`Compose files are in ${composeDirectory}`);
+}
+async function runDownWizard(input) {
+  const { logger, options, prompt, runCommand, store } = input;
+  await ensureDockerReady(logger, runCommand);
+  const hasRuntimeDirectory = await runtimeDirectoryExists(store);
+  if (!hasRuntimeDirectory) {
+    logger.info(
+      `No Starcite runtime found at ${runtimeDirectory(
+        store
+      )}. Nothing to tear down.`
+    );
+    return;
+  }
+  const removeVolumes = options.volumes ?? true;
+  const confirmed = options.yes ? true : await prompt.confirm(
+    removeVolumes ? "Are you sure you want to stop and delete Starcite containers and volumes?" : "Are you sure you want to stop Starcite containers?",
+    false
+  );
+  if (!confirmed) {
+    logger.info("Cancelled.");
+    return;
+  }
+  const args = ["compose", "down", "--remove-orphans"];
+  if (removeVolumes) {
+    args.push("-v");
+  }
+  const result = await runCommand("docker", args, {
+    cwd: runtimeDirectory(store)
+  });
+  if (result.code !== 0) {
+    const message = result.stderr || result.stdout || "docker compose down failed";
+    throw new Error(message.trim());
+  }
+  logger.info("Starcite containers stopped.");
+  if (removeVolumes) {
+    logger.info("Starcite volumes removed.");
+  }
+}
+function createDefaultPrompt() {
+  const assertInteractive = () => {
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+      throw new Error(
+        "Interactive mode requires a TTY. Re-run with explicit options (for example: --yes, --endpoint, --api-key)."
+      );
+    }
+  };
+  return {
+    async confirm(message, defaultValue = true) {
+      assertInteractive();
+      const answer = await clackConfirm({
+        message,
+        initialValue: defaultValue,
+        input: process.stdin,
+        output: process.stdout
+      });
+      if (isCancel(answer)) {
+        clackCancel("Cancelled.");
+        return false;
+      }
+      return answer;
+    },
+    async input(message, defaultValue = "") {
+      assertInteractive();
+      const answer = await clackText({
+        message,
+        defaultValue,
+        placeholder: defaultValue || void 0,
+        input: process.stdin,
+        output: process.stdout
+      });
+      if (isCancel(answer)) {
+        clackCancel("Cancelled.");
+        throw new Error("Cancelled.");
+      }
+      const normalized = answer.trim();
+      return normalized || defaultValue;
+    },
+    async password(message) {
+      assertInteractive();
+      const answer = await clackPassword({
+        message,
+        input: process.stdin,
+        output: process.stdout
+      });
+      if (isCancel(answer)) {
+        clackCancel("Cancelled.");
+        throw new Error("Cancelled.");
+      }
+      return answer.trim();
+    }
+  };
+}
+var defaultCommandRunner = (command, args, options) => new Promise((resolve2) => {
+  const child = spawn(command, args, {
+    cwd: options?.cwd,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout?.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+  child.on("error", (error) => {
+    const message = error.message || "command failed to start";
+    resolve2({ code: 127, stdout, stderr: `${stderr}${message}` });
+  });
+  child.on("close", (code) => {
+    resolve2({ code: code ?? 1, stdout, stderr });
+  });
+});
+
+// src/cli.ts
+var defaultLogger = createConsola();
+var nonNegativeIntegerSchema = z2.coerce.number().int().nonnegative();
+var positiveIntegerSchema = z2.coerce.number().int().positive();
+var jsonObjectSchema = z2.record(z2.unknown());
+var TRAILING_SLASHES_REGEX = /\/+$/;
+function parseNonNegativeInteger(value, optionName) {
+  const parsed = nonNegativeIntegerSchema.safeParse(value);
+  if (!parsed.success) {
+    throw new InvalidArgumentError(
+      `${optionName} must be a non-negative integer`
+    );
+  }
+  return parsed.data;
+}
+function parsePositiveInteger(value, optionName) {
+  const parsed = positiveIntegerSchema.safeParse(value);
+  if (!parsed.success) {
+    throw new InvalidArgumentError(`${optionName} must be a positive integer`);
+  }
+  return parsed.data;
+}
+function parsePort2(value, optionName) {
+  return parsePortOption(value, optionName);
+}
+function parseEndpoint(value, optionName) {
+  const endpoint = trimString2(value);
+  if (!endpoint) {
+    throw new InvalidArgumentError(`${optionName} cannot be empty`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new InvalidArgumentError(`${optionName} must be a valid URL`);
+  }
+  if (!(parsed.protocol === "http:" || parsed.protocol === "https:")) {
+    throw new InvalidArgumentError(
+      `${optionName} must use http:// or https://`
+    );
+  }
+  return endpoint.replace(TRAILING_SLASHES_REGEX, "");
+}
+function parseConfigSetKey(value) {
+  const normalized = value.trim().toLowerCase();
+  if (["endpoint", "base-url", "base_url"].includes(normalized)) {
+    return "endpoint";
+  }
+  if (["producer-id", "producer_id"].includes(normalized)) {
+    return "producer-id";
+  }
+  if (["api-key", "api_key"].includes(normalized)) {
+    return "api-key";
+  }
+  throw new InvalidArgumentError(
+    "config key must be one of: endpoint, producer-id, api-key"
+  );
+}
+function parseJsonOption(value, schema, optionName, invalidShapeMessage) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new InvalidArgumentError(`${optionName} must be valid JSON`);
+  }
+  const result = schema.safeParse(parsed);
+  if (!result.success) {
+    throw new InvalidArgumentError(
+      `${optionName} must be ${invalidShapeMessage}`
+    );
+  }
+  return result.data;
+}
+function parseJsonObject(value, optionName) {
+  return parseJsonOption(value, jsonObjectSchema, optionName, "a JSON object");
+}
+function parseEventRefs(value) {
+  return parseJsonObject(value, "--refs");
+}
+function parseSessionMetadataFilters(value) {
+  const parsed = parseJsonObject(value, "--metadata");
+  const filters = {};
+  for (const [key, rawValue] of Object.entries(parsed)) {
+    if (key.trim().length === 0) {
+      throw new InvalidArgumentError("--metadata keys must be non-empty");
+    }
+    if (typeof rawValue !== "string") {
+      throw new InvalidArgumentError("--metadata values must be strings");
+    }
+    filters[key] = rawValue;
+  }
+  return filters;
+}
+function getGlobalOptions(command) {
+  return command.optsWithGlobals();
+}
+function trimString2(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveBaseUrl(config, options) {
+  const defaultBaseUrl = `http://localhost:${DEFAULT_API_PORT}`;
+  return trimString2(options.baseUrl) ?? trimString2(process.env.STARCITE_BASE_URL) ?? trimString2(config.baseUrl) ?? defaultBaseUrl;
+}
+async function resolveGlobalOptions(command) {
+  const options = getGlobalOptions(command);
+  const configDir = resolveConfigDir(options.configDir);
+  const store = new StarciteCliStore(configDir);
+  const config = await store.readConfig();
+  const apiKey = trimString2(options.token) ?? await store.readApiKey();
+  return {
+    baseUrl: resolveBaseUrl(config, options),
+    apiKey,
+    json: options.json,
+    store
+  };
+}
+async function promptForEndpoint(prompt, defaultEndpoint) {
+  while (true) {
+    const answer = await prompt.input("Starcite endpoint URL", defaultEndpoint);
+    try {
+      return parseEndpoint(answer, "endpoint");
+    } catch {
+    }
+  }
+}
+async function promptForApiKey(prompt) {
+  const message = "Paste your Starcite API key";
+  const answer = prompt.password ? await prompt.password(message) : await prompt.input(message, "");
+  return trimString2(answer) ?? "";
+}
+function formatTailEvent(event) {
+  const actorLabel = event.agent ?? event.actor;
+  if (event.text) {
+    return `[${actorLabel}] ${event.text}`;
+  }
+  return `[${actorLabel}] ${JSON.stringify(event.payload)}`;
+}
+function buildProgram(deps = {}) {
+  const createClient = deps.createClient ?? ((baseUrl, apiKey) => createStarciteClient({
+    baseUrl,
+    apiKey
+  }));
+  const logger = deps.logger ?? defaultLogger;
+  const prompt = deps.prompt ?? createDefaultPrompt();
+  const runCommand = deps.runCommand ?? defaultCommandRunner;
+  const program = new Command();
+  program.name("starcite").description("Starcite CLI").showHelpAfterError().option("-u, --base-url <url>", "Starcite API base URL").option("-k, --token <token>", "Starcite API key / service JWT").option(
+    "--config-dir <path>",
+    "Starcite CLI config directory (default: ~/.starcite)"
+  ).option("--json", "Output JSON");
+  program.command("init").description("Initialize Starcite CLI config for a remote instance").option("--endpoint <url>", "Starcite endpoint URL").option("--api-key <key>", "API key to store").option("-y, --yes", "Skip prompts and only use provided options").action(async function initAction(options) {
+    const { baseUrl, json, store } = await resolveGlobalOptions(this);
+    const defaultEndpoint = parseEndpoint(baseUrl, "endpoint");
+    let endpoint = defaultEndpoint;
+    if (options.endpoint) {
+      endpoint = parseEndpoint(options.endpoint, "--endpoint");
+    } else if (!options.yes) {
+      endpoint = await promptForEndpoint(prompt, defaultEndpoint);
+    }
+    await store.updateConfig({ baseUrl: endpoint });
+    let apiKey = trimString2(options.apiKey);
+    if (!(apiKey || options.yes)) {
+      apiKey = await promptForApiKey(prompt);
+    }
+    if (apiKey) {
+      await store.saveApiKey(apiKey);
+      await store.updateConfig({ apiKey: void 0 });
+    }
+    if (json) {
+      logger.info(
+        JSON.stringify(
+          {
+            configDir: store.directory,
+            endpoint,
+            apiKeySaved: Boolean(apiKey)
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    logger.info(`Initialized Starcite CLI in ${store.directory}`);
+    logger.info(`Endpoint set to ${endpoint}`);
+    if (apiKey) {
+      logger.info("API key saved. You can now run create/append/tail.");
+    } else {
+      logger.info("API key not set. Run `starcite auth login` when ready.");
+    }
+  });
+  program.command("config").description("Manage CLI configuration").addCommand(
+    new Command("set").description("Set a configuration value").argument("<key>", "endpoint | producer-id | api-key").argument("<value>", "value to store").action(async function configSetAction(key, value) {
+      const { store } = await resolveGlobalOptions(this);
+      const parsedKey = parseConfigSetKey(key);
+      if (parsedKey === "endpoint") {
+        const endpoint = parseEndpoint(value, "endpoint");
+        await store.updateConfig({ baseUrl: endpoint });
+        logger.info(`Endpoint set to ${endpoint}`);
+        return;
+      }
+      if (parsedKey === "producer-id") {
+        const producerId = trimString2(value);
+        if (!producerId) {
+          throw new InvalidArgumentError("producer-id cannot be empty");
+        }
+        await store.updateConfig({ producerId });
+        logger.info(`Producer ID set to ${producerId}`);
+        return;
+      }
+      await store.saveApiKey(value);
+      await store.updateConfig({ apiKey: void 0 });
+      logger.info("API key saved.");
+    })
+  ).addCommand(
+    new Command("show").description("Show current configuration").action(async function configShowAction() {
+      const { baseUrl, store } = await resolveGlobalOptions(this);
+      const config = await store.readConfig();
+      const apiKey = await store.readApiKey();
+      const fromEnv = trimString2(process.env.STARCITE_API_KEY);
+      let apiKeySource = "unset";
+      if (fromEnv) {
+        apiKeySource = "env";
+      } else if (apiKey) {
+        apiKeySource = "stored";
+      }
+      logger.info(
+        JSON.stringify(
+          {
+            endpoint: config.baseUrl ?? baseUrl,
+            producerId: config.producerId ?? null,
+            apiKey: apiKey ? "***" : null,
+            apiKeySource,
+            configDir: store.directory
+          },
+          null,
+          2
+        )
+      );
+    })
+  );
+  program.command("auth").description("Manage API key authentication").addCommand(
+    new Command("login").description("Save an API key for authenticated requests").option("--api-key <key>", "API key to store").action(async function authLoginAction(options) {
+      const { store } = await resolveGlobalOptions(this);
+      let apiKey = trimString2(options.apiKey);
+      if (!apiKey) {
+        apiKey = await promptForApiKey(prompt);
+      }
+      if (!apiKey) {
+        throw new Error("API key cannot be empty");
+      }
+      await store.saveApiKey(apiKey);
+      await store.updateConfig({ apiKey: void 0 });
+      logger.info("API key saved.");
+    })
+  ).addCommand(
+    new Command("logout").description("Remove the saved API key").action(async function authLogoutAction() {
+      const { store } = await resolveGlobalOptions(this);
+      await store.clearApiKey();
+      logger.info("Saved API key removed.");
+    })
+  ).addCommand(
+    new Command("status").description("Show authentication status").action(async function authStatusAction() {
+      const { store } = await resolveGlobalOptions(this);
+      const apiKey = await store.readApiKey();
+      const fromEnv = trimString2(process.env.STARCITE_API_KEY);
+      if (fromEnv) {
+        logger.info("Authenticated via STARCITE_API_KEY.");
+        return;
+      }
+      if (apiKey) {
+        logger.info("Authenticated via saved API key.");
+        return;
+      }
+      logger.info("No API key configured. Run `starcite auth login`.");
+    })
+  );
+  program.command("sessions").description("Manage sessions").addCommand(
+    new Command("list").description("List sessions").option(
+      "--limit <count>",
+      "Maximum sessions to return",
+      (value) => parsePositiveInteger(value, "--limit")
+    ).option("--cursor <cursor>", "Pagination cursor").option("--metadata <json>", "Metadata filter JSON object").action(async function sessionsListAction(options) {
+      const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
+      const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
+      const metadata = options.metadata ? parseSessionMetadataFilters(options.metadata) : void 0;
+      const cursor = options.cursor?.trim();
+      if (options.cursor !== void 0 && !cursor) {
+        throw new InvalidArgumentError("--cursor must be non-empty");
+      }
+      const page = await client.listSessions({
+        limit: options.limit,
+        cursor,
+        metadata
+      });
+      if (json) {
+        logger.info(JSON.stringify(page, null, 2));
+        return;
+      }
+      if (page.sessions.length === 0) {
+        logger.info("No sessions found.");
+        return;
+      }
+      logger.info("id	title	created_at");
+      for (const session of page.sessions) {
+        logger.info(
+          `${session.id}	${session.title ?? ""}	${session.created_at}`
+        );
+      }
+      if (page.next_cursor) {
+        logger.info(`next_cursor=${page.next_cursor}`);
+      }
+    })
+  );
+  program.command("up").description("Start local Starcite services with Docker").option("-y, --yes", "Skip confirmation prompts and use defaults").option(
+    "--port <port>",
+    "Starcite API port",
+    (value) => parsePort2(value, "--port")
+  ).option(
+    "--db-port <port>",
+    "Postgres port",
+    (value) => parsePort2(value, "--db-port")
+  ).option("--image <image>", "Override Starcite image").action(async function upAction(options) {
+    const { baseUrl, store } = await resolveGlobalOptions(this);
+    await runUpWizard({
+      baseUrl,
+      logger,
+      options,
+      prompt,
+      runCommand,
+      store
+    });
+  });
+  program.command("down").description("Stop and remove local Starcite services").option("-y, --yes", "Skip confirmation prompt").option("--no-volumes", "Keep Postgres volume data").action(async function downAction(options) {
+    const { store } = await resolveGlobalOptions(this);
+    await runDownWizard({
+      logger,
+      options,
+      prompt,
+      runCommand,
+      store
+    });
+  });
+  program.command("create").description("Create a session").option("--id <id>", "Session ID").option("--title <title>", "Session title").option("--metadata <json>", "Session metadata JSON object").action(async function createAction(options) {
+    const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
+    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
+    const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
+    const session = await client.create({
+      id: options.id,
+      title: options.title,
+      metadata
+    });
+    if (json) {
+      logger.info(
+        JSON.stringify(session.record ?? { id: session.id }, null, 2)
+      );
+      return;
+    }
+    logger.info(session.id);
+  });
+  program.command("append <sessionId>").description("Append an event").option("--agent <agent>", "Agent name (high-level mode)").option("--text <text>", "Text content (high-level mode)").option("--type <type>", "Event type", "content").option("--source <source>", "Event source").option(
+    "--producer-id <id>",
+    "Producer identity (auto-generated if omitted)"
+  ).option(
+    "--producer-seq <seq>",
+    "Producer sequence (defaults to persisted state, starting at 1)",
+    (value) => parsePositiveInteger(value, "--producer-seq")
+  ).option("--actor <actor>", "Raw actor field (raw mode)").option("--payload <json>", "Raw payload JSON object (raw mode)").option("--metadata <json>", "Event metadata JSON object").option("--refs <json>", "Event refs JSON object").option("--idempotency-key <key>", "Idempotency key").option(
+    "--expected-seq <seq>",
+    "Expected sequence",
+    (value) => parseNonNegativeInteger(value, "--expected-seq")
+  ).action(async function appendAction(sessionId, options) {
+    const { baseUrl, apiKey, json, store } = await resolveGlobalOptions(this);
+    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
+    const session = client.session(sessionId);
+    const metadata = options.metadata ? parseJsonObject(options.metadata, "--metadata") : void 0;
+    const refs = options.refs ? parseEventRefs(options.refs) : void 0;
+    const highLevelMode = options.agent !== void 0 || options.text !== void 0;
+    const rawMode = options.actor !== void 0 || options.payload !== void 0;
+    if (highLevelMode && rawMode) {
+      throw new Error(
+        "Choose either high-level mode (--agent and --text) or raw mode (--actor and --payload), not both"
+      );
+    }
+    const producerId = await store.resolveProducerId(options.producerId);
+    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+    const contextKey = buildSeqContextKey(
+      normalizedBaseUrl,
+      sessionId,
+      producerId
+    );
+    const response = await store.withStateLock(async () => {
+      const producerSeq = options.producerSeq ?? await store.readNextSeq(contextKey);
+      const appendOptions = {
+        ...options,
+        producerId,
+        producerSeq
+      };
+      const appendResponse = highLevelMode ? await appendHighLevel(session, appendOptions, metadata, refs) : await appendRaw(session, appendOptions, metadata, refs);
+      await store.bumpNextSeq(contextKey, producerSeq);
+      return appendResponse;
+    });
+    if (json) {
+      logger.info(JSON.stringify(response, null, 2));
+      return;
+    }
+    logger.info(
+      `seq=${response.seq} last_seq=${response.last_seq} deduped=${response.deduped}`
+    );
+  });
+  program.command("tail <sessionId>").description("Tail events from a session").option(
+    "--cursor <cursor>",
+    "Replay cursor",
+    (value) => parseNonNegativeInteger(value, "--cursor")
+  ).option("--agent <agent>", "Filter by agent name").option(
+    "--limit <count>",
+    "Stop after N events",
+    (value) => parseNonNegativeInteger(value, "--limit")
+  ).action(async function tailAction(sessionId, options) {
+    const { baseUrl, apiKey, json } = await resolveGlobalOptions(this);
+    const client = apiKey ? createClient(baseUrl, apiKey) : createClient(baseUrl);
+    const session = client.session(sessionId);
+    const abortController = new AbortController();
+    const onSigint = () => {
+      abortController.abort();
+    };
+    process.once("SIGINT", onSigint);
+    try {
+      let emitted = 0;
+      for await (const event of session.tail({
+        cursor: options.cursor ?? 0,
+        agent: options.agent,
+        signal: abortController.signal
+      })) {
+        if (json) {
+          logger.info(JSON.stringify(event));
+        } else {
+          logger.info(formatTailEvent(event));
+        }
+        emitted += 1;
+        if (options.limit !== void 0 && emitted >= options.limit) {
+          abortController.abort();
+          break;
+        }
+      }
+    } finally {
+      process.removeListener("SIGINT", onSigint);
+    }
+  });
+  return program;
+}
+function appendHighLevel(session, options, metadata, refs) {
+  if (!(options.agent && options.text)) {
+    throw new Error(
+      "--agent and --text are required for high-level append mode"
+    );
+  }
+  return session.append({
+    agent: options.agent,
+    producerId: options.producerId,
+    producerSeq: options.producerSeq,
+    text: options.text,
+    type: options.type,
+    source: options.source,
+    metadata,
+    refs,
+    idempotencyKey: options.idempotencyKey,
+    expectedSeq: options.expectedSeq
+  });
+}
+function appendRaw(session, options, metadata, refs) {
+  if (!(options.actor && options.payload)) {
+    throw new Error(
+      "Raw append mode requires --actor and --payload, or use --agent and --text"
+    );
+  }
+  return session.appendRaw({
+    type: options.type,
+    payload: parseJsonObject(options.payload, "--payload"),
+    actor: options.actor,
+    producer_id: options.producerId,
+    producer_seq: options.producerSeq,
+    source: options.source,
+    metadata,
+    refs,
+    idempotency_key: options.idempotencyKey,
+    expected_seq: options.expectedSeq
+  });
+}
+async function run(argv = process.argv, deps = {}) {
+  const program = buildProgram(deps);
+  try {
+    await program.parseAsync(argv);
+  } catch (error) {
+    if (error instanceof StarciteApiError) {
+      const logger2 = deps.logger ?? defaultLogger;
+      logger2.error(`${error.code} (${error.status}): ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (error instanceof Error) {
+      const logger2 = deps.logger ?? defaultLogger;
+      logger2.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    const logger = deps.logger ?? defaultLogger;
+    logger.error("Unknown error");
+    process.exitCode = 1;
+  }
+}
+
+// src/index.ts
+run();
+//# sourceMappingURL=index.js.map