update_version_milestone

Instructions

Implementation Reference

• src/tools/updateVersionMilestone.ts:58-93 (handler)

  The handler function for the update_version_milestone tool. It resolves project ID or key, then calls backlog.patchVersions() to update a version milestone.

  export const updateVersionMilestoneTool = (
    backlog: Backlog,
    { t }: TranslationHelper
  ): ToolDefinition<
    ReturnType<typeof updateVersionMilestoneSchema>,
    (typeof VersionSchema)['shape']
  > => {
    return {
      name: 'update_version_milestone',
      description: t(
        'TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION',
        'Updates an existing version milestone'
      ),
      schema: z.object(updateVersionMilestoneSchema(t)),
      outputSchema: VersionSchema,
      importantFields: [
        'id',
        'name',
        'description',
        'startDate',
        'releaseDueDate',
        'archived',
      ],
      handler: async ({ projectId, projectKey, id, ...params }) => {
        const result = resolveIdOrKey(
          'project',
          { id: projectId, key: projectKey },
          t
        );
        if (!result.ok) {
          throw result.error;
        }
        return backlog.patchVersions(result.value, id, params);
      },
    };
  };

• src/tools/updateVersionMilestone.ts:8-56 (schema)

  Zod schema defining the input parameters for the update_version_milestone tool: projectId, projectKey, id, name, description, startDate, releaseDueDate, archived.

  const updateVersionMilestoneSchema = buildToolSchema((t) => ({
    projectId: z
      .number()
      .optional()
      .describe(
        t(
          'TOOL_UPDATE_VERSION_MILESTONE_PROJECT_ID',
          'The numeric ID of the project (e.g., 12345)'
        )
      ),
    projectKey: z
      .string()
      .optional()
      .describe(
        t(
          'TOOL_UPDATE_VERSION_MILESTONE_PROJECT_KEY',
          "The key of the project (e.g., 'PROJECT')"
        )
      ),
    id: z.number().describe(t('TOOL_UPDATE_VERSION_MILESTONE_ID', 'Version ID')),
    name: z
      .string()
      .describe(t('TOOL_UPDATE_VERSION_MILESTONE_NAME', 'Version name')),
    description: z
      .string()
      .optional()
      .describe(
        t('TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION', 'Version description')
      ),
    startDate: z
      .string()
      .optional()
      .describe(t('TOOL_UPDATE_VERSION_MILESTONE_START_DATE', 'Start date')),
    releaseDueDate: z
      .string()
      .optional()
      .describe(
        t('TOOL_UPDATE_VERSION_MILESTONE_RELEASE_DUE_DATE', 'Release due date')
      ),
    archived: z
      .boolean()
      .optional()
      .describe(
        t(
          'TOOL_UPDATE_VERSION_MILESTONE_ARCHIVED',
          'Archive status of the version'
        )
      ),
  }));

• src/tools/tools.ts:121-122 (registration)

  Registration of the update_version_milestone tool in the 'issue' toolset within the allTools collection.

  updateVersionMilestoneTool(backlog, helper),
  deleteVersionTool(backlog, helper),

• src/types/zod/backlogOutputDefinition.ts:158-167 (schema)

  VersionSchema defines the output shape returned by the update_version_milestone tool.

  export const VersionSchema = z.object({
    id: z.number(),
    projectId: z.number(),
    name: z.string(),
    description: z.string().optional(),
    startDate: z.string().optional(),
    releaseDueDate: z.string().optional(),
    archived: z.boolean(),
    displayOrder: z.number(),
  });

• src/utils/resolveIdOrKey.ts:22-65 (helper)

  Helper used by the handler to resolve project identification (by ID or key). The handler calls resolveIdOrKey('project', ...) to get the project identifier before calling patchVersions.

  function resolveIdOrField<E extends EntityName, F extends string>(
    entity: E,
    fieldName: F,
    values: ResolveIdOrFieldInput<F>,
    t: TranslationHelper['t']
  ): ResolveResult {
    const value = tryResolveIdOrField(fieldName, values);
    if (value === undefined) {
      return {
        ok: false,
        error: new Error(
          t(
            `${entity.toUpperCase()}_ID_OR_${fieldName.toUpperCase()}_REQUIRED`,
            `${capitalize(entity)} ID or ${fieldName} is required`
          )
        ),
      };
    }
  
    return { ok: true, value };
  }
  
  function tryResolveIdOrField<F extends string>(
    fieldName: F,
    values: ResolveIdOrFieldInput<F>
  ): string | number | undefined {
    return values.id !== undefined ? values.id : values[fieldName];
  }
  
  export const resolveIdOrKey = <E extends EntityName>(
    entity: E,
    values: { id?: number; key?: string },
    t: TranslationHelper['t']
  ): ResolveResult => resolveIdOrField(entity, 'key', values, t);
  
  export const resolveIdOrName = <E extends EntityName>(
    entity: E,
    values: { id?: number; name?: string },
    t: TranslationHelper['t']
  ): ResolveResult => resolveIdOrField(entity, 'name', values, t);
  
  function capitalize(str: string): string {
    return str.charAt(0).toUpperCase() + str.slice(1);
  }