@intentius/chant 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -36,6 +36,7 @@
     ".": "./src/index.ts",
     "./cli": "./src/cli/index.ts",
     "./cli/*": "./src/cli/*.ts",
+    "./op": "./src/op/index.ts",
     "./*": "./src/*.ts"
   },
   "dependencies": {

package/src/index.ts

@@ -61,3 +61,7 @@ export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./state/index";
 export * from "./spell/index";
+// Op builders — use explicit exports to avoid collision with the core `build` function
+export { Op, phase, activity, gate, kubectlApply, helmInstall, waitForStack,
+         gitlabPipeline, stateSnapshot, shell, teardown, OpResource } from "./op/index";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, RetryPolicy } from "./op/index";

package/src/op/builders.ts

@@ -0,0 +1,96 @@
+import { OpResource } from "./resource";
+import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+
+// ── Core builders ─────────────────────────────────────────────────────────────
+
+/**
+ * Declare a named, phased Temporal workflow.
+ *
+ * @example
+ * ```ts
+ * export default Op({
+ *   name: "alb-deploy",
+ *   overview: "Build and deploy the ALB multi-service stack",
+ *   phases: [
+ *     phase("Build", [build("examples/gitlab-aws-alb-infra")], { parallel: true }),
+ *     phase("Deploy", [kubectlApply("dist/alb-infra.yaml")]),
+ *   ],
+ * });
+ * ```
+ */
+export function Op(config: OpConfig): InstanceType<typeof OpResource> {
+  return new OpResource(config as unknown as Record<string, unknown>);
+}
+
+/** Define a named execution phase containing one or more steps. */
+export function phase(
+  name: string,
+  steps: StepDefinition[],
+  opts?: { parallel?: boolean },
+): PhaseDefinition {
+  return { name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
+}
+
+/** Reference a pre-built or custom activity by function name. */
+export function activity(
+  fn: string,
+  args?: Record<string, unknown>,
+  profile?: ActivityStep["profile"],
+): ActivityStep {
+  return {
+    kind: "activity",
+    fn,
+    ...(args && Object.keys(args).length > 0 ? { args } : {}),
+    ...(profile ? { profile } : {}),
+  };
+}
+
+/** Insert a human gate — the workflow pauses until the named signal is received. */
+export function gate(
+  signalName: string,
+  opts?: { timeout?: string; description?: string },
+): GateStep {
+  return {
+    kind: "gate",
+    signalName,
+    ...(opts?.timeout ? { timeout: opts.timeout } : {}),
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
+}
+
+// ── Pre-built activity shortcuts ──────────────────────────────────────────────
+
+/** Run `npm run build` (or `chant build`) in the given project directory. */
+export const build = (path: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("chantBuild", { path, ...opts });
+
+/** Run `kubectl apply -f <manifest>`. Uses `longInfra` profile. */
+export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("kubectlApply", { manifest, ...opts }, "longInfra");
+
+/** Run `helm upgrade --install`. Uses `longInfra` profile. */
+export const helmInstall = (
+  name: string,
+  chart: string,
+  opts?: { values?: string; namespace?: string; [k: string]: unknown },
+): ActivityStep => activity("helmInstall", { name, chart, ...opts }, "longInfra");
+
+/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Uses `k8sWait` profile. */
+export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("waitForStack", { name, ...opts }, "k8sWait");
+
+/** Trigger and wait for a GitLab CI pipeline to complete. Uses `longInfra` profile. */
+export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("gitlabPipeline", { name, ...opts }, "longInfra");
+
+/** Take a chant state snapshot for the given environment. */
+export const stateSnapshot = (env: string): ActivityStep =>
+  activity("stateSnapshot", { env });
+
+/** Run an arbitrary shell command. */
+export const shell = (cmd: string, opts?: { env?: Record<string, string> }): ActivityStep =>
+  activity("shellCmd", { cmd, ...opts });
+
+/** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
+export const teardown = (path: string): ActivityStep =>
+  activity("chantTeardown", { path }, "longInfra");

package/src/op/index.ts

@@ -0,0 +1,4 @@
+export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
+         gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+export { OpResource } from "./resource";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, RetryPolicy } from "./types";

package/src/op/op.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Core Op builder tests.
+ */
+
+import { describe, expect, it } from "vitest";
+import { Op, phase, activity, gate, build, kubectlApply, helmInstall,
+         waitForStack, gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+
+// ── Op() ──────────────────────────────────────────────────────────────────────
+
+describe("Op()", () => {
+  function opProps(op: Declarable): Record<string, unknown> {
+    return (op as unknown as { props: Record<string, unknown> }).props;
+  }
+
+  it("returns a Declarable with correct lexicon and entityType", () => {
+    const op = Op({ name: "my-op", overview: "Test op", phases: [] });
+    expect(op[DECLARABLE_MARKER]).toBe(true);
+    expect(op.lexicon).toBe("temporal");
+    expect(op.entityType).toBe("Temporal::Op");
+    expect(op.kind).toBe("resource");
+  });
+
+  it("stores name and overview in props", () => {
+    const op = Op({ name: "deploy-op", overview: "Deploy infra", phases: [] });
+    const props = opProps(op);
+    expect(props.name).toBe("deploy-op");
+    expect(props.overview).toBe("Deploy infra");
+  });
+
+  it("stores phases in props", () => {
+    const p = phase("Build", [build("path/to/project")]);
+    const op = Op({ name: "op", overview: "o", phases: [p] });
+    const props = opProps(op);
+    expect(Array.isArray(props.phases)).toBe(true);
+    expect((props.phases as unknown[]).length).toBe(1);
+  });
+
+  it("stores optional depends in props", () => {
+    const op = Op({ name: "second-op", overview: "o", phases: [], depends: ["first-op"] });
+    const props = opProps(op);
+    expect(props.depends).toEqual(["first-op"]);
+  });
+
+  it("stores optional onFailure in props", () => {
+    const compensation = phase("Rollback", [shell("echo rollback")]);
+    const op = Op({ name: "op", overview: "o", phases: [], onFailure: [compensation] });
+    const props = opProps(op);
+    expect(Array.isArray(props.onFailure)).toBe(true);
+  });
+
+  it("stores optional taskQueue in props", () => {
+    const op = Op({ name: "op", overview: "o", phases: [], taskQueue: "custom-queue" });
+    const props = opProps(op);
+    expect(props.taskQueue).toBe("custom-queue");
+  });
+});
+
+// ── phase() ───────────────────────────────────────────────────────────────────
+
+describe("phase()", () => {
+  it("returns correct shape with name and steps", () => {
+    const p = phase("Deploy", [build("./")]);
+    expect(p.name).toBe("Deploy");
+    expect(p.steps).toHaveLength(1);
+  });
+
+  it("sets parallel: true when passed as option", () => {
+    const p = phase("Build", [build("a"), build("b")], { parallel: true });
+    expect(p.parallel).toBe(true);
+  });
+
+  it("omits parallel key when not set", () => {
+    const p = phase("Build", [build("a")]);
+    expect("parallel" in p).toBe(false);
+  });
+});
+
+// ── activity() ────────────────────────────────────────────────────────────────
+
+describe("activity()", () => {
+  it("returns ActivityStep with kind 'activity'", () => {
+    const a = activity("myFn");
+    expect(a.kind).toBe("activity");
+    expect(a.fn).toBe("myFn");
+  });
+
+  it("includes args when provided", () => {
+    const a = activity("myFn", { key: "val" });
+    expect(a.args).toEqual({ key: "val" });
+  });
+
+  it("omits args key when no args provided", () => {
+    const a = activity("myFn");
+    expect("args" in a).toBe(false);
+  });
+
+  it("includes profile when provided", () => {
+    const a = activity("myFn", {}, "longInfra");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("omits profile key when not provided", () => {
+    const a = activity("myFn");
+    expect("profile" in a).toBe(false);
+  });
+});
+
+// ── gate() ────────────────────────────────────────────────────────────────────
+
+describe("gate()", () => {
+  it("returns GateStep with kind 'gate' and signalName", () => {
+    const g = gate("dns-delegation");
+    expect(g.kind).toBe("gate");
+    expect(g.signalName).toBe("dns-delegation");
+  });
+
+  it("includes timeout when provided", () => {
+    const g = gate("approval", { timeout: "24h" });
+    expect(g.timeout).toBe("24h");
+  });
+
+  it("includes description when provided", () => {
+    const g = gate("approval", { description: "Awaiting DNS delegation" });
+    expect(g.description).toBe("Awaiting DNS delegation");
+  });
+
+  it("omits timeout and description when not provided", () => {
+    const g = gate("sig");
+    expect("timeout" in g).toBe(false);
+    expect("description" in g).toBe(false);
+  });
+});
+
+// ── Pre-built shortcuts ───────────────────────────────────────────────────────
+
+describe("pre-built shortcuts", () => {
+  it("build() produces chantBuild activity with path arg", () => {
+    const a = build("./my-project");
+    expect(a.kind).toBe("activity");
+    expect(a.fn).toBe("chantBuild");
+    expect(a.args?.path).toBe("./my-project");
+  });
+
+  it("build() uses default fastIdempotent profile (no profile key)", () => {
+    const a = build("./p");
+    expect("profile" in a).toBe(false);
+  });
+
+  it("kubectlApply() produces kubectlApply activity with longInfra profile", () => {
+    const a = kubectlApply("dist/infra.yaml");
+    expect(a.fn).toBe("kubectlApply");
+    expect(a.args?.manifest).toBe("dist/infra.yaml");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("helmInstall() produces helmInstall activity with name and chart", () => {
+    const a = helmInstall("my-release", "charts/app");
+    expect(a.fn).toBe("helmInstall");
+    expect(a.args?.name).toBe("my-release");
+    expect(a.args?.chart).toBe("charts/app");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("waitForStack() produces waitForStack activity with k8sWait profile", () => {
+    const a = waitForStack("my-stack");
+    expect(a.fn).toBe("waitForStack");
+    expect(a.args?.name).toBe("my-stack");
+    expect(a.profile).toBe("k8sWait");
+  });
+
+  it("gitlabPipeline() produces gitlabPipeline activity with longInfra profile", () => {
+    const a = gitlabPipeline("group/project");
+    expect(a.fn).toBe("gitlabPipeline");
+    expect(a.args?.name).toBe("group/project");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("stateSnapshot() produces stateSnapshot activity with env arg", () => {
+    const a = stateSnapshot("prod");
+    expect(a.fn).toBe("stateSnapshot");
+    expect(a.args?.env).toBe("prod");
+    expect("profile" in a).toBe(false);
+  });
+
+  it("shell() produces shellCmd activity with cmd arg", () => {
+    const a = shell("echo hello");
+    expect(a.fn).toBe("shellCmd");
+    expect(a.args?.cmd).toBe("echo hello");
+  });
+
+  it("teardown() produces chantTeardown activity with longInfra profile", () => {
+    const a = teardown("./project");
+    expect(a.fn).toBe("chantTeardown");
+    expect(a.args?.path).toBe("./project");
+    expect(a.profile).toBe("longInfra");
+  });
+});

package/src/op/resource.ts

@@ -0,0 +1,8 @@
+import { createResource } from "../runtime";
+
+/**
+ * The Declarable resource backing an Op definition.
+ * entityType: "Temporal::Op", lexicon: "temporal"
+ * Discovered automatically alongside infra files — no pipeline changes needed.
+ */
+export const OpResource = createResource("Temporal::Op", "temporal", {});

package/src/op/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Op type definitions — the data model for a named, phased Temporal workflow.
+ *
+ * These types are intentionally free of Temporal SDK imports so they can live
+ * in core without pulling in @temporalio/* as a dependency.
+ */
+
+export interface OpConfig {
+  /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
+  name: string;
+  /** Human-readable description shown in `chant run list` and deployment reports. */
+  overview: string;
+  /** Temporal task queue. Defaults to `name`. */
+  taskQueue?: string;
+  /** Temporal namespace. Defaults to chant.config.ts defaultProfile's namespace. */
+  namespace?: string;
+  /** Ordered list of execution phases. */
+  phases: PhaseDefinition[];
+  /** Other Op names that must be complete before this Op can run. */
+  depends?: string[];
+  /** Compensation phases executed on terminal failure (run in reverse order). */
+  onFailure?: PhaseDefinition[];
+  /** Search attributes to upsert at workflow start. */
+  searchAttributes?: Record<string, string>;
+}
+
+export interface PhaseDefinition {
+  /** Display name shown in progress output and Temporal UI. */
+  name: string;
+  /** Ordered steps within the phase. */
+  steps: StepDefinition[];
+  /** Run all steps concurrently via Promise.all. Default: false. */
+  parallel?: boolean;
+}
+
+export type StepDefinition = ActivityStep | GateStep;
+
+export interface ActivityStep {
+  kind: "activity";
+  /** Name of the exported activity function in the pre-built activity library. */
+  fn: string;
+  /** Arguments passed to the activity function. */
+  args?: Record<string, unknown>;
+  /**
+   * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
+   * Default: "fastIdempotent"
+   */
+  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+}
+
+export interface GateStep {
+  kind: "gate";
+  /** Signal name. The generated workflow waits for this signal before continuing. */
+  signalName: string;
+  /** Temporal duration string. Default: "48h". */
+  timeout?: string;
+  /** Human-readable description of the action required to unblock this gate. */
+  description?: string;
+}
+
+export interface RetryPolicy {
+  initialInterval?: string;
+  backoffCoefficient?: number;
+  maximumAttempts?: number;
+  maximumInterval?: string;
+}