@skitterbyte/skitterspec 1.0.0 → 2.0.0

package/src/deprecate.js

@@ -0,0 +1,138 @@
+'use strict'
+
+// Cleanup path for projects that installed release tooling from an older
+// skitterspec (before it moved to @skitterbyte/skittership). `skitterspec update`
+// detects the leftover files and — only on an explicit interactive "yes" or the
+// --remove-release-tooling flag — removes exactly what skitterspec used to
+// install. It never touches the user's generated CHANGELOG.md / RELEASES.md, nor
+// any script it didn't add.
+
+const fs = require('fs')
+const path = require('path')
+
+const SKITTERSHIP = '@skitterbyte/skittership'
+
+// Files/dirs skitterspec used to install for release tooling (repo-relative).
+const RELEASE_PATHS = [
+  'skitterspec.config.json',
+  path.join('scripts', 'generate-changelog.js'),
+  path.join('scripts', 'generate-releases.js'),
+  path.join('scripts', 'lib', 'git-commits.js'),
+  path.join('scripts', 'lib', 'config.js'),
+  path.join('.claude', 'skills', 'commit'),
+  path.join('.claude', 'rules', 'commit-messages.md'),
+]
+
+// npm scripts skitterspec used to wire; only removed when their value still
+// matches the generator command (so a user's custom override is preserved).
+const HELPER_SCRIPTS = {
+  changelog: 'node scripts/generate-changelog.js',
+  'changelog:retro': 'node scripts/generate-changelog.js --retro',
+  releases: 'node scripts/generate-releases.js',
+  'releases:retro': 'node scripts/generate-releases.js --retro',
+}
+
+function readPkg(dir) {
+  const pkgPath = path.join(dir, 'package.json')
+  if (!fs.existsSync(pkgPath)) return null
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+// Does package.json have a `version` script that runs the release generators?
+function versionHookReferencesGenerators(pkg) {
+  const v = pkg && pkg.scripts && pkg.scripts.version
+  return typeof v === 'string' && /generate-(changelog|releases)\.js/.test(v)
+}
+
+// Is skittership the source of the release tooling here (rather than a leftover
+// legacy skitterspec install)? True when the project has adopted skittership —
+// its config file is present, or it's a declared dependency. In that case the
+// release files are skittership's current install and must NOT be offered for
+// removal (they'd just come back on the next `skittership init`).
+function skittershipAdopted(dir) {
+  if (fs.existsSync(path.join(dir, 'skittership.config.json'))) return true
+  const pkg = readPkg(dir)
+  const deps = Object.assign({}, pkg && pkg.dependencies, pkg && pkg.devDependencies)
+  return Boolean(deps['@skitterbyte/skittership'])
+}
+
+// Report which release-tooling artifacts are present. `present` is true only when
+// there are legacy artifacts to clean up (a file/dir or a generator-driven version
+// hook) AND skittership hasn't been adopted — otherwise the files belong to a
+// live skittership install, not an old bundled-skitterspec one.
+function detectReleaseTooling(dir) {
+  const files = RELEASE_PATHS.filter((rel) => fs.existsSync(path.join(dir, rel)))
+  const pkg = readPkg(dir)
+  const versionHook = versionHookReferencesGenerators(pkg)
+  const adopted = skittershipAdopted(dir)
+  return { present: (files.length > 0 || versionHook) && !adopted, files, versionHook, adopted }
+}
+
+// Remove an emptied directory, walking up while parents are left empty. Never
+// climbs out of `dir`.
+function pruneEmptyDirs(dir, startAbs) {
+  let cur = startAbs
+  while (cur.startsWith(dir) && cur !== dir && fs.existsSync(cur)) {
+    if (fs.readdirSync(cur).length > 0) break
+    fs.rmdirSync(cur)
+    cur = path.dirname(cur)
+  }
+}
+
+// Remove exactly the detected artifacts + unwire the version hook. Returns a
+// report of what was removed. Scoped and non-destructive: only skitterspec's own
+// files, and only npm scripts whose value still matches the generator command.
+function removeReleaseTooling(dir, detection = detectReleaseTooling(dir)) {
+  const removed = []
+
+  for (const rel of detection.files) {
+    const abs = path.join(dir, rel)
+    if (!fs.existsSync(abs)) continue
+    fs.rmSync(abs, { recursive: true, force: true })
+    removed.push(rel)
+    pruneEmptyDirs(dir, path.dirname(abs))
+  }
+
+  const pkg = readPkg(dir)
+  if (pkg && pkg.scripts) {
+    let changed = false
+    if (versionHookReferencesGenerators(pkg)) {
+      delete pkg.scripts.version
+      removed.push('package.json (version hook)')
+      changed = true
+    }
+    for (const [name, cmd] of Object.entries(HELPER_SCRIPTS)) {
+      if (pkg.scripts[name] === cmd) {
+        delete pkg.scripts[name]
+        changed = true
+      }
+    }
+    if (changed) {
+      if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n')
+    }
+  }
+
+  return { removed }
+}
+
+// One-line pointer shown when we detect release tooling but don't remove it
+// (declined, or a non-interactive run).
+function releaseToolingNotice() {
+  return (
+    `Release tooling has moved to ${SKITTERSHIP} — run ` +
+    `npx ${SKITTERSHIP} init to keep it (your config is migrated automatically).`
+  )
+}
+
+module.exports = {
+  detectReleaseTooling,
+  removeReleaseTooling,
+  releaseToolingNotice,
+  RELEASE_PATHS,
+  SKITTERSHIP,
+}

package/src/env/config.js

@@ -18,7 +18,8 @@
  *                 portsPerSpec, envFile, backupCommand },
  *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
- *     linkLinear: true,
+ *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
+ *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed }
  *   }
  */
@@ -41,7 +42,13 @@ const DEFAULT_CONFIG = Object.freeze({
   }),
   open: Object.freeze({ command: '' }),
   registry: '.spec-env/registry.json',
-  linkLinear: true,
+  // Git branch naming, provider-neutral. `pattern` expands {type}/{slug} and,
+  // when a tracker provider is linked, {identifier}; `identifierField` names the
+  // 00-overview.md frontmatter field a provider writes the ticket id into (empty
+  // = no identifier, so patterns referencing {identifier} fall back to type/slug).
+  branch: Object.freeze({ pattern: '{type}/{slug}', identifierField: '' }),
+  // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
+  baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
 })
 
@@ -56,7 +63,8 @@ function defaults() {
     docker: { ...DEFAULT_CONFIG.docker },
     open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
-    linkLinear: DEFAULT_CONFIG.linkLinear,
+    branch: { ...DEFAULT_CONFIG.branch },
+    baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
   }
 }
@@ -104,8 +112,13 @@ function mergeConfig(base, parsed) {
     assign(base.open, parsed.open, 'command', 'string?')
   }
 
+  if (isObject(parsed.branch)) {
+    assign(base.branch, parsed.branch, 'pattern', 'string')
+    assign(base.branch, parsed.branch, 'identifierField', 'string')
+  }
+
   assign(base, parsed, 'registry', 'string')
-  assign(base, parsed, 'linkLinear', 'boolean')
+  assign(base, parsed, 'baseBranch', 'string')
 
   if (isObject(parsed.guards)) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')

package/src/env/integrate.js

@@ -0,0 +1,46 @@
+'use strict'
+
+/**
+ * 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 (unused today; kept for symmetry).
+ * @param {object} ctx   { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath }
+ * @returns {object} { blocked, noop, reason, commands, 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: [], 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.
+  if (!aheadOfBase) {
+    return { ...result, noop: true }
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${spec.worktreePath} rebase ${base}`,
+      `git -C ${mainRepoPath} merge --ff-only ${branch}`,
+    ],
+  }
+}
+
+module.exports = { planIntegrate }

package/src/env/resolve.js

@@ -5,21 +5,18 @@
  *
  * Given a spec argument (a folder name or path) it locates the spec folder under
  * `specs/**`, splits the `feat-`/`bug-` prefix into `{ type, slug }`, derives the
- * git branch (optional Linear seam, else `{type}/{slug}`), and expands the
- * config's path/name tokens (`{repo}`, `{repoSlug}`, `{slug}`). Reads files to
- * locate the spec and read frontmatter, but makes no git/docker side effects —
- * deterministic and safe to unit-test with fixtures.
+ * git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
+ * is filled from a tracker id when one is configured, else it falls back to
+ * `{type}/{slug}`), and expands the config's path/name tokens (`{repo}`,
+ * `{repoSlug}`, `{slug}`). Reads files to locate the spec and read frontmatter,
+ * but makes no git/docker side effects — deterministic and safe to unit-test with
+ * fixtures.
  */
 
 const fs = require('node:fs')
 const path = require('node:path')
 
 const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
-const LINEAR_CONFIG = path.join('specs', '.core', 'linear.config.json')
-
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
 
 // Find the spec folder under specs/<bucket>/<name>. `specArg` may be a bare
 // folder name or a path — only its basename is matched against the buckets.
@@ -59,9 +56,12 @@ function expandTokens(str, tokens) {
   )
 }
 
-// Read the `linear_identifier` from a spec's 00-overview.md YAML frontmatter,
-// if present. Returns null when there's no frontmatter / field / file.
-function readLinearIdentifier(specPath) {
+// Read a named field from a spec's 00-overview.md YAML frontmatter, if present.
+// `field` is provider-neutral (e.g. a tracker's ticket-id field, configured via
+// `branch.identifierField`). Returns null when there's no frontmatter / field /
+// file, or no field name was given.
+function readFrontmatterField(specPath, field) {
+  if (!field) return null
   const overview = path.join(specPath, '00-overview.md')
   let raw
   try {
@@ -71,7 +71,7 @@ function readLinearIdentifier(specPath) {
   }
   const fm = /^---\n([\s\S]*?)\n---/.exec(raw)
   if (!fm) return null
-  const m = /^linear_identifier:\s*(.+)$/m.exec(fm[1])
+  const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(fm[1])
   if (!m) return null
   return m[1].trim().replace(/^["']|["']$/g, '') || null
 }
@@ -99,43 +99,51 @@ function readStackField(specPath, config) {
   return config.docker && config.docker.enabled ? 'docker' : 'worktree'
 }
 
-// Load specs/.core/linear.config.json when present, else null.
-function loadLinearConfig(dir) {
-  const file = path.join(dir, LINEAR_CONFIG)
-  let raw
-  try {
-    raw = fs.readFileSync(file, 'utf-8')
-  } catch {
-    return null
-  }
-  try {
-    const parsed = JSON.parse(raw)
-    return isObject(parsed) ? parsed : null
-  } catch (error) {
-    throw new Error(`Invalid ${LINEAR_CONFIG}: ${error.message}`)
+/**
+ * Derive the git branch for a spec from the provider-neutral `branch.pattern`
+ * (`{type}`, `{slug}`, and optionally `{identifier}`). When the pattern uses
+ * `{identifier}`, the id is read from the frontmatter field named by
+ * `branch.identifierField` (a tracker provider writes it); if that field is unset
+ * or absent on the spec, the branch falls back to `{type}/{slug}` so we never
+ * emit a half-expanded name. No knowledge of any specific tracker lives here.
+ */
+function branchFor(spec, config) {
+  const branch = (config.branch && config.branch.pattern) || '{type}/{slug}'
+  const tokens = { type: spec.type, slug: spec.slug }
+  if (/\{identifier\}/.test(branch)) {
+    const field = config.branch && config.branch.identifierField
+    const identifier = readFrontmatterField(spec.path, field)
+    if (!identifier) return `${spec.type}/${spec.slug}`
+    tokens.identifier = identifier
   }
+  return expandTokens(branch, tokens)
 }
 
 /**
- * Derive the git branch for a spec. If `linkLinear` and a linear.config.json
- * with a `branch.pattern` is present and the spec has a `linear_identifier`,
- * expand that pattern (`{identifier}`, `{slug}`, `{type}`). Otherwise fall back
- * to `{type}/{slug}`.
+ * Resolve the integration base branch (the branch specs fork from and land back
+ * onto). Precedence:
+ *   1. `config.baseBranch` — explicit override
+ *   2. `origin/HEAD` — the remote's default branch
+ *   3. `main` if it exists locally
+ *   4. `master` if it exists locally
+ *   5. `main` — last-resort default
+ *
+ * `git(args)` runs a read-only git command and returns trimmed stdout, or `null`
+ * on a non-zero exit / failure. It's injected so this stays pure and unit-testable
+ * with no live git; the CLI supplies a real reader. (Note: `show-ref --quiet`
+ * emits no stdout on success, so a non-null `''` still means "exists".)
  */
-function branchFor(spec, dir, config) {
-  if (config.linkLinear) {
-    const linear = loadLinearConfig(dir)
-    const pattern = linear && linear.branch && linear.branch.pattern
-    const identifier = readLinearIdentifier(spec.path)
-    if (pattern && identifier) {
-      return expandTokens(pattern, {
-        identifier,
-        slug: spec.slug,
-        type: spec.type,
-      })
-    }
+function resolveBaseBranch(config, git) {
+  const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
+  if (explicit) return explicit
+
+  const originHead = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
+  if (originHead) return originHead.replace(/^origin\//, '')
+
+  for (const name of ['main', 'master']) {
+    if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return name
   }
-  return `${spec.type}/${spec.slug}`
+  return 'main'
 }
 
 /**
@@ -154,7 +162,7 @@ function resolveSpec(specArg, dir, config) {
 
   const stack = readStackField(found.path, config)
   const spec = { folder: found.folder, bucket: found.bucket, path: found.path, type, slug, stack }
-  const branch = branchFor(spec, dir, config)
+  const branch = branchFor(spec, config)
 
   const worktreeRoot = expandTokens(config.worktree.root, tokens)
   const worktreeFolder = expandTokens(config.worktree.folderPattern, tokens)
@@ -175,6 +183,7 @@ function resolveSpec(specArg, dir, config) {
 
 module.exports = {
   resolveSpec,
+  resolveBaseBranch,
   branchFor,
   splitPrefix,
   repoInfo,

package/src/env/teardown.js

@@ -18,10 +18,10 @@
 const { expandTokens } = require('./resolve.js')
 
 /**
- * @param {object} spec  resolved spec: { slug, worktreePath, projectName, ... }
+ * @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 }, timestamp }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged }, timestamp }
  * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
  *                     volumesDropped }
  */
@@ -35,8 +35,16 @@ function planDown(spec, config, flags, ctx) {
     if (config.guards.refuseTeardownIfDirty && worktreeState.dirty) {
       return blocked('worktree has uncommitted changes')
     }
-    if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed) {
-      return blocked('worktree has unpushed commits')
+    // Unpushed commits are only unsafe when they aren't already integrated into
+    // the base branch. A branch merged into base carries nothing to lose even
+    // with no remote — so /spec-complete's local land-then-teardown needs no
+    // --force. Block only when the commits are both unpushed AND unmerged.
+    if (
+      config.guards.refuseTeardownIfUnpushed &&
+      worktreeState.unpushed &&
+      !worktreeState.merged
+    ) {
+      return blocked('worktree has unpushed commits not yet merged into the base branch')
     }
   }
 
@@ -77,6 +85,13 @@ function planDown(spec, config, flags, ctx) {
       : `git worktree remove ${spec.worktreePath}`,
   )
 
+  // --- delete the branch (safe: -d refuses an unmerged branch, never -D) ---
+  // Runs after the worktree remove frees the branch. On a forced teardown of an
+  // unmerged branch this fails loudly; the skill relays it rather than -D-ing.
+  if (spec.branch) {
+    commands.push(`git branch -d ${spec.branch}`)
+  }
+
   return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
 }
 

package/src/env/trust.js

@@ -0,0 +1,87 @@
+'use strict'
+
+/**
+ * Trust a per-spec worktree directory with Claude Code.
+ *
+ * Worktrees live outside the primary checkout (`../{repo}-wt/{slug}`), so Claude
+ * Code treats them as untrusted and prompts on every edit until the operator
+ * grants access. Registering the shared worktree root in
+ * `permissions.additionalDirectories` lifts those prompts for every spec at once.
+ *
+ * The root is an **absolute** path (relative entries aren't reliable in
+ * `additionalDirectories`) and therefore machine-specific, so it belongs in the
+ * gitignored `.claude/settings.local.json` — never committed config. This merge
+ * is deliberately conservative: it preserves every existing key (notably
+ * `permissions.allow`), dedups by exact path, and refuses to clobber a file it
+ * can't parse. `fs` is the only side effect; callers own the reporting.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Absolute path to the machine-local Claude Code settings for `dir`.
+function settingsPath(dir) {
+  return path.join(dir, '.claude', 'settings.local.json')
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
+}
+
+/**
+ * Ensure `rootAbs` is listed in `permissions.additionalDirectories` of `dir`'s
+ * `.claude/settings.local.json`. Idempotent and non-destructive. Returns
+ * `{ changed, reason }` where reason is one of:
+ *   - `created`   — the settings file was absent and was created
+ *   - `added`     — the root was merged into an existing file
+ *   - `present`   — the root was already listed (no write)
+ *   - `malformed` — the file exists but isn't parseable JSON (left untouched)
+ */
+function ensureWorktreeDirTrusted(dir, rootAbs) {
+  const file = settingsPath(dir)
+
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
+      return { changed: true, reason: 'created' }
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return { changed: false, reason: 'malformed' }
+  }
+  if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
+
+  const permissions = isObject(parsed.permissions) ? parsed.permissions : {}
+  const dirs = Array.isArray(permissions.additionalDirectories)
+    ? permissions.additionalDirectories
+    : []
+
+  if (dirs.includes(rootAbs)) return { changed: false, reason: 'present' }
+
+  writeSettings(file, {
+    ...parsed,
+    permissions: {
+      ...permissions,
+      additionalDirectories: [...dirs, rootAbs],
+    },
+  })
+  return { changed: true, reason: 'added' }
+}
+
+module.exports = {
+  ensureWorktreeDirTrusted,
+  settingsPath,
+}