devops-plugin-kit 0.1.0

package/@danieli-automation/create-devops-plugin/src/template/files/webpackCommonConfig.ts

@@ -0,0 +1,116 @@
+/**
+ * Generates the shared webpack config template entry.
+ */
+export function webpackCommonConfigFile(): [string, string] {
+  return [
+    "config/webpack/common.cjs",
+    `const path = require("path");
+     const webpack = require("webpack");
+     const CopyWebpackPlugin = require("copy-webpack-plugin");
+     const ReactRefreshWebpackPlugin = require("@pmmmwh/react-refresh-webpack-plugin");
+     const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+     const ReactRefreshTypeScript = require("react-refresh-typescript").default;
+     const TsconfigPathsPlugin = require("tsconfig-paths-webpack-plugin");
+     const dotenv = require("dotenv");
+
+  dotenv.config({ path: path.resolve(__dirname, "../../.env") });
+
+  function createCommonConfig({ env, name, entry, outputPath, publicPath, copyPatterns, withDevServer }) {
+    const isServe = !!(process.env.WEBPACK_SERVE || process.env.WEBPACK_DEV_SERVER);
+    const resolvedEnv = env || process.env.ENV || (isServe ? "dev" : "prod");
+    const isDev = resolvedEnv === "dev" && isServe;
+    const port = Number(process.env.PORT || 8080);
+
+    const config = {
+      name,
+      target: "web",
+      entry,
+      output: {
+        filename: "[name].js",
+        path: outputPath,
+        publicPath,
+        clean: false
+      },
+      mode: isDev ? "development" : "production",
+      devtool: isDev ? "inline-source-map" : "source-map",
+      resolve: {
+        extensions: [".ts", ".tsx", ".js", ".json"],
+        plugins: [
+          new TsconfigPathsPlugin({
+            configFile: path.resolve(__dirname, "../../tsconfig.json")
+          })
+        ]
+      },
+      module: {
+        rules: [
+          {
+            test: /\\.tsx?$/,
+            exclude: /node_modules/,
+            use: [
+              {
+                loader: "ts-loader",
+                options: {
+                  transpileOnly: true,
+                  getCustomTransformers: () => ({
+                    before: isDev ? [ReactRefreshTypeScript()] : []
+                  })
+                }
+              }
+            ]
+          },
+          { test: /\\.css$/, use: ["style-loader", "css-loader"] },
+          { test: /\\.scss$/, use: ["style-loader", "css-loader", "sass-loader"], exclude: /node_modules/ },
+          { test: /\\.svg$/i, type: "asset/inline" },
+          {
+            test: /\\.(woff2?|eot|ttf|otf)$/i,
+            type: "asset/resource",
+            generator: { filename: "static/fonts/[name][ext]" }
+          },
+          {
+            test: /\\.(png|jpe?g|gif|webp)$/i,
+            type: "asset/resource",
+            generator: { filename: "static/images/[name][ext]" }
+          }
+        ]
+      },
+      plugins: [
+        new webpack.EnvironmentPlugin({
+          ENV: resolvedEnv,
+          HMR: isServe ? "true" : "false",
+          PORT: String(port),
+          SCOPE: process.env.SCOPE || "User"
+        }),
+        new CopyWebpackPlugin({ patterns: copyPatterns }),
+        ...(isDev ? [new ReactRefreshWebpackPlugin({ overlay: false })] : []),
+        ...(isDev ? [new ForkTsCheckerWebpackPlugin({ async: true })] : [])
+      ]
+    };
+
+    if (withDevServer) {
+      config.devServer = {
+        server: { type: "https" },
+        hot: true,
+        liveReload: false,
+        static: { directory: path.resolve(__dirname, "../../dist") },
+        port,
+        open: true,
+        historyApiFallback: { index: "/app/App.html" },
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+          "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
+        },
+        client: {
+          overlay: { errors: true, warnings: false },
+          webSocketURL: { protocol: "wss", hostname: "localhost", port }
+        }
+      };
+    }
+
+    return config;
+  }
+
+module.exports = { createCommonConfig };
+`
+  ];
+}

package/@danieli-automation/create-devops-plugin/src/template/files/webpackConfig.ts

@@ -0,0 +1,15 @@
+/**
+ * Generates the webpack root config template entry.
+ */
+export function webpackConfigFile(): [string, string] {
+  return [
+    "webpack.config.cjs",
+    `const { createAppConfig } = require("./config/webpack/app.cjs");
+
+module.exports = (env = {}) => {
+  const configEnv = env.ENV || process.env.ENV;
+  return [createAppConfig(configEnv)];
+};
+`
+  ];
+}

package/@danieli-automation/create-devops-plugin/src/template/files.ts

@@ -0,0 +1 @@
+export { createTemplateFiles } from "./files/index.js";

package/@danieli-automation/create-devops-plugin/src/template/fs.ts

@@ -0,0 +1,85 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Ensures the target output directory exists and respects overwrite rules.
+ *
+ * @param outputDir - absolute path of the scaffold destination
+ * @param force - allows reuse of non-empty target directory when true
+ * @throws Error if the target directory is non-empty and force is false
+ */
+export async function ensureOutputDir(outputDir: string, force: boolean) {
+  try {
+    const entries = await fs.readdir(outputDir);
+    if (entries.length > 0 && !force) {
+      throw new Error(`Target directory is not empty: ${outputDir}`);
+    }
+  } catch (error: unknown) {
+    const code = (error as NodeJS.ErrnoException)?.code;
+    if (code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  await fs.mkdir(outputDir, { recursive: true });
+}
+
+/**
+ * Writes all generated template files into the target directory.
+ *
+ * @param outputDir - absolute project output directory
+ * @param files - map of relative file paths and file contents
+ * @throws Error if any file or intermediate directory cannot be created
+ */
+export async function writeFiles(outputDir: string, files: Map<string, string>) {
+  await Promise.all(
+    Array.from(files.entries()).map(async ([filePath, content]) => {
+      const fullPath = path.join(outputDir, filePath);
+      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs.writeFile(fullPath, content, "utf8");
+    })
+  );
+}
+
+/**
+ * Copies the static folder from the template to the target directory. It checks multiple candidate locations for the source static folder to ensure it can be found regardless of how the package is installed or executed.
+ *
+ * @param targetDir - target directory where the static folder should be copied
+ * @throws Error if the static source folder cannot be found in any of the expected locations
+ */
+export async function copyStaticFolder(targetDir: string) {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const sourceStaticDir = await resolveStaticSourceDir(moduleDir);
+  const destinationStaticDir = path.join(targetDir, "static");
+
+  await fs.mkdir(destinationStaticDir, { recursive: true });
+  await fs.cp(sourceStaticDir, destinationStaticDir, { recursive: true, force: true });
+}
+
+/**
+ * Resolves the static template source directory from known candidate paths.
+ *
+ * @param moduleDir - directory of the current module file
+ * @throws Error if no candidate static directory exists
+ */
+async function resolveStaticSourceDir(moduleDir: string) {
+  const candidates = [
+    path.resolve(moduleDir, "static"),
+    path.resolve(process.cwd(), "@danieli-automation/create-devops-plugin/dist/template/static"),
+    path.resolve(process.cwd(), "@danieli-automation/create-devops-plugin/src/template/static"),
+    path.resolve(process.cwd(), "dist/template/static"),
+    path.resolve(process.cwd(), "src/template/static")
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // try next candidate
+    }
+  }
+
+  throw new Error(`Static template folder not found. Checked: ${candidates.join(", ")}`);
+}

package/@danieli-automation/create-devops-plugin/src/template/manifest.ts

@@ -0,0 +1,40 @@
+import type { TemplateContext } from "./types.js";
+
+/**
+ * Creates production and development Azure DevOps manifest objects.
+ *
+ * @param context - normalized plugin metadata used for manifest generation
+ */
+export function createManifests(context: TemplateContext) {
+  const manifest = {
+    manifestVersion: 1,
+    id: context.extensionId,
+    publisher: context.publisher,
+    version: "0.0.1",
+    name: context.pluginName,
+    description: `${context.pluginName} Azure DevOps extension`,
+    public: false,
+    targets: [{ id: "Microsoft.VisualStudio.Services" }],
+    categories: ["Code"],
+    files: [{ path: "dist", addressable: true }],
+    contributions: [
+      {
+        id: `${context.extensionId}-hub`,
+        type: "ms.vss-web.hub",
+        description: `${context.pluginName} hub`,
+        targets: ["ms.vss-code-web.code-hub-group"],
+        properties: {
+          name: context.pluginName,
+          uri: "dist/index.html"
+        }
+      }
+    ]
+  };
+
+  const devManifest = {
+    ...manifest,
+    baseUri: "https://localhost:3000"
+  };
+
+  return { manifest, devManifest };
+}

package/@danieli-automation/create-devops-plugin/src/template/npm.ts

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Runs npm install in the generated plugin directory.
+ *
+ * @param cwd - generated project directory path
+ * @throws Error if npm install exits with a non-zero code
+ */
+export function runNpmInstall(cwd: string) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn("npm", ["install"], { cwd, stdio: "inherit", shell: true });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`npm install failed with code ${code}`));
+    });
+  });
+}

package/@danieli-automation/create-devops-plugin/src/template/types.ts

@@ -0,0 +1,14 @@
+export interface CreatePluginTemplateInput {
+  targetDir: string;
+  pluginName: string;
+  publisher: string;
+  extensionId?: string;
+  installDependencies?: boolean;
+  force?: boolean;
+}
+
+export interface TemplateContext {
+  pluginName: string;
+  publisher: string;
+  extensionId: string;
+}

package/@danieli-automation/create-devops-plugin/src/template/utils.ts

@@ -0,0 +1,22 @@
+/**
+ * Normalizes text into a lowercase kebab-case identifier.
+ *
+ * @param value - raw input text to normalize
+ */
+export function normalizeId(value: string) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-");
+}
+
+/**
+ * Escapes special characters for safe HTML interpolation.
+ *
+ * @param value - raw string content
+ */
+export function escapeForHtml(value: string) {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}

package/@danieli-automation/create-devops-plugin/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/@danieli-automation/devops-plugin-core/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@danieli-automation/devops-plugin-core",
+  "version": "0.1.0",
+  "description": "Core utilities and API wrappers for Azure DevOps plugins",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue",
+    "lint": "echo lint not configured",
+    "test": "echo test not configured"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/@danieli-automation/devops-plugin-core/src/core/azureClients.ts

@@ -0,0 +1,18 @@
+/**
+ * @description: Azure DevOps clients for various services.
+ * Provides functions to get clients for Core, Work Item Tracking, Work, Git, and Graph services.
+ * These clients are used to interact with Azure DevOps REST APIs.
+ */
+
+import { getClient } from "azure-devops-extension-api";
+import { CoreRestClient } from "azure-devops-extension-api/Core";
+import { GitRestClient } from "azure-devops-extension-api/Git";
+import { GraphRestClient } from "azure-devops-extension-api/Graph";
+import { WorkRestClient } from "azure-devops-extension-api/Work";
+import { WorkItemTrackingRestClient } from "azure-devops-extension-api/WorkItemTracking";
+
+export const coreClient = () => getClient(CoreRestClient);
+export const witClient = () => getClient(WorkItemTrackingRestClient);
+export const workClient = () => getClient(WorkRestClient);
+export const gitClient = () => getClient(GitRestClient);
+export const graphClient = () => getClient(GraphRestClient);

package/@danieli-automation/devops-plugin-core/src/core/storage/createStore.ts

@@ -0,0 +1,65 @@
+/**
+ * @description: Key-Value Store abstraction using Azure DevOps Data Manager.
+ * Provides load and save methods for storing and retrieving data with specified scope.
+ * Handles non-existent keys gracefully by returning undefined on load.
+ * Uses default scope from configuration if none is provided.
+ * Logs errors during save operations for debugging purposes.
+ */
+
+import { IExtensionDataManager, IExtensionDataService } from "azure-devops-extension-api";
+import * as SDK from "azure-devops-extension-sdk";
+import { KVStore } from "core/types/KVStoreType";
+import { ScopeType } from "core/types/ScopeType";
+import { DEFAULT_SCOPE } from "./keys";
+
+export function createKVStore<T>(key: string, scopeType: ScopeType = DEFAULT_SCOPE): KVStore<T> {
+    return {
+        async load() {
+            try {
+                const manager = await getDataManager();
+                return await manager.getValue(key, { scopeType }) as T | undefined;
+            } catch (err: any) {
+                if (err?.typeKey === "DocumentCollectionDoesNotExistException") {
+                    return undefined;
+                }
+                if (String(err).includes("404")) return undefined;
+                throw err;
+            }
+        },
+        async save(value: T) {
+            try {
+                const manager = await getDataManager();
+                await manager.setValue(key, value, { scopeType });
+            } catch (err) {
+                console.log(`CrateteKVStore: Error saving key ${key} with scope ${scopeType}`, err);
+                throw err;
+            }
+        }
+    };
+}
+
+//#region Private Functions
+
+/**
+ * @description: Azure DevOps Data Manager accessor.
+ * Provides a function to get the extension data manager for storing and retrieving extension data.
+ * Caches the manager instance for reuse.   
+ * Handles SDK readiness and service retrieval.
+ * Uses extension context to get the appropriate data manager.
+ * @returns Promise resolving to IExtensionDataManager instance.
+ */
+
+let cachedManager: IExtensionDataManager | null = null;
+
+async function getDataManager(): Promise<IExtensionDataManager> {
+    if (cachedManager) return cachedManager;
+
+    try { await SDK.ready(); } catch { }
+    const extDataService: IExtensionDataService = await SDK.getService<IExtensionDataService>("ms.vss-features.extension-data-service");
+    const accessToken = await SDK.getAccessToken();
+    const { id: extensionId } = SDK.getExtensionContext();
+
+    cachedManager = await extDataService.getExtensionDataManager(extensionId, accessToken);
+    return cachedManager;
+}
+//#endregion

package/@danieli-automation/devops-plugin-core/src/core/storage/hooks/useCrossTeamSprintInstance.ts

@@ -0,0 +1,145 @@
+/**
+ * @description: Column Preference storage hooks using React Query.
+ * Provides hooks for querying and mutating
+ * Utilizes zustand stores for persistent storage and caching.
+ * Ensures data consistency by updating the query cache on successful mutations.
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { QUERY_KEYS } from "core/storage/keys";
+import { CreateInstanceInput } from "core/types/instance/CreateInstanceInputType";
+import { CrossSprintInstanceType } from "core/types/instance/CrossSprintInstanceType";
+import { DefaultInstanceType } from "core/types/instance/DefaultInstanceType";
+import { UpdateInstanceInput } from "core/types/instance/UpdateInstanceInputType";
+import { createCrossSprintInstance, deleteCrossTeamInstance, loadAllInstances, updateCrossSprintInstance } from "../repositories/instance";
+import { defaultInstanceStore } from "../stores";
+
+/** Load all instances (for some picker UI later)
+ *
+ * Fetches all saved Cross Sprint instances.
+ *
+ * @returns React Query result containing the instances list.
+ */
+export function useCrossSprintInstancesQuery() {
+    return useQuery({
+        queryKey: [QUERY_KEYS.crossSprint, QUERY_KEYS.instances],
+        queryFn: () => loadAllInstances(),
+        staleTime: Infinity,
+        cacheTime: 1,
+    });
+}
+
+/** Create new instance
+ *
+ * Creates a new Cross Sprint instance and appends it to the cached instances list.
+ *
+ * @returns React Query mutation for creating an instance.
+ */
+export function useCreateCrossSprintInstance() {
+    const qc = useQueryClient();
+    return useMutation({
+        mutationFn: (input: CreateInstanceInput) => createCrossSprintInstance(input),
+        onSuccess: (created) => {
+            qc.setQueryData<CrossSprintInstanceType[] | undefined>(
+                [QUERY_KEYS.crossSprint, QUERY_KEYS.instances],
+                (prev) => (prev ? [...prev, created] : [created])
+            );
+        },
+    });
+}
+
+/** Update existing instance (e.g. add/remove teams)
+ *
+ * Updates an existing Cross Sprint instance, replaces it in the cached list,
+ * and syncs the zustand `currentInstance` if it matches the updated item.
+ *
+ * @returns React Query mutation for updating an instance.
+ */
+export function useUpdateCrossTeamInstance() {
+    const qc = useQueryClient();
+
+    return useMutation({
+        mutationFn: (input: UpdateInstanceInput) => updateCrossSprintInstance(input),
+        onSuccess: (updated) => {
+            if (!updated) return;
+
+            qc.setQueryData<CrossSprintInstanceType[] | undefined>(
+                [QUERY_KEYS.crossSprint, QUERY_KEYS.instances],
+                (prev) => prev?.map(i => i.id === updated.id ? updated : i) ?? [updated]
+            );
+        },
+    });
+}
+
+/** Delete an instance
+ *
+ * Deletes an instance, removes it from the cached instances list,
+ * clears related preference queries, and resets zustand `currentInstance`
+ * if the deleted instance was selected. Also clears default instance preference
+ * if it was pointing to the deleted instance.
+ *
+ * @returns React Query mutation for deleting an instance by id.
+ */
+export function useDeleteCrossTeamInstance() {
+    const qc = useQueryClient();
+
+    return useMutation({
+        mutationFn: (instanceId: string) => deleteCrossTeamInstance(instanceId),
+        onSuccess: async (_, instanceId) => {
+            qc.setQueryData<CrossSprintInstanceType[] | undefined>(
+                [QUERY_KEYS.crossSprint, QUERY_KEYS.instances],
+                (prev) => prev?.filter(i => i.id !== instanceId) ?? []
+            );
+
+            qc.removeQueries({ queryKey: [QUERY_KEYS.prefs, QUERY_KEYS.backlogOrder, instanceId] });
+
+            try {
+                const pref = await defaultInstanceStore.load();
+                if (pref?.id === instanceId) {
+                    await defaultInstanceStore.save({});
+                    qc.setQueryData([QUERY_KEYS.crossSprint, QUERY_KEYS.defaultInstancePref], {});
+                }
+            } catch (e) {
+                console.warn("Failed to clear default instance pref after delete:", e);
+            }
+        },
+    });
+}
+
+//#region Default Instance Hook
+
+/** Load default instance preference
+ *
+ * Loads the persisted default instance preference from storage.
+ *
+ * @returns React Query result containing the default instance preference.
+ */
+export function useDefaultInstanceQuery() {
+    return useQuery({
+        queryKey: [QUERY_KEYS.crossSprint, QUERY_KEYS.defaultInstancePref],
+        queryFn: () => defaultInstanceStore.load(),
+        staleTime: Infinity,
+        cacheTime: Infinity,
+    });
+}
+
+/** Save default instance preference
+ *
+ * Persists the default instance preference and updates the query cache.
+ *
+ * @param pref The default instance preference object to save.
+ * @returns React Query mutation for saving the default preference.
+ */
+export function useSaveDefaultInstance() {
+    const qc = useQueryClient();
+
+    return useMutation({
+        // always save an object, never null/undefined
+        mutationFn: (pref: DefaultInstanceType) => defaultInstanceStore.save(pref),
+        onSuccess: (_, pref) => {
+            qc.setQueryData([QUERY_KEYS.crossSprint, QUERY_KEYS.defaultInstancePref], pref);
+        },
+    });
+}
+
+//#endregion