🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →

@qvac/ci

Advanced tools

License

Install Socket

Detect and block malicious and high-risk dependencies

Install

@qvac/ci - npm Package Compare versions

Comparing version

0.0.0

0.1.0

+10

CHANGELOG.md

		# Changelog

		## [0.1.0] - 2026-06-04

		### Added

		- Initial release
		- `pending-approvals` subcommand: checks PR approval status and posts a review-status comment
		- Modular command architecture with `Command` base class and per-command directory layout
		- Security model: secrets via env vars only, `redact()` + `sanitizeError()` on all output

+51

lib/command.js

		import { validateRequiredEnv } from './helpers.js'
		import { Sanitizer } from './sanitizer.js'

		/**
		* Base class for all actions-ci subcommands.
		*
		* Subclasses must implement:
		* toCommand() — builds and returns the paparam command() instance
		* _run(flags) — contains the actual domain logic
		*
		* Subclasses MUST NOT override run() — it is a template method that
		* automatically validates all declared secrets before calling _run().
		* This is a structural guarantee: secret validation cannot be skipped.
		*
		* To add a new subcommand:
		* 1. Create lib/commands/<name>/index.js — extend Command
		* 2. Create lib/commands/<name>/helpers.js — domain logic
		* 3. Call newCmd.toCommand() as a positional arg in main.js command()
		* 4. Write flat test files: test/unit/<name>-index.test.js, test/unit/<name>-helpers.test.js
		*/
		export class Command {
		constructor ({ name, description, secrets = [], sanitizer = new Sanitizer() }) {
		this.name = name
		this.description = description
		this.secrets = secrets
		this.sanitizer = sanitizer
		}

		toCommand () {
		throw new Error(this.name + ': toCommand() must be implemented')
		}

		async run (flags) {
		validateRequiredEnv(this.secrets.map(s => s.envVar))
		return this._run(flags)
		}

		async _run (flags) { // eslint-disable-line no-unused-vars
		throw new Error(this.name + ': _run() must be implemented')
		}

		_secretsFooter () {
		if (this.secrets.length === 0) return ''
		const maxLen = Math.max(...this.secrets.map(s => s.envVar.length))
		const lines = this.secrets.map(s => {
		const pad = ' '.repeat(maxLen - s.envVar.length + 2)
		return ' ' + s.envVar + pad + s.description
		})
		return 'Environment (required):\n' + lines.join('\n')
		}
		}

+7

lib/commands/index.js

		// Command registry — add new commands here.
		// Each entry calls .toCommand() so main.js can spread the array directly.
		import pendingApprovals from './pending-approvals/index.js'

		export const commands = [
		pendingApprovals.toCommand()
		]

+277

lib/commands/pending-approvals/helpers.js

		// All pending-approvals domain logic.
		//
		// Secrets (GITHUB_TOKEN, GITHUB_APP_ID, GITHUB_PRIVATE_KEY) are read from
		// process.env inside this file — they are never passed as function parameters.
		// This prevents secrets from appearing in call stacks or being accidentally
		// logged by a caller.

		import { Octokit } from '@octokit/rest'
		import { createAppAuth } from '@octokit/auth-app'
		import { Sanitizer } from '../../sanitizer.js'

		// Patterns specific to GitHub tokens and PEM keys.
		// Kept here so future subcommands don't inherit a GitHub-specific allowlist.
		export const SECRET_PATTERNS = [
		/ghp_[A-Za-z0-9_]{36,}/g,
		/ghs_[A-Za-z0-9_]{36,}/g,
		/-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g
		]

		export class GitHubSanitizer extends Sanitizer {
		redact (str) {
		if (typeof str !== 'string') return str
		let result = str
		for (const pattern of SECRET_PATTERNS) {
		result = result.replace(pattern, '[REDACTED]')
		}
		return result
		}
		}

		export function throwApiError (err, context) {
		let message
		if (err.status === 401) {
		message = 'Authentication failed — check GITHUB_TOKEN / GITHUB_APP_ID / GITHUB_PRIVATE_KEY'
		} else if (err.status === 403) {
		message = context + ' (forbidden — check token scopes and permissions)'
		} else if (err.status === 404) {
		message = context + ' (not found — check the value is correct and the token has access)'
		} else {
		message = context + ': ' + err.message
		}
		const out = new Error(message)
		out.status = err.status
		throw out
		}

		export const ROLE_DISPLAY = {
		maintainer: 'Management',
		teamLead: 'Team Lead',
		other: 'Member'
		}

		export const MIN_CODEOWNER_APPROVALS = 1

		export async function buildOctokit () {
		const token = process.env.GITHUB_TOKEN
		return new Octokit({ auth: token })
		}

		export async function buildAppOctokit (owner, repo) {
		const appId = parseInt(process.env.GITHUB_APP_ID, 10)
		const privateKey = process.env.GITHUB_PRIVATE_KEY

		const auth = createAppAuth({ appId, privateKey })

		const { token: jwtToken } = await auth({ type: 'app' })
		const appOctokit = new Octokit({ auth: jwtToken })

		let installation
		try {
		const { data } = await appOctokit.rest.apps.getRepoInstallation({ owner, repo })
		installation = data
		} catch (err) {
		throwApiError(err, `GitHub App (ID: ${appId}) does not appear to be installed on ${owner}/${repo}`)
		}

		const { token: installToken } = await auth({ type: 'installation', installationId: installation.id })

		return new Octokit({ auth: installToken })
		}

		export function getLatestApprovals (reviews) {
		const byUser = Object.create(null)
		for (const review of reviews) {
		const username = review.user && review.user.login
		if (!username) continue
		if (!byUser[username] \|\| review.submitted_at > byUser[username].submitted_at) {
		byUser[username] = review
		}
		}
		return Object.values(byUser)
		}

		export function checkApproved (counts, minTotal) {
		const maintainer = counts.maintainer \|\| 0
		const teamLead = counts.teamLead \|\| 0
		const other = counts.other \|\| 0
		const codeowner = maintainer + teamLead
		const total = codeowner + other
		return codeowner >= MIN_CODEOWNER_APPROVALS && total >= minTotal
		}

		export function getPendingMessage (counts, minTotal) {
		if (checkApproved(counts, minTotal)) return ''
		const maintainer = counts.maintainer \|\| 0
		const teamLead = counts.teamLead \|\| 0
		const other = counts.other \|\| 0
		const codeowner = maintainer + teamLead
		const total = codeowner + other

		const missingCodeowner = Math.max(0, MIN_CODEOWNER_APPROVALS - codeowner)
		const missingTotal = Math.max(0, minTotal - total)
		const extraNeeded = Math.max(0, missingTotal - missingCodeowner)

		const parts = []
		if (missingCodeowner > 0) parts.push(missingCodeowner + ' Management or Team Lead')
		if (extraNeeded > 0) parts.push(extraNeeded + ' more from Management, Team Lead, or Member')
		return parts.join(', and ')
		}

		export function buildApprovalComment (approved, counts, pendingMessage) {
		const approvalSummary = Object.entries(counts)
		.filter(([, count]) => count > 0)
		.map(([role, count]) => (ROLE_DISPLAY[role] \|\| role) + ': ' + count)
		.join(', ') \|\| 'none'

		const lines = [
		'## Review Status',
		'Current Status: ' + (approved ? '✅ APPROVED' : '❌ PENDING') + '',
		'Approvals so far: ' + approvalSummary
		]

		if (!approved) lines.push('\nPending reviews: Needs ' + pendingMessage + '.')

		return lines.join('\n')
		}

		export async function fetchReviews (octokit, owner, repo, prNumber) {
		try {
		const { data } = await octokit.rest.pulls.listReviews({
		owner,
		repo,
		pull_number: prNumber
		})
		return data
		} catch (err) {
		throwApiError(err, `PR #${prNumber} not found in ${owner}/${repo}`)
		}
		}

		// Returns true only for collaborators with write or admin access.
		// Prevents external contributors on public repos from counting toward approvals.
		export async function hasWriteAccess (octokit, owner, repo, username) {
		try {
		const { data } = await octokit.rest.repos.getCollaboratorPermissionLevel({
		owner,
		repo,
		username
		})
		const perm = data.permission
		return perm === 'admin' \|\| perm === 'write'
		} catch (err) {
		if (err.status === 404) return false // not a collaborator
		throwApiError(err, `Could not check repository permission for '${username}'`)
		}
		}

		export async function buildApprovalCounts (appOctokit, owner, repo, reviews, teams) {
		const latestApprovals = getLatestApprovals(reviews)
		const approvers = latestApprovals
		.filter(r => r.state === 'APPROVED')
		.map(r => r.user.login)

		if (approvers.length === 0) {
		return { maintainer: 0, teamLead: 0, other: 0 }
		}

		// Drop approvers without write access (read-only collaborators or external contributors).
		const accessFlags = await Promise.all(
		approvers.map(login => hasWriteAccess(appOctokit, owner, repo, login))
		)
		const writeApprovers = approvers.filter((_, i) => accessFlags[i])

		if (writeApprovers.length === 0) {
		return { maintainer: 0, teamLead: 0, other: 0 }
		}

		const [maintainerMembers, teamLeadMembers] = await Promise.all([
		getTeamMembers(appOctokit, owner, teams.maintainer),
		getTeamMembers(appOctokit, owner, teams.teamLead)
		])

		const counts = { maintainer: 0, teamLead: 0, other: 0 }
		for (const login of writeApprovers) {
		if (maintainerMembers.has(login)) {
		counts.maintainer++
		} else if (teamLeadMembers.has(login)) {
		counts.teamLead++
		} else {
		counts.other++
		}
		}

		return counts
		}

		export async function getTeamMembers (octokit, org, teamSlug) {
		try {
		const members = await octokit.paginate(octokit.rest.teams.listMembersInOrg, {
		org,
		team_slug: teamSlug,
		per_page: 100
		})
		return new Set(members.map(m => m.login))
		} catch (err) {
		throwApiError(err, `Team '${teamSlug}' not found in org '${org}'`)
		}
		}

		export async function upsertPrComment (octokit, owner, repo, prNumber, body) {
		const MARKER = '## Review Status'

		let comments
		try {
		comments = await octokit.paginate(octokit.rest.issues.listComments, {
		owner,
		repo,
		issue_number: prNumber,
		per_page: 100
		})
		} catch (err) {
		throwApiError(err, `Could not list comments on PR #${prNumber} in ${owner}/${repo}`)
		}

		const existing = comments.find(c => c.body && c.body.includes(MARKER))

		try {
		if (existing) {
		await octokit.rest.issues.updateComment({
		owner,
		repo,
		comment_id: existing.id,
		body
		})
		} else {
		await octokit.rest.issues.createComment({
		owner,
		repo,
		issue_number: prNumber,
		body
		})
		}
		} catch (err) {
		throwApiError(err, `Could not post review-status comment on PR #${prNumber} in ${owner}/${repo}`)
		}
		}

		// Mutable namespace object — index.js imports and calls through this object,
		// allowing tests to stub individual methods without a mock framework.
		export const helpers = {
		SECRET_PATTERNS,
		GitHubSanitizer,
		throwApiError,
		buildOctokit,
		buildAppOctokit,
		getLatestApprovals,
		checkApproved,
		getPendingMessage,
		buildApprovalComment,
		fetchReviews,
		hasWriteAccess,
		buildApprovalCounts,
		getTeamMembers,
		upsertPrComment,
		MIN_CODEOWNER_APPROVALS,
		ROLE_DISPLAY
		}

+82

lib/commands/pending-approvals/index.js

		import { command, flag, summary, footer } from 'paparam'
		import { Command } from '../../command.js'
		import { validatePrNumber, validateRepo, validateTeamSlug, exitWithError } from '../../helpers.js'
		// Imported as a namespace so tests can inject mocks via the shared module object.
		import { helpers } from './helpers.js'

		class PendingApprovals extends Command {
		constructor () {
		super({
		name: 'pending-approvals',
		description: 'Check PR approval status and post a review-status comment',
		secrets: [
		{ envVar: 'GITHUB_TOKEN', description: 'GitHub token for comment posting' },
		{ envVar: 'GITHUB_APP_ID', description: 'App ID for team membership resolution' },
		{ envVar: 'GITHUB_PRIVATE_KEY', description: 'App private key for team membership resolution' }
		],
		sanitizer: new helpers.GitHubSanitizer()
		})
		}

		toCommand () {
		const cmd = command(
		'pending-approvals',
		summary(this.description),
		flag('--pr-number <number>', 'PR number to check (required)'),
		flag('--repo [owner/repo]', 'owner/repo — falls back to $GITHUB_REPOSITORY'),
		flag('--maintainers-team <slug>', 'GitHub team slug for maintainers/management (required)'),
		flag('--team-leads-team <slug>', 'GitHub team slug for team leads (required)'),
		flag('--min-approvals <n>', 'Minimum total approvals required (default: 2)'),
		footer(this._secretsFooter()),
		async () => {
		try {
		await this.run(cmd.flags)
		} catch (err) {
		exitWithError(this.sanitizer.sanitizeError(err))
		}
		}
		)
		return cmd
		}

		async _run (flags) {
		const prNumber = validatePrNumber(flags['pr-number'] \|\| flags.prNumber)
		const { owner, repo } = validateRepo(
		flags.repo \|\| process.env.GITHUB_REPOSITORY
		)

		const maintainersTeam = validateTeamSlug(
		flags['maintainers-team'] \|\| flags.maintainersTeam, '--maintainers-team'
		)
		const teamLeadsTeam = validateTeamSlug(
		flags['team-leads-team'] \|\| flags.teamLeadsTeam, '--team-leads-team'
		)
		const minApprovals = parseInt(flags['min-approvals'] \|\| flags.minApprovals \|\| '2', 10)
		if (isNaN(minApprovals) \|\| minApprovals < 1) {
		throw new RangeError('--min-approvals must be a positive integer, got: ' + String(flags['min-approvals'] \|\| flags.minApprovals))
		}

		const teams = {
		maintainer: maintainersTeam,
		teamLead: teamLeadsTeam
		}

		const commentOctokit = await helpers.buildOctokit()
		const appOctokit = await helpers.buildAppOctokit(owner, repo)

		const reviews = await helpers.fetchReviews(commentOctokit, owner, repo, prNumber)
		const counts = await helpers.buildApprovalCounts(appOctokit, owner, repo, reviews, teams)

		const approved = helpers.checkApproved(counts, minApprovals)
		const pendingMessage = approved ? '' : helpers.getPendingMessage(counts, minApprovals)
		const commentBody = helpers.buildApprovalComment(approved, counts, pendingMessage)

		await helpers.upsertPrComment(commentOctokit, owner, repo, prNumber, commentBody)

		if (!approved) {
		process.stdout.write('PR #' + prNumber + ' is pending approval: ' + pendingMessage + '\n')
		}
		}
		}

		export default new PendingApprovals()

+59

lib/helpers.js

		// Generic, domain-agnostic utilities.
		// No GitHub, no CI-domain logic — no secret patterns either.
		// Each subcommand defines its own secret patterns and sanitizeError in its own helpers.js.
		// Any subcommand or future JS action can use these.

		export function exitWithError (message, code) {
		process.stderr.write(String(message) + '\n')
		process.exit(code === undefined ? 1 : code)
		}

		export function validateRequiredEnv (vars) {
		const missing = vars.filter(v => !process.env[v])
		if (missing.length > 0) {
		throw new Error(
		'Missing required environment variable' + (missing.length > 1 ? 's' : '') +
		': ' + missing.join(', ')
		)
		}
		}

		export function validatePrNumber (raw) {
		if (raw === undefined \|\| raw === null \|\| raw === '') {
		throw new RangeError('--pr-number is required')
		}
		const n = parseInt(String(raw), 10)
		if (isNaN(n) \|\| n < 1) {
		throw new RangeError('--pr-number must be a positive integer, got: ' + String(raw))
		}
		return n
		}

		export function validateRepo (raw) {
		if (!raw \|\| typeof raw !== 'string') {
		throw new Error(
		'--repo is required (or set $GITHUB_REPOSITORY). ' +
		'Expected format: owner/repo'
		)
		}
		if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(raw)) {
		throw new Error(
		'Invalid repo format: ' + JSON.stringify(raw) + '. Expected: owner/repo'
		)
		}
		const [owner, repo] = raw.split('/')
		return { owner, repo }
		}

		export function validateTeamSlug (raw, flagName) {
		if (!raw \|\| typeof raw !== 'string') {
		throw new Error(flagName + ' is required')
		}
		if (!/^[a-zA-Z0-9-]+$/.test(raw)) {
		throw new Error(
		'Invalid ' + flagName + ' slug: ' + JSON.stringify(raw) +
		'. Expected: letters, digits, and hyphens only'
		)
		}
		return raw
		}

+25

lib/sanitizer.js

		/**
		* Base sanitizer interface — passthrough by default.
		*
		* Subcommands that handle sensitive secrets should extend this class and
		* override redact() with their own SECRET_PATTERNS.
		* sanitizeError() is a template method; it calls this.redact() so overriding
		* redact() alone is sufficient.
		*
		* Example:
		* class GitHubSanitizer extends Sanitizer {
		* redact (str) { ... }
		* }
		*/
		export class Sanitizer {
		redact (str) {
		return str
		}

		sanitizeError (err) {
		if (err && typeof err.message === 'string') {
		return this.redact(err.message)
		}
		return this.redact(String(err))
		}
		}

+179

LICENSE


		Apache License
		Version 2.0, January 2004
		http://www.apache.org/licenses/

		TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

		1. Definitions.

		"License" shall mean the terms and conditions for use, reproduction,
		and distribution as defined by Sections 1 through 9 of this document.

		"Licensor" shall mean the copyright owner or entity authorized by
		the copyright owner that is granting the License.

		"Legal Entity" shall mean the union of the acting entity and all
		other entities that control, are controlled by, or are under common
		control with that entity. For the purposes of this definition,
		"control" means (i) the power, direct or indirect, to cause the
		direction or management of such entity, whether by contract or
		otherwise, or (ii) ownership of fifty percent (50%) or more of the
		outstanding shares, or (iii) beneficial ownership of such entity.

		"You" (or "Your") shall mean an individual or Legal Entity
		exercising permissions granted by this License.

		"Source" form shall mean the preferred form for making modifications,
		including but not limited to software source code, documentation
		source, and configuration files.

		"Object" form shall mean any form resulting from mechanical
		transformation or translation of a Source form, including but
		not limited to compiled object code, generated documentation,
		and conversions to other media types.

		"Work" shall mean the work of authorship, whether in Source or
		Object form, made available under the License, as indicated by a
		copyright notice that is included in or attached to the work
		(an example is provided in the Appendix below).

		"Derivative Works" shall mean any work, whether in Source or Object
		form, that is based on (or derived from) the Work and for which the
		editorial revisions, annotations, elaborations, or other modifications
		represent, as a whole, an original work of authorship. For the purposes
		of this License, Derivative Works shall not include works that remain
		separable from, or merely link (or bind by name) to the interfaces of,
		the Work and Derivative Works thereof.

		"Contribution" shall mean any work of authorship, including
		the original version of the Work and any modifications or additions
		to that Work or Derivative Works thereof, that is intentionally
		submitted to Licensor for inclusion in the Work by the copyright owner
		or by an individual or Legal Entity authorized to submit on behalf of
		the copyright owner. For the purposes of this definition, "submitted"
		means any form of electronic, verbal, or written communication sent
		to the Licensor or its representatives, including but not limited to
		communication on electronic mailing lists, source code control systems,
		and issue tracking systems that are managed by, or on behalf of, the
		Licensor for the purpose of discussing and improving the Work, but
		excluding communication that is conspicuously marked or otherwise
		designated in writing by the copyright owner as "Not a Contribution."

		"Contributor" shall mean Licensor and any individual or Legal Entity
		on behalf of whom a Contribution has been received by Licensor and
		subsequently incorporated within the Work.

		2. Grant of Copyright License. Subject to the terms and conditions of
		this License, each Contributor hereby grants to You a perpetual,
		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
		copyright license to reproduce, prepare Derivative Works of,
		publicly display, publicly perform, sublicense, and distribute the
		Work and such Derivative Works in Source or Object form.

		3. Grant of Patent License. Subject to the terms and conditions of
		this License, each Contributor hereby grants to You a perpetual,
		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
		(except as stated in this section) patent license to make, have made,
		use, offer to sell, sell, import, and otherwise transfer the Work,
		where such license applies only to those patent claims licensable
		by such Contributor that are necessarily infringed by their
		Contribution(s) alone or by combination of their Contribution(s)
		with the Work to which such Contribution(s) was submitted. If You
		institute patent litigation against any entity (including a
		cross-claim or counterclaim in a lawsuit) alleging that the Work
		or a Contribution incorporated within the Work constitutes direct
		or contributory patent infringement, then any patent licenses
		granted to You under this License for that Work shall terminate
		as of the date such litigation is filed.

		4. Redistribution. You may reproduce and distribute copies of the
		Work or Derivative Works thereof in any medium, with or without
		modifications, and in Source or Object form, provided that You
		meet the following conditions:

		(a) You must give any other recipients of the Work or
		Derivative Works a copy of this License; and

		(b) You must cause any modified files to carry prominent notices
		stating that You changed the files; and

		(c) You must retain, in the Source form of any Derivative Works
		that You distribute, all copyright, patent, trademark, and
		attribution notices from the Source form of the Work,
		excluding those notices that do not pertain to any part of
		the Derivative Works; and

		(d) If the Work includes a "NOTICE" text file as part of its
		distribution, then any Derivative Works that You distribute must
		include a readable copy of the attribution notices contained
		within such NOTICE file, excluding those notices that do not
		pertain to any part of the Derivative Works, in at least one
		of the following places: within a NOTICE text file distributed
		as part of the Derivative Works; within the Source form or
		documentation, if provided along with the Derivative Works; or,
		within a display generated by the Derivative Works, if and
		wherever such third-party notices normally appear. The contents
		of the NOTICE file are for informational purposes only and
		do not modify the License. You may add Your own attribution
		notices within Derivative Works that You distribute, alongside
		or as an addendum to the NOTICE text from the Work, provided
		that such additional attribution notices cannot be construed
		as modifying the License.

		You may add Your own copyright statement to Your modifications and
		may provide additional or different license terms and conditions
		for use, reproduction, or distribution of Your modifications, or
		for any such Derivative Works as a whole, provided Your use,
		reproduction, and distribution of the Work otherwise complies with
		the conditions stated in this License.

		5. Submission of Contributions. Unless You explicitly state otherwise,
		any Contribution intentionally submitted for inclusion in the Work
		by You to the Licensor shall be under the terms and conditions of
		this License, without any additional terms or conditions.
		Notwithstanding the above, nothing herein shall supersede or modify
		the terms of any separate license agreement you may have executed
		with Licensor regarding such Contributions.

		6. Trademarks. This License does not grant permission to use the trade
		names, trademarks, service marks, or product names of the Licensor,
		except as required for reasonable and customary use in describing the
		origin of the Work and reproducing the content of the NOTICE file.

		7. Disclaimer of Warranty. Unless required by applicable law or
		agreed to in writing, Licensor provides the Work (and each
		Contributor provides its Contributions) on an "AS IS" BASIS,
		WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
		implied, including, without limitation, any warranties or conditions
		of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
		PARTICULAR PURPOSE. You are solely responsible for determining the
		appropriateness of using or redistributing the Work and assume any
		risks associated with Your exercise of permissions under this License.

		8. Limitation of Liability. In no event and under no legal theory,
		whether in tort (including negligence), contract, or otherwise,
		unless required by applicable law (such as deliberate and grossly
		negligent acts) or agreed to in writing, shall any Contributor be
		liable to You for damages, including any direct, indirect, special,
		incidental, or consequential damages of any character arising as a
		result of this License or out of the use or inability to use the
		Work (including but not limited to damages for loss of goodwill,
		work stoppage, computer failure or malfunction, or any and all
		other commercial damages or losses), even if such Contributor
		has been advised of the possibility of such damages.

		9. Accepting Warranty or Additional Liability. While redistributing
		the Work or Derivative Works thereof, You may choose to offer,
		and charge a fee for, acceptance of support, warranty, indemnity,
		or other liability obligations and/or rights consistent with this
		License. However, in accepting such obligations, You may act only
		on Your own behalf and on Your sole responsibility, not on behalf
		of any other Contributor, and only if You agree to indemnify,
		defend, and hold each Contributor harmless for any liability
		incurred by, or claims asserted against, such Contributor by reason
		of your accepting any such warranty or additional liability.

		END OF TERMS AND CONDITIONS

		Copyright 2026 Tether Data, S.A. de C.V.

+17

main.js

		#!/usr/bin/env node
		import { createRequire } from 'module'
		import { command, flag, summary, header } from 'paparam'
		import { commands } from './lib/commands/index.js'

		const { version } = createRequire(import.meta.url)('./package.json')

		// Commands are registered in lib/commands/index.js — see README for how to add one.
		const prog = command(
		'qvac-ci',
		header('qvac-ci v' + version),
		summary('CI utilities for the QVAC monorepo'),
		flag('--version\|-v', 'Print version and exit'),
		...commands
		)

		prog.parse()

+4

NOTICE

		@qvac/ci
		Copyright 2026 Tether Data, S.A. de C.V.

		This product includes software developed by Tether Data, S.A. de C.V.

+113

README.md

		# @qvac/ci

		CI utilities — a modular, extensible CLI for GitHub automation. Replaces inline YAML scripts with tested, versioned Node.js commands.

		> Note: Development and feature builds are published to GitHub Packages (GPR) under the name `@qvac/ci-mono`. The unscoped `@qvac/ci` name is only available after a release-branch npm publish.

		## Installation

		```bash
		npm install @qvac/ci
		```

		Or run directly in a GitHub Actions step:

		```bash
		npx @qvac/ci <command> [flags]
		```

		## Commands

		### `pending-approvals`

		Checks whether a PR has the required approvals from the right roles (Management, Team Lead, Member), then upserts a `## Review Status` comment on the PR summarising the current state.

		Always exits with code `0` — this command is informational only. Merge enforcement is delegated to GitHub-native branch protection (CODEOWNERS + ruleset approval requirements).

		> Note: This command is deprecated as part of the Tier 1 approval migration to native GitHub controls. It will be disabled after rollout validation.

		```bash
		qvac-ci pending-approvals \
		--pr-number 123 \
		--maintainers-team management \
		--team-leads-team team-leads \
		--min-approvals 2
		```

		Flags:

		\| Flag \| Description \| Default \|
		\|------\|-------------\|---------\|
		\| `--pr-number` \| PR number to check (required) \| — \|
		\| `--repo` \| `owner/repo` string \| `$GITHUB_REPOSITORY` \|
		\| `--maintainers-team` \| GitHub team slug for Management (required) \| — \|
		\| `--team-leads-team` \| GitHub team slug for Team Leads (required) \| — \|
		\| `--min-approvals` \| Minimum total approvals required \| `2` \|

		Environment variables (required):

		\| Variable \| Description \|
		\|----------\|-------------\|
		\| `GITHUB_TOKEN` \| Token used to post the review-status comment \|
		\| `GITHUB_APP_ID` \| GitHub App ID used for team membership resolution \|
		\| `GITHUB_PRIVATE_KEY` \| GitHub App private key (PEM) \|

		Secrets are env-only — there are no `--token` flags. This prevents tokens from appearing in the process list, shell history, or CI log echoes.

		Example GitHub Actions step:

		```yaml
		- name: Check PR approvals
		env:
		GITHUB_TOKEN: ${{ secrets.CI_TOKEN }}
		GITHUB_APP_ID: ${{ secrets.APP_ID }}
		GITHUB_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }}
		run: \|
		npx @qvac/ci pending-approvals \
		--pr-number ${{ github.event.pull_request.number }} \
		--maintainers-team management \
		--team-leads-team team-leads \
		--min-approvals 2
		```

		Comment format:

		The command upserts a single `## Review Status` comment on the PR (updates in place if one already exists):

		```
		## Review Status
		Current Status: ✅ APPROVED
		Approvals so far: Management: 1, Team Lead: 1
		```

		```
		## Review Status
		Current Status: ❌ PENDING
		Approvals so far: Member: 1

		Pending reviews: Needs 1 Management or Team Lead.
		```

		## Adding a new command

		1. Create `lib/commands/<name>/index.js` — extend `Command`, implement `toCommand()` and `_run()`.
		2. Create `lib/commands/<name>/helpers.js` — domain logic. Read secrets from `process.env`; never pass them as parameters. Export a mutable `helpers` object so tests can stub methods without a mock framework.
		3. Register in `lib/commands/index.js` — `main.js` picks it up automatically.
		4. Write tests in `test/unit/<name>/index.test.js` and `test/unit/<name>/helpers.test.js`. Mock all network calls.

		## Development

		```bash
		npm install
		npm test
		npm run lint
		npm run lint:fix
		```

		## Requirements

		Node.js `>=18.0.0`

		## License

		Apache-2.0

+54

-1

package.json

		@@ -1,1 +0,54 @@
		{"name":"@qvac/ci","version":"0.0.0"}
		{
		"name": "@qvac/ci",
		"version": "0.1.0",
		"description": "CI utilities for the QVAC monorepo",
		"author": "Tether",
		"license": "Apache-2.0",
		"type": "module",
		"main": "./main.js",
		"bin": {
		"qvac-ci": "./main.js"
		},
		"keywords": [
		"tether",
		"ci",
		"qvac"
		],
		"files": [
		"main.js",
		"lib/*/",
		"README.md",
		"CHANGELOG.md",
		"LICENSE",
		"NOTICE"
		],
		"engines": {
		"node": ">=18.0.0"
		},
		"scripts": {
		"lint": "standard",
		"lint:fix": "standard --fix",
		"test:unit": "brittle-node test/unit/.test.js test/unit//.test.js",
		"test": "npm run test:unit",
		"audit": "npm audit --audit-level=high"
		},
		"publishConfig": {
		"access": "public"
		},
		"bugs": "https://github.com/tetherto/qvac/issues",
		"repository": {
		"type": "git",
		"url": "git+https://github.com/tetherto/qvac.git",
		"directory": "packages/qvac-ci"
		},
		"homepage": "https://github.com/tetherto/qvac/tree/main/packages/qvac-ci#readme",
		"dependencies": {
		"@octokit/auth-app": "^8.2.0",
		"@octokit/rest": "^22.0.1",
		"paparam": "^1.10.1"
		},
		"devDependencies": {
		"brittle": "^3.10.1",
		"standard": "17.1.0"
		}
		}

@qvac/ci - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics

Dependency changes