Add date filters: Seconds, Minutes, Hours, Days, Weeks, Months, TimeSpan

[NickJosevski]

All PRs in this change

Three variants of the same feature — pick one row, the other two get closed.

Variant	Octostache	Docs	Server	Calamari
A · AddHours + AddDays	#124	OctopusDeploy/docs#3326	OctopusDeploy/OctopusDeploy#46148	OctopusDeploy/Calamari#2124
B · AddTimeSpan only	#125	OctopusDeploy/docs#3328	OctopusDeploy/OctopusDeploy#46155	OctopusDeploy/Calamari#2128
C ← this PR · all units + AddTimeSpan	#126	OctopusDeploy/docs#3329	OctopusDeploy/OctopusDeploy#46159	OctopusDeploy/Calamari#2129

Merge order is the same for every variant: Octostache first, then the package publishes, then Docs and Server. Calamari additionally needs its Octostache 3.9.2 pin bumped, so it stays red until then.

---

What

The full set, so nothing is missing and AddTimeSpan isn't the only option.

Filter	Amount
AddSeconds AddMinutes AddHours AddDays AddWeeks	number, negative and fractional allowed
AddMonths	whole number, calendar shift
AddTimeSpan	{days}.{hours}:{minutes}:{seconds}

#{Octopus.Task.QueueTime | AddHours 2 | Format "yyyy-MM-dd HH:mm:ss"}
#{MyVar | AddMonths 1 | AddDays 1 | AddHours 2}

Fractional amounts need quoting (AddHours "1.5") — . isn't valid in an unquoted filter argument. Time zone shape is preserved: naive stays naive, UTC stays UTC, an explicit offset is kept rather than converted to server-local.

What reviewers should look at

1. AddMonths is not a duration. Calendar months vary in length, so it uses DateTime.AddMonths, takes whole months only, and clamps the day:

Input	Filter	Output
2030-01-31	AddMonths 1	2030-02-28
2032-01-31	AddMonths 1	2032-02-29 (leap)
2030-03-31	AddMonths -1	2030-02-28

So AddMonths 1 | AddMonths -1 is not always identity. AddMonths "1.5" is rejected rather than rounded.

2. AddTimeSpan 48:00:00 is 48 days, not 48 hours — the {hours} field only holds 0–23, so above that the leading field becomes {days} and the rest shift along. Silent, and inherent to the .NET format. This variant is the only one where the docs can point at an unambiguous alternative in the same release: AddHours 48. A test contrasts the two directly.

Implementation

One Shift core owns parsing, time-zone shape and formatting. AddDuration adapts the five fixed-duration filters via Func<double, TimeSpan>; AddMonths and AddTimeSpan call Shift directly. Same delegate-parameterised helper shape as HashFunction.

Tests

628 passing — every unit, negatives, fractionals, month clamping both directions and across a leap year, whole-month rejection, the AddTimeSpan vs AddHours 48 contrast, quoting, chained filters, offset preservation, chaining off NowDate/NowDateUtc, echo-on-bad-input.

🤖 Generated with Claude Code

[NickJosevski]

Closing — going with the AddHours/AddDays shape in #124 instead.