Compare commits

...
15 Commits
Author SHA1 Message Date
james.maes 5196609974 Merge pull request #16 from QRun-IO/develop
release: publish npm Trusted Publishing support in orb 0.6.7
2026-09-29 14:18:44 -05:00
james.maes 988401023a Merge pull request #15 from QRun-IO/feature/GH-912-npm-trusted-publishing
fix(ci): support CircleCI npm Trusted Publishing
2026-09-29 14:17:01 -05:00
james.maes e23bd4588d test(ci): preserve stdin for npm subprocesses (#912) 2026-09-29 14:14:32 -05:00
james.maes 51e9bba5b0 fix(ci): support tokenless npm publishing (#912)
Refs QRun-IO/qqq#912. Use CircleCI OIDC with isolated npm configuration and retain legacy authentication by default.
2026-09-29 14:09:04 -05:00
james.maes 49e09a6776 Merge pull request #14 from QRun-IO/develop
release: publish orb log-safety fix as 0.6.6
2026-09-29 13:38:22 -05:00
james.maes dae3f4b677 fix: keep Maven settings out of orb logs (#13)
* fix: keep Maven settings out of orb logs (#12)

* test: enforce Maven log-safety guard in CI (#12)

Run the reviewed output regression before publishing and capture both output streams. Refs QRun-IO/qqq#903.
2026-09-29 13:23:43 -05:00
James MaesandClaude Opus 4.8 20d324957d docs: add CLAUDE.md pointer to QQQ knowledge-base dossier + hub
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-12 05:31:59 -05:00
james.maesandClaude Opus 4.7 bdff16ff95 chore: add CODEOWNERS pointing to sole maintainer
Architecture audit pass 2026-05-21. Minimal CODEOWNERS file
making the implicit ownership explicit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 17:13:51 -05:00
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
james.maes 6514aaa688 Merge pull request #8 from QRun-IO/develop
fix(ci): remove legacy tag-based publish workflow
2026-01-31 18:46:54 -06:00
james.maes c561e4d290 fix(ci): remove legacy tag-based publish workflow 2026-01-31 18:43:52 -06:00
24 changed files with 885 additions and 30 deletions

No files matched your search

+7 -21
View File
@@ -12,13 +12,6 @@ filters: &filters
tags:
only: /.*/
# Filter for release tags.
release-filters: &release-filters
branches:
ignore: /.*/
tags:
only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
# Auto-publish filters.
develop-filters: &develop-filters
branches:
@@ -33,9 +26,15 @@ jobs:
# You may want to add additional validation steps to ensure the commands are working as expected.
command-test:
docker:
- image: cimg/base:current
- image: cimg/node:24.21
steps:
- checkout
- run:
name: Verify Maven settings stay out of build logs
command: bash tests/test_maven_settings_output.sh
- run:
name: Verify npm publisher authentication and dist-tags
command: python3 tests/test_node_npm_publish.py
# Run your orb's commands to validate them.
- qqq-orb/install_asciidoctor
@@ -103,19 +102,6 @@ workflows:
# Test your orb's commands in a custom job and test your orb's jobs directly as a part of this workflow.
- command-test:
filters: *filters
# The orb must be re-packed for publishing, and saved to the workspace.
- orb-tools/pack:
filters: *release-filters
- orb-tools/publish:
orb_name: kingsrook/qqq-orb
vcs_type: << pipeline.project.type >>
pub_type: production
# Ensure this job requires all test jobs and the pack job.
requires:
- orb-tools/pack
- command-test
context: orb-publishing
filters: *release-filters
# Auto-publish dev snapshot on develop
- publish-dev-snapshot:
context: orb-publishing
+1
View File
@@ -0,0 +1 @@
* @KofTwentyTwo
+12
View File
@@ -80,3 +80,15 @@ The orb uses CircleCI's "unpacked" format. YAML files in `src/` are packed into
- `MAVEN_USERNAME`, `MAVEN_PASSWORD` - Sonatype credentials
- `GPG_PRIVATE_KEY_B64`, `GPG_KEYNAME`, `GPG_PASSPHRASE` - GPG signing
- `GITHUB_TOKEN` - GitHub API access
## Knowledge base
Deep-review dossiers for this repo and the wider QQQ platform live in the second-brain
vault (Obsidian, `R:/Git.Local/KofTwentyTwo/second-brain`):
- Platform hub: `knowledge/qqq/qqq-hub.md`
- This repo's dossier: `knowledge/qqq/repos/qqq-orb.md` (reviewed at develop
commit `bdff16ff9582`, 2026-07-04) — covers 0.5.0→0.6.0→HEAD behavior changes,
the npm dist-tag defect verdict, org-wide pin survey, licensing history, and
open bug #5 (release-branch patch loss).
- Release/versioning architecture: `knowledge/qqq/architecture/build-release-versioning.md`
+14
View File
@@ -60,6 +60,20 @@ workflows:
| `static_analysis` | Run SpotBugs and PMD static analysis |
| `security_scan` | Run Gitleaks, Semgrep, OWASP Dependency Check, and CycloneDX SBOM |
### npm Trusted Publishing
For npm Trusted Publishing, set `npm_trusted_publishing: true` and use a supported
executor such as `node_version: "24.21"` on `node_publish`. Configure the package's
[npm Trusted Publisher](https://docs.npmjs.com/trusted-publishers/) for the exact
CircleCI organization, project, pipeline definition and VCS origin, and allow
direct `npm publish`. The job requires Node >=22.14.0 and npm >=11.5.1, obtains an
OIDC identity at publish time, and does not run `npm whoami` or need `NPM_TOKEN`.
Existing token authentication remains the default. Trusted mode requires no
project `.npmrc` or npm credential/config-path environment settings; it ignores user/global
npm config and clears conventional token variables to prevent token fallback.
CircleCI does not currently provide npm provenance attestations. A successful
real publication, not a dry run, verifies the trust relationship.
### Branch Types
| Branch | Version Format |
+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
+14 -3
View File
@@ -3,10 +3,21 @@ description: >
- Sets up NPM authentication
- Publishes the package to NPM
parameters:
trusted_publishing:
type: boolean
default: false
description: "Authenticate npm publish using the CircleCI job's OIDC identity."
steps:
- run:
name: "Setup NPM authentication"
command: <<include(scripts/node_npm_auth.sh)>>
- unless:
condition: << parameters.trusted_publishing >>
steps:
- run:
name: "Setup NPM authentication"
command: <<include(scripts/node_npm_auth.sh)>>
- run:
name: "Publish to NPM"
environment:
QQQ_NPM_TRUSTED_PUBLISHING: << parameters.trusted_publishing >>
command: <<include(scripts/node_npm_publish.sh)>>
+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 >>
+6 -1
View File
@@ -16,6 +16,10 @@ parameters:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
npm_trusted_publishing:
type: boolean
default: false
description: "Use CircleCI OIDC instead of NPM_TOKEN (Node >=22.14, npm >=11.5.1)."
steps:
- git_full_checkout
@@ -26,7 +30,8 @@ steps:
- attach_workspace:
at: .
- node_build_package
- node_publish
- node_publish:
trusted_publishing: << parameters.npm_trusted_publishing >>
# GitHub releases only for final releases and hotfixes (not RCs)
# RCs just publish artifacts - GitHub release happens when merged to main
-1
View File
@@ -25,5 +25,4 @@ set -e
##############################################
## Deploy signed artifacts to Maven Central ##
##############################################
cat /tmp/circleci/mvn-settings.xml
mvn -s /tmp/circleci/mvn-settings.xml -P release -B -DskipTests -Dgpg.keyname="$GPG_KEYNAME" -Dgpg.passphrase="$GPG_PASSPHRASE" deploy
+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"
+40 -2
View File
@@ -1,4 +1,4 @@
#!/bin/bash
#!/usr/bin/env bash
############################################################################
## node_npm_publish.sh
@@ -16,7 +16,45 @@
## Usage: Called by CircleCI orb command node_publish
############################################################################
set -e
set +x
set -euo pipefail
if [[ "${QQQ_NPM_TRUSTED_PUBLISHING:-false}" == "true" ]]; then
NPM_CLI_VERSION=$(npm --version)
node - "$NPM_CLI_VERSION" <<'NODE'
const atLeast = (actual, minimum) => {
const parts = actual.split('.').map(Number);
return minimum.every((part, index) => parts[index] === part)
|| minimum.some((part, index) => parts[index] > part
&& minimum.slice(0, index).every((value, previous) => parts[previous] === value));
};
if (!atLeast(process.versions.node, [22, 14, 0]) || !atLeast(process.argv[2], [11, 5, 1])) {
console.error('Trusted publishing requires Node >=22.14.0 and npm >=11.5.1.');
process.exit(1);
}
if (Object.keys(process.env).some(name => /^npm_config_.*(auth|password|username|userconfig|globalconfig)/i.test(name))) {
console.error('Remove npm credential/config-path environment settings before using trusted publishing.');
process.exit(1);
}
NODE
# Do not inherit a project/user token or write the short-lived identity to disk.
if [[ -f .npmrc ]]; then
echo "Trusted publishing requires a publish directory without .npmrc." >&2
exit 1
fi
unset NPM_TOKEN NODE_AUTH_TOKEN NPM_AUTH_TOKEN
PUBLISH_CONFIG_DIR=$(mktemp -d)
trap 'rm -rf "$PUBLISH_CONFIG_DIR"' EXIT
export NPM_CONFIG_USERCONFIG="$PUBLISH_CONFIG_DIR/user.npmrc"
export NPM_CONFIG_GLOBALCONFIG="$PUBLISH_CONFIG_DIR/global.npmrc"
NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud":"npm:registry.npmjs.org"}')
if [[ -z "$NPM_ID_TOKEN" ]]; then
echo "CircleCI did not provide an npm OIDC token." >&2
exit 1
fi
export NPM_ID_TOKEN
fi
# Extract version from package.json
VERSION=$(grep '"version"' package.json | sed 's/.*"version": "//;s/".*//')
+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
}
-1
View File
@@ -47,4 +47,3 @@ http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.
EOF
echo "✅ Maven settings file created: /tmp/circleci/mvn-settings.xml"
cat /tmp/circleci/mvn-settings.xml
+7 -1
View File
@@ -16,6 +16,7 @@ set -e
###################
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TEST_SCRIPT="$SCRIPT_DIR/test_calculate_version.sh"
SETTINGS_TEST_SCRIPT="$SCRIPT_DIR/test_maven_settings_output.sh"
VERBOSE=false
CI_MODE=false
@@ -54,6 +55,10 @@ main() {
echo "❌ Test script not found: $TEST_SCRIPT"
exit 1
fi
if [[ ! -f "$SETTINGS_TEST_SCRIPT" ]]; then
echo "❌ Test script not found: $SETTINGS_TEST_SCRIPT"
exit 1
fi
###############
## Run tests ##
@@ -68,7 +73,7 @@ main() {
## CI mode: minimal output, focus on results ##
###############################################
echo "Running tests in CI mode..."
if "$TEST_SCRIPT" $test_args > /tmp/test_output.log 2>&1; then
if { "$TEST_SCRIPT" $test_args && bash "$SETTINGS_TEST_SCRIPT"; } > /tmp/test_output.log 2>&1; then
echo "✅ All tests passed!"
exit 0
else
@@ -82,6 +87,7 @@ main() {
## Interactive mode: full output ##
###################################
"$TEST_SCRIPT" $test_args
bash "$SETTINGS_TEST_SCRIPT"
fi
}
+55
View File
@@ -0,0 +1,55 @@
#!/bin/bash
set -euo pipefail
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source_dir="$(dirname "$script_dir")/src/scripts"
test_dir="$(mktemp -d)"
trap 'rm -rf "$test_dir"' EXIT
mkdir -p "$test_dir/bin"
# Keep the production scripts' fixed CircleCI path away from any shared /tmp file.
sed "s|/tmp/circleci|$test_dir/circleci|g" \
"$source_dir/setup_maven_settings.sh" > "$test_dir/setup.sh"
sed "s|/tmp/circleci|$test_dir/circleci|g" \
"$source_dir/mvn_jar_deploy.sh" > "$test_dir/deploy.sh"
bash "$test_dir/setup.sh" > "$test_dir/setup-output" 2>&1
settings="$test_dir/circleci/mvn-settings.xml"
test -f "$settings"
grep -Fq "\${env.CENTRAL_USERNAME}" "$settings"
grep -Fq "\${env.CENTRAL_PASSWORD}" "$settings"
if grep -Fq '<settings' "$test_dir/setup-output" ||
grep -Fq "\${env.CENTRAL_USERNAME}" "$test_dir/setup-output"; then
echo 'Setup printed Maven settings content' >&2
exit 1
fi
# A distinctive future secret must never be echoed by the deploy wrapper.
printf '\n<!-- settings-output-sentinel -->\n' >> "$settings"
cat > "$test_dir/bin/mvn" <<'EOF'
#!/bin/bash
printf '%s\n' "$@" > "$TEST_MVN_ARGS"
EOF
chmod +x "$test_dir/bin/mvn"
PATH="$test_dir/bin:$PATH" TEST_MVN_ARGS="$test_dir/mvn-args" \
GPG_KEYNAME=test-key GPG_PASSPHRASE=test-passphrase \
bash "$test_dir/deploy.sh" > "$test_dir/deploy-output" 2>&1
if grep -Fq 'settings-output-sentinel' "$test_dir/deploy-output"; then
echo 'Deploy printed Maven settings content' >&2
exit 1
fi
cat > "$test_dir/expected-args" <<EOF
-s
$settings
-P
release
-B
-DskipTests
-Dgpg.keyname=test-key
-Dgpg.passphrase=test-passphrase
deploy
EOF
diff -u "$test_dir/expected-args" "$test_dir/mvn-args"
echo 'Maven settings setup and deploy output are safe; deploy arguments preserved'
+128
View File
@@ -0,0 +1,128 @@
#!/usr/bin/env python3
"""Exercise publisher boundaries without network access or real credentials."""
import json
import os
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
SCRIPT = Path(__file__).resolve().parents[1] / 'src/scripts/node_npm_publish.sh'
NODE = shutil.which('node')
NPM = shutil.which('npm')
class PublishTests(unittest.TestCase):
def run_publish(self, version='1.0.0-RC.1', trusted=True, project_config=False, **overrides):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
bin_dir = root / 'bin'
bin_dir.mkdir()
(root / 'package.json').write_text(json.dumps({'version': version}) + '\n')
if project_config:
(root / '.npmrc').write_text('//registry.npmjs.org/:_authToken=synthetic-old-token\n')
scripts = {
'npm': '''#!/usr/bin/env python3
import json, os, pathlib, subprocess, sys
if sys.argv[1:] == ['--version']:
print(os.environ.get('TEST_NPM_VERSION', '11.19.0'))
else:
assert sys.argv[1] == 'publish', 'Unexpected npm command'
if os.environ['QQQ_NPM_TRUSTED_PUBLISHING'] == 'true':
assert os.environ.get('NPM_ID_TOKEN') == 'synthetic-oidc-token'
assert all(not os.environ.get(name) for name in ['NPM_TOKEN', 'NODE_AUTH_TOKEN', 'NPM_AUTH_TOKEN'])
assert os.environ['NPM_CONFIG_USERCONFIG'] != os.environ['NPM_CONFIG_GLOBALCONFIG']
assert not pathlib.Path(os.environ['NPM_CONFIG_USERCONFIG']).exists()
assert not pathlib.Path(os.environ['NPM_CONFIG_GLOBALCONFIG']).exists()
registry = subprocess.check_output([os.environ['TEST_REAL_NPM'], 'config', 'get', 'registry'], text=True)
assert registry.strip() == 'https://registry.npmjs.org/'
pathlib.Path('published.json').write_text(json.dumps(sys.argv[1:]))
sys.exit(int(os.environ.get('TEST_PUBLISH_STATUS', '0')))
''',
'circleci': '''#!/usr/bin/env python3
import os, pathlib, sys
assert sys.argv[1:] == ['run', 'oidc', 'get', '--claims', '{"aud":"npm:registry.npmjs.org"}']
pathlib.Path('oidc-called').touch()
print(os.environ.get('TEST_OIDC_VALUE', 'synthetic-oidc-token'))
sys.exit(int(os.environ.get('TEST_OIDC_STATUS', '0')))
''',
'node': '''#!/usr/bin/env python3
import os, subprocess, sys
if sys.argv[1] != '-':
os.execv(os.environ['TEST_REAL_NODE'], [os.environ['TEST_REAL_NODE'], *sys.argv[1:]])
source = sys.stdin.read()
if 'TEST_NODE_VERSION' in os.environ:
source = source.replace('process.versions.node', repr(os.environ['TEST_NODE_VERSION']))
sys.exit(subprocess.run([os.environ['TEST_REAL_NODE'], *sys.argv[1:]], input=source, text=True).returncode)
'''
}
for name, contents in scripts.items():
executable = bin_dir / name
executable.write_text(contents)
executable.chmod(0o755)
env = dict(os.environ, PATH=str(bin_dir) + os.pathsep + os.environ['PATH'],
QQQ_NPM_TRUSTED_PUBLISHING=str(trusted).lower(), TEST_REAL_NODE=NODE, TEST_REAL_NPM=NPM,
NPM_TOKEN='synthetic-old-token', NODE_AUTH_TOKEN='synthetic-old-token',
NPM_AUTH_TOKEN='synthetic-old-token', **overrides)
result = subprocess.run(['bash', '-x', str(SCRIPT)], cwd=root, env=env,
text=True, capture_output=True)
self.assertNotIn('synthetic-oidc-token', result.stdout + result.stderr)
self.assertNotIn('synthetic-old-token', result.stdout + result.stderr)
published = root / 'published.json'
return result, json.loads(published.read_text()) if published.exists() else None, (root / 'oidc-called').exists()
def test_tags_and_legacy_authentication(self):
for trusted in [True, False]:
for version, tag in [('1.0.0-RC.1', 'rc'), ('1.0.0-SNAPSHOT', 'snapshot'),
('1.0.0-alpha.1', 'next'), ('1.0.0-beta.1', 'next'), ('1.0.0', 'latest')]:
with self.subTest(trusted=trusted, version=version):
result, args, oidc = self.run_publish(version, trusted)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(args, ['publish', '--access', 'public', '--tag', tag])
self.assertEqual(oidc, trusted)
def test_oidc_failure_or_empty_token_stops_publication(self):
for overrides in [{'TEST_OIDC_STATUS': '7'}, {'TEST_OIDC_VALUE': ''}]:
with self.subTest(overrides=overrides):
result, args, oidc = self.run_publish(**overrides)
self.assertNotEqual(result.returncode, 0)
self.assertIsNone(args)
self.assertTrue(oidc)
def test_unsupported_toolchains_stop_before_requesting_identity(self):
for overrides in [{'TEST_NPM_VERSION': '11.5.0'}, {'TEST_NPM_VERSION': '10.9.0'},
{'TEST_NODE_VERSION': '22.13.1'}, {'TEST_NODE_VERSION': '20.20.0'}]:
with self.subTest(overrides=overrides):
result, args, oidc = self.run_publish(**overrides)
self.assertNotEqual(result.returncode, 0)
self.assertIsNone(args)
self.assertFalse(oidc)
def test_minimum_toolchain_is_supported(self):
result, args, oidc = self.run_publish(TEST_NPM_VERSION='11.5.1', TEST_NODE_VERSION='22.14.0')
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIsNotNone(args)
self.assertTrue(oidc)
def test_project_or_environment_credentials_are_rejected(self):
for overrides in [{'project_config': True}, {'NPM_CONFIG__AUTH': 'synthetic-old-token'},
{'npm_config_userconfig': '/synthetic/legacy.npmrc'},
{'npm_config_USERCONFIG': '/synthetic/legacy.npmrc'},
{'Npm_Config_Globalconfig': '/synthetic/legacy.npmrc'}]:
with self.subTest(overrides=overrides):
result, args, oidc = self.run_publish(**overrides)
self.assertNotEqual(result.returncode, 0)
self.assertIsNone(args)
self.assertFalse(oidc)
def test_publish_failure_is_not_reported_as_success(self):
result, args, oidc = self.run_publish(TEST_PUBLISH_STATUS='9')
self.assertEqual(result.returncode, 9)
self.assertIsNotNone(args)
self.assertTrue(oidc)
self.assertNotIn('Successfully published', result.stdout)
if __name__ == '__main__':
unittest.main()