@skitterbyte/skitterspec-linear 1.0.0

package/src/vendor/linear/cli-sync.js

@@ -0,0 +1,256 @@
+'use strict'
+
+/**
+ * `spec-sync` CLI handler — the Linear hybrid-sync engine seam.
+ *
+ * Extracted out of the base CLI: this ships only with the Linear provider package,
+ * so the base (`@skitterbyte/skitterspec-common`) knows nothing about tracker sync.
+ * It drives the provider-neutral engine (`@skitterbyte/skitterspec-sync-core`) with
+ * the Linear config loader (`./config.js`) and a file-backed adapter; live
+ * MCP-backed sync goes through the /spec-status · /spec-pull · /spec-push skills.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { findSpecFolder } = require('../../env/resolve.js')
+const {
+  normalizeLocal,
+  normalizeRemote,
+  readSnapshot,
+  classify,
+  readBase,
+  pull,
+  push,
+} = require('../sync-core')
+
+const { loadLinearConfig } = require('./config.js')
+
+// A compact, filesystem-safe timestamp (e.g. 20260714-030405) for backup/adapter
+// stamps. Inlined so this handler needs nothing from the base CLI.
+function compactTimestamp() {
+  return new Date()
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d+Z$/, '')
+    .replace('T', '-')
+}
+
+// Resolve a spec argument to its snapshot dir. Accepts a spec name/folder found
+// under specs/** (preferred) or a literal path to a snapshot directory.
+function resolveSnapshotDir(specArg, dir) {
+  const found = findSpecFolder(specArg, dir)
+  if (found) return found.path
+  const literal = path.resolve(dir, specArg)
+  if (fs.existsSync(literal) && fs.statSync(literal).isDirectory()) return literal
+  return null
+}
+
+// The identifier keying the base sidecar: the spec's linear_identifier if set,
+// else its folder name (so the engine is usable before a spec is linked).
+function specIdentifier(snapshotDir, config) {
+  try {
+    const { frontmatter } = readSnapshot(snapshotDir, config)
+    if (frontmatter.linear_identifier) return String(frontmatter.linear_identifier)
+  } catch {
+    /* fall through to folder name */
+  }
+  return path.basename(snapshotDir)
+}
+
+// `spec-sync normalize <spec>` — print the normalized local field set as JSON.
+function specSyncNormalize(dir, config, specArg) {
+  if (!specArg) {
+    process.stdout.write('Usage: skitterspec spec-sync normalize <spec>\n')
+    return
+  }
+  const snapshotDir = resolveSnapshotDir(specArg, dir)
+  if (!snapshotDir) {
+    process.stdout.write(`spec-sync: spec not found: ${specArg}\n`)
+    return
+  }
+  const local = normalizeLocal(snapshotDir, config)
+  process.stdout.write(JSON.stringify(local, null, 2) + '\n')
+}
+
+// `spec-sync status <spec> [--remote file]` — read-only per-field divergence
+// (git status analog). With `--remote` (a Linear Project projection, supplied by
+// the /spec-status skill via MCP) it reports true three-way divergence; without
+// it, it compares local vs the committed base only (what changed locally since
+// the last sync).
+function specSyncStatus(dir, config, specArg, flags = {}) {
+  if (!specArg) {
+    process.stdout.write('Usage: skitterspec spec-sync status <spec> [--remote file]\n')
+    return
+  }
+  const snapshotDir = resolveSnapshotDir(specArg, dir)
+  if (!snapshotDir) {
+    process.stdout.write(`spec-sync: spec not found: ${specArg}\n`)
+    return
+  }
+  const identifier = specIdentifier(snapshotDir, config)
+  const local = normalizeLocal(snapshotDir, config)
+  const base = readBase(dir, identifier, config)
+
+  let remote = base // no remote → compare local vs base
+  let haveRemote = false
+  if (flags.remote && fs.existsSync(flags.remote)) {
+    remote = normalizeRemote(JSON.parse(fs.readFileSync(flags.remote, 'utf-8')), config)
+    haveRemote = true
+  }
+  const fields = classify(local, remote, base, config)
+
+  const out = []
+  out.push(`spec-sync status: ${identifier}${base ? '' : ' (no base yet — never synced)'}`)
+  if (!haveRemote) out.push('  (no --remote given — compared local vs base only)')
+  const changed = fields.filter((f) => f.status !== 'unchanged')
+  if (!changed.length) {
+    out.push(haveRemote ? '  in sync — local, Linear, and base agree' : '  nothing to sync — local matches base')
+  } else {
+    for (const f of changed) {
+      const dir_ = f.pushable && f.pullable ? 'push+pull' : f.pushable ? 'push' : f.pullable ? 'pull' : '—'
+      out.push(`  ${f.status.padEnd(12)} ${f.field.padEnd(18)} (${f.ownership}, ${dir_})`)
+    }
+  }
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+// The linked Linear project id for a spec (frontmatter linear_project_id), else
+// its identifier — enough for the file adapter / a single-project remote file.
+function specProjectId(snapshotDir, config) {
+  try {
+    const { frontmatter } = readSnapshot(snapshotDir, config)
+    if (frontmatter.linear_project_id) return String(frontmatter.linear_project_id)
+    if (frontmatter.linear_identifier) return String(frontmatter.linear_identifier)
+  } catch {
+    /* fall through */
+  }
+  return path.basename(snapshotDir)
+}
+
+// A file-backed MCP adapter: reads the remote Project projection from a JSON file
+// and (on push) writes the merged result to `outPath` (default: the same file).
+// This lets `spec-sync push|pull` run the engine deterministically from the CLI /
+// CI. Live MCP-backed sync goes through the /spec-push · /spec-pull skills, which
+// supply the real adapter. `stamp` bumps updatedAt on write.
+function fileAdapter(remotePath, outPath, stamp) {
+  const readRemote = () => JSON.parse(fs.readFileSync(remotePath, 'utf-8'))
+  return {
+    async readProject() {
+      return fs.existsSync(remotePath) ? readRemote() : null
+    },
+    async updateProject(id, updates) {
+      const merged = { ...readRemote(), ...updates, updatedAt: `${stamp}-pushed` }
+      if (outPath) fs.writeFileSync(outPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8')
+      return merged
+    },
+  }
+}
+
+// Print a git-like summary of a pull/push engine result.
+function printSyncResult(kind, result) {
+  const out = []
+  if (result.ok === false && !result.blocked) {
+    out.push(`spec-sync ${kind}: error — ${result.error}`)
+  } else if (result.blocked) {
+    out.push(`spec-sync ${kind}: refused — ${result.message}`)
+  } else {
+    out.push(`spec-sync ${kind}: ok`)
+    if (kind === 'pull') {
+      if (result.applied.length) out.push(`  applied:   ${result.applied.join(', ')}`)
+      if (result.deferred.length) out.push(`  deferred:  ${result.deferred.join(', ')} (body write-back — manual)`)
+      if (!result.applied.length && !result.deferred.length) out.push('  nothing to pull — up to date')
+    } else {
+      if (result.written && result.written.length) out.push(`  written:   ${result.written.join(', ')}`)
+      if (result.skipped && result.skipped.length) out.push(`  skipped:   ${result.skipped.join(', ')} (not pushable)`)
+      if (result.note) out.push(`  ${result.note}`)
+    }
+    if (result.backupPath) out.push(`  backup:    ${result.backupPath}`)
+    if (result.basePath) out.push(`  base:      ${result.basePath}`)
+  }
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+// `spec-sync push|pull <spec> [--force] [--remote file] [--out file]`.
+async function specSyncPushPull(kind, dir, config, specArg, flags) {
+  if (!specArg) {
+    process.stdout.write(`Usage: skitterspec spec-sync ${kind} <spec> [--force] [--remote file] [--out file]\n`)
+    return
+  }
+  const snapshotDir = resolveSnapshotDir(specArg, dir)
+  if (!snapshotDir) {
+    process.stdout.write(`spec-sync: spec not found: ${specArg}\n`)
+    return
+  }
+  if (!flags.remote) {
+    process.stdout.write(
+      `spec-sync ${kind}: live Linear sync runs through the /spec-${kind} skill, which ` +
+        'connects the Linear MCP server.\n' +
+        `For a local run, pass --remote <project.json> (a Linear Project projection).\n`,
+    )
+    return
+  }
+  const identifier = specIdentifier(snapshotDir, config)
+  const projectId = specProjectId(snapshotDir, config)
+  const stamp = compactTimestamp()
+  const adapter = fileAdapter(flags.remote, flags.out, stamp)
+  const run = kind === 'pull' ? pull : push
+  const result = await run({
+    dir,
+    snapshotDir,
+    identifier,
+    projectId,
+    adapter,
+    config,
+    force: flags.force,
+    timestamp: new Date().toISOString(),
+  })
+  printSyncResult(kind, result)
+}
+
+// Dispatch `skitterspec spec-sync <sub> [spec] [flags]`. No-ops with a clear
+// message when Linear sync isn't enabled (no specs/.core/linear.config.json).
+async function specSync(rest) {
+  const [sub, ...args] = rest
+  let dir = process.cwd()
+  const positional = []
+  const flags = { force: false, remote: null, out: null }
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') dir = path.resolve(args[++i])
+    else if (args[i] === '--force') flags.force = true
+    else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
+    else if (args[i] === '--out') flags.out = path.resolve(args[++i])
+    else positional.push(args[i])
+  }
+  dir = path.resolve(dir)
+
+  const { config, present } = loadLinearConfig(dir)
+  if (!present) {
+    process.stdout.write(
+      'spec-sync: Linear sync not enabled (no specs/.core/linear.config.json).\n' +
+        'Opt in by copying specs/.core/linear.config.json.example → linear.config.json.\n',
+    )
+    return
+  }
+
+  switch (sub) {
+    case 'normalize':
+      specSyncNormalize(dir, config, positional[0])
+      break
+    case 'status':
+      specSyncStatus(dir, config, positional[0], flags)
+      break
+    case 'pull':
+      await specSyncPushPull('pull', dir, config, positional[0], flags)
+      break
+    case 'push':
+      await specSyncPushPull('push', dir, config, positional[0], flags)
+      break
+    default:
+      process.stdout.write(
+        'Usage: skitterspec spec-sync <normalize|status|pull|push> <spec> [--force] [--remote file] [--out file]\n',
+      )
+  }
+}
+
+module.exports = { specSync }

package/src/vendor/linear/config.js

@@ -0,0 +1,198 @@
+'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/vendor/linear/mcp.js

@@ -0,0 +1,112 @@
+'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,
+}

package/src/vendor/sync-core/index.js

@@ -0,0 +1,35 @@
+'use strict'
+
+/**
+ * Provider-neutral spec↔tracker sync engine.
+ *
+ * Every function here is parameterised by a plain `config` object and an injected
+ * `adapter` — it knows nothing about any specific tracker or provider. A
+ * provider package supplies the config shape, the frontmatter key mapping, and the
+ * adapter that talks to its API; this core does the three-way merge.
+ */
+
+const { normalizeLocal, normalizeRemote, readSnapshot } = require('./src/normalize.js')
+const { classify, hashField, stableStringify } = require('./src/compare.js')
+const { readBase, writeBase, backup } = require('./src/base.js')
+const { pull } = require('./src/pull.js')
+const { push } = require('./src/push.js')
+const { writeFrontmatter } = require('./src/write.js')
+const { frontmatterPatchFor, localWorkflowState } = require('./src/apply.js')
+
+module.exports = {
+  normalizeLocal,
+  normalizeRemote,
+  readSnapshot,
+  classify,
+  hashField,
+  stableStringify,
+  readBase,
+  writeBase,
+  backup,
+  pull,
+  push,
+  writeFrontmatter,
+  frontmatterPatchFor,
+  localWorkflowState,
+}

package/src/vendor/sync-core/src/apply.js

@@ -0,0 +1,66 @@
+'use strict'
+
+/**
+ * Translate normalized field values into a local frontmatter patch (pull side).
+ *
+ * Only the `pull`-owned, frontmatter-backed fields have a local home in Phase 2:
+ *   workflowState → spec_status (remote state name mapped back to the bucket),
+ *   priority      → priority,
+ *   labels        → labels.
+ * Any other field handed in (a body field like `description`/`milestones`) has no
+ * frontmatter mapping yet, so it's returned in `deferred` — the caller must NOT
+ * advance its base, keeping the remote edit pending instead of falsely synced.
+ */
+
+// field name → frontmatter key.
+const FRONTMATTER_FIELD = {
+  workflowState: 'spec_status',
+  priority: 'priority',
+  labels: 'labels',
+}
+
+// Invert config.states ({ bucket: "remote Name" }) → { "remote name": bucket }.
+function invertStates(config) {
+  const out = {}
+  const states = (config && config.states) || {}
+  for (const [bucket, name] of Object.entries(states)) {
+    if (typeof name === 'string') out[name.toLowerCase()] = bucket
+  }
+  return out
+}
+
+// Map a remote workflowState (a remote state name) back to a local bucket. Falls
+// back to the raw value when it isn't one of the configured states.
+function localWorkflowState(value, config) {
+  if (value == null) return null
+  const bucket = invertStates(config)[String(value).toLowerCase()]
+  return bucket || String(value)
+}
+
+/**
+ * Build the frontmatter patch for a set of applied field values.
+ * @param {object} fieldValues  { fieldName: value } to write locally
+ * @returns {{ patch:object, applied:string[], deferred:string[] }}
+ */
+function frontmatterPatchFor(fieldValues, config) {
+  const patch = {}
+  const applied = []
+  const deferred = []
+  for (const [field, value] of Object.entries(fieldValues)) {
+    const key = FRONTMATTER_FIELD[field]
+    if (!key) {
+      deferred.push(field)
+      continue
+    }
+    patch[key] = field === 'workflowState' ? localWorkflowState(value, config) : value
+    applied.push(field)
+  }
+  return { patch, applied, deferred }
+}
+
+module.exports = {
+  frontmatterPatchFor,
+  localWorkflowState,
+  invertStates,
+  FRONTMATTER_FIELD,
+}