Skip to content

Starfie1d1272/dsh-github-skills / skills/gh-publish

gh-publish

Verified

Publish task-scoped changes to GitHub through a branch/commit/push/PR flow, including fork-based external contributions. Use when the user wants changes pushed or a PR opened; draft PR is the default.

FileKindSize
SKILL.mdskill md2.8 KB
scripts/publish-preflight.mjsscript9.2 KB

scripts/publish-preflight.mjs

View on GitHub
#!/usr/bin/env node
/**
 * publish-preflight.mjs — deterministic, strictly READ-ONLY scope evidence
 * for a git working tree, so publish-scope confirmation never depends on
 * guessing.
 *
 * Outputs: git root, branch, detached state, default branch, origin URL,
 * upstream ref, porcelain status, staged/unstaged/untracked file lists,
 * per-file diff stats (staged and unstaged), ahead/behind counts, a
 * `mixedWorktree` flag, and warnings.
 *
 * SAFETY: this script performs ZERO write operations. It never runs
 * `git add`, `git commit`, `git push`, `git reset`, `git stash`,
 * `git checkout`, or `git switch`. Every command is argv-based
 * (no shell interpolation) and read-only.
 *
 * Usage:
 *   node publish-preflight.mjs [--repo <path>] [--json]
 *
 * stdout: one stable JSON document (always JSON; --json is accepted for
 * symmetry with the other helpers). stderr: diagnostics only.
 * Exit codes: 0 ok, 1 not a git repository, 2 usage error.
 */

import { spawnSync } from 'node:child_process'
import { pathToFileURL } from 'node:url'

import { redact } from '../../../lib/redact.mjs'

const WRITE_COMMANDS = new Set(['add', 'commit', 'push', 'reset', 'stash', 'checkout', 'switch', 'rm', 'mv', 'clean', 'restore'])

export function parseArgs(argv) {
  const args = { repo: '.', json: false }
  for (let index = 0; index < argv.length; index += 1) {
    const flag = argv[index]
    const value = argv[index + 1]
    if (flag === '--repo' && value !== undefined) { args.repo = value; index += 1 }
    else if (flag === '--json') args.json = true
    else if (flag === '--help' || flag === '-h') { printUsage(); process.exit(0) }
    else {
      process.stderr.write(`publish-preflight: unknown argument ${redact(JSON.stringify(flag))}\n`)
      printUsage()
      process.exit(2)
    }
  }
  return args
}

export function printUsage() {
  process.stdout.write(
    'Usage: node publish-preflight.mjs [--repo <path>] [--json]\n' +
    'Read-only git scope preflight. Never modifies the working tree.\n',
  )
}

/** Run git with argv only; returns {status, stdout, stderr}. Never a shell. */
function git(args, cwd, options = {}) {
  // Defense in depth: a read-only preflight must never invoke a write subcommand.
  const subcommand = args[0]
  if (WRITE_COMMANDS.has(subcommand)) {
    throw new Error(`publish-preflight: refusing to run write command git ${subcommand}`)
  }
  const result = spawnSync('git', args, {
    encoding: 'utf8',
    cwd,
    timeout: options.timeout ?? 30_000,
    maxBuffer: 16 * 1024 * 1024,
  })
  if (result.error !== undefined) throw new Error(`failed to run git: ${result.error.message}`)
  // Internal state stays RAW; credential redaction happens only at the
  // output/error boundary (a credential-bearing remote URL such as
  // https://user:TOKEN@github.com/... is sanitized before stdout).
  return {
    status: result.status,
    stdout: result.stdout ?? '',
    stderr: result.stderr ?? '',
  }
}

function gitOk(args, cwd) {
  const result = git(args, cwd)
  return result.status === 0 ? result.stdout.trim() : undefined
}

function parseStatusLine(line) {
  // porcelain v1: "XY path" (renames/copies: "R  old -> new")
  if (line.length < 3) return undefined
  const code = line.slice(0, 2)
  let path = line.slice(3)
  const renameMatch = /^(.*) -> (.*)$/.exec(path)
  if (renameMatch !== null) path = renameMatch[2]
  return { code, path }
}

function isStaged(code) {
  const x = code[0]
  return x !== ' ' && x !== '?' && x !== '!'
}

function isUnstaged(code) {
  const x = code[0]
  if (x === '?') return false
  return code[1] !== ' '
}

function parseNumstat(text) {
  const files = []
  for (const line of text.split('\n')) {
    if (line === '') continue
    const [added, deleted, ...pathParts] = line.split('\t')
    if (pathParts.length === 0) continue
    files.push({
      path: pathParts.join('\t'),
      added: added === '-' ? null : Number(added),
      deleted: deleted === '-' ? null : Number(deleted),
    })
  }
  return files
}

function resolveDefaultBranch(cwd) {
  const ref = gitOk(['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD'], cwd)
  if (ref !== undefined && ref.startsWith('origin/')) return ref.slice('origin/'.length)
  return undefined
}

function resolveAheadBehind(cwd, upstream, branch, origin) {
  const ref = upstream ?? (branch !== undefined && origin !== undefined ? `origin/${branch}` : undefined)
  if (ref === undefined) return null
  const result = git(['rev-list', '--left-right', '--count', `${ref}...HEAD`], cwd)
  if (result.status !== 0) return null
  const [behind, ahead] = result.stdout.trim().split(/\s+/).map((value) => Number(value))
  if (!Number.isInteger(behind) || !Number.isInteger(ahead)) return null
  return { ahead, behind }
}

export function collectPreflight(repoPath) {
  const root = gitOk(['rev-parse', '--show-toplevel'], repoPath)
  if (root === undefined) throw new Error(`not inside a git repository: ${repoPath}`)

  // `git branch --show-current` exits 0 with an empty line when HEAD is
  // detached, so an empty string means "no branch" just like an undefined one.
  const branchRaw = gitOk(['branch', '--show-current'], root)
  const branch = branchRaw === '' ? undefined : branchRaw
  const detached = branch === undefined
  const head = gitOk(['rev-parse', 'HEAD'], root) ?? null
  const defaultBranch = resolveDefaultBranch(root)
  const origin = gitOk(['remote', 'get-url', 'origin'], root) ?? undefined
  const upstream = gitOk(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], root) ?? undefined

  // Multi-line outputs must NOT be trimmed globally: porcelain v1 and numstat
  // use leading columns/whitespace that a whole-output trim would corrupt.
  const statusRaw = git(['status', '--porcelain=v1'], root).stdout
  const status = statusRaw.split('\n').filter((line) => line !== '').map(parseStatusLine).filter(Boolean)
  const stagedFiles = status.filter((entry) => isStaged(entry.code)).map((entry) => entry.path)
  const unstagedFiles = status.filter((entry) => isUnstaged(entry.code)).map((entry) => entry.path)
  const untrackedFiles = status.filter((entry) => entry.code.startsWith('?')).map((entry) => entry.path)
  // A file with BOTH staged and unstaged hunks (porcelain MM/AM/...): never
  // blindly `git add <file>` it again — that would sweep the unstaged hunks in.
  const partiallyStagedFiles = status
    .filter((entry) => isStaged(entry.code) && isUnstaged(entry.code))
    .map((entry) => entry.path)

  const stagedStat = parseNumstat(git(['diff', '--cached', '--numstat'], root).stdout)
  const unstagedStat = parseNumstat(git(['diff', '--numstat'], root).stdout)

  const aheadBehind = resolveAheadBehind(root, upstream, branch, origin)

  // Objective change-class signals. `mixedWorktree` is a conservative
  // heuristic (any two change classes present), never a scope verdict: the
  // skill must still judge scope from the actual diff and task intent.
  const hasStaged = stagedFiles.length > 0
  const hasUnstaged = unstagedFiles.length > 0
  const hasUntracked = untrackedFiles.length > 0
  const changeClassCount = Number(hasStaged) + Number(hasUnstaged) + Number(hasUntracked)
  const multipleChangeClasses = changeClassCount > 1
  const scopeNeedsInspection = multipleChangeClasses || partiallyStagedFiles.length > 0
  const mixedWorktree = (hasStaged && hasUnstaged) || (hasStaged && hasUntracked) || (hasUnstaged && hasUntracked)

  const warnings = []
  if (detached) warnings.push('detached HEAD: no branch is checked out')
  if (origin === undefined) warnings.push('no origin remote configured')
  if (upstream === undefined && branch !== undefined && origin !== undefined) warnings.push(`branch ${branch} has no upstream; push would need -u`)
  if (untrackedFiles.length > 0) warnings.push(`${untrackedFiles.length} untracked file(s) present`)
  if (aheadBehind !== null && aheadBehind.ahead > 0) warnings.push(`${aheadBehind.ahead} unpushed commit(s) on this branch`)
  if (aheadBehind !== null && aheadBehind.behind > 0) warnings.push(`${aheadBehind.behind} commit(s) behind the remote ref`)
  if (partiallyStagedFiles.length > 0) warnings.push(`partially staged file(s) need hunk-level attention: ${partiallyStagedFiles.join(', ')}`)
  if (scopeNeedsInspection) warnings.push('working tree mixes change classes; confirm scope before staging')

  return {
    schemaVersion: 1,
    gitRoot: root,
    head,
    branch: branch ?? null,
    detached,
    defaultBranch: defaultBranch ?? null,
    origin: origin ?? null,
    upstream: upstream ?? null,
    status,
    stagedFiles,
    unstagedFiles,
    untrackedFiles,
    partiallyStagedFiles,
    hasStaged,
    hasUnstaged,
    hasUntracked,
    multipleChangeClasses,
    scopeNeedsInspection,
    diffStat: { staged: stagedStat, unstaged: unstagedStat },
    aheadBehind,
    mixedWorktree,
    warnings,
  }
}

export function main(argv) {
  const args = parseArgs(argv)
  try {
    const preflight = collectPreflight(args.repo)
    process.stdout.write(`${redact(JSON.stringify(preflight, null, 2))}\n`)
  } catch (error) {
    process.stderr.write(`publish-preflight: ${redact(error instanceof Error ? error.message : String(error))}\n`)
    process.exitCode = 1
  }
}

if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main(process.argv.slice(2))
}
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall