@skitterbyte/skitterspec-linear 10.2.0 → 10.3.0

package/bin/skitterspec-linear.js

@@ -4,8 +4,13 @@
 /**
  * The Linear-provider distribution's bin — a superset of the base CLI.
  *
- * `spec-sync …` is handled here (the provider engine seam); every other command
- * (`init`, `update`, `spec-env`, `--help`, …) delegates to the base CLI unchanged.
+ * The provider's own commands are routed from ONE table (`src/commands.js`),
+ * which also generates their `--help` section; every other command (`init`,
+ * `update`, `spec-env`, …) delegates to the base CLI unchanged.
+ *
+ * `--help` is the exception that has to be handled here rather than delegated:
+ * the base prints its own HELP const, which cannot know what a provider adds, so
+ * delegating made this distribution report that `spec-sync` did not exist.
  */
 
 // This package's bin/, src/ and assets/ are COMPOSED by scripts/build-dist.js and
@@ -27,24 +32,33 @@ if (!existsSync(join(__dirname, '..', 'src'))) {
   process.exit(1)
 }
 
-const { run } = require('../src/cli.js')
-const { specSync } = require('../src/vendor/linear/cli-sync.js')
-const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')
+const { run, HELP } = require('../src/cli.js')
+const {
+  PROVIDER_COMMANDS,
+  providerHelpSection,
+} = require('../src/vendor/linear/commands.js')
 
 async function main(argv) {
   const [cmd, ...rest] = argv
-  if (cmd === 'spec-sync') {
-    // Propagate the exit code, like spec-sanitise below. Dropping it made
-    // `status --workspace-states` (a bad state name) and `stamp` (a refused
-    // write) both look successful to any caller checking $?, which is exactly
-    // what the /spec-push skill does before it applies a plan.
-    process.exitCode = await specSync(rest)
+
+  // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
+  // never the whole argv: `spec-sanitise --help` must reach that command's own
+  // help, not be swallowed by the top-level one.
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`${HELP}\n${providerHelpSection()}`)
     return
   }
-  if (cmd === 'spec-sanitise') {
-    process.exitCode = await specSanitise(rest)
+
+  const provider = PROVIDER_COMMANDS[cmd]
+  if (provider) {
+    // Propagate the exit code. Dropping it made `spec-sync status
+    // --workspace-states` (a bad state name) and `stamp` (a refused write) both
+    // look successful to any caller checking $?, which is exactly what the
+    // /spec-push skill does before it applies a plan.
+    process.exitCode = await provider.run(rest)
     return
   }
+
   await run(argv)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -48,6 +48,29 @@ const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
 
 const pkg = require('../package.json')
 
+// Commands this (tracker-free) base does NOT ship, and the distribution that
+// does. Without this the base says only "unknown command: spec-sync", which a
+// user correctly reads as "no such feature" — nothing anywhere named the
+// distribution that has it, so they were stranded. Naming Linear here is a
+// diagnostic string, not provider machinery: `init.js` already knows
+// `linear.config.json` and `linear-base/` by name in order to protect them.
+const PROVIDER_COMMANDS = {
+  'spec-sync': '@skitterbyte/skitterspec-linear',
+  'spec-sanitise': '@skitterbyte/skitterspec-linear',
+}
+
+function unknownCommand(cmd) {
+  const dist = PROVIDER_COMMANDS[cmd]
+  if (dist) {
+    return (
+      `unknown command: ${cmd} — this is the base distribution, which does not ` +
+      `ship it.\n  ${cmd} comes from ${dist} (a superset of this package): ` +
+      `install that instead.`
+    )
+  }
+  return `unknown command: ${cmd} (try --help)`
+}
+
 const HELP = `skitterspec — spec-driven-development for Claude Code
 
 Usage:
@@ -1384,8 +1407,8 @@ async function run(argv) {
       await cleanupReleaseTooling(dir, opts)
       break
     default:
-      throw new Error(`unknown command: ${cmd} (try --help)`)
+      throw new Error(unknownCommand(cmd))
   }
 }
 
-module.exports = { run, parse }
+module.exports = { run, parse, HELP, unknownCommand }

package/src/vendor/linear/cli-sync.js

@@ -158,8 +158,15 @@ function warnToErr(snapshotDir, config, err) {
   if (lines.length) err.write(lines.join('\n') + '\n')
 }
 
+// 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: /spec-push 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) return null
+  if (!specArg) {
+    out.write('spec-sync: no spec given\n')
+    return null
+  }
   const snapshotDir = resolveSnapshotDir(specArg, dir)
   if (!snapshotDir) {
     out.write(`spec-sync: spec not found: ${specArg}\n`)
@@ -171,7 +178,7 @@ function resolveOrExit(specArg, dir, out) {
 // `spec-sync normalize <spec>` — print the local projection as JSON.
 function specSyncNormalize(dir, config, specArg, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   // stdout is the projection and nothing else — callers pipe it into jq.
   warnToErr(snapshotDir, config, err)
   out.write(JSON.stringify(projectionOf(snapshotDir, config), null, 2) + '\n')
@@ -404,7 +411,7 @@ function specSyncStamp(dir, config, specArg, flags, out) {
 // files. The skill calls this AFTER applying the plan and stamping new ids.
 function specSyncRecord(dir, config, specArg, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   const identifier = specIdentifier(snapshotDir, config)
   const file = recordPush({ dir, snapshotDir, identifier, config })
   out.write(`spec-sync record: snapshot written → ${path.relative(dir, file)}\n`)
@@ -417,7 +424,7 @@ function specSyncRecord(dir, config, specArg, out) {
 // configured state names and fails loudly on a typo Linear would silently no-op.
 function specSyncStatus(dir, config, specArg, flags, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   const identifier = specIdentifier(snapshotDir, config)
   const lines = [`spec-sync status: ${identifier}`, ...warningLines(snapshotDir, config)]
 
@@ -1227,15 +1234,13 @@ async function specSync(rest, io = {}) {
 
   switch (sub) {
     case 'normalize':
-      specSyncNormalize(dir, config, positional[0], out, err)
-      return 0
+      return specSyncNormalize(dir, config, positional[0], out, err) || 0
     case 'push':
       return specSyncPush(dir, config, positional[0], flags, out, err) || 0
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
-      specSyncRecord(dir, config, positional[0], out)
-      return 0
+      return specSyncRecord(dir, config, positional[0], out) || 0
     case 'status':
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
     case 'projects':

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 }