@skitterbyte/skitterspec 0.1.0

package/assets/scripts/lib/config.js

@@ -0,0 +1,127 @@
+'use strict'
+
+/**
+ * Config loader for the release-artifact generators.
+ *
+ * Reads `skitterspec.config.json` from the repo root and normalises it over
+ * documented defaults. Shipped alongside the generators (copied into the
+ * consumer's `scripts/lib/`) so the consumer's scripts never depend back into
+ * the skitterspec package. Zero-dependency.
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "changelog": { "enabled": true, "file": "CHANGELOG.md" },
+ *     "releases":  { "enabled": true, "file": "RELEASES.md",
+ *                    "productName": "<repo name>", "scopeAreas": {} },
+ *     "versionHook": true
+ *   }
+ */
+
+const { readFileSync } = require('node:fs')
+const { basename, join } = require('node:path')
+
+const SCHEMA_VERSION = 1
+const CONFIG_FILE = 'skitterspec.config.json'
+
+// Static template (productName is derived from the repo dir when blank).
+const DEFAULT_CONFIG = Object.freeze({
+  version: SCHEMA_VERSION,
+  changelog: Object.freeze({ enabled: true, file: 'CHANGELOG.md' }),
+  releases: Object.freeze({
+    enabled: true,
+    file: 'RELEASES.md',
+    productName: '',
+    scopeAreas: Object.freeze({}),
+  }),
+  versionHook: true,
+})
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function defaultsFor(dir) {
+  return {
+    version: SCHEMA_VERSION,
+    changelog: { enabled: true, file: 'CHANGELOG.md' },
+    releases: {
+      enabled: true,
+      file: 'RELEASES.md',
+      productName: basename(dir),
+      scopeAreas: {},
+    },
+    versionHook: true,
+  }
+}
+
+/**
+ * Merge a parsed config over the defaults. Only known keys are copied (unknown
+ * keys are ignored for forward-compat); `scopeAreas` is replaced wholesale, not
+ * deep-merged, since it's a complete map.
+ */
+function mergeConfig(base, parsed) {
+  if (!isObject(parsed)) return base
+
+  if (typeof parsed.version === 'number') base.version = parsed.version
+  if (typeof parsed.versionHook === 'boolean') base.versionHook = parsed.versionHook
+
+  if (isObject(parsed.changelog)) {
+    if (typeof parsed.changelog.enabled === 'boolean') {
+      base.changelog.enabled = parsed.changelog.enabled
+    }
+    if (typeof parsed.changelog.file === 'string' && parsed.changelog.file.trim()) {
+      base.changelog.file = parsed.changelog.file.trim()
+    }
+  }
+
+  if (isObject(parsed.releases)) {
+    if (typeof parsed.releases.enabled === 'boolean') {
+      base.releases.enabled = parsed.releases.enabled
+    }
+    if (typeof parsed.releases.file === 'string' && parsed.releases.file.trim()) {
+      base.releases.file = parsed.releases.file.trim()
+    }
+    if (typeof parsed.releases.productName === 'string' && parsed.releases.productName.trim()) {
+      base.releases.productName = parsed.releases.productName.trim()
+    }
+    if (isObject(parsed.releases.scopeAreas)) {
+      base.releases.scopeAreas = { ...parsed.releases.scopeAreas }
+    }
+  }
+
+  return base
+}
+
+/**
+ * Load and normalise config from `dir` (default cwd). Missing file → all
+ * defaults. Malformed JSON → throws a clear Error (callers exit non-zero).
+ */
+function loadConfig(dir = process.cwd()) {
+  const base = defaultsFor(dir)
+  const file = join(dir, CONFIG_FILE)
+
+  let raw
+  try {
+    raw = readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return base
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+
+  return mergeConfig(base, parsed)
+}
+
+module.exports = {
+  loadConfig,
+  DEFAULT_CONFIG,
+  SCHEMA_VERSION,
+  CONFIG_FILE,
+}

package/assets/scripts/lib/git-commits.js

@@ -0,0 +1,265 @@
+'use strict'
+
+/**
+ * Shared git-history plumbing for the release artifact generators.
+ *
+ * Both `generate-changelog.js` (dev-facing CHANGELOG, from commit subjects) and
+ * `generate-releases.js` (user-facing RELEASES, from `Release-Note:` footers)
+ * walk the same tag ranges and parse the same conventional-commit format. This
+ * module is the single source of that logic so the two generators cannot drift.
+ *
+ * Commit serialisation: git log emits `hash\0subject\0body\0` per commit (NUL
+ * delimiters so multi-line bodies survive). `reconstructCommits` regroups the
+ * flat NUL-split array back into per-commit `hash\0subject\0body` strings.
+ *
+ * A parsed commit is a plain object:
+ *   { type, scope?, message, body?, hash, breaking }
+ */
+
+const { execSync } = require('node:child_process')
+
+function getCommitsSinceLastTag(currentVersion) {
+  try {
+    // Fetch tags to ensure they're available (important in CI)
+    try {
+      execSync('git fetch --tags --force', { encoding: 'utf-8', stdio: 'pipe' })
+    } catch {
+      // If fetch fails, continue - tags might already be available
+    }
+
+    // Get all tags sorted by version (newest first)
+    const allTags = execSync('git tag --sort=-version:refname', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    })
+      .trim()
+      .split('\n')
+      .filter((tag) => tag.trim().length > 0)
+
+    // Determine the previous tag to compare against
+    let previousTag = null
+    let currentTag = null
+
+    if (allTags.length === 0) {
+      // No tags exist, get all commits
+      const output = execSync('git log --pretty=format:"%h%x00%s%x00%b%x00" --no-merges', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      }).trim()
+
+      return reconstructCommits(output)
+    }
+
+    // Check if HEAD is at a tag
+    try {
+      currentTag = execSync('git describe --tags --exact-match HEAD', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      }).trim()
+    } catch {
+      // HEAD is not at a tag - try to get current branch/tag from environment
+      // In CI, Build.SourceBranchName might be available
+      const sourceBranch = process.env.BUILD_SOURCEBRANCHNAME || process.env.BUILD_SOURCEBRANCH
+      if (sourceBranch && sourceBranch.startsWith('v')) {
+        currentTag = sourceBranch
+      } else if (currentVersion) {
+        // Use the version parameter as fallback (e.g., "8.0.0" -> "v8.0.0")
+        const versionTag = `v${currentVersion}`
+        if (allTags.includes(versionTag)) {
+          currentTag = versionTag
+        }
+      }
+    }
+
+    if (currentTag && allTags.includes(currentTag)) {
+      // HEAD is at a tag - find the previous tag
+      const currentIndex = allTags.indexOf(currentTag)
+      if (currentIndex > 0) {
+        // There is a previous tag
+        previousTag = allTags[currentIndex - 1]
+      } else {
+        // This is the first tag, get all commits
+        const output = execSync('git log --pretty=format:"%h%x00%s%x00%b%x00" --no-merges', {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        }).trim()
+
+        return reconstructCommits(output)
+      }
+    } else {
+      // HEAD is not at a tag, use the most recent tag
+      previousTag = allTags[0]
+    }
+
+    if (!previousTag) {
+      // No previous tag found, get all commits
+      const output = execSync('git log --pretty=format:"%h%x00%s%x00%b%x00" --no-merges', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      }).trim()
+
+      return reconstructCommits(output)
+    }
+
+    // When HEAD is at a tag, use the tag explicitly instead of HEAD
+    // This ensures we get commits up to and including the tag commit
+    const rangeEnd = currentTag || 'HEAD'
+
+    // Get commits since previous tag (inclusive of rangeEnd)
+    // Use null character as delimiter to handle multi-line bodies
+    // Format: hash\0subject\0body\0hash2\0subject2\0body2\0...
+    // NOTE: do NOT pass --all here — it traverses every ref (branches,
+    // remotes, tags) and leaks commits from unmerged branches into the
+    // range. Shallow-clone fallback below uses git fetch --unshallow.
+    const output = execSync(
+      `git log ${previousTag}..${rangeEnd} --pretty=format:"%h%x00%s%x00%b%x00" --no-merges`,
+      { encoding: 'utf-8', stdio: 'pipe' },
+    ).trim()
+
+    const commits = reconstructCommits(output)
+
+    // If no commits found and we're in CI, try unshallow the repo
+    if (commits.length === 0) {
+      try {
+        execSync('git fetch --unshallow', { encoding: 'utf-8', stdio: 'pipe' })
+        // Try again after unshallow
+        const retryOutput = execSync(
+          `git log ${previousTag}..${rangeEnd} --pretty=format:"%h%x00%s%x00%b%x00" --no-merges`,
+          { encoding: 'utf-8', stdio: 'pipe' },
+        ).trim()
+        return reconstructCommits(retryOutput)
+      } catch {
+        // Unshallow failed or not a shallow clone, return empty
+      }
+    }
+
+    return commits
+  } catch (error) {
+    // If git commands fail, try to get all commits as fallback
+    try {
+      const output = execSync('git log --pretty=format:"%h%x00%s%x00%b%x00" --no-merges', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      }).trim()
+
+      return reconstructCommits(output)
+    } catch {
+      console.error('Failed to get git commits:', error)
+      return []
+    }
+  }
+}
+
+function reconstructCommits(output) {
+  if (!output.trim()) {
+    return []
+  }
+
+  // Split by null character - DO NOT filter empty parts yet
+  // Empty bodies are valid and needed to maintain correct grouping
+  const parts = output.split('\0')
+
+  const commits = []
+
+  // Group parts into commits: each commit has hash, subject, body
+  // Parts array: [hash1, subject1, body1, hash2, subject2, body2, ...]
+  // Trailing empty string from final \0 is expected and ignored
+  for (let i = 0; i < parts.length - 1; i += 3) {
+    const hash = parts[i] || ''
+    const subject = parts[i + 1] || ''
+    const body = parts[i + 2] || ''
+
+    // Only add commit if we have hash and subject (body can be empty)
+    if (hash.trim() && subject.trim()) {
+      // Reconstruct commit string with null delimiters
+      commits.push(`${hash}\0${subject}\0${body}`)
+    }
+  }
+
+  return commits
+}
+
+function parseCommit(commitLine) {
+  // Split by null character (used as delimiter in git log format)
+  const parts = commitLine.split('\0')
+
+  // Need at least hash and subject (body is optional)
+  if (parts.length < 2) {
+    return null // Invalid format, skip
+  }
+
+  const hash = parts[0].trim()
+  const subject = parts[1].trim()
+  const body = (parts[2] && parts[2].trim()) || undefined
+
+  // Parse conventional commit format: type(scope)!: description
+  // The optional `!` marks a breaking change per the Conventional Commits spec.
+  const conventionalCommitRegex = /^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/
+  const match = subject.match(conventionalCommitRegex)
+
+  if (!match) {
+    return null // Skip non-conventional commits
+  }
+
+  const [, type, scope, bang, message] = match
+
+  // Breaking change markers:
+  //   1. `!` suffix on type/scope (e.g. `feat!:` or `feat(api)!:`)
+  //   2. A `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer in the body
+  const breakingFooterRegex = /(^|\n)BREAKING[- ]CHANGE:/i
+  const breaking = Boolean(bang) || (body ? breakingFooterRegex.test(body) : false)
+
+  return {
+    type: type.toLowerCase(),
+    scope: scope || undefined,
+    message: message.trim(),
+    body: body,
+    hash: hash.trim(),
+    breaking,
+  }
+}
+
+function getAllVersionTags() {
+  try {
+    execSync('git fetch --tags --force', { encoding: 'utf-8', stdio: 'pipe' })
+  } catch {
+    // fetch is best-effort
+  }
+
+  return execSync('git tag --sort=-version:refname', { encoding: 'utf-8', stdio: 'pipe' })
+    .trim()
+    .split('\n')
+    .map((t) => t.trim())
+    .filter((t) => /^v?\d+\.\d+\.\d+/.test(t))
+}
+
+function getCommitsBetween(fromTag, toTag) {
+  const range = fromTag ? `${fromTag}..${toTag}` : toTag
+  const output = execSync(`git log ${range} --pretty=format:"%h%x00%s%x00%b%x00" --no-merges`, {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  }).trim()
+  return reconstructCommits(output)
+}
+
+function getTagDate(tag) {
+  try {
+    return execSync(`git log -1 --format=%cs ${tag}`, { encoding: 'utf-8', stdio: 'pipe' }).trim()
+  } catch {
+    return new Date().toISOString().split('T')[0]
+  }
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+module.exports = {
+  getCommitsSinceLastTag,
+  reconstructCommits,
+  parseCommit,
+  getAllVersionTags,
+  getCommitsBetween,
+  getTagDate,
+  escapeRegex,
+}

package/assets/skills/commit/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: commit
+description: Stage and commit the current change with a concise conventional-commit message. Stages only files related to the task, runs typecheck and the relevant tests first, and appends a Release-Note: footer when the change is user-visible (grammar in .claude/rules/commit-messages.md). Use when the user says "/commit", "commit this", or wants their working changes committed.
+---
+
+# /commit — stage and commit the current change
+
+A disciplined commit: stage only what belongs to the task, prove it's green,
+then write a conventional-commit message — with a `Release-Note:` footer when an
+end user would notice the change. Message grammar and length limits live in
+`.claude/rules/commit-messages.md`.
+
+1. Run `git status` and `git diff --staged`.
+2. Stage ONLY files related to the current task (ignore unrelated UI/config
+   drift).
+3. Run typecheck and the relevant tests.
+4. Write a concise conventional commit message scoped to the change.
+5. **Decide if the change is user-visible.** If an end user would notice it
+   (feature, fix, improvement), append a `Release-Note:` footer in plain user
+   language — what they can now do, not the implementation. Use `Release-Note!:`
+   for a release headline, and `Release-Area:` to override the area when the
+   scope isn't a user area. Omit the footer for internal/dev-only changes
+   (`chore`, `test`, `docs`, refactors with no user effect). Put a blank line
+   before the footer. See `.claude/rules/commit-messages.md` → "Release notes
+   footer" for the grammar. When the release tooling is installed, these footers
+   are what the generated release notes are built from at `npm version` — so the
+   note is the user-facing record of the change, not just metadata.
+6. Do NOT ask about unrelated uncommitted files.

package/assets/skills/spec/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: spec
+description: Create a new spec-driven-development spec. Grills the user to a clear, shared understanding of the requirement AND the proposed solution FIRST, then writes one concise, phased, test-included, change-logged spec into specs/backlog/. Use when the user wants to plan a feature, write a spec, capture a requirement, or says "/spec" or "spec this out".
+---
+
+# /spec — author a new spec
+
+Produce ONE concise spec in `specs/backlog/`. Do not start coding — this skill
+plans only. Implementation happens later via `/spec-go`.
+
+Lifecycle (the governing skills) — status in parentheses:
+`/spec` (Draft, backlog) → `/spec-ready` (Ready, still backlog) → `/spec-go`
+(In Progress, in-progress; implement phase 1) → `/spec-complete` (Complete) /
+`/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`.
+
+## Phase A — reach a clear shared understanding (grill first)
+
+Interview the user until requirement AND proposed solution are unambiguous. Do
+not write the spec until this is resolved.
+
+- Break the problem into **distinctive areas** and work them in logical order,
+  resolving dependencies between decisions one at a time.
+- Ask **one question at a time**. For each, give your **recommended answer**.
+- If a question can be answered by **reading the codebase, read it** instead of
+  asking. Verify endpoints/models/files actually exist before relying on them.
+- Cover, at minimum, the areas that apply:
+  1. **Problem & why** — what's broken/missing, who feels it, why now.
+  2. **Scope & non-goals** — explicit out-of-scope items.
+  3. **Affected areas** — concrete files/modules/packages this touches.
+  4. **Proposed solution shape** — the chosen approach and the alternatives
+     rejected, with the reason (this becomes "Decisions").
+  5. **Data / API impact** — schema/model changes, new endpoints, and
+     **backward compatibility** (additive = safe; breaking = needs explicit
+     permission and coordination).
+  6. **Security & multi-tenancy** — authz, tenant scoping, untrusted input.
+  7. **Edge cases & failure modes.**
+  8. **Testing approach** — what proves each phase correct.
+  9. **Open questions** — anything still undecided.
+
+Stop grilling when there are no unresolved branches that would change the spec.
+Briefly play back the agreed understanding before writing.
+
+## Phase B — write the spec
+
+This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
+
+- **Every spec is a folder** — never a bare file, even for a one-line change:
+  `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
+- The entry point is **always `00-overview.md`** — the index/dashboard for the
+  spec. It holds the header block, Problem, Decisions, Solution overview, the
+  **phase index** (a table linking to each phase file), Open questions, State
+  log, and Changelog. It does **not** hold the per-phase task lists.
+- **Each phase is its own file** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, …
+  numbered in execution order; the slug is a short kebab description of the phase
+  goal (e.g. `01-data-model.md`, `02-api-endpoints.md`). The phase file holds
+  that phase's goal, its task checkboxes (tests included), and any phase-specific
+  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
+  into `00-overview.md`. This keeps each phase easy to dive into on its own.
+- Choose a short kebab-case name and **prefix it `feat-`** (the bug counterpart
+  uses `bug-`).
+
+Use this template (keep it **as concise as possible** — no filler, no restating
+the codebase, link rather than duplicate):
+
+```markdown
+# <Feature title>
+
+> **Type:** Feature
+> **Status:** Draft — not started
+> **Author:** <git user.name — `git config user.name`>
+> **Developer:** —
+> **Raised:** <YYYY-MM-DD (today)>
+> **Area:** <comma-separated files/modules this touches>
+
+## Problem
+
+<2–6 sentences: what's wrong/missing and why it matters. No fluff.>
+
+## Decisions
+
+<Numbered, confirmed decisions from Phase A. Each: the choice + one-line why,
+and the rejected alternative when it sharpens the choice. This is the heart of
+the spec — be specific.>
+
+## Solution overview
+
+<Short prose or bullets describing the chosen shape end-to-end. Optional small
+schema/grammar/output snippets where they remove ambiguity.>
+
+## Phases
+
+Each phase lives in its own file in this folder. Status: ⬜ not started ·
+🔄 in progress · ✅ done.
+
+| # | Phase | Status | File |
+|---|-------|--------|------|
+| 1 | <goal> | ⬜ | [01-<phase-slug>.md](01-<phase-slug>.md) |
+| 2 | <goal> | ⬜ | [02-<phase-slug>.md](02-<phase-slug>.md) |
+
+## Open questions
+
+- [ ] <anything deferred — or "None">
+
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| <YYYY-MM-DD> | Draft | backlog | <author> |
+
+## Changelog
+
+- <YYYY-MM-DD> — Spec created.
+```
+
+Then create **one file per phase** (`01-<phase-slug>.md`, `02-…`, in execution
+order). Each phase file uses this template:
+
+```markdown
+# Phase 1 — <goal> ⬜
+
+> Spec: [00-overview.md](00-overview.md) · **Status:** Not started
+
+**Goal:** <one line — what this phase delivers and how it's proven>.
+
+## Tasks
+
+- [ ] <clear, verb-first task>
+- [ ] <clear, verb-first task>
+- [ ] Add/extend tests covering this phase; run the project's typecheck and
+      test commands (see `.claude/rules/spec-planning.md`) — green before the
+      phase is done.
+
+## Notes
+
+<Phase-specific decisions, gotchas, or context. Delete if empty.>
+```
+
+Keep the `00-overview.md` phase index and the phase files in sync: the index row
+is the one-line summary + status; the phase file is the detail.
+
+The **State log** is the audit trail of folder/status transitions — every
+lifecycle skill (`/spec-ready`, `/spec-go`, `/spec-complete`, `/spec-cancel`)
+appends one row when it moves the spec. The **Changelog** is for decisions and
+course-corrections only — keep the two separate.
+
+Rules for the spec body:
+
+- **Every phase is independently shippable and ends with tests.** A phase is
+  not "done" until its tests are written and the suite is green. Bake a test
+  task into each phase — never a separate "testing phase" at the end only.
+- **Tasks are checkboxes** (`- [ ]`), clear, verb-first, and granular enough to
+  finish in one session. They live in the **phase files**, not the overview. Use
+  `⬜`/`🔄`/`✅` on each phase-file heading and mirror it in the `00-overview.md`
+  phase index.
+- **Honour project conventions** when writing tasks — reference the relevant
+  `.claude/rules/*.md` rather than re-explaining them.
+- **Changelog** is mandatory and lives in the spec. Every later decision or
+  course-correction gets a dated one-line entry. Convert relative dates to
+  absolute.
+- Keep it tight. If a section adds no information, delete it.
+
+## Phase C — index the spec
+
+Prepend a row to `specs/backlog/00-index.md` (newest first — directly under the table
+header row, above existing rows):
+
+```
+| <YYYY-MM-DD> | <feat-name> | Feature | Draft |
+```
+
+This is the live view of the backlog; `/spec-go` / `/spec-cancel` remove the row
+when the spec leaves. Create `00-index.md` from a header if it's somehow missing
+(`/spec-init` normally ensures it).
+
+After writing, tell the user the path and that it's a `Draft` in `backlog`. Next
+step is `/spec-ready` once it's groomed, then `/spec-go` to start building.