@intentius/chant 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/commands/describe.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { describeCommand } from "./describe";
+
+// The #203 layered-config example: one WebApp instantiated for dev/staging/prod
+// from layered (spread) config. describe v1 projects the effective, resolved
+// config for one named component over it.
+const exampleSrc = resolve(
+  fileURLToPath(import.meta.url),
+  "../../../../../../lexicons/k8s/examples/layered-config/src",
+);
+
+function opts(component: string, format: "text" | "json" = "json") {
+  return { component, path: exampleSrc, format };
+}
+
+describe("describeCommand (resolved view, v1)", () => {
+  test("describes a composite instance by its export name (grouped resources)", async () => {
+    const r = await describeCommand(opts("prodApp"));
+    expect(r.success).toBe(true);
+    expect(r.composite).toBe(true);
+    const names = r.resources.map((x) => x.name).sort();
+    expect(names).toEqual([
+      "prodAppDeployment",
+      "prodAppIngress",
+      "prodAppPdb",
+      "prodAppService",
+    ]);
+  });
+
+  test("shows the effective, fully-resolved props (post-merge)", async () => {
+    const r = await describeCommand(opts("prodApp"));
+    const dep = r.resources.find((x) => x.entityType.endsWith("Deployment"))!;
+    const props = dep.props as { spec: { replicas: number }; metadata: { labels: Record<string, string> } };
+    // prod overrode replicas; base labels merged with prod-only ones.
+    expect(props.spec.replicas).toBe(6);
+    expect(props.metadata.labels["app.kubernetes.io/part-of"]).toBe("acme-web"); // base layer
+    expect(props.metadata.labels["acme.io/env"]).toBe("prod"); // env layer
+    expect(props.metadata.labels["acme.io/tier"]).toBe("critical"); // prod-only
+  });
+
+  test("environments resolve to different effective configs", async () => {
+    const dev = await describeCommand(opts("devApp"));
+    const devDep = dev.resources.find((x) => x.entityType.endsWith("Deployment"))!;
+    const devProps = devDep.props as { spec: { replicas: number }; metadata: { labels: Record<string, string> } };
+    expect(devProps.spec.replicas).toBe(2); // base default, not overridden in dev
+    expect(devProps.metadata.labels["acme.io/env"]).toBe("dev");
+    expect(devProps.metadata.labels["acme.io/tier"]).toBeUndefined(); // prod-only key absent
+    // dev declares no ingress; prod does.
+    expect(dev.resources.some((x) => x.entityType.endsWith("Ingress"))).toBe(false);
+  });
+
+  test("describes a single declarable by exact name (not a composite)", async () => {
+    const r = await describeCommand(opts("devAppService"));
+    expect(r.success).toBe(true);
+    expect(r.composite).toBe(false);
+    expect(r.resources).toHaveLength(1);
+    expect(r.resources[0].entityType).toBe("K8s::Core::Service");
+  });
+
+  test("unknown component fails with the known-component list", async () => {
+    const r = await describeCommand(opts("doesNotExist"));
+    expect(r.success).toBe(false);
+    expect(r.output).toContain("No component");
+    expect(r.output).toContain("prodAppDeployment");
+  });
+
+  test("text format renders the component header and props", async () => {
+    const r = await describeCommand(opts("prodApp", "text"));
+    expect(r.output).toContain("prodApp");
+    expect(r.output).toContain("K8s::Apps::Deployment");
+    expect(r.output).toContain("web-prod");
+  });
+});

package/src/cli/commands/describe.ts

@@ -0,0 +1,141 @@
+import { resolve } from "path";
+import { discover } from "../../discovery/index";
+import type { Declarable } from "../../declarable";
+import { formatSuccess, formatBold } from "../format";
+
+/**
+ * `chant describe <component>` — project the effective, fully-resolved
+ * configuration for one named component, offline (source only; no live calls).
+ *
+ * `chant list` shows inventory and `chant graph` shows edges; neither shows the
+ * resolved property bag for a single thing. `describe` does: for a layered
+ * config (see the layered-config guide) it answers "what is the effective config
+ * for this component, after every spread/override?" without merging the layers
+ * by hand.
+ */
+export interface DescribeOptions {
+  /** The component to describe — a named export (declarable or composite instance). */
+  component: string;
+  /** Path to the infrastructure directory. */
+  path: string;
+  /** Output format. */
+  format: "text" | "json";
+}
+
+/** One resolved resource produced by the component. */
+export interface DescribedResource {
+  name: string;
+  lexicon: string;
+  entityType: string;
+  kind: string;
+  /** The resolved (post-merge, post-composite-expansion) property bag. */
+  props: unknown;
+}
+
+export interface DescribeResult {
+  success: boolean;
+  component: string;
+  /** True when the component is a composite instance (≥1 produced resource by prefix). */
+  composite: boolean;
+  resources: DescribedResource[];
+  output: string;
+}
+
+/** Read a discovered entity's resolved props (same accessor the build pipeline uses). */
+function readProps(entity: Declarable): unknown {
+  return "props" in entity ? (entity as { props: unknown }).props : undefined;
+}
+
+/**
+ * Find the entities a component name refers to. A composite instance is
+ * flattened at discovery: `WebApp(x)` exported as `foo` becomes `fooDeployment`,
+ * `fooService`, … — so an exact-name miss falls back to grouping entities whose
+ * name is the export prefix followed by a capitalized result key.
+ */
+function matchComponent(
+  entities: Map<string, Declarable>,
+  component: string,
+): { matched: Array<[string, Declarable]>; composite: boolean } {
+  const exact = entities.get(component);
+  if (exact) return { matched: [[component, exact]], composite: false };
+
+  const grouped = [...entities].filter(
+    ([n]) =>
+      n.length > component.length &&
+      n.startsWith(component) &&
+      n.charAt(component.length) === n.charAt(component.length).toUpperCase() &&
+      n.charAt(component.length) !== n.charAt(component.length).toLowerCase(),
+  );
+  grouped.sort((a, b) => a[0].localeCompare(b[0]));
+  return { matched: grouped, composite: grouped.length > 0 };
+}
+
+export async function describeCommand(options: DescribeOptions): Promise<DescribeResult> {
+  const infraPath = resolve(options.path);
+  const result = await discover(infraPath);
+
+  if (result.errors.length > 0) {
+    return {
+      success: false,
+      component: options.component,
+      composite: false,
+      resources: [],
+      output: result.errors.map((e) => e.message).join("\n"),
+    };
+  }
+
+  const { matched, composite } = matchComponent(result.entities, options.component);
+
+  if (matched.length === 0) {
+    const known = [...result.entities.keys()].sort().join(", ");
+    return {
+      success: false,
+      component: options.component,
+      composite: false,
+      resources: [],
+      output: `No component "${options.component}" found.\nKnown components: ${known || "(none)"}`,
+    };
+  }
+
+  const resources: DescribedResource[] = matched.map(([name, decl]) => ({
+    name,
+    lexicon: decl.lexicon ?? "",
+    entityType: decl.entityType ?? "",
+    kind: decl.kind ?? "resource",
+    props: readProps(decl),
+  }));
+
+  const output =
+    options.format === "json"
+      ? JSON.stringify({ component: options.component, composite, resources }, null, 2)
+      : formatText(options.component, composite, resources);
+
+  return { success: true, component: options.component, composite, resources, output };
+}
+
+/** Human-readable effective-config view. */
+function formatText(component: string, composite: boolean, resources: DescribedResource[]): string {
+  const lines: string[] = [];
+  const header = composite
+    ? `${formatBold(component)} — composite instance, ${resources.length} resource(s)`
+    : `${formatBold(component)}`;
+  lines.push(header);
+  for (const r of resources) {
+    lines.push("");
+    lines.push(`  ${formatBold(r.name)}  (${r.entityType})`);
+    const propsJson = JSON.stringify(r.props ?? {}, null, 2)
+      .split("\n")
+      .map((l) => `    ${l}`)
+      .join("\n");
+    lines.push(propsJson);
+  }
+  return lines.join("\n");
+}
+
+/** Print a describe result to the console. */
+export function printDescribeResult(result: DescribeResult): void {
+  if (result.output) console.log(result.output);
+  if (result.success) {
+    console.error(formatSuccess(`Described ${formatBold(result.component)}`));
+  }
+}

package/src/cli/handlers/lifecycle.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
+import { sep } from "node:path";
 import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
@@ -85,6 +86,8 @@ describe("runLifecycleDiff --live", () => {
     buildMock.mockReset();
     fetchLifecycleMock.mockReset();
     readSnapshotMock.mockReset();
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
   });
 
   test("surfaces drift between previous snapshot and live state", async () => {
@@ -124,6 +127,46 @@ describe("runLifecycleDiff --live", () => {
     expect(output).toContain("UPDATE_COMPLETE");
   });
 
+  test("builds from config.sourceDir on a mixed-layout project", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    loadChantConfigMock.mockResolvedValue({ config: { sourceDir: "src" } });
+
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+    ];
+    const exit = await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", extraPositional2: "aws", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(exit).toBe(0);
+    const builtPath = buildMock.mock.calls[0][0] as string;
+    expect(builtPath.endsWith(`${sep}src`)).toBe(true);
+  });
+
+  test("--src overrides config.sourceDir for the build root", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    loadChantConfigMock.mockResolvedValue({ config: { sourceDir: "src" } });
+
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({}) }),
+    ];
+    const exit = await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", extraPositional2: "aws", live: true, src: "infra" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(exit).toBe(0);
+    const builtPath = buildMock.mock.calls[0][0] as string;
+    expect(builtPath.endsWith(`${sep}infra`)).toBe(true);
+  });
+
   test("warns and skips lexicons without describeResources", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ k8s: ["pod"] }));
     fetchLifecycleMock.mockResolvedValue(undefined);

package/src/cli/handlers/lifecycle.ts

@@ -12,6 +12,20 @@ import type { LifecycleSnapshot } from "../../lifecycle/types";
 import type { SerializerResult } from "../../serializer";
 import type { ObservationLexicon, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
+import type { ParsedArgs } from "../registry";
+import type { ChantConfig } from "../../config";
+
+/**
+ * Resolve the build root for a lifecycle command. The project root (where
+ * chant.config.ts lives) is always ".", but the *build* can be scoped to a
+ * subdirectory so a mixed-layout project — chant `src/` next to app code with
+ * import side effects — only synthesizes its infra. Precedence: `--src` flag,
+ * then `config.sourceDir`, then "." (the root). Snapshot/diff/plan all use this
+ * so their build digests stay consistent.
+ */
+function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
+  return resolve(args.src ?? config.sourceDir ?? ".");
+}
 
 /**
  * chant lifecycle snapshot <environment> [lexicon]
@@ -44,7 +58,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const targetSerializers = targetPlugins.map((p) => p.serializer);
 
   // Build first to get entity names and build output
-  const buildResult = await build(projectPath, targetSerializers);
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before taking a snapshot" }));
     return 1;
@@ -149,9 +163,9 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
     ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
     : serializers;
 
-  // Build to get current state
-  const projectPath = resolve(".");
-  const buildResult = await build(projectPath, targetSerializers);
+  // Build to get current state (from the configured source root, not necessarily ".")
+  const { config } = await loadChantConfig(resolve("."));
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before diffing" }));
     return 1;
@@ -425,8 +439,8 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
     : serializers;
 
-  const projectPath = resolve(".");
-  const buildResult = await build(projectPath, targetSerializers);
+  const { config } = await loadChantConfig(resolve("."));
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before planning" }));
     return 1;

package/src/cli/handlers/misc.ts

@@ -1,4 +1,5 @@
 import { listCommand, printListResult } from "../commands/list";
+import { describeCommand, printDescribeResult } from "../commands/describe";
 import { importCommand, importFromLive, printImportResult } from "../commands/import";
 import type { ResourceSelector } from "../../lexicon";
 import { formatError, formatSuccess, formatWarning } from "../format";
@@ -21,6 +22,35 @@ export async function runList(ctx: CommandContext): Promise<number> {
   return result.success ? 0 : 1;
 }
 
+export async function runDescribe(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  // `chant describe <component> [path]` — component is the first positional
+  // (args.path), the optional project dir is the second (args.extraPositional).
+  const component = args.path;
+  if (!component || component === ".") {
+    console.error(formatError({
+      message: "Component is required: chant describe <component> [path]",
+      hint: "Run `chant list` to see component names.",
+    }));
+    return 1;
+  }
+
+  const describeFormat = (args.format || "text") as "text" | "json";
+  if (describeFormat !== "text" && describeFormat !== "json") {
+    console.error(formatError({ message: `Invalid format for describe: ${describeFormat}. Expected 'text' or 'json'.` }));
+    return 1;
+  }
+
+  const result = await describeCommand({
+    component,
+    path: args.extraPositional ?? ".",
+    format: describeFormat,
+  });
+
+  printDescribeResult(result);
+  return result.success ? 0 : 1;
+}
+
 export async function runImport(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 

package/src/cli/main.ts

@@ -11,7 +11,7 @@ import { runLint } from "./handlers/lint";
 import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevUnknown } from "./handlers/dev";
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
-import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runList, runDescribe, runImport, runUpdate, runDoctor } from "./handlers/misc";
 import { runMigrate } from "./handlers/migrate";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runGraph } from "./handlers/graph";
@@ -49,6 +49,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     useComposites: false,
     reportFile: undefined,
     skill: undefined,
+    src: undefined,
   };
 
   let i = 0;
@@ -111,6 +112,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.useComposites = true;
     } else if (arg === "--skill") {
       result.skill = args[++i];
+    } else if (arg === "--src") {
+      result.src = args[++i];
     } else if (arg === "--local") {
       result.local = true;
     } else if (arg === "--temporal") {
@@ -151,6 +154,7 @@ Commands:
   build                 Build infrastructure from specification files
   lint                  Check specifications for issues
   list                  List discovered entities
+  describe              Show the effective config for one component
   import                Import external template into TypeScript
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
@@ -227,6 +231,8 @@ Examples:
   chant lint ./infra/ --watch
   chant list ./infra/
   chant list ./infra/ --format json
+  chant describe myComponent src/
+  chant describe myComponent src/ --format json
 `);
 }
 
@@ -262,6 +268,7 @@ const registry: CommandDef[] = [
   { name: "build", requiresPlugins: true, handler: runBuild },
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
+  { name: "describe", handler: runDescribe },
   { name: "import", handler: runImport },
   { name: "migrate", handler: runMigrate },
   { name: "init", handler: runInit },
@@ -332,9 +339,14 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  // For compound commands (e.g. "run list"), args.path is the subcommand,
-  // so always use "." as the project path. For simple commands, use args.path.
-  const projectPath = match.compound ? (args.extraPositional || ".") : args.path;
+  // For compound commands (e.g. "run list", "lifecycle plan <env>"), the first
+  // positional is a subcommand argument — an environment, op, or lexicon name —
+  // not a project path. Plugins always load from the cwd; the handler reads its
+  // own positionals from args.extraPositional. Using extraPositional as the path
+  // here pointed plugin resolution at e.g. "./local" for `lifecycle plan local`,
+  // which then fell through to import-detection on an empty file set and failed
+  // with "No lexicon detected" even though chant.config.ts lists the lexicons.
+  const projectPath = match.compound ? "." : args.path;
   const plugins = match.def.requiresPlugins
     ? await loadPluginsOrExit(projectPath)
     : [];

package/src/cli/registry.ts

@@ -51,6 +51,8 @@ export interface ParsedArgs {
   owned?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
+  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
+  src?: string;
 }
 
 /**

package/src/config.ts

@@ -10,6 +10,7 @@ import type { OwnershipMarker } from "./ownership";
 export const ChantConfigSchema = z.object({
   lexicons: z.array(z.string().min(1)).optional(),
   environments: z.array(z.string().min(1)).optional(),
+  sourceDir: z.string().min(1).optional(),
   lint: z.record(z.string(), z.unknown()).optional(),
   ownership: z.object({
     stack: z.string().min(1).optional(),
@@ -30,6 +31,15 @@ export interface ChantConfig {
   /** Environment names (e.g. ["staging", "prod"]) */
   environments?: string[];
 
+  /**
+   * Directory (relative to the project root) that holds the chant infrastructure
+   * source. Lifecycle commands (`snapshot`/`diff`/`plan`) build from here instead
+   * of the project root, so a mixed-layout project — chant `src/` alongside app
+   * code that has import side effects — can scope the build to just the infra.
+   * Defaults to "." (the project root). The `--src` flag overrides it.
+   */
+  sourceDir?: string;
+
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
 

package/src/op/activity-registry.ts

@@ -63,10 +63,17 @@ export interface ActivityProfile {
  * Dynamically import the lexicon's `TEMPORAL_ACTIVITY_PROFILES` (pure data, no
  * Temporal SDK). Returns an empty record if the lexicon is absent — the
  * executor then falls back to built-in defaults per step.
+ *
+ * Imports the lexicon's `/config` entry, not its root index. `/config` is a
+ * side-effect-free data module; the root index pulls in the plugin, serializer,
+ * composites, and re-exported Op machinery, any of which could throw on load
+ * and make this silently return `{}` — which would drop every profiled step to
+ * the 5-minute default while the Temporal path (reading the same table) kept the
+ * declared timeout. Importing the narrow module keeps the two executors agreed.
  */
 export async function loadProfiles(): Promise<Record<string, ActivityProfile>> {
   try {
-    const spec = "@intentius/chant-lexicon-temporal";
+    const spec = "@intentius/chant-lexicon-temporal/config";
     const mod = (await import(spec)) as { TEMPORAL_ACTIVITY_PROFILES?: Record<string, ActivityProfile> };
     return mod.TEMPORAL_ACTIVITY_PROFILES ?? {};
   } catch {

package/src/op/builders.ts

@@ -60,36 +60,72 @@ export function gate(
 
 // ── Pre-built activity shortcuts ──────────────────────────────────────────────
 
+/**
+ * Pull an optional `profile` override out of an opts bag, returning the
+ * remaining keys (which become activity args) separately.
+ *
+ * Without this, a `profile` passed in opts would spread into the activity's
+ * **args** rather than set the step's `profile` — a silent no-op on the step's
+ * timeout. The activity then runs under the default profile, so a step the
+ * author tagged `longInfra` (20m) would still get the 5m default. Routing it
+ * here lets every shortcut accept a `profile` override that actually takes.
+ */
+function takeProfile(
+  opts: Record<string, unknown> | undefined,
+): { args: Record<string, unknown>; profile?: ActivityStep["profile"] } {
+  if (!opts) return { args: {} };
+  const { profile, ...args } = opts as { profile?: ActivityStep["profile"] } & Record<string, unknown>;
+  return { args, profile };
+}
+
 /** 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 });
+export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("chantBuild", { path, ...args }, profile);
+};
 
-/** Run `kubectl apply -f <manifest>`. Uses `longInfra` profile. */
-export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep =>
-  activity("kubectlApply", { manifest, ...opts }, "longInfra");
+/** Run `kubectl apply -f <manifest>`. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("kubectlApply", { manifest, ...args }, profile ?? "longInfra");
+};
 
-/** Run `helm upgrade --install`. Uses `longInfra` profile. */
+/** Run `helm upgrade --install`. Defaults to the `longInfra` profile (override via `opts.profile`). */
 export const helmInstall = (
   name: string,
   chart: string,
-  opts?: { values?: string; namespace?: string; [k: string]: unknown },
-): ActivityStep => activity("helmInstall", { name, chart, ...opts }, "longInfra");
+  opts?: { values?: string; namespace?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("helmInstall", { name, chart, ...args }, profile ?? "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");
+/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
+export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("waitForStack", { name, ...args }, profile ?? "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");
+/** Trigger and wait for a GitLab CI pipeline to complete. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("gitlabPipeline", { name, ...args }, profile ?? "longInfra");
+};
 
 /** Take a chant lifecycle snapshot for the given environment. */
 export const lifecycleSnapshot = (env: string): ActivityStep =>
   activity("lifecycleSnapshot", { env });
 
-/** Run an arbitrary shell command. */
-export const shell = (cmd: string, opts?: { env?: Record<string, string> }): ActivityStep =>
-  activity("shellCmd", { cmd, ...opts });
+/**
+ * Run an arbitrary shell command. Tag long-running commands with a `profile`
+ * (e.g. `longInfra` for a multi-GB image push) so they get the right
+ * start-to-close timeout under both the local executor and Temporal.
+ */
+export const shell = (
+  cmd: string,
+  opts?: { env?: Record<string, string>; profile?: ActivityStep["profile"] },
+): ActivityStep =>
+  activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
 
 /** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
 export const teardown = (path: string): ActivityStep =>

package/src/op/local-executor.test.ts

@@ -110,6 +110,22 @@ describe("runOpLocally — retry + timeout", () => {
     const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "always" }] }] });
     await expect(runOpLocally(config, new Map([["always", always]]), PROFILES)).rejects.toBeInstanceOf(OpRunFailure);
   });
+
+  test("honors a step's non-default profile timeout (not the default)", async () => {
+    // The default profile would time out at 50ms; the step is tagged longInfra,
+    // which gives it room. Guards the bug where a profiled step silently got the
+    // default cap (local vs --temporal disagreement).
+    const slow: ActivityFn = async () => { await new Promise((r) => setTimeout(r, 150)); return "done"; };
+    const profiles = {
+      fastIdempotent: { startToCloseTimeout: "50ms", retry: { maximumAttempts: 1 } },
+      longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+    };
+    const config = op({
+      phases: [{ name: "P", steps: [{ kind: "activity", fn: "slow", profile: "longInfra" }] }],
+    });
+    const result = await runOpLocally(config, new Map([["slow", slow]]), profiles);
+    expect(result.records[0].status).toBe("ok");
+  });
 });
 
 describe("runOpLocally — cancellation", () => {

package/src/op/op.test.ts

@@ -197,3 +197,40 @@ describe("pre-built shortcuts", () => {
     expect(a.profile).toBe("longInfra");
   });
 });
+
+describe("profile routing (opts.profile sets the step profile, never leaks into args)", () => {
+  it("shell() routes profile to the step, keeps env in args", () => {
+    const a = shell("docker compose push", { env: { TAG: "v1" }, profile: "longInfra" });
+    expect(a.profile).toBe("longInfra");
+    expect(a.args?.cmd).toBe("docker compose push");
+    expect(a.args?.env).toEqual({ TAG: "v1" });
+    // The footgun this fixes: profile must NOT end up as an activity arg.
+    expect("profile" in (a.args ?? {})).toBe(false);
+  });
+
+  it("shell() without profile leaves the step unprofiled (defaults apply downstream)", () => {
+    const a = shell("echo hi", { env: { A: "1" } });
+    expect("profile" in a).toBe(false);
+    expect(a.args?.env).toEqual({ A: "1" });
+  });
+
+  it("build() accepts a profile override and does not leak it into args", () => {
+    const a = build("./p", { profile: "longInfra" });
+    expect(a.profile).toBe("longInfra");
+    expect(a.args?.path).toBe("./p");
+    expect("profile" in (a.args ?? {})).toBe(false);
+  });
+
+  it("kubectlApply() lets opts.profile override the longInfra default", () => {
+    const a = kubectlApply("dist/infra.yaml", { profile: "k8sWait" });
+    expect(a.profile).toBe("k8sWait");
+    expect(a.args?.manifest).toBe("dist/infra.yaml");
+    expect("profile" in (a.args ?? {})).toBe(false);
+  });
+
+  it("waitForStack() supports the argoSync profile", () => {
+    const a = waitForStack("argo-app", { profile: "argoSync" });
+    expect(a.profile).toBe("argoSync");
+    expect("profile" in (a.args ?? {})).toBe(false);
+  });
+});

package/src/op/types.ts

@@ -45,7 +45,7 @@ export interface ActivityStep {
    * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
    * Default: "fastIdempotent"
    */
-  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate" | "argoSync";
   /**
    * Surface this activity's return value as a workflow search attribute.
    *