@crossdelta/platform-sdk 0.26.0 → 0.26.2

package/bin/templates/workspace/.github/actions/check-image-tag-exists/ghcr.js

@@ -0,0 +1,87 @@
+/**
+ * GHCR tag lookup shared by check-image-tag-exists and generate-scope-matrix.
+ *
+ * One API client for both, so the build job and the matrix ask GHCR the same question the same way.
+ * generate-scope-matrix/index.js requires this file by its relative path: moving it breaks that action.
+ */
+
+const PAGE_SIZE = 100
+
+/**
+ * Resolves the GHCR package prefix: the explicit input, else $GHCR_REPOSITORY_PREFIX, else the
+ * repository name, else 'platform'.
+ * @param {string} input - The action's repository-prefix input, possibly empty
+ * @param {Record<string, string | undefined>} env - Process environment
+ * @returns {string}
+ */
+const resolveRepositoryPrefix = (input, env) =>
+  input || env.GHCR_REPOSITORY_PREFIX || env.GITHUB_REPOSITORY?.split('/')[1] || 'platform'
+
+/**
+ * Checks if the target tag exists in a list of container versions.
+ * @param {Object[]} versions - Array of version objects from GitHub API
+ * @param {string} targetTag - The tag to search for
+ * @returns {boolean} True if tag is found
+ */
+const tagExistsInVersions = (versions, targetTag) =>
+  versions.some((version) => {
+    const tags = version?.metadata?.container?.tags
+    return Array.isArray(tags) && tags.includes(targetTag)
+  })
+
+/**
+ * Creates a GHCR client for one package owner and repository prefix.
+ * @param {Object} options
+ * @param {string} options.owner - GitHub organization that owns the container packages
+ * @param {string} options.prefix - Package prefix, e.g. 'platform' for 'platform/storefront'
+ * @param {string} options.token - Token with read:packages
+ * @param {number} [options.maxPages=5] - Pages of 100 versions to inspect before giving up
+ * @param {typeof fetch} [options.fetchImpl=fetch] - Injected for tests
+ * @returns {{tagExists: (shortName: string, tag: string) => Promise<boolean>}}
+ *   `tagExists` resolves false when the package does not exist yet (404) and rejects on any other
+ *   API error, so a caller decides itself whether an unknown answer means "build".
+ */
+const createGhcrClient = ({ owner, prefix, token, maxPages = 5, fetchImpl = fetch }) => {
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  }
+
+  const fetchVersions = async (shortName, page) => {
+    const encodedPackage = encodeURIComponent(`${prefix}/${shortName}`)
+    const url = `https://api.github.com/orgs/${owner}/packages/container/${encodedPackage}/versions?per_page=${PAGE_SIZE}&page=${page}`
+    const response = await fetchImpl(url, { headers })
+
+    // 404 means the package doesn't exist yet (first build)
+    if (response.status === 404) {
+      return { notFound: true, versions: [], hasMore: false }
+    }
+
+    if (!response.ok) {
+      const body = await response.text()
+      throw new Error(`GitHub API error (${response.status}): ${body}`)
+    }
+
+    const data = await response.json()
+    const versions = Array.isArray(data) ? data : []
+    return { notFound: false, versions, hasMore: versions.length === PAGE_SIZE }
+  }
+
+  const tagExists = async (shortName, tag) => {
+    const targetTag = tag.trim()
+
+    for (let page = 1; page <= maxPages; page += 1) {
+      const { versions, hasMore, notFound } = await fetchVersions(shortName, page)
+      if (notFound) return false
+      if (tagExistsInVersions(versions, targetTag)) return true
+      if (!hasMore) break
+    }
+
+    return false
+  }
+
+  return { tagExists }
+}
+
+module.exports = { createGhcrClient, resolveRepositoryPrefix, tagExistsInVersions }

package/bin/templates/workspace/.github/actions/check-image-tag-exists/index.js

@@ -16,6 +16,7 @@
 
 const { appendFileSync } = require('node:fs')
 const { exit } = require('node:process')
+const { createGhcrClient, resolveRepositoryPrefix } = require('./ghcr.js')
 
 /**
  * Builds environment variable keys for GitHub Actions inputs.
@@ -71,103 +72,17 @@ const githubToken = getInput('github-token', { required: true })
 
 // Optional inputs - defaults from environment for portability
 const repositoryOwner = getInput('repository-owner', { defaultValue: process.env.GITHUB_REPOSITORY_OWNER })
-const repositoryPrefixInput = getInput('repository-prefix')
-const repositoryPrefix =
-  repositoryPrefixInput || process.env.GHCR_REPOSITORY_PREFIX || process.env.GITHUB_REPOSITORY?.split('/')[1] || 'platform'
+const repositoryPrefix = resolveRepositoryPrefix(getInput('repository-prefix'), process.env)
 const maxPages = Number(getInput('max-pages', { defaultValue: '5' }))
 
-// GitHub API request headers
-const headers = {
-  Authorization: `Bearer ${githubToken}`,
-  Accept: 'application/vnd.github+json',
-  'X-GitHub-Api-Version': '2022-11-28',
-}
-
-// Construct the full package name (e.g., 'platform/storefront')
-const packageName = `${repositoryPrefix}/${scopeShortName}`
-const encodedPackage = encodeURIComponent(packageName)
-
-/**
- * Fetches a page of container versions from the GitHub Packages API.
- * @param {number} page - Page number (1-indexed)
- * @returns {Promise<Object>} Result with versions array, hasMore flag, and notFound flag
- */
-const fetchVersions = async (page) => {
-  const url = `https://api.github.com/orgs/${repositoryOwner}/packages/container/${encodedPackage}/versions?per_page=100&page=${page}`
-  const response = await fetch(url, { headers })
-
-  // 404 means the package doesn't exist yet (first build)
-  if (response.status === 404) {
-    return { notFound: true, versions: [], hasMore: false }
-  }
-
-  if (!response.ok) {
-    const body = await response.text()
-    throw new Error(`GitHub API error (${response.status}): ${body}`)
-  }
-
-  const data = await response.json()
-  const versions = Array.isArray(data) ? data : []
-  return {
-    versions,
-    hasMore: versions.length === 100, // Full page means there might be more
-    notFound: false,
-  }
-}
-
-/**
- * Checks if the target tag exists in a list of container versions.
- * @param {Object[]} versions - Array of version objects from GitHub API
- * @param {string} targetTag - The tag to search for
- * @returns {boolean} True if tag is found
- */
-const tagExistsInVersions = (versions, targetTag) => {
-  for (const version of versions) {
-    const tags = version?.metadata?.container?.tags
-    if (!Array.isArray(tags)) continue
-    if (tags.includes(targetTag)) {
-      return true
-    }
-  }
-  return false
-}
-
-/**
- * Checks if the image tag exists in GHCR by paginating through all versions.
- * @returns {Promise<boolean>} True if tag exists
- */
-const check = async () => {
-  const targetTag = imageTag.trim()
-
-  // Paginate through versions until we find the tag or run out of pages
-  for (let page = 1; page <= maxPages; page += 1) {
-    const { versions, hasMore, notFound } = await fetchVersions(page)
-
-    // Package doesn't exist yet - tag definitely doesn't exist
-    if (notFound) {
-      return false
-    }
-
-    // Check if target tag is in this page
-    if (tagExistsInVersions(versions, targetTag)) {
-      return true
-    }
-
-    // No more pages to check
-    if (!hasMore) {
-      break
-    }
-  }
-
-  return false
-}
+const ghcr = createGhcrClient({ owner: repositoryOwner, prefix: repositoryPrefix, token: githubToken, maxPages })
 
 /**
  * Main entry point - runs the check and outputs the result.
  */
 const run = async () => {
   try {
-    const exists = await check()
+    const exists = await ghcr.tagExists(scopeShortName, imageTag)
     setOutput('exists', String(exists))
   } catch (error) {
     console.error('Failed to check image tag existence:', error)

package/bin/templates/workspace/.github/actions/generate-scope-matrix/action.yml

@@ -11,11 +11,29 @@ inputs:
     description: When true, include ALL discovered scopes regardless of changes
     required: false
     default: 'false'
+  only-unbuilt:
+    description: >-
+      When true, include every scope whose checksum tag is not in GHCR yet, whatever changed.
+      Needs `bun install` before this step (the checksum prunes with the workspace's turbo) and
+      `github-token`. Ignored when force-all is true.
+    required: false
+    default: 'false'
+  github-token:
+    description: Token with read:packages, used by only-unbuilt to query GHCR
+    required: false
 outputs:
   scopes:
     description: JSON array describing scopes for the matrix strategy
   scopes_count:
     description: Number of scopes detected in the matrix
+  scope_tags:
+    description: >-
+      JSON object mapping every scope's short name to the checksum tag computed for this commit
+      (only-unbuilt); `{}` otherwise
+  tags_changed:
+    description: >-
+      'true' when a scope's checksum tag differs from the one at the diff base (GITHUB_EVENT_BEFORE),
+      even if its image exists, as after a revert (only-unbuilt); 'false' otherwise
 runs:
   using: node24
   main: index.js

package/bin/templates/workspace/.github/actions/generate-scope-matrix/index.js

@@ -13,14 +13,20 @@
  *   with:
  *     scope-roots: apps,services
  *
- * @outputs scopes - JSON array of scope objects [{name, shortName, dir, run}]
+ * With `only-unbuilt`, a scope is in the matrix when GHCR lacks its checksum tag instead of when
+ * its directory changed, and each entry carries that tag as `imageTag`.
+ *
+ * @outputs scopes - JSON array of scope objects [{name, shortName, dir, run, imageTag?}]
  * @outputs scopes_count - Number of scopes in the matrix
+ * @outputs tags_changed - 'true' when a scope's tag differs from the diff base's (only-unbuilt)
  */
 
 const { appendFileSync } = require('node:fs')
 const { spawnSync } = require('node:child_process')
-const { existsSync, readdirSync, readFileSync, statSync } = require('node:fs')
+const { existsSync, readdirSync, readFileSync, statSync, symlinkSync } = require('node:fs')
 const { basename, join, relative } = require('node:path')
+const { createGhcrClient, resolveRepositoryPrefix } = require('../check-image-tag-exists/ghcr.js')
+const { changedScopeTags, scopeTagMap, selectUnbuilt } = require('./select.js')
 
 /** Default directories to scan for scopes (Turborepo convention) */
 const defaultRoots = ['apps', 'services']
@@ -317,13 +323,144 @@ const hasGitDiffChanges = (dir, changedFilesFromEvent, beforeRef, headRef) => {
 const scopeHasChanges = (scopeDir, changedFilesFromEvent, beforeRef, headRef) =>
   hasGitDiffChanges(scopeDir, changedFilesFromEvent, beforeRef, headRef)
 
+/**
+ * Checks if a boolean input is enabled.
+ * @param {string} name - Input name as defined in action.yml
+ * @returns {boolean} True for 'true', '1' or 'yes'
+ */
+const isEnabled = (name) => {
+  const value = getInput(name)
+  return value === 'true' || value === '1' || value === 'yes'
+}
+
 /**
  * Checks if the force-all input is enabled.
  * @returns {boolean} True if all scopes should be force-included
  */
-const isForceAll = () => {
-  const value = getInput('force-all')
-  return value === 'true' || value === '1' || value === 'yes'
+const isForceAll = () => isEnabled('force-all')
+
+/**
+ * Prunes a scope and computes its checksum tag through the script the build job runs.
+ * @param {{name: string, shortName: string, dir: string}} scope - Scope to checksum
+ * @param {string} [cwd=process.cwd()] - Workspace root to prune from
+ * @returns {string} The scope's image tag
+ */
+const computeScopeChecksum = (scope, cwd = process.cwd()) => {
+  const script = join(__dirname, 'scope-checksum.sh')
+  // The GHCR token stays out of turbo's environment: the prune needs no credentials.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^INPUT_GITHUB[-_]TOKEN$/i.test(key)))
+  const result = spawnSync('bash', [script, scope.name, scope.shortName, scope.dir], {
+    cwd,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'inherit'],
+  })
+
+  if (result.error || result.status !== 0) {
+    throw new Error(`Checksum for ${scope.name} failed (exit ${result.status}): ${result.error ?? ''}`)
+  }
+
+  return result.stdout.trim()
+}
+
+/**
+ * Looks up every scope's checksum tag in GHCR. An unanswered lookup counts as missing, so the
+ * scope is built: the build job checks the tag again before it pushes.
+ * @param {Map} scopeMap - Discovered scopes
+ * @returns {Promise<Array<{scope: Object, imageTag: string, exists: boolean}>>}
+ */
+const lookupScopeTags = async (scopeMap) => {
+  const ghcr = createGhcrClient({
+    owner: process.env.GITHUB_REPOSITORY_OWNER,
+    prefix: resolveRepositoryPrefix('', process.env),
+    token: getInput('github-token'),
+  })
+  const lookups = []
+
+  for (const scope of scopeMap.values()) {
+    const imageTag = computeScopeChecksum(scope)
+    const exists = await ghcr.tagExists(scope.shortName, imageTag).catch((error) => {
+      console.warn(`GHCR lookup for ${scope.shortName} failed, building it:`, error)
+      return false
+    })
+    console.log(`${scope.shortName} ${imageTag} ${exists ? 'exists' : 'missing'}`)
+    lookups.push({ scope, imageTag, exists })
+  }
+
+  return lookups
+}
+
+/**
+ * Runs git and throws with its stderr when it fails.
+ * @param {string[]} args - git arguments
+ */
+const runGit = (args) => {
+  const result = spawnSync('git', args, { encoding: 'utf8' })
+  if (result.error || result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.error ?? result.stderr}`)
+  }
+}
+
+/**
+ * Checks out the base commit into a temporary worktree that borrows this checkout's node_modules
+ * for turbo.
+ * @param {string} baseDir - Worktree directory
+ * @param {string} baseRef - Commit to check out
+ * @returns {boolean} False when the worktree could not be created (it is then removed again)
+ */
+const addBaseTree = (baseDir, baseRef) => {
+  try {
+    runGit(['worktree', 'add', '--detach', '--force', baseDir, baseRef])
+  } catch (error) {
+    console.warn(`No base tree at ${baseRef}, counting every scope as changed:`, error.message)
+    return false
+  }
+  try {
+    symlinkSync(join(process.cwd(), 'node_modules'), join(baseDir, 'node_modules'))
+    return true
+  } catch (error) {
+    console.warn('No node_modules in the base tree, counting every scope as changed:', error.message)
+    removeBaseTree(baseDir)
+    return false
+  }
+}
+
+/**
+ * Removes the temporary worktree; a failure only warns, the tags are computed by then.
+ * @param {string} baseDir - Worktree directory
+ */
+const removeBaseTree = (baseDir) => {
+  try {
+    runGit(['worktree', 'remove', '--force', baseDir])
+  } catch (error) {
+    console.warn('Could not remove the base tree:', error.message)
+  }
+}
+
+/**
+ * Computes every scope's checksum tag at the base commit, in a temporary worktree under out/. A
+ * scope the base cannot checksum (absent there, renamed) is left out and so counts as changed;
+ * without a base tree every scope does, so the deploy runs.
+ * @param {Map} scopeMap - Discovered scopes
+ * @param {string} baseRef - Diff base commit
+ * @returns {Record<string, string>} Short name → tag at the base
+ */
+const computeBaseScopeTags = (scopeMap, baseRef) => {
+  const baseDir = join(process.cwd(), 'out', '.base-tree')
+  if (!addBaseTree(baseDir, baseRef)) return {}
+  try {
+    const tags = {}
+    for (const scope of scopeMap.values()) {
+      try {
+        tags[scope.shortName] = computeScopeChecksum(scope, baseDir)
+      } catch (error) {
+        console.warn(`No base tag for ${scope.shortName}, counting it as changed:`, error.message)
+      }
+    }
+    return tags
+  } finally {
+    removeBaseTree(baseDir)
+  }
 }
 
 /**
@@ -358,13 +495,39 @@ const buildMatrix = (scopeMap, changedFilesFromEvent, beforeRef, headRef, forced
   return [...base, ...forced]
 }
 
-// Main execution
-const roots = loadRoots()
-const scopeMap = discoverScopes(roots)
-const changedFilesFromEvent = loadEventChangedFiles(process.env.GITHUB_EVENT_PATH)
-const { beforeRef, headRef } = getCommitRefs()
-const forcedShortNames = loadForcedShortNames()
-const matrix = buildMatrix(scopeMap, changedFilesFromEvent, beforeRef, headRef, forcedShortNames)
+/**
+ * Builds the matrix: with only-unbuilt, every scope whose checksum tag GHCR lacks, every scope's
+ * computed tag and the scopes whose tag differs from the base's; otherwise the changed scopes (or
+ * all with force-all), no tags and no tag changes.
+ * @returns {Promise<{matrix: Object[], scopeTags: Record<string, string>, changedTags: string[]}>}
+ */
+const resolveMatrix = async () => {
+  const scopeMap = discoverScopes(loadRoots())
+  const forcedShortNames = loadForcedShortNames()
+  const { beforeRef, headRef } = getCommitRefs()
+
+  if (isEnabled('only-unbuilt') && !isForceAll()) {
+    const lookups = await lookupScopeTags(scopeMap)
+    const scopeTags = scopeTagMap(lookups)
+    const baseScopeTags = beforeRef ? computeBaseScopeTags(scopeMap, beforeRef) : {}
+    const changedTags = changedScopeTags(scopeTags, baseScopeTags)
+    console.log(`Tags changed since ${beforeRef ?? 'no base'}: ${changedTags.join(' ') || 'none'}`)
+    return { matrix: selectUnbuilt(lookups, forcedShortNames), scopeTags, changedTags }
+  }
+
+  const changedFilesFromEvent = loadEventChangedFiles(process.env.GITHUB_EVENT_PATH)
+  const matrix = buildMatrix(scopeMap, changedFilesFromEvent, beforeRef, headRef, forcedShortNames)
+  return { matrix, scopeTags: {}, changedTags: [] }
+}
 
-setOutput('scopes', JSON.stringify(matrix))
-setOutput('scopes_count', String(matrix.length))
+resolveMatrix()
+  .then(({ matrix, scopeTags, changedTags }) => {
+    setOutput('scopes', JSON.stringify(matrix))
+    setOutput('scopes_count', String(matrix.length))
+    setOutput('scope_tags', JSON.stringify(scopeTags))
+    setOutput('tags_changed', String(changedTags.length > 0))
+  })
+  .catch((error) => {
+    console.error('Failed to generate the scope matrix:', error)
+    process.exit(1)
+  })

package/bin/templates/workspace/.github/actions/generate-scope-matrix/scope-checksum.js

@@ -0,0 +1,81 @@
+/**
+ * Usage: node scope-checksum.js <pruned-out-dir> <scope-dir>
+ *
+ * Prints the checksum of a pruned scope (out/<short-name>) over its git-tracked files, without the
+ * workspaces the scope does not reach: their directories under json/ and full/ and their blocks in
+ * bun.lock. Called by scope-checksum.sh from the workspace root after `turbo prune`.
+ */
+
+const { execFileSync } = require('node:child_process')
+const { createHash } = require('node:crypto')
+const { lstatSync, readdirSync, readFileSync } = require('node:fs')
+const { join, relative, sep } = require('node:path')
+const {
+  checksumOf,
+  foreignWorkspaces,
+  isForeignPath,
+  isSourcePath,
+  stripLockWorkspaces,
+  workspaceManifest,
+} = require('./scope-tree.js')
+
+/**
+ * Lists the regular files below a directory, like `find -type f`: symlinks are not followed or listed.
+ * @param {string} root - Directory to walk
+ * @returns {string[]} Paths relative to root, '/'-separated
+ */
+const listFiles = (root) => {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const path = join(dir, entry)
+      const stats = lstatSync(path)
+      if (stats.isDirectory()) walk(path)
+      else if (stats.isFile()) files.push(relative(root, path).split(sep).join('/'))
+    }
+  }
+  walk(root)
+  return files
+}
+
+/**
+ * Reads every workspace manifest of the pruned tree's json/ half, the root manifest excluded.
+ * @param {string} outDir - out/<short-name>
+ * @param {string[]} files - Files of outDir
+ * @returns {Map<string, import('./scope-tree.js').WorkspaceManifest>}
+ */
+const readManifests = (outDir, files) =>
+  new Map(
+    files
+      .filter((path) => path.startsWith('json/') && path.endsWith('/package.json') && !path.includes('/node_modules/'))
+      .filter((path) => path !== 'json/package.json')
+      .map((path) => [
+        path.slice('json/'.length, -'/package.json'.length),
+        workspaceManifest(JSON.parse(readFileSync(join(outDir, path), 'utf8'))),
+      ]),
+  )
+
+const sha256 = (content) => createHash('sha256').update(content).digest('hex')
+
+/**
+ * Lists the files git tracks in the current directory, which must be the workspace root.
+ * @returns {Set<string>} '/'-separated paths
+ */
+const readTrackedPaths = () =>
+  new Set(execFileSync('git', ['ls-files', '-z'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }).split('\0').filter(Boolean))
+
+const [outDir, scopeDir] = process.argv.slice(2)
+const files = listFiles(outDir)
+const trackedPaths = readTrackedPaths()
+const foreignDirs = foreignWorkspaces(scopeDir, readManifests(outDir, files))
+const entries = files
+  .filter((path) => isSourcePath(path, trackedPaths))
+  .filter((path) => !isForeignPath(path, foreignDirs))
+  .map((path) => {
+    const content = readFileSync(join(outDir, path))
+    const isLock = path === 'bun.lock' || path.endsWith('/bun.lock')
+    return { path, digest: sha256(isLock ? stripLockWorkspaces(content.toString('utf8'), foreignDirs) : content) }
+  })
+
+console.error(`${scopeDir}: left out of the checksum: ${foreignDirs.join(', ') || 'nothing'}`)
+console.log(checksumOf(entries))

package/bin/templates/workspace/.github/actions/generate-scope-matrix/scope-checksum.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Usage: scope-checksum.sh <scope-name> <scope-short-name> <scope-dir>
+#
+# Prunes one scope into out/<short-name> and prints its checksum, which is the scope's image tag.
+# Workspaces the scope does not depend on (scope-checksum.js) stay in the build context but not in
+# the checksum.
+# The build job and generate-scope-matrix (only-unbuilt) both call this script, so the tag the
+# matrix looks up in GHCR is the tag the build job pushes. Run from the workspace root after
+# `bun install`: `bunx` must resolve the workspace's own turbo, another version prunes differently.
+set -euo pipefail
+
+SCOPE_NAME="$1"
+SHORT_NAME="$2"
+SCOPE_DIR="$3"
+OUT_DIR="out/${SHORT_NAME}"
+
+bunx turbo prune --scope="${SCOPE_NAME}" --docker --out-dir "${OUT_DIR}" >&2
+# turbo prune omits the bun patchedDependencies patch files. Copy them into the
+# pruned context so `bun install` can apply them (rxdb patch for studio/storefront).
+# Done before the scope checksum so a patch change busts the image tag.
+if [ -d patches ]; then
+  cp -rT patches "${OUT_DIR}/full/patches"
+fi
+
+node "$(dirname "$0")/scope-checksum.js" "${OUT_DIR}" "${SCOPE_DIR}"