All files / src/entities/milestones schema.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
17x
17x
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17x
 
 
 
 
 
 
17x
 
 
 
 
17x
 
 
 
 
 
 
 
 
 
17x
 
 
 
 
 
 
 
 
 
1x
 
 
 
 
 
 
17x
 
 
 
 
 
 
17x
 
 
 
 
 
 
17x
 
 
 
 
 
 
 
 
 
 
 
 
import { z } from "zod";
import { requiredId } from "../utils";
 
// ============================================================================
// manage_milestone - CQRS Command Tool (discriminated union schema)
// Actions: create, update, delete, promote
//
// Uses z.discriminatedUnion() to define action-specific parameters.
// Benefits:
// - Each action has ONLY its relevant parameters (token savings)
// - TypeScript type narrowing in handlers
// - Filtering denied actions removes their exclusive parameters from schema
// - JSON Schema outputs oneOf which is flattened for AI clients at runtime
// ============================================================================
 
// --- Base fields shared by all actions ---
const namespaceField = z.string().describe("Namespace path (group or project)");
 
// NOTE on milestone_id:
// GitLab Milestones REST API uses the global ID in URL paths, NOT the IID.
// Example: PUT /projects/:id/milestones/:milestone_id where :milestone_id is the global ID.
// The API response contains both 'id' (global unique) and 'iid' (project-scoped).
// Unlike issues/MRs which use IID in URLs, milestones use the global ID.
const milestoneIdField = requiredId.describe(
  "The ID of a project or group milestone. Required for 'update', 'delete', 'promote' action(s)."
);
 
// --- Create action: creates a new milestone ---
const CreateMilestoneSchema = z.object({
  action: z.literal("create"),
  namespace: namespaceField,
  title: z.string().describe("The title of the milestone"),
  description: z.string().optional().describe("The description of the milestone"),
  due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
  start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
});
 
// --- Update action: modifies an existing milestone ---
const UpdateMilestoneSchema = z.object({
  action: z.literal("update"),
  namespace: namespaceField,
  milestone_id: milestoneIdField,
  title: z.string().optional().describe("The new title of the milestone"),
  description: z.string().optional().describe("The new description of the milestone"),
  due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
  start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
  state_event: z
    .string()
    .transform(val => val.toLowerCase())
    .pipe(z.enum(["close", "activate"]))
    .optional()
    .describe("State event to apply: 'close' or 'activate'"),
});
 
// --- Delete action: removes a milestone ---
const DeleteMilestoneSchema = z.object({
  action: z.literal("delete"),
  namespace: namespaceField,
  milestone_id: milestoneIdField,
});
 
// --- Promote action: elevates project milestone to group level ---
const PromoteMilestoneSchema = z.object({
  action: z.literal("promote"),
  namespace: namespaceField,
  milestone_id: milestoneIdField,
});
 
// --- Discriminated union combining all actions ---
export const ManageMilestoneSchema = z.discriminatedUnion("action", [
  CreateMilestoneSchema,
  UpdateMilestoneSchema,
  DeleteMilestoneSchema,
  PromoteMilestoneSchema,
]);
 
// ============================================================================
// Type exports
// ============================================================================
 
export type ManageMilestoneInput = z.infer<typeof ManageMilestoneSchema>;