Add typed on.stop-after field; allow GitHub Actions expressions (#56983)

Author: Copilot

.changeset/type-on-stop-after.md

@@ -3,6 +3,66 @@
 
 const { ERR_CONFIG, ERR_VALIDATION } = require("./error_codes.cjs");
 const { writeDenialSummary } = require("./pre_activation_summary.cjs");
+
+// Matches a relative time delta such as "+25h", "+3d", "+1w", "+1mo", "+1d12h".
+// Mirrors pkg/workflow/time_delta.go's parseTimeDeltaForStopAfter: minutes are not
+// supported since the minimum unit for stop-after is hours.
+const TIME_DELTA_PATTERN = /(\d+)(mo|w|d|h)/g;
+
+/** @param {string} stopTime */
+function isRelativeStopTime(stopTime) {
+  return stopTime.startsWith("+");
+}
+
+/** @param {string} deltaStr */
+function parseTimeDeltaForStopAfter(deltaStr) {
+  const rest = deltaStr.slice(1);
+  if (!rest) {
+    throw new Error("empty time delta after '+'");
+  }
+
+  const matches = [...rest.matchAll(TIME_DELTA_PATTERN)];
+  if (matches.length === 0) {
+    throw new Error(`invalid time delta format: +${rest}. Expected format like +25h, +3d, +1w, +1mo, +1d12h`);
+  }
+
+  const consumed = matches.reduce((sum, match) => sum + match[0].length, 0);
+  if (consumed !== rest.length) {
+    throw new Error(`invalid time delta format: +${rest}. Extra characters detected`);
+  }
+
+  const delta = { months: 0, weeks: 0, days: 0, hours: 0 };
+  const seenUnits = new Set();
+  for (const [, valueStr, unit] of matches) {
+    if (seenUnits.has(unit)) {
+      throw new Error(`duplicate unit '${unit}' in time delta: +${rest}`);
+    }
+    seenUnits.add(unit);
+    const value = parseInt(valueStr, 10);
+    if (unit === "mo") delta.months = value;
+    else if (unit === "w") delta.weeks = value;
+    else if (unit === "d") delta.days = value;
+    else if (unit === "h") delta.hours = value;
+  }
+  return delta;
+}
+
+/**
+ * Resolves a relative stop-time delta (e.g. "+48h") to an absolute Date, relative to baseTime.
+ * Mirrors pkg/workflow/stop_after.go's resolveStopTime: months and days/weeks are applied
+ * together in a single calendar computation (so date-normalization overflow, e.g. Jan 31 + 1mo,
+ * is resolved consistently), then hours are added on top.
+ * @param {string} deltaStr
+ * @param {Date} baseTime
+ */
+function resolveRelativeStopTime(deltaStr, baseTime) {
+  const delta = parseTimeDeltaForStopAfter(deltaStr);
+  const totalDays = delta.weeks * 7 + delta.days;
+  return new Date(
+    Date.UTC(baseTime.getUTCFullYear(), baseTime.getUTCMonth() + delta.months, baseTime.getUTCDate() + totalDays, baseTime.getUTCHours() + delta.hours, baseTime.getUTCMinutes(), baseTime.getUTCSeconds(), baseTime.getUTCMilliseconds())
+  );
+}
+
 async function main() {
   const stopTime = process.env.GH_AW_STOP_TIME;
   const workflowName = process.env.GH_AW_WORKFLOW_NAME;
@@ -19,8 +79,21 @@ async function main() {
 
   core.info(`Checking stop-time limit: ${stopTime}`);
 
-  // Parse the stop time (format: "YYYY-MM-DD HH:MM:SS")
-  const stopTimeDate = new Date(stopTime);
+  // Resolve the stop time. A GitHub Actions expression (e.g. "${{ inputs.stop-after }}")
+  // is passed through verbatim at compile time and evaluated by the runner before this
+  // step runs, so it may still be a relative delta (e.g. "+48h") rather than an already
+  // resolved absolute timestamp (format: "YYYY-MM-DD HH:MM:SS").
+  let stopTimeDate;
+  if (isRelativeStopTime(stopTime)) {
+    try {
+      stopTimeDate = resolveRelativeStopTime(stopTime, new Date());
+    } catch (err) {
+      core.setFailed(`${ERR_VALIDATION}: Invalid stop-time format: ${stopTime}. ${err instanceof Error ? err.message : String(err)}`);
+      return;
+    }
+  } else {
+    stopTimeDate = new Date(stopTime);
+  }
 
   if (Number.isNaN(stopTimeDate.getTime())) {
     core.setFailed(`${ERR_VALIDATION}: Invalid stop-time format: ${stopTime}. Expected format: YYYY-MM-DD HH:MM:SS`);

actions/setup/js/check_stop_time.cjs

@@ -97,5 +97,28 @@ const mockCore = {
             expect(mockCore.setOutput).toHaveBeenCalledWith("stop_time_ok", "false"),
             expect(mockCore.setFailed).not.toHaveBeenCalled());
         });
+      }),
+      describe("when stop time is a relative delta (e.g. resolved from a GitHub Actions expression)", () => {
+        it("should allow execution for a future relative delta such as +48h", async () => {
+          ((process.env.GH_AW_STOP_TIME = "+48h"),
+            (process.env.GH_AW_WORKFLOW_NAME = "test-workflow"),
+            await eval(`(async () => { ${checkStopTimeScript}; await main(); })()`),
+            expect(mockCore.setOutput).toHaveBeenCalledWith("stop_time_ok", "true"),
+            expect(mockCore.setFailed).not.toHaveBeenCalled());
+        });
+        it("should support combined units such as +1d12h", async () => {
+          ((process.env.GH_AW_STOP_TIME = "+1d12h"),
+            (process.env.GH_AW_WORKFLOW_NAME = "test-workflow"),
+            await eval(`(async () => { ${checkStopTimeScript}; await main(); })()`),
+            expect(mockCore.setOutput).toHaveBeenCalledWith("stop_time_ok", "true"),
+            expect(mockCore.setFailed).not.toHaveBeenCalled());
+        });
+        it("should fail with a descriptive error for an invalid relative delta", async () => {
+          ((process.env.GH_AW_STOP_TIME = "+5x"),
+            (process.env.GH_AW_WORKFLOW_NAME = "test-workflow"),
+            await eval(`(async () => { ${checkStopTimeScript}; await main(); })()`),
+            expect(mockCore.setFailed).toHaveBeenCalledWith(expect.stringContaining("Invalid stop-time format")),
+            expect(mockCore.setOutput).not.toHaveBeenCalled());
+        });
       }));
   }));

actions/setup/js/check_stop_time.test.cjs

@@ -0,0 +1,50 @@
+# ADR-56983: Add Typed `on.stop-after` and Runtime Expressions
+
+**Date**: 2026-08-29
+**Status**: Draft
+**Deciders**: pelikhan, adr-writer agent
+
+---
+
+### Context
+
+This pull request changes workflow frontmatter handling in `pkg/workflow` so `on.stop-after` is no longer interpreted only through the dynamic `On` map and can also accept GitHub Actions expressions such as `${{ inputs.stop-after }}`. The PR description identifies a drift risk between typed config, parser behavior, and documentation because `stop-after` was documented and consumed at runtime but had no dedicated typed field. The existing compile-time stop-after resolution logic also rejected expression-based values even when those values should be deferred to workflow runtime. Because this PR adds more than 100 lines in business-logic directories and changes parser/compiler behavior, the underlying design decision should be recorded explicitly.
+
+### Decision
+
+We will add a typed `OnStopAfter` field to `FrontmatterConfig`, centralize `on.stop-after` extraction in a shared parser helper, and treat GitHub Actions expressions for `stop-after` as runtime-resolved values that pass through compilation unchanged. We chose this approach to eliminate schema/parser/docs drift, keep typed and untyped frontmatter access paths consistent, and allow parameterized stop times without forcing compile-time parsing of runtime expressions. Literal relative and absolute stop-after values will continue to be resolved using the existing compiler behavior.
+
+### Alternatives Considered
+
+#### Alternative 1: Keep `stop-after` Dynamic-Only in `on` Map
+
+Continue reading `on.stop-after` only from `map[string]any` and leave typed config without a dedicated field.
+
+This was considered because it would require the fewest structural changes to frontmatter parsing. It was not chosen because the PR evidence shows this has already created typed-schema and documentation drift risk, and separate access paths make it easier for parser behavior to diverge over time.
+
+#### Alternative 2: Require All `stop-after` Values to Be Compile-Time Literals
+
+Preserve the existing behavior that parses every `stop-after` value as a relative delta or absolute timestamp during compilation.
+
+This was considered because compile-time normalization gives early validation and a single resolved representation in generated workflows. It was not chosen because GitHub Actions expressions are legitimate runtime inputs for workflow dispatch and should not be rejected merely because they cannot be resolved at compile time.
+
+### Consequences
+
+#### Positive
+- Typed frontmatter now exposes `on.stop-after` explicitly, reducing drift between config structs, parser behavior, schema text, and documentation.
+- A shared parsing helper makes typed population and runtime extraction use the same interpretation logic, lowering the risk of inconsistent behavior.
+- Workflows can accept expression-based `stop-after` values such as `${{ inputs.stop-after }}`, enabling runtime parameterization for dispatch inputs.
+
+#### Negative
+- Stop-after handling now has two execution modes: compile-time resolution for literals and runtime passthrough for expressions, which increases conceptual complexity.
+- Expression-based values defer some validation until workflow runtime, so certain user errors will no longer be caught during compilation.
+- Adding another typed frontmatter field increases the maintenance surface of `FrontmatterConfig` and its parsing/tests.
+
+#### Neutral
+- Existing literal `stop-after` formats remain supported; this change extends accepted inputs rather than replacing them.
+- The implementation requires coordinated updates across parser code, schema descriptions, generated docs, and tests.
+- Runtime workflow semantics change only for expression inputs; absolute and relative literal values continue through the established resolution path.
+
+---
+
+*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*

docs/adr/56983-add-typed-on-stop-after-and-runtime-expressions.md

@@ -859,10 +859,11 @@ on:
       {}
 
   # Time when workflow should stop running. Supports multiple formats: absolute
-  # dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.) or
-  # relative time deltas (+25h, +3d, +1d12h30m). Maximum values for time deltas:
-  # 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not allowed for
-  # stop-after; minimum unit is hours 'h'.
+  # dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.),
+  # relative time deltas (+25h, +3d, +1d12h30m), or a GitHub Actions expression
+  # (e.g. ${{ inputs.stop-after }}) resolved at workflow runtime. Maximum values for
+  # time deltas: 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not
+  # allowed for stop-after; minimum unit is hours 'h'.
   # (optional)
   stop-after: "example-value"
 

docs/src/content/docs/reference/frontmatter-full.md

@@ -1933,7 +1933,7 @@
             },
             "stop-after": {
               "type": "string",
-              "description": "Time when workflow should stop running. Supports multiple formats: absolute dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.) or relative time deltas (+25h, +3d, +1d12h30m). Maximum values for time deltas: 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not allowed for stop-after; minimum unit is hours 'h'."
+              "description": "Time when workflow should stop running. Supports multiple formats: absolute dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.), relative time deltas (+25h, +3d, +1d12h30m), or a GitHub Actions expression (e.g. ${{ inputs.stop-after }}) resolved at workflow runtime. Maximum values for time deltas: 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not allowed for stop-after; minimum unit is hours 'h'."
             },
             "skip-if-match": {
               "oneOf": [

pkg/parser/schemas/main_workflow_schema.json

@@ -114,6 +114,17 @@ func ParseFrontmatterConfig(frontmatter map[string]any) (*FrontmatterConfig, err
 		}
 	}
 
+	// Parse typed on.stop-after field if on exists. Parse errors (e.g. wrong type) are
+	// intentionally not fatal here: extractStopAfterFromOn re-validates the raw value
+	// and returns the actual compile error at the point stop-after is consumed.
+	if len(config.On) > 0 {
+		stopAfter, err := parseOnStopAfterValue(config.On)
+		if err == nil {
+			config.OnStopAfter = stopAfter
+			frontmatterTypesLog.Printf("Parsed typed on.stop-after config: %q", stopAfter)
+		}
+	}
+
 	// Populate typed ExperimentConfigs from the raw frontmatter map so that both the
 	// legacy bare-array form and the new object form are available as ExperimentConfig
 	// structs without callers needing to type-assert config.Experiments entries.

pkg/workflow/frontmatter_parsing.go

@@ -390,6 +390,7 @@ type FrontmatterConfig struct {
 	// Event and trigger configuration
 	On          map[string]any `json:"on,omitempty"`          // Complex trigger config with many variants (too dynamic to type)
 	OnNeeds     []string       `json:"-"`                     // New typed field extracted from on.needs (not in JSON to avoid conflict)
+	OnStopAfter string         `json:"-"`                     // Typed field extracted from on.stop-after (not in JSON to avoid conflict). Accepts a relative delta ("+25h"), an absolute timestamp, or a GitHub Actions expression (e.g. "${{ inputs.stop-after }}").
 	Permissions map[string]any `json:"permissions,omitempty"` // Deprecated: use PermissionsTyped (can be string or map)
 	Concurrency map[string]any `json:"concurrency,omitempty"`
 	If          string         `json:"if,omitempty"`