@intentius/chant-lexicon-temporal 0.1.5

package/src/skills/chant-temporal-ops.md

@@ -0,0 +1,184 @@
+---
+skill: chant-temporal-ops
+description: Signal workflows, diagnose stuck activities, reset checkpoints, and cancel runs via the Temporal CLI and chant run
+user-invocable: true
+---
+
+# Temporal Operations Playbook
+
+## Signal a gate (unblock a paused workflow)
+
+Workflows that use `setHandler` on a signal pause at gate activities waiting for a named signal. The `chant run signal` command (available in issue #8) forwards signals to the running workflow.
+
+```bash
+# Via chant CLI (requires chant run — issue #8)
+chant run signal <op-name> dnsConfigured
+
+# Directly via temporal CLI
+temporal workflow signal \
+  --workflow-id <workflow-id> \
+  --name dnsConfigured \
+  --namespace <namespace>
+```
+
+List pending signals by querying the workflow:
+
+```bash
+temporal workflow query \
+  --workflow-id <workflow-id> \
+  --type currentPhase \
+  --namespace <namespace>
+```
+
+## Check run status
+
+```bash
+# Summary view
+temporal workflow describe --workflow-id <id> --namespace <ns>
+
+# Full event history
+temporal workflow show --workflow-id <id> --namespace <ns>
+
+# Filter by search attribute (requires registered custom attributes)
+temporal workflow list \
+  --namespace <ns> \
+  --query 'GcpProject = "my-project"'
+```
+
+## Diagnose a stuck activity
+
+Activities can be stuck for three distinct reasons:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Activity never started | `scheduleToStartTimeout` exceeded — no available workers | Start the worker: `chant run <op>` |
+| Activity started but no heartbeats | `heartbeatTimeout` exceeded — worker crashed mid-activity | Bounce the worker; Temporal auto-retries |
+| Activity running but slow | Normal — long-running activities with heartbeats | Wait, or check heartbeat details |
+
+### View activity timeout details
+
+```bash
+temporal workflow show --workflow-id <id> --namespace <ns> | grep -A5 "ActivityTaskScheduled"
+```
+
+### Check worker connectivity
+
+```bash
+# See which task queues have pollers
+temporal task-queue describe --task-queue <queue> --namespace <ns>
+```
+
+A task queue with `pollerCount: 0` means no workers are running.
+
+## Reset a workflow to a previous checkpoint
+
+Use `workflow reset` to replay a workflow from a specific event, skipping failed activities:
+
+```bash
+# Reset to just before the most recent failure
+temporal workflow reset \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --event-id <N> \
+  --reason "Retrying after infra fix"
+```
+
+Find the event ID to reset to:
+
+```bash
+# List events — find the last successful ActivityTaskCompleted before the failure
+temporal workflow show --workflow-id <id> --namespace <ns> | grep -n "ActivityTask"
+```
+
+Reset to the beginning of a named phase (requires workflow to record phase transitions as signals or markers):
+
+```bash
+temporal workflow reset \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --reapply-type None \
+  --type LastWorkflowTask
+```
+
+## Cancel a stuck or unwanted run
+
+```bash
+# Graceful cancel — workflow receives CancellationError and can clean up
+temporal workflow cancel \
+  --workflow-id <id> \
+  --namespace <ns>
+
+# Forceful terminate — immediate stop, no cleanup
+temporal workflow terminate \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --reason "Terminated by operator"
+```
+
+## Pause and resume a schedule
+
+```bash
+# Pause
+temporal schedule pause \
+  --schedule-id <id> \
+  --namespace <ns> \
+  --note "Paused for maintenance"
+
+# Resume
+temporal schedule unpause \
+  --schedule-id <id> \
+  --namespace <ns>
+
+# Trigger immediately (ignores spec)
+temporal schedule trigger \
+  --schedule-id <id> \
+  --namespace <ns>
+```
+
+## Inspect workflow history for debugging
+
+```bash
+# Show all events in JSON (machine-readable)
+temporal workflow show \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --output json
+
+# Filter to activity failures only
+temporal workflow show \
+  --workflow-id <id> \
+  --namespace <ns> \
+  --output json | jq '.[] | select(.eventType == "ActivityTaskFailed")'
+```
+
+## Common failure patterns
+
+### "no workers polling" after `chant run`
+
+The worker started but cannot connect. Check:
+1. `TEMPORAL_ADDRESS` matches the server address
+2. `TEMPORAL_NAMESPACE` matches the namespace the workflow was started in
+3. TLS and API key config match (`tls: true` + `apiKey` for Temporal Cloud)
+
+### Activity retrying indefinitely
+
+Default retry policy has `maximumAttempts: 0` (unlimited). If an activity is retrying unexpectedly:
+
+```bash
+# Check the current attempt count and last failure
+temporal workflow show --workflow-id <id> --namespace <ns> | grep "attempt\|failure"
+```
+
+Add `maximumAttempts` to the activity's retry policy in the workflow code, or cancel the run.
+
+### "workflow execution already started" on re-run
+
+`chant run` uses deterministic workflow IDs (e.g. `crdb-deploy-{project}`). If a previous run is still open:
+
+```bash
+# Check if it's still running
+temporal workflow describe --workflow-id <id> --namespace <ns> | grep "status"
+
+# If stuck, terminate it first
+temporal workflow terminate --workflow-id <id> --namespace <ns> --reason "Restarting"
+```

package/src/skills/chant-temporal.md

@@ -0,0 +1,201 @@
+---
+skill: chant-temporal
+description: Build and manage Temporal server deployment, namespace provisioning, and schedule registration from a chant project
+user-invocable: true
+---
+
+# Temporal Operational Playbook
+
+## How chant and Temporal relate
+
+chant is a **synthesis compiler** — it compiles TypeScript resource declarations into deployment artifacts. `chant build` does not start Temporal or register anything; synthesis is pure and deterministic. Your job as an agent is to bridge synthesis and deployment:
+
+- Use **chant** for: build, lint, diff (local config comparison)
+- Use **docker compose / kubectl / temporal CLI** for: starting the server, applying configs, and all runtime operations
+
+The source of truth for Temporal configuration is the TypeScript in `src/`. The generated artifacts in `dist/` are intermediate outputs.
+
+## Resources and their outputs
+
+| Resource | Emits |
+|---|---|
+| `TemporalServer` | `docker-compose.yml` (primary) + `temporal-helm-values.yaml` |
+| `TemporalNamespace` | `temporal-setup.sh` (namespace create commands) |
+| `SearchAttribute` | `temporal-setup.sh` (search-attribute create commands) |
+| `TemporalSchedule` | `schedules/<id>.ts` (SDK schedule creation script) |
+
+## Build and validate
+
+### Build the project
+
+```bash
+chant build src/ --output dist/
+```
+
+Options:
+- `--watch` — rebuild on source changes
+- `--format json` — not applicable (Temporal outputs are YAML/shell/TypeScript)
+
+### Lint the source
+
+```bash
+chant lint src/
+```
+
+## Start the Temporal server
+
+### Local dev (generated docker-compose.yml)
+
+```bash
+# Start the dev server
+docker compose up -d
+
+# Verify it's running
+temporal operator cluster health
+```
+
+The dev server runs as a single container (`temporal server start-dev`). The Web UI is available at `http://localhost:8080`.
+
+### Temporal Cloud
+
+No server to start. Configure your worker profile in `chant.config.ts`:
+
+```ts
+import type { TemporalChantConfig } from "@intentius/chant-lexicon-temporal";
+
+export default {
+  lexicons: ["temporal"],
+  temporal: {
+    profiles: {
+      cloud: {
+        address: "myns.a2dd6.tmprl.cloud:7233",
+        namespace: "myns.a2dd6",
+        taskQueue: "my-deploy",
+        tls: true,
+        apiKey: { env: "TEMPORAL_API_KEY" },
+      },
+    },
+    defaultProfile: "cloud",
+  } satisfies TemporalChantConfig,
+};
+```
+
+## Provision namespaces and search attributes
+
+After the server is ready, run the generated setup script:
+
+```bash
+bash dist/temporal-setup.sh
+```
+
+This creates namespaces and registers search attributes using the `temporal` CLI. The `TEMPORAL_ADDRESS` env var overrides the default `localhost:7233`:
+
+```bash
+TEMPORAL_ADDRESS=myns.a2dd6.tmprl.cloud:7233 bash dist/temporal-setup.sh
+```
+
+Verify:
+
+```bash
+temporal operator namespace describe --namespace default
+temporal operator search-attribute list --namespace default
+```
+
+## Deploy with Helm
+
+```bash
+helm repo add temporal https://go.temporal.io/server/helm-charts
+helm repo update
+helm install temporal temporal/temporal -f dist/temporal-helm-values.yaml
+```
+
+Wait for all pods:
+
+```bash
+kubectl get pods -l app.kubernetes.io/name=temporal -w
+```
+
+## Register schedules
+
+Each `TemporalSchedule` resource generates a standalone TypeScript runner:
+
+```bash
+# Set connection env vars
+export TEMPORAL_ADDRESS=localhost:7233
+export TEMPORAL_NAMESPACE=default
+
+# Run the generated schedule creation script
+npx tsx dist/schedules/daily-backup.ts
+```
+
+Verify the schedule was created:
+
+```bash
+temporal schedule list --namespace default
+temporal schedule describe --schedule-id daily-backup --namespace default
+```
+
+## Key resource types
+
+| Resource | Purpose |
+|---|---|
+| `TemporalServer` | Server deployment config (dev vs full mode) |
+| `TemporalNamespace` | Namespace with retention policy |
+| `SearchAttribute` | Custom workflow search field |
+| `TemporalSchedule` | Recurring workflow trigger |
+
+## Common patterns
+
+### Minimal local dev stack
+
+```ts
+import { TemporalServer, TemporalNamespace } from "@intentius/chant-lexicon-temporal";
+
+export const server = new TemporalServer({ mode: "dev" });
+export const ns = new TemporalNamespace({ name: "default", retention: "7d" });
+```
+
+### Production namespace with search attributes
+
+```ts
+import { TemporalNamespace, SearchAttribute } from "@intentius/chant-lexicon-temporal";
+
+export const ns = new TemporalNamespace({
+  name: "prod-deploy",
+  retention: "30d",
+  description: "Production deployment workflows",
+});
+
+export const gcpProject = new SearchAttribute({
+  name: "GcpProject",
+  type: "Text",
+  namespace: "prod-deploy",
+});
+
+export const environment = new SearchAttribute({
+  name: "Environment",
+  type: "Keyword",
+  namespace: "prod-deploy",
+});
+```
+
+### Recurring backup schedule
+
+```ts
+import { TemporalSchedule } from "@intentius/chant-lexicon-temporal";
+
+export const backupSchedule = new TemporalSchedule({
+  scheduleId: "daily-backup",
+  spec: {
+    cronExpressions: ["0 3 * * *"],
+  },
+  action: {
+    workflowType: "backupWorkflow",
+    taskQueue: "backup-queue",
+  },
+  policies: {
+    overlap: "Skip",
+    pauseOnFailure: true,
+  },
+});
+```

package/src/validate-cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate";
+
+const result = await validate({ verbose: true });
+if (result.failed > 0) {
+  process.exit(1);
+}

package/src/validate.test.ts

@@ -0,0 +1,9 @@
+import { test, expect } from "vitest";
+import { validate } from "./validate";
+
+test("validate passes — all 4 resources have correct entityType strings", async () => {
+  const result = await validate({ verbose: false });
+  expect(result.valid ?? result.failed === 0).toBe(true);
+  expect(result.failed).toBe(0);
+  expect(result.errors).toHaveLength(0);
+});

package/src/validate.ts

@@ -0,0 +1,92 @@
+/**
+ * Validate the Temporal lexicon dist/ artifacts.
+ *
+ * Since all resources are hand-written, validation checks that
+ * the packaging step produced correct dist/ artifacts: manifest.json,
+ * meta.json (with the 4 expected resource types), types/index.d.ts,
+ * and integrity.json.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+export interface ValidateResult {
+  passed: number;
+  failed: number;
+  errors: string[];
+}
+
+const EXPECTED_RESOURCE_TYPES = [
+  "TemporalServer",
+  "TemporalNamespace",
+  "SearchAttribute",
+  "TemporalSchedule",
+] as const;
+
+export async function validate(opts?: { verbose?: boolean; basePath?: string }): Promise<ValidateResult> {
+  const pkgDir = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const distDir = join(pkgDir, "dist");
+  const errors: string[] = [];
+
+  // manifest.json
+  const manifestPath = join(distDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    errors.push("dist/manifest.json not found — run npm run bundle");
+  } else {
+    try {
+      const m = JSON.parse(readFileSync(manifestPath, "utf-8")) as Record<string, unknown>;
+      if (m["name"] !== "temporal") errors.push(`manifest.json: expected name "temporal", got ${JSON.stringify(m["name"])}`);
+      if (m["namespace"] !== "Temporal") errors.push(`manifest.json: expected namespace "Temporal", got ${JSON.stringify(m["namespace"])}`);
+    } catch (err) {
+      errors.push(`manifest.json: parse error — ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // meta.json (lexicon catalog)
+  const metaPath = join(distDir, "meta.json");
+  if (!existsSync(metaPath)) {
+    errors.push("dist/meta.json not found — run npm run bundle");
+  } else {
+    try {
+      const catalog = JSON.parse(readFileSync(metaPath, "utf-8")) as Record<string, unknown>;
+      for (const name of EXPECTED_RESOURCE_TYPES) {
+        if (!(name in catalog)) {
+          errors.push(`meta.json: missing resource "${name}"`);
+        }
+      }
+    } catch (err) {
+      errors.push(`meta.json: parse error — ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // types/index.d.ts
+  const dtsPath = join(distDir, "types", "index.d.ts");
+  if (!existsSync(dtsPath)) {
+    errors.push("dist/types/index.d.ts not found — run npm run bundle");
+  }
+
+  // integrity.json
+  const integrityPath = join(distDir, "integrity.json");
+  if (!existsSync(integrityPath)) {
+    errors.push("dist/integrity.json not found — run npm run bundle");
+  }
+
+  const result: ValidateResult = {
+    passed: 4 - errors.length < 0 ? 0 : 4 - errors.length,
+    failed: errors.length,
+    errors,
+  };
+
+  if (opts?.verbose) {
+    if (errors.length === 0) {
+      console.error(`Validation passed: all dist/ artifacts present and valid`);
+    } else {
+      for (const err of errors) {
+        console.error(`  ✗ ${err}`);
+      }
+    }
+  }
+
+  return result;
+}