monecromanci 0.0.0

package/dist/assets/build-templates/04-publish-libs.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * Step 04 — Publish libraries.
+ *
+ * Versions are managed manually: a developer sets the `version` in each
+ * library's `package.json`. This step publishes every affected
+ * `type:publishable-lib` at the version already declared on disk, skipping any
+ * version already present on the registry. It does not bump versions, create
+ * tags, or push commits.
+ *
+ * Gated by the YAML step to non-PR builds on a release branch (master/main).
+ */
+
+import path from 'node:path'
+import process from 'node:process'
+import {
+  banner,
+  isWindows,
+  log,
+  readJsonSafe,
+  run,
+  runInherit,
+  runSafe,
+  section,
+  setVariable,
+  shellEscape,
+  warn,
+} from './lib/_h.mjs'
+import { loadContext, selectAffected } from './lib/context.mjs'
+import { runNxInherit } from './lib/nx.mjs'
+
+const WORKSPACE_ROOT = process.cwd()
+const NPM_BIN = isWindows() ? 'npm.cmd' : 'npm'
+const NPM_USER_CONFIG = path.join(WORKSPACE_ROOT, '.npmrc')
+
+/**
+ * Returns whether the current build is a pull request validation.
+ *
+ * @returns {boolean} Returns true for pull request builds.
+ */
+function isPullRequest () {
+  return String(process.env.BUILD_REASON || '').toLowerCase() === 'pullrequest'
+}
+
+/**
+ * Returns whether the current branch is allowed to publish.
+ *
+ * The allowed branches default to `master` and `main` and can be overridden with
+ * the `RELEASE_BRANCHES` environment variable (comma-separated).
+ *
+ * @returns {boolean} Returns true when the current branch may publish.
+ */
+function isReleaseBranch () {
+  const allowed = (process.env.RELEASE_BRANCHES || 'master,main')
+    .split(',')
+    .map(branch => branch.trim().toLowerCase())
+    .filter(Boolean)
+  const current = String(process.env.BUILD_SOURCEBRANCHNAME || runSafe('git rev-parse --abbrev-ref HEAD')).trim().toLowerCase()
+
+  return allowed.includes(current)
+}
+
+/**
+ * Resolves whether a package version is already on the registry.
+ *
+ * @param {string} packageName The package name.
+ * @param {string} packageVersion The package version.
+ * @returns {boolean} Returns true when the version already exists.
+ */
+function isVersionPublished (packageName, packageVersion) {
+  try {
+    const output = run(`${NPM_BIN} view ${shellEscape(`${packageName}@${packageVersion}`)} version --json --userconfig ${shellEscape(NPM_USER_CONFIG)}`)
+
+    return JSON.parse(output) === packageVersion
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Publishes a single library at its declared version and records the outcome.
+ *
+ * @param {Record<string, any>} project The library project data.
+ * @param {{published: string[], skipped: string[]}} results The publish result accumulator.
+ */
+function publishLibrary (project, results) {
+  const projectRoot = path.join(WORKSPACE_ROOT, project.root)
+  const packageJson = readJsonSafe(path.join(projectRoot, 'package.json'))
+  const packageName = String(packageJson.name || '').trim()
+  const packageVersion = String(packageJson.version || '').trim()
+
+  if (packageJson.private === true) {
+    log(`[${project.name}] skipped — package is private`)
+    return
+  }
+
+  if (!packageName || !packageVersion) {
+    log(`[${project.name}] skipped — missing package name or version in package.json`)
+    return
+  }
+
+  if (isVersionPublished(packageName, packageVersion)) {
+    log(`[${project.name}] skipped — ${packageName}@${packageVersion} already published`)
+    results.skipped.push(`${packageName}@${packageVersion}`)
+    return
+  }
+
+  log(`[${project.name}] building before publish`)
+  runNxInherit(`run ${project.name}:build`)
+
+  log(`[${project.name}] publishing ${packageName}@${packageVersion}`)
+  runInherit(`${NPM_BIN} publish --userconfig ${shellEscape(NPM_USER_CONFIG)}`, { cwd: projectRoot })
+  results.published.push(`${packageName}@${packageVersion}`)
+}
+
+/**
+ * Runs the manual-version publish workflow.
+ */
+function main () {
+  banner('[04] Publish libraries (versions managed manually in package.json)')
+
+  const context = loadContext()
+  const publishableLibraries = selectAffected(context, project => project.type.externalPackage)
+
+  if (publishableLibraries.length === 0) {
+    banner('[04] No affected publishable libraries — nothing to publish')
+    return
+  }
+
+  if (isPullRequest()) {
+    warn('Pull request build — skipping publish (validation only).')
+    return
+  }
+
+  if (!isReleaseBranch()) {
+    warn(`Branch "${process.env.BUILD_SOURCEBRANCHNAME || '(unknown)'}" is not a publish branch (${process.env.RELEASE_BRANCHES || 'master,main'}) — skipping publish.`)
+    return
+  }
+
+  log(`Candidates (${publishableLibraries.length}): ${publishableLibraries.map(project => project.name).join(', ')}`)
+
+  const results = { published: [], skipped: [] }
+  for (const project of publishableLibraries) {
+    section(`Publish: ${project.name}`)
+    publishLibrary(project, results)
+  }
+
+  setVariable('PUBLISHED_LIBS', results.published.join(', '))
+  setVariable('SKIPPED_LIBS', results.skipped.join(', '))
+
+  banner(`[04] Publish complete — published ${results.published.length}, skipped ${results.skipped.length}`)
+}
+
+main()

package/dist/assets/build-templates/04-publish-libs.yml

@@ -0,0 +1,20 @@
+steps:
+  - task: npmAuthenticate@0
+    displayName: "[04] Authenticate npm registry"
+    condition: and(succeeded(), eq(variables['HAS_PUBLISHABLE_LIBS'], 'true'))
+    inputs:
+      workingFile: .npmrc
+
+  # Versions are set manually in each library's package.json. This step only
+  # publishes (skipping versions already on the registry), so it runs on a
+  # publish branch (master or main) for non-PR builds. The script re-checks these.
+  - script: node .build-templates/04-publish-libs.mjs
+    displayName: "[04] Publish affected libraries"
+    condition: >
+      and(succeeded(),
+          eq(variables['HAS_PUBLISHABLE_LIBS'], 'true'),
+          ne(variables['Build.Reason'], 'PullRequest'),
+          or(eq(variables['Build.SourceBranchName'], 'master'),
+             eq(variables['Build.SourceBranchName'], 'main')))
+    env:
+      NODE_AUTH_TOKEN: $(NODE_AUTH_TOKEN)

package/dist/assets/build-templates/05-publish-documentation.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Step 05 — Publish documentation.
+ *
+ * Uploads generated TypeDoc output for every affected library (internal or
+ * publishable) to the documentation blob container. Each project is uploaded to
+ * its own destination so projects never overwrite each other.
+ */
+
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { banner, log, run, runInherit, section, shellEscape, warn } from './lib/_h.mjs'
+import { loadContext, selectAffected } from './lib/context.mjs'
+import { runNxInherit } from './lib/nx.mjs'
+
+const WORKSPACE_ROOT = process.cwd()
+
+/**
+ * Resolves the base blob destination for documentation.
+ *
+ * @returns {string} Returns the base blob destination path.
+ */
+function getDocumentationDestination () {
+  const buildDefinitionName = process.env.BUILD_DEFINITIONNAME || 'local'
+
+  return `$web/${buildDefinitionName}`
+}
+
+/**
+ * Ensures the Azure CLI is available before uploading.
+ */
+function ensureAzureCliAvailable () {
+  run('az --version')
+}
+
+/**
+ * Publishes generated documentation for affected library projects.
+ */
+function main () {
+  banner('[05] Publish documentation')
+
+  const context = loadContext()
+  const documentationProjects = selectAffected(context, project => project.type.internalPackage || project.type.externalPackage)
+
+  if (documentationProjects.length === 0) {
+    banner('[05] No affected library documentation to publish')
+    return
+  }
+
+  // Generate the docs for the affected range (no-ops for projects without a doc target).
+  section('Generating documentation')
+  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 doc${range} --outputStyle=static`)
+
+  const connectionString = process.env.saDevConnectionString
+  if (!connectionString) {
+    banner('[05] Documentation hosting not configured (saDevConnectionString unset) — skipping upload')
+    return
+  }
+
+  ensureAzureCliAvailable()
+  const destination = getDocumentationDestination()
+
+  for (const project of documentationProjects) {
+    section(`Documentation: ${project.name}`)
+
+    const documentationPath = path.join(WORKSPACE_ROOT, project.root, 'doc')
+    const markerPath = path.join(documentationPath, 'index.html')
+    const projectToken = String(project.packageName || project.name || '').trim()
+    const projectDestination = `${destination}/${projectToken}`
+
+    if (!existsSync(markerPath)) {
+      warn(`[${project.name}] skipped — missing ${path.relative(WORKSPACE_ROOT, markerPath)}`)
+      continue
+    }
+
+    log(`[${project.name}] uploading to ${projectDestination}`)
+    runInherit(`az storage blob upload-batch -d ${shellEscape(projectDestination)} -s ${shellEscape(documentationPath)} --connection-string ${shellEscape(connectionString)} --overwrite`)
+  }
+
+  banner('[05] Documentation publish complete')
+}
+
+main()

package/dist/assets/build-templates/05-publish-documentation.yml

@@ -0,0 +1,20 @@
+steps:
+  - task: AzureCLI@2
+    displayName: "[05] Build and publish affected library documentation"
+    # Skipped entirely unless a docs service connection is configured.
+    condition: >
+      and(succeeded(),
+          ne(variables['docsAzureSubscription'], ''),
+          or(eq(variables['HAS_INTERNAL_PACKAGES'], 'true'),
+             eq(variables['HAS_PUBLISHABLE_LIBS'], 'true')))
+    env:
+      BUILD_DEFINITIONNAME: $(Build.DefinitionName)
+      MONOREPO_CONTEXT_FILE: $(MONOREPO_CONTEXT_FILE)
+      NX_BASE: $(NX_BASE)
+      NX_HEAD: $(NX_HEAD)
+      saDevConnectionString: $(saDevConnectionString)
+    inputs:
+      azureSubscription: $(docsAzureSubscription)
+      scriptType: pscore
+      scriptLocation: inlineScript
+      inlineScript: node .build-templates/05-publish-documentation.mjs