@skitterbyte/skitterspec 0.1.0 → 1.0.0

package/src/env/config.js

@@ -0,0 +1,152 @@
+'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",
+ *     linkLinear: true,
+ *     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',
+  linkLinear: true,
+  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,
+    linkLinear: DEFAULT_CONFIG.linkLinear,
+    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?')
+  }
+
+  assign(base, parsed, 'registry', 'string')
+  assign(base, parsed, 'linkLinear', 'boolean')
+
+  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/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,184 @@
+'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 (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.
+ */
+
+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.
+function findSpecFolder(specArg, dir) {
+  const name = path.basename(specArg)
+  for (const bucket of BUCKETS) {
+    const abs = path.join(dir, '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 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) {
+  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 = /^linear_identifier:\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'
+}
+
+// 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. 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}`.
+ */
+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,
+      })
+    }
+  }
+  return `${spec.type}/${spec.slug}`
+}
+
+/**
+ * Resolve a spec argument to its identity + isolation coordinates.
+ * Throws a clear Error when the spec folder can't be found.
+ */
+function resolveSpec(specArg, dir, config) {
+  const found = findSpecFolder(specArg, dir)
+  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, dir, 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,
+  branchFor,
+  splitPrefix,
+  repoInfo,
+  expandTokens,
+  findSpecFolder,
+  readStackField,
+}

package/src/env/teardown.js

@@ -0,0 +1,94 @@
+'use strict'
+
+/**
+ * Pure teardown planner for `spec-env down`.
+ *
+ * `planDown` evaluates the dirty/unpushed guards, plans an optional config-driven
+ * pre-drop backup, and returns the exact commands the `/spec-env-down` skill runs
+ * (`docker compose down` [+`--volumes`], `git worktree remove`). It performs no
+ * side effects: the caller (the CLI) queries git for `worktreeState` and supplies
+ * a `timestamp`, keeping this deterministic and unit-testable with no live
+ * git/docker.
+ *
+ * Volumes are the only destructive action — dropped by default (reclaims disk)
+ * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
+ * configured.
+ */
+
+const { expandTokens } = require('./resolve.js')
+
+/**
+ * @param {object} spec  resolved spec: { slug, worktreePath, projectName, ... }
+ * @param {object} config normalised env config.
+ * @param {object} flags { keepVolumes, force }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed }, timestamp }
+ * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
+ *                     volumesDropped }
+ */
+function planDown(spec, config, flags, ctx) {
+  const { worktreeState = {}, timestamp } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const keepVolumes = Boolean(flags && flags.keepVolumes)
+
+  // --- guards (overridable with --force) ---
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && worktreeState.dirty) {
+      return blocked('worktree has uncommitted changes')
+    }
+    if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed) {
+      return blocked('worktree has unpushed commits')
+    }
+  }
+
+  // Docker teardown only applies to a Docker-escalated spec. A worktree-only spec
+  // (Stack: worktree) has no stack/volumes even when the project master switch is
+  // on — tearing it down is just removing the worktree. A spec resolved without an
+  // explicit stack (legacy/tests) follows the master switch (pre-`Stack` behaviour).
+  const stack = spec.stack || (config.docker.enabled ? 'docker' : 'worktree')
+  const wantsDocker = stack === 'docker' && config.docker.enabled
+
+  const commands = []
+  const volumesDropped = !keepVolumes && wantsDocker
+
+  // --- optional pre-drop backup (only when volumes are actually dropped) ---
+  let backupCommand = null
+  let backupPath = null
+  if (volumesDropped && config.docker.backupCommand) {
+    backupPath = `.spec-env/backups/${spec.slug}-${timestamp}.dump`
+    backupCommand = expandTokens(config.docker.backupCommand, {
+      backupPath,
+      slug: spec.slug,
+      projectName: spec.projectName,
+      timestamp: String(timestamp),
+    })
+    commands.push(backupCommand)
+  }
+
+  // --- docker compose down (drop volumes unless kept) ---
+  if (wantsDocker) {
+    const base = `docker compose --project-name ${spec.projectName} down`
+    commands.push(volumesDropped ? `${base} --volumes` : base)
+  }
+
+  // --- remove the worktree (force needed if we bypassed a dirty guard) ---
+  commands.push(
+    force
+      ? `git worktree remove --force ${spec.worktreePath}`
+      : `git worktree remove ${spec.worktreePath}`,
+  )
+
+  return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
+}
+
+function blocked(reason) {
+  return {
+    blocked: true,
+    reason,
+    commands: [],
+    backupCommand: null,
+    backupPath: null,
+    volumesDropped: false,
+  }
+}
+
+module.exports = { planDown }