@tsctl/cli 0.2.0

package/src/__tests__/migrate-advanced.test.ts

@@ -0,0 +1,197 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import {
+  generateVersionedName,
+  extractBaseName,
+  findCollectionVersions,
+  planMigration,
+  executeMigration,
+  formatMigrationPlan,
+} from "../migrate/index.js";
+import { createCollection, getCollection } from "../resources/collection.js";
+import { upsertAlias, getAlias } from "../resources/alias.js";
+import type { CollectionConfig } from "../types/index.js";
+
+describe("migrate advanced", () => {
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  describe("versioned naming", () => {
+    test("extractBaseName handles multiple underscores", () => {
+      expect(extractBaseName("my_cool_products_1706486400000")).toBe("my_cool_products");
+    });
+
+    test("extractBaseName ignores non-timestamp suffixes", () => {
+      expect(extractBaseName("products_v2")).toBe("products_v2");
+    });
+
+    test("extractBaseName handles plain name", () => {
+      expect(extractBaseName("products")).toBe("products");
+    });
+
+    test("generateVersionedName format is correct", () => {
+      const name = generateVersionedName("my_collection");
+      expect(name).toMatch(/^my_collection_\d{13}$/);
+    });
+  });
+
+  describe("findCollectionVersions", () => {
+    test("returns empty for non-existent collection", async () => {
+      const versions = await findCollectionVersions("nonexistent");
+      expect(versions).toHaveLength(0);
+    });
+
+    test("finds base collection and versioned copies", async () => {
+      await createCollection({
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await createCollection({
+        name: "products_1706486400000",
+        fields: [{ name: "title", type: "string" }],
+      });
+
+      const versions = await findCollectionVersions("products");
+      expect(versions).toHaveLength(2);
+    });
+
+    test("does not include unrelated collections", async () => {
+      await createCollection({
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await createCollection({
+        name: "orders",
+        fields: [{ name: "id", type: "string" }],
+      });
+
+      const versions = await findCollectionVersions("products");
+      expect(versions).toHaveLength(1);
+      expect(versions[0]!.name).toBe("products");
+    });
+  });
+
+  describe("planMigration", () => {
+    test("creates correct plan without existing alias", async () => {
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [
+          { name: "title", type: "string" },
+          { name: "price", type: "float" },
+        ],
+      };
+
+      const plan = await planMigration("products_live", config);
+      expect(plan.alias).toBe("products_live");
+      expect(plan.currentCollection).toBeNull();
+      expect(plan.newCollection).toMatch(/^products_\d{13}$/);
+      expect(plan.newCollectionConfig.name).toBe(plan.newCollection);
+      expect(plan.newCollectionConfig.fields).toHaveLength(2);
+    });
+
+    test("plan includes delete step when alias exists", async () => {
+      await createCollection({
+        name: "products_old",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_old" });
+
+      const plan = await planMigration("products_live", {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      });
+
+      expect(plan.currentCollection).toBe("products_old");
+      const stepActions = plan.steps.map((s) => s.action);
+      expect(stepActions).toContain("create_collection");
+      expect(stepActions).toContain("switch_alias");
+      expect(stepActions).toContain("delete_old_collection");
+    });
+  });
+
+  describe("executeMigration", () => {
+    test("full migration with schema change", async () => {
+      // Create v1
+      await createCollection({
+        name: "products_v1",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_v1" });
+
+      // Migrate to v2 with new fields
+      const plan = await planMigration("products_live", {
+        name: "products",
+        fields: [
+          { name: "title", type: "string" },
+          { name: "description", type: "string", optional: true },
+          { name: "price", type: "float" },
+        ],
+      });
+
+      const result = await executeMigration(plan);
+      expect(result.success).toBe(true);
+
+      // Verify new collection has updated schema
+      const newCollection = await getCollection(plan.newCollection);
+      expect(newCollection).not.toBeNull();
+      expect(newCollection!.fields.length).toBeGreaterThanOrEqual(3);
+
+      // Verify alias points to new collection
+      const alias = await getAlias("products_live");
+      expect(alias!.collection).toBe(plan.newCollection);
+
+      // Verify old collection was deleted
+      const oldCollection = await getCollection("products_v1");
+      expect(oldCollection).toBeNull();
+    });
+
+    test("migration with skipDelete preserves old collection", async () => {
+      await createCollection({
+        name: "old_coll",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "my_alias", collection: "old_coll" });
+
+      const plan = await planMigration("my_alias", {
+        name: "my_collection",
+        fields: [{ name: "title", type: "string" }],
+      });
+
+      const result = await executeMigration(plan, { skipDelete: true });
+      expect(result.success).toBe(true);
+
+      // Old collection should still exist
+      const oldColl = await getCollection("old_coll");
+      expect(oldColl).not.toBeNull();
+
+      // But alias should point to new
+      const alias = await getAlias("my_alias");
+      expect(alias!.collection).toBe(plan.newCollection);
+    });
+
+    test("formatMigrationPlan produces readable output", async () => {
+      await createCollection({
+        name: "products_old",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_old" });
+
+      const plan = await planMigration("products_live", {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      });
+
+      const output = formatMigrationPlan(plan);
+      expect(output).toContain("Migration Plan");
+      expect(output).toContain("products_live");
+      expect(output).toContain("products_old");
+      expect(output).toContain(plan.newCollection);
+    });
+  });
+});

package/src/__tests__/migrate.test.ts

@@ -0,0 +1,220 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import {
+  generateVersionedName,
+  extractBaseName,
+  findCollectionVersions,
+  planMigration,
+  executeMigration,
+} from "../migrate/index.js";
+import { createCollection, getCollection } from "../resources/collection.js";
+import { upsertAlias, getAlias } from "../resources/alias.js";
+import type { CollectionConfig } from "../types/index.js";
+
+describe("migrate", () => {
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  describe("generateVersionedName", () => {
+    test("appends timestamp to base name", () => {
+      const name = generateVersionedName("products");
+      expect(name).toMatch(/^products_\d{13}$/);
+    });
+
+    test("generates unique names on subsequent calls", async () => {
+      const name1 = generateVersionedName("products");
+      // Tiny delay to ensure different timestamp
+      await new Promise((r) => setTimeout(r, 5));
+      const name2 = generateVersionedName("products");
+      expect(name1).not.toBe(name2);
+    });
+  });
+
+  describe("extractBaseName", () => {
+    test("extracts base name from versioned name", () => {
+      expect(extractBaseName("products_1706486400000")).toBe("products");
+    });
+
+    test("returns original name if not versioned", () => {
+      expect(extractBaseName("products")).toBe("products");
+    });
+
+    test("handles names with underscores", () => {
+      expect(extractBaseName("my_products_1706486400000")).toBe("my_products");
+    });
+  });
+
+  describe("findCollectionVersions", () => {
+    test("finds all versions of a collection", async () => {
+      await createCollection({
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await createCollection({
+        name: "products_1706486400000",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await createCollection({
+        name: "products_1706486500000",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await createCollection({
+        name: "users",
+        fields: [{ name: "name", type: "string" }],
+      });
+
+      const versions = await findCollectionVersions("products");
+      expect(versions).toHaveLength(3);
+      const names = versions.map((v) => v.name);
+      expect(names).toContain("products");
+      expect(names).toContain("products_1706486400000");
+      expect(names).not.toContain("users");
+    });
+
+    test("returns empty array for non-existent base name", async () => {
+      const versions = await findCollectionVersions("nonexistent");
+      expect(versions).toHaveLength(0);
+    });
+  });
+
+  describe("planMigration", () => {
+    test("plans migration without existing alias", async () => {
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      };
+
+      const plan = await planMigration("products_live", config);
+
+      expect(plan.alias).toBe("products_live");
+      expect(plan.currentCollection).toBeNull();
+      expect(plan.newCollection).toMatch(/^products_\d{13}$/);
+      expect(plan.steps).toHaveLength(2); // create + switch (no delete since no current)
+      expect(plan.steps[0]!.action).toBe("create_collection");
+      expect(plan.steps[1]!.action).toBe("switch_alias");
+    });
+
+    test("plans migration with existing alias", async () => {
+      await createCollection({
+        name: "products_old",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_old" });
+
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [
+          { name: "title", type: "string" },
+          { name: "description", type: "string" },
+        ],
+      };
+
+      const plan = await planMigration("products_live", config);
+
+      expect(plan.currentCollection).toBe("products_old");
+      expect(plan.steps).toHaveLength(3); // create + switch + delete
+      expect(plan.steps[2]!.action).toBe("delete_old_collection");
+    });
+  });
+
+  describe("executeMigration", () => {
+    test("executes full migration", async () => {
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      };
+
+      const plan = await planMigration("products_live", config);
+      const result = await executeMigration(plan);
+
+      expect(result.success).toBe(true);
+      expect(result.errors).toHaveLength(0);
+
+      // Verify new collection exists
+      const collection = await getCollection(plan.newCollection);
+      expect(collection).not.toBeNull();
+
+      // Verify alias points to new collection
+      const alias = await getAlias("products_live");
+      expect(alias).not.toBeNull();
+      expect(alias!.collection).toBe(plan.newCollection);
+    });
+
+    test("executes migration with skipDelete", async () => {
+      await createCollection({
+        name: "products_old",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_old" });
+
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      };
+
+      const plan = await planMigration("products_live", config);
+      const result = await executeMigration(plan, { skipDelete: true });
+
+      expect(result.success).toBe(true);
+
+      // Old collection should still exist
+      const oldCollection = await getCollection("products_old");
+      expect(oldCollection).not.toBeNull();
+    });
+
+    test("calls onStep callback for each step", async () => {
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [{ name: "title", type: "string" }],
+      };
+
+      const plan = await planMigration("products_live", config);
+      const steps: number[] = [];
+
+      await executeMigration(plan, {
+        onStep: (_step, index) => {
+          steps.push(index);
+        },
+      });
+
+      expect(steps).toEqual([0, 1]);
+    });
+
+    test("migration replaces old collection when not skipping delete", async () => {
+      // Setup: existing collection and alias
+      await createCollection({
+        name: "products_old",
+        fields: [{ name: "title", type: "string" }],
+      });
+      await upsertAlias({ name: "products_live", collection: "products_old" });
+
+      const config: CollectionConfig = {
+        name: "products",
+        fields: [
+          { name: "title", type: "string" },
+          { name: "price", type: "float" },
+        ],
+      };
+
+      const plan = await planMigration("products_live", config);
+      const result = await executeMigration(plan);
+
+      expect(result.success).toBe(true);
+
+      // Old collection should be deleted
+      const oldCollection = await getCollection("products_old");
+      expect(oldCollection).toBeNull();
+
+      // New collection should exist with new schema
+      const newCollection = await getCollection(plan.newCollection);
+      expect(newCollection).not.toBeNull();
+      expect(newCollection!.fields).toHaveLength(2);
+    });
+  });
+});

package/src/__tests__/plan-new-resources.test.ts

@@ -0,0 +1,258 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { setupClient, cleanupTypesense } from "./setup.js";
+import { getTypesenseVersion } from "./helpers.js";
+import { buildPlan } from "../plan/index.js";
+import { applyPlan } from "../apply/index.js";
+import { loadState } from "../state/index.js";
+import { getStopwordSet } from "../resources/stopword.js";
+import { getPreset } from "../resources/preset.js";
+import { getCurationSet } from "../resources/curationset.js";
+import { upsertStopwordSet } from "../resources/stopword.js";
+import { upsertPreset } from "../resources/preset.js";
+import type { TypesenseConfig } from "../types/index.js";
+
+describe("plan/apply with new resource types", () => {
+  let version: number;
+
+  beforeEach(async () => {
+    setupClient();
+    await cleanupTypesense();
+    version = await getTypesenseVersion();
+  });
+
+  afterEach(async () => {
+    await cleanupTypesense();
+  });
+
+  describe("stopwords", () => {
+    test("plans creation for new stopword set", async () => {
+      const config: TypesenseConfig = {
+        stopwords: [
+          { id: "english", stopwords: ["the", "a", "an"] },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "stopword");
+      expect(change).toBeDefined();
+      expect(change!.action).toBe("create");
+    });
+
+    test("plans no-change for existing stopword set", async () => {
+      await upsertStopwordSet({ id: "english", stopwords: ["the", "a", "an"] });
+      const config: TypesenseConfig = {
+        stopwords: [
+          { id: "english", stopwords: ["the", "a", "an"] },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "stopword");
+      expect(change!.action).toBe("no-change");
+    });
+
+    test("plans update for modified stopword set", async () => {
+      await upsertStopwordSet({ id: "english", stopwords: ["the", "a"] });
+      const config: TypesenseConfig = {
+        stopwords: [
+          { id: "english", stopwords: ["the", "a", "an", "is"] },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "stopword");
+      expect(change!.action).toBe("update");
+    });
+
+    test("creates stopword set via apply", async () => {
+      const config: TypesenseConfig = {
+        stopwords: [
+          { id: "english", stopwords: ["the", "a", "an"] },
+        ],
+      };
+      const plan = await buildPlan(config);
+      await applyPlan(plan, config);
+
+      const result = await getStopwordSet("english");
+      expect(result).not.toBeNull();
+      expect(result!.stopwords).toContain("the");
+    });
+
+    test("deletes stopword set via apply", async () => {
+      // Create and apply
+      const config1: TypesenseConfig = {
+        stopwords: [{ id: "english", stopwords: ["the"] }],
+      };
+      const plan1 = await buildPlan(config1);
+      await applyPlan(plan1, config1);
+
+      // Delete
+      const config2: TypesenseConfig = {};
+      const plan2 = await buildPlan(config2);
+      await applyPlan(plan2, config2);
+
+      const result = await getStopwordSet("english");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("presets", () => {
+    test("plans creation for new preset", async () => {
+      const config: TypesenseConfig = {
+        presets: [
+          { name: "listing", value: { q: "*", sort_by: "price:asc" } },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "preset");
+      expect(change).toBeDefined();
+      expect(change!.action).toBe("create");
+    });
+
+    test("creates preset via apply", async () => {
+      const config: TypesenseConfig = {
+        presets: [
+          { name: "listing", value: { q: "*" } },
+        ],
+      };
+      const plan = await buildPlan(config);
+      await applyPlan(plan, config);
+
+      const result = await getPreset("listing");
+      expect(result).not.toBeNull();
+    });
+
+    test("plans no-change for existing preset", async () => {
+      await upsertPreset({ name: "listing", value: { q: "*" } });
+      const config: TypesenseConfig = {
+        presets: [
+          { name: "listing", value: { q: "*" } },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "preset");
+      expect(change!.action).toBe("no-change");
+    });
+
+    test("deletes preset via apply", async () => {
+      const config1: TypesenseConfig = {
+        presets: [{ name: "listing", value: { q: "*" } }],
+      };
+      const plan1 = await buildPlan(config1);
+      await applyPlan(plan1, config1);
+
+      const config2: TypesenseConfig = {};
+      const plan2 = await buildPlan(config2);
+      await applyPlan(plan2, config2);
+
+      const result = await getPreset("listing");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("curation sets (v30+)", () => {
+    test("plans creation for new curation set", async () => {
+      if (version < 30) return;
+      const config: TypesenseConfig = {
+        curationSets: [
+          {
+            name: "products",
+            items: [
+              {
+                id: "featured",
+                rule: { query: "featured", match: "exact" },
+                includes: [{ id: "product-1", position: 1 }],
+              },
+            ],
+          },
+        ],
+      };
+      const plan = await buildPlan(config);
+      const change = plan.changes.find((c) => c.identifier.type === "curationSet");
+      expect(change).toBeDefined();
+      expect(change!.action).toBe("create");
+    });
+
+    test("creates curation set via apply", async () => {
+      if (version < 30) return;
+      const config: TypesenseConfig = {
+        curationSets: [
+          {
+            name: "products",
+            items: [
+              {
+                id: "boost-shoes",
+                rule: { query: "shoes", match: "contains" },
+                filter_by: "category:=footwear",
+              },
+            ],
+          },
+        ],
+      };
+      const plan = await buildPlan(config);
+      await applyPlan(plan, config);
+
+      const result = await getCurationSet("products");
+      expect(result).not.toBeNull();
+      expect(result!.items).toHaveLength(1);
+    });
+
+    test("deletes curation set via apply", async () => {
+      if (version < 30) return;
+      const config1: TypesenseConfig = {
+        curationSets: [
+          {
+            name: "products",
+            items: [
+              {
+                id: "rule1",
+                rule: { query: "x", match: "exact" },
+                filter_by: "a:=1",
+              },
+            ],
+          },
+        ],
+      };
+      const plan1 = await buildPlan(config1);
+      await applyPlan(plan1, config1);
+
+      const config2: TypesenseConfig = {};
+      const plan2 = await buildPlan(config2);
+      await applyPlan(plan2, config2);
+
+      const result = await getCurationSet("products");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("full config with all resource types", () => {
+    test("applies config with stopwords, presets, and collections", async () => {
+      const config: TypesenseConfig = {
+        collections: [
+          { name: "products", fields: [{ name: "title", type: "string" }] },
+        ],
+        aliases: [{ name: "products_live", collection: "products" }],
+        stopwords: [
+          { id: "english", stopwords: ["the", "a"] },
+        ],
+        presets: [
+          { name: "default_search", value: { q: "*" } },
+        ],
+        apiKeys: [
+          { description: "Search key", actions: ["documents:search"], collections: ["*"] },
+        ],
+      };
+
+      const plan = await buildPlan(config);
+      const result = await applyPlan(plan, config);
+
+      expect(result.success).toBe(true);
+
+      // Verify state
+      const state = await loadState();
+      const types = state.resources.map((r) => r.identifier.type);
+      expect(types).toContain("collection");
+      expect(types).toContain("alias");
+      expect(types).toContain("stopword");
+      expect(types).toContain("preset");
+      expect(types).toContain("apiKey");
+    });
+  });
+});