@skitterbyte/skitterspec-linear 10.6.0 → 10.8.0

package/src/env/teardown.js

@@ -13,6 +13,12 @@
  * Volumes are the only destructive action — dropped by default (reclaims disk)
  * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
  * configured.
+ *
+ * `commands` is safe for a caller to run BLIND — that is the property the remote
+ * delete must not break. A remote branch delete reaches outside this machine, so
+ * it is returned in a separate `remoteCommands` array that the skills confirm
+ * with the user before running, and it never enters `commands` unless the
+ * project has opted in with `teardown.deleteRemoteBranch: "always"`.
  */
 
 const { expandTokens } = require('./resolve.js')
@@ -21,9 +27,10 @@ const { expandTokens } = require('./resolve.js')
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
  * @param {object} config normalised env config.
  * @param {object} flags { keepVolumes, force }
- * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag }, timestamp }
- * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
- *                     volumesDropped }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag,
+ *                     remoteBranch }, timestamp }
+ * @returns {object} { blocked, reason, commands, remoteCommands, backupCommand,
+ *                     backupPath, volumesDropped }
  */
 function planDown(spec, config, flags, ctx) {
   const { worktreeState = {}, timestamp } = ctx || {}
@@ -113,7 +120,57 @@ function planDown(spec, config, flags, ctx) {
     commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
-  return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
+  // --- delete the branch on the remote (planned, never run here) ---
+  //
+  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // leaves a merged branch on the remote forever. Cleaning that up is the goal;
+  // doing it safely is the constraint.
+  //
+  // Gated on `landed` because until the branch is merged (or captured by a tag)
+  // the remote copy is the ONLY backup of the work — that is the whole reason
+  // `refuseTeardownIfUnpushed` exists, and deleting the remote branch of an
+  // unlanded spec would defeat it. `--force` deliberately does NOT enable this:
+  // force is for "I accept losing this worktree", not "also reach out and delete
+  // the backup". The same `landed` that decides `-D` vs `-d` decides this, so the
+  // two can never disagree about whether the commits are recoverable.
+  //
+  // A null `remoteBranch` plans nothing. An absence is not evidence — the branch
+  // may well be on a remote this clone cannot see (pushed from another machine),
+  // and the honest answer to "is there a remote branch?" is then "cannot tell",
+  // which routes to doing nothing.
+  const remoteCommands = []
+  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
+  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
+    // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
+    // itself contains slashes, so the remote is what remains once the exact
+    // "/<branch>" suffix is stripped — not the text before the first slash.
+    //
+    // If it does not end that way the ref maps to a differently-named branch on
+    // the remote (a push refspec, or push.default set to something exotic). We
+    // cannot tell what to delete, so we plan nothing rather than guess at a
+    // branch name on someone's shared remote.
+    const suffix = `/${spec.branch}`
+    if (worktreeState.remoteBranch.endsWith(suffix)) {
+      const remote = worktreeState.remoteBranch.slice(0, -suffix.length)
+      if (remote) {
+        const cmd = `git push ${remote} --delete ${spec.branch}`
+        // "always" is the project saying it never wants to be asked, so the push
+        // joins the run-blind list. Everything else keeps it quarantined.
+        if (policy === 'always') commands.push(cmd)
+        else remoteCommands.push(cmd)
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    reason: null,
+    commands,
+    remoteCommands,
+    backupCommand,
+    backupPath,
+    volumesDropped,
+  }
 }
 
 function blocked(reason) {
@@ -121,6 +178,7 @@ function blocked(reason) {
     blocked: true,
     reason,
     commands: [],
+    remoteCommands: [],
     backupCommand: null,
     backupPath: null,
     volumesDropped: false,

package/src/init.js

@@ -23,6 +23,21 @@ function listSkills() {
     .sort()
 }
 
+// Slash commands shipped as `assets/commands/*.md`, installed to
+// `.claude/commands/`. Discovered from the bundled tree exactly like skills, so
+// each distribution installs precisely what it ships.
+function listCommands() {
+  const dir = path.join(ASSETS, 'commands')
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no commands
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -42,6 +57,8 @@ function listCoreTemplates() {
 
 const SKILLS = listSkills()
 
+const COMMANDS = listCommands()
+
 const RULES = listRules()
 
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
@@ -50,6 +67,89 @@ const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled'
 // env.config isolation templates; a provider superset also ships its own).
 const CORE_FILES = listCoreTemplates()
 
+// The CLI is a local devDependency and never on PATH, so a command file that
+// pre-executes it must carry a literal, working invocation. Detect the runner
+// from the lockfile and bake it in at write time.
+//
+// The lockfile is a POSITIVE signal — a file that must be present for the answer
+// to be yes — rather than an absence. When none is found we do not guess a
+// package manager we have no evidence for; `npx` is the fallback because it is
+// the one runner that works across all three installs.
+const PACKAGE_MANAGERS = [
+  ['pnpm-lock.yaml', 'pnpm exec'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npx'],
+  ['bun.lockb', 'bunx'],
+]
+
+function detectPackageManager(dir) {
+  for (const [lockfile, exec] of PACKAGE_MANAGERS) {
+    if (fs.existsSync(path.join(dir, lockfile))) return exec
+  }
+  return 'npx'
+}
+
+// Fill a command file's `{{exec}}` placeholders. Kept a pure function of
+// (content, dir) so `managedTargets` can compare against exactly what
+// `installCommands` would write — otherwise every install would hash as
+// customized on the next run.
+function renderCommand(content, dir) {
+  return content.split('{{exec}}').join(detectPackageManager(dir))
+}
+
+// --- composed-assets guard -------------------------------------------------
+//
+// A source package's `assets/` is PRE-composition: `<!-- seam:NAME -->` is still
+// literal text that scripts/build-dist.js replaces — with a provider's fragment
+// for the provider distribution, with nothing for the base. Only a built
+// distribution's assets are installable.
+//
+// This is a POSITIVE signal, not an absence: a seam marker must be **present**
+// for the guard to fire, so it cannot misfire on a tree it simply failed to read.
+// And it refuses rather than repairing — installing the wrong thing is the
+// expensive mistake here. In a dev-linked checkout the installed skills are
+// symlinks to the composed distribution, so a `--force` install would write
+// these markers straight through the link and into the built assets.
+const SEAM_RE = /<!--\s*seam:[A-Za-z0-9_-]+\s*-->/
+
+function assetFiles(dir) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return // a distribution need not ship every asset kind
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(dir)
+  return out
+}
+
+// Throws when this package's assets are uncomposed. Called from the **bins** —
+// the outermost boundary, and the only way a real install happens — never from
+// init()/resync()/run(), which the unit tests legitimately drive against this
+// source tree. Guarding any deeper would make the library untestable while
+// protecting nothing extra.
+function assertComposedAssets() {
+  const offenders = assetFiles(ASSETS)
+    .filter((f) => SEAM_RE.test(fs.readFileSync(f, 'utf8')))
+    .map((f) => path.relative(ASSETS, f))
+  if (!offenders.length) return
+  throw new Error(
+    `refusing to install: this package's assets are uncomposed (${offenders.length} ` +
+      `file(s) still carry a <!-- seam:… --> marker, e.g. ${offenders[0]}).\n` +
+      '  These are a workspace source package\'s assets, not a distribution\'s. ' +
+      'Run "npm run build" in the skitterspec repo, then run the command again ' +
+      'from the built distribution.',
+  )
+}
+
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
@@ -99,13 +199,15 @@ function sha1(content) {
 // the bundled content that ships in this distribution's assets.
 function managedTargets(dir) {
   const out = []
-  const add = (assetRel, targetAbs) =>
+  const add = (assetRel, targetAbs, render = (c) => c) =>
     out.push({
       relPath: rel(dir, targetAbs),
       abs: targetAbs,
-      bundled: fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'),
+      bundled: render(fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'), dir),
     })
   for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of COMMANDS)
+    add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
   for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
   for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
   return out
@@ -230,6 +332,16 @@ function installSkills(dir, opts) {
   }
 }
 
+function installCommands(dir, opts) {
+  for (const name of COMMANDS) {
+    const content = renderCommand(
+      fs.readFileSync(path.join(ASSETS, 'commands', name), 'utf8'),
+      dir,
+    )
+    writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
+  }
+}
+
 function installRule(dir, opts) {
   for (const name of RULES) {
     copyAsset(
@@ -519,6 +631,7 @@ function reset(dir, { claudeMd = true } = {}) {
   }
   if (claudeMd) stripClaudeMdSection(dir)
   installSkills(dir, { force: true })
+  installCommands(dir, { force: true })
   installRule(dir, { force: true })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -597,6 +710,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   resetReport()
 
   installSkills(dir, { force })
+  installCommands(dir, { force })
   installRule(dir, { force })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -615,6 +729,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
 module.exports = {
   init,
   SKILLS,
+  COMMANDS,
   RULES,
   SPEC_FOLDERS,
   MANIFEST_FILE,
@@ -627,4 +742,7 @@ module.exports = {
   resync,
   reset,
   assertSafeToDelete,
+  assertComposedAssets,
+  detectPackageManager,
+  renderCommand,
 }