@tsctl/cli 0.2.0

package/src/client/index.ts

@@ -0,0 +1,55 @@
+import Typesense, { Client } from "typesense";
+import type { ConnectionConfig } from "../types/index.js";
+
+let client: Client | null = null;
+
+export function initClient(config: ConnectionConfig): Client {
+  client = new Typesense.Client({
+    nodes: config.nodes,
+    apiKey: config.apiKey,
+    connectionTimeoutSeconds: config.connectionTimeoutSeconds ?? 10,
+    retryIntervalSeconds: config.retryIntervalSeconds ?? 0.1,
+    numRetries: config.numRetries ?? 3,
+  });
+  return client;
+}
+
+export function getClient(): Client {
+  if (!client) {
+    throw new Error(
+      "Typesense client not initialized. Call initClient() first or run 'tsctl init'"
+    );
+  }
+  return client;
+}
+
+export async function testConnection(): Promise<boolean> {
+  try {
+    const c = getClient();
+    await c.health.retrieve();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getClientFromEnv(): Client {
+  const host = process.env["TYPESENSE_HOST"] || "localhost";
+  const port = parseInt(process.env["TYPESENSE_PORT"] || "8108", 10);
+  const protocol = (process.env["TYPESENSE_PROTOCOL"] || "http") as
+    | "http"
+    | "https";
+  const apiKey = process.env["TYPESENSE_API_KEY"];
+
+  if (!apiKey) {
+    throw new Error(
+      "TYPESENSE_API_KEY environment variable is required.\n" +
+        "Set it in your environment or create a .env file."
+    );
+  }
+
+  return initClient({
+    nodes: [{ host, port, protocol }],
+    apiKey,
+  });
+}

package/src/config/loader.ts

@@ -0,0 +1,158 @@
+import { cosmiconfig } from "cosmiconfig";
+import { resolve, dirname } from "path";
+import { pathToFileURL } from "url";
+import { TypesenseConfigSchema, type TypesenseConfig } from "../types/index.js";
+
+const MODULE_NAME = "tsctl";
+
+/**
+ * TypeScript/ESM loader for cosmiconfig
+ */
+async function typeScriptLoader(filepath: string): Promise<unknown> {
+  const fileUrl = pathToFileURL(filepath).href;
+  // Add cache busting to ensure we get fresh config
+  const cacheBustedUrl = `${fileUrl}?t=${Date.now()}`;
+  const module = await import(cacheBustedUrl);
+  return module.default || module;
+}
+
+/**
+ * Create the cosmiconfig explorer with all supported file formats
+ *
+ * Supported config files (in search order):
+ * - package.json ("tsctl" property)
+ * - .tsctlrc (JSON or YAML)
+ * - .tsctlrc.json
+ * - .tsctlrc.yaml / .tsctlrc.yml
+ * - .tsctlrc.js / .tsctlrc.cjs / .tsctlrc.mjs
+ * - .tsctlrc.ts / .tsctlrc.cts / .tsctlrc.mts
+ * - tsctl.config.js / tsctl.config.cjs / tsctl.config.mjs
+ * - tsctl.config.ts / tsctl.config.cts / tsctl.config.mts
+ * - tsctl.config.json
+ * - tsctl.config.yaml / tsctl.config.yml
+ * - typesense.config.js / typesense.config.cjs / typesense.config.mjs (legacy)
+ * - typesense.config.ts / typesense.config.cts / typesense.config.mts (legacy)
+ */
+function createExplorer() {
+  return cosmiconfig(MODULE_NAME, {
+    searchPlaces: [
+      // package.json
+      "package.json",
+
+      // RC files (JSON/YAML)
+      `.${MODULE_NAME}rc`,
+      `.${MODULE_NAME}rc.json`,
+      `.${MODULE_NAME}rc.yaml`,
+      `.${MODULE_NAME}rc.yml`,
+
+      // RC files (JS)
+      `.${MODULE_NAME}rc.js`,
+      `.${MODULE_NAME}rc.cjs`,
+      `.${MODULE_NAME}rc.mjs`,
+
+      // RC files (TS)
+      `.${MODULE_NAME}rc.ts`,
+      `.${MODULE_NAME}rc.cts`,
+      `.${MODULE_NAME}rc.mts`,
+
+      // Config files (JS)
+      `${MODULE_NAME}.config.js`,
+      `${MODULE_NAME}.config.cjs`,
+      `${MODULE_NAME}.config.mjs`,
+
+      // Config files (TS)
+      `${MODULE_NAME}.config.ts`,
+      `${MODULE_NAME}.config.cts`,
+      `${MODULE_NAME}.config.mts`,
+
+      // Config files (JSON/YAML)
+      `${MODULE_NAME}.config.json`,
+      `${MODULE_NAME}.config.yaml`,
+      `${MODULE_NAME}.config.yml`,
+
+      // Legacy config files (for backwards compatibility)
+      "typesense.config.js",
+      "typesense.config.cjs",
+      "typesense.config.mjs",
+      "typesense.config.ts",
+      "typesense.config.cts",
+      "typesense.config.mts",
+      "typesense.config.json",
+      "typesense.config.yaml",
+      "typesense.config.yml",
+    ],
+    loaders: {
+      ".ts": typeScriptLoader,
+      ".cts": typeScriptLoader,
+      ".mts": typeScriptLoader,
+      ".mjs": typeScriptLoader,
+    },
+  });
+}
+
+/**
+ * Find the config file in the given directory or parent directories
+ */
+export async function findConfigFile(startDir: string = process.cwd()): Promise<string | null> {
+  const explorer = createExplorer();
+  const result = await explorer.search(startDir);
+  return result?.filepath || null;
+}
+
+/**
+ * Load and validate a config file
+ *
+ * @param configPath - Optional path to config file. If not provided, searches for config.
+ * @returns Validated TypesenseConfig
+ */
+export async function loadConfig(configPath?: string): Promise<TypesenseConfig> {
+  const explorer = createExplorer();
+
+  let result;
+
+  if (configPath) {
+    // Load specific file
+    const resolvedPath = resolve(configPath);
+    result = await explorer.load(resolvedPath);
+  } else {
+    // Search for config
+    result = await explorer.search();
+  }
+
+  if (!result || result.isEmpty) {
+    throw new Error(
+      "No config file found. Create one of the following:\n" +
+      "  - tsctl.config.ts (recommended)\n" +
+      "  - tsctl.config.js\n" +
+      "  - tsctl.config.json\n" +
+      "  - tsctl.config.yaml\n" +
+      "  - .tsctlrc\n" +
+      "  - \"tsctl\" property in package.json\n" +
+      "\nOr specify a config file with --config"
+    );
+  }
+
+  try {
+    // Validate with Zod
+    const validated = TypesenseConfigSchema.parse(result.config);
+    return validated;
+  } catch (error) {
+    if (error instanceof Error && error.name === "ZodError") {
+      throw new Error(`Invalid config in ${result.filepath}:\n${error.message}`);
+    }
+    throw new Error(
+      `Failed to parse config file: ${result.filepath}\n${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Get the directory containing the config file
+ */
+export async function getConfigDir(configPath?: string): Promise<string> {
+  const configFile = configPath ? resolve(configPath) : await findConfigFile();
+  if (!configFile) {
+    return process.cwd();
+  }
+  return dirname(configFile);
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Main entry point for library usage
+// Users can import { defineConfig } from "@tsctl/cli"
+
+export {
+  defineConfig,
+  // Types
+  type TypesenseConfig,
+  type CollectionConfig,
+  type AliasConfig,
+  type SynonymConfig,
+  type SynonymSetConfig,
+  type SynonymSetItem,
+  type OverrideConfig,
+  type CurationSetConfig,
+  type CurationItem,
+  type StopwordSetConfig,
+  type PresetConfig,
+  type StemmingDictionaryConfig,
+  type StemmingWord,
+  type AnalyticsRuleConfig,
+  type ApiKeyConfig,
+  type Field,
+  type FieldType,
+  type ConnectionConfig,
+  // Schemas (for validation)
+  TypesenseConfigSchema,
+  CollectionConfigSchema,
+  AliasConfigSchema,
+  SynonymConfigSchema,
+  SynonymSetConfigSchema,
+  SynonymSetItemSchema,
+  OverrideConfigSchema,
+  CurationSetConfigSchema,
+  CurationItemSchema,
+  CurationRuleSchema,
+  StopwordSetConfigSchema,
+  PresetConfigSchema,
+  StemmingDictionaryConfigSchema,
+  StemmingWordSchema,
+  AnalyticsRuleConfigSchema,
+  ApiKeyConfigSchema,
+  FieldSchema,
+  FieldTypeSchema,
+  ConnectionConfigSchema,
+} from "./types/index.js";

package/src/migrate/index.ts

@@ -0,0 +1,220 @@
+import chalk from "chalk";
+import ora from "ora";
+import {
+  getCollection,
+  createCollection,
+  deleteCollection,
+  listCollections,
+} from "../resources/collection.js";
+import { upsertAlias, getAlias } from "../resources/alias.js";
+import type { CollectionConfig, AliasConfig } from "../types/index.js";
+
+export interface MigrationPlan {
+  alias: string;
+  currentCollection: string | null;
+  newCollection: string;
+  newCollectionConfig: CollectionConfig;
+  steps: MigrationStep[];
+}
+
+export interface MigrationStep {
+  action: "create_collection" | "switch_alias" | "delete_old_collection";
+  description: string;
+  target: string;
+}
+
+export interface MigrationResult {
+  success: boolean;
+  newCollectionName: string;
+  oldCollectionName: string | null;
+  aliasName: string;
+  errors: string[];
+}
+
+/**
+ * Generate a versioned collection name
+ */
+export function generateVersionedName(baseName: string): string {
+  const timestamp = Date.now();
+  return `${baseName}_${timestamp}`;
+}
+
+/**
+ * Extract the base name from a versioned collection name
+ */
+export function extractBaseName(name: string): string {
+  // Try to extract base name by removing _<timestamp> suffix
+  const match = name.match(/^(.+)_\d{13}$/);
+  return match ? match[1]! : name;
+}
+
+/**
+ * Find all versions of a collection by base name
+ */
+export async function findCollectionVersions(baseName: string): Promise<CollectionConfig[]> {
+  const allCollections = await listCollections();
+  return allCollections.filter(
+    (c) => c.name === baseName || c.name.startsWith(`${baseName}_`)
+  );
+}
+
+/**
+ * Plan a blue/green migration
+ */
+export async function planMigration(
+  aliasName: string,
+  newCollectionConfig: CollectionConfig
+): Promise<MigrationPlan> {
+  const steps: MigrationStep[] = [];
+
+  // Get current alias target
+  const currentAlias = await getAlias(aliasName);
+  const currentCollection = currentAlias?.collection || null;
+
+  // Generate new collection name with timestamp
+  const baseName = extractBaseName(newCollectionConfig.name);
+  const newCollectionName = generateVersionedName(baseName);
+
+  // Update config with versioned name
+  const versionedConfig: CollectionConfig = {
+    ...newCollectionConfig,
+    name: newCollectionName,
+  };
+
+  // Step 1: Create new collection
+  steps.push({
+    action: "create_collection",
+    description: `Create new collection '${newCollectionName}'`,
+    target: newCollectionName,
+  });
+
+  // Step 2: Switch alias (user should index data between step 1 and 2)
+  steps.push({
+    action: "switch_alias",
+    description: `Switch alias '${aliasName}' to '${newCollectionName}'`,
+    target: aliasName,
+  });
+
+  // Step 3: Delete old collection (optional)
+  if (currentCollection) {
+    steps.push({
+      action: "delete_old_collection",
+      description: `Delete old collection '${currentCollection}'`,
+      target: currentCollection,
+    });
+  }
+
+  return {
+    alias: aliasName,
+    currentCollection,
+    newCollection: newCollectionName,
+    newCollectionConfig: versionedConfig,
+    steps,
+  };
+}
+
+/**
+ * Execute a migration step
+ */
+export async function executeMigrationStep(
+  plan: MigrationPlan,
+  step: MigrationStep
+): Promise<void> {
+  switch (step.action) {
+    case "create_collection":
+      await createCollection(plan.newCollectionConfig);
+      break;
+
+    case "switch_alias":
+      await upsertAlias({
+        name: plan.alias,
+        collection: plan.newCollection,
+      });
+      break;
+
+    case "delete_old_collection":
+      if (plan.currentCollection) {
+        await deleteCollection(plan.currentCollection);
+      }
+      break;
+  }
+}
+
+/**
+ * Execute a full migration
+ */
+export async function executeMigration(
+  plan: MigrationPlan,
+  options: {
+    skipDelete?: boolean;
+    onStep?: (step: MigrationStep, index: number) => void;
+  } = {}
+): Promise<MigrationResult> {
+  const result: MigrationResult = {
+    success: true,
+    newCollectionName: plan.newCollection,
+    oldCollectionName: plan.currentCollection,
+    aliasName: plan.alias,
+    errors: [],
+  };
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const step = plan.steps[i]!;
+
+    // Skip delete step if requested
+    if (step.action === "delete_old_collection" && options.skipDelete) {
+      continue;
+    }
+
+    if (options.onStep) {
+      options.onStep(step, i);
+    }
+
+    try {
+      await executeMigrationStep(plan, step);
+    } catch (error) {
+      result.success = false;
+      result.errors.push(
+        `Step ${i + 1} failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      break; // Stop on first error
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format migration plan for display
+ */
+export function formatMigrationPlan(plan: MigrationPlan): string {
+  const lines: string[] = [];
+
+  lines.push(chalk.bold("\nMigration Plan:\n"));
+
+  lines.push(`  Alias:              ${chalk.cyan(plan.alias)}`);
+  lines.push(
+    `  Current collection: ${plan.currentCollection ? chalk.yellow(plan.currentCollection) : chalk.gray("(none)")}`
+  );
+  lines.push(`  New collection:     ${chalk.green(plan.newCollection)}`);
+
+  lines.push(chalk.bold("\nSteps:\n"));
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const step = plan.steps[i]!;
+    const icon =
+      step.action === "create_collection"
+        ? chalk.green("+")
+        : step.action === "switch_alias"
+          ? chalk.blue("→")
+          : chalk.red("-");
+
+    lines.push(`  ${i + 1}. ${icon} ${step.description}`);
+  }
+
+  lines.push(chalk.yellow("\n⚠️  Important:"));
+  lines.push(chalk.yellow("  Index your data to the new collection before switching the alias."));
+  lines.push(chalk.yellow("  Use --skip-delete to keep the old collection for rollback."));
+
+  return lines.join("\n");
+}