@fission-ai/openspec 1.15.0 → 1.16.1

package/dist/core/version-check.js

@@ -57,15 +57,21 @@ function standaloneUpgradeCommand() {
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
  * same privacy signals telemetry already honors — a user who set DO_NOT_TRACK
  * or telemetry.enabled false did not agree to a different outbound request.
+ *
+ * `requested` is an explicit `openspec version --check`: the user asked for
+ * this one request, so neither the telemetry signals nor CI detection apply
+ * to it. Only the update-check opt-out and the test guard still stop it.
  */
-function isCheckEnabled() {
+function isCheckEnabled(requested) {
     if (process.env.OPENSPEC_NO_UPDATE_CHECK !== undefined)
         return false;
-    if (isTelemetryOptedOutByEnv())
+    if (process.env.NODE_ENV === 'test')
         return false;
+    if (requested)
+        return true;
     if (isCiEnvironment())
         return false;
-    if (process.env.NODE_ENV === 'test')
+    if (isTelemetryOptedOutByEnv())
         return false;
     // Same config opt-out as telemetry (env remains the hard override above).
     if (getGlobalConfig().telemetry?.enabled === false)
@@ -180,40 +186,28 @@ export function compareVersions(a, b) {
     return comparePrerelease(left.prerelease, right.prerelease);
 }
 /**
- * Reads the `latest` dist-tag. Sends no custom Accept header: the registry
- * answers `/<pkg>/latest` with 406 for npm's abbreviated-metadata type, which
- * it only serves on the full packument.
+ * One GET, finished by `deadline`. Uses node:http(s) rather than fetch so the
+ * timeout can destroy the socket. Aborting a fetch that is still completing
+ * its TCP handshake — a firewall dropping packets, a captive portal — leaves
+ * the connect handle open and the CLI cannot exit until the OS gives up, long
+ * after the hint has printed.
  *
- * Uses node:http(s) rather than fetch so the timeout can destroy the socket.
- * Aborting a fetch that is still completing its TCP handshake — a firewall
- * dropping packets, a captive portal — leaves the connect handle open and the
- * CLI cannot exit until the OS gives up, long after the hint has printed.
+ * Resolves the final status (with the body only for a 200), or null on any
+ * network failure, an oversized body, or a redirect that cannot be followed.
+ * With `followRedirects: false` a redirect is returned as-is, unread.
  */
-function fetchLatestVersion() {
+function httpsGet(url, options) {
     return new Promise((resolve) => {
         let settled = false;
         let timer;
-        const finish = (version) => {
+        const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             if (timer)
                 clearTimeout(timer);
-            resolve(version);
+            resolve(result);
         };
-        let url;
-        try {
-            const resolved = registryUrl();
-            if (resolved === null) {
-                resolve(null);
-                return;
-            }
-            url = new URL(resolved);
-        }
-        catch {
-            resolve(null);
-            return;
-        }
         // Mirrors and corporate front-ends redirect; without following one the
         // check would be permanently and silently dead for them.
         let redirectsLeft = MAX_REDIRECTS;
@@ -229,6 +223,10 @@ function fetchLatestVersion() {
                 if (status >= 300 && status < 400 && location) {
                     response.resume();
                     request.destroy();
+                    if (!options.followRedirects) {
+                        finish({ status, body: '' });
+                        return;
+                    }
                     if (redirectsLeft <= 0) {
                         finish(null);
                         return;
@@ -256,29 +254,20 @@ function fetchLatestVersion() {
                 if (status !== 200) {
                     response.resume();
                     request.destroy();
-                    finish(null);
+                    finish({ status, body: '' });
                     return;
                 }
                 let body = '';
                 response.setEncoding('utf-8');
                 response.on('data', (chunk) => {
                     body += chunk;
-                    // The dist-tag document is small; refuse to buffer a firehose.
+                    // Version documents are small; refuse to buffer a firehose.
                     if (body.length > MAX_RESPONSE_BYTES) {
                         request.destroy();
                         finish(null);
                     }
                 });
-                response.on('end', () => {
-                    try {
-                        const parsed = JSON.parse(body);
-                        const version = parsed.version;
-                        finish(typeof version === 'string' && SAFE_VERSION.test(version) ? version : null);
-                    }
-                    catch {
-                        finish(null);
-                    }
-                });
+                response.on('end', () => finish({ status, body }));
                 response.on('error', () => finish(null));
             });
             activeRequest = request;
@@ -292,22 +281,105 @@ function fetchLatestVersion() {
                 timer = setTimeout(() => {
                     activeRequest?.destroy();
                     finish(null);
-                }, REQUEST_TIMEOUT_MS);
+                }, Math.max(0, options.deadline - Date.now()));
             }
         };
         send(url);
     });
 }
+/**
+ * Reads the `latest` dist-tag. Sends no custom Accept header: the registry
+ * answers `/<pkg>/latest` with 406 for npm's abbreviated-metadata type, which
+ * it only serves on the full packument.
+ */
+async function fetchLatestVersion() {
+    let url;
+    try {
+        const resolved = registryUrl();
+        if (resolved === null)
+            return null;
+        url = new URL(resolved);
+    }
+    catch {
+        return null;
+    }
+    const response = await httpsGet(url, {
+        deadline: Date.now() + REQUEST_TIMEOUT_MS,
+        followRedirects: true,
+    });
+    if (!response || response.status !== 200)
+        return null;
+    try {
+        const version = JSON.parse(response.body).version;
+        return typeof version === 'string' && SAFE_VERSION.test(version) ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where `openspec install` gets the standalone binary: install.sh and
+ * install.ps1 default to this releases page.
+ */
+const RELEASES_URL = 'https://github.com/Fission-AI/OpenSpec/releases';
+/**
+ * The release `openspec install` would install, found the way install.sh and
+ * install.ps1 find it: stable tags from the releases feed, newest first, and
+ * the first one whose SHA256SUMS (uploaded last) exists. npm's `latest` is not
+ * the answer here: it is published minutes before the standalone files are
+ * attached to the GitHub release (and for good, if that job fails), and
+ * offering a version the installer cannot get makes `openspec install`
+ * quietly reinstall the old one.
+ *
+ * Stops at the first tag that is not newer than this CLI, since nothing from
+ * there on is an update, so an up-to-date binary costs only the feed request.
+ * Null when the answer is not known: the feed or a probe failed or ran out of
+ * time, or every listed newer release is still incomplete.
+ */
+async function fetchLatestStandaloneRelease() {
+    // The same total budget as the registry check, across every request.
+    const deadline = Date.now() + REQUEST_TIMEOUT_MS;
+    const feed = await httpsGet(new URL(`${RELEASES_URL}.atom`), { deadline, followRedirects: true });
+    if (!feed || feed.status !== 200)
+        return null;
+    const versions = [
+        ...new Set(Array.from(feed.body.matchAll(/\/releases\/tag\/v(\d+\.\d+\.\d+)"/g), (m) => m[1])),
+    ].filter((version) => SAFE_VERSION.test(version));
+    for (const version of versions) {
+        if (compareVersions(version, OPENSPEC_VERSION) <= 0)
+            return version;
+        // GitHub answers for an attached file with a redirect to its storage, so
+        // the file itself never needs downloading.
+        const probe = await httpsGet(new URL(`${RELEASES_URL}/download/v${version}/SHA256SUMS`), {
+            deadline,
+            followRedirects: false,
+        });
+        if (!probe)
+            return null;
+        if (probe.status === 200 || (probe.status >= 300 && probe.status < 400))
+            return version;
+        // Still being prepared: the installer moves on to the next release too.
+        if (probe.status === 404)
+            continue;
+        // Rate-limited or failing: not knowing beats a wrong answer.
+        return null;
+    }
+    return null;
+}
 /**
  * Checks the registry while preserving enough detail for callers to explain
- * why no newer version was reported. Never throws.
+ * why no newer version was reported. Never throws. Pass `requested` only when
+ * the user explicitly asked for the check.
  */
-export async function checkForCliUpdate() {
-    if (!isCheckEnabled() || registryUrl() === null) {
+export async function checkForCliUpdate(options = {}) {
+    // The standalone binary updates from GitHub releases, not npm, so the
+    // registry neither answers for it nor can disable its check.
+    const standalone = standaloneBinaryPath !== null;
+    if (!isCheckEnabled(options.requested === true) || (!standalone && registryUrl() === null)) {
         return { status: 'disabled', latest: null };
     }
     try {
-        const latest = await fetchLatestVersion();
+        const latest = standalone ? await fetchLatestStandaloneRelease() : await fetchLatestVersion();
         if (!latest)
             return { status: 'offline', latest: null };
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -38,20 +38,20 @@
     "!dist/**/*.map"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
-    "@types/node": "^20.19.43",
+    "@types/node": "^22.12.0",
     "@types/picomatch": "^4.0.3",
-    "@vitest/ui": "^4.1.12",
+    "@vitest/ui": "^5.0.3",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vite": "^7.3.7",
-    "vitest": "^4.1.12"
+    "vite": "^8.3.5",
+    "vitest": "^5.0.3"
   },
   "dependencies": {
     "@inquirer/core": "^12.0.0",

package/schemas/spec-driven/schema.yaml

@@ -105,6 +105,7 @@ artifacts:
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
+      - Every scenario MUST have a WHEN/GIVEN step (its trigger) and a THEN step (its outcome). A scenario with only AND lines or plain prose still counts as a scenario, but `openspec validate` flags it as a warning: normal validation still passes, but `openspec validate --strict` fails on it.
       - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
       New capabilities only: the delta spec's first section is `## Purpose` -