@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/vendor/jira/commands.js

@@ -0,0 +1,44 @@
+'use strict'
+
+/**
+ * The commands this provider distribution adds on top of the base CLI.
+ *
+ * ONE table drives both routing and `--help`, exactly as the Linear provider's
+ * does: anything added here is routed and documented in the same edit, so the
+ * two cannot drift.
+ *
+ * `run(rest)` returns an exit code (the bin propagates it); `summary` is the
+ * one-line description `--help` prints.
+ */
+
+const { specSync } = require('./cli-sync.js')
+
+const DIST = '@skitterbyte/skitterspec-jira'
+
+const PROVIDER_COMMANDS = {
+  'spec-sync': {
+    run: specSync,
+    usage: 'skitterspec spec-sync <cmd>',
+    summary:
+      'One-way sync to Jira Cloud (repo -> tracker; opt-in, needs\n' +
+      'specs/.core/jira.config.json). Run it with no args to\n' +
+      'list its subcommands.',
+  },
+}
+
+// The `--help` section for these commands, in the base HELP's column layout:
+// two-space indent, description starting at column 30, continuations aligned.
+const COL = 30
+
+function providerHelpSection() {
+  const lines = [`Provider commands (${DIST}):`]
+  for (const name of Object.keys(PROVIDER_COMMANDS)) {
+    const { usage, summary } = PROVIDER_COMMANDS[name]
+    const [first, ...rest] = summary.split('\n')
+    lines.push(`  ${usage.padEnd(COL - 2)}${first}`)
+    for (const line of rest) lines.push(`${' '.repeat(COL)}${line}`)
+  }
+  return lines.join('\n') + '\n'
+}
+
+module.exports = { PROVIDER_COMMANDS, providerHelpSection, DIST }

package/src/vendor/jira/config.js

@@ -0,0 +1,286 @@
+'use strict'
+
+/**
+ * `specs/.core/jira.config.json` — the committed, shareable half of this
+ * provider's setup. It holds ids, names and env-var NAMES; never a credential
+ * (those live in the user-level store — `credentials.js`).
+ *
+ * The merge/validation machinery is the kit's (`provider-kit/src/config.js`);
+ * this module owns what is Jira's: the defaults, the file name, and the
+ * vocabularies.
+ */
+
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+const kitConfig = require('../provider-kit/src/config.js')
+const { dialect } = require('./dialect.js')
+const { adfToText } = require('./adf.js')
+
+const CONFIG_FILE = 'specs/.core/jira.config.json'
+
+const OWNERSHIP = Object.freeze(['both', 'pull', 'push', 'none'])
+const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
+const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
+const TRANSPORTS = Object.freeze(['api', 'mcp'])
+const DEFAULT_EMAIL_ENV = 'JIRA_EMAIL'
+const DEFAULT_TOKEN_ENV = 'JIRA_API_TOKEN'
+const DEFAULT_PHASE_MODE = 'subissue'
+
+const DEFAULT_CONFIG = Object.freeze({
+  // `siteUrl` is the Jira Cloud site (https://<site>.atlassian.net); it also
+  // keys the credentials-store entry, so one store serves every checkout.
+  // `projectKey` is where spec issues land — Jira's project is the analogue of
+  // Linear's team, so there is no separate project picker: placement is decided
+  // here, once. `issueType`/`subtaskType` name the types this site uses for a
+  // spec and its phases; workflows and type names vary per site, which is why
+  // both are config rather than constants.
+  jira: Object.freeze({ siteUrl: '', projectKey: '', issueType: 'Task', subtaskType: 'Subtask' }),
+  // A spec is a Jira ISSUE; each phase a SUBTASK of it. `tasks` selects how the
+  // phase's checkboxes reach that subtask's description (as an ADF task list —
+  // live checkboxes, still a read-only mirror).
+  mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist' }),
+  // Jira STATUS names — the spec issue's status (from the folder bucket) and
+  // each subtask's status (from the phase emoji) both map through this table.
+  // They must match the project's workflow statuses exactly; `validateStates`
+  // checks them at push/status time. `cancelled` defaults to Done because the
+  // default Jira workflows carry no Cancelled status — a site that has one
+  // overrides this.
+  states: Object.freeze({
+    backlog: 'To Do',
+    'in-progress': 'In Progress',
+    complete: 'Done',
+    cancelled: 'Done',
+  }),
+  snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
+  // The frontmatter FIELD VOCABULARY this provider stamps into spec files
+  // (sync-core `src/fields.js`). No legacy keys: this provider has no pre-9.0
+  // era, so legacy-mirror detection reports nothing by construction.
+  fields: Object.freeze({
+    identifier: 'jira_identifier',
+    url: 'jira_url',
+    issueId: 'jira_issue_id',
+    assigneeId: 'jira_assignee_id',
+    assigneeName: 'jira_assignee_name',
+  }),
+  release: Object.freeze({ ignorePaths: Object.freeze(['specs/', 'CHANGELOG.md', 'RELEASES.md']) }),
+  branch: Object.freeze({ pattern: '{type}/{slug}' }),
+  // Env-var NAMES, not values: Jira Cloud authenticates with an email + API
+  // token pair (basic auth), so there are two of them.
+  auth: Object.freeze({ emailEnv: DEFAULT_EMAIL_ENV, tokenEnv: DEFAULT_TOKEN_ENV }),
+  apply: Object.freeze({ transport: '' }),
+  sync: Object.freeze({
+    baseDir: 'specs/.core/jira-base',
+    backupDir: 'specs/.core/jira-backups',
+    fieldOwnership: Object.freeze({
+      description: 'push',
+      subIssues: 'push',
+      workflowState: 'push',
+      assignee: 'push',
+    }),
+    localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
+    keyedFields: Object.freeze({}),
+  }),
+})
+
+const IDENTIFIER_FIELD = DEFAULT_CONFIG.fields.identifier
+
+// The per-spec-isolation keys THIS PROVIDER needs a project to declare, merged
+// into env.config.json.example at dist-compose time (see build-dist.js).
+const ENV_CONFIG_DEFAULTS = Object.freeze({
+  branch: Object.freeze({ identifierField: IDENTIFIER_FIELD }),
+  spec: Object.freeze({
+    companionPaths: Object.freeze([`${DEFAULT_CONFIG.sync.baseDir}/{identifier}.base.json`]),
+  }),
+})
+
+const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
+
+// A fresh, deeply-mutable copy of the defaults to merge onto.
+function defaults() {
+  return {
+    jira: { ...DEFAULT_CONFIG.jira },
+    mapping: { ...DEFAULT_CONFIG.mapping },
+    states: { ...DEFAULT_CONFIG.states },
+    stateAliases: {},
+    snapshot: { ...DEFAULT_CONFIG.snapshot },
+    fields: { ...DEFAULT_CONFIG.fields },
+    release: {
+      ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
+    },
+    branch: { ...DEFAULT_CONFIG.branch },
+    auth: { ...DEFAULT_CONFIG.auth },
+    apply: { ...DEFAULT_CONFIG.apply },
+    sync: {
+      baseDir: DEFAULT_CONFIG.sync.baseDir,
+      backupDir: DEFAULT_CONFIG.sync.backupDir,
+      fieldOwnership: { ...DEFAULT_CONFIG.sync.fieldOwnership },
+      localOnlySections: [...DEFAULT_CONFIG.sync.localOnlySections],
+      keyedFields: { ...DEFAULT_CONFIG.sync.keyedFields },
+    },
+  }
+}
+
+const { isObject, stringList, assign } = kitConfig
+const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
+  kitConfig.makeMergeHelpers({
+    configFile: CONFIG_FILE,
+    ownership: OWNERSHIP,
+    lifecycleBuckets: LIFECYCLE_BUCKETS,
+    phaseMappings: PHASE_MAPPINGS,
+  })
+
+/**
+ * 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.jira)) {
+    assign(base.jira, parsed.jira, 'siteUrl', 'string?')
+    assign(base.jira, parsed.jira, 'projectKey', 'string?')
+    assign(base.jira, parsed.jira, 'issueType', 'string')
+    assign(base.jira, parsed.jira, 'subtaskType', 'string')
+    // A trailing slash on the site would double up in every composed URL.
+    if (base.jira.siteUrl) base.jira.siteUrl = base.jira.siteUrl.replace(/\/+$/, '')
+  }
+
+  if (isObject(parsed.mapping)) {
+    assign(base.mapping, parsed.mapping, 'specFolder', 'string')
+    assign(base.mapping, parsed.mapping, 'tasks', 'string')
+    if (!TASK_MAPPINGS.includes(base.mapping.tasks)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: mapping.tasks = ${JSON.stringify(base.mapping.tasks)} ` +
+          `(expected one of ${TASK_MAPPINGS.join('|')})`,
+      )
+    }
+    mergePhaseMapping(base.mapping, parsed.mapping)
+  }
+
+  mergeStates(base, parsed)
+
+  if (isObject(parsed.snapshot)) {
+    assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
+  }
+
+  if (isObject(parsed.release)) {
+    mergeReleaseIgnorePaths(base.release, parsed.release)
+  }
+
+  if (isObject(parsed.branch)) {
+    assign(base.branch, parsed.branch, 'pattern', 'string')
+  }
+
+  if (isObject(parsed.auth)) {
+    assign(base.auth, parsed.auth, 'emailEnv', 'string')
+    assign(base.auth, parsed.auth, 'tokenEnv', 'string')
+  }
+
+  if (isObject(parsed.apply)) {
+    assign(base.apply, parsed.apply, 'transport', 'string?')
+    if (base.apply.transport && !TRANSPORTS.includes(base.apply.transport)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: apply.transport = ${JSON.stringify(base.apply.transport)} ` +
+          `(expected one of ${TRANSPORTS.join('|')})`,
+      )
+    }
+  }
+
+  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 = stringList(parsed.sync.localOnlySections)
+    }
+    mergeKeyedFields(base.sync.keyedFields, parsed.sync.keyedFields)
+  }
+
+  return base
+}
+
+// Attach the parts of the provider contract that are code, not JSON: the ADF
+// dialect, and the `provider` block retarget reads (Jira's project key is the
+// identifier prefix, the analogue of Linear's team key). Runs on BOTH loader
+// paths so an absent config still carries them.
+function withRuntime(config) {
+  config.dialect = dialect
+  config.provider = {
+    teamKey: (config.jira && config.jira.projectKey) || '',
+    configFile: CONFIG_FILE,
+    teamKeyJsonField: 'projectKey',
+  }
+  // How sync-core reads a REMOTE issue this provider hands it. `--remote` is
+  // documented as "fetch the issue JSON", which is the raw REST shape —
+  // everything under `fields`, the description as ADF — where the default
+  // readers expect the flat Linear-like shape. Without these hooks every
+  // drift check routes to its silent cannot-tell branch, so `status
+  // --remote` can never report anything. Each hook falls back to the flat
+  // shape, so a pre-reduced payload keeps working.
+  config.remote = {
+    stateName(issue) {
+      const st = issue && issue.fields && issue.fields.status
+      if (st && typeof st === 'object' && st.name != null) return st.name
+      const flat = issue && (issue.state != null ? issue.state : issue.status)
+      if (flat == null) return null
+      if (typeof flat === 'object') return flat.name != null ? flat.name : flat.type != null ? flat.type : null
+      return flat
+    },
+    description(issue) {
+      const fields = issue && issue.fields
+      if (fields && typeof fields === 'object' && 'description' in fields) {
+        // null IS an answer on this branch: Jira returns it when the field
+        // was fetched and the description is genuinely empty — clearing a
+        // description on Jira is an edit, not a cannot-tell.
+        const d = fields.description
+        return d == null ? '' : typeof d === 'string' ? d : adfToText(d)
+      }
+      return issue && typeof issue.description === 'string' ? issue.description : undefined
+    },
+  }
+  return config
+}
+
+function loadJiraConfig(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: withRuntime(base), present: false }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+
+  return { config: withRuntime(mergeConfig(base, parsed)), present: true }
+}
+
+// The bookkeeping path prefixes `released` ignores.
+const releaseIgnorePaths = (config) => (config.release && config.release.ignorePaths) || []
+
+module.exports = {
+  loadJiraConfig,
+  mergeConfig,
+  defaults,
+  releaseIgnorePaths,
+  DEFAULT_CONFIG,
+  CONFIG_FILE,
+  OWNERSHIP,
+  TASK_MAPPINGS,
+  PHASE_MAPPINGS,
+  LIFECYCLE_BUCKETS,
+  TRANSPORTS,
+  DEFAULT_EMAIL_ENV,
+  DEFAULT_TOKEN_ENV,
+  ENV_CONFIG_DEFAULTS,
+  IDENTIFIER_FIELD,
+}

package/src/vendor/jira/credentials.js

@@ -0,0 +1,108 @@
+'use strict'
+
+/**
+ * The Jira binding of the shared credentials store
+ * (`@skitterbyte/skitterspec-provider-kit`, `src/credentials.js`) — one file
+ * per machine at `$XDG_CONFIG_HOME/skitterspec/credentials.json`, this
+ * provider's entries keyed by SITE URL so one store serves every checkout.
+ *
+ * Jira Cloud authenticates with an email + API-token pair (basic auth), so the
+ * stored credential is COMPOUND — `{ email, token }` — where Linear's is a
+ * bare string. The kit store passes compounds through opaquely
+ * (`credentialFor`), and the token half is a secret on exactly the same terms
+ * as a key: never logged, never in an error, never in argv.
+ *
+ * Environment wins over the store: `auth.emailEnv` + `auth.tokenEnv` (both
+ * required — an email without a token authenticates nothing).
+ */
+
+const kit = require('../provider-kit/src/credentials.js')
+
+// v1 stores were only ever written by the Linear provider (the store predates
+// the namespace), so this binding is NOT their owner: its first write migrates
+// a v1 file to the namespaced v2 shape, folding the old entries under linear.
+const store = kit.makeCredentialsStore({ provider: 'jira', legacyV1Owner: 'linear' })
+
+// An Atlassian API token pasted where a command belongs. Tokens are opaque
+// strings; the modern ones carry this prefix.
+const LITERAL_TOKEN_RE = /ATATT[A-Za-z0-9_=-]{8,}/
+
+const LITERAL_TOKEN_ADVICE =
+  'that command has a Jira API token written into it.\n' +
+  '  A command is displayed by `credentials status` and is not treated as a\n' +
+  '  secret — embedding a token there exposes it. To store credentials, run\n' +
+  '  `credentials set` with no arguments and paste at the hidden prompt.'
+
+const siteOf = (config) => (config && config.jira && config.jira.siteUrl) || ''
+
+/**
+ * Resolve the email + token pair: environment first, then the store.
+ *
+ * @returns {{ ok: true, email, token, source } | { ok: false, error, envVars }}
+ *   `source` is `'env'` or `'store'`. The error names what was looked for and
+ *   where; it never contains a token.
+ */
+function resolveCredential(config, env = process.env, deps = {}) {
+  const emailEnv = (config && config.auth && config.auth.emailEnv) || 'JIRA_EMAIL'
+  const tokenEnv = (config && config.auth && config.auth.tokenEnv) || 'JIRA_API_TOKEN'
+  const email = (env[emailEnv] || '').trim()
+  const token = (env[tokenEnv] || '').trim()
+  if (email && token) return { ok: true, email, token, source: 'env', envVars: [emailEnv, tokenEnv] }
+
+  const site = siteOf(config)
+  const file = (deps.storePath || kit.storePath)(env)
+  if (site) {
+    const read = (deps.readStore || kit.readStore)(file)
+    if (read.ok) {
+      const cred = store.credentialFor(read.store, site)
+      if (cred && typeof cred.email === 'string' && typeof cred.token === 'string' && cred.email && cred.token) {
+        return { ok: true, email: cred.email, token: cred.token, source: 'store', path: file }
+      }
+    } else if (read.code !== 'absent') {
+      return { ok: false, error: read.reason, envVars: [emailEnv, tokenEnv], path: file }
+    }
+  }
+
+  const half = email || token ? `\n  (${email ? tokenEnv : emailEnv} is unset — both are required)` : ''
+  return {
+    ok: false,
+    error:
+      `no Jira credentials: set ${emailEnv} and ${tokenEnv}, or run ` +
+      `\`skitterspec-jira spec-sync credentials set\`${half}`,
+    envVars: [emailEnv, tokenEnv],
+    path: file,
+  }
+}
+
+// The basic-auth header value for a resolved credential.
+function authHeader({ email, token }) {
+  return `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`
+}
+
+const writeCredential = (file, site, email, token, deps) =>
+  store.writeKey(file, site, { email, token }, deps)
+const userForSite = (s, site) => store.userFor(s, site)
+const writeUser = (file, site, user, deps) => store.writeUser(file, site, user, deps)
+const removeUser = (file, site, deps) => store.removeUser(file, site, deps)
+const removeCredential = (file, site, deps) => store.removeKey(file, site, deps)
+const writeKeyCommand = (file, site, command, deps) =>
+  store.writeKeyCommand(file, site, command, deps, {
+    literalKeyRe: LITERAL_TOKEN_RE,
+    literalKeyAdvice: LITERAL_TOKEN_ADVICE,
+  })
+
+module.exports = {
+  storePath: kit.storePath,
+  readStore: kit.readStore,
+  storeMode: kit.storeMode,
+  fingerprint: kit.fingerprint,
+  resolveCredential,
+  authHeader,
+  siteOf,
+  writeCredential,
+  userForSite,
+  writeUser,
+  removeUser,
+  removeCredential,
+  writeKeyCommand,
+}

package/src/vendor/jira/dialect.js

@@ -0,0 +1,45 @@
+'use strict'
+
+/**
+ * The Jira Cloud dialect — how projections are shaped for, and read back from,
+ * a tracker that stores ADF rather than markdown.
+ *
+ * The ADF conversion itself lives in `adf.js` and is applied at the ADAPTER
+ * boundary (`api.js`): the engine only ever sees markdown text. What the
+ * dialect hooks carry (sync-core `src/dialect.js`):
+ *
+ *   - `canonicalize` — light markdown canonicalisation of the outbound
+ *     projection: bullet markers unify, trailing whitespace and blank runs
+ *     collapse. No emphasis surgery — ADF has no straddle mangle to defend
+ *     against; the renderer joins soft-wrapped lines itself.
+ *   - `flattenTables` — ADF's `listItem` cannot contain a `table` node, so a
+ *     table nested in a list item is re-shaped before it reaches the renderer
+ *     (shared with the Linear dialect — kit `src/md-tables.js`).
+ *   - `canonicalForCompare` — the shared markdown-form reduction (kit
+ *     `src/md-compare.js`): read-backs are our own `adfToText` rendering, which
+ *     re-emits `-` bullets, renumbered ordered lists and `| -- |` separators
+ *     whatever the source spelled, and the reduction makes exactly those
+ *     differences invisible.
+ */
+
+const { flattenNestedTables } = require('../provider-kit/src/md-tables.js')
+const { markdownCanonicalForCompare } = require('../provider-kit/src/md-compare.js')
+
+function canonicalizeMarkdown(text) {
+  if (text == null) return text
+  return String(text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+const dialect = Object.freeze({
+  canonicalize: canonicalizeMarkdown,
+  flattenTables: flattenNestedTables,
+  canonicalForCompare: markdownCanonicalForCompare,
+})
+
+module.exports = { dialect, canonicalizeMarkdown }

package/src/vendor/jira/mcp.js

@@ -0,0 +1,129 @@
+'use strict'
+
+/**
+ * The MCP transport: resolve the connected Atlassian MCP server's tool names
+ * at runtime and wrap them in the same op shapes `api.js` exposes, so the two
+ * transports are interchangeable where MCP can express the operation at all.
+ *
+ * Tool names are DISCOVERED, never hardcoded as a single truth: Atlassian's
+ * remote server (mcp.atlassian.com) names its tools one way today
+ * (`getJiraIssue`, `createJiraIssue`, `editJiraIssue`,
+ * `searchJiraIssuesUsingJql`, `transitionJiraIssue`, …) and a self-hosted
+ * bridge may spell them another. Each matcher is an ordered regex list;
+ * first advertised tool that matches wins.
+ *
+ * The engine itself never CALLS an MCP tool — the skill does, and hands
+ * results to the engine as files (the same `--workspace-states` /
+ * `--stored` idiom the Linear provider uses). This module exists so a skill
+ * can ask which tools to call and so `doctor` can report a usable server.
+ */
+
+const MATCHERS = {
+  issueRead: [/^getJiraIssue$/i, /\bget.*jira.*issue\b/i, /^get_issue$/i],
+  issueCreate: [/^createJiraIssue$/i, /\bcreate.*jira.*issue\b/i, /^create_issue$/i],
+  issueEdit: [/^editJiraIssue$/i, /\bedit.*jira.*issue\b/i, /^update_issue$/i],
+  issueSearch: [/^searchJiraIssuesUsingJql$/i, /\bsearch.*jira.*issues\b/i, /^search_issues$/i],
+  issueTransition: [/^transitionJiraIssue$/i, /\btransition.*jira.*issue\b/i],
+  transitionsList: [/^getTransitionsForJiraIssue$/i, /\btransitions?\b.*jira/i],
+  commentAdd: [/^addCommentToJiraIssue$/i, /\badd.*comment\b/i],
+  viewerRead: [/^atlassianUserInfo$/i, /\b(current|my)?.?user.?info\b/i, /^get_user$/i],
+  projectsList: [/^getVisibleJiraProjects$/i, /\bvisible.*projects\b/i, /^list_projects$/i],
+}
+
+// The minimum a server must offer for the MCP transport to be worth using at
+// all: reading an issue and creating one. Everything else degrades per-command.
+const REQUIRED = ['issueRead', 'issueCreate']
+
+/**
+ * Match the advertised tool list against the matchers.
+ * @param {string[]} toolNames what the connected server advertises
+ * @returns {{ ok: true, tools: Record<string,string> } | { ok: false, error, tools }}
+ */
+function discoverJira(toolNames) {
+  const names = (toolNames || []).filter((n) => typeof n === 'string')
+  const tools = {}
+  for (const [op, patterns] of Object.entries(MATCHERS)) {
+    for (const pattern of patterns) {
+      const hit = names.find((n) => pattern.test(n))
+      if (hit) {
+        tools[op] = hit
+        break
+      }
+    }
+  }
+  const missing = REQUIRED.filter((op) => !tools[op])
+  if (missing.length) {
+    return {
+      ok: false,
+      tools,
+      error:
+        `the connected MCP server is missing ${missing.join(' and ')} — ` +
+        `advertised ${names.length} tool(s), none matched. Is the Atlassian MCP server connected?`,
+    }
+  }
+  return { ok: true, tools }
+}
+
+/**
+ * Wrap a discovered tool set + a `call(toolName, args)` function into the op
+ * shapes the engine consumes. Ops the server cannot express are absent — the
+ * consumer feature-detects, exactly as with the API adapter's extras.
+ */
+function makeAdapter({ tools, call, siteUrl, projectKey }) {
+  const urlOf = (key) => (siteUrl ? `${String(siteUrl).replace(/\/+$/, '')}/browse/${key}` : null)
+  const normalize = (raw) => {
+    if (!raw || !raw.key) return null
+    const f = raw.fields || {}
+    return {
+      id: String(raw.id || raw.key),
+      identifier: raw.key,
+      url: urlOf(raw.key),
+      title: f.summary != null ? f.summary : null,
+      state: f.status ? { name: f.status.name } : null,
+    }
+  }
+
+  const adapter = {}
+  if (tools.issueRead) {
+    adapter.readIssue = async (keyOrId) => normalize(await call(tools.issueRead, { issueIdOrKey: String(keyOrId) }))
+  }
+  if (tools.issueCreate) {
+    adapter.createIssue = async ({ title, description }) =>
+      normalize(
+        await call(tools.issueCreate, {
+          projectKey,
+          issueTypeName: 'Task',
+          summary: title,
+          description,
+        }),
+      )
+    adapter.createSubIssue = async (parentId, { title, description }) =>
+      normalize(
+        await call(tools.issueCreate, {
+          projectKey,
+          issueTypeName: 'Subtask',
+          summary: title,
+          description,
+          parent: { id: String(parentId) },
+        }),
+      )
+  }
+  if (tools.issueEdit) {
+    adapter.updateIssue = async (keyOrId, updates) =>
+      call(tools.issueEdit, { issueIdOrKey: String(keyOrId), fields: updates })
+  }
+  if (tools.issueSearch) {
+    adapter.searchIssues = async ({ query, projectKey: pk }) =>
+      call(tools.issueSearch, {
+        jql: [pk || projectKey ? `project = "${pk || projectKey}"` : null, query ? `summary ~ "${String(query).replace(/(["\\])/g, '\\$1')}"` : null]
+          .filter(Boolean)
+          .join(' AND '),
+      })
+  }
+  if (tools.viewerRead) {
+    adapter.readViewer = async () => call(tools.viewerRead, {})
+  }
+  return adapter
+}
+
+module.exports = { discoverJira, makeAdapter, MATCHERS, REQUIRED }

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

@@ -0,0 +1,41 @@
+'use strict'
+
+/**
+ * Provider-neutral CLI plumbing shared by skitterspec ticketing providers.
+ *
+ * sync-core is the projection/plan/snapshot ENGINE — pure, no CLI, no network.
+ * This package is everything a provider\'s CLI builds around that engine and
+ * that a second provider would otherwise duplicate: config merging, the
+ * namespaced credentials store, identity resolution, the doctor report
+ * framework, released-range scanning, transport resolution, rate-limit-aware
+ * HTTP retry, spec resolution/listing, terminal secret input, and a flag
+ * parser with the unknown-flag refusal. Nothing in here names a tracker.
+ */
+
+const config = require('./src/config.js')
+const credentials = require('./src/credentials.js')
+const identity = require('./src/identity.js')
+const doctor = require('./src/doctor.js')
+const released = require('./src/released.js')
+const transport = require('./src/transport.js')
+const http = require('./src/http.js')
+const specs = require('./src/specs.js')
+const prompt = require('./src/prompt.js')
+const args = require('./src/args.js')
+const adapter = require('./src/adapter.js')
+const apply = require('./src/apply.js')
+
+module.exports = {
+  ...config,
+  ...credentials,
+  ...identity,
+  ...doctor,
+  ...released,
+  ...transport,
+  ...http,
+  ...specs,
+  ...prompt,
+  ...args,
+  ...adapter,
+  ...apply,
+}

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

@@ -0,0 +1,23 @@
+'use strict'
+
+/**
+ * The transport op-contract check: a provider's API adapter may ADD ops beyond
+ * its MCP adapter, but must never be missing one — consumers feature-detect the
+ * extras and assume the base set. Run it in the provider's own tests against
+ * both adapters, so the two transports cannot drift apart silently.
+ */
+
+// The function-valued op names an adapter exposes.
+function adapterOps(adapter) {
+  return Object.keys(adapter || {})
+    .filter((k) => typeof adapter[k] === 'function')
+    .sort()
+}
+
+// Which of `required` are absent from `adapter` — [] is the passing answer.
+function missingOps(required, adapter) {
+  const have = new Set(adapterOps(adapter))
+  return [].concat(required).filter((op) => !have.has(op))
+}
+
+module.exports = { adapterOps, missingOps }