@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/env/hotfixland.js

@@ -0,0 +1,302 @@
+'use strict'
+
+/**
+ * Run a hotfix land's steps — the engine half of `spec-env hotfix land`.
+ *
+ * `planHotfixLand` (hotfix.js) decides WHAT the land is; this module does it,
+ * the way `bootstrap.js` does a worktree's steps. It used to be a printed plan
+ * the skill ran by hand, and that stopped being possible the moment the release
+ * could be a project's own command: the prod tag is only known once that
+ * command has run and said what it cut, so no plan printed beforehand can name
+ * it.
+ *
+ * The run stops at the first step that fails, and the release is reported to
+ * `io.record` the moment it succeeds — so a land that stops later (a refused
+ * push, a conflicted cherry-pick) can be re-run without cutting a second
+ * release. skittership's own command refuses a second one anyway, since HEAD is
+ * then already tagged; the record is what lets the re-run carry on instead of
+ * stopping there.
+ *
+ * Every side effect goes through `io.spawn`, so tests drive it with a fake.
+ */
+
+const { spawnSync } = require('node:child_process')
+
+// The fields skittership's `release-hotfix.cjs --json` prints, and their types.
+// `versionCommit` is null only on its `--dry-run`, which skitterspec never
+// passes — so a null here is accepted, and means "no version commit to leave
+// behind", exactly as the built-in tagger's.
+const RELEASE_FIELDS = {
+  tag: 'string',
+  version: 'string',
+  baseTag: 'string',
+  branch: 'string',
+  versionCommit: 'string|null',
+  pushed: 'boolean',
+}
+
+/**
+ * Parse a release command's stdout STRICTLY: the whole of it, trimmed, must be
+ * one JSON object carrying every field above. Anything else — a package
+ * manager's run banner, a stray log line, a missing field — is a refusal rather
+ * than a best guess, because a guessed tag is a deploy of the wrong thing.
+ */
+function parseRelease(stdout) {
+  const text = String(stdout || '').trim()
+  if (!text) return { ok: false, reason: 'printed nothing on stdout — expected one JSON line' }
+  let obj
+  try {
+    obj = JSON.parse(text)
+  } catch {
+    const first = text.split('\n')[0].slice(0, 120)
+    return { ok: false, reason: `stdout is not one JSON object (starts: ${first})` }
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, reason: 'stdout is JSON but not an object' }
+  }
+  for (const [key, type] of Object.entries(RELEASE_FIELDS)) {
+    const v = obj[key]
+    const fits = type
+      .split('|')
+      .some((t) => (t === 'null' ? v === null : typeof v === t && (t !== 'string' || v.length)))
+    if (!fits) return { ok: false, reason: `JSON field "${key}" is missing or not ${type}` }
+  }
+  return { ok: true, release: obj }
+}
+
+/** One line describing a step, for `--plan` and the failure report. */
+function describeStep(step) {
+  switch (step.kind) {
+    case 'release':
+      if (step.via === 'command') return `release: ${step.command}`
+      if (step.via === 'recorded') return `release: ${step.tag} (cut earlier — not re-run)`
+      return `release: git tag ${step.tag}`
+    case 'push':
+      if (step.via === 'remote') return `push: ${step.tag || 'the tag'} is already on ${step.remote}`
+      if (step.via === 'hold') return `push: held — no consent to push to ${step.remote}`
+      return `push: ${step.branch}, then ${step.tag || 'the tag'}, to ${step.remote}`
+    case 'target':
+      return `target: ${step.base} -> ${step.tag} (cherry-pick, tag)`
+    case 'carry': {
+      const n = Array.isArray(step.commits) ? step.commits.length : 0
+      const what = n === 1 ? '1 commit' : `${n} commits`
+      if (step.strategy === 'worktree') return `carry: cherry-pick ${what} onto ${step.base} (throwaway worktree)`
+      return `carry: cherry-pick ${what} onto ${step.base}`
+    }
+    default:
+      return `unknown step ${step.kind}`
+  }
+}
+
+// The last non-blank line a command wrote to stderr — skittership's refusals
+// are one `✖ release-hotfix: <reason>` line there, and that is what to relay.
+function lastLine(text) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+  return lines.length ? lines[lines.length - 1] : null
+}
+
+function why(res) {
+  if (res.error) return res.error.message
+  return res.status === null ? `killed by ${res.signal || 'a signal'}` : `exit ${res.status}`
+}
+
+function runRelease(step, ctx) {
+  if (step.via === 'recorded') {
+    return { outcome: 'skipped', line: describeStep(step), release: step.release }
+  }
+  if (step.via === 'tag') {
+    const res = ctx.spawn('git', ['-C', step.cwd, 'tag', step.tag], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    })
+    if (res.error || res.status !== 0) {
+      return { outcome: 'failed', line: `${describeStep(step)} — ${lastLine(res.stderr) || why(res)}` }
+    }
+    const release = {
+      tag: step.tag,
+      version: step.tag.replace(/^\D*/, ''),
+      baseTag: step.baseTag,
+      branch: step.branch,
+      versionCommit: null,
+      pushed: false,
+    }
+    return { outcome: 'released', line: `tagged ${step.tag}`, release }
+  }
+  // A project's own command, through the shell. stdout is captured whole for
+  // the JSON; stderr is captured so a refusal can be relayed as its own line,
+  // and is passed on to ours so its progress output is not lost.
+  const res = ctx.spawn(step.command, {
+    cwd: step.cwd,
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  })
+  if (res.stderr) ctx.childStderr(res.stderr)
+  if (res.error || res.status !== 0) {
+    return { outcome: 'refused', line: `release refused — ${lastLine(res.stderr) || why(res)}` }
+  }
+  const parsed = parseRelease(res.stdout)
+  if (!parsed.ok) return { outcome: 'refused', line: `release refused — ${parsed.reason}` }
+  return { outcome: 'released', line: `released ${parsed.release.tag}`, release: parsed.release }
+}
+
+// Publish the release. The tag is the release's, known only once it has run,
+// so the argvs are built here rather than in the plan. `hold` is not a failure:
+// it is the operator not having said yes, and it stops the run so nothing after
+// it is carried before the deploy tag is public.
+function runPush(step, release, ctx) {
+  const s = { ...step, tag: release ? release.tag : null }
+  if (s.via === 'remote') return { outcome: 'skipped', line: describeStep(s) }
+  if (s.via === 'hold') return { outcome: 'held', line: describeStep(s) }
+  if (!release) return { outcome: 'failed', line: `${describeStep(s)} — no release to push` }
+  for (const ref of [s.branch, s.tag]) {
+    const argv = ['-C', s.cwd, 'push', s.remote, ref]
+    const res = ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
+    if (res.error || res.status !== 0) {
+      return { outcome: 'failed', line: `push ${ref} to ${s.remote} — ${lastLine(res.stderr) || why(res)}` }
+    }
+  }
+  return { outcome: 'pushed', line: `pushed ${s.branch}, then ${s.tag}, to ${s.remote}` }
+}
+
+/**
+ * Carry the fix onto the base branch, one commit at a time so a conflict can
+ * name the commit that caused it.
+ *
+ * Three strategies, chosen by the caller from where the base branch is:
+ *   inplace  — checked out and clean: cherry-pick there.
+ *   worktree — not checked out anywhere: a throwaway worktree on it, removed
+ *              afterwards, so the branch moves without anyone's checkout moving.
+ *   dirty    — checked out with uncommitted work: refuse, and print the command
+ *              to run by hand once it is clean. Somebody's work is in that tree.
+ * On a conflict the cherry-pick is aborted, which leaves the base branch where
+ * it was before that commit, and the hotfix branch and its record untouched —
+ * so a re-run tries the carry again.
+ */
+function runCarry(step, release, ctx) {
+  const version = release && release.versionCommit
+  // The version commit cannot be in a list made before the release cut it,
+  // but a re-run lists the branch after — so it is left out here as well.
+  const commits = (step.commits || []).filter((sha) => !version || sha !== version)
+  if (!commits.length) {
+    return { outcome: 'skipped', line: `carry: nothing to carry — ${step.base} already has the fix`, carried: 0 }
+  }
+  if (step.strategy === 'dirty') {
+    return {
+      outcome: 'refused',
+      line:
+        `carry: ${step.cwd} has uncommitted changes on ${step.base} — commit or stash them, ` +
+        `then run: git -C ${step.cwd} cherry-pick ${commits.join(' ')}`,
+    }
+  }
+  const git = (argv) =>
+    ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
+  let cwd = step.cwd
+  if (step.strategy === 'worktree') {
+    cwd = step.tmpPath
+    const res = git(['-C', step.root, 'worktree', 'add', cwd, step.base])
+    if (res.error || res.status !== 0) {
+      return { outcome: 'failed', line: `carry: worktree add ${cwd} — ${lastLine(res.stderr) || why(res)}` }
+    }
+  }
+  const cleanup = () => {
+    if (step.strategy === 'worktree') git(['-C', step.root, 'worktree', 'remove', '--force', cwd])
+  }
+  for (const sha of commits) {
+    const res = git(['-C', cwd, 'cherry-pick', sha])
+    if (res.error || res.status !== 0) {
+      git(['-C', cwd, 'cherry-pick', '--abort'])
+      cleanup()
+      return {
+        outcome: 'failed',
+        line:
+          `carry: cherry-pick ${sha} onto ${step.base} conflicted — aborted; ` +
+          `${lastLine(res.stderr) || why(res)}`,
+      }
+    }
+  }
+  cleanup()
+  const what = commits.length === 1 ? '1 commit' : `${commits.length} commits`
+  return { outcome: 'ran', line: `carried ${what} onto ${step.base}`, carried: commits.length }
+}
+
+// A step that is a list of git argvs run in order — a target's worktree,
+// cherry-pick, tag and cleanup, or the carry's cherry-pick.
+function runArgvs(step, ctx) {
+  for (const argv of step.argvs) {
+    const res = ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
+    if (res.error || res.status !== 0) {
+      return {
+        outcome: 'failed',
+        line: `${describeStep(step)} — git ${argv.join(' ')}: ${lastLine(res.stderr) || why(res)}`,
+      }
+    }
+  }
+  return { outcome: 'ran', line: describeStep(step) }
+}
+
+/**
+ * Run `steps` in order, stopping at the first that fails or refuses.
+ *
+ * io: { spawn?, write?, record?, childStdout?, childStderr? }
+ *   - `write(line)` receives every report line as it happens
+ *   - `record(release)` is called once, as soon as a release succeeds
+ *
+ * Returns { ok, held, results, failedAt, release } — `release` is what the
+ * release step cut (or found recorded), or null if it never got that far.
+ * `held` is a run that stopped at the push for want of consent: not a failure,
+ * and nothing after it ran.
+ */
+function runHotfixLand(steps, io = {}) {
+  const ctx = {
+    spawn: io.spawn || spawnSync,
+    childStdout: io.childStdout || 'inherit',
+    childStderr: io.childStderr || ((t) => process.stderr.write(t)),
+  }
+  const write = io.write || (() => {})
+  const results = []
+  let release = null
+  let carried = null
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]
+    let r
+    try {
+      if (step.kind === 'release') r = runRelease(step, ctx)
+      else if (step.kind === 'push') r = runPush(step, release, ctx)
+      else if (step.kind === 'carry') r = runCarry(step, release, ctx)
+      else if (step.kind === 'target') {
+        // A project's release command can cut a tag the built-in tagger also
+        // planned for a target on the same root. Refuse rather than collide.
+        if (step.kind === 'target' && release && release.tag === step.tag) {
+          r = { outcome: 'refused', line: `${describeStep(step)} — the release already cut ${step.tag}` }
+        } else r = runArgvs(step, ctx)
+      } else r = { outcome: 'failed', line: describeStep(step) }
+    } catch (err) {
+      r = { outcome: 'failed', line: `${describeStep(step)} — ${err.message}` }
+    }
+    results.push({ step, outcome: r.outcome, line: r.line })
+    if (typeof r.carried === 'number') carried = r.carried
+    if (r.release) {
+      release = r.release
+      if (r.outcome === 'released' && io.record) io.record(release)
+    }
+    if (r.outcome === 'pushed' && release) {
+      release = { ...release, pushed: true }
+      if (io.record) io.record(release)
+    }
+    if (r.outcome === 'held') {
+      if (r.line) write(r.line)
+      return { ok: true, held: true, results, failedAt: null, release, carried }
+    }
+    if (r.outcome === 'failed' || r.outcome === 'refused') {
+      return { ok: false, results, failedAt: i + 1, release, carried }
+    }
+    if (r.line) write(r.line)
+  }
+  return { ok: true, held: false, results, failedAt: null, release, carried }
+}
+
+module.exports = { parseRelease, runHotfixLand, describeStep, RELEASE_FIELDS }

package/src/env/integrate.js

@@ -0,0 +1,167 @@
+'use strict'
+
+const { globToRegExp } = require('./glob.js')
+
+/**
+ * Pure integrate planner for `spec-env integrate`.
+ *
+ * `planIntegrate` decides whether a spec's worktree branch can be landed onto the
+ * base branch and, if so, emits the exact commands the `/spec-complete` skill runs
+ * (rebase the branch onto base in the worktree, then fast-forward base to it in the
+ * primary checkout). It performs no side effects: the caller (the CLI) queries git
+ * for `dirty`/`aheadOfBase`/`mainRepoPath` and supplies them, keeping this
+ * deterministic and unit-testable with no live git.
+ *
+ * Strategy is rebase + fast-forward (linear history). Conflict handling lives in
+ * the skill: it runs the rebase and, on a non-zero exit, `git rebase --abort` and
+ * hands back — so the planner never needs to reason about conflicts.
+ *
+ * @param {object} spec  resolved spec: { branch, worktreePath, folder, ... }
+ * @param {object} config normalised env config (reads `afterLand`).
+ * In CHECKOUT mode there is no worktree: the branch is already checked out in the
+ * primary checkout, so landing is a rebase in place, a switch to base, and the
+ * fast-forward. `planIntegrateCheckout` below covers that; the shape of what it
+ * returns is identical so callers need no second code path.
+ *
+ * @param {object} ctx   { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath,
+ *                        changedFiles } — `changedFiles` is what the land brings
+ *                        in (`base...branch`), or null when it could not be read
+ * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
+ */
+function planIntegrate(spec, config, ctx) {
+  const { worktreeState = {}, base, aheadOfBase, mainRepoPath } = ctx || {}
+  const branch = spec.branch
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
+
+  // The completion edits must be committed first — never rebase a dirty tree.
+  if (worktreeState.dirty) {
+    return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the completion first' }
+  }
+
+  // Nothing on the branch that isn't already on base → already landed. The
+  // after-land commands still apply: the land may have happened on another
+  // machine or in an earlier session, leaving them pending in THIS checkout.
+  // That earlier land's range is unknown here, so the range is null.
+  if (!aheadOfBase) {
+    return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath, null) }
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${spec.worktreePath} rebase ${base}`,
+      `git -C ${mainRepoPath} merge --ff-only ${branch}`,
+    ],
+    afterLand: afterLandFor(config, mainRepoPath, rangeOf(ctx)),
+  }
+}
+
+/**
+ * Pure integrate planner for CHECKOUT mode.
+ *
+ * The branch lives in the primary checkout, so `git -C <worktree> rebase` — the
+ * worktree-mode plan — has nothing to address. Landing is three steps in one
+ * repo: rebase onto base, switch to base, fast-forward.
+ *
+ * The switch is what makes this safe to repeat. Leaving the checkout on the spec
+ * branch after landing would mean the next `spec-env up` refuses ("standing on
+ * another spec's branch") for a spec that is finished, and the operator would
+ * have to know to switch back by hand.
+ *
+ * ctx: { dirty, base, aheadOfBase, checkoutPath, onBranch, changedFiles }
+ */
+function planIntegrateCheckout(spec, config, ctx) {
+  const { dirty, base, aheadOfBase, checkoutPath, onBranch } = ctx || {}
+  const branch = spec.branch
+  const result = {
+    blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
+  }
+
+  // "Already landed" is answered FIRST, before any refusal. A landed spec needs
+  // no action wherever the checkout happens to be standing — and after a
+  // successful land it is standing on base, so asking "not on the branch" here
+  // would refuse the very spec this just finished landing. /spec-complete calls
+  // integrate again on exactly that state.
+  if (!aheadOfBase) {
+    return { ...result, noop: true, afterLand: afterLandFor(config, checkoutPath, null) }
+  }
+  if (dirty) {
+    return {
+      ...result,
+      blocked: true,
+      reason: 'the checkout has uncommitted changes — commit the completion first',
+    }
+  }
+  // There IS something to land, so where you are standing now matters: the
+  // branch is the checkout in this mode, and landing from elsewhere would
+  // rebase and fast-forward a branch the operator is not looking at.
+  if (onBranch === false) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `the checkout is not on ${branch} — switch to it before landing`,
+    }
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${checkoutPath} rebase ${base}`,
+      `git -C ${checkoutPath} switch ${base}`,
+      `git -C ${checkoutPath} merge --ff-only ${branch}`,
+    ],
+    afterLand: afterLandFor(config, checkoutPath, rangeOf(ctx)),
+  }
+}
+
+// The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
+// primary checkout, standing on base) once the land commands have succeeded.
+// A blocked plan carries the empty form — nothing landed, so nothing follows.
+//
+// `range` is the files the land changes: a list (possibly empty) when known,
+// null when it is not. Each entry gets a decision — `always` (no `when`),
+// `matched` (with the first path that hit), `skipped`, or `unknown` — and
+// `commands` is every entry but the skipped ones, in config order.
+//
+// AN UNKNOWN RANGE RUNS THE CONDITIONAL ENTRIES. A land made elsewhere, or a
+// diff git would not answer, says nothing about what changed, and only one
+// reading is harmless: a redundant generate costs seconds, a skipped one leaves
+// the base red with nothing pointing at why (`.claude/rules/negative-checks.md`
+// rule 4). An EMPTY known range is not unknown — a land whose commits touch no
+// files is healthy, and it skips them.
+function afterLandFor(config, cwd, range = null) {
+  const raw = (config && Array.isArray(config.afterLand)) ? config.afterLand : []
+  const entries = raw.map((e) => decide(asEntry(e), range))
+  const commands = entries.filter((e) => e.decision !== 'skipped').map((e) => e.run)
+  return { cwd: entries.length ? cwd : null, commands, entries, range }
+}
+
+function decide(entry, range) {
+  if (!entry.when) return { ...entry, decision: 'always', matched: null }
+  if (range === null) return { ...entry, decision: 'unknown', matched: null }
+  const res = entry.when.map(globToRegExp)
+  const matched = range.find((f) => res.some((r) => r.test(f)))
+  return matched === undefined
+    ? { ...entry, decision: 'skipped', matched: null }
+    : { ...entry, decision: 'matched', matched }
+}
+
+// Normalised config holds `{ run, when }`; a pure caller may still hand over
+// the plain string an entry is written as.
+function asEntry(entry) {
+  return typeof entry === 'string' ? { run: entry, when: null } : { run: entry.run, when: entry.when || null }
+}
+
+// `changedFiles` from a planner's ctx, with anything that is not a list read as
+// unknown — a caller that did not supply it said nothing about the range.
+function rangeOf(ctx) {
+  return Array.isArray(ctx && ctx.changedFiles) ? ctx.changedFiles : null
+}
+
+function noAfterLand() {
+  return { cwd: null, commands: [], entries: [], range: null }
+}
+
+module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor, rangeOf }