@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/vendor/provider-kit/src/specs.js

@@ -0,0 +1,248 @@
+'use strict'
+
+/**
+ * Spec resolution and listing for a provider CLI — how a spec argument becomes
+ * a snapshot directory, how a spec names its snapshot sidecar, and which specs
+ * a repo holds with which tracker links.
+ *
+ * The frontmatter key that links a spec is the provider's
+ * (`config.fields.identifier` — sync-core `src/fields.js`); everything else
+ * here is filesystem shape shared by every provider. `program` prefixes the
+ * user-facing refusals (`spec-sync: spec not found: …`).
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { execFileSync } = require('node:child_process')
+
+const {
+  BUCKETS,
+  findSpecFolder,
+  resolveSpec,
+  liveWorktreePaths,
+  resolvePrimaryCheckout,
+} = require('../../../env/resolve.js')
+const { loadEnvConfig } = require('../../../env/config.js')
+const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
+
+function makeSpecHelpers({ program = 'spec-sync' } = {}) {
+  // 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 snapshot sidecar: the spec's stamped identifier
+  // if set, else its folder name (so the engine is usable before a spec is
+  // linked).
+  function specIdentifier(snapshotDir, config) {
+    const field = fieldsOf(config).identifier
+    try {
+      const { frontmatter } = readSnapshot(snapshotDir, config)
+      if (frontmatter[field]) return String(frontmatter[field])
+    } catch {
+      /* fall through to folder name */
+    }
+    return path.basename(snapshotDir)
+  }
+
+  // Read a spec's stamped identifier without throwing: an unlinked spec, an
+  // unreadable file and a spec with no frontmatter all read as `null`.
+  function linkedIdentifier(overviewPath, config) {
+    return linkedFields(overviewPath, config).identifier
+  }
+
+  // The stamped identifier AND url, each `null` when absent. The url is only
+  // ever what a push stamped — never built from the identifier, because a url
+  // constructed here would be a guess about a tracker's address scheme.
+  function linkedFields(overviewPath, config) {
+    const fields = fieldsOf(config)
+    let raw
+    try {
+      raw = fs.readFileSync(overviewPath, 'utf-8')
+    } catch {
+      return { identifier: null, url: null }
+    }
+    const { data } = parseFrontmatter(raw)
+    return {
+      identifier: data[fields.identifier] ? String(data[fields.identifier]) : null,
+      url: fields.url && data[fields.url] ? String(data[fields.url]) : null,
+    }
+  }
+
+  // Every spec under specs/<bucket>/, paired with the tracker issue it is
+  // linked to (`null` when it has never been pushed). Folder specs read
+  // `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
+  // itself. Sorted for stable output.
+  function listSpecs(dir, config, options = {}) {
+    const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+    const specs = []
+    for (const bucket of BUCKETS) {
+      const root = path.join(dir, 'specs', bucket)
+      let entries
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) {
+        let name
+        let overviewPath
+        if (entry.isDirectory()) {
+          name = entry.name
+          overviewPath = path.join(root, name, overviewFile)
+        } else if (entry.isFile() && entry.name.endsWith('.md')) {
+          name = entry.name.slice(0, -3)
+          overviewPath = path.join(root, entry.name)
+        } else {
+          continue
+        }
+        const linked = linkedFields(overviewPath, config)
+        const row = { spec: name, bucket, identifier: linked.identifier }
+        // Opt-in, so every listing that never asked for a url keeps its shape.
+        if (options.urls) row.url = linked.url
+        specs.push(row)
+      }
+    }
+    return specs.sort((a, b) => a.spec.localeCompare(b.spec))
+  }
+
+  // `listSpecs`, but each spec's BUCKET read from where that spec actually
+  // lives. `/spec-start` moves a spec to `in-progress/` on its own branch, so
+  // on the base branch an in-flight spec still reads `backlog` — and a spec
+  // authored in its own worktree and not yet landed is not here at all. Each
+  // live worktree is read too, and a spec found in ITS OWN worktree (the path
+  // `resolveSpec` names for it) wins over every other copy. `source` says
+  // which: `here`, `worktree`, or `other-tree` for a spec only some other
+  // worktree carries.
+  //
+  // WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is
+  // still live, so a finished spec can read from a stale tree. And with no
+  // `env.config.json` there is no worktree layout to resolve, so this is
+  // exactly `listSpecs` — the current tree's answer, as before.
+  function listSpecsLive(dir, config) {
+    const here = listSpecs(dir, config).map((s) => ({ ...s, source: 'here' }))
+    const git = (args) => {
+      try {
+        return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+      } catch {
+        return null
+      }
+    }
+    let primary
+    let env
+    try {
+      primary = resolvePrimaryCheckout(dir, git) || dir
+      env = loadEnvConfig(primary)
+    } catch {
+      return here
+    }
+    if (!env.present) return here
+    // Compared as REAL paths: git reports a worktree resolved through
+    // symlinks (macOS /var → /private/var) where `resolveSpec` does not.
+    const real = (p) => {
+      try {
+        return fs.realpathSync(p)
+      } catch {
+        return path.resolve(p)
+      }
+    }
+    const self = real(dir)
+    const byName = new Map(here.map((s) => [s.spec, s]))
+    for (const listed of liveWorktreePaths(git)) {
+      const tree = real(listed)
+      if (tree === self) continue
+      for (const s of listSpecs(tree, config)) {
+        let own = null
+        try {
+          own = real(resolveSpec(s.spec, primary, env.config, { searchDirs: [tree] }).worktreePath)
+        } catch {
+          own = null
+        }
+        if (own === tree) byName.set(s.spec, { ...s, source: 'worktree' })
+        else if (!byName.has(s.spec)) byName.set(s.spec, { ...s, source: 'other-tree' })
+      }
+    }
+    return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
+  }
+
+  // Resolve a spec argument to its folder, or null with a message on stdout.
+  // EVERY failure path here must print and EVERY caller must return a non-zero
+  // code: a push skill checks $? before it applies a plan, so a resolve failure
+  // that exits 0 reads as "nothing to do" rather than "I could not find the
+  // spec".
+  function resolveOrExit(specArg, dir, out) {
+    if (!specArg) {
+      out.write(`${program}: no spec given\n`)
+      return null
+    }
+    const snapshotDir = resolveSnapshotDir(specArg, dir)
+    if (!snapshotDir) {
+      out.write(`${program}: spec not found: ${specArg}\n`)
+      return null
+    }
+    return snapshotDir
+  }
+
+  // Phase-status warnings for a spec, one formatted line each. A spec states
+  // each phase's status three times and only the h1 emoji is read — get it
+  // wrong and the phase projects as `backlog`, pushes cleanly, and is recorded
+  // as intended: invisible. Reported by every subcommand that reads a
+  // projection, fatal in none — a legacy spec must still push.
+  function warningLines(snapshotDir, config) {
+    return lintPhases(snapshotDir, config).map((w) => `  warning ${w.file}: ${w.message}`)
+  }
+
+  // Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
+  function warnToErr(snapshotDir, config, err) {
+    const lines = warningLines(snapshotDir, config)
+    if (lines.length) err.write(lines.join('\n') + '\n')
+  }
+
+  // Render the read-back comparison — the same check `verify` and `apply`
+  // both report through, so the two cannot disagree about what "intact" means.
+  function verifyLines(snapshotDir, config, stored, identifier) {
+    const projection = projectionOf(snapshotDir, config)
+    const checks = []
+    if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
+    for (const [ref, text] of Object.entries(stored.subIssues || {})) {
+      const sub = projection.subIssues.find((s) => s.ref === ref)
+      if (!sub) {
+        checks.push([`sub-issue ${ref}`, null, text])
+        continue
+      }
+      checks.push([`sub-issue ${ref}`, sub.goal, text])
+    }
+
+    const lines = [`${program} verify: ${identifier}`]
+    let bad = 0
+    for (const [label, sent, got] of checks) {
+      if (sent == null) {
+        lines.push(`  ?? ${label}: read back, but the projection has no such phase — stale ref?`)
+        bad++
+        continue
+      }
+      const r = compareStored(sent, got, config)
+      if (r.ok) continue
+      bad++
+      lines.push(
+        `  !! ${label}: the tracker stored different text — ${Math.abs(r.lost)} character(s) ` +
+          `${r.lost > 0 ? 'lost' : 'added'}, first difference at ${r.at}`,
+        `     sent:   …${r.sentContext}…`,
+        `     stored: …${r.storedContext}…`,
+      )
+    }
+    if (!bad) lines.push(`  ${checks.length} description(s) round-tripped intact`)
+    else lines.push('     the repo is unchanged and still correct; re-push to overwrite the mirror')
+    return lines
+  }
+
+  return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
+}
+
+module.exports = { makeSpecHelpers }

package/src/vendor/provider-kit/src/transport.js

@@ -0,0 +1,22 @@
+'use strict'
+
+/**
+ * Which transport a command runs over: `--via` wins, else the config's
+ * declared default, else "api when a credential resolved, mcp when it didn't".
+ *
+ * This expression was repeated verbatim nine times in the first provider —
+ * hoisted so the precedence is decided once. Per-command DEGRADATION stays with
+ * the command: which operations are impossible over mcp (exit 1, say so) and
+ * which hand the skill instructions (exit 0) is a per-command judgment, not a
+ * transport fact.
+ */
+
+function resolveTransport(flags, config, credentialOk) {
+  return (
+    (flags && flags.via) ||
+    (config && config.apply && config.apply.transport) ||
+    (credentialOk ? 'api' : 'mcp')
+  )
+}
+
+module.exports = { resolveTransport }

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

@@ -0,0 +1,92 @@
+'use strict'
+
+/**
+ * Provider-neutral one-way sync engine (repo → tracker).
+ *
+ * Every function is parameterised by a plain `config` object — it knows nothing
+ * about any specific tracker. The repo is the source of truth: the engine builds
+ * a local projection, diffs it against a committed last-pushed snapshot
+ * (`planChanges`), and returns a create/update plan the provider skill applies
+ * over its API. No remote content is read for CONTENT: nothing the tracker holds
+ * ever feeds the projection, the snapshot, or a repo file. `compareStored` is the
+ * one function that looks at a tracker value, and it only checks that what was
+ * stored matches what was sent — it merges nothing (see `src/verify.js`).
+ */
+
+const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
+const { readBase, writeBase } = require('./src/base.js')
+const { push, recordPush, projectionOf } = require('./src/push.js')
+const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
+const { detectLegacyMirror } = require('./src/legacy.js')
+const { compareStored, stream } = require('./src/verify.js')
+const { identityDialect, dialectOf } = require('./src/dialect.js')
+const { fieldsOf } = require('./src/fields.js')
+const { renderTaskBlock, findTaskBlocks, wrapEmphasisAware, collapseHyphenAware, inferWidth, fenceMask, DEFAULT_WIDTH } = require('./src/task-block.js')
+const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
+
+module.exports = {
+  ownsField,
+  normalizeLocal,
+  // Exported for `spec-sync list`: an `inline`-mode spec has no phase sub-issues
+  // to read, so the listing must resolve the mode rather than assume `subissue`.
+  phaseModeFor,
+  lintPhases,
+  readSnapshot,
+  parseFrontmatter,
+  projectionOf,
+  planChanges,
+  snapshotOf,
+  isEmptyPlan,
+  push,
+  recordPush,
+  remoteWorkflowState,
+  remoteStateReading,
+  stateNamesFor,
+  titleFromText,
+  validateStates,
+  stateSuggestions,
+  hashField,
+  stableStringify,
+  readBase,
+  writeBase,
+  writeFrontmatter,
+  deleteFrontmatter,
+  stampSubIssueId,
+  stampIssueId,
+  findPhaseFileByTitle,
+  listPhaseFiles,
+  detectLegacyMirror,
+  compareStored,
+  // The tolerant reduction behind both `compareStored` and the snapshot's
+  // `descriptionStream` hash — exported so a provider can reduce a read-back the
+  // same way rather than writing a second one that disagrees.
+  stream,
+  // Did someone else edit the tracker's description since the last push?
+  // Three-valued; `null` is cannot-tell and must never be reported as drift.
+  remoteDescriptionEdited,
+  remoteSubIssueEdited,
+  // Provider seams: the frontmatter field vocabulary and the markdown dialect
+  // a provider's config supplies (`config.fields` / `config.dialect`).
+  fieldsOf,
+  identityDialect,
+  dialectOf,
+  // The lifecycle buckets, exported once so providers and tests stop growing
+  // private copies (the tracker-free common package keeps its own — it cannot
+  // depend on this package).
+  LIFECYCLE_BUCKETS,
+  // Task-block helpers a provider's own text tooling builds on (the Linear
+  // sanitiser reflows emphasis-aware with these).
+  renderTaskBlock,
+  findTaskBlocks,
+  wrapEmphasisAware,
+  collapseHyphenAware,
+  inferWidth,
+  fenceMask,
+  DEFAULT_WIDTH,
+  planRetarget,
+  applyRetarget,
+  deriveRecordedKey,
+  isEmptyRetarget,
+  dirtyPaths,
+}

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

@@ -0,0 +1,81 @@
+'use strict'
+
+/**
+ * The committed **last-pushed snapshot** sidecar.
+ *
+ * One-way sync (repo → Linear) records what it last pushed per spec at
+ * `{sync.baseDir}/{identifier}.base.json`, committed so each worktree carries its
+ * own snapshot. The snapshot is a set of content hashes
+ * (`{ issue, subIssues: {id:hash} }`, see compare.js
+ * `snapshotOf`); `planChanges` diffs the current projection against it to decide
+ * create/update/skip — no remote read. After a successful push the engine
+ * rewrites it (`writeBase`). Generic JSON read/write; the shape is the caller's.
+ */
+
+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,
+}