Compare commits

...
5 Commits
Author SHA1 Message Date
james.maes 748016f105 Merge pull request #10 from QRun-IO/develop
[minor] feat: add node_app_* job family
2026-02-27 12:59:51 -06:00
james.maesandClaude Sonnet 4.6 dbd158e5eb fix(node-app): handle corepack permission error on cimg/node
cimg/node images have pnpm pre-installed; corepack enable fails with
EACCES when trying to replace /usr/local/bin/pnpm (owned by root).
Skip corepack entirely when the package manager is already available.
Fall back to sudo corepack enable or user-local --install-directory
only when the tool is genuinely missing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-27 12:34:41 -06:00
james.maesandClaude Sonnet 4.6 1297ba10f0 fix(node-app): fix helper sourcing and cache key bugs
- Add fallback stubs to all node_app_*.sh scripts — qqq_helpers.sh
  is not present on disk in a packed orb, so the source silently fails
  and banner/require_tool are undefined (exit 127)
- Fix node_app_install cache keys to use per-pkg_manager conditionals —
  checksumming all three lockfiles simultaneously fails hard when the
  non-primary lockfiles (package-lock.json, yarn.lock) don't exist

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-27 12:31:35 -06:00
james.maes 62ae2f7d29 Merge pull request #9 from QRun-IO/feature/node-app-jobs
feat: add node_app_* job family for deployed Node.js apps
2026-02-27 12:07:31 -06:00
james.maesandClaude Opus 4.6 99fa73a581 feat: add node_app_* job family for deployed Node.js applications
Add new job family for pnpm/npm/yarn-based Node.js applications that
need CI for build/test/e2e but do NOT publish to npm (e.g., Next.js apps).

New files:
- qqq_helpers.sh: shared helper functions (banner, require_tool, source guard)
- node_app_install.sh/yml: dependency install with corepack + cache
- node_app_test.sh/yml: type-check + lint + unit tests
- node_app_build.sh/yml: production build with timing
- node_app_e2e.sh/yml: Playwright browser install + e2e tests

Jobs:
- node_app_test_only: checkout + install + test (feature branches)
- node_app_build: checkout + install + test + build + persist workspace
- node_app_e2e: attach workspace + Playwright e2e tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 12:05:30 -06:00
12 changed files with 601 additions and 0 deletions

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
description: >
Runs the production build for a Node.js application
- Executes the build script with timing output
parameters:
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
build_script:
type: string
default: "build"
description: "Name of the build script in package.json."
steps:
- run:
name: "Production build"
environment:
NODE_PKG_MANAGER: << parameters.pkg_manager >>
BUILD_SCRIPT: << parameters.build_script >>
command: <<include(scripts/node_app_build.sh)>>
+31
View File
@@ -0,0 +1,31 @@
description: >
Runs Playwright end-to-end tests for a Node.js application
- Installs Playwright browsers
- Runs e2e test suite producing JUnit output
- Stores test results and Playwright traces as artifacts
parameters:
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
e2e_script:
type: string
default: "test:e2e"
description: "Name of the e2e test script in package.json."
steps:
- run:
name: "Run Playwright e2e tests"
environment:
NODE_PKG_MANAGER: << parameters.pkg_manager >>
E2E_SCRIPT: << parameters.e2e_script >>
command: <<include(scripts/node_app_e2e.sh)>>
- store_test_results:
path: test-results/e2e
- store_artifacts:
path: test-results/e2e
destination: e2e-results
- store_artifacts:
path: playwright-report
destination: playwright-report
+72
View File
@@ -0,0 +1,72 @@
description: >
Installs dependencies for a Node.js application
- Restores dependency cache
- Runs install via configured package manager (pnpm, npm, yarn)
- Saves dependency cache
parameters:
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
steps:
# Restore cache using only the lockfile for the configured pkg manager.
# All three lockfiles cannot be checksummed simultaneously — CircleCI
# fails hard if any referenced file doesn't exist.
- when:
condition:
equal: [ pnpm, << parameters.pkg_manager >> ]
steps:
- restore_cache:
keys:
- node-app-v1-pnpm-{{ checksum "pnpm-lock.yaml" }}
- node-app-v1-pnpm-
- when:
condition:
equal: [ npm, << parameters.pkg_manager >> ]
steps:
- restore_cache:
keys:
- node-app-v1-npm-{{ checksum "package-lock.json" }}
- node-app-v1-npm-
- when:
condition:
equal: [ yarn, << parameters.pkg_manager >> ]
steps:
- restore_cache:
keys:
- node-app-v1-yarn-{{ checksum "yarn.lock" }}
- node-app-v1-yarn-
- run:
name: "Install dependencies"
environment:
NODE_PKG_MANAGER: << parameters.pkg_manager >>
command: <<include(scripts/node_app_install.sh)>>
- when:
condition:
equal: [ pnpm, << parameters.pkg_manager >> ]
steps:
- save_cache:
key: node-app-v1-pnpm-{{ checksum "pnpm-lock.yaml" }}
paths:
- node_modules
- ~/.cache/pnpm
- when:
condition:
equal: [ npm, << parameters.pkg_manager >> ]
steps:
- save_cache:
key: node-app-v1-npm-{{ checksum "package-lock.json" }}
paths:
- node_modules
- ~/.npm
- when:
condition:
equal: [ yarn, << parameters.pkg_manager >> ]
steps:
- save_cache:
key: node-app-v1-yarn-{{ checksum "yarn.lock" }}
paths:
- node_modules
- ~/.cache/yarn
+37
View File
@@ -0,0 +1,37 @@
description: >
Runs type-check, lint, and unit tests for a Node.js application
- Runs type checking, linting, and tests via package.json scripts
- Stores test results as artifacts
parameters:
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
typecheck_script:
type: string
default: "typecheck"
description: "Name of the typecheck script in package.json."
lint_script:
type: string
default: "lint"
description: "Name of the lint script in package.json."
test_script:
type: string
default: "test"
description: "Name of the test script in package.json."
steps:
- run:
name: "Run type-check, lint, and tests"
environment:
NODE_PKG_MANAGER: << parameters.pkg_manager >>
TYPECHECK_SCRIPT: << parameters.typecheck_script >>
LINT_SCRIPT: << parameters.lint_script >>
TEST_SCRIPT: << parameters.test_script >>
command: <<include(scripts/node_app_test.sh)>>
- store_test_results:
path: test-results
- store_artifacts:
path: test-results
destination: test-results
+53
View File
@@ -0,0 +1,53 @@
description: >
Build job for Node.js applications on protected branches
Runs checkout, install, test, and production build
Persists build output to workspace for downstream jobs (e.g., e2e)
executor:
name: default
tag: << parameters.node_version >>
parameters:
node_version:
type: string
default: "lts"
description: "Node.js version tag (e.g., 'lts', '18.0', '20.0')."
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
typecheck_script:
type: string
default: "typecheck"
description: "Name of the typecheck script in package.json."
lint_script:
type: string
default: "lint"
description: "Name of the lint script in package.json."
test_script:
type: string
default: "test"
description: "Name of the test script in package.json."
build_script:
type: string
default: "build"
description: "Name of the build script in package.json."
steps:
- checkout
- node_app_install:
pkg_manager: << parameters.pkg_manager >>
- node_app_test:
pkg_manager: << parameters.pkg_manager >>
typecheck_script: << parameters.typecheck_script >>
lint_script: << parameters.lint_script >>
test_script: << parameters.test_script >>
- node_app_build_step:
pkg_manager: << parameters.pkg_manager >>
build_script: << parameters.build_script >>
- persist_to_workspace:
root: .
paths:
- .next/
- node_modules/
- package.json
+29
View File
@@ -0,0 +1,29 @@
description: >
End-to-end test job for Node.js applications using Playwright
Attaches workspace from a prior build job and runs e2e tests
Stores JUnit results and Playwright traces as artifacts
executor:
name: default
tag: << parameters.node_version >>
parameters:
node_version:
type: string
default: "lts"
description: "Node.js version tag (e.g., 'lts', '18.0', '20.0')."
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
e2e_script:
type: string
default: "test:e2e"
description: "Name of the e2e test script in package.json."
steps:
- attach_workspace:
at: .
- node_app_e2e:
pkg_manager: << parameters.pkg_manager >>
e2e_script: << parameters.e2e_script >>
+40
View File
@@ -0,0 +1,40 @@
description: >
Test-only job for Node.js application feature branches
Runs checkout, dependency install, and test suite
Supports: pnpm, npm, and yarn package managers
executor:
name: default
tag: << parameters.node_version >>
parameters:
node_version:
type: string
default: "lts"
description: "Node.js version tag (e.g., 'lts', '18.0', '20.0')."
pkg_manager:
type: string
default: "pnpm"
description: "Package manager to use (e.g., 'pnpm', 'npm', 'yarn')."
typecheck_script:
type: string
default: "typecheck"
description: "Name of the typecheck script in package.json."
lint_script:
type: string
default: "lint"
description: "Name of the lint script in package.json."
test_script:
type: string
default: "test"
description: "Name of the test script in package.json."
steps:
- checkout
- node_app_install:
pkg_manager: << parameters.pkg_manager >>
- node_app_test:
pkg_manager: << parameters.pkg_manager >>
typecheck_script: << parameters.typecheck_script >>
lint_script: << parameters.lint_script >>
test_script: << parameters.test_script >>
+43
View File
@@ -0,0 +1,43 @@
#!/bin/bash
############################################################################
## node_app_build.sh
## Node Application Production Build
##
## Runs the production build for a Node.js application with timing output.
##
## Environment Variables:
## NODE_PKG_MANAGER - Package manager to use (default: pnpm)
## BUILD_SCRIPT - Script name for the build step (default: build)
##
## Usage: Called by CircleCI orb command node_app_build_step
## Output: Production build artifacts
############################################################################
set -e
# Source shared helpers (no-op in packed orb — file won't exist at runtime)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
# shellcheck disable=SC1091
source "${SCRIPT_DIR}/qqq_helpers.sh" 2>/dev/null || true
# Fallback stubs when helpers couldn't be sourced (packed orb environment)
if ! type banner &>/dev/null; then
banner() { echo ""; echo "========================================"; echo " ${1:-}"; echo "========================================"; echo ""; }
require_tool() { command -v "$1" &>/dev/null || { echo "ERROR: Required tool '$1' is not installed."; exit 1; }; }
fi
NODE_PKG_MANAGER="${NODE_PKG_MANAGER:-pnpm}"
BUILD_SCRIPT="${BUILD_SCRIPT:-build}"
banner "Production Build"
require_tool "${NODE_PKG_MANAGER}"
START_TIME=$(date +%s)
"${NODE_PKG_MANAGER}" run "${BUILD_SCRIPT}"
END_TIME=$(date +%s)
ELAPSED=$((END_TIME - START_TIME))
echo "Build completed in ${ELAPSED}s"
+56
View File
@@ -0,0 +1,56 @@
#!/bin/bash
############################################################################
## node_app_e2e.sh
## Node Application End-to-End Test Runner
##
## Installs Playwright browsers and runs e2e tests producing JUnit output.
##
## Environment Variables:
## NODE_PKG_MANAGER - Package manager to use (default: pnpm)
## E2E_SCRIPT - Script name for e2e tests (default: test:e2e)
##
## Usage: Called by CircleCI orb command node_app_e2e
## Output: JUnit test results in test-results/e2e/ and Playwright traces
############################################################################
set -e
# Source shared helpers (no-op in packed orb — file won't exist at runtime)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
# shellcheck disable=SC1091
source "${SCRIPT_DIR}/qqq_helpers.sh" 2>/dev/null || true
# Fallback stubs when helpers couldn't be sourced (packed orb environment)
if ! type banner &>/dev/null; then
banner() { echo ""; echo "========================================"; echo " ${1:-}"; echo "========================================"; echo ""; }
require_tool() { command -v "$1" &>/dev/null || { echo "ERROR: Required tool '$1' is not installed."; exit 1; }; }
fi
NODE_PKG_MANAGER="${NODE_PKG_MANAGER:-pnpm}"
E2E_SCRIPT="${E2E_SCRIPT:-test:e2e}"
banner "End-to-End Tests (Playwright)"
require_tool "${NODE_PKG_MANAGER}"
###########################
## Install Browsers ##
###########################
echo "Installing Playwright browsers..."
npx playwright install --with-deps chromium
###########################
## Run E2E Tests ##
###########################
mkdir -p test-results/e2e
echo "Running e2e tests..."
"${NODE_PKG_MANAGER}" run "${E2E_SCRIPT}" || E2E_EXIT=$?
if [[ "${E2E_EXIT:-0}" -ne 0 ]]; then
echo "E2E tests failed with exit code ${E2E_EXIT}"
exit "${E2E_EXIT}"
fi
echo "E2E tests completed successfully"
+96
View File
@@ -0,0 +1,96 @@
#!/bin/bash
############################################################################
## node_app_install.sh
## Node Application Dependency Installation
##
## Installs dependencies for a Node.js application project using the
## configured package manager (pnpm, npm, or yarn). Enables corepack
## when using pnpm or yarn.
##
## Environment Variables:
## NODE_PKG_MANAGER - Package manager to use (default: pnpm)
##
## Usage: Called by CircleCI orb command node_app_install
## Output: Installed node_modules and validated lockfile
############################################################################
set -e
# Source shared helpers (no-op in packed orb — file won't exist at runtime)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
# shellcheck disable=SC1091
source "${SCRIPT_DIR}/qqq_helpers.sh" 2>/dev/null || true
# Fallback stubs when helpers couldn't be sourced (packed orb environment)
if ! type banner &>/dev/null; then
banner() { echo ""; echo "========================================"; echo " ${1:-}"; echo "========================================"; echo ""; }
require_tool() { command -v "$1" &>/dev/null || { echo "ERROR: Required tool '$1' is not installed."; exit 1; }; }
fi
NODE_PKG_MANAGER="${NODE_PKG_MANAGER:-pnpm}"
banner "Install Dependencies (${NODE_PKG_MANAGER})"
###########################
## Enable Corepack ##
###########################
if [[ "${NODE_PKG_MANAGER}" == "pnpm" || "${NODE_PKG_MANAGER}" == "yarn" ]]; then
if command -v "${NODE_PKG_MANAGER}" &>/dev/null; then
echo "${NODE_PKG_MANAGER} already available: $(${NODE_PKG_MANAGER} --version)"
else
echo "Installing ${NODE_PKG_MANAGER} via corepack..."
# corepack enable requires write access to /usr/local/bin; use sudo if available
if sudo -n corepack enable 2>/dev/null; then
echo "corepack enable succeeded (sudo)"
else
corepack enable --install-directory "${HOME}/.local/bin"
export PATH="${HOME}/.local/bin:${PATH}"
fi
corepack prepare "${NODE_PKG_MANAGER}@latest" --activate
fi
fi
require_tool "${NODE_PKG_MANAGER}"
###########################
## Lockfile Validation ##
###########################
case "${NODE_PKG_MANAGER}" in
pnpm)
if [[ ! -f pnpm-lock.yaml ]]; then
echo "WARNING: pnpm-lock.yaml not found"
fi
;;
npm)
if [[ ! -f package-lock.json ]]; then
echo "WARNING: package-lock.json not found"
fi
;;
yarn)
if [[ ! -f yarn.lock ]]; then
echo "WARNING: yarn.lock not found"
fi
;;
*)
echo "ERROR: Unsupported package manager '${NODE_PKG_MANAGER}'"
exit 1
;;
esac
###########################
## Install ##
###########################
case "${NODE_PKG_MANAGER}" in
pnpm)
pnpm install --frozen-lockfile
;;
npm)
npm ci
;;
yarn)
yarn install --immutable
;;
esac
echo "Dependencies installed successfully with ${NODE_PKG_MANAGER}"
+73
View File
@@ -0,0 +1,73 @@
#!/bin/bash
############################################################################
## node_app_test.sh
## Node Application Test Runner
##
## Runs type-checking, linting, and unit tests for a Node.js application.
## Each step can be overridden via environment variables to support
## projects with non-standard script names.
##
## Environment Variables:
## NODE_PKG_MANAGER - Package manager to use (default: pnpm)
## TYPECHECK_SCRIPT - Script name for type checking (default: typecheck)
## LINT_SCRIPT - Script name for linting (default: lint)
## TEST_SCRIPT - Script name for unit tests (default: test)
##
## Usage: Called by CircleCI orb command node_app_test
## Output: Test results and lint/typecheck status
############################################################################
set -e
# Source shared helpers (no-op in packed orb — file won't exist at runtime)
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
# shellcheck disable=SC1091
source "${SCRIPT_DIR}/qqq_helpers.sh" 2>/dev/null || true
# Fallback stubs when helpers couldn't be sourced (packed orb environment)
if ! type banner &>/dev/null; then
banner() { echo ""; echo "========================================"; echo " ${1:-}"; echo "========================================"; echo ""; }
require_tool() { command -v "$1" &>/dev/null || { echo "ERROR: Required tool '$1' is not installed."; exit 1; }; }
fi
NODE_PKG_MANAGER="${NODE_PKG_MANAGER:-pnpm}"
TYPECHECK_SCRIPT="${TYPECHECK_SCRIPT:-typecheck}"
LINT_SCRIPT="${LINT_SCRIPT:-lint}"
TEST_SCRIPT="${TEST_SCRIPT:-test}"
############################################################################
## has_script - check if a script exists in package.json
############################################################################
has_script() {
local name="$1"
node -e "
const pkg = require('./package.json');
process.exit(pkg.scripts && pkg.scripts['${name}'] ? 0 : 1);
"
}
############################################################################
## run_step - run a package.json script if it exists
############################################################################
run_step() {
local label="$1"
local script="$2"
banner "${label}"
if has_script "${script}"; then
"${NODE_PKG_MANAGER}" run "${script}"
else
echo "SKIP: No '${script}' script found in package.json"
fi
}
###########################
## Run Steps ##
###########################
run_step "Type Check" "${TYPECHECK_SCRIPT}"
run_step "Lint" "${LINT_SCRIPT}"
run_step "Unit Tests" "${TEST_SCRIPT}"
echo "All test steps completed successfully"
+50
View File
@@ -0,0 +1,50 @@
#!/bin/bash
############################################################################
## qqq_helpers.sh
## QQQ Orb Shared Helper Functions
##
## Provides common utilities used across node_app_* scripts:
## - Double-source guard to prevent re-initialization
## - Banner display for step identification
## - Tool existence checking
##
## Usage: source qqq_helpers.sh (from other scripts)
## Output: Exports helper functions into the calling script
############################################################################
# Double-source guard
if [[ -n "${_QQQ_HELPERS_LOADED:-}" ]]; then
# shellcheck disable=SC2317
return 0 2>/dev/null || true
fi
_QQQ_HELPERS_LOADED=1
############################################################################
## banner
## Print a visible section header
##
## Usage: banner "Step Name"
############################################################################
banner() {
local msg="$1"
echo ""
echo "========================================"
echo " ${msg}"
echo "========================================"
echo ""
}
############################################################################
## require_tool
## Verify a CLI tool is available, exit 1 if missing
##
## Usage: require_tool "pnpm"
############################################################################
require_tool() {
local tool="$1"
if ! command -v "${tool}" &>/dev/null; then
echo "ERROR: Required tool '${tool}' is not installed."
exit 1
fi
}