devops-plugin-kit 0.1.0

package/@danieli-automation/devops-plugin-features/src/features/iterations/utils/iteration.ts

@@ -0,0 +1,132 @@
+import { TimeFrame } from "azure-devops-extension-api/Work";
+import type { IterationInfoType } from "../types/IterationInfoType.js";
+
+/**
+ * Formats an iteration into a short, human-readable label.
+ *
+ * Output format:
+ *   YYYY Mon (DD-DD)
+ * Example:
+ *   2025 Jan (01-14)
+ *
+ * Notes:
+ * - Dates are interpreted and formatted in UTC to avoid timezone-related shifts.
+ * - Returns an empty string if the iteration or its start/end dates are missing
+ *   or invalid.
+ *
+ * @param iter The iteration information to format.
+ * @returns A formatted iteration label or an empty string if invalid.
+ */
+export function formatIteration(iter?: IterationInfoType | null) {
+    const start = toDate(iter?.startDate);
+    const end = toDate(iter?.finishDate);
+    if (!start || !end) return "";
+
+    const year = start.getUTCFullYear();
+    const month = start.toLocaleString("en-US", { month: "short", timeZone: "UTC" });
+    const pad = (n: number) => n.toString().padStart(2, "0");
+
+    return `${year} ${month} (${pad(start.getUTCDate())}-${pad(end.getUTCDate())})`;
+}
+
+/**
+ * Finds the first iteration path whose root segment matches
+ * the root segment of the given area path.
+ *
+ * Root segment definition:
+ * - The first path component before the `\` character.
+ *
+ * Example:
+ *   areaPath:        "Web\\Frontend"
+ *   iterationPaths:  ["Web\\Sprint 1", "Mobile\\Sprint 1"]
+ *   result:          "Web\\Sprint 1"
+ *
+ * @param iterationPaths A list of iteration paths to search within.
+ * @param areaPath       The area path used to determine the root segment.
+ * @returns The first matching iteration path, or `undefined` if none match.
+ */
+export function findByAreaRoot<T extends string>(iterationPaths?: T[] | null, areaPath?: string | null): T | undefined {
+    if (!iterationPaths?.length) return undefined;
+    if (!areaPath) return undefined;
+
+    const areaRoot = areaPath.split("\\")[0]?.trim().toLowerCase();
+    if (!areaRoot) return undefined;
+
+    return iterationPaths.find((p) => {
+        const root = p.split("\\")[0]?.trim().toLowerCase();
+        return root === areaRoot;
+    });
+}
+
+/**
+ * Resolves a stable string key for an iteration.
+ *
+ * Priority:
+ * 1. Iteration ID (most stable across renames)
+ * 2. Iteration path (fallback)
+ *
+ * This key is typically used for:
+ * - React Query cache keys
+ * - Memoization
+ * - Store indexing
+ *
+ * @param iteration The iteration to derive a key from.
+ * @returns A stable iteration key, or `null` if unavailable.
+ */
+export function getIterationKey(iteration?: IterationInfoType): string | null {
+    return iteration?.id ?? iteration?.path ?? null;
+}
+
+/**
+ * Builds a user-facing iteration title that includes:
+ * - Formatted date range (via `formatIteration`)
+ * - Time frame label (Past/Current/Future/Unknown)
+ *
+ * Example output:
+ *   " 2025 Jan (01-14) (Current)"
+ *
+ * @param iteration The iteration to build a display title for.
+ * @returns A formatted iteration title string.
+ */
+export function getFormattedIterationTitle(iteration: IterationInfoType) {
+    return `${formatIteration(iteration)} (${resolveIterationTimeFrame(iteration)})`;
+}
+
+//#region Private Functions
+/**
+ * Safely converts a date string into a `Date` object.
+ *
+ * @param v A date string value.
+ * @returns A valid `Date` object, or `undefined` if the value is null, undefined,
+ *          or cannot be parsed into a valid date.
+ */
+function toDate(v?: string | null): Date | undefined {
+    if (v == null) return undefined;
+    const date = new Date(v);
+    return isNaN(date.getTime()) ? undefined : date;
+}
+
+/**
+ * Converts an iteration's `TimeFrame` value into a user-friendly label.
+ *
+ * Notes:
+ * - Treats `undefined` the same as `Past` (common when the API omits the field).
+ * - Returns "Unknown" for unexpected enum values.
+ *
+ * @param iteration The iteration containing the `timeFrame` value.
+ * @returns The normalized time frame label ("Past", "Current", "Future", or "Unknown").
+ */
+function resolveIterationTimeFrame(iteration: IterationInfoType): string {
+    switch (iteration.timeFrame) {
+        case TimeFrame.Past:
+        case undefined:
+            return "Past";
+        case TimeFrame.Current:
+            return "Current";
+        case TimeFrame.Future:
+            return "Future";
+        default:
+            return "Unknown";
+    }
+}
+//#endregion

package/@danieli-automation/devops-plugin-features/src/features/teams/api/projects.ts

@@ -0,0 +1,79 @@
+import { TeamProjectReference, WebApiTeam } from "azure-devops-extension-api/Core";
+import { coreClient } from "core/azureClients";
+import { SelectedProjectType } from "features/teams/types/SelectedProjectType";
+
+type ListBoxItem = {
+    id?: string;
+    text?: string;
+    [key: string]: unknown;
+};
+
+/**
+ * Fetches all projects and maps them to IListBoxItem objects.
+ * 
+ * @description This function retrieves all projects using the Core REST client
+ * and maps them to an array of IListBoxItem for UI representation.
+ * 
+ * @returns An object containing an array of IListBoxItem and an array of TeamProjectReference
+ */
+export async function fetchProjects() {
+    const core = coreClient();
+    const projects: TeamProjectReference[] = await core.getProjects();
+    const projectItems = projects.map((project) => ({ text: project.name, id: project.id, })) as ListBoxItem[];
+    return { projectItems, projects };
+}
+
+/**
+ * Fetches a single project by its ID.
+ * @description This function retrieves a specific project using the Core REST client
+ * and returns its TeamProjectReference.
+ * 
+ * @param projectId - The unique identifier of the project to fetch
+ * @returns A promise resolving to the TeamProjectReference of the project, or null if not found
+ */
+export async function fetchProjectById(projectId: string): Promise<any | null> {
+    const core = coreClient();
+    const project = await core.getProject(projectId);
+    return project;
+}
+
+/**
+ * Fetches project and team IDs based on team project name, selected projects, and area path.
+ * 
+ * @param teamProjectName The name of the team project
+ * @param selectedProjects An array of selected projects
+ * @param areaPath The area path within the project
+ * @returns Promise resolving to an object containing projectId and teamId
+ * 
+ */
+export async function getProjectAndTeamIds(teamProjectName: string, selectedProjects: SelectedProjectType[], areaPath?: string) {
+    const core = coreClient();
+
+    const project = await core.getProject(teamProjectName);
+    const projectId = project.id;
+
+    const parts = (areaPath ?? "").split("\\");
+    const candidateTeamName = parts.length > 1 ? parts[1] : undefined;
+    const teams: WebApiTeam[] = await core.getTeams(projectId, undefined, 200, 0);
+
+    teams.filter(t => {
+        return selectedProjects.some(p => {
+            return p.teamId === t.id;
+        });
+    });
+
+    let team = (candidateTeamName && teams.find(t => t.name?.toLowerCase() === candidateTeamName.toLowerCase())) ||
+        (teams as any[]).find(t => t.isDefault) ||
+        teams[0];
+
+    if (!team?.id) {
+        throw new Error(`No team found in project ${project.name}`);
+    }
+
+    return {
+        projectId,
+        teamId: team.id,
+        projectName: project.name,
+        teamName: team.name,
+    };
+}

package/@danieli-automation/devops-plugin-features/src/features/teams/api/teams.ts

@@ -0,0 +1,29 @@
+import { coreClient } from "core/azureClients";
+
+/**
+ * Fetches teams for a given project.
+ * @description This function retrieves all teams within the specified project
+ * using the Core REST client and maps them to IListBoxItem format.
+ * 
+ * @param projectId - The ID of the project to fetch teams for
+ * @returns  - A promise resolving to an array of teams in IListBoxItem format
+ */
+export async function fetchTeams(projectId: string): Promise<any[]> {
+    const core = coreClient();
+    const teams = await core.getTeams(projectId);
+    return teams.map((team) => ({ text: team.name, id: team.id }));
+}
+
+/**
+ * Fetches a team by its ID within a project.
+ * @description This function retrieves a specific team using the Core REST client
+ * and returns its details.
+ * 
+ * @param projectId - Project ID
+ * @param teamId - Team ID
+ * @returns - A promise resolving to the team details
+ */
+export function fetchTeamById(projectId: string, teamId: string): Promise<any> {
+    const core = coreClient();
+    return core.getTeam(projectId, teamId);
+}

package/@danieli-automation/devops-plugin-features/src/features/teams/api/users.ts

@@ -0,0 +1,124 @@
+import { GraphMember } from "azure-devops-extension-api/Graph";
+import { AvatarSize } from "azure-devops-extension-api/Profile/Profile";
+import { coreClient, graphClient } from "core/azureClients";
+import { SelectedProjectType } from "features/teams/types/SelectedProjectType";
+import { UserSearchResultType } from "features/teams/types/UserSearchResultType";
+import { getProjectAndTeamIds } from "./projects.js";
+
+/**
+ * Fetches current team members for a given team project and selected projects.
+ * 
+ * @param teamProjectName 
+ * @param selectedProjects 
+ * @param areaPath 
+ * @returns Promise resolving to an array of team member information
+ * 
+ */
+export async function getCurrentTeamMembers(teamProjectName: string, selectedProjects: SelectedProjectType[], areaPath?: string) {
+    const core = coreClient();
+    const ids = await getProjectAndTeamIds(teamProjectName, selectedProjects, areaPath);
+    let members = await core.getTeamMembersWithExtendedProperties(ids.projectId, ids.teamId);
+
+    /*if (!isAdminIncluded) {
+        members = members.filter(m => !m.isTeamAdmin);
+    }*/
+
+    return members.map(m => ({
+        descriptor: m.identity?.descriptor,
+        displayName: m.identity?.displayName ?? "",
+        uniqueName: m.identity?.uniqueName,
+        imageUrl: m.identity?.imageUrl,
+    }));
+}
+
+/**
+ * Fetches the avatar image for a given Azure DevOps user.
+ *
+ * Retrieves the user's avatar using their graph descriptor and
+ * allows specifying the desired avatar size.
+ *
+ * @param descriptor Azure DevOps graph descriptor of the user.
+ * @param size Optional avatar size (defaults to small).
+ * @returns Promise resolving to the user's avatar image.
+ */
+export async function getDefaultUserAvatar(descriptor?: string, size = AvatarSize.Small as AvatarSize) {
+    if (!descriptor) return;
+    return await graphClient().getAvatar(descriptor, size);
+}
+
+/**
+ * Searches users across the whole organization for typeahead scenarios.
+ *
+ * Uses Graph client `querySubjects` with `subjectKind: ["User"]`.
+ * Azure DevOps Graph currently returns results in batches (typically up to 100).
+ * 
+ * @param query searched value
+ * @param maxResults desired max result constant
+ * @returns Promise resolving to an object containing user fields
+ */
+export async function searchUsersInOrganization(query: string, maxResults = 100): Promise<UserSearchResultType[]> {
+    const term = query.trim();
+    if (!term) return [];
+
+    const subjects = await graphClient().querySubjects({
+        query: term,
+        subjectKind: ["User"],
+        scopeDescriptor: undefined as unknown as string,
+    });
+
+    return (subjects as GraphMember[])
+        .filter(subject => (subject.subjectKind || "").toLowerCase() === "user")
+        .slice(0, maxResults)
+        .map(subject => ({
+            id: subject.descriptor,
+            descriptor: subject.descriptor,
+            displayName: subject.displayName || "",
+            uniqueName: subject.principalName || undefined,
+            mailAddress: subject.mailAddress || undefined,
+            origin: subject.origin || undefined,
+            originId: subject.originId || undefined,
+        }));
+}
+
+/**
+ * Resolves user ids/descriptors to user profiles for display purposes.
+ *
+ * This is used when persisted owner ids are already known, but we need
+ * display names for UI rendering.
+ * 
+ * @params userIds list of user ids to get details
+ * @returns Promise resolving to an object containing user details
+ */
+export async function getUsersByIds(userIds: string[]): Promise<UserSearchResultType[]> {
+    const ids = Array.from(new Set((userIds ?? []).map(id => (id || "").trim()).filter(Boolean)));
+    if (ids.length === 0) return [];
+
+    const graph = graphClient();
+
+    const resolved = await Promise.all(ids.map(async (userId) => {
+        let subject: GraphMember | undefined;
+
+        // Case 1: id is already a graph descriptor.
+        try {
+            const byDescriptor = await graph.getUser(userId) as GraphMember;
+            if ((byDescriptor?.subjectKind || "").toLowerCase() === "user") {
+                subject = byDescriptor;
+            }
+        } catch {
+            // noop
+        }
+
+        if (!subject) return undefined;
+
+        return {
+            id: subject.descriptor,
+            descriptor: subject.descriptor,
+            displayName: subject.displayName || userId,
+            uniqueName: subject.principalName || undefined,
+            mailAddress: subject.mailAddress || undefined,
+            origin: subject.origin || undefined,
+        } as UserSearchResultType;
+    }));
+
+    return resolved.filter(Boolean) as UserSearchResultType[];
+}

package/@danieli-automation/devops-plugin-features/src/features/teams/services/ProjectService.ts

@@ -0,0 +1,80 @@
+import { workClient } from "core/azureClients";
+import { fetchProjectById } from "features/teams/api/projects";
+import { SelectedProjectType } from "features/teams/types/SelectedProjectType";
+import { fetchTeamById } from "../api/teams.js";
+
+export type AreaGroup = {
+    projectId: string;
+    projectName: string;
+    teamId: string;
+    teamName?: string;
+    areaPaths: string[];
+};
+
+const areaPathCache = new Map<string, AreaGroup>();
+
+export const ProjectService = {
+    getAreaPaths: async (projectTeamPairs?: SelectedProjectType[]): Promise<AreaGroup[]> => {
+        if (!projectTeamPairs || projectTeamPairs.length === 0) return [];
+
+        const results = await Promise.all(
+            projectTeamPairs.map(async (pair) => {
+
+                const { projectId, teamId } = pair;
+
+                const cacheKey = `${projectId}:${teamId}`;
+
+                const cached = areaPathCache.get(cacheKey);
+
+                if (cached) return cached;
+
+                try {
+                    const [project, team] = await Promise.all([fetchProjectById(projectId), fetchTeamById(projectId, teamId)]);
+                    const teamName = team?.name ?? "";
+
+                    const teamContext = {
+                        project: project?.name ?? "",
+                        projectId,
+                        team: teamName,
+                        teamId,
+                    };
+
+                    const teamFieldValues = await workClient().getTeamFieldValues(teamContext);
+
+                    const collected: string[] = [];
+
+                    if (Array.isArray(teamFieldValues?.values)) {
+                        for (const v of teamFieldValues.values) {
+                            if (!v?.value) continue;
+                            collected.push(v.value);
+                        }
+                    }
+
+                    if (collected.length === 0) {
+                        console.warn("[getAreaPaths] Team has no area paths configured");
+                    }
+
+                    const projectName = project?.name ?? "";
+
+                    const clean = Array.from(new Set(collected.filter(p => typeof p === "string" && p.length > 0)
+                        .map(p => p.replace(/[\u0000-\u001F\u007F-\u009F]/g, "").trim()))
+                    );
+
+                    const specificAreaPaths = clean.filter(p => p === projectName || p.startsWith(projectName + "\\"));
+
+                    const result = { projectId, projectName, teamId, teamName, areaPaths: specificAreaPaths } as AreaGroup;
+                    areaPathCache.set(cacheKey, result);
+                    return result;
+
+                } catch (err) {
+                    //console.error("[getAreaPaths] Failed to fetch area paths");
+
+                    const result = { projectId, projectName: "", teamId, teamName: undefined, areaPaths: [] } as AreaGroup;
+                    areaPathCache.set(cacheKey, result);
+                    return result;
+                }
+            })
+        );
+        return results;
+    },
+};

package/@danieli-automation/devops-plugin-features/src/features/teams/types/SelectedProjectType.ts

@@ -0,0 +1,8 @@
+export type SelectedProjectType = {
+    projectId: string;
+    projectName?: string;
+    teamName?: string;
+    teamId: string;
+    teams?: any[],
+    selectedTeamKey?: string,
+};

package/@danieli-automation/devops-plugin-features/src/features/teams/types/TeamMemberType.ts

@@ -0,0 +1,7 @@
+export type TeamMember = {
+    id: string;
+    descriptor?: string;
+    displayName: string;
+    uniqueName: string;
+    imageUrl?: string;
+};

package/@danieli-automation/devops-plugin-features/src/features/teams/types/TeamRowSeedType.ts

@@ -0,0 +1,6 @@
+export type TeamRowSeedType = {
+    projectId?: string;
+    projectName?: string;
+    teamId?: string;
+    teamName?: string;
+};

package/@danieli-automation/devops-plugin-features/src/features/teams/types/UserSearchResultType.ts

@@ -0,0 +1,8 @@
+export type UserSearchResultType = {
+    id: string;
+    descriptor: string;
+    displayName: string;
+    uniqueName?: string;
+    mailAddress?: string;
+    origin?: string;
+}

package/@danieli-automation/devops-plugin-features/src/features/work-items/api/states.ts

@@ -0,0 +1,24 @@
+import { getClient } from "azure-devops-extension-api";
+import { WorkItemTrackingRestClient } from "azure-devops-extension-api/WorkItemTracking";
+
+/**
+ * Fetches the work item states for a given work item type within a project.
+ * @description This function uses the Work Item Tracking REST client to retrieve
+ * the states associated with the specified work item type in the given project.
+ * 
+ * @param projectName - The name of the project
+ * @param workItemType - The work item type (e.g., 'Task', 'Bug')
+ * @returns - A promise resolving to an array of work item states for the specified type
+ */
+export async function getWorkItemStates(projectName: string, workItemType: string) {
+    const witClient = getClient(WorkItemTrackingRestClient);
+    const typeInfo = await witClient.getWorkItemType(projectName, workItemType);
+
+    // Map to a clean array for dropdowns
+    return typeInfo.states.map((s) => ({
+        id: s.name,
+        text: s.name,
+        color: s.color,
+        category: s.category
+    }));
+}

package/@danieli-automation/devops-plugin-features/src/features/work-items/api/wiql.ts

@@ -0,0 +1,146 @@
+/**
+ * Fetches child work items for a given parent work item within a project.
+ * 
+ * @param pbiIds - Array of parent work item IDs (PBIs or Bugs)
+ * @returns WIQL string to fetch child work items
+ * 
+ */
+export function wiqlForParentWorkItems(pbiIds: number[]) {
+    if (pbiIds.length === 0) return null;
+
+    const idsClause = pbiIds.length === 1 ? `[Target].[System.Id] = ${pbiIds[0]}` : `[Target].[System.Id] IN (${pbiIds.join(',')})`;
+
+    const wiql = `
+        SELECT [Source].[System.Id]
+        FROM WorkItemLinks
+        WHERE
+        (
+            [Source].[System.WorkItemType] IN ('Epic','Feature')
+            AND [Source].[System.State] <> 'Removed'
+        )
+        AND ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward')
+        AND (
+            [Target].[System.WorkItemType] IN ('Product Backlog Item','Bug')
+            AND [Target].[System.State] <> 'Removed'
+            AND ${idsClause}
+        )
+        MODE (Recursive) `;
+
+    return wiql;
+}
+
+/**
+ * @description: Generates WIQL queries to fetch PBIs/Bugs and Tasks that belong to a single iteration,
+ * and optionally restricted to one or more area path roots (UNDER clauses).
+ * @param iterationPath The selected iteration path (e.g. "Project\\2026\\Sprint 02").
+ * @param areaPaths Optional list of area paths to scope results (uses UNDER).
+ * @returns An object containing WIQL strings for parent items and tasks.
+ */
+export function wiqlForSingleIteration(iterationPath: string, areaPaths?: (string | null)[]) {
+    const safeAreaPaths = (areaPaths ?? []).filter((p): p is string => typeof p === "string" && p.length > 0);
+
+    const areaClause = safeAreaPaths.length
+        ? `AND (${safeAreaPaths.map(p => `[System.AreaPath] UNDER '${escapeWiqlString(p)}'`).join(" OR ")})`
+        : "";
+
+    const iterClause = `[System.IterationPath] = '${escapeWiqlString(sanitizeForWiql(iterationPath))}'`;
+
+    const parentsQuery = `
+    SELECT [System.Id]
+    FROM WorkItems
+    WHERE
+      [System.WorkItemType] IN ('Product Backlog Item','Bug')
+      AND [System.State] <> 'Removed'
+      AND ${iterClause}
+      ${areaClause}
+  `;
+
+    const tasksQuery = `
+    SELECT [System.Id]
+    FROM WorkItems
+    WHERE
+      [System.WorkItemType] = 'Task'
+      AND [System.State] <> 'Removed'
+      AND ${iterClause}
+      ${areaClause}
+  `;
+
+    return { parentsQuery, tasksQuery };
+}
+
+/**
+ * @description: Generates WIQL queries to fetch PBIs/Bugs and Tasks that belong to multiple iterations,
+ * optionally restricted to one or more area path roots (UNDER clauses).
+ * @param iterationPaths The selected iteration paths.
+ * @param areaPaths Optional list of area paths to scope results (uses UNDER).
+ * @returns An object containing WIQL strings for parent items and tasks.
+ */
+export function wiqlForMultipleIterations(iterationPaths: string[], areaPaths?: (string | null)[]) {
+    const safeAreaPaths = (areaPaths ?? []).filter((p): p is string => typeof p === "string" && p.length > 0);
+
+    const areaClause = safeAreaPaths.length
+        ? `AND (${safeAreaPaths.map(p => `[System.AreaPath] UNDER '${escapeWiqlString(p)}'`).join(" OR ")})`
+        : "";
+
+    const iterClause = iterationPaths && iterationPaths.length
+        ? buildUnderOrClause('[System.IterationPath]', iterationPaths)
+        : "";
+
+    const parentsQuery = `
+    SELECT [System.Id]
+    FROM WorkItems
+    WHERE
+      [System.WorkItemType] IN ('Product Backlog Item','Bug')
+      AND [System.State] <> 'Removed'
+      ${iterClause ? 'AND ' + iterClause : ''}
+      ${areaClause}
+  `;
+
+    const tasksQuery = `
+    SELECT [System.Id]
+    FROM WorkItems
+    WHERE
+      [System.WorkItemType] = 'Task'
+      AND [System.State] <> 'Removed'
+      ${iterClause ? 'AND ' + iterClause : ''}
+      ${areaClause}
+  `;
+
+    return { parentsQuery, tasksQuery };
+}
+
+//#region Private Functions
+/**
+ * Builds a WIQL clause joining multiple `UNDER` path checks with `OR`.
+ *
+ * @param field WIQL field name (e.g. `[System.IterationPath]`).
+ * @param paths Path list to include.
+ * @returns A WIQL condition string, or empty string when no paths are provided.
+ */
+function buildUnderOrClause(field: string, paths?: string[]) {
+    if (!paths || paths.length === 0) return '';
+    const cleanPaths = paths.map(p => escapeWiqlString(sanitizeForWiql(p)));
+    if (cleanPaths.length === 1) return `${field} UNDER '${cleanPaths[0]}'`;
+    return '(' + cleanPaths.map(p => `${field} UNDER '${p}'`).join(' OR ') + ')';
+}
+
+/**
+ * Escapes string values for safe embedding in WIQL string literals.
+ *
+ * @param str Raw string value.
+ * @returns Escaped WIQL-safe string.
+ */
+function escapeWiqlString(str: string) {
+    return str.replace(/'/g, "''").replace(/\\/g, '\\\\');
+}
+
+/**
+ * Removes control characters and trims whitespace before WIQL interpolation.
+ *
+ * @param s Raw input string.
+ * @returns Sanitized string suitable for WIQL.
+ */
+function sanitizeForWiql(s: string) {
+    return s ? s.replace(/[\u0000-\u001F\u007F-\u009F]/g, '').trim() : s;
+}
+//#endregion