@fission-ai/openspec 1.7.0 → 1.9.0

package/dist/utils/command-references.js

@@ -59,12 +59,47 @@ const SKILL_INVOCATION_PREFIX = {
     kimi: '/skill:',
     codex: '$',
 };
+/**
+ * Tools that have no slash-command surface at all: skills are matched
+ * automatically or invoked by natural-language prompts, never by typing a
+ * `/<name>` command. Rovo Dev CLI is such a tool — `/skills` only manages
+ * skills, and any `/openspec-*` form would be a dead command (see
+ * docs/supported-tools.md). References for these tools are spelled as prose
+ * ("the openspec-propose skill") so generated content never tells the user to
+ * type a command their CLI does not register.
+ */
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev']);
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export function usesNaturalLanguageSkillReferences(toolId) {
+    return NATURAL_LANGUAGE_SKILL_TOOLS.has(toolId);
+}
+function replaceCommandsWithNaturalLanguageSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `the ${skillName} skill`;
+    });
+}
 function replaceCommandsWithSkillReferences(text, prefix) {
     return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
         const skillName = COMMAND_TO_SKILL_NAME[commandId];
         return skillName === undefined ? match : `${prefix}${skillName}`;
     });
 }
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export function transformToCodexCompatibleSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined
+            ? match
+            : `$${skillName} (Codex) or /${skillName} (other agents)`;
+    });
+}
 /**
  * Transforms command references to skill references using the default `/`
  * invocation prefix. Converts `/opsx:<command>` patterns to
@@ -88,12 +123,17 @@ export function transformToSkillReferences(text) {
 /**
  * Returns the skill-reference transformer for a specific tool, honoring the
  * tool's documented skill invocation syntax (e.g. Kimi Code's
- * `/skill:openspec-propose`). Falls back to the default `/openspec-*` form.
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
  *
- * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe')
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
  * @returns A transformer converting `/opsx:*` references to skill invocations
  */
 export function getSkillReferenceTransformer(toolId) {
+    if (usesNaturalLanguageSkillReferences(toolId)) {
+        return replaceCommandsWithNaturalLanguageSkillReferences;
+    }
     const prefix = SKILL_INVOCATION_PREFIX[toolId];
     if (prefix === undefined) {
         return transformToSkillReferences;
@@ -138,7 +178,9 @@ export function getSkillReferenceTransformer(toolId) {
  */
 export function getTransformerForTool(toolId, delivery, capability, invocation) {
     if (delivery === 'skills' || capability !== 'adapter-backed') {
-        return getSkillReferenceTransformer(toolId);
+        return toolId === 'codex'
+            ? transformToCodexCompatibleSkillReferences
+            : getSkillReferenceTransformer(toolId);
     }
     if (toolId === 'devin' && delivery === 'both') {
         return getSkillReferenceTransformer(toolId);

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

@@ -9,6 +9,16 @@ export declare class FileSystemUtils {
      * Falls back to path.resolve() so callers can still produce a stable absolute path.
      */
     static canonicalizeExistingPath(targetPath: string): string;
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
+    static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
+    private static isPathWithin;
+    private static canonicalizePotentialPath;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;

package/dist/utils/file-system.js

@@ -87,6 +87,76 @@ export class FileSystemUtils {
             }
         }
     }
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory, targetPath) {
+        const resolvedDirectory = path.resolve(allowedDirectory);
+        const resolvedTarget = path.resolve(targetPath);
+        if (!this.isPathWithin(resolvedDirectory, resolvedTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+        const canonicalDirectory = this.canonicalizePotentialPath(resolvedDirectory);
+        const canonicalTarget = this.canonicalizePotentialPath(resolvedTarget);
+        if (!this.isPathWithin(canonicalDirectory, canonicalTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+    }
+    static resolveProjectArtifactPath(projectPath, artifactPath) {
+        if (path.isAbsolute(artifactPath)) {
+            throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);
+        }
+        const targetPath = path.join(projectPath, artifactPath);
+        this.assertPathWithin(projectPath, targetPath);
+        return targetPath;
+    }
+    static assertProjectArtifactPath(projectPath, targetPath) {
+        this.assertPathWithin(projectPath, targetPath);
+    }
+    static isPathWithin(allowedDirectory, targetPath) {
+        const relative = path.relative(allowedDirectory, targetPath);
+        return (relative === '' ||
+            (relative !== '..' &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative)));
+    }
+    static canonicalizePotentialPath(targetPath) {
+        let existingPath = targetPath;
+        const missingSegments = [];
+        while (true) {
+            try {
+                // lstat distinguishes a missing path from a dangling symlink. A
+                // dangling link cannot be proven confined, so realpath must fail it.
+                nodeFs.lstatSync(existingPath);
+                const canonicalExisting = nodeFs.realpathSync.native(existingPath);
+                return path.resolve(canonicalExisting, ...missingSegments);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOENT') {
+                    throw error;
+                }
+                try {
+                    if (nodeFs.lstatSync(existingPath).isSymbolicLink()) {
+                        throw new Error(`Cannot verify dangling symbolic link: ${existingPath}`);
+                    }
+                }
+                catch (lstatError) {
+                    if (lstatError.code !== 'ENOENT') {
+                        throw lstatError;
+                    }
+                }
+                const parent = path.dirname(existingPath);
+                if (parent === existingPath) {
+                    throw new Error(`Cannot resolve an existing parent for ${targetPath}`);
+                }
+                missingSegments.unshift(path.basename(existingPath));
+                existingPath = parent;
+            }
+        }
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/dist/utils/interactive.d.ts

@@ -1,3 +1,4 @@
+import type { Readable, Writable } from 'node:stream';
 export type InteractiveOptions = {
     /**
      * Explicit "disable prompts" flag passed by internal callers.
@@ -15,4 +16,55 @@ export type InteractiveOptions = {
  */
 export declare function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean;
 export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`openspec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
+ */
+export declare function isNonInteractivePromptError(error: unknown, value?: boolean | InteractiveOptions): boolean;
+export type ConfirmPrompt = {
+    message: string;
+    default: boolean;
+};
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | openspec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export declare function confirmPrompt(prompt: ConfirmPrompt, io?: {
+    input?: Readable;
+    output?: Writable;
+}): Promise<boolean>;
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -1,3 +1,4 @@
+import { createInterface } from 'node:readline';
 /**
  * Resolves whether non-interactive mode is requested.
  * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
@@ -18,4 +19,138 @@ export function isInteractive(value) {
         return false;
     return !!process.stdin.isTTY;
 }
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | openspec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`openspec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
+ */
+export function isNonInteractivePromptError(error, value) {
+    if (!(error instanceof Error))
+        return false;
+    const failedPrompt = error.name === 'ExitPromptError' || error.message.includes('force closed the prompt');
+    if (!failedPrompt)
+        return false;
+    if (error.message.includes('SIGINT'))
+        return false;
+    return !isInteractive(value) || !process.stdout.isTTY;
+}
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | openspec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export async function confirmPrompt(prompt, io = {}) {
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stdout;
+    const isTerminal = Boolean(input.isTTY) &&
+        Boolean(output.isTTY);
+    if (isTerminal) {
+        const { confirm } = await import('@inquirer/prompts');
+        return confirm(prompt);
+    }
+    return readYesNo(prompt, input, output);
+}
+function readYesNo(prompt, input, output) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // Detach the input-stream error listener on settle: `input` is the
+        // long-lived process.stdin, so a leftover listener would accumulate across
+        // archive's successive prompts and swallow a later, unrelated stdin error.
+        const cleanup = () => {
+            input.removeListener('error', onError);
+        };
+        const blockOnNoAnswer = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            // No line could be read (stdin closed / EOF). Mirror @inquirer's failure
+            // so callers that classify it — isNonInteractivePromptError, the #1479
+            // "rerun with --yes" guidance — keep working unchanged.
+            const error = new Error('User force closed the prompt');
+            error.name = 'ExitPromptError';
+            reject(error);
+        };
+        // A stdin error surfaces on the interface (readline forwards input-stream
+        // errors since Node 16). Without a handler the promise would hang and the
+        // 'error' would go unhandled; settle it with the real fault instead.
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        // An earlier prompt may have already drained stdin (only one piped answer
+        // was ever supported). A fresh readline over an ended stream never emits
+        // 'close', so guard here rather than hang and exit as a no-op.
+        if (input.readableEnded) {
+            blockOnNoAnswer();
+            return;
+        }
+        output.write(`${prompt.message} ${prompt.default ? '(Y/n)' : '(y/N)'} `);
+        // terminal:false guarantees readline never emits its own line-editing
+        // escapes — an escape-free read is the whole point here.
+        const rl = createInterface({ input, terminal: false });
+        input.once('error', onError);
+        rl.once('error', onError);
+        rl.once('line', (line) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            output.write('\n');
+            // Mirror @inquirer/confirm's parser (prefix match on y/yes and n/no,
+            // otherwise the default) so a piped answer resolves identically to the
+            // interactive prompt it replaces.
+            const answer = line.trim();
+            if (/^(y|yes)/i.test(answer)) {
+                resolve(true);
+            }
+            else if (/^(n|no)/i.test(answer)) {
+                resolve(false);
+            }
+            else {
+                resolve(prompt.default);
+            }
+        });
+        rl.once('close', () => {
+            blockOnNoAnswer();
+        });
+    });
+}
 //# 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.
- * 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; a dangling link is skipped. Results are sorted
- * by id for deterministic output.
+ * 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 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,15 +1,26 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import { FileSystemUtils } from './file-system.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.
- * 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; a dangling link is skipped. Results are sorted
- * by id for deterministic output.
+ * 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 missing root (ENOENT) yields an empty list, but any other read failure
  * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
@@ -35,13 +46,15 @@ export async function discoverSpecFiles(specsRoot) {
                 await walk(path.join(dir, entry.name), [...segments, entry.name]);
             }
             else if (entry.name === 'spec.md' && segments.length > 0) {
+                const specFile = path.join(dir, entry.name);
                 if (entry.isFile()) {
-                    results.push({ id: segments.join('/'), specFile: path.join(dir, entry.name) });
+                    assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                    results.push({ id: segments.join('/'), specFile });
                 }
                 else if (entry.isSymbolicLink()) {
-                    const specFile = path.join(dir, entry.name);
                     try {
                         if ((await fs.stat(specFile)).isFile()) {
+                            assertDiscoveredSpecPath(specsRoot, dir, specFile);
                             results.push({ id: segments.join('/'), specFile });
                         }
                     }

package/dist/utils/task-progress.d.ts

@@ -1,8 +1,46 @@
+export interface ParsedTask {
+    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    done: boolean;
+    /** Task text after the checkbox, trimmed (may be empty). */
+    description: string;
+}
+/**
+ * Parses every task line in a tasks file, in document order.
+ *
+ * Every line matching the pattern counts, wherever it sits - inside a code
+ * fence, an HTML comment or an indented block, as before. Skipping fenced
+ * checkboxes was tried and dropped: every rule for deciding which fence is
+ * "real" has an input where a stray or unbalanced ``` swallows genuine tasks.
+ * Counting a documented example as work is a loud, bypassable false positive;
+ * losing a real task is a silent one.
+ */
+export declare function parseTaskLines(content: string): ParsedTask[];
 export interface TaskProgress {
     total: number;
     completed: number;
 }
 export declare function countTasksFromContent(content: string): TaskProgress;
+/**
+ * Run-scoped memo mapping a schema name to its tracked-tasks `generates` glob.
+ * When one command resolves progress for many changes under a constant
+ * `projectRoot` — e.g. `validate --archived` over an append-only archive — this
+ * avoids re-reading and re-parsing (YAML + Zod) the same `schema.yaml` once per
+ * change. Keyed by schema name alone, which is safe *only* because a single run
+ * holds `projectRoot` constant; never reuse one cache across differing roots.
+ */
+export type SchemaGlobCache = Map<string, string | undefined>;
+/** Resolves the task files selected by the schema's apply tracking rule. */
+export declare function resolveTaskFilesForChange(changeDir: string, projectRoot: string, schemaGlobCache?: SchemaGlobCache): string[];
+export interface TaskProgressDetail extends TaskProgress {
+    /**
+     * Task files that exist but could not be read (any error other than ENOENT).
+     * `getTaskProgressForChange` discards this list to preserve its behavior;
+     * callers that must fail loudly on an unreadable tasks file — e.g.
+     * `openspec validate --archived` — read it so an unreadable file is never
+     * silently counted as "no tasks" (#205).
+     */
+    unreadable: string[];
+}
 /**
  * Computes a change's task progress by resolving its tracked-tasks artifact and
  * counting checkboxes across every file matched by that artifact's `generates`
@@ -10,7 +48,19 @@ export declare function countTasksFromContent(content: string): TaskProgress;
  * artifact (`resolveArtifactOutputs`) — so progress is no longer blind to nested
  * `tasks.md` files (#1202). Falls back to a single top-level `tasks.md` (exactly
  * as before) when the schema is unresolvable, no tracked-tasks artifact is found,
- * or the glob matches no file. Never throws.
+ * or the glob matches no file. Also reports task files that exist but could not
+ * be read. Per-file read errors are captured (never thrown); the only throw path
+ * is a malformed/unsafe schema whose glob resolution rejects (path traversal or
+ * a linked-directory cycle in `resolveArtifactOutputs`). Pass `schemaGlobCache`
+ * to memoize schema→glob resolution across many changes in one run.
+ */
+export declare function getTaskProgressDetailForChange(changesDir: string, changeName: string, projectRoot: string, schemaGlobCache?: SchemaGlobCache): Promise<TaskProgressDetail>;
+/**
+ * The task-completion counter `status`, `list`, and `archive` share. Delegates
+ * to `getTaskProgressDetailForChange` and drops the `unreadable` detail, so its
+ * returned totals are unchanged. Throws only on the same malformed/unsafe-schema
+ * glob-resolution path as that function (existing behavior; callers guard it as
+ * they did before).
  */
 export declare function getTaskProgressForChange(changesDir: string, changeName: string, projectRoot: string): Promise<TaskProgress>;
 export declare function formatTaskStatus(progress: TaskProgress): string;