@skitterbyte/skitterspec-jira 0.0.0-stage → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/MIGRATION.md +1126 -0
  2. package/README.md +42 -2
  3. package/assets/claude-md-section.md +85 -0
  4. package/assets/commands/allow-main.md +33 -0
  5. package/assets/commands/spec-connect.md +13 -0
  6. package/assets/commands/spec-live.md +14 -0
  7. package/assets/commands/spec-remote-review.md +37 -0
  8. package/assets/commands/spec-skip.md +24 -0
  9. package/assets/core/SETUP.md +192 -0
  10. package/assets/core/env.config.json.example +56 -0
  11. package/assets/core/env.config.md +606 -0
  12. package/assets/core/gating.config.json.example +4 -0
  13. package/assets/core/gating.config.md +81 -0
  14. package/assets/core/jira.config.json.example +18 -0
  15. package/assets/core/jira.config.md +61 -0
  16. package/assets/hooks/main-guard.cjs +162 -0
  17. package/assets/hooks/review-gate.cjs +146 -0
  18. package/assets/review/page.html +3384 -0
  19. package/assets/rules/commit-trailers.md +96 -0
  20. package/assets/rules/negative-checks.md +69 -0
  21. package/assets/rules/offered-unblocks.md +100 -0
  22. package/assets/rules/spec-planning.md +692 -0
  23. package/assets/rules/spec-reports.md +572 -0
  24. package/assets/skills/no-spec/SKILL.md +249 -0
  25. package/assets/skills/spec/SKILL.md +714 -0
  26. package/assets/skills/spec-bug/SKILL.md +585 -0
  27. package/assets/skills/spec-cancel/SKILL.md +261 -0
  28. package/assets/skills/spec-complete/SKILL.md +451 -0
  29. package/assets/skills/spec-diff/SKILL.md +870 -0
  30. package/assets/skills/spec-hotfix/SKILL.md +607 -0
  31. package/assets/skills/spec-init/SKILL.md +178 -0
  32. package/assets/skills/spec-jira-setup/SKILL.md +220 -0
  33. package/assets/skills/spec-list/SKILL.md +173 -0
  34. package/assets/skills/spec-next/SKILL.md +678 -0
  35. package/assets/skills/spec-push/SKILL.md +306 -0
  36. package/assets/skills/spec-review/SKILL.md +256 -0
  37. package/assets/skills/spec-reviewed/SKILL.md +284 -0
  38. package/assets/skills/spec-start/SKILL.md +496 -0
  39. package/assets/skills/spec-status/SKILL.md +112 -0
  40. package/assets/skills/spec-sync/SKILL.md +218 -0
  41. package/assets/skills/spec-to-main/SKILL.md +141 -0
  42. package/bin/skitterspec-jira.js +68 -0
  43. package/package.json +40 -4
  44. package/src/cli.js +5967 -0
  45. package/src/deprecate.js +138 -0
  46. package/src/env/bootstrap.js +188 -0
  47. package/src/env/building.js +143 -0
  48. package/src/env/classify.js +176 -0
  49. package/src/env/commitcmd.js +108 -0
  50. package/src/env/config.js +850 -0
  51. package/src/env/dev.js +63 -0
  52. package/src/env/glob.js +34 -0
  53. package/src/env/hooks.js +226 -0
  54. package/src/env/hotfix.js +413 -0
  55. package/src/env/hotfixland.js +302 -0
  56. package/src/env/integrate.js +167 -0
  57. package/src/env/live.js +479 -0
  58. package/src/env/mainguard.js +299 -0
  59. package/src/env/provision.js +466 -0
  60. package/src/env/proxy.js +225 -0
  61. package/src/env/prune.js +119 -0
  62. package/src/env/registry.js +159 -0
  63. package/src/env/render.js +17 -0
  64. package/src/env/resolve.js +716 -0
  65. package/src/env/review.js +2622 -0
  66. package/src/env/reviewers/coderabbit.js +228 -0
  67. package/src/env/reviewers.js +517 -0
  68. package/src/env/serve.js +1044 -0
  69. package/src/env/supervise.js +157 -0
  70. package/src/env/teardown.js +248 -0
  71. package/src/env/trust.js +87 -0
  72. package/src/gating.js +155 -0
  73. package/src/init.js +1150 -0
  74. package/src/lines-diff.js +114 -0
  75. package/src/prompts.js +129 -0
  76. package/src/vendor/jira/adf.js +414 -0
  77. package/src/vendor/jira/api.js +295 -0
  78. package/src/vendor/jira/cli-sync.js +1256 -0
  79. package/src/vendor/jira/commands.js +44 -0
  80. package/src/vendor/jira/config.js +296 -0
  81. package/src/vendor/jira/credentials.js +108 -0
  82. package/src/vendor/jira/dialect.js +45 -0
  83. package/src/vendor/jira/mcp.js +129 -0
  84. package/src/vendor/provider-kit/index.js +41 -0
  85. package/src/vendor/provider-kit/src/adapter.js +23 -0
  86. package/src/vendor/provider-kit/src/apply.js +207 -0
  87. package/src/vendor/provider-kit/src/args.js +68 -0
  88. package/src/vendor/provider-kit/src/assignment.js +277 -0
  89. package/src/vendor/provider-kit/src/config.js +198 -0
  90. package/src/vendor/provider-kit/src/credentials.js +404 -0
  91. package/src/vendor/provider-kit/src/doctor.js +35 -0
  92. package/src/vendor/provider-kit/src/http.js +63 -0
  93. package/src/vendor/provider-kit/src/identity.js +93 -0
  94. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  95. package/src/vendor/provider-kit/src/md-tables.js +94 -0
  96. package/src/vendor/provider-kit/src/prompt.js +50 -0
  97. package/src/vendor/provider-kit/src/released.js +269 -0
  98. package/src/vendor/provider-kit/src/releases.js +595 -0
  99. package/src/vendor/provider-kit/src/specs.js +166 -0
  100. package/src/vendor/provider-kit/src/transport.js +22 -0
  101. package/src/vendor/sync-core/index.js +93 -0
  102. package/src/vendor/sync-core/src/base.js +81 -0
  103. package/src/vendor/sync-core/src/compare.js +338 -0
  104. package/src/vendor/sync-core/src/dialect.js +51 -0
  105. package/src/vendor/sync-core/src/fields.js +36 -0
  106. package/src/vendor/sync-core/src/legacy.js +100 -0
  107. package/src/vendor/sync-core/src/normalize.js +998 -0
  108. package/src/vendor/sync-core/src/push.js +85 -0
  109. package/src/vendor/sync-core/src/retarget.js +278 -0
  110. package/src/vendor/sync-core/src/task-block.js +308 -0
  111. package/src/vendor/sync-core/src/verify.js +67 -0
  112. package/src/vendor/sync-core/src/write.js +191 -0
@@ -0,0 +1,166 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Spec resolution and listing for a provider CLI — how a spec argument becomes
5
+ * a snapshot directory, how a spec names its snapshot sidecar, and which specs
6
+ * a repo holds with which tracker links.
7
+ *
8
+ * The frontmatter key that links a spec is the provider's
9
+ * (`config.fields.identifier` — sync-core `src/fields.js`); everything else
10
+ * here is filesystem shape shared by every provider. `program` prefixes the
11
+ * user-facing refusals (`spec-sync: spec not found: …`).
12
+ */
13
+
14
+ const fs = require('node:fs')
15
+ const path = require('node:path')
16
+
17
+ const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
18
+ const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
19
+
20
+ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
21
+ // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder
22
+ // found under specs/** (preferred) or a literal path to a snapshot directory.
23
+ function resolveSnapshotDir(specArg, dir) {
24
+ const found = findSpecFolder(specArg, dir)
25
+ if (found) return found.path
26
+ const literal = path.resolve(dir, specArg)
27
+ if (fs.existsSync(literal) && fs.statSync(literal).isDirectory()) return literal
28
+ return null
29
+ }
30
+
31
+ // The identifier keying the snapshot sidecar: the spec's stamped identifier
32
+ // if set, else its folder name (so the engine is usable before a spec is
33
+ // linked).
34
+ function specIdentifier(snapshotDir, config) {
35
+ const field = fieldsOf(config).identifier
36
+ try {
37
+ const { frontmatter } = readSnapshot(snapshotDir, config)
38
+ if (frontmatter[field]) return String(frontmatter[field])
39
+ } catch {
40
+ /* fall through to folder name */
41
+ }
42
+ return path.basename(snapshotDir)
43
+ }
44
+
45
+ // Read a spec's stamped identifier without throwing: an unlinked spec, an
46
+ // unreadable file and a spec with no frontmatter all read as `null`.
47
+ function linkedIdentifier(overviewPath, config) {
48
+ const field = fieldsOf(config).identifier
49
+ let raw
50
+ try {
51
+ raw = fs.readFileSync(overviewPath, 'utf-8')
52
+ } catch {
53
+ return null
54
+ }
55
+ const { data } = parseFrontmatter(raw)
56
+ return data[field] ? String(data[field]) : null
57
+ }
58
+
59
+ // Every spec under specs/<bucket>/, paired with the tracker issue it is
60
+ // linked to (`null` when it has never been pushed). Folder specs read
61
+ // `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
62
+ // itself. Sorted for stable output.
63
+ function listSpecs(dir, config) {
64
+ const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
65
+ const specs = []
66
+ for (const bucket of BUCKETS) {
67
+ const root = path.join(dir, 'specs', bucket)
68
+ let entries
69
+ try {
70
+ entries = fs.readdirSync(root, { withFileTypes: true })
71
+ } catch {
72
+ continue
73
+ }
74
+ for (const entry of entries) {
75
+ let name
76
+ let overviewPath
77
+ if (entry.isDirectory()) {
78
+ name = entry.name
79
+ overviewPath = path.join(root, name, overviewFile)
80
+ } else if (entry.isFile() && entry.name.endsWith('.md')) {
81
+ name = entry.name.slice(0, -3)
82
+ overviewPath = path.join(root, entry.name)
83
+ } else {
84
+ continue
85
+ }
86
+ specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
87
+ }
88
+ }
89
+ return specs.sort((a, b) => a.spec.localeCompare(b.spec))
90
+ }
91
+
92
+ // Resolve a spec argument to its folder, or null with a message on stdout.
93
+ // EVERY failure path here must print and EVERY caller must return a non-zero
94
+ // code: a push skill checks $? before it applies a plan, so a resolve failure
95
+ // that exits 0 reads as "nothing to do" rather than "I could not find the
96
+ // spec".
97
+ function resolveOrExit(specArg, dir, out) {
98
+ if (!specArg) {
99
+ out.write(`${program}: no spec given\n`)
100
+ return null
101
+ }
102
+ const snapshotDir = resolveSnapshotDir(specArg, dir)
103
+ if (!snapshotDir) {
104
+ out.write(`${program}: spec not found: ${specArg}\n`)
105
+ return null
106
+ }
107
+ return snapshotDir
108
+ }
109
+
110
+ // Phase-status warnings for a spec, one formatted line each. A spec states
111
+ // each phase's status three times and only the h1 emoji is read — get it
112
+ // wrong and the phase projects as `backlog`, pushes cleanly, and is recorded
113
+ // as intended: invisible. Reported by every subcommand that reads a
114
+ // projection, fatal in none — a legacy spec must still push.
115
+ function warningLines(snapshotDir, config) {
116
+ return lintPhases(snapshotDir, config).map((w) => ` warning ${w.file}: ${w.message}`)
117
+ }
118
+
119
+ // Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
120
+ function warnToErr(snapshotDir, config, err) {
121
+ const lines = warningLines(snapshotDir, config)
122
+ if (lines.length) err.write(lines.join('\n') + '\n')
123
+ }
124
+
125
+ // Render the read-back comparison — the same check `verify` and `apply`
126
+ // both report through, so the two cannot disagree about what "intact" means.
127
+ function verifyLines(snapshotDir, config, stored, identifier) {
128
+ const projection = projectionOf(snapshotDir, config)
129
+ const checks = []
130
+ if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
131
+ for (const [ref, text] of Object.entries(stored.subIssues || {})) {
132
+ const sub = projection.subIssues.find((s) => s.ref === ref)
133
+ if (!sub) {
134
+ checks.push([`sub-issue ${ref}`, null, text])
135
+ continue
136
+ }
137
+ checks.push([`sub-issue ${ref}`, sub.goal, text])
138
+ }
139
+
140
+ const lines = [`${program} verify: ${identifier}`]
141
+ let bad = 0
142
+ for (const [label, sent, got] of checks) {
143
+ if (sent == null) {
144
+ lines.push(` ?? ${label}: read back, but the projection has no such phase — stale ref?`)
145
+ bad++
146
+ continue
147
+ }
148
+ const r = compareStored(sent, got, config)
149
+ if (r.ok) continue
150
+ bad++
151
+ lines.push(
152
+ ` !! ${label}: the tracker stored different text — ${Math.abs(r.lost)} character(s) ` +
153
+ `${r.lost > 0 ? 'lost' : 'added'}, first difference at ${r.at}`,
154
+ ` sent: …${r.sentContext}…`,
155
+ ` stored: …${r.storedContext}…`,
156
+ )
157
+ }
158
+ if (!bad) lines.push(` ${checks.length} description(s) round-tripped intact`)
159
+ else lines.push(' the repo is unchanged and still correct; re-push to overwrite the mirror')
160
+ return lines
161
+ }
162
+
163
+ return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
164
+ }
165
+
166
+ module.exports = { makeSpecHelpers }
@@ -0,0 +1,22 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Which transport a command runs over: `--via` wins, else the config's
5
+ * declared default, else "api when a credential resolved, mcp when it didn't".
6
+ *
7
+ * This expression was repeated verbatim nine times in the first provider —
8
+ * hoisted so the precedence is decided once. Per-command DEGRADATION stays with
9
+ * the command: which operations are impossible over mcp (exit 1, say so) and
10
+ * which hand the skill instructions (exit 0) is a per-command judgment, not a
11
+ * transport fact.
12
+ */
13
+
14
+ function resolveTransport(flags, config, credentialOk) {
15
+ return (
16
+ (flags && flags.via) ||
17
+ (config && config.apply && config.apply.transport) ||
18
+ (credentialOk ? 'api' : 'mcp')
19
+ )
20
+ }
21
+
22
+ module.exports = { resolveTransport }
@@ -0,0 +1,93 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Provider-neutral one-way sync engine (repo → tracker).
5
+ *
6
+ * Every function is parameterised by a plain `config` object — it knows nothing
7
+ * about any specific tracker. The repo is the source of truth: the engine builds
8
+ * a local projection, diffs it against a committed last-pushed snapshot
9
+ * (`planChanges`), and returns a create/update plan the provider skill applies
10
+ * over its API. No remote content is read for CONTENT: nothing the tracker holds
11
+ * ever feeds the projection, the snapshot, or a repo file. `compareStored` is the
12
+ * one function that looks at a tracker value, and it only checks that what was
13
+ * stored matches what was sent — it merges nothing (see `src/verify.js`).
14
+ */
15
+
16
+ const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
17
+ const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
18
+ const { readBase, writeBase } = require('./src/base.js')
19
+ const { push, recordPush, projectionOf } = require('./src/push.js')
20
+ const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
21
+ const { detectLegacyMirror } = require('./src/legacy.js')
22
+ const { compareStored, stream } = require('./src/verify.js')
23
+ const { identityDialect, dialectOf } = require('./src/dialect.js')
24
+ const { fieldsOf } = require('./src/fields.js')
25
+ const { renderTaskBlock, findTaskBlocks, wrapEmphasisAware, collapseHyphenAware, inferWidth, fenceMask, DEFAULT_WIDTH } = require('./src/task-block.js')
26
+ const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
27
+
28
+ module.exports = {
29
+ ownsField,
30
+ normalizeLocal,
31
+ // Exported for `spec-sync list`: an `inline`-mode spec has no phase sub-issues
32
+ // to read, so the listing must resolve the mode rather than assume `subissue`.
33
+ phaseModeFor,
34
+ lintPhases,
35
+ readSnapshot,
36
+ parseFrontmatter,
37
+ projectionOf,
38
+ planChanges,
39
+ snapshotOf,
40
+ isEmptyPlan,
41
+ push,
42
+ recordPush,
43
+ remoteWorkflowState,
44
+ titleFromText,
45
+ validateStates,
46
+ stateSuggestions,
47
+ stageForState,
48
+ remoteStage,
49
+ LADDER_ORIGIN_BUCKET,
50
+ hashField,
51
+ stableStringify,
52
+ readBase,
53
+ writeBase,
54
+ writeFrontmatter,
55
+ deleteFrontmatter,
56
+ stampSubIssueId,
57
+ stampIssueId,
58
+ findPhaseFileByTitle,
59
+ listPhaseFiles,
60
+ detectLegacyMirror,
61
+ compareStored,
62
+ // The tolerant reduction behind both `compareStored` and the snapshot's
63
+ // `descriptionStream` hash — exported so a provider can reduce a read-back the
64
+ // same way rather than writing a second one that disagrees.
65
+ stream,
66
+ // Did someone else edit the tracker's description since the last push?
67
+ // Three-valued; `null` is cannot-tell and must never be reported as drift.
68
+ remoteDescriptionEdited,
69
+ remoteSubIssueEdited,
70
+ // Provider seams: the frontmatter field vocabulary and the markdown dialect
71
+ // a provider's config supplies (`config.fields` / `config.dialect`).
72
+ fieldsOf,
73
+ identityDialect,
74
+ dialectOf,
75
+ // The lifecycle buckets, exported once so providers and tests stop growing
76
+ // private copies (the tracker-free common package keeps its own — it cannot
77
+ // depend on this package).
78
+ LIFECYCLE_BUCKETS,
79
+ // Task-block helpers a provider's own text tooling builds on (the Linear
80
+ // sanitiser reflows emphasis-aware with these).
81
+ renderTaskBlock,
82
+ findTaskBlocks,
83
+ wrapEmphasisAware,
84
+ collapseHyphenAware,
85
+ inferWidth,
86
+ fenceMask,
87
+ DEFAULT_WIDTH,
88
+ planRetarget,
89
+ applyRetarget,
90
+ deriveRecordedKey,
91
+ isEmptyRetarget,
92
+ dirtyPaths,
93
+ }
@@ -0,0 +1,81 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The committed **last-pushed snapshot** sidecar.
5
+ *
6
+ * One-way sync (repo → Linear) records what it last pushed per spec at
7
+ * `{sync.baseDir}/{identifier}.base.json`, committed so each worktree carries its
8
+ * own snapshot. The snapshot is a set of content hashes
9
+ * (`{ issue, subIssues: {id:hash} }`, see compare.js
10
+ * `snapshotOf`); `planChanges` diffs the current projection against it to decide
11
+ * create/update/skip — no remote read. After a successful push the engine
12
+ * rewrites it (`writeBase`). Generic JSON read/write; the shape is the caller's.
13
+ */
14
+
15
+ const fs = require('node:fs')
16
+ const path = require('node:path')
17
+
18
+ function baseFile(dir, identifier, config) {
19
+ return path.join(dir, config.sync.baseDir, `${identifier}.base.json`)
20
+ }
21
+
22
+ /**
23
+ * Read a spec's committed base. Returns the parsed object, or `null` when no base
24
+ * exists yet (never synced) — the compare treats null as "no prior state".
25
+ */
26
+ function readBase(dir, identifier, config) {
27
+ const file = baseFile(dir, identifier, config)
28
+ let raw
29
+ try {
30
+ raw = fs.readFileSync(file, 'utf-8')
31
+ } catch (error) {
32
+ if (error.code === 'ENOENT') return null
33
+ throw error
34
+ }
35
+ try {
36
+ return JSON.parse(raw)
37
+ } catch (error) {
38
+ throw new Error(`Invalid base ${path.relative(dir, file)}: ${error.message}`)
39
+ }
40
+ }
41
+
42
+ /**
43
+ * Rewrite a spec's committed base with the freshly-synced field set. Creates
44
+ * `{sync.baseDir}` if needed. Returns the absolute path written.
45
+ */
46
+ function writeBase(dir, identifier, config, data) {
47
+ const file = baseFile(dir, identifier, config)
48
+ fs.mkdirSync(path.dirname(file), { recursive: true })
49
+ fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
50
+ return file
51
+ }
52
+
53
+ /**
54
+ * Back up the about-to-be-clobbered `side` ('local' | 'remote') into
55
+ * `{sync.backupDir}` before a --force. `timestamp` is caller-supplied (the engine
56
+ * never reads the clock); the name is made collision-safe with a `-N` counter.
57
+ * Returns the absolute path written, or null when `data` is nullish (nothing to
58
+ * back up — e.g. forcing a pull with no prior remote).
59
+ */
60
+ function backup(side, dir, identifier, config, { timestamp, data }) {
61
+ if (data == null) return null
62
+ const backupRoot = path.join(dir, config.sync.backupDir)
63
+ fs.mkdirSync(backupRoot, { recursive: true })
64
+
65
+ const stem = `${identifier}.${side}.${timestamp}`
66
+ let file = path.join(backupRoot, `${stem}.json`)
67
+ let n = 1
68
+ while (fs.existsSync(file)) {
69
+ file = path.join(backupRoot, `${stem}-${n}.json`)
70
+ n += 1
71
+ }
72
+ fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
73
+ return file
74
+ }
75
+
76
+ module.exports = {
77
+ readBase,
78
+ writeBase,
79
+ backup,
80
+ baseFile,
81
+ }