@fission-ai/openspec 1.14.1 → 1.14.3

package/dist/utils/change-metadata.d.ts

@@ -2,10 +2,22 @@ import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-
 import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
 export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.openspec.yaml` alongside OpenSpec (a tracker id, an
+ * owner). OpenSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export declare const EXTENSION_KEY_PATTERN: RegExp;
+export declare function isExtensionMetadataKey(key: string): boolean;
 /**
  * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
  * stripped by ChangeMetadataSchema rather than rejected, so callers that want
  * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
  */
 export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
 /**
@@ -40,6 +52,11 @@ export declare function validateSchemaName(schemaName: string, projectRoot?: str
 /**
  * Writes change metadata to .openspec.yaml in the change directory.
  *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
  * @param changeDir - The path to the change directory
  * @param metadata - The metadata to write
  * @param projectRoot - Optional project root for project-local schema resolution

package/dist/utils/change-metadata.js

@@ -7,10 +7,24 @@ import { readProjectConfig } from '../core/project-config.js';
 import { sanitizeInline } from '../core/references.js';
 export const METADATA_FILENAME = '.openspec.yaml';
 export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Extension keys: a top-level key starting with a lowercase `x-` belongs to a
+ * tool or team that reads `.openspec.yaml` alongside OpenSpec (a tracker id, an
+ * owner). OpenSpec ignores it and does not report it as unknown. As with
+ * OpenAPI's `x-` extensions, the name after the prefix may use any case or
+ * spelling, but must be non-empty and free of whitespace, so `x-`, `x- foo`
+ * and `X-Foo` are still reported. Extensions are top-level only: a key inside
+ * `initiative:` is rejected by that object's strict schema.
+ */
+export const EXTENSION_KEY_PATTERN = /^x-\S+$/;
+export function isExtensionMetadataKey(key) {
+    return EXTENSION_KEY_PATTERN.test(key);
+}
 /**
  * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
  * stripped by ChangeMetadataSchema rather than rejected, so callers that want
  * to tell the author a key did nothing have to look at the raw object.
+ * Extension keys (`x-*`) are not unknown: they are deliberately someone else's.
  */
 export function listUnknownChangeMetadataKeys(parsed) {
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -18,7 +32,7 @@ export function listUnknownChangeMetadataKeys(parsed) {
     }
     const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
     return Object.keys(parsed)
-        .filter((key) => !known.has(key))
+        .filter((key) => !known.has(key) && !isExtensionMetadataKey(key))
         .sort();
 }
 /**
@@ -32,7 +46,13 @@ export function formatUnknownChangeMetadataKeysMessage(keys) {
     const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
     const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
     let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
-        `Known keys: ${known}. Unknown keys are ignored and have no effect.`;
+        `Known keys: ${known}. Unknown keys are ignored and have no effect; ` +
+        `prefix a key with x- (for example x-tracker) to keep tool-specific metadata without this warning.`;
+    if (keys.some((key) => /^x-/i.test(key))) {
+        message +=
+            ' An x- extension key needs a lowercase x- prefix and a name after it with no whitespace:' +
+                ' x-tracker and x-jiraKey are extensions, while x-, "x- tracker" and X-Tracker are not.';
+    }
     if (keys.includes('skip_design')) {
         message +=
             ' skip_design is not a supported key; only skip_specs exists, and it only skips artifacts whose generates path lives under specs/.';
@@ -92,6 +112,11 @@ export function validateSchemaName(schemaName, projectRoot) {
 /**
  * Writes change metadata to .openspec.yaml in the change directory.
  *
+ * Meant for a new file only (`createChange` refuses an existing change
+ * directory). `ChangeMetadataSchema` strips unknown keys, including `x-`
+ * extension keys, so a caller that rewrites an existing file must merge those
+ * keys back from the raw YAML first or it silently deletes them.
+ *
  * @param changeDir - The path to the change directory
  * @param metadata - The metadata to write
  * @param projectRoot - Optional project root for project-local schema resolution

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;
     /**
@@ -15,6 +15,13 @@ export declare class FileSystemUtils {
      * Missing suffixes are resolved from their nearest existing ancestor.
      */
     static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    /**
+     * Like assertPathWithin, but a targetPath that is itself a symlink may
+     * resolve outside allowedDirectory, so a project can keep a managed
+     * directory (for example openspec/changes) in another repository. Its parent
+     * must still be confined and the link must resolve to an existing path.
+     */
+    static assertPathWithinAllowingLinkedLeaf(allowedDirectory: string, targetPath: string): void;
     static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
     static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
     private static isPathWithin;

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, '/');
@@ -105,6 +105,31 @@ export class FileSystemUtils {
             throw new Error(`Path is outside the allowed directory: ${targetPath}`);
         }
     }
+    /**
+     * Like assertPathWithin, but a targetPath that is itself a symlink may
+     * resolve outside allowedDirectory, so a project can keep a managed
+     * directory (for example openspec/changes) in another repository. Its parent
+     * must still be confined and the link must resolve to an existing path.
+     */
+    static assertPathWithinAllowingLinkedLeaf(allowedDirectory, targetPath) {
+        const resolvedTarget = path.resolve(targetPath);
+        let isLink = false;
+        try {
+            isLink = nodeFs.lstatSync(resolvedTarget).isSymbolicLink();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        if (!isLink) {
+            this.assertPathWithin(allowedDirectory, resolvedTarget);
+            return;
+        }
+        this.assertPathWithin(allowedDirectory, path.dirname(resolvedTarget));
+        // Throws for a dangling link, which cannot be proven to be a directory.
+        nodeFs.realpathSync.native(resolvedTarget);
+    }
     static resolveProjectArtifactPath(projectPath, artifactPath) {
         if (path.isAbsolute(artifactPath)) {
             throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);

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.1",
+  "version": "1.14.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -44,6 +44,7 @@
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
+    "@types/picomatch": "^4.0.3",
     "@vitest/ui": "^4.1.11",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
@@ -54,12 +55,14 @@
   "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"
   },