@skitterbyte/skitterspec 1.0.0 → 2.0.0

package/src/sync/base.js

@@ -1,83 +0,0 @@
-'use strict'
-
-/**
- * The committed base sidecar + the backup-before-force reflog.
- *
- * The base is the last-synced snapshot per spec, stored at
- * `{sync.baseDir}/{identifier}.base.json` and committed so each worktree carries
- * its own base and the three-way divergence check stays accurate. After any
- * successful pull/push/force the engine rewrites it (`writeBase`).
- *
- * `backup(side, …)` lands the about-to-be-clobbered side under `{sync.backupDir}`
- * BEFORE a `--force` overwrites it — force never destroys without first writing a
- * copy. The filename carries a caller-supplied timestamp (the engine takes no
- * Date.now(), for reproducible tests) and is made collision-safe with a counter.
- */
-
-const fs = require('node:fs')
-const path = require('node:path')
-
-function baseFile(dir, identifier, config) {
-  return path.join(dir, config.sync.baseDir, `${identifier}.base.json`)
-}
-
-/**
- * Read a spec's committed base. Returns the parsed object, or `null` when no base
- * exists yet (never synced) — the compare treats null as "no prior state".
- */
-function readBase(dir, identifier, config) {
-  const file = baseFile(dir, identifier, config)
-  let raw
-  try {
-    raw = fs.readFileSync(file, 'utf-8')
-  } catch (error) {
-    if (error.code === 'ENOENT') return null
-    throw error
-  }
-  try {
-    return JSON.parse(raw)
-  } catch (error) {
-    throw new Error(`Invalid base ${path.relative(dir, file)}: ${error.message}`)
-  }
-}
-
-/**
- * Rewrite a spec's committed base with the freshly-synced field set. Creates
- * `{sync.baseDir}` if needed. Returns the absolute path written.
- */
-function writeBase(dir, identifier, config, data) {
-  const file = baseFile(dir, identifier, config)
-  fs.mkdirSync(path.dirname(file), { recursive: true })
-  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
-  return file
-}
-
-/**
- * Back up the about-to-be-clobbered `side` ('local' | 'remote') into
- * `{sync.backupDir}` before a --force. `timestamp` is caller-supplied (the engine
- * never reads the clock); the name is made collision-safe with a `-N` counter.
- * Returns the absolute path written, or null when `data` is nullish (nothing to
- * back up — e.g. forcing a pull with no prior remote).
- */
-function backup(side, dir, identifier, config, { timestamp, data }) {
-  if (data == null) return null
-  const backupRoot = path.join(dir, config.sync.backupDir)
-  fs.mkdirSync(backupRoot, { recursive: true })
-
-  const stem = `${identifier}.${side}.${timestamp}`
-  let file = path.join(backupRoot, `${stem}.json`)
-  let n = 1
-  while (fs.existsSync(file)) {
-    file = path.join(backupRoot, `${stem}-${n}.json`)
-    n += 1
-  }
-  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
-  return file
-}
-
-module.exports = {
-  readBase,
-  writeBase,
-  backup,
-  baseFile,
-}

package/src/sync/compare.js

@@ -1,99 +0,0 @@
-'use strict'
-
-/**
- * The three-way compare at the heart of the hybrid sync.
- *
- * `classify(local, remote, base, config)` compares each configured field across
- * the local snapshot, the remote (Linear) projection, and the committed base
- * (the last-synced state). Per field it returns a raw three-way `status`
- * (unchanged / local-only / remote-only / conflict), then collapses it through
- * the field's ownership (`both|pull|push`) into effective `pushable` / `pullable`
- * flags. Ownership is what makes most "both sides differ" cases *not* a real
- * conflict:
- *   - a `pull` field never pushes (Linear wins) → conflict collapses to remote-only
- *   - a `push` field never pulls (repo wins)    → conflict collapses to local-only
- *   - only a `both` field where both sides moved off base is a true `conflict`.
- *
- * Pure and deterministic: field identity is a stable content hash (sorted-key
- * JSON → SHA-1), so `null`, `undefined`, and a missing base all compare equal,
- * and object key order never causes a false diff. No Date.now()/Math.random().
- */
-
-const { createHash } = require('node:crypto')
-
-// Deterministic JSON: object keys sorted recursively; array order preserved
-// (order is meaningful for milestones/tasks). undefined normalises to null.
-function stableStringify(value) {
-  if (value === undefined || value === null) return 'null'
-  if (Array.isArray(value)) {
-    return '[' + value.map(stableStringify).join(',') + ']'
-  }
-  if (typeof value === 'object') {
-    const keys = Object.keys(value).sort()
-    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}'
-  }
-  return JSON.stringify(value)
-}
-
-// Stable content hash of a single field value.
-function hashField(value) {
-  return createHash('sha1').update(stableStringify(value)).digest('hex')
-}
-
-// Raw three-way status from the three hashes.
-function rawStatus(localH, remoteH, baseH) {
-  const localChanged = localH !== baseH
-  const remoteChanged = remoteH !== baseH
-  if (!localChanged && !remoteChanged) return 'unchanged'
-  if (localChanged && !remoteChanged) return 'local-only'
-  if (!localChanged && remoteChanged) return 'remote-only'
-  // both moved off base — but they may have converged on the same value.
-  if (localH === remoteH) return 'unchanged'
-  return 'conflict'
-}
-
-// Collapse the raw status through ownership into an effective status + flags.
-function collapse(raw, ownership) {
-  const canPush = ownership === 'both' || ownership === 'push'
-  const canPull = ownership === 'both' || ownership === 'pull'
-
-  if (raw === 'unchanged') return { status: 'unchanged', pushable: false, pullable: false }
-  if (raw === 'local-only') return { status: 'local-only', pushable: canPush, pullable: false }
-  if (raw === 'remote-only') return { status: 'remote-only', pushable: false, pullable: canPull }
-
-  // conflict: both sides diverged off base.
-  if (ownership === 'push') return { status: 'local-only', pushable: true, pullable: false }
-  if (ownership === 'pull') return { status: 'remote-only', pushable: false, pullable: true }
-  return { status: 'conflict', pushable: true, pullable: true }
-}
-
-/**
- * Classify every field in `config.sync.fieldOwnership`.
- *
- * @param {object} local  normalized local snapshot (normalizeLocal output)
- * @param {object} remote normalized remote projection (normalizeRemote output)
- * @param {object|null} base the committed base (same shape) or null (never synced)
- * @returns {Array<{field, ownership, raw, status, pushable, pullable}>}
- *   one entry per configured field, in config order.
- */
-function classify(local, remote, base, config) {
-  const ownership = config.sync.fieldOwnership
-  const baseObj = base || {}
-  return Object.keys(ownership).map((field) => {
-    const own = ownership[field]
-    const localH = hashField(local ? local[field] : null)
-    const remoteH = hashField(remote ? remote[field] : null)
-    const baseH = hashField(field in baseObj ? baseObj[field] : null)
-    const raw = rawStatus(localH, remoteH, baseH)
-    const { status, pushable, pullable } = collapse(raw, own)
-    return { field, ownership: own, raw, status, pushable, pullable }
-  })
-}
-
-module.exports = {
-  classify,
-  hashField,
-  stableStringify,
-  rawStatus,
-  collapse,
-}

package/src/sync/config.js

@@ -1,198 +0,0 @@
-'use strict'
-
-/**
- * Config loader for the Linear hybrid-sync feature (`/spec-status`, `/spec-pull`,
- * `/spec-push` and the Linear-aware paths of `/spec` and `/spec-go`).
- *
- * Reads `specs/.core/linear.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 "Linear sync unused".
- *
- * Mirrors the shape/idiom of `src/env/config.js` (frozen defaults, merge known
- * keys only, forward-compatible on unknown keys). Zero-dependency. The one place
- * it is stricter: a `sync.fieldOwnership` value outside `both|pull|push` is a
- * hard error — the engine's whole safety model rests on those enums.
- *
- * Shape (see assets/core/linear.config.md for field docs):
- *   {
- *     linear:   { teamKey, teamId, initiativeId },
- *     mapping:  { specFolder, phases, tasks },
- *     states:   { backlog, "in-progress", complete, cancelled },
- *     snapshot: { overviewFile },
- *     branch:   { pattern },
- *     sync: {
- *       baseDir, backupDir,
- *       fieldOwnership: { <field>: "both" | "pull" | "push" },
- *       localOnlySections: string[]
- *     }
- *   }
- */
-
-const { readFileSync } = require('node:fs')
-const { join } = require('node:path')
-
-const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
-
-const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
-
-const DEFAULT_CONFIG = Object.freeze({
-  linear: Object.freeze({ teamKey: '', teamId: '', initiativeId: '' }),
-  mapping: Object.freeze({ specFolder: 'project', phases: 'milestone', tasks: 'issue' }),
-  states: Object.freeze({
-    backlog: 'Backlog',
-    'in-progress': 'In Progress',
-    complete: 'Done',
-    cancelled: 'Cancelled',
-  }),
-  snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
-  branch: Object.freeze({ pattern: '{type}/{slug}' }),
-  sync: Object.freeze({
-    baseDir: 'specs/.core/linear-base',
-    backupDir: 'specs/.core/linear-backups',
-    fieldOwnership: Object.freeze({
-      description: 'both',
-      milestones: 'both',
-      phaseBodies: 'both',
-      acceptanceCriteria: 'both',
-      taskBreakdown: 'both',
-      workflowState: 'pull',
-      priority: 'pull',
-      labels: 'pull',
-    }),
-    localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
-  }),
-})
-
-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 {
-    linear: { ...DEFAULT_CONFIG.linear },
-    mapping: { ...DEFAULT_CONFIG.mapping },
-    states: { ...DEFAULT_CONFIG.states },
-    snapshot: { ...DEFAULT_CONFIG.snapshot },
-    branch: { ...DEFAULT_CONFIG.branch },
-    sync: {
-      baseDir: DEFAULT_CONFIG.sync.baseDir,
-      backupDir: DEFAULT_CONFIG.sync.backupDir,
-      fieldOwnership: { ...DEFAULT_CONFIG.sync.fieldOwnership },
-      localOnlySections: [...DEFAULT_CONFIG.sync.localOnlySections],
-    },
-  }
-}
-
-// Copy a typed field from parsed[key] onto base[key] when it matches `type`.
-// Strings are trimmed and must be non-empty to override; `string?` may be empty.
-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?') {
-    if (typeof v === 'string') base[key] = v
-  } else if (type === 'boolean') {
-    if (typeof v === 'boolean') base[key] = v
-  }
-}
-
-// Merge (and validate) sync.fieldOwnership. Any key the caller lists joins the
-// compared field set; the value MUST be one of both|pull|push.
-function mergeFieldOwnership(base, parsed) {
-  if (!isObject(parsed)) return
-  for (const [field, dir] of Object.entries(parsed)) {
-    if (!OWNERSHIP.includes(dir)) {
-      throw new Error(
-        `Invalid ${CONFIG_FILE}: sync.fieldOwnership.${field} = ${JSON.stringify(dir)} ` +
-          `(expected one of ${OWNERSHIP.join('|')})`,
-      )
-    }
-    base[field] = dir
-  }
-}
-
-/**
- * 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.linear)) {
-    assign(base.linear, parsed.linear, 'teamKey', 'string?')
-    assign(base.linear, parsed.linear, 'teamId', 'string?')
-    assign(base.linear, parsed.linear, 'initiativeId', 'string?')
-  }
-
-  if (isObject(parsed.mapping)) {
-    assign(base.mapping, parsed.mapping, 'specFolder', 'string')
-    assign(base.mapping, parsed.mapping, 'phases', 'string')
-    assign(base.mapping, parsed.mapping, 'tasks', 'string')
-  }
-
-  if (isObject(parsed.states)) {
-    for (const key of Object.keys(base.states)) {
-      assign(base.states, parsed.states, key, 'string')
-    }
-  }
-
-  if (isObject(parsed.snapshot)) {
-    assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
-  }
-
-  if (isObject(parsed.branch)) {
-    assign(base.branch, parsed.branch, 'pattern', 'string')
-  }
-
-  if (isObject(parsed.sync)) {
-    assign(base.sync, parsed.sync, 'baseDir', 'string')
-    assign(base.sync, parsed.sync, 'backupDir', 'string')
-    mergeFieldOwnership(base.sync.fieldOwnership, parsed.sync.fieldOwnership)
-    if (Array.isArray(parsed.sync.localOnlySections)) {
-      base.sync.localOnlySections = parsed.sync.localOnlySections
-        .filter((s) => typeof s === 'string' && s.trim())
-        .map((s) => s.trim())
-    }
-  }
-
-  return base
-}
-
-/**
- * Load and normalise `specs/.core/linear.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 or a bad `fieldOwnership` enum → throws a clear Error.
- */
-function loadLinearConfig(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 = {
-  loadLinearConfig,
-  mergeConfig,
-  DEFAULT_CONFIG,
-  CONFIG_FILE,
-  OWNERSHIP,
-}

package/src/sync/mcp.js

@@ -1,112 +0,0 @@
-'use strict'
-
-/**
- * The Linear MCP boundary — the one place that knows concrete Linear tool names.
- *
- * `discoverLinear(tools)` resolves the operations the sync needs (read/update a
- * Project, list/create/update Milestones + Issues) against the *connected*
- * server's advertised tool list at runtime, rather than hardcoding names that
- * drift. If Linear isn't connected (empty / zero-match tool list) it returns a
- * clean `{ ok:false, error }` so the caller can stop and do nothing destructive.
- *
- * `makeAdapter(callTool, resolved)` wraps a generic `callTool(name, args)` (the
- * skill's MCP invoker) into the typed async operations push/pull consume. Tests
- * inject a fake adapter directly (an in-memory Project), so the engine stays
- * offline and deterministic; production wires `callTool` to the real MCP server.
- */
-
-// Canonical operations, and the regexes that match a Linear MCP tool name to
-// each. Ordered patterns: first match wins. Verified against the connected
-// Linear MCP server during build (resolves the overview's Open questions).
-const MATCHERS = {
-  projectRead: [/get_?project\b/i, /read_?project/i, /project_?get/i],
-  projectUpdate: [/update_?project/i, /project_?update/i],
-  projectCreate: [/create_?project/i, /project_?create/i],
-  milestoneList: [/list_?.*milestone/i, /milestones?_?list/i, /get_?.*milestones?/i],
-  milestoneCreate: [/create_?.*milestone/i, /milestone_?create/i],
-  milestoneUpdate: [/update_?.*milestone/i, /milestone_?update/i],
-  issueList: [/list_?issues?/i, /issues?_?list/i, /get_?issues?/i],
-  issueCreate: [/create_?issue/i, /issue_?create/i],
-  issueUpdate: [/update_?issue/i, /issue_?update/i],
-}
-
-// The minimum the push/pull engine can't run without. Milestone/issue ops are
-// optional in Phase 2 (project description round-trips first).
-const REQUIRED = ['projectRead', 'projectUpdate']
-
-// Normalise a tools argument (array of strings or {name} objects) to names.
-function toolNames(tools) {
-  if (!Array.isArray(tools)) return []
-  return tools
-    .map((t) => (typeof t === 'string' ? t : t && typeof t === 'object' ? t.name : null))
-    .filter((n) => typeof n === 'string' && n)
-}
-
-/**
- * Resolve Linear operations against the connected server's tool list.
- * @returns {{ok:true, tools:Record<string,string>}} on success, or
- *          {{ok:false, error:string, resolved?:object, missing?:string[]}}.
- */
-function discoverLinear(tools) {
-  const names = toolNames(tools)
-  if (!names.length) {
-    return {
-      ok: false,
-      error: 'Linear not connected — connect the `linear` MCP server, then retry.',
-    }
-  }
-
-  const resolved = {}
-  for (const [op, patterns] of Object.entries(MATCHERS)) {
-    const hit = names.find((n) => patterns.some((p) => p.test(n)))
-    if (hit) resolved[op] = hit
-  }
-
-  const missing = REQUIRED.filter((op) => !resolved[op])
-  if (missing.length) {
-    return {
-      ok: false,
-      error:
-        `Linear MCP is connected but missing required tools: ${missing.join(', ')}. ` +
-        'Check the linear server exposes project read + update.',
-      resolved,
-      missing,
-    }
-  }
-
-  return { ok: true, tools: resolved }
-}
-
-/**
- * Wrap a generic `callTool(name, args) → Promise<result>` into the typed ops the
- * engine uses. `resolved` is `discoverLinear(...).tools`.
- */
-function makeAdapter(callTool, resolved) {
-  const need = (op) => {
-    const name = resolved[op]
-    if (!name) throw new Error(`Linear MCP op not available: ${op}`)
-    return name
-  }
-  return {
-    async readProject(id) {
-      return callTool(need('projectRead'), { id })
-    },
-    async updateProject(id, updates) {
-      return callTool(need('projectUpdate'), { id, ...updates })
-    },
-    async createMilestone(projectId, milestone) {
-      return callTool(need('milestoneCreate'), { projectId, ...milestone })
-    },
-    async updateMilestone(id, updates) {
-      return callTool(need('milestoneUpdate'), { id, ...updates })
-    },
-  }
-}
-
-module.exports = {
-  discoverLinear,
-  makeAdapter,
-  toolNames,
-  MATCHERS,
-  REQUIRED,
-}