@intentius/chant 0.13.1 → 0.15.1

package/src/op/activity-registry.ts

@@ -16,32 +16,51 @@
  */
 export type ActivityFn = (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
 
+/** Add every exported function from an activity module to `into`, keyed by name. */
+function collectActivities(mod: Record<string, unknown>, into: Map<string, ActivityFn>): void {
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === "function") {
+      into.set(name, value as ActivityFn);
+    }
+  }
+}
+
 /**
- * Dynamically import the Temporal lexicon's activity library and return a map
- * of every exported function keyed by its export name (`shellCmd`, `chantBuild`,
- * `kubectlApply`, …).
+ * Build the activity map for local execution by importing activity libraries and
+ * keying every exported function by name (`shellCmd`, `kubectlApply`, `gcpApply`, …).
+ *
+ * The base activities always live in the temporal lexicon. Cloud-specific
+ * appliers live in their own lexicon (aws → `flociUp`/`flociDown`, gcp →
+ * `gcpApply`, azure → `azGroupEnsure`/`azGroupDelete`), so `lexicons` — the
+ * project's configured lexicon list — is consulted to pull those in. A lexicon
+ * that ships no `op/activities` module is skipped.
  *
- * Throws a friendly error if the lexicon is not installed — local execution
- * needs the activity implementations even though it never starts a worker.
+ * Throws only if the temporal base library is missing — local execution needs
+ * the activity implementations even though it never starts a worker.
  */
-export async function loadActivities(): Promise<Map<string, ActivityFn>> {
-  let mod: Record<string, unknown>;
+export async function loadActivities(lexicons: string[] = []): Promise<Map<string, ActivityFn>> {
+  const activities = new Map<string, ActivityFn>();
+
   try {
     // Variable specifier so tsc does not statically resolve the optional dep.
     const spec = "@intentius/chant-lexicon-temporal/op/activities";
-    mod = (await import(spec)) as Record<string, unknown>;
+    collectActivities((await import(spec)) as Record<string, unknown>, activities);
   } catch {
     throw new Error(
       "no activities registered — install `@intentius/chant-lexicon-temporal`",
     );
   }
 
-  const activities = new Map<string, ActivityFn>();
-  for (const [name, value] of Object.entries(mod)) {
-    if (typeof value === "function") {
-      activities.set(name, value as ActivityFn);
+  for (const name of lexicons) {
+    if (name === "temporal") continue;
+    try {
+      const spec = `@intentius/chant-lexicon-${name}/op/activities`;
+      collectActivities((await import(spec)) as Record<string, unknown>, activities);
+    } catch {
+      // Lexicon absent or contributes no activities — fine.
     }
   }
+
   return activities;
 }
 

package/src/op/activity-runtime.ts

@@ -0,0 +1,73 @@
+/**
+ * Activity runtime helpers shared by every Op activity implementation, wherever
+ * it lives — the base activities in the temporal lexicon and the cloud-specific
+ * appliers relocated into the aws/gcp/azure lexicons. Hosting them in core keeps
+ * a cloud lexicon from having to depend on the temporal lexicon just to
+ * heartbeat or sleep.
+ */
+
+interface ActivityContext {
+  current(): { heartbeat(details?: unknown): void };
+}
+
+// undefined = not yet attempted; null = unavailable; object = resolved Context.
+let cachedContext: ActivityContext | null | undefined;
+let loading: Promise<void> | undefined;
+
+function ensureContext(): void {
+  if (cachedContext !== undefined || loading) return;
+  // Variable specifier so bundlers/tsc do not statically require the optional dep.
+  const spec = "@temporalio/activity";
+  loading = import(spec)
+    .then((mod: unknown) => {
+      cachedContext = (mod as { Context?: ActivityContext }).Context ?? null;
+    })
+    .catch(() => {
+      cachedContext = null;
+    });
+}
+
+/**
+ * Emit an activity heartbeat if running under a Temporal worker; otherwise no-op.
+ *
+ * The first call kicks off a one-time lazy load of `@temporalio/activity` and
+ * returns immediately; once resolved, subsequent calls heartbeat. Heartbeats
+ * are periodic (every ~15s, well inside the 60s heartbeat timeout), so the
+ * single missed first tick is harmless. Under chant's local executor (no
+ * Temporal SDK present) it no-ops, and the module imports cleanly without the SDK.
+ */
+export function safeHeartbeat(details?: unknown): void {
+  if (cachedContext === undefined) {
+    ensureContext();
+    return;
+  }
+  if (cachedContext === null) return;
+  try {
+    cachedContext.current().heartbeat(details);
+  } catch {
+    // Not inside an activity execution context — nothing to do.
+  }
+}
+
+/**
+ * Sleep for `ms`, rejecting early if `signal` aborts. Polling activities use
+ * this between attempts so a local-executor timeout or Ctrl-C interrupts the
+ * wait instead of running it to completion.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/op/builders.ts

@@ -131,6 +131,105 @@ export const shell = (
 export const teardown = (path: string): ActivityStep =>
   activity("chantTeardown", { path }, "longInfra");
 
+/**
+ * Create a local k3d cluster (vanilla Kubernetes in Docker) and merge its
+ * kubeconfig / switch context — k3d's defaults. Idempotent: skips creation if a
+ * cluster of the same name already exists. Defaults to the `longInfra` profile
+ * (creating a cluster may pull the k3s image); override via `opts.profile`.
+ *
+ * `opts` accepts `servers`, `agents`, `image`, `ports` (e.g.
+ * `["8080:80@loadbalancer"]`), `registryCreate`, `configFile`, and `timeout`.
+ */
+export const k3dUp = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3dUp", { name, ...args }, profile ?? "longInfra");
+};
+
+/** Delete a local k3d cluster. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const k3dDown = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3dDown", { name, ...args }, profile ?? "fastIdempotent");
+};
+
+/**
+ * Boot a local Floci AWS emulator in Docker and point subsequent steps at it —
+ * sets `AWS_ENDPOINT_URL` + test creds in the process env so a following
+ * `cloudformation` apply targets the emulator (local executor). Idempotent:
+ * reuses a running container of the same name. Defaults to the `longInfra`
+ * profile (the image may pull); override via `opts.profile`.
+ *
+ * `opts` accepts `name`, `port`, `image`, `dockerSocket` (mount the docker
+ * socket for the ECR backing registry), `region`, `readyService`, `timeoutMs`.
+ */
+export const flociUp = (opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("flociUp", args, profile ?? "longInfra");
+};
+
+/** Stop and remove the local Floci emulator container. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const flociDown = (opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("flociDown", args, profile ?? "fastIdempotent");
+};
+
+/**
+ * Ensure an Azure resource group exists before an ARM apply. `az deployment
+ * group create` (the `arm` apply target) fails without its group, so place this
+ * before the deploy phase. Idempotent. Defaults to the `fastIdempotent` profile
+ * (override via `opts.profile`). `opts` accepts `location` (default `eastus`).
+ */
+export const azGroupEnsure = (resourceGroup: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("azGroupEnsure", { resourceGroup, ...args }, profile ?? "fastIdempotent");
+};
+
+/** Delete an Azure resource group and its contents (non-blocking). Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const azGroupDelete = (resourceGroup: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("azGroupDelete", { resourceGroup, ...args }, profile ?? "fastIdempotent");
+};
+
+/**
+ * Apply chant's built ARM template directly to the ARM resource API — the Azure
+ * twin of {@link gcpApply}. Targets floci-az's resource CRUD (which `az deployment`
+ * can't, floci-az having no deployments provider) or real Azure by endpoint
+ * override; ensures the resource group first. Defaults to the `longInfra` profile.
+ *
+ * `opts` requires `resourceGroup`; accepts `location`, `endpoint` (floci-az
+ * `http://localhost:4577`), `subscriptionId`, and `prune` (owned-only prune of
+ * chant-managed resources no longer in the template — destructive, off by default).
+ */
+export const azApply = (templatePath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("azApply", { templatePath, ...args }, profile ?? "longInfra");
+};
+
+/** Delete the Azure (ARM) resources in a built template — the inverse of {@link azApply}. Defaults to the `longInfra` profile (override via `opts.profile`). `opts` requires `resourceGroup`. */
+export const azDelete = (templatePath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("azDelete", { templatePath, ...args }, profile ?? "longInfra");
+};
+
+/**
+ * Apply chant's built GCP (CNRM) resources directly to the GCS REST API,
+ * targeting a local floci-gcp emulator or real GCP by endpoint override — the
+ * native GCP applier (#706 starter #711), currently handling `StorageBucket`.
+ * Defaults to the `longInfra` profile (override via `opts.profile`).
+ *
+ * `opts` accepts `endpoint` (default `STORAGE_EMULATOR_HOST` env / real GCS) and
+ * `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM project-id annotation).
+ */
+export const gcpApply = (manifestPath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("gcpApply", { manifestPath, ...args }, profile ?? "longInfra");
+};
+
+/** Delete the GCP (CNRM) resources in a built manifest — the inverse of {@link gcpApply}. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const gcpDelete = (manifestPath: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("gcpDelete", { manifestPath, ...args }, profile ?? "longInfra");
+};
+
 /**
  * Gate an apply on organizational policy: build the project and run its
  * `lint.policies` over the resolved resources, blocking the workflow on any

package/src/op/index.ts

@@ -1,6 +1,8 @@
 export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
-         gitlabPipeline, lifecycleSnapshot, shell, teardown, policyGate } from "./builders";
+         gitlabPipeline, lifecycleSnapshot, shell, teardown, k3dUp, k3dDown, flociUp, flociDown,
+         azGroupEnsure, azGroupDelete, azApply, azDelete, gcpApply, gcpDelete, policyGate } from "./builders";
 export { OpResource } from "./resource";
+export { safeHeartbeat, sleep } from "./activity-runtime";
 export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";

package/src/ownership.test.ts

@@ -1,42 +1,40 @@
 import { describe, expect, test } from "vitest";
 import {
   ownershipEntries,
-  ownershipKeys,
   hasOwnershipMarker,
   readOwnership,
   classifyOwnership,
   tagArrayToMap,
+  LABEL_OWNERSHIP_KEYS,
   OWNERSHIP_MANAGED_BY_VALUE,
+  type ChannelKeys,
 } from "./ownership";
 import { resolveOwnershipMarker } from "./config";
 
+// A stand-in for a lexicon-provided convention (e.g. AWS's colon keys), to
+// prove the core helpers are generic over any `ChannelKeys` — the per-provider
+// conventions themselves live in their lexicons (aws/azure), not here.
+const COLON_KEYS: ChannelKeys = { managedBy: "chant:managed-by", stack: "chant:stack", env: "chant:env" };
+
 describe("ownershipEntries (#119)", () => {
-  test("label channel carries managed-by + stack + env", () => {
-    const e = ownershipEntries("label", { stack: "billing", env: "prod" });
+  test("the default label keys carry managed-by + stack + env", () => {
+    const e = ownershipEntries(LABEL_OWNERSHIP_KEYS, { stack: "billing", env: "prod" });
     expect(e["app.kubernetes.io/managed-by"]).toBe("chant");
     expect(e["chant.intentius.io/stack"]).toBe("billing");
     expect(e["chant.intentius.io/env"]).toBe("prod");
   });
 
-  test("aws-tag channel uses colon keys", () => {
-    const e = ownershipEntries("aws-tag", { stack: "billing" });
+  test("stamps whatever key names the provided ChannelKeys names, env omitted when unset", () => {
+    const e = ownershipEntries(COLON_KEYS, { stack: "billing" });
     expect(e["chant:managed-by"]).toBe("chant");
     expect(e["chant:stack"]).toBe("billing");
     expect(e["chant:env"]).toBeUndefined(); // env omitted when not set
   });
 
-  test("azure-tag channel uses hyphen keys (no slash, which Azure forbids)", () => {
-    const e = ownershipEntries("azure-tag", { stack: "billing", env: "stg" });
-    expect(e["chant-managed-by"]).toBe("chant");
-    expect(e["chant-stack"]).toBe("billing");
-    expect(e["chant-env"]).toBe("stg");
-    expect(Object.keys(e).some((k) => k.includes("/"))).toBe(false);
-  });
-
   test("carries stack identity, not just managed=true", () => {
-    const a = ownershipEntries("label", { stack: "stack-a" });
-    const b = ownershipEntries("label", { stack: "stack-b" });
-    expect(a[ownershipKeys("label").stack]).not.toBe(b[ownershipKeys("label").stack]);
+    const a = ownershipEntries(LABEL_OWNERSHIP_KEYS, { stack: "stack-a" });
+    const b = ownershipEntries(LABEL_OWNERSHIP_KEYS, { stack: "stack-b" });
+    expect(a[LABEL_OWNERSHIP_KEYS.stack]).not.toBe(b[LABEL_OWNERSHIP_KEYS.stack]);
   });
 });
 
@@ -47,29 +45,29 @@ describe("hasOwnershipMarker / readOwnership", () => {
       "chant:stack": "billing",
       "team": "payments", // foreign co-stamp
     };
-    expect(hasOwnershipMarker(tags, "aws-tag")).toBe(true);
+    expect(hasOwnershipMarker(tags, COLON_KEYS)).toBe(true);
   });
 
   test("absent marker → not owned", () => {
-    expect(hasOwnershipMarker({ team: "payments" }, "aws-tag")).toBe(false);
-    expect(hasOwnershipMarker(undefined, "label")).toBe(false);
+    expect(hasOwnershipMarker({ team: "payments" }, COLON_KEYS)).toBe(false);
+    expect(hasOwnershipMarker(undefined, LABEL_OWNERSHIP_KEYS)).toBe(false);
   });
 
   test("readOwnership recovers stack/env from a marked resource", () => {
-    const labels = ownershipEntries("label", { stack: "billing", env: "prod" });
-    expect(readOwnership(labels, "label")).toEqual({ stack: "billing", env: "prod" });
+    const labels = ownershipEntries(LABEL_OWNERSHIP_KEYS, { stack: "billing", env: "prod" });
+    expect(readOwnership(labels, LABEL_OWNERSHIP_KEYS)).toEqual({ stack: "billing", env: "prod" });
   });
 
   test("readOwnership returns undefined when unmarked", () => {
-    expect(readOwnership({ foo: "bar" }, "label")).toBeUndefined();
+    expect(readOwnership({ foo: "bar" }, LABEL_OWNERSHIP_KEYS)).toBeUndefined();
   });
 });
 
 describe("classifyOwnership / tagArrayToMap (#120)", () => {
   test("marker present → owned, absent → foreign", () => {
-    expect(classifyOwnership({ "chant:managed-by": "chant" }, "aws-tag")).toBe("owned");
-    expect(classifyOwnership({ team: "x" }, "aws-tag")).toBe("foreign");
-    expect(classifyOwnership(undefined, "label")).toBe("foreign");
+    expect(classifyOwnership({ "chant:managed-by": "chant" }, COLON_KEYS)).toBe("owned");
+    expect(classifyOwnership({ team: "x" }, COLON_KEYS)).toBe("foreign");
+    expect(classifyOwnership(undefined, LABEL_OWNERSHIP_KEYS)).toBe("foreign");
   });
 
   test("tagArrayToMap converts CloudFormation {Key,Value} tags", () => {
@@ -78,7 +76,7 @@ describe("classifyOwnership / tagArrayToMap (#120)", () => {
       { Key: "chant:stack", Value: "billing" },
     ]);
     expect(map["chant:managed-by"]).toBe("chant");
-    expect(classifyOwnership(map, "aws-tag")).toBe("owned");
+    expect(classifyOwnership(map, COLON_KEYS)).toBe("owned");
   });
 
   test("tagArrayToMap tolerates undefined / malformed entries", () => {

package/src/ownership.ts

@@ -28,50 +28,39 @@ export interface OwnershipMarker {
 }
 
 /**
- * The native metadata channel a target stamps into. Tag-key syntax differs:
- * Kubernetes/GCP labels allow a `prefix/name` form; AWS tag keys allow `:`;
- * Azure tag keys forbid `/`, so they use a hyphenated form.
+ * The marker key names a target stamps into — the managed-by/stack/env tag or
+ * label keys. Tag-key syntax differs per provider (Kubernetes/GCP labels allow
+ * a `prefix/name` form; AWS tag keys allow `:`; Azure tag keys forbid `/`), so
+ * each cloud lexicon provides its own `ChannelKeys` and passes it to these
+ * helpers. Core owns the generic stamp/detect logic and the shared label
+ * convention (`LABEL_OWNERSHIP_KEYS`), not a per-provider key registry.
  */
-export type OwnershipChannel = "label" | "aws-tag" | "azure-tag";
-
-interface ChannelKeys {
+export interface ChannelKeys {
   readonly managedBy: string;
   readonly stack: string;
   readonly env: string;
 }
 
-const CHANNEL_KEYS: Record<OwnershipChannel, ChannelKeys> = {
-  label: {
-    managedBy: "app.kubernetes.io/managed-by",
-    stack: "chant.intentius.io/stack",
-    env: "chant.intentius.io/env",
-  },
-  "aws-tag": {
-    managedBy: "chant:managed-by",
-    stack: "chant:stack",
-    env: "chant:env",
-  },
-  "azure-tag": {
-    managedBy: "chant-managed-by",
-    stack: "chant-stack",
-    env: "chant-env",
-  },
+/**
+ * The label-based ownership convention (`app.kubernetes.io/managed-by` +
+ * `chant.intentius.io/{stack,env}`) — the default, shared by every label-based
+ * lexicon (k8s, gcp, helm, and the Temporal apply activity's `kubectl --prune`
+ * selector). AWS and Azure tag keys are defined in their own lexicons.
+ */
+export const LABEL_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "app.kubernetes.io/managed-by",
+  stack: "chant.intentius.io/stack",
+  env: "chant.intentius.io/env",
 };
 
-/** The marker key names used in a given channel. */
-export function ownershipKeys(channel: OwnershipChannel): ChannelKeys {
-  return CHANNEL_KEYS[channel];
-}
-
 /**
- * The key/value entries to stamp for a channel: the managed-by marker, the
- * stack identity, and the env identity when present.
+ * The key/value entries to stamp: the managed-by marker, the stack identity,
+ * and the env identity when present.
  */
 export function ownershipEntries(
-  channel: OwnershipChannel,
+  keys: ChannelKeys,
   marker: OwnershipMarker,
 ): Record<string, string> {
-  const keys = CHANNEL_KEYS[channel];
   const entries: Record<string, string> = {
     [keys.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
     [keys.stack]: marker.stack,
@@ -86,10 +75,10 @@ export function ownershipEntries(
  */
 export function hasOwnershipMarker(
   tagsOrLabels: Record<string, unknown> | undefined,
-  channel: OwnershipChannel,
+  keys: ChannelKeys,
 ): boolean {
   if (!tagsOrLabels) return false;
-  return tagsOrLabels[CHANNEL_KEYS[channel].managedBy] === OWNERSHIP_MANAGED_BY_VALUE;
+  return tagsOrLabels[keys.managedBy] === OWNERSHIP_MANAGED_BY_VALUE;
 }
 
 /**
@@ -104,9 +93,9 @@ export function hasOwnershipMarker(
  */
 export function classifyOwnership(
   tagsOrLabels: Record<string, unknown> | undefined,
-  channel: OwnershipChannel,
+  keys: ChannelKeys,
 ): "owned" | "foreign" {
-  return hasOwnershipMarker(tagsOrLabels, channel) ? "owned" : "foreign";
+  return hasOwnershipMarker(tagsOrLabels, keys) ? "owned" : "foreign";
 }
 
 /**
@@ -129,10 +118,9 @@ export function tagArrayToMap(
  */
 export function readOwnership(
   tagsOrLabels: Record<string, unknown> | undefined,
-  channel: OwnershipChannel,
+  keys: ChannelKeys,
 ): OwnershipMarker | undefined {
-  if (!hasOwnershipMarker(tagsOrLabels, channel)) return undefined;
-  const keys = CHANNEL_KEYS[channel];
+  if (!hasOwnershipMarker(tagsOrLabels, keys)) return undefined;
   const stack = tagsOrLabels![keys.stack];
   const env = tagsOrLabels![keys.env];
   return {