@fission-ai/openspec 1.14.2 → 1.15.0

package/dist/core/validation/validator.js

@@ -9,6 +9,7 @@ import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractR
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { assertDiscoveredSpecFile } from '../../utils/spec-path-containment.js';
 import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
 import { METADATA_FILENAME, formatUnknownChangeMetadataKeysMessage, readSkipSpecsMarker, readUnknownChangeMetadataKeys, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
@@ -314,8 +315,7 @@ export class Validator {
                 // authoring time instead of days later at archive time (#1477).
                 if (options.mainSpecsDir && plan.modified.length > 0) {
                     const mainSpecFile = path.join(options.mainSpecsDir, ...specId.split('/'), 'spec.md');
-                    FileSystemUtils.assertPathWithin(path.dirname(mainSpecFile), mainSpecFile);
-                    issues.push(...(await this.findScenarioLossIssues(plan.modified, plan.renamed, mainSpecFile, entryPath, path.dirname(mainSpecFile))));
+                    issues.push(...(await this.findScenarioLossIssues(plan.modified, plan.renamed, mainSpecFile, entryPath, options.mainSpecsDir)));
                 }
                 // Validate REMOVED (names only)
                 for (const name of plan.removed) {
@@ -606,7 +606,7 @@ export class Validator {
      */
     async findScenarioLossIssues(modified, renamed, mainSpecFile, entryPath, mainSpecRoot) {
         let mainContent;
-        FileSystemUtils.assertPathWithin(mainSpecRoot, mainSpecFile);
+        assertDiscoveredSpecFile(mainSpecRoot, mainSpecFile);
         try {
             mainContent = await fs.readFile(mainSpecFile, 'utf-8');
         }

package/dist/core/version-check.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Called by the standalone binary's entry point. That copy has no package
+ * manager behind it, so a package-manager command is the wrong upgrade advice.
+ */
+export declare function markStandaloneBinary(executablePath: string): void;
+/** The standalone binary's own path, or null when running from a package. */
+export declare function getStandaloneBinaryPath(): string | null;
 /**
  * The registry to ask. A configured registry is honored only over TLS: a
  * cleartext hop would aim the request at a link-local or internal address and
@@ -79,7 +86,7 @@ export declare function isNpmGlobalInstall(installDir: string | null, roots?: st
  */
 export declare function isSourceCheckout(installDir: string | null): boolean;
 export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
-export type InstallScope = 'global' | 'project' | 'temporary' | 'source';
+export type InstallScope = 'global' | 'project' | 'temporary' | 'source' | 'standalone';
 export interface CliInstallInfo {
     location: string | null;
     packageManager: PackageManager | null;

package/dist/core/version-check.js

@@ -3,11 +3,13 @@ import http from 'http';
 import https from 'https';
 import path from 'path';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
+import { findCopiesOnPath, samePath } from '../utils/executable-path.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
@@ -22,6 +24,34 @@ const MAX_REDIRECTS = 3;
  * one could smuggle ANSI cursor controls and repaint the lines around it.
  */
 const SAFE_VERSION = /^\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
+let standaloneBinaryPath = null;
+/**
+ * Called by the standalone binary's entry point. That copy has no package
+ * manager behind it, so a package-manager command is the wrong upgrade advice.
+ */
+export function markStandaloneBinary(executablePath) {
+    standaloneBinaryPath = executablePath;
+}
+/** The standalone binary's own path, or null when running from a package. */
+export function getStandaloneBinaryPath() {
+    return standaloneBinaryPath;
+}
+/**
+ * `openspec install` reinstalls the standalone binary where it already is,
+ * under its own name, so the new copy cannot end up shadowed by the old one.
+ * Spelled with the full path when `openspec` on PATH is some other copy.
+ * Null when this is not the binary.
+ */
+function standaloneUpgradeCommand() {
+    if (!standaloneBinaryPath)
+        return null;
+    const first = findCopiesOnPath()[0];
+    if (first && samePath(first, standaloneBinaryPath))
+        return 'openspec install';
+    return process.platform === 'win32'
+        ? `& '${standaloneBinaryPath.replace(/'/g, "''")}' install`
+        : `'${standaloneBinaryPath.replace(/'/g, `'\\''`)}' install`;
+}
 /**
  * The check is opt-out and must never get in the way: no network in CI or
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
@@ -304,12 +334,14 @@ export async function getAvailableCliUpdate() {
  * which copy is actually answering.
  */
 export function getInstallDir() {
-    try {
-        return path.dirname(require.resolve('../../package.json'));
-    }
-    catch {
+    // The binary is not a package install, so no package-manager logic applies.
+    if (standaloneBinaryPath)
         return null;
-    }
+    // Resolved at runtime from this module's own (symlink-resolved) location.
+    // require.resolve would be resolved by the binary's bundler at build time,
+    // baking the build machine's path into it.
+    const packageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
+    return fs.existsSync(packageJson) ? path.dirname(packageJson) : null;
 }
 /**
  * True when the running CLI resolves from a `node_modules` belonging to the
@@ -508,6 +540,9 @@ function detectGlobalPackageManager(installDir) {
 }
 /** Describes the running copy without guessing when its owner is ambiguous. */
 export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.') {
+    if (standaloneBinaryPath) {
+        return { location: path.dirname(standaloneBinaryPath), packageManager: null, scope: 'standalone' };
+    }
     if (!installDir) {
         return { location: null, packageManager: null, scope: null };
     }
@@ -537,6 +572,8 @@ export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.
 }
 /** Returns a safe update command only for an install with known global ownership. */
 export function getCliUpdateCommand(install) {
+    if (install.scope === 'standalone')
+        return standaloneUpgradeCommand();
     if (install.scope !== 'global' || install.packageManager === null)
         return null;
     return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
@@ -585,6 +622,12 @@ export function buildCliUpdateLines(latestVersion, installDir, projectPath, opti
  */
 export function buildUpgradeCommandLines(installDir, projectPath) {
     const lines = [];
+    const standalone = standaloneUpgradeCommand();
+    if (standalone) {
+        lines.push(`  ${standalone}`);
+        lines.push('  Then run "openspec update" again to pick up new workflows.');
+        return lines;
+    }
     if (isEphemeralRunnerInstall(installDir)) {
         // That command *is* the update, so there is nothing to run afterwards.
         lines.push(`  npx ${PACKAGE_NAME}@latest update`);

package/dist/utils/executable-path.d.ts

@@ -0,0 +1,5 @@
+/** Every `openspec` on PATH, in the order a shell would find them. */
+export declare function findCopiesOnPath(pathValue?: string, platform?: NodeJS.Platform): string[];
+/** Whether two paths name the same file once symlinks are resolved. */
+export declare function samePath(a: string, b: string): boolean;
+//# sourceMappingURL=executable-path.d.ts.map

package/dist/utils/executable-path.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Every `openspec` on PATH, in the order a shell would find them. */
+export function findCopiesOnPath(pathValue = process.env.PATH ?? '', platform = process.platform) {
+    const names = platform === 'win32' ? ['openspec.exe', 'openspec.cmd'] : ['openspec'];
+    const seen = new Set();
+    const copies = [];
+    for (const dir of pathValue.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if (!fs.statSync(candidate).isFile())
+                    continue;
+                if (platform !== 'win32')
+                    fs.accessSync(candidate, fs.constants.X_OK);
+                const key = platform === 'win32' ? candidate.toLowerCase() : candidate;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    copies.push(candidate);
+                }
+            }
+            catch {
+                // Not there, or not runnable: not a copy a shell would run.
+            }
+        }
+    }
+    return copies;
+}
+/** Whether two paths name the same file once symlinks are resolved. */
+export function samePath(a, b) {
+    const real = (value) => {
+        try {
+            return fs.realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const [x, y] = [real(a), real(b)];
+    return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+//# sourceMappingURL=executable-path.js.map

package/dist/utils/file-system.d.ts

@@ -1,7 +1,7 @@
 export declare class FileSystemUtils {
     /**
      * Converts a path to use forward slashes (POSIX style).
-     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     * Essential for cross-platform compatibility with glob libraries like tinyglobby.
      */
     static toPosixPath(p: string): string;
     /**

package/dist/utils/file-system.js

@@ -65,7 +65,7 @@ function findMarkerIndex(content, marker, fromIndex = 0) {
 export class FileSystemUtils {
     /**
      * Converts a path to use forward slashes (POSIX style).
-     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     * Essential for cross-platform compatibility with glob libraries like tinyglobby.
      */
     static toPosixPath(p) {
         return p.replace(/\\/g, '/');

package/dist/utils/interactive.d.ts

@@ -67,4 +67,19 @@ export declare function confirmPrompt(prompt: ConfirmPrompt, io?: {
     input?: Readable;
     output?: Writable;
 }): Promise<boolean>;
+/**
+ * Whether a spinner can safely render to `stream`.
+ *
+ * ora decides how many lines to erase with `ceil(width / stream.columns)`, so a
+ * TTY that reports zero columns makes that count `Infinity` and `clear()` never
+ * ends: the spinner emits cursor-up/clear-line escapes as fast as it can and the
+ * command never finishes (#2106). Zero-width TTYs are real — a pty inherited
+ * from a pre-commit runner such as lefthook, or `script -qec` — and nothing can
+ * be drawn in zero columns anyway, so refuse the spinner and let the caller fall
+ * back to its plain output.
+ */
+export declare function canRenderSpinner(stream?: {
+    isTTY?: boolean;
+    columns?: number;
+}): boolean;
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -153,4 +153,22 @@ function readYesNo(prompt, input, output) {
         });
     });
 }
+/**
+ * Whether a spinner can safely render to `stream`.
+ *
+ * ora decides how many lines to erase with `ceil(width / stream.columns)`, so a
+ * TTY that reports zero columns makes that count `Infinity` and `clear()` never
+ * ends: the spinner emits cursor-up/clear-line escapes as fast as it can and the
+ * command never finishes (#2106). Zero-width TTYs are real — a pty inherited
+ * from a pre-commit runner such as lefthook, or `script -qec` — and nothing can
+ * be drawn in zero columns anyway, so refuse the spinner and let the caller fall
+ * back to its plain output.
+ */
+export function canRenderSpinner(stream = process.stderr) {
+    // A non-TTY stream never enters the clear loop: ora disables itself and
+    // prints one plain line instead.
+    if (!stream.isTTY)
+        return true;
+    return (stream.columns ?? 0) > 0;
+}
 //# sourceMappingURL=interactive.js.map

package/dist/utils/spec-discovery.d.ts

@@ -10,10 +10,10 @@ export interface DiscoveredSpec {
  * are found (#1353). A `spec.md` sitting directly in the root is ignored,
  * matching the historical requirement that specs live in a capability folder.
  * Dot-directories are skipped and symlinked directories are not followed.
- * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
- * artifact graph's globs both count it as content, so dropping it here would
- * silently lose the delta on archive. A link outside its capability is
- * rejected and a dangling link is skipped. Results are sorted by id.
+ * A symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the artifact
+ * graph's globs both count it as content, so dropping it here would silently
+ * lose the delta on archive. `assertSpecFilePathAllowed` decides how far such
+ * a link may point; a dangling link is skipped. Results are sorted by id.
  *
  * A missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the

package/dist/utils/spec-discovery.js

@@ -1,27 +1,17 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { FileSystemUtils } from './file-system.js';
+import { assertDiscoveredSpecFile } from './spec-path-containment.js';
 import { parseDeltaSpec } from '../core/parsers/requirement-blocks.js';
-function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
-    try {
-        FileSystemUtils.assertPathWithin(specsRoot, specFile);
-    }
-    catch {
-        // Direct capability directories may intentionally be external monorepo
-        // links. In that case, confine the file to the capability itself.
-        FileSystemUtils.assertPathWithin(capabilityDir, specFile);
-    }
-}
 /**
  * Recursively discover every `spec.md` under a specs root, so both the flat
  * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
  * are found (#1353). A `spec.md` sitting directly in the root is ignored,
  * matching the historical requirement that specs live in a capability folder.
  * Dot-directories are skipped and symlinked directories are not followed.
- * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
- * artifact graph's globs both count it as content, so dropping it here would
- * silently lose the delta on archive. A link outside its capability is
- * rejected and a dangling link is skipped. Results are sorted by id.
+ * A symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the artifact
+ * graph's globs both count it as content, so dropping it here would silently
+ * lose the delta on archive. `assertSpecFilePathAllowed` decides how far such
+ * a link may point; a dangling link is skipped. Results are sorted by id.
  *
  * A missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
@@ -49,13 +39,13 @@ export async function discoverSpecFiles(specsRoot) {
             else if (entry.name === 'spec.md' && segments.length > 0) {
                 const specFile = path.join(dir, entry.name);
                 if (entry.isFile()) {
-                    assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                    assertDiscoveredSpecFile(specsRoot, specFile);
                     results.push({ id: segments.join('/'), specFile });
                 }
                 else if (entry.isSymbolicLink()) {
                     try {
                         if ((await fs.stat(specFile)).isFile()) {
-                            assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                            assertDiscoveredSpecFile(specsRoot, specFile);
                             results.push({ id: segments.join('/'), specFile });
                         }
                     }

package/dist/utils/spec-path-containment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Containment for a `spec.md` under a trust root already established for it:
+ * inside the root, or a link out of the root that stays inside the project.
+ *
+ * Deliberately does not re-derive a trust root from the file's own capability
+ * directory. Callers use this to recheck a path immediately before reading or
+ * writing it, and a capability directory swapped for a link since the path was
+ * resolved has to be refused rather than trusted afresh.
+ */
+export declare function assertSpecFileWithin(root: string, specFile: string): void;
+/**
+ * Containment for a `spec.md` as it is discovered, where the capability
+ * directory itself may deliberately be a link into another repository and is
+ * then the file's own trust root.
+ */
+export declare function assertDiscoveredSpecFile(specsRoot: string, specFile: string): void;
+//# sourceMappingURL=spec-path-containment.d.ts.map

package/dist/utils/spec-path-containment.js

@@ -0,0 +1,122 @@
+import * as nodeFs from 'fs';
+import path from 'path';
+import { OPENSPEC_DIR_NAME } from '../core/config.js';
+import { FileSystemUtils } from './file-system.js';
+/**
+ * The project a specs root belongs to, or null when it cannot be named.
+ *
+ * Every specs root OpenSpec reads is addressed through the project's
+ * `openspec` directory - `<project>/openspec/specs` for main specs and
+ * `<project>/openspec/changes/<change>/specs` (or `.../changes/archive/...`)
+ * for a change's deltas - so the project is the parent of that `openspec`
+ * directory.
+ *
+ * The directory below the match has to be `specs` or `changes`, which is what
+ * makes this a planning root rather than a directory that merely shares the
+ * name: a store kept at `~/openspec/my-store` would otherwise hand out `~` as
+ * its boundary. A specs root reached some other way (a store given by path)
+ * has no project to name, and containment stays at the specs root.
+ */
+function findProjectRoot(specsRoot) {
+    let current = path.resolve(specsRoot);
+    let below = null;
+    while (true) {
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        if (path.basename(current) === OPENSPEC_DIR_NAME &&
+            (below === 'specs' || below === 'changes')) {
+            return parent;
+        }
+        below = path.basename(current);
+        current = parent;
+    }
+}
+/** Path-segment containment on the paths as written, without resolving links. */
+function isLexicallyWithin(allowedDirectory, targetPath) {
+    const relative = path.relative(path.resolve(allowedDirectory), path.resolve(targetPath));
+    return (relative === '' ||
+        (relative !== '..' &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+/**
+ * A project may keep a capability's spec file elsewhere - beside the product
+ * documentation it belongs to - and leave a relative symlink at
+ * `openspec/specs/<capability>/spec.md`, so OpenSpec and the docs read and
+ * write the same bytes. Accept such a link, and refuse one that leaves the
+ * project, so a link swapped underneath a repo cannot turn a spec read or an
+ * archive write into an arbitrary file access.
+ *
+ * `outsideError` is rethrown when the file is not a link at all, so a path
+ * that simply escapes its root keeps reporting that.
+ */
+function assertLinkedSpecFileInProject(root, specFile, outsideError) {
+    const projectRoot = findProjectRoot(root);
+    if (projectRoot === null) {
+        throw outsideError;
+    }
+    const resolvedFile = path.resolve(specFile);
+    let isLink = false;
+    try {
+        isLink = nodeFs.lstatSync(resolvedFile).isSymbolicLink();
+    }
+    catch {
+        isLink = false;
+    }
+    if (!isLink) {
+        throw outsideError;
+    }
+    // Only where the link points is the project's choice. The directory holding
+    // it must still be reached from inside the root.
+    FileSystemUtils.assertPathWithin(root, path.dirname(resolvedFile));
+    // Canonicalizes through the link, so a target outside the project is refused
+    // and a dangling link - which cannot be proven contained - fails loudly.
+    FileSystemUtils.assertPathWithin(projectRoot, resolvedFile);
+}
+/**
+ * Containment for a `spec.md` under a trust root already established for it:
+ * inside the root, or a link out of the root that stays inside the project.
+ *
+ * Deliberately does not re-derive a trust root from the file's own capability
+ * directory. Callers use this to recheck a path immediately before reading or
+ * writing it, and a capability directory swapped for a link since the path was
+ * resolved has to be refused rather than trusted afresh.
+ */
+export function assertSpecFileWithin(root, specFile) {
+    try {
+        FileSystemUtils.assertPathWithin(root, specFile);
+    }
+    catch (error) {
+        assertLinkedSpecFileInProject(root, specFile, error);
+    }
+}
+/**
+ * Containment for a `spec.md` as it is discovered, where the capability
+ * directory itself may deliberately be a link into another repository and is
+ * then the file's own trust root.
+ */
+export function assertDiscoveredSpecFile(specsRoot, specFile) {
+    const capabilityDir = path.dirname(path.resolve(specFile));
+    try {
+        FileSystemUtils.assertPathWithin(specsRoot, specFile);
+        return;
+    }
+    catch (error) {
+        // The capability directory is the file's own trust root only while it is
+        // addressed from inside the specs root: the link it may be is deliberate,
+        // a `..` out of the root is not.
+        if (isLexicallyWithin(specsRoot, capabilityDir)) {
+            try {
+                FileSystemUtils.assertPathWithin(capabilityDir, specFile);
+                return;
+            }
+            catch {
+                // Not a file of its own capability either; the link rule decides.
+            }
+        }
+        assertLinkedSpecFileInProject(specsRoot, specFile, error);
+    }
+}
+//# sourceMappingURL=spec-path-containment.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -44,22 +44,26 @@
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
-    "@vitest/ui": "^4.1.11",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/ui": "^4.1.12",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.11"
+    "vite": "^7.3.7",
+    "vitest": "^4.1.12"
   },
   "dependencies": {
     "@inquirer/core": "^12.0.0",
     "@inquirer/prompts": "^8.5.2",
+    "brace-expansion": "^5.0.12",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "cross-spawn": "7.0.6",
     "diff": "^9.0.0",
-    "fast-glob": "^3.3.3",
     "ora": "^9.4.1",
+    "picomatch": "^4.0.4",
+    "tinyglobby": "^0.2.17",
     "yaml": "^2.8.3",
     "zod": "^4.4.3"
   },