@intentius/chant-lexicon-temporal 0.1.5

package/src/plugin.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Temporal plugin tests.
+ */
+
+import { describe, expect, it } from "vitest";
+import { temporalPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("temporal plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(temporalPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(temporalPlugin.name).toBe("temporal");
+  });
+
+  it("has a serializer with name 'temporal'", () => {
+    expect(temporalPlugin.serializer).toBeDefined();
+    expect(temporalPlugin.serializer.name).toBe("temporal");
+  });
+
+  it("lintRules() returns 2 rules (TMP001, TMP002)", () => {
+    const rules = temporalPlugin.lintRules?.();
+    expect(Array.isArray(rules)).toBe(true);
+    expect(rules?.length).toBe(2);
+    const ids = rules?.map((r) => r.id).sort();
+    expect(ids).toEqual(["TMP001", "TMP002"]);
+  });
+
+  it("mcpTools() returns 1 diff tool", () => {
+    const tools = temporalPlugin.mcpTools?.();
+    expect(Array.isArray(tools)).toBe(true);
+    expect(tools?.length).toBe(1);
+    expect(tools?.[0].name).toBe("diff");
+  });
+
+  it("mcpResources() returns at least 2 resources including resource-catalog", () => {
+    const resources = temporalPlugin.mcpResources?.();
+    expect(Array.isArray(resources)).toBe(true);
+    expect((resources?.length ?? 0)).toBeGreaterThanOrEqual(2);
+    const uris = resources?.map((r) => r.uri);
+    expect(uris).toContain("resource-catalog");
+  });
+
+  it("skills() returns 2 skill entries", () => {
+    const skills = temporalPlugin.skills?.();
+    expect(Array.isArray(skills)).toBe(true);
+    expect(skills?.length).toBe(2);
+  });
+
+  it("skills include chant-temporal and chant-temporal-ops", () => {
+    const skills = temporalPlugin.skills?.() ?? [];
+    const names = skills.map((s) => s.name);
+    expect(names).toContain("chant-temporal");
+    expect(names).toContain("chant-temporal-ops");
+  });
+
+  describe("initTemplates", () => {
+    it("default template returns src with temporal.ts", () => {
+      const result = temporalPlugin.initTemplates?.();
+      expect(result).toBeDefined();
+      expect(result?.src).toBeDefined();
+      expect(result?.src?.["temporal.ts"]).toBeDefined();
+    });
+
+    it("default template includes TemporalServer and TemporalNamespace imports", () => {
+      const result = temporalPlugin.initTemplates?.();
+      const src = result?.src?.["temporal.ts"] as string;
+      expect(src).toContain("TemporalServer");
+      expect(src).toContain("TemporalNamespace");
+    });
+
+    it("'cloud' template includes TemporalNamespace and SearchAttribute (no server)", () => {
+      const result = temporalPlugin.initTemplates?.("cloud");
+      const src = result?.src?.["temporal.ts"] as string;
+      expect(src).toContain("TemporalNamespace");
+      expect(src).toContain("SearchAttribute");
+      expect(src).not.toContain("TemporalServer");
+    });
+
+    it("'full' template includes all 4 resource types", () => {
+      const result = temporalPlugin.initTemplates?.("full");
+      const src = result?.src?.["temporal.ts"] as string;
+      expect(src).toContain("TemporalServer");
+      expect(src).toContain("TemporalNamespace");
+      expect(src).toContain("SearchAttribute");
+      expect(src).toContain("TemporalSchedule");
+    });
+
+    it("'full' template uses mode: \"full\"", () => {
+      const result = temporalPlugin.initTemplates?.("full");
+      const src = result?.src?.["temporal.ts"] as string;
+      expect(src).toContain('"full"');
+    });
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,286 @@
+/**
+ * Temporal lexicon plugin — implements the LexiconPlugin lifecycle.
+ *
+ * All resources are hand-written; there is no remote spec to generate from.
+ * The generate step is a no-op. The package step builds dist/manifest.json
+ * and copies skill markdown files.
+ */
+
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import { discoverLintRules, discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { temporalSerializer } from "./serializer";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+const rulesDir = join(srcDir, "lint/rules");
+const postSynthDir = join(srcDir, "lint/post-synth");
+
+export const temporalPlugin: LexiconPlugin = {
+  name: "temporal",
+  serializer: temporalSerializer,
+
+  // ── Required lifecycle methods ──────────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { dirname: pathDirname } = await import("path");
+    const { fileURLToPath: toPath } = await import("url");
+    const pkgDir = pathDirname(pathDirname(toPath(import.meta.url)));
+    const result = await generate(options);
+    writeGeneratedFiles(result, pkgDir);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const result = await validate(options);
+    if (result.failed > 0) {
+      throw new Error(`Temporal lexicon validation failed:\n${result.errors.join("\n")}`);
+    }
+  },
+
+  async coverage(options?: { verbose?: boolean }): Promise<void> {
+    const { analyze, printCoverageResult } = await import("./coverage");
+    const result = analyze();
+    printCoverageResult(result, options?.verbose ?? true);
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join: pathJoin, dirname: pathDirname } = await import("path");
+    const { fileURLToPath: toPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = pathDirname(pathDirname(toPath(import.meta.url)));
+    writeBundleSpec(spec, pathJoin(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ─────────────────────────────────────────────
+
+  lintRules() {
+    return discoverLintRules(rulesDir, import.meta.url);
+  },
+
+  postSynthChecks() {
+    return discoverPostSynthChecks(postSynthDir, import.meta.url);
+  },
+
+  skills() {
+    return createSkillsLoader(import.meta.url, [
+      {
+        file: "chant-temporal.md",
+        name: "chant-temporal",
+        description: "Temporal server setup, namespace provisioning, and schedule registration",
+        triggers: [
+          { type: "file-pattern", value: "**/*.ts" },
+          { type: "context", value: "temporal" },
+          { type: "context", value: "workflow" },
+        ],
+        parameters: [],
+        examples: [],
+      },
+      {
+        file: "chant-temporal-ops.md",
+        name: "chant-temporal-ops",
+        description: "Signal workflows, diagnose stuck activities, reset checkpoints",
+        triggers: [
+          { type: "context", value: "temporal workflow" },
+          { type: "context", value: "stuck activity" },
+          { type: "context", value: "chant run" },
+        ],
+        parameters: [],
+        examples: [],
+      },
+    ])();
+  },
+
+  mcpTools() {
+    return [
+      createDiffTool(
+        temporalSerializer,
+        "Compare current Temporal build output (docker-compose.yml, temporal-setup.sh, schedules/) against previous version",
+      ),
+    ];
+  },
+
+  mcpResources() {
+    return [
+      createCatalogResource(
+        import.meta.url,
+        "Temporal Resource Types",
+        "All supported Temporal resource types: TemporalServer, TemporalNamespace, SearchAttribute, TemporalSchedule",
+        "lexicon-temporal.json",
+      ),
+      {
+        uri: "examples/dev-server",
+        name: "Local Dev Server Example",
+        description: "Minimal Temporal dev server with namespace for local development",
+        mimeType: "text/typescript",
+        async handler(): Promise<string> {
+          return [
+            'import { TemporalServer, TemporalNamespace } from "@intentius/chant-lexicon-temporal";',
+            "",
+            "// Local dev server — runs via `temporal server start-dev`",
+            'export const server = new TemporalServer({ mode: "dev" });',
+            "",
+            "export const ns = new TemporalNamespace({",
+            '  name: "default",',
+            '  retention: "7d",',
+            "});",
+          ].join("\n");
+        },
+      },
+      {
+        uri: "examples/cloud-setup",
+        name: "Temporal Cloud Setup Example",
+        description: "Namespace and search attributes for Temporal Cloud (no local server)",
+        mimeType: "text/typescript",
+        async handler(): Promise<string> {
+          return [
+            'import { TemporalNamespace, SearchAttribute, TemporalSchedule } from "@intentius/chant-lexicon-temporal";',
+            "",
+            "export const ns = new TemporalNamespace({",
+            '  name: "prod",',
+            '  retention: "30d",',
+            '  description: "Production workflow namespace",',
+            "});",
+            "",
+            "export const projectAttr = new SearchAttribute({",
+            '  name: "Project",',
+            '  type: "Keyword",',
+            '  namespace: "prod",',
+            "});",
+            "",
+            "export const dailyReport = new TemporalSchedule({",
+            '  scheduleId: "daily-report",',
+            "  spec: {",
+            '    cronExpressions: ["0 8 * * *"],',
+            "  },",
+            "  action: {",
+            '    workflowType: "reportWorkflow",',
+            '    taskQueue: "reports",',
+            "  },",
+            "  policies: {",
+            '    overlap: "Skip",',
+            "  },",
+            "});",
+          ].join("\n");
+        },
+      },
+    ];
+  },
+
+  // ── initTemplates ────────────────────────────────────────────────────
+  // 3 templates: "local" (default), "cloud", "full"
+
+  initTemplates(template?: string) {
+    if (template === "cloud") {
+      return {
+        src: {
+          "temporal.ts": [
+            'import { TemporalNamespace, SearchAttribute, TemporalSchedule } from "@intentius/chant-lexicon-temporal";',
+            "",
+            "// Namespace — provision once after connecting to Temporal Cloud",
+            "export const ns = new TemporalNamespace({",
+            '  name: "my-namespace",',
+            '  retention: "30d",',
+            '  description: "Production deployment namespace",',
+            "});",
+            "",
+            "// Search attributes — register once per namespace",
+            "export const projectAttr = new SearchAttribute({",
+            '  name: "Project",',
+            '  type: "Keyword",',
+            '  namespace: "my-namespace",',
+            "});",
+            "",
+            "// Schedule — daily maintenance run",
+            "export const maintenanceSchedule = new TemporalSchedule({",
+            '  scheduleId: "daily-maintenance",',
+            "  spec: {",
+            '    cronExpressions: ["0 2 * * *"],',
+            "  },",
+            "  action: {",
+            '    workflowType: "maintenanceWorkflow",',
+            '    taskQueue: "maintenance-queue",',
+            "  },",
+            "  policies: {",
+            '    overlap: "Skip",',
+            "  },",
+            "});",
+          ].join("\n"),
+        },
+      };
+    }
+
+    if (template === "full") {
+      return {
+        src: {
+          "temporal.ts": [
+            'import {',
+            '  TemporalServer,',
+            '  TemporalNamespace,',
+            '  SearchAttribute,',
+            '  TemporalSchedule,',
+            '} from "@intentius/chant-lexicon-temporal";',
+            "",
+            "// Full server stack (auto-setup + postgres + UI)",
+            "export const server = new TemporalServer({",
+            '  version: "1.26.2",',
+            '  mode: "full",',
+            "  port: 7233,",
+            "  uiPort: 8080,",
+            "});",
+            "",
+            "export const ns = new TemporalNamespace({",
+            '  name: "default",',
+            '  retention: "7d",',
+            "});",
+            "",
+            "export const projectAttr = new SearchAttribute({",
+            '  name: "Project",',
+            '  type: "Keyword",',
+            "});",
+            "",
+            "export const weeklyBackup = new TemporalSchedule({",
+            '  scheduleId: "weekly-backup",',
+            "  spec: {",
+            '    cronExpressions: ["0 3 * * SUN"],',
+            "  },",
+            "  action: {",
+            '    workflowType: "backupWorkflow",',
+            '    taskQueue: "backup-queue",',
+            "  },",
+            "});",
+          ].join("\n"),
+        },
+      };
+    }
+
+    // default = "local"
+    return {
+      src: {
+        "temporal.ts": [
+          'import { TemporalServer, TemporalNamespace } from "@intentius/chant-lexicon-temporal";',
+          "",
+          "// Local dev server — runs via `temporal server start-dev`",
+          "export const server = new TemporalServer({ mode: \"dev\" });",
+          "",
+          "export const ns = new TemporalNamespace({",
+          '  name: "default",',
+          '  retention: "7d",',
+          "});",
+        ].join("\n"),
+      },
+    };
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/resources.ts

@@ -0,0 +1,121 @@
+/**
+ * Temporal lexicon resources — hand-written Declarable constructors.
+ *
+ * These model the Temporal.io infrastructure concerns that chant serializes:
+ * server deployment configs, namespace provisioning scripts, search attribute
+ * registration, and SDK schedule creation code.
+ *
+ * All 4 resources are hand-written (no upstream spec to generate from).
+ *
+ * Reference: https://docs.temporal.io
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+
+// ── TemporalServer ────────────────────────────────────────────────────
+// Serializes to docker-compose.yml (primary) and temporal-helm-values.yaml.
+// mode: "dev" emits a single-container dev server via `temporal server start-dev`.
+// mode: "full" emits auto-setup + postgresql + UI services.
+
+export const TemporalServer = createResource("Temporal::Server", "temporal", {});
+
+export interface TemporalServerProps {
+  /** Temporal server version tag. Default: "1.26.2" */
+  version?: string;
+  /** Deployment mode. Default: "dev" */
+  mode?: "dev" | "full";
+  /** gRPC port. Default: 7233 */
+  port?: number;
+  /** Web UI port. Default: 8080 */
+  uiPort?: number;
+  /** PostgreSQL image tag for "full" mode. Default: "16-alpine" */
+  postgresVersion?: string;
+  /** Helm chart version hint — written as a comment in helm-values.yaml */
+  helmChartVersion?: string;
+}
+
+// ── TemporalNamespace ─────────────────────────────────────────────────
+// Serializes to temporal-setup.sh as `temporal operator namespace create` commands.
+
+export const TemporalNamespace = createResource("Temporal::Namespace", "temporal", {});
+
+export interface TemporalNamespaceProps {
+  /** Namespace name */
+  name: string;
+  /** Workflow execution retention period. Default: "7d" */
+  retention?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Whether this is a global (multi-cluster) namespace */
+  isGlobalNamespace?: boolean;
+}
+
+// ── SearchAttribute ───────────────────────────────────────────────────
+// Serializes to temporal-setup.sh as `temporal operator search-attribute create` commands.
+
+export const SearchAttribute = createResource("Temporal::SearchAttribute", "temporal", {});
+
+export interface SearchAttributeProps {
+  /** Attribute name (PascalCase recommended by Temporal) */
+  name: string;
+  /** Attribute value type */
+  type: "Text" | "Keyword" | "Int" | "Double" | "Bool" | "Datetime" | "KeywordList";
+  /** Namespace to register in. If omitted, --namespace flag is not emitted */
+  namespace?: string;
+}
+
+// ── TemporalSchedule ──────────────────────────────────────────────────
+// Serializes to schedules/<scheduleId>.ts — runnable TypeScript that creates
+// the schedule via the Temporal SDK client.
+
+export const TemporalSchedule = createResource("Temporal::Schedule", "temporal", {});
+
+export interface TemporalScheduleProps {
+  /** Unique schedule identifier */
+  scheduleId: string;
+  /** Schedule timing specification */
+  spec: {
+    /** Cron expressions (e.g. "0 9 * * MON-FRI") */
+    cronExpressions?: string[];
+    /** Fixed intervals (e.g. { every: "1d" }) */
+    intervals?: Array<{ every: string; offset?: string }>;
+  };
+  /** What workflow to start */
+  action: {
+    workflowType: string;
+    taskQueue: string;
+    args?: unknown[];
+    workflowExecutionTimeout?: string;
+    workflowRunTimeout?: string;
+    memo?: Record<string, unknown>;
+    searchAttributes?: Record<string, unknown>;
+    /**
+     * Retry policy for the triggered workflow execution.
+     * When set, the generated schedule script includes `workflowStartOptions.retry`.
+     */
+    workflowRetryPolicy?: {
+      /** Initial retry interval (e.g. "10s"). Default: Temporal server default (~1s). */
+      initialInterval?: string;
+      /** Backoff multiplier for each subsequent retry (e.g. 2). */
+      backoffCoefficient?: number;
+      /** 0 = unlimited retries; defaults to Temporal server default (unlimited). */
+      maximumAttempts?: number;
+      /** Cap on retry intervals (e.g. "5m"). */
+      maximumInterval?: string;
+      /** Error types that should NOT trigger a retry. */
+      nonRetryableErrorTypes?: string[];
+    };
+  };
+  policies?: {
+    overlap?: "Skip" | "BufferOne" | "BufferAll" | "CancelOther" | "TerminateOther" | "AllowAll";
+    catchupWindow?: string;
+    pauseOnFailure?: boolean;
+  };
+  /** Initial paused state */
+  state?: {
+    paused?: boolean;
+    note?: string;
+  };
+  /** Namespace to create schedule in. Default: process.env.TEMPORAL_NAMESPACE ?? "default" */
+  namespace?: string;
+}