@go-labs-sg/gosh 1.4.0 → 1.6.0

package/README.md

@@ -157,6 +157,42 @@ Deploy prerequisite: apply the additive GOSH database schema changes for both
 to `[]`, before deploying the updated server. Older event snapshots restore an
 empty list. Client generation alone does not apply these database changes.
 
+### Number range answers
+
+Fill-in-the-blank missions can accept any number in an inclusive range instead
+of text answers. Set `config.numberRange` with `min` and `max` (`min` must be
+less than or equal to `max`). Players must answer with a number such as `55`,
+`55.5`, `-3` or `1,000`; anything that is not a number is marked incorrect.
+Ranges cannot be combined with `acceptedAnswers` and are only available for
+fill-in-the-blank missions.
+
+```bash
+gosh mission create --input '{"stationId":"station-id","name":"Guess the height","type":"FILL_IN_THE_BLANK","config":{"numberRange":{"min":50,"max":60}}}'
+gosh mission update --input '{"missionId":"mission-id","name":"Guess the height","type":"FILL_IN_THE_BLANK","config":null,"correctAnswer":"55"}'
+```
+
+When updating, omit `config` to keep the saved range or pass `null` to switch
+back to text answers. Players see a number input but never the range itself.
+
+Rollout gate: the stored `correctAnswer` (`"50-60"`) is a display key, not a
+safe fallback. A server without number-range support grades it as plain text,
+so it accepts the literal `50-60` and rejects an in-range `55`, and its
+template, clone and version writers drop `config`. Apply the additive
+`Mission.config` and `GoshTemplateMission.config` columns, finish rolling out
+the server everywhere, then create range missions.
+
+Rollback: a range mission that has submissions cannot be switched back to text.
+The answer-key lock in `mission update` rejects that edit on purpose, so stored
+answers and points stay consistent. Do not loosen or bypass it. Instead:
+
+- Unused range missions (no submissions) and templates can be switched back to
+  text answers or removed before a rollback.
+- Used range missions: do not roll the server back past number-range support
+  while those events are live. Fix forward on a compatible build (any build
+  with number-range grading), or keep the previous image ready only for
+  events with no range missions. A lossless rollback for used range missions
+  needs its own approved plan; a normal edit cannot do it.
+
 ### Templates and organization scope
 
 Template commands use the selected organization as their scope. Provide its ID in
@@ -264,11 +300,15 @@ gosh team create \
 ```
 
 Configure gameplay, then manage the event's routing groups and their complete
-station lists:
+station lists. `requireLocationOnSubmit` (default false) makes players at a
+location-locked station check in again within the last two minutes before each
+answer or upload is accepted, not only once at check-in. A fresh QR scan counts
+at stations that also accept QR. It stays editable during live play; omit it,
+or `allowStationSkipping`, to keep the event's current value.
 
 ```bash
 gosh event set-gameplay \
-  --input '{"eventId":"event-id","progression":"SEQUENTIAL","groupRoutingEnabled":true,"allowMissionSkipping":true,"allowStationSkipping":false}' \
+  --input '{"eventId":"event-id","progression":"SEQUENTIAL","groupRoutingEnabled":true,"allowMissionSkipping":true,"allowStationSkipping":false,"requireLocationOnSubmit":true}' \
   --target event-id \
   --allow-state-change
 
@@ -332,6 +372,49 @@ groups to read back release values and editability, and use
 for the five most recent actor/before/after changes; the existing event activity
 timeline provides the full audit history.
 
+### Staggered team starts within a group
+
+Teams sharing a route can start at different times. A team's own `releaseAt`
+replaces the group's time (earlier or later); with none, the team uses the
+group's time, so existing events are unchanged. A held group still holds every
+team, and a team hold holds one team inside a released group. The server
+enforces each team's effective time on every gameplay call.
+
+Preview a stagger first. It writes nothing and lists each team's before/after
+time plus any blockers the apply would refuse with:
+
+```bash
+gosh routing-group stagger-preview \
+  --input '{"eventId":"event-id","groupId":"group-a","mode":"STAGGER","firstReleaseAt":"2030-01-01T13:40:00+08:00","intervalMinutes":5,"teamIds":["team-1","team-2","team-3"]}'
+gosh routing-group stagger \
+  --input '{"eventId":"event-id","groupId":"group-a","mode":"STAGGER","firstReleaseAt":"2030-01-01T13:40:00+08:00","intervalMinutes":5,"teamIds":["team-1","team-2","team-3"]}' \
+  --target group-a \
+  --allow-state-change
+```
+
+`teamIds` order is start order: `team-1` 13:40, `team-2` 13:45, `team-3` 13:50.
+Teams left out keep their current time. Use `"mode":"SHIFT","shiftMinutes":10`
+to delay every unstarted scheduled team by 10 minutes (negative moves earlier,
+never into the past), or `"mode":"CLEAR"` to drop team times so teams use the
+group time again. Apply runs in one transaction, so either every team changes
+or none do. Started teams are never rescheduled.
+
+One team at a time, including while LIVE:
+
+```bash
+gosh team release \
+  --input '{"eventId":"event-id","teamId":"team-2","action":"HOLD"}' \
+  --target team-2 \
+  --allow-state-change
+gosh team release-history --input '{"eventId":"event-id","teamId":"team-2"}'
+```
+
+Actions are SCHEDULE (future `releaseAt` with offset), CLEAR (use the group
+time), HOLD, RELEASE_HOLD (keep the team time) and RELEASE_NOW (start this team
+now; refused while the group is held). After a team starts, only HOLD and
+RELEASE_HOLD are accepted. Every change is audited with actor and before/after
+values.
+
 The server evaluates deadlines without cron. Release never starts a timer or
 bypasses LIVE status, availability, check-in or captain permissions. Any team in
 a group beginning play locks that group's schedule; emergency HOLD/resume stays

package/command-manifest.json

@@ -791,7 +791,7 @@
 		"path": ["mission", "create"],
 		"procedure": "event.createMission",
 		"requiresAuth": true,
-		"summary": "Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives). Optional revealMessage (up to 2,000 characters) is shown only after submitting.",
+		"summary": "Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives), or config.numberRange {min,max} to accept any number in that inclusive range instead. Optional revealMessage (up to 2,000 characters) is shown only after submitting.",
 		"targetKeys": [
 			"id",
 			"memberId",
@@ -823,7 +823,7 @@
 		"path": ["mission", "update"],
 		"procedure": "event.updateMission",
 		"requiresAuth": true,
-		"summary": "Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.",
+		"summary": "Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Set config.numberRange {min,max} for a numeric range answer; omit config to preserve or pass null to return to text answers. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.",
 		"targetKeys": [
 			"id",
 			"memberId",
@@ -1170,7 +1170,7 @@
 		"path": ["event", "set-gameplay"],
 		"procedure": "team.setGameplaySettings",
 		"requiresAuth": true,
-		"summary": "Set open or sequential progression, group routing, and per-mission skipping before play starts.",
+		"summary": "Set open or sequential progression, group routing, and per-mission skipping before play starts. Station skipping and requireLocationOnSubmit stay editable live.",
 		"targetKeys": ["eventId"]
 	},
 	{
@@ -1201,6 +1201,44 @@
 		"summary": "Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, RELEASE_SCHEDULED_HOLD (keep schedule), or RELEASE_NOW for a routing group. After a group starts, only HOLD and RELEASE_SCHEDULED_HOLD are accepted. Requires launchEvent permission.",
 		"targetKeys": ["groupId", "eventId"]
 	},
+	{
+		"effects": [],
+		"input": "json",
+		"operation": "query",
+		"path": ["routing-group", "stagger-preview"],
+		"procedure": "team.previewRoutingGroupStagger",
+		"requiresAuth": true,
+		"summary": "Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with."
+	},
+	{
+		"effects": ["state-change"],
+		"input": "json",
+		"operation": "mutation",
+		"path": ["routing-group", "stagger"],
+		"procedure": "team.applyRoutingGroupStagger",
+		"requiresAuth": true,
+		"summary": "Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.",
+		"targetKeys": ["groupId", "eventId"]
+	},
+	{
+		"effects": ["state-change"],
+		"input": "json",
+		"operation": "mutation",
+		"path": ["team", "release"],
+		"procedure": "team.updateTeamRelease",
+		"requiresAuth": true,
+		"summary": "Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.",
+		"targetKeys": ["teamId", "eventId"]
+	},
+	{
+		"effects": [],
+		"input": "json",
+		"operation": "query",
+		"path": ["team", "release-history"],
+		"procedure": "team.listTeamReleaseHistory",
+		"requiresAuth": true,
+		"summary": "Show a team's five most recent start-time changes with actor, action and before/after UTC values."
+	},
 	{
 		"effects": ["state-change"],
 		"input": "json",
@@ -2200,6 +2238,15 @@
 		"requiresAuth": true,
 		"summary": "Get a playable station."
 	},
+	{
+		"effects": [],
+		"input": "json",
+		"operation": "query",
+		"path": ["player", "station", "presence"],
+		"procedure": "event.getPlayerStationPresence",
+		"requiresAuth": true,
+		"summary": "Check whether a location is within a station's submit range when the event asks players to stay at the station to submit. Returns a state and rounded distance, never coordinates."
+	},
 	{
 		"effects": [],
 		"input": "none",

package/command-reference.md

@@ -332,7 +332,7 @@ Reorder shared stations, or a selected team's station route when scopeTeamId is
 
 ## `gosh mission create`
 
-Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives). Optional revealMessage (up to 2,000 characters) is shown only after submitting.
+Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives), or config.numberRange {min,max} to accept any number in that inclusive range instead. Optional revealMessage (up to 2,000 characters) is shown only after submitting.
 
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
@@ -340,7 +340,7 @@ Create a mission in a station. Fill-in-the-blank inputs support correctAnswer an
 
 ## `gosh mission update`
 
-Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.
+Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Set config.numberRange {min,max} for a numeric range answer; omit config to preserve or pass null to return to text answers. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.
 
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
@@ -444,7 +444,7 @@ Replace a team's linked station route and set its order.
 
 ## `gosh event set-gameplay`
 
-Set open or sequential progression, group routing, and per-mission skipping before play starts.
+Set open or sequential progression, group routing, and per-mission skipping before play starts. Station skipping and requireLocationOnSubmit stay editable live.
 
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
@@ -474,6 +474,38 @@ Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, REL
 - Input: `--input '<json>'` required
 - Effects: state-change
 
+## `gosh routing-group stagger-preview`
+
+Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: read-only
+
+## `gosh routing-group stagger`
+
+Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: state-change
+
+## `gosh team release`
+
+Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: state-change
+
+## `gosh team release-history`
+
+Show a team's five most recent start-time changes with actor, action and before/after UTC values.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: read-only
+
 ## `gosh routing-group create`
 
 Create a routing group within an event before play starts.
@@ -922,6 +954,14 @@ Get a playable station.
 - Input: `--input '<json>'` required
 - Effects: read-only
 
+## `gosh player station presence`
+
+Check whether a location is within a station's submit range when the event asks players to stay at the station to submit. Returns a state and rounded distance, never coordinates.
+
+- Authentication: browser-authenticated CLI session required
+- Input: `--input '<json>'` required
+- Effects: read-only
+
 ## `gosh player events`
 
 List events joined by the current user.

package/dist/index.js

@@ -35,7 +35,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = import.meta.require;
 
-// ../../../node_modules/.bun/dotenv@18.0.8/node_modules/dotenv/dist/index.cjs
+// ../../../node_modules/.bun/dotenv@18.0.9/node_modules/dotenv/dist/index.cjs
 var require_dist = __commonJS(function(exports, module) {
   var j = (e, n) => () => {
     try {
@@ -367,7 +367,7 @@ var require_dist = __commonJS(function(exports, module) {
     }
     function Ee(e) {
       let n = J(), t = { encoding: n.encoding || "utf8", quiet: n.quiet, debug: n.debug === true, override: n.override === true, fast: n.fast === true, paths: [".env"], defaultPath: true };
-      return n.path != null && (t.paths = [n.path], t.defaultPath = false), e.pathSet && (t.paths = e.paths, t.defaultPath = false), e.quiet != null && (t.quiet = e.quiet), e.debug != null && (t.debug = e.debug), e.override != null && (t.override = e.override), e.fast != null && (t.fast = e.fast), t;
+      return n.path && (t.paths = [n.path], t.defaultPath = false), e.pathSet && (t.paths = e.paths, t.defaultPath = false), e.quiet != null && (t.quiet = e.quiet), e.debug != null && (t.debug = e.debug), e.override != null && (t.override = e.override), e.fast != null && (t.fast = e.fast), t;
     }
     function be(e) {
       let n = {}, t = [], o = { override: e.override, debug: e.debug };
@@ -7504,6 +7504,22 @@ var typedOperations = {
     kind: "mutation",
     invoke: (client, input) => client.team.updateRoutingGroupRelease.mutate(input)
   },
+  "team.previewRoutingGroupStagger": {
+    kind: "query",
+    invoke: (client, input) => client.team.previewRoutingGroupStagger.query(input)
+  },
+  "team.applyRoutingGroupStagger": {
+    kind: "mutation",
+    invoke: (client, input) => client.team.applyRoutingGroupStagger.mutate(input)
+  },
+  "team.updateTeamRelease": {
+    kind: "mutation",
+    invoke: (client, input) => client.team.updateTeamRelease.mutate(input)
+  },
+  "team.listTeamReleaseHistory": {
+    kind: "query",
+    invoke: (client, input) => client.team.listTeamReleaseHistory.query(input)
+  },
   "team.createRoutingGroup": {
     kind: "mutation",
     invoke: (client, input) => client.team.createRoutingGroup.mutate(input)
@@ -7728,6 +7744,10 @@ var typedOperations = {
     kind: "query",
     invoke: (client, input) => client.event.getPlayerStation.query(input)
   },
+  "event.getPlayerStationPresence": {
+    kind: "query",
+    invoke: (client, input) => client.event.getPlayerStationPresence.query(input)
+  },
   "event.listJoined": {
     kind: "query",
     invoke: (client, input) => client.event.listJoined.query(input)
@@ -7985,6 +8005,8 @@ var defaultMutationTargetKeys = [
 ];
 var mutationTargetKeys = {
   "team.updateRoutingGroupRelease": ["groupId", "eventId"],
+  "team.updateTeamRelease": ["teamId", "eventId"],
+  "team.applyRoutingGroupStagger": ["groupId", "eventId"],
   "team.setGameplaySettings": ["eventId"],
   "event.updateSurveySettings": ["eventId"],
   "team.createRoutingGroup": ["eventId"],
@@ -8091,8 +8113,8 @@ var commands = [
   mutation(["station", "clone"], "event.cloneStation", "Clone a station and its missions.", ["state-change"]),
   mutation(["station", "archive"], "event.archiveStation", "Archive a station.", ["state-change", "delete"]),
   mutation(["station", "reorder"], "event.reorderStations", "Reorder shared stations, or a selected team's station route when scopeTeamId is supplied.", ["state-change"]),
-  mutation(["mission", "create"], "event.createMission", "Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives). Optional revealMessage (up to 2,000 characters) is shown only after submitting.", ["state-change"]),
-  mutation(["mission", "update"], "event.updateMission", "Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.", ["state-change"]),
+  mutation(["mission", "create"], "event.createMission", "Create a mission in a station. Fill-in-the-blank inputs support correctAnswer and acceptedAnswers (up to 50 alternatives), or config.numberRange {min,max} to accept any number in that inclusive range instead. Optional revealMessage (up to 2,000 characters) is shown only after submitting.", ["state-change"]),
+  mutation(["mission", "update"], "event.updateMission", "Update a mission. Fill-in-the-blank inputs support acceptedAnswers; omit to preserve or pass [] to clear. Set config.numberRange {min,max} for a numeric range answer; omit config to preserve or pass null to return to text answers. Existing submissions are not re-graded. Edit revealMessage during live play; omit it to preserve or use an empty string to clear.", ["state-change"]),
   mutation(["mission", "archive"], "event.archiveMission", "Archive a mission.", ["state-change", "delete"]),
   mutation(["mission", "reorder"], "event.reorderMissions", "Reorder missions within a station.", ["state-change"]),
   query(["team", "list"], "team.list", "List teams and their current members."),
@@ -8109,10 +8131,14 @@ var commands = [
   mutation(["team", "set-play-mode"], "team.setPlayMode", "Change an event between individual and team play.", ["state-change"]),
   mutation(["team", "set-submission-access"], "team.setSubmissionAccess", "Change who can submit missions in team play.", ["state-change"]),
   mutation(["team", "set-station-routes"], "team.setStationRoutes", "Replace a team's linked station route and set its order.", ["state-change"]),
-  mutation(["event", "set-gameplay"], "team.setGameplaySettings", "Set open or sequential progression, group routing, and per-mission skipping before play starts.", ["state-change"]),
+  mutation(["event", "set-gameplay"], "team.setGameplaySettings", "Set open or sequential progression, group routing, and per-mission skipping before play starts. Station skipping and requireLocationOnSubmit stay editable live.", ["state-change"]),
   query(["routing-group", "list"], "team.listRoutingGroups", "List an event's routing groups, ordered stations, and assigned teams."),
   query(["routing-group", "release-history"], "team.listRoutingGroupReleaseHistory", "Show a routing group's five most recent release changes with actor, action and before/after UTC values."),
   mutation(["routing-group", "release"], "team.updateRoutingGroupRelease", "Schedule (future releaseAt ISO timestamp with offset), CLEAR schedule, HOLD, RELEASE_SCHEDULED_HOLD (keep schedule), or RELEASE_NOW for a routing group. After a group starts, only HOLD and RELEASE_SCHEDULED_HOLD are accepted. Requires launchEvent permission.", ["state-change"]),
+  query(["routing-group", "stagger-preview"], "team.previewRoutingGroupStagger", "Dry run: show each team's before/after start time for a routing-group STAGGER (firstReleaseAt + intervalMinutes in teamIds order), SHIFT (shiftMinutes, unstarted scheduled teams) or CLEAR (back to the group time). Writes nothing; returns blockers apply would refuse with."),
+  mutation(["routing-group", "stagger"], "team.applyRoutingGroupStagger", "Apply the same STAGGER, SHIFT or CLEAR input as stagger-preview in one transaction (all teams or none). Started teams are never rescheduled. Requires launchEvent permission; allowed while LIVE.", ["state-change"]),
+  mutation(["team", "release"], "team.updateTeamRelease", "Set one team's start inside its routing group: SCHEDULE (future releaseAt ISO timestamp with offset), CLEAR (use the group time), HOLD, RELEASE_HOLD, or RELEASE_NOW. A held group still holds every team. After a team starts, only HOLD and RELEASE_HOLD are accepted. Requires launchEvent permission.", ["state-change"]),
+  query(["team", "release-history"], "team.listTeamReleaseHistory", "Show a team's five most recent start-time changes with actor, action and before/after UTC values."),
   mutation(["routing-group", "create"], "team.createRoutingGroup", "Create a routing group within an event before play starts.", ["state-change"]),
   mutation(["routing-group", "rename"], "team.renameRoutingGroup", "Rename an event's routing group before play starts.", ["state-change"]),
   mutation(["routing-group", "delete"], "team.deleteRoutingGroup", "Delete an unassigned routing group before play starts.", ["state-change", "delete"]),
@@ -8172,6 +8198,7 @@ var commands = [
   query(["player", "map"], "event.getPlayerMap", "Get the player event map."),
   query(["player", "shell"], "event.getPlayerShell", "Get the player application shell."),
   query(["player", "station"], "event.getPlayerStation", "Get a playable station."),
+  query(["player", "station", "presence"], "event.getPlayerStationPresence", "Check whether a location is within a station's submit range when the event asks players to stay at the station to submit. Returns a state and rounded distance, never coordinates."),
   query(["player", "events"], "event.listJoined", "List events joined by the current user.", { input: "none" }),
   query(["player", "broadcasts"], "event.listPlayerBroadcasts", "List broadcasts visible to the current player."),
   query(["player", "broadcast"], "event.getPlayerBroadcast", "Get one broadcast visible to the current player."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/gosh",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "GOSH CLI for organizers and AI agents — manage organizations, events, teams, stations, missions, templates, and live operations through the GOSH API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "@trpc/client": "^11.19.0",
-    "dotenv": "^18.0.8",
+    "dotenv": "^18.0.9",
     "superjson": "^2.2.6"
   },
   "engines": {