@skitterbyte/skitterspec-linear 1.0.0

package/src/env/config.js

@@ -0,0 +1,165 @@
+'use strict'
+
+/**
+ * Config loader for the per-spec isolation feature (`/spec-env`).
+ *
+ * Reads `specs/.core/env.config.json` from the project root and normalises it
+ * over frozen defaults. The feature is strictly opt-in: when the file is absent
+ * the loader never throws — it returns the defaults with `present:false`, which
+ * every caller treats as "feature unused".
+ *
+ * Mirrors the shape/idiom of `assets/scripts/lib/config.js` (frozen defaults,
+ * merge known keys only, forward-compatible on unknown keys). Zero-dependency.
+ *
+ * Shape (see specs/.core/env.config.md for field docs):
+ *   {
+ *     worktree: { root, folderPattern },
+ *     docker:   { enabled, composeFile, projectNamePattern, portBase,
+ *                 portsPerSpec, envFile, backupCommand },
+ *     open:     { command },   // optional, editor/terminal-agnostic opener
+ *     registry: ".spec-env/registry.json",
+ *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
+ *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
+ *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed }
+ *   }
+ */
+
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+const CONFIG_FILE = join('specs', '.core', 'env.config.json')
+
+const DEFAULT_CONFIG = Object.freeze({
+  worktree: Object.freeze({ root: '../{repo}-wt', folderPattern: '{slug}' }),
+  docker: Object.freeze({
+    enabled: true,
+    composeFile: 'docker-compose.yml',
+    projectNamePattern: '{repoSlug}_{slug}',
+    portBase: 3000,
+    portsPerSpec: 10,
+    envFile: '.env',
+    backupCommand: '',
+  }),
+  open: Object.freeze({ command: '' }),
+  registry: '.spec-env/registry.json',
+  // 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 }),
+})
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// A fresh, deeply-mutable copy of the defaults to merge onto.
+function defaults() {
+  return {
+    worktree: { ...DEFAULT_CONFIG.worktree },
+    docker: { ...DEFAULT_CONFIG.docker },
+    open: { ...DEFAULT_CONFIG.open },
+    registry: DEFAULT_CONFIG.registry,
+    branch: { ...DEFAULT_CONFIG.branch },
+    baseBranch: DEFAULT_CONFIG.baseBranch,
+    guards: { ...DEFAULT_CONFIG.guards },
+  }
+}
+
+// Copy a typed field from parsed[key] onto base[key] when it matches `type`.
+// Strings are trimmed and must be non-empty to override.
+function assign(base, parsed, key, type) {
+  const v = parsed[key]
+  if (type === 'string') {
+    if (typeof v === 'string' && v.trim()) base[key] = v.trim()
+  } else if (type === 'string?') {
+    // string that may be intentionally empty (e.g. backupCommand)
+    if (typeof v === 'string') base[key] = v
+  } else if (type === 'boolean') {
+    if (typeof v === 'boolean') base[key] = v
+  } else if (type === 'number') {
+    if (typeof v === 'number' && Number.isFinite(v)) base[key] = v
+  }
+}
+
+/**
+ * Merge a parsed config over the defaults. Only known keys are copied (unknown
+ * keys ignored for forward-compat). Nested objects are merged field-by-field.
+ */
+function mergeConfig(base, parsed) {
+  if (!isObject(parsed)) return base
+
+  if (isObject(parsed.worktree)) {
+    assign(base.worktree, parsed.worktree, 'root', 'string')
+    assign(base.worktree, parsed.worktree, 'folderPattern', 'string')
+  }
+
+  if (isObject(parsed.docker)) {
+    assign(base.docker, parsed.docker, 'enabled', 'boolean')
+    assign(base.docker, parsed.docker, 'composeFile', 'string')
+    assign(base.docker, parsed.docker, 'projectNamePattern', 'string')
+    assign(base.docker, parsed.docker, 'portBase', 'number')
+    assign(base.docker, parsed.docker, 'portsPerSpec', 'number')
+    assign(base.docker, parsed.docker, 'envFile', 'string')
+    assign(base.docker, parsed.docker, 'backupCommand', 'string?')
+  }
+
+  if (isObject(parsed.open)) {
+    // command may be intentionally empty (no auto-open)
+    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, 'baseBranch', 'string')
+
+  if (isObject(parsed.guards)) {
+    assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
+    assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
+  }
+
+  return base
+}
+
+/**
+ * Load and normalise `specs/.core/env.config.json` from `dir` (default cwd).
+ * Returns `{ config, present }`:
+ *   - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
+ *   - present      → `{ config: merged,   present: true }`
+ * Malformed JSON → throws a clear Error (callers exit non-zero).
+ */
+function loadEnvConfig(dir = process.cwd()) {
+  const base = defaults()
+  const file = join(dir, CONFIG_FILE)
+
+  let raw
+  try {
+    raw = readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { config: base, present: false }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+
+  return { config: mergeConfig(base, parsed), present: true }
+}
+
+module.exports = {
+  loadEnvConfig,
+  mergeConfig,
+  DEFAULT_CONFIG,
+  CONFIG_FILE,
+}

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/provision.js

@@ -0,0 +1,76 @@
+'use strict'
+
+/**
+ * Pure provisioning planner for `spec-env up`.
+ *
+ * Given a resolved spec and its allocated slot, `planUp` returns the exact
+ * side-effecting commands the `/spec-env` skill runs (`git worktree add`,
+ * `docker compose up`), the rendered `.env` contents, and the expanded opener —
+ * but performs no side effects itself. The caller (the CLI) reads/allocates the
+ * registry and passes the slot; this stays deterministic and unit-testable with
+ * no live git/docker.
+ */
+
+const { portOffset } = require('./registry.js')
+const { renderEnvFile, expandOpenCommand } = require('./render.js')
+
+/**
+ * Plan a provisioning run.
+ *
+ * @param {object} spec  resolved spec (from resolveSpec): { slug, type, branch,
+ *                       worktreePath, projectName, ... }
+ * @param {object} alloc { slot, attached } — attached:true when the slot already
+ *                       existed in the registry (re-run → attach, don't clobber).
+ * @param {object} config normalised env config.
+ * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
+ *                     envContents, openCommand, commands, attached }
+ */
+function planUp(spec, alloc, config) {
+  const { slot, attached } = alloc
+
+  // Per-spec escalation: bring Docker up only when this spec's Stack is `docker`,
+  // gated by the project master switch. A spec resolved without an explicit stack
+  // (legacy/tests) follows the master switch — preserving pre-`Stack` behaviour.
+  const stack = spec.stack || (config.docker.enabled ? 'docker' : 'worktree')
+  const wantsDocker = stack === 'docker' && config.docker.enabled
+
+  // Slot, port block and `.env` are Docker-only. A worktree-only spec takes none
+  // of them: no registry slot, no PORT_OFFSET, no `.env`.
+  const offset = wantsDocker ? portOffset(slot, config) : null
+  const envContents = wantsDocker
+    ? renderEnvFile({ projectName: spec.projectName, portOffset: offset })
+    : null
+
+  const openCommand = expandOpenCommand(config.open.command, {
+    worktreePath: spec.worktreePath,
+    slug: spec.slug,
+    branch: spec.branch,
+    projectName: spec.projectName,
+    portOffset: offset === null ? '' : String(offset),
+  })
+
+  const commands = []
+  // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
+  commands.push(
+    attached
+      ? `git worktree add ${spec.worktreePath} ${spec.branch}`
+      : `git worktree add ${spec.worktreePath} -b ${spec.branch}`,
+  )
+  if (wantsDocker) {
+    commands.push(`docker compose --project-name ${spec.projectName} up -d`)
+  }
+
+  return {
+    worktreePath: spec.worktreePath,
+    branch: spec.branch,
+    projectName: spec.projectName,
+    slot: wantsDocker ? slot : null,
+    portOffset: offset,
+    envContents,
+    openCommand,
+    commands,
+    attached,
+  }
+}
+
+module.exports = { planUp }

package/src/env/registry.js

@@ -0,0 +1,95 @@
+'use strict'
+
+/**
+ * Slot registry for per-spec isolation — the single source of truth for which
+ * spec owns which slot index. It lives at the **primary checkout root** (shared
+ * by all worktrees, machine-local, gitignored) at the config-driven `registry`
+ * path (default `.spec-env/registry.json`).
+ *
+ * Slot `n` → a reserved port block: `portOffset = portBase + n * portsPerSpec`.
+ *
+ * The allocation helpers are pure transforms on a registry object so they can be
+ * unit-tested with no filesystem; `readRegistry`/`writeRegistry` are the only IO
+ * and are the seam the CLI drives. No `Date.now()`/`Math.random()` — determinism
+ * matters (callers pass timestamps when needed).
+ */
+
+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 registry file, resolved against the primary checkout root.
+function registryPath(rootDir, config) {
+  return path.resolve(rootDir, config.registry)
+}
+
+// Read the registry from disk. Missing file → an empty registry (never throws
+// on absence). Malformed JSON → a clear Error.
+function readRegistry(rootDir, config) {
+  const file = registryPath(rootDir, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { slots: {} }
+    throw error
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid registry ${config.registry}: ${error.message}`)
+  }
+  return { slots: isObject(parsed.slots) ? { ...parsed.slots } : {} }
+}
+
+// Persist the registry, creating its parent dir as needed.
+function writeRegistry(rootDir, config, registry) {
+  const file = registryPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify({ slots: registry.slots }, null, 2) + '\n')
+}
+
+/**
+ * Allocate the lowest free slot index to `name`. Idempotent: if `name` already
+ * holds a slot, that slot is returned and the registry is unchanged. Returns a
+ * new registry object (does not mutate the input).
+ */
+function allocateSlot(registry, name) {
+  const slots = { ...registry.slots }
+  if (Object.prototype.hasOwnProperty.call(slots, name)) {
+    return { registry: { slots }, slot: slots[name] }
+  }
+  const used = new Set(Object.values(slots))
+  let slot = 0
+  while (used.has(slot)) slot++
+  slots[name] = slot
+  return { registry: { slots }, slot }
+}
+
+/**
+ * Free `name`'s slot. Idempotent: freeing an absent spec is a clean no-op.
+ * Returns a new registry object (does not mutate the input).
+ */
+function freeSlot(registry, name) {
+  const slots = { ...registry.slots }
+  delete slots[name]
+  return { slots }
+}
+
+// Port block base for a slot.
+function portOffset(slot, config) {
+  return config.docker.portBase + slot * config.docker.portsPerSpec
+}
+
+module.exports = {
+  registryPath,
+  readRegistry,
+  writeRegistry,
+  allocateSlot,
+  freeSlot,
+  portOffset,
+}

package/src/env/render.js

@@ -0,0 +1,26 @@
+'use strict'
+
+/**
+ * Pure renderers for per-spec isolation artifacts.
+ *
+ * `renderEnvFile` produces the worktree's `.env` body (the only file the engine
+ * writes). `expandOpenCommand` expands the optional, editor/terminal-agnostic
+ * `open.command` template. No side effects — unit-testable in isolation.
+ */
+
+const { expandTokens } = require('./resolve.js')
+
+// The worktree `.env`: COMPOSE_PROJECT_NAME namespaces the Docker stack and its
+// named volumes; PORT_OFFSET shifts the spec's reserved port block.
+function renderEnvFile({ projectName, portOffset }) {
+  return `COMPOSE_PROJECT_NAME=${projectName}\nPORT_OFFSET=${portOffset}\n`
+}
+
+// Expand the opener template with the provided tokens. An empty/whitespace-only
+// template means "no auto-open" → returns null.
+function expandOpenCommand(template, tokens) {
+  if (typeof template !== 'string' || !template.trim()) return null
+  return expandTokens(template, tokens)
+}
+
+module.exports = { renderEnvFile, expandOpenCommand }

package/src/env/resolve.js

@@ -0,0 +1,202 @@
+'use strict'
+
+/**
+ * Pure spec/branch resolution for per-spec isolation.
+ *
+ * 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 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']
+
+// 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.
+// Searches `dir` first, then any `extraDirs` in order — so a caller (e.g.
+// `spec-env integrate`) can fall back to a worktree checkout for a spec that
+// was authored on its branch and never committed to the primary checkout.
+function findSpecFolder(specArg, dir, extraDirs = []) {
+  const name = path.basename(specArg)
+  for (const root of [dir, ...extraDirs]) {
+    for (const bucket of BUCKETS) {
+      const abs = path.join(root, 'specs', bucket, name)
+      if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+        return { folder: name, bucket, path: abs }
+      }
+    }
+  }
+  return null
+}
+
+// Split a `feat-`/`bug-` prefix. Unknown prefix → type defaults to `feat` and
+// the whole folder name is the slug.
+function splitPrefix(folder) {
+  const m = /^(feat|bug)-(.+)$/.exec(folder)
+  if (m) return { type: m[1], slug: m[2] }
+  return { type: 'feat', slug: folder }
+}
+
+// Repo identity used for token expansion.
+function repoInfo(dir) {
+  const repo = path.basename(dir)
+  const repoSlug = repo
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return { repo, repoSlug }
+}
+
+// Replace {token} occurrences from `tokens`; unknown tokens are left intact.
+function expandTokens(str, tokens) {
+  return String(str).replace(/\{(\w+)\}/g, (m, key) =>
+    Object.prototype.hasOwnProperty.call(tokens, key) ? tokens[key] : m,
+  )
+}
+
+// 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 {
+    raw = fs.readFileSync(overview, 'utf-8')
+  } catch {
+    return null
+  }
+  const fm = /^---\n([\s\S]*?)\n---/.exec(raw)
+  if (!fm) return null
+  const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(fm[1])
+  if (!m) return null
+  return m[1].trim().replace(/^["']|["']$/g, '') || null
+}
+
+/**
+ * Read a spec's `> **Stack:** …` blockquote field from 00-overview.md and map it
+ * to the isolation stack: any value containing `docker` → `'docker'`, otherwise
+ * `'worktree'`. A spec with no field falls back to the project default — which
+ * preserves pre-`Stack` behaviour: with Docker available (`docker.enabled`) a
+ * legacy spec still gets Docker, else it's worktree-only. The planner ANDs this
+ * with the master switch, so an explicit `worktree` always suppresses Docker.
+ */
+function readStackField(specPath, config) {
+  const overview = path.join(specPath, '00-overview.md')
+  let raw
+  try {
+    raw = fs.readFileSync(overview, 'utf-8')
+  } catch {
+    raw = null
+  }
+  const m = raw && /^>\s*\*\*Stack:\*\*\s*(.+)$/m.exec(raw)
+  if (m) {
+    return /docker/i.test(m[1]) ? 'docker' : 'worktree'
+  }
+  return config.docker && config.docker.enabled ? 'docker' : 'worktree'
+}
+
+/**
+ * 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)
+}
+
+/**
+ * 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 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 'main'
+}
+
+/**
+ * Resolve a spec argument to its identity + isolation coordinates.
+ * Throws a clear Error when the spec folder can't be found.
+ *
+ * `opts.searchDirs` adds fallback checkout roots to look under (after `dir`) when
+ * locating the spec folder; identity/coordinate tokens still expand against `dir`
+ * (the primary checkout), so a worktree-only spec resolves to the right base.
+ */
+function resolveSpec(specArg, dir, config, opts = {}) {
+  const found = findSpecFolder(specArg, dir, opts.searchDirs || [])
+  if (!found) {
+    throw new Error(`spec not found under specs/**: ${specArg}`)
+  }
+
+  const { type, slug } = splitPrefix(found.folder)
+  const { repo, repoSlug } = repoInfo(dir)
+  const tokens = { repo, repoSlug, slug }
+
+  const stack = readStackField(found.path, config)
+  const spec = { folder: found.folder, bucket: found.bucket, path: found.path, type, slug, stack }
+  const branch = branchFor(spec, config)
+
+  const worktreeRoot = expandTokens(config.worktree.root, tokens)
+  const worktreeFolder = expandTokens(config.worktree.folderPattern, tokens)
+  const worktreePath = path.resolve(dir, worktreeRoot, worktreeFolder)
+  const projectName = expandTokens(config.docker.projectNamePattern, tokens)
+
+  return {
+    ...spec,
+    repo,
+    repoSlug,
+    branch,
+    worktreeRoot,
+    worktreeFolder,
+    worktreePath,
+    projectName,
+  }
+}
+
+module.exports = {
+  resolveSpec,
+  resolveBaseBranch,
+  branchFor,
+  splitPrefix,
+  repoInfo,
+  expandTokens,
+  findSpecFolder,
+  readStackField,
+}