@skitterbyte/skitterspec-linear 10.0.1 → 10.2.0

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 },
@@ -44,6 +44,40 @@ const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
 // box ticked in the tracker is overwritten by the next push.
 const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
 
+// When a phase becomes a sub-issue.
+//   subissue — always, from the spec's first push (default)
+//   deferred — only once the work starts: a spec sitting in `backlog` (or
+//              `cancelled` without ever having started) projects the issue
+//              alone, so adopting sync on a long backlog costs one call per
+//              spec instead of one per spec PLUS one per phase. A phase that
+//              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.
+//   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
   // first `/spec-push` offer the team's projects and pre-select this one; empty
@@ -54,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;
@@ -74,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',
@@ -97,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)
 }
@@ -105,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,
@@ -153,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) {
@@ -186,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
@@ -201,6 +299,7 @@ function mergeConfig(base, parsed) {
           `(expected one of ${TASK_MAPPINGS.join('|')})`,
       )
     }
+    mergePhaseMapping(base.mapping, parsed.mapping)
   }
 
   if (isObject(parsed.states)) {
@@ -217,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')
@@ -262,8 +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,
 }

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

@@ -7,7 +7,10 @@
  * 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 or merged.
+ * 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 { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions } = require('./src/normalize.js')
@@ -17,6 +20,8 @@ const { push, recordPush, projectionOf } = require('./src/push.js')
 const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 const { detectLegacyMirror } = require('./src/legacy.js')
+const { compareStored } = require('./src/verify.js')
+const { flattenNestedTables } = require('./src/tables.js')
 
 module.exports = {
   normalizeLocal,
@@ -44,4 +49,6 @@ module.exports = {
   listPhaseFiles,
   sanitizeSpecMarkdown,
   detectLegacyMirror,
+  compareStored,
+  flattenNestedTables,
 }