@skitterbyte/skitterspec-linear 10.1.0 → 10.3.0

package/src/vendor/linear/commands.js

@@ -0,0 +1,54 @@
+'use strict'
+
+/**
+ * The commands this provider distribution adds on top of the base CLI.
+ *
+ * ONE table drives both routing and `--help`. That pairing is the point: the bug
+ * this fixes was `spec-sync` being routed by the bin while the base's `HELP`
+ * const knew nothing about it, so the one distribution that ships the command
+ * told users it did not exist. Anything added here is routed and documented in
+ * the same edit — the two cannot drift, and a test asserts it.
+ *
+ * `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 { specSanitise } = require('./cli-sanitise.js')
+
+const DIST = '@skitterbyte/skitterspec-linear'
+
+const PROVIDER_COMMANDS = {
+  'spec-sync': {
+    run: specSync,
+    usage: 'skitterspec spec-sync <cmd>',
+    summary:
+      'One-way sync to Linear (repo -> tracker; opt-in, needs\n' +
+      'specs/.core/linear.config.json). Run it with no args to\n' +
+      'list its subcommands.',
+  },
+  'spec-sanitise': {
+    run: specSanitise,
+    usage: 'skitterspec spec-sanitise',
+    summary:
+      'Rewrite spec markdown so no emphasis or link straddles a\n' +
+      'line break. Dry-run; --write to apply.',
+  },
+}
+
+// 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/linear/config.js

@@ -17,7 +17,7 @@
  * Shape (see assets/core/linear.config.md for field docs):
  *   {
  *     linear:   { teamKey, teamId, projectId },
- *     intake:   { label, bugLabels },
+ *     intake:   { label, bugLabels, hotfixLabels },
  *     mapping:  { specFolder, phases, tasks },
  *     states:   { backlog, "in-progress", complete, cancelled },
  *     snapshot: { overviewFile },
@@ -53,7 +53,30 @@ const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
 //              already carries an id keeps projecting either way — one-way sync
 //              has no delete, so withholding a LINKED sub-issue would freeze it
 //              in the tracker rather than remove it.
-const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred'])
+//   inline   — never: each phase becomes a SECTION of the spec issue's own
+//              description instead, and the `## Phases` index stays as its table
+//              of contents. For work nobody will pick up phase by phase — 250
+//              finished specs are 250 issues worth reading and 669 sub-issues
+//              worth nobody's attention. Keeps an already-linked phase's
+//              sub-issue for the same reason `deferred` does.
+//
+// `mapping.phases` takes one of these as a scalar (one mode for the whole repo)
+// OR a map keyed by lifecycle bucket — `{ "backlog": "subissue", "complete":
+// "deferred" }` — because a repo can want assignable sub-issues for work in
+// flight and something else entirely for work that finished long ago. A bucket
+// the map omits gets DEFAULT_PHASE_MODE, so a partial map adds an exception
+// rather than silently suppressing phases everywhere it is silent.
+const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
+const DEFAULT_PHASE_MODE = 'subissue'
+
+// How `spec-sync apply` reaches Linear. `api` talks to the GraphQL API directly;
+// `mcp` prints the plan for the skill to apply over MCP, as it always has.
+const TRANSPORTS = Object.freeze(['api', 'mcp'])
+
+// The environment variable a Linear personal API key is read from, unless
+// `auth.keyEnv` names another. The config names the VARIABLE, never the key —
+// nothing secret is ever written to the repo.
+const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
 
 const DEFAULT_CONFIG = Object.freeze({
   // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
@@ -65,14 +88,18 @@ const DEFAULT_CONFIG = Object.freeze({
   linear: Object.freeze({ teamKey: '', teamId: '', projectId: '' }),
   // Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
   // inbox filter — issues carrying it are what the web app files; `bugLabels`
-  // route an issue to `/spec-bug` instead of `/spec`. Both empty = no inbox to
-  // browse (a bare issue ref still works) and no bug routing.
-  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]) }),
+  // route an issue to `/spec-bug` instead of `/spec`, and `hotfixLabels` route it
+  // to `/spec-hotfix` — a bug that has to be patched on the released version, not
+  // fixed on main. All empty = no inbox to browse (a bare issue ref still works)
+  // and no routing. `hotfixLabels` wins over `bugLabels` on an issue carrying
+  // both: production is the more specific destination, and the cost of getting it
+  // wrong is asymmetric — a fix that lands only on main never reaches prod.
+  intake: Object.freeze({ label: '', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]) }),
   // A spec is a Linear ISSUE; each phase is a SUB-ISSUE of it; tasks are not
   // synced (they live only in the repo phase files).
   // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
   // phase's checkboxes reach that sub-issue's description — see TASK_MAPPINGS.
-  mapping: Object.freeze({ specFolder: 'issue', phases: 'subissue', tasks: 'checklist' }),
+  mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist' }),
   // Linear ISSUE workflow-state names — the spec issue's state (from the folder
   // bucket) and each sub-issue's state (from the phase emoji) both map through
   // this one table. They must match the workspace's issue states exactly;
@@ -85,6 +112,12 @@ const DEFAULT_CONFIG = Object.freeze({
   }),
   snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
   branch: Object.freeze({ pattern: '{type}/{slug}' }),
+  // `keyEnv` names the env var holding the personal API key. It is a NAME, not a
+  // key: putting the secret itself here would commit it.
+  auth: Object.freeze({ keyEnv: DEFAULT_KEY_ENV }),
+  // `transport` is the default for `spec-sync apply --via`. Empty means "decide
+  // at run time": use the API when a key is present, MCP when it isn't.
+  apply: Object.freeze({ transport: '' }),
   sync: Object.freeze({
     baseDir: 'specs/.core/linear-base',
     backupDir: 'specs/.core/linear-backups',
@@ -108,6 +141,11 @@ const DEFAULT_CONFIG = Object.freeze({
   }),
 })
 
+// The lifecycle buckets a per-bucket `mapping.phases` map may key on. Derived
+// from `states` rather than restated: both maps key on the spec's folder bucket,
+// so they cannot drift apart.
+const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
+
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -116,11 +154,17 @@ function isObject(value) {
 function defaults() {
   return {
     linear: { ...DEFAULT_CONFIG.linear },
-    intake: { label: DEFAULT_CONFIG.intake.label, bugLabels: [...DEFAULT_CONFIG.intake.bugLabels] },
+    intake: {
+      label: DEFAULT_CONFIG.intake.label,
+      bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
+      hotfixLabels: [...DEFAULT_CONFIG.intake.hotfixLabels],
+    },
     mapping: { ...DEFAULT_CONFIG.mapping },
     states: { ...DEFAULT_CONFIG.states },
     snapshot: { ...DEFAULT_CONFIG.snapshot },
     branch: { ...DEFAULT_CONFIG.branch },
+    auth: { ...DEFAULT_CONFIG.auth },
+    apply: { ...DEFAULT_CONFIG.apply },
     sync: {
       baseDir: DEFAULT_CONFIG.sync.baseDir,
       backupDir: DEFAULT_CONFIG.sync.backupDir,
@@ -164,6 +208,47 @@ function mergeFieldOwnership(base, parsed) {
   }
 }
 
+// Merge (and validate) `mapping.phases` in either of its two forms: a scalar
+// mode for the whole repo, or a map of lifecycle bucket → mode. Loud on a bad
+// key or value, like fieldOwnership and mapping.tasks — a misspelt bucket would
+// otherwise read as a deliberate default and go on minting the sub-issues the
+// config was written to stop.
+function mergePhaseMapping(base, parsed) {
+  const value = parsed.phases
+  if (typeof value === 'string') {
+    if (value.trim()) base.phases = value.trim()
+  } else if (isObject(value)) {
+    const byBucket = {}
+    for (const [bucket, mode] of Object.entries(value)) {
+      if (!LIFECYCLE_BUCKETS.includes(bucket)) {
+        throw new Error(
+          `Invalid ${CONFIG_FILE}: mapping.phases.${bucket} is not a lifecycle bucket ` +
+            `(expected one of ${LIFECYCLE_BUCKETS.join('|')})`,
+        )
+      }
+      if (!PHASE_MAPPINGS.includes(mode)) {
+        throw new Error(
+          `Invalid ${CONFIG_FILE}: mapping.phases.${bucket} = ${JSON.stringify(mode)} ` +
+            `(expected one of ${PHASE_MAPPINGS.join('|')})`,
+        )
+      }
+      byBucket[bucket] = mode
+    }
+    base.phases = byBucket
+  } else if (value !== undefined) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(value)} ` +
+        `(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
+    )
+  }
+  if (typeof base.phases === 'string' && !PHASE_MAPPINGS.includes(base.phases)) {
+    throw new Error(
+      `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.phases)} ` +
+        `(expected one of ${PHASE_MAPPINGS.join('|')}, or a map of lifecycle bucket to mode)`,
+    )
+  }
+}
+
 // Merge (and validate) sync.keyedFields. Each value is the item's id property
 // name (a non-empty string); a field listed here is compared per item.
 function mergeKeyedFields(base, parsed) {
@@ -197,11 +282,13 @@ function mergeConfig(base, parsed) {
     if (Array.isArray(parsed.intake.bugLabels)) {
       base.intake.bugLabels = stringList(parsed.intake.bugLabels)
     }
+    if (Array.isArray(parsed.intake.hotfixLabels)) {
+      base.intake.hotfixLabels = stringList(parsed.intake.hotfixLabels)
+    }
   }
 
   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')
     // Loud on a typo, like fieldOwnership above. Quietly falling back would make
     // a misspelt value look like a deliberate `none` — the same silent
@@ -212,12 +299,7 @@ function mergeConfig(base, parsed) {
           `(expected one of ${TASK_MAPPINGS.join('|')})`,
       )
     }
-    if (!PHASE_MAPPINGS.includes(base.mapping.phases)) {
-      throw new Error(
-        `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.mapping.phases)} ` +
-          `(expected one of ${PHASE_MAPPINGS.join('|')})`,
-      )
-    }
+    mergePhaseMapping(base.mapping, parsed.mapping)
   }
 
   if (isObject(parsed.states)) {
@@ -234,6 +316,22 @@ function mergeConfig(base, parsed) {
     assign(base.branch, parsed.branch, 'pattern', 'string')
   }
 
+  if (isObject(parsed.auth)) {
+    assign(base.auth, parsed.auth, 'keyEnv', 'string')
+  }
+
+  if (isObject(parsed.apply)) {
+    assign(base.apply, parsed.apply, 'transport', 'string?')
+    // Loud on a typo, like the mapping enums: a misspelt transport must not
+    // quietly fall back to MCP and look like a deliberate choice.
+    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')
@@ -279,9 +377,13 @@ function loadLinearConfig(dir = process.cwd()) {
 module.exports = {
   loadLinearConfig,
   mergeConfig,
+  defaults,
   DEFAULT_CONFIG,
   CONFIG_FILE,
   OWNERSHIP,
   TASK_MAPPINGS,
   PHASE_MAPPINGS,
+  LIFECYCLE_BUCKETS,
+  TRANSPORTS,
+  DEFAULT_KEY_ENV,
 }