monecromanci 0.0.0

package/README.md

@@ -0,0 +1,84 @@
+# MoNecromanCI
+
+> **MO**no(repo) + **NECROMAN**cy + **CI**. The CLI command is `monecromanci` (short alias `mnci`).
+
+An interactive CLI that **summons**, **conjures**, **raises** and **validates** NX
+monorepos — Node + TypeScript, Jest, ESLint, real VSCode `.ts` debugging, and a
+complete CI pipeline (Azure DevOps **and/or** GitHub Actions), with near-zero
+per-project configuration.
+
+It generates nine project kinds and keeps every repo's tool-owned config in sync:
+
+| Kind              | What you get                                                            |
+| ----------------- | ----------------------------------------------------------------------- |
+| `internal-lib`    | Source-resolved (`main → src/index.ts`) so you step into it while debugging and "find references" works across libs. |
+| `publishable-lib` | Published via `nx release`; `dist/package.json` gets **real, resolved dependencies** even though all deps live in the root. |
+| `cli-tool`        | A publishable lib that also ships a bundled `bin` (esbuild + shebang).   |
+| `function-app`    | Azure Functions v4, `.configurations/{dev,uat,prod}.json`, `clean:config` whitespace-strip, attach-debugging. |
+| `node-app`        | A framework-agnostic TS HTTP server (node:http) you extend with Express/Koa/Fastify/Nest/…; built, dependency-traced and zipped like a function app. |
+| `react-app`       | Vite with `dev`/`uat`/`prod` builds (`dist-dev`/`dist-uat`/`dist-prod`) and browser debugging. |
+| `vue-app`         | Vue 3 + Vite, same multi-env builds.                                    |
+| `svelte-app`      | Svelte 5 + Vite, same multi-env builds.                                 |
+| `nextjs-app`      | Full-stack Next.js (App Router). Per-env builds assemble `dist-<env>` in **server** (standalone) or **static-export** mode (`NEXT_OUTPUT`). |
+
+## Commands
+
+Every command keeps its plain name and gains a necromancy-themed alias (in the
+comment below) — use whichever reads better to you:
+
+```sh
+monecromanci new [name]       # summon  · scaffold a brand-new monorepo (prompts: CI provider, registry, scope, …)
+monecromanci add [type]       # conjure · internal-lib | publishable-lib | cli-tool | function-app | node-app | react-app | vue-app | svelte-app | nextjs-app
+monecromanci doctor [--fix]   # raise   · detect (and with --fix, repair) tool-owned config drift
+monecromanci update           # ascend  · doctor --fix + re-stamp the template version
+monecromanci validate [--all] # ritual  · run lint/test/build locally (nx affected; --all = run-many) before pushing to CI
+```
+
+`new` is fully scriptable: `monecromanci new demo --yes --ci github --registry github-packages --owner acme`.
+
+## CI providers & registry (chosen per repo)
+
+`new` prompts for a **CI provider** — `azure`, `github`, or `both` — and a **package
+registry** — Azure Artifacts, GitHub Packages, or public npm (defaulting to match
+the CI). The `.build-templates/*.mjs` are the single engine for **both** providers;
+only a thin wrapper differs: `azure-pipelines.yml` and/or `.github/workflows/ci.yml`.
+The `.npmrc`, each publishable project's `publishConfig`, and the nx-release docs
+are generated to match the registry.
+
+## What's centralised
+
+One root `package.json` holds **all** dependencies. The root owns `nx.json`
+(with `nx release`), `tsconfig.base.json`, `tsconfig.jest.json`, a Jest preset
+factory, a **non-type-checked** ESLint flat config (standard/no-semi + @stylistic
++ unicorn + React + Jest + TSDoc + JSON/JSONC/JSON5 + YAML + Markdown), the
+`.code-workspace`, and a vendored CI pipeline. Per-project config is 2–4 tiny files.
+
+## Debugging (works on the TypeScript, including into libs)
+
+The `.code-workspace` ships **breakpoint-capable** configs at the workspace top
+level (where VSCode actually reads them): "Debug Jest (current file)"
+(`--runInBand`, `resolveSourceMapLocations: null`, source maps on), a Function/Node
+App attach config (`:9229`), and browser configs for Vite (`:5173`) and Next.js
+(`:3000`) — plus the `Orta.vscode-jest` extension for per-test Debug lenses.
+
+## Developing MoNecromanCI
+
+```sh
+npm install --legacy-peer-deps   # ESLint 10 leads some plugins' peer ranges
+npm run build                    # tsup bundle + copy assets to dist/
+npm run lint
+npm test
+```
+
+### Verify the generated output end-to-end
+
+```sh
+node dist/cli.js new demo --yes --registry npm --lib helpers
+cd demo
+node ../dist/cli.js add nextjs-app web   # or any other kind
+npm install
+npm run lint && npm test && npm run build
+node ../dist/cli.js validate             # (ritual) nx affected -t lint test build
+# In VSCode: open demo.code-workspace, set a breakpoint in a *.test.ts, run
+# "Debug Jest (current file)" → it should pause on the breakpoint.
+```

package/dist/assets/azure-pipelines.yml

@@ -0,0 +1,33 @@
+name: monorepo-ci-$(Date:yyyyMMdd)$(Rev:.r)
+
+# Generated by MoNecromanCI. Re-sync the build-templates with 'monecromanci doctor'.
+trigger:
+  branches:
+    include: [dev, development, uat, master, main]
+  paths:
+    exclude: [docs/**, "**/*.md"]
+
+pr:
+  branches:
+    include: [dev, development, uat, master, main]
+  paths:
+    exclude: [docs/**, "**/*.md"]
+
+pool:
+  name: AzurePipelineManagedPool-Windows
+  demands:
+    - npm
+
+variables:
+  # Set to an Azure Resource Manager service connection to publish TypeDoc to a
+  # Storage blob; leave empty to skip documentation publishing.
+  - name: docsAzureSubscription
+    value: ""
+
+steps:
+  - template: .build-templates/01-preparation.yml
+  - template: .build-templates/02-quality-control.yml
+  - template: .build-templates/03-package-apps.yml
+  - template: .build-templates/04-publish-libs.yml
+  - template: .build-templates/05-publish-documentation.yml
+  - template: .build-templates/06-summary.yml

package/dist/assets/build-templates/01-preparation.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Step 01 — Preparation.
+ *
+ * Resolves the git range, the Nx affected project set, classifies every project
+ * from its tags, and writes a reusable context manifest consumed by every later
+ * step. Also emits the pipeline variables used for step gating and prints a
+ * human-readable execution plan so a run can be understood at a glance.
+ *
+ * Run locally with `npm run pipeline:plan` (after `npm ci`) to preview the plan
+ * without pushing.
+ */
+
+import process from 'node:process'
+import {
+  banner,
+  log,
+  section,
+  setBuildNumber,
+  setVariables,
+  table,
+  writeJson,
+} from './lib/_h.mjs'
+import {
+  buildContextManifest,
+  CONTEXT_FILE_PATH,
+  describeProjectAction,
+  describeProjectType,
+  enrichProject,
+} from './lib/context.mjs'
+import {
+  resolveAffectedProjects,
+  resolveAllProjects,
+  resolveBaseCommit,
+  resolveEffectiveBranchName,
+  resolveHeadCommit,
+  resolveProjectMetadata,
+} from './lib/nx.mjs'
+
+/**
+ * Resolves and enriches every project in the workspace.
+ *
+ * @param {string[]} projectNames All Nx project names.
+ * @param {Set<string>} affectedSet The affected project names.
+ * @param {string} branchName The effective branch name.
+ * @returns {Array<Record<string, any>>} Returns enriched project data.
+ */
+function resolvePipelineProjects (projectNames, affectedSet, branchName) {
+  const projects = []
+
+  for (const projectName of [...projectNames].sort((left, right) => left.localeCompare(right))) {
+    const metadata = resolveProjectMetadata(projectName)
+    if (!metadata) {
+      log(`[projects] Skipping ${projectName}: no Nx metadata resolved`)
+      continue
+    }
+
+    projects.push(enrichProject(metadata, affectedSet.has(projectName), branchName))
+  }
+
+  return projects
+}
+
+/**
+ * Resolves the build number from releasable project versions.
+ *
+ * @param {Record<string, any>} context The context manifest.
+ * @returns {string} Returns the build number.
+ */
+function resolveBuildNumber (context) {
+  const releasable = context.projects
+    .filter(project => !project.ignored)
+    .filter(project => project.type.functionApp || project.type.reactApp || project.type.externalPackage)
+    .filter(project => project.affected && project.version)
+
+  if (releasable.length === 0) {
+    return process.env.BUILD_BUILDNUMBER || 'monorepo-no-affected'
+  }
+
+  return releasable.map(project => `${project.name}_${project.version}`).join('-')
+}
+
+/**
+ * Builds the pipeline variables emitted for step gating.
+ *
+ * @param {Record<string, any>} context The context manifest.
+ * @returns {{name: string, value: string}[]} Returns the pipeline variables.
+ */
+function buildPipelineVariables (context) {
+  const variables = [
+    { name: 'MONOREPO_CONTEXT_FILE', value: CONTEXT_FILE_PATH },
+    { name: 'NX_BASE', value: context.baseCommit },
+    { name: 'NX_HEAD', value: context.headCommit },
+    { name: 'HAS_AFFECTED', value: String(context.hasAffected) },
+    { name: 'AFFECTED_PROJECTS', value: context.affectedProjects.join(',') },
+    { name: 'FUNCTION_APPS', value: context.groups.functionApps.join(',') },
+    { name: 'NODE_APPS', value: context.groups.nodeApps.join(',') },
+    { name: 'REACT_APPS', value: context.groups.reactApps.join(',') },
+    { name: 'INTERNAL_PACKAGES', value: context.groups.internalPackages.join(',') },
+    { name: 'EXTERNAL_PACKAGES', value: context.groups.externalPackages.join(',') },
+    { name: 'IGNORED_PROJECTS', value: context.groups.ignoredProjects.join(',') },
+    { name: 'HAS_FUNCTION_APPS', value: String(context.groups.functionApps.length > 0) },
+    { name: 'HAS_NODE_APPS', value: String(context.groups.nodeApps.length > 0) },
+    { name: 'HAS_REACT_APPS', value: String(context.groups.reactApps.length > 0) },
+    { name: 'HAS_INTERNAL_PACKAGES', value: String(context.groups.internalPackages.length > 0) },
+    { name: 'HAS_PUBLISHABLE_LIBS', value: String(context.groups.externalPackages.length > 0) },
+  ]
+
+  for (const project of context.projects) {
+    variables.push({ name: `HAS_${project.sanitizedName}`, value: String(project.affected && !project.ignored) })
+  }
+
+  return variables
+}
+
+/**
+ * Prints the execution plan derived from the context manifest.
+ *
+ * @param {Record<string, any>} context The context manifest.
+ */
+function printExecutionPlan (context) {
+  section('Execution plan')
+
+  table(context.projects.map(project => ({
+    project:  project.name,
+    type:     describeProjectType(project),
+    affected: project.affected && !project.ignored ? 'yes' : 'no',
+    version:  project.version || 'n/a',
+    action:   project.affected && !project.ignored ? describeProjectAction(project) : '—',
+  })))
+}
+
+/**
+ * Runs preparation discovery and emits the reusable pipeline context.
+ */
+function main () {
+  banner('[01] Preparation — resolving monorepo context')
+  log(`Platform: ${process.platform}, cwd: ${process.cwd()}`)
+
+  const branchName = resolveEffectiveBranchName()
+  const headCommit = resolveHeadCommit()
+  const baseCommit = resolveBaseCommit(headCommit)
+  log(`Branch: ${branchName || '(unknown)'}`)
+  log(`Range:  ${baseCommit} .. ${headCommit}`)
+
+  const affectedProjects = resolveAffectedProjects(baseCommit, headCommit)
+  const affectedSet = new Set(affectedProjects)
+  log(`Affected (${affectedProjects.length}): ${affectedProjects.join(', ') || '(none)'}`)
+
+  const projectNames = resolveAllProjects()
+  log(`All projects (${projectNames.length}): ${projectNames.join(', ')}`)
+
+  const projects = resolvePipelineProjects(projectNames, affectedSet, branchName)
+  const context = buildContextManifest({ baseCommit, branchName, headCommit, projects })
+
+  writeJson(CONTEXT_FILE_PATH, context)
+  log(`Context written: ${CONTEXT_FILE_PATH}`)
+
+  printExecutionPlan(context)
+
+  const buildNumber = resolveBuildNumber(context)
+  setBuildNumber(buildNumber)
+  log(`Build number: ${buildNumber}`)
+
+  section('Pipeline variables')
+  setVariables(buildPipelineVariables(context))
+
+  banner(context.hasAffected
+    ? `[01] Preparation complete — ${context.affectedProjects.length} affected project(s)`
+    : '[01] Preparation complete — no affected projects, downstream steps will skip')
+}
+
+main()

package/dist/assets/build-templates/01-preparation.yml

@@ -0,0 +1,51 @@
+steps:
+  - checkout: self
+    fetchDepth: 0
+    persistCredentials: true
+
+  - task: PowerShell@2
+    displayName: "[01] Fetch all refs for affected detection"
+    inputs:
+      targetType: inline
+      script: |
+        Write-Host "=== Fetching all refs and tags ===" -ForegroundColor Cyan
+        git fetch --all --prune --tags
+        Write-Host "=== Recent commits ===" -ForegroundColor Cyan
+        git log --oneline -10
+
+  - task: UseNode@1
+    displayName: "[01] Use Node.js 24"
+    inputs:
+      version: 24.x
+
+  - task: PowerShell@2
+    displayName: "[01] Ensure npm cache directory exists"
+    inputs:
+      targetType: inline
+      script: New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/.npm" -Force | Out-Null
+
+  - task: Cache@2
+    displayName: "[01] Restore npm cache"
+    inputs:
+      key: npm | "$(Agent.OS)" | $(Build.SourcesDirectory)/package-lock.json
+      restoreKeys: |
+        npm | "$(Agent.OS)"
+      path: $(Pipeline.Workspace)/.npm
+
+  # Authenticate against the registries declared in the repo's .npmrc. This
+  # injects credentials so the plain `npm ci` below works for any feed/registry.
+  - task: npmAuthenticate@0
+    displayName: "[01] Authenticate npm registry"
+    inputs:
+      workingFile: .npmrc
+
+  # Dependencies are installed BEFORE affected detection so Nx computes the
+  # project graph with the workspace's pinned Nx version (never a downloaded one).
+  - script: npm ci
+    displayName: "[01] Install monorepo dependencies"
+    workingDirectory: $(Build.SourcesDirectory)
+    env:
+      HUSKY: 0
+
+  - script: node .build-templates/01-preparation.mjs
+    displayName: "[01] Resolve context, affected projects and execution plan"

package/dist/assets/build-templates/02-quality-control.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * Step 02 — Quality control.
+ *
+ * Runs lint, test and build for the affected projects over the resolved git
+ * range. Kept as a Node step (rather than a repo `qa` npm script) so the
+ * template stays self-contained — a consuming repo only needs the standard Nx
+ * `lint`/`test`/`build` targets, defined either in `project.json` or via the
+ * `@nx/*` inference plugins.
+ */
+
+import process from 'node:process'
+import { banner, shellEscape } from './lib/_h.mjs'
+import { runNxInherit } from './lib/nx.mjs'
+
+/**
+ * Runs lint, test and build for the affected project set.
+ */
+function main () {
+  banner('[02] Quality control — lint, test and build affected projects')
+
+  const base = process.env.NX_BASE || ''
+  const head = process.env.NX_HEAD || ''
+  const range = base && head ? ` --base=${shellEscape(base)} --head=${shellEscape(head)}` : ''
+
+  runNxInherit(`affected -t lint,test,build${range} --outputStyle=static`)
+
+  banner('[02] Quality control complete')
+}
+
+main()

package/dist/assets/build-templates/02-quality-control.yml

@@ -0,0 +1,24 @@
+steps:
+  - script: node .build-templates/02-quality-control.mjs
+    displayName: "[02] Run affected projects lint, test and build"
+    condition: and(succeeded(), eq(variables['HAS_AFFECTED'], 'true'))
+
+  - task: PublishTestResults@2
+    displayName: "[02] Publish affected projects test results"
+    condition: and(succeededOrFailed(), eq(variables['HAS_AFFECTED'], 'true'))
+    inputs:
+      testResultsFormat: JUnit
+      testResultsFiles: "**/coverage/test-results.xml"
+      searchFolder: $(Build.SourcesDirectory)
+      mergeTestResults: true
+      failTaskOnFailedTests: true
+      testRunTitle: Affected Tests
+
+  - task: PublishCodeCoverageResults@2
+    displayName: "[02] Publish affected projects coverage results"
+    condition: and(succeededOrFailed(), eq(variables['HAS_AFFECTED'], 'true'))
+    inputs:
+      summaryFileLocation: "$(Build.SourcesDirectory)/**/coverage/cobertura-coverage.xml"
+      pathToSources: $(Build.SourcesDirectory)
+      reportDirectory: "$(Build.SourcesDirectory)/**/coverage"
+      failIfCoverageEmpty: false