feat(api): POST /api/turn ticks the queue one turn; an empty queue is a free skip (#44)

lib/openapi.test.ts

@@ -20,6 +20,7 @@ describe('OpenAPI spec', () => {
       '/api/ship/upgrade',
       '/api/system',
       '/api/tech',
+      '/api/turn',
       '/api/version',
       '/api/world',
     ]);
@@ -171,6 +172,25 @@ describe('OpenAPI spec', () => {
     expect((jumpReq.properties.helperCrewIds as { items: { type: string } }).items.type).toBe('integer');
   });
 
+  it('describes the turn endpoint: POST /api/turn with no body → WorldState + tasks, 500 on internal error', () => {
+    const post = openApiSpec.paths['/api/turn'].post;
+    expect(post).not.toHaveProperty('requestBody');
+    expect(post.responses[200].content['application/json'].schema.$ref).toBe('#/components/schemas/TurnResult');
+    expect(post.responses[500].content['application/json'].schema.$ref).toBe('#/components/schemas/Error');
+
+    // TurnResult extends WorldState with the task queue after the tick.
+    const turnResult = openApiSpec.components.schemas.TurnResult as { allOf: unknown[] };
+    expect((turnResult.allOf[0] as { $ref: string }).$ref).toBe('#/components/schemas/WorldState');
+    const extra = (turnResult.allOf[1] as { properties: Record<string, unknown> }).properties;
+    expect(Object.keys(extra)).toEqual(['tasks']);
+
+    const props = openApiSpec.components.schemas.Task.properties;
+    expect(Object.keys(props)).toEqual(['id', 'saveId', 'type', 'payload', 'leadCrewId', 'helpers', 'duration', 'remaining', 'status', 'queuedAtTurn']);
+    expect((props.type as { enum: string[] }).enum).toEqual(['JUMP', 'EXPLORE', 'SHIP_UPGRADE', 'SHIP_EXPAND', 'SHIP_BUILD', 'RESEARCH']);
+    expect((props.status as { enum: string[] }).enum).toEqual(['ACTIVE', 'PENDING', 'DONE']);
+    expect((props.helpers as { items: { type: string } }).items.type).toBe('integer');
+  });
+
   it('keeps info.version in sync with package.json', () => {
     expect(openApiSpec.info.title).toBe('SpaceWanderer API');
     expect(openApiSpec.info.version).toBe(pkg.version);