devops-plugin-kit 0.1.0

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

@@ -0,0 +1,30 @@
+{
+  "name": "@danieli-automation/create-devops-plugin",
+  "version": "0.1.0",
+  "description": "Scaffold Azure DevOps plugin template and manifest files",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "create-devops-plugin": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').cpSync('src/template/static','dist/template/static',{recursive:true,force:true})\"",
+    "clean": "Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue",
+    "lint": "echo lint not configured",
+    "test": "echo test not configured"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import process from "node:process";
+import { createPluginTemplate } from "./index.js";
+
+type CliArgs = {
+  pluginName: string;
+  publisher: string;
+  targetDir: string;
+  extensionId?: string;
+  installDependencies: boolean;
+  force: boolean;
+};
+
+/**
+ * Parses command line flags and positional arguments for scaffold execution.
+ *
+ * @param argv - raw process argv list
+ * @throws Error when required options are missing or malformed
+ */
+function parseArgs(argv: string[]): CliArgs {
+  const args = [...argv];
+  const pluginName = args.shift();
+  if (!pluginName) {
+    throw new Error("Missing required argument: <plugin-name>");
+  }
+
+  let publisher = "";
+  let targetDir = process.cwd();
+  let extensionId: string | undefined;
+  let installDependencies = true;
+  let force = false;
+
+  while (args.length > 0) {
+    const token = args.shift();
+
+    if (!token) {
+      continue;
+    }
+
+    if (token === "--publisher" || token === "-p") {
+      publisher = args.shift() ?? "";
+      continue;
+    }
+
+    if (token === "--targetDir" || token === "--target-dir" || token === "-t") {
+      targetDir = args.shift() ?? targetDir;
+      continue;
+    }
+
+    if (token === "--extensionId" || token === "--extension-id" || token === "-e") {
+      extensionId = args.shift();
+      continue;
+    }
+
+    if (token === "--no-install") {
+      installDependencies = false;
+      continue;
+    }
+
+    if (token === "--force" || token === "-f") {
+      force = true;
+      continue;
+    }
+
+    if (token === "--help" || token === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (!publisher) {
+    throw new Error("Missing required option: --publisher <publisher-id>");
+  }
+
+  return {
+    pluginName,
+    publisher,
+    targetDir,
+    extensionId,
+    installDependencies,
+    force
+  };
+}
+
+/**
+ * Prints usage help for the create-devops-plugin CLI.
+ */
+function printHelp() {
+  console.log(
+    [
+      "Usage:",
+      "  create-devops-plugin <plugin-name> --publisher <publisher-id> [options]",
+      "",
+      "Options:",
+      "  -p, --publisher <id>           Azure DevOps publisher id (required)",
+      "  -t, --target-dir <path>        Parent folder (default: current directory)",
+      "  -e, --extension-id <id>        Manifest extension id override",
+      "      --no-install               Skip npm install in generated plugin",
+      "  -f, --force                    Allow non-empty target directory",
+      "  -h, --help                     Show help"
+    ].join("\n")
+  );
+}
+
+async function main() {
+  try {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--help") || argv.includes("-h")) {
+      printHelp();
+      return;
+    }
+
+    const parsed = parseArgs(argv);
+    const outputDir = await createPluginTemplate({
+      pluginName: parsed.pluginName,
+      publisher: parsed.publisher,
+      targetDir: path.resolve(parsed.targetDir),
+      extensionId: parsed.extensionId,
+      installDependencies: parsed.installDependencies,
+      force: parsed.force
+    });
+
+    console.log(`Plugin created at: ${outputDir}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`create-devops-plugin failed: ${message}`);
+    printHelp();
+    process.exit(1);
+  }
+}
+
+void main();

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

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { createManifests } from "./template/manifest.js";
+import { runNpmInstall } from "./template/npm.js";
+import { createTemplateFiles } from "./template/files/index.js";
+import { copyStaticFolder, ensureOutputDir, writeFiles } from "./template/fs.js";
+import { normalizeId } from "./template/utils.js";
+import type { CreatePluginTemplateInput } from "./template/types.js";
+
+export type { CreatePluginTemplateInput } from "./template/types.js";
+
+/**
+ * Creates a development-ready Azure DevOps plugin project from templates.
+ *
+ * @param input - scaffold options for target path, naming, and install behavior
+ * @throws Error if directory validation, file generation, or dependency install fails
+ */
+export async function createPluginTemplate(input: CreatePluginTemplateInput) {
+  const context = {
+    pluginName: input.pluginName,
+    publisher: input.publisher,
+    extensionId: normalizeId(input.extensionId ?? input.pluginName)
+  };
+
+  const outputDir = path.resolve(input.targetDir, input.pluginName);
+  await ensureOutputDir(outputDir, Boolean(input.force));
+
+  const { manifest, devManifest } = createManifests(context);
+  const files = createTemplateFiles({ context, manifest, devManifest });
+  await writeFiles(outputDir, files);
+  await copyStaticFolder(outputDir);
+
+  if (input.installDependencies ?? true) {
+    await runNpmInstall(outputDir);
+  }
+
+  return outputDir;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Generates the azure-devops-extension-api mock index template entry.
+ */
+export function apiIndexMockFile(): [string, string] {
+  return [
+    "src/test/mocks/azure-devops-extension-api/index.ts",
+    `export {};
+`
+  ];
+}

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

@@ -0,0 +1,25 @@
+import type { TemplateContext } from "../types.js";
+import { escapeForHtml } from "../utils.js";
+
+/**
+ * Generates the main application HTML template entry.
+ *
+ * @param context - template metadata for document title
+ */
+export function appHtmlFile(context: TemplateContext): [string, string] {
+  return [
+    "src/app/App.html",
+    `<!doctype html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <title>${escapeForHtml(context.pluginName)}</title>
+        </head>
+        <body>
+          <div id="app-root"></div>
+        </body>
+      </html>
+`
+  ];
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Generates the base stylesheet template entry.
+ */
+export function appStylesFile(): [string, string] {
+  return [
+    "src/app/styles.css",
+    `:root {
+  font-family: Segoe UI, Arial, sans-serif;
+}
+
+body {
+  margin: 0;
+  background: #f5f6f8;
+  color: #1f2328;
+}
+
+.app {
+  padding: 24px;
+}
+`
+  ];
+}

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

@@ -0,0 +1,41 @@
+import type { TemplateContext } from "../types.js";
+import { escapeForHtml } from "../utils.js";
+
+/**
+ * Generates the main React entry component template entry.
+ *
+ * @param context - template metadata for UI text
+ */
+export function appTsxFile(context: TemplateContext): [string, string] {
+  return [
+    "src/app/App.tsx",
+    `import React from "react";
+     import { createRoot } from "react-dom/client";
+     import * as SDK from "azure-devops-extension-sdk";
+     import "./styles.css";
+
+    async function bootstrap() {
+      SDK.init();
+      await SDK.ready();
+
+      const root = document.getElementById("app-root");
+      if (!root) {
+        throw new Error("Root element not found");
+      }
+
+      createRoot(root).render(
+        <React.StrictMode>
+          <main className="app">
+            <h1>${escapeForHtml(context.pluginName)}</h1>
+            <p>Your Azure DevOps plugin template is ready.</p>
+          </main>
+        </React.StrictMode>
+      );
+    }
+
+bootstrap().catch((error) => {
+  console.error("Bootstrap failed", error);
+});
+`
+  ];
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Generates the environment example file template entry.
+ */
+export function envExampleFile(): [string, string] {
+  return [
+    ".env.example",
+    `ENV=dev
+     PORT=8080
+     SCOPE=User`
+  ];
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Generates the .gitignore template entry.
+ */
+export function gitignoreFile(): [string, string] {
+  return [
+    ".gitignore",
+    `node_modules
+    dist
+    *.vsix
+    coverage
+`
+  ];
+}

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

@@ -0,0 +1,51 @@
+import type { TemplateContext } from "../types.js";
+import { apiIndexMockFile } from "./apiIndexMock.js";
+import { appHtmlFile } from "./appHtml.js";
+import { appStylesFile } from "./appStyles.js";
+import { appTsxFile } from "./appTsx.js";
+import { envExampleFile } from "./envExample.js";
+import { gitignoreFile } from "./gitignore.js";
+import { packageJsonFile } from "./packageJson.js";
+import { readmeFile } from "./readme.js";
+import { sdkMockFile } from "./sdkMock.js";
+import { testSetupFile } from "./testSetup.js";
+import { tsconfigJsonFile } from "./tsconfigJson.js";
+import { vitestConfigFile } from "./vitestConfig.js";
+import { webpackAppConfigFile } from "./webpackAppConfig.js";
+import { webpackCommonConfigFile } from "./webpackCommonConfig.js";
+import { webpackConfigFile } from "./webpackConfig.js";
+
+type Props = {
+  context: TemplateContext;
+  manifest: Record<string, unknown>;
+  devManifest: Record<string, unknown>;
+}
+
+/**
+ * Builds the full file map for project scaffolding.
+ *
+ * @param context - template metadata used in generated files
+ * @param manifest - production manifest content
+ * @param devManifest - development manifest content
+ */
+export function createTemplateFiles({ context, manifest, devManifest }: Props): Map<string, string> {
+  return new Map<string, string>([
+    packageJsonFile(context),
+    tsconfigJsonFile(),
+    webpackConfigFile(),
+    webpackCommonConfigFile(),
+    webpackAppConfigFile(),
+    vitestConfigFile(),
+    appTsxFile(context),
+    appHtmlFile(context),
+    appStylesFile(),
+    testSetupFile(),
+    sdkMockFile(),
+    apiIndexMockFile(),
+    envExampleFile(),
+    ["vss-extension.json", JSON.stringify(manifest, null, 2)],
+    ["vss-extension.dev.json", JSON.stringify(devManifest, null, 2)],
+    gitignoreFile(),
+    readmeFile(context)
+  ]);
+}

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

@@ -0,0 +1,60 @@
+import type { TemplateContext } from "../types.js";
+
+/**
+ * Generates the package.json template entry.
+ *
+ * @param context - template metadata for package naming
+ */
+export function packageJsonFile(context: TemplateContext): [string, string] {
+  return [
+    "package.json",
+    JSON.stringify(
+      {
+        name: context.extensionId,
+        version: "0.0.1",
+        private: true,
+        scripts: {
+          dev: "webpack serve --config webpack.config.cjs --env ENV=dev",
+          build: "webpack --config webpack.config.cjs --env ENV=prod",
+          test: "vitest run",
+          "test:watch": "vitest",
+          package: "npm run build && tfx extension create --manifest-globs vss-extension.json",
+          "package:dev": "tfx extension create --manifest-globs vss-extension.dev.json"
+        },
+        dependencies: {
+          react: "^19.1.0",
+          "react-dom": "^19.1.0",
+          "azure-devops-extension-sdk": "^4.0.2",
+          "azure-devops-extension-api": "^4.251.0"
+        },
+        devDependencies: {
+          "@types/node": "^24.3.0",
+          "@types/react": "^19.1.10",
+          "@types/react-dom": "^19.1.7",
+          "@vitest/coverage-v8": "^3.2.4",
+          "@pmmmwh/react-refresh-webpack-plugin": "^0.5.15",
+          "copy-webpack-plugin": "^13.0.1",
+          dotenv: "^17.2.1",
+          "css-loader": "^7.1.2",
+          "fork-ts-checker-webpack-plugin": "^9.1.0",
+          jsdom: "^26.1.0",
+          "react-refresh": "^0.18.0",
+          "react-refresh-typescript": "^2.0.11",
+          sass: "^1.90.0",
+          "sass-loader": "^16.0.5",
+          "style-loader": "^4.0.0",
+          "ts-loader": "^9.5.2",
+          "tsconfig-paths-webpack-plugin": "^4.2.0",
+          typescript: "^5.9.2",
+          vitest: "^3.2.4",
+          webpack: "^5.101.0",
+          "webpack-cli": "^6.0.1",
+          "webpack-dev-server": "^5.2.2",
+          "tfx-cli": "^0.21.1"
+        }
+      },
+      null,
+      2
+    )
+  ];
+}

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

@@ -0,0 +1,30 @@
+import type { TemplateContext } from "../types.js";
+
+/**
+ * Generates the README template entry.
+ *
+ * @param context - template metadata for project title
+ */
+export function readmeFile(context: TemplateContext): [string, string] {
+  return [
+    "README.md",
+    `# ${context.pluginName}
+
+## Commands
+
+- \`npm run dev\`: start webpack dev server
+- \`npm run build\`: production build to \`dist\`
+- \`npm run test\`: run unit tests with vitest
+- \`npm run test:watch\`: run tests in watch mode
+- \`npm run package\`: build and create VSIX using \`vss-extension.json\`
+- \`npm run package:dev\`: create VSIX using \`vss-extension.dev.json\`
+
+## Configuration Layout
+
+- \`webpack.config.cjs\`: webpack entry point
+- \`config/webpack/common.cjs\`: shared webpack rules and plugins
+- \`config/webpack/app.cjs\`: app bundle configuration
+- \`vitest.config.ts\`: test and coverage setup
+`
+  ];
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Generates the azure-devops-extension-sdk mock template entry.
+ */
+export function sdkMockFile(): [string, string] {
+  return [
+    "src/test/mocks/azure-devops-extension-sdk.ts",
+    `export const init = () => undefined;
+export const ready = async () => undefined;
+`
+  ];
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Generates the vitest setup template entry.
+ */
+export function testSetupFile(): [string, string] {
+  return [
+    "src/test/setup.ts",
+    `import { vi } from "vitest";
+
+    vi.mock("azure-devops-extension-sdk", () => ({
+      default: {},
+      init: vi.fn(),
+      ready: vi.fn().mockResolvedValue(undefined)
+    }));
+`
+  ];
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Generates the tsconfig.json template entry.
+ */
+export function tsconfigJsonFile(): [string, string] {
+  return [
+    "tsconfig.json",
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          lib: ["ES2022", "DOM", "DOM.Iterable"],
+          jsx: "react-jsx",
+          moduleResolution: "Node",
+          strict: true,
+          skipLibCheck: true,
+          sourceMap: true,
+          baseUrl: ".",
+          paths: {
+            "core/*": ["src/core/*"],
+            "app/*": ["src/app/*"],
+          }
+        },
+        include: ["src", "vitest.config.ts"]
+      },
+      null,
+      2
+    )
+  ];
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Generates the vitest.config.ts template entry.
+ */
+export function vitestConfigFile(): [string, string] {
+  return [
+    "vitest.config.ts",
+    `import path from "node:path";
+     import { defineConfig } from "vitest/config";
+
+      export default defineConfig({
+        resolve: {
+          alias: [
+            {
+              find: "azure-devops-extension-sdk",
+              replacement: path.resolve(__dirname, "src/test/mocks/azure-devops-extension-sdk.ts")
+            },
+            {
+              find: /^azure-devops-extension-api\\/(.*)$/,
+              replacement: path.resolve(__dirname, "src/test/mocks/azure-devops-extension-api/$1.ts")
+            },
+            {
+              find: /^azure-devops-extension-api$/,
+              replacement: path.resolve(__dirname, "src/test/mocks/azure-devops-extension-api/index.ts")
+            },
+            { find: /^core\\/(.*)$/, replacement: path.resolve(__dirname, "src/core/$1") },
+            { find: /^app\\/(.*)$/, replacement: path.resolve(__dirname, "src/app/$1") },
+            { find: /^tabs\\/(.*)$/, replacement: path.resolve(__dirname, "src/app/tabs/$1") }
+          ]
+        },
+        test: {
+          environment: "jsdom",
+          setupFiles: ["./src/test/setup.ts"],
+          globals: true,
+          restoreMocks: true,
+          clearMocks: true,
+          mockReset: true,
+          coverage: {
+            all: true,
+            provider: "v8",
+            reporter: ["text", "html", "lcov"],
+            reportsDirectory: "./coverage",
+            include: ["src/**/*.ts", "src/**/*.tsx"],
+            exclude: [
+              "**/node_modules/**",
+              "**/dist/**",
+              "**/coverage/**",
+              "**/*.d.ts",
+              "src/test/**",
+              "src/**/__tests__/**",
+              "src/**/__mocks__/**"
+            ]
+          }
+        }
+      });
+`
+  ];
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Generates the app webpack config template entry.
+ */
+export function webpackAppConfigFile(): [string, string] {
+  return [
+    "config/webpack/app.cjs",
+    `const path = require("path");
+     const { createCommonConfig } = require("./common.cjs");
+
+      function createAppConfig(env) {
+        const isDev = env === "dev";
+
+        return createCommonConfig({
+          env,
+          name: "app",
+          entry: { app: "./src/app/App.tsx" },
+          outputPath: path.resolve(__dirname, "../../dist/app"),
+          publicPath: isDev ? "/app/" : "./",
+          withDevServer: true,
+          copyPatterns: [
+            { from: "src/app/App.html", to: "App.html" },
+            { from: "static/images", to: "static/images", noErrorOnMissing: true },
+            { from: "static/fonts", to: "static/fonts", noErrorOnMissing: true }
+          ]
+        });
+      }
+
+      module.exports = { createAppConfig };
+      `
+  ];
+}