@fission-ai/openspec 1.6.0 → 1.7.0

package/dist/core/view.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import chalk from 'chalk';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
+import { discoverSpecFiles } from '../utils/spec-discovery.js';
 export class ViewCommand {
     async execute(targetPath = '.') {
         const openspecDir = path.join(targetPath, 'openspec');
@@ -106,23 +107,17 @@ export class ViewCommand {
             return [];
         }
         const specs = [];
-        const entries = fs.readdirSync(specsDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                const specFile = path.join(specsDir, entry.name, 'spec.md');
-                if (fs.existsSync(specFile)) {
-                    try {
-                        const content = fs.readFileSync(specFile, 'utf-8');
-                        const parser = new MarkdownParser(content);
-                        const spec = parser.parseSpec(entry.name);
-                        const requirementCount = spec.requirements.length;
-                        specs.push({ name: entry.name, requirementCount });
-                    }
-                    catch (error) {
-                        // If spec cannot be parsed, include with 0 count
-                        specs.push({ name: entry.name, requirementCount: 0 });
-                    }
-                }
+        for (const { id, specFile } of await discoverSpecFiles(specsDir)) {
+            try {
+                const content = fs.readFileSync(specFile, 'utf-8');
+                const parser = new MarkdownParser(content);
+                const spec = parser.parseSpec(id);
+                const requirementCount = spec.requirements.length;
+                specs.push({ name: id, requirementCount });
+            }
+            catch (error) {
+                // If spec cannot be parsed, include with 0 count
+                specs.push({ name: id, requirementCount: 0 });
             }
         }
         return specs;

package/dist/prompts/searchable-multi-select.js

@@ -113,7 +113,7 @@ async function createSearchableMultiSelect() {
                 const actualIndex = startIndex + i;
                 const isActive = actualIndex === cursor;
                 const selected = selectedSet.has(item.value);
-                const icon = selected ? chalk.green('◉') : chalk.dim('○');
+                const icon = selected ? chalk.green('[x]') : chalk.dim('[ ]');
                 const arrow = isActive ? chalk.cyan('›') : ' ';
                 const name = isActive ? chalk.cyan(item.name) : item.name;
                 const isRefresh = selected && item.configured;

package/dist/telemetry/index.d.ts

@@ -24,7 +24,7 @@ export declare function trackCommand(commandName: string, version: string): Prom
  */
 export declare function maybeShowTelemetryNotice(): Promise<void>;
 /**
- * Shutdown the PostHog client and flush pending events.
+ * Flush pending telemetry events.
  * Call this before CLI exit.
  */
 export declare function shutdown(): Promise<void>;

package/dist/telemetry/index.js

@@ -7,8 +7,17 @@
  * - Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
  * - Auto-disabled in CI environments
  * - Anonymous ID is a random UUID with no relation to the user
+ *
+ * Events are sent with a plain fetch to PostHog's stable public `/batch/`
+ * endpoint — the same one posthog-node used — instead of through the SDK.
+ * The SDK's only remaining job here was the wire format: every reliability
+ * knob was already forced to "send one event immediately, time-bounded,
+ * never retry, never throw". Carrying `posthog-node` for that shipped its
+ * fast-moving transitive tree (`@posthog/core`, `@posthog/types`, multiple
+ * releases per day) to every downstream consumer, where supply-chain age
+ * policies such as pnpm's `minimumReleaseAge` rejected the freshly published
+ * versions and broke installs (#1390).
  */
-import { PostHog } from 'posthog-node';
 import { randomUUID } from 'crypto';
 import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
 // PostHog API key - public key for client-side analytics
@@ -17,11 +26,23 @@ const POSTHOG_API_KEY = 'phc_Hthu8YvaIJ9QaFKyTG4TbVwkbd5ktcAFzVTKeMmoW2g';
 // Using reverse proxy to avoid ad blockers and keep traffic on our domain
 const POSTHOG_HOST = 'https://edge.openspec.dev';
 const TELEMETRY_REQUEST_TIMEOUT_MS = 1000;
-let posthogClient = null;
 let anonymousId = null;
+/**
+ * Requests started by trackCommand and not yet settled, so shutdown can
+ * flush them before the process exits. Each request is individually
+ * time-bounded, so awaiting them cannot stall exit for more than the
+ * request timeout.
+ */
+const pendingEvents = new Set();
 async function safeTelemetryFetch(url, options) {
     try {
         const response = await fetch(url, options);
+        // Telemetry never reads the body, but undici keeps the connection
+        // occupied until the body is consumed or canceled — dispose of it on
+        // every path so no socket outlives shutdown().
+        if (response.body) {
+            await response.body.cancel();
+        }
         if (response.ok) {
             return response;
         }
@@ -75,24 +96,30 @@ export async function getOrCreateAnonymousId() {
     return anonymousId;
 }
 /**
- * Get the PostHog client instance.
- * Creates it on first call with CLI-optimized settings.
+ * Send one capture event to PostHog's batch endpoint. Fire-and-forget:
+ * bounded by the request timeout, never throws, never retries.
  */
-function getClient() {
-    if (!posthogClient) {
-        posthogClient = new PostHog(POSTHOG_API_KEY, {
-            host: POSTHOG_HOST,
-            flushAt: 1, // Send immediately, don't batch
-            flushInterval: 0, // No timer-based flushing
-            fetchRetryCount: 0,
-            requestTimeout: TELEMETRY_REQUEST_TIMEOUT_MS,
-            preloadFeatureFlags: false,
-            disableRemoteConfig: true,
-            disableSurveys: true,
-            fetch: safeTelemetryFetch,
-        });
-    }
-    return posthogClient;
+function sendEvent(distinctId, event, properties) {
+    const body = JSON.stringify({
+        api_key: POSTHOG_API_KEY,
+        batch: [
+            {
+                type: 'capture',
+                event,
+                distinct_id: distinctId,
+                properties,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    });
+    const request = safeTelemetryFetch(`${POSTHOG_HOST}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
+    }).then(() => undefined);
+    pendingEvents.add(request);
+    void request.finally(() => pendingEvents.delete(request));
 }
 /**
  * Track a command execution.
@@ -106,16 +133,11 @@ export async function trackCommand(commandName, version) {
     }
     try {
         const userId = await getOrCreateAnonymousId();
-        const client = getClient();
-        client.capture({
-            distinctId: userId,
-            event: 'command_executed',
-            properties: {
-                command: commandName,
-                version: version,
-                surface: 'cli',
-                $ip: null, // Explicitly disable IP tracking
-            },
+        sendEvent(userId, 'command_executed', {
+            command: commandName,
+            version: version,
+            surface: 'cli',
+            $ip: null, // Explicitly disable IP tracking
         });
     }
     catch {
@@ -144,21 +166,21 @@ export async function maybeShowTelemetryNotice() {
     }
 }
 /**
- * Shutdown the PostHog client and flush pending events.
+ * Flush pending telemetry events.
  * Call this before CLI exit.
  */
 export async function shutdown() {
-    if (!posthogClient) {
+    if (pendingEvents.size === 0) {
         return;
     }
     try {
-        await posthogClient.shutdown();
+        await Promise.allSettled([...pendingEvents]);
     }
     catch {
         // Silent failure - telemetry should never break CLI exit
     }
     finally {
-        posthogClient = null;
+        pendingEvents.clear();
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/ui/welcome-screen.d.ts

@@ -2,9 +2,17 @@
  * Animated welcome screen for the experimental artifact workflow setup.
  * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
  */
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export declare function prefersReducedMotion(platform?: NodeJS.Platform): boolean;
 /**
  * Shows the animated welcome screen.
  * Returns when user presses Enter.
  */
-export declare function showWelcomeScreen(): Promise<void>;
+export declare function showWelcomeScreen(workflows: readonly string[], options?: {
+    animate?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=welcome-screen.d.ts.map

package/dist/ui/welcome-screen.js

@@ -3,7 +3,9 @@
  * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
  */
 import chalk from 'chalk';
+import { execFileSync, } from 'node:child_process';
 import { WELCOME_ANIMATION } from './ascii-patterns.js';
+import { getOnboardingCommands } from '../core/onboarding-commands.js';
 // Minimum terminal width for side-by-side layout
 const MIN_WIDTH = 60;
 // Width of the ASCII art column (with padding)
@@ -11,20 +13,35 @@ const ART_COLUMN_WIDTH = 24;
 /**
  * Welcome text content (right column)
  */
-function getWelcomeText() {
+function getWelcomeText(workflows) {
+    const onboardingCommands = getOnboardingCommands(workflows);
+    const quickStart = [];
+    if (onboardingCommands.length > 0) {
+        const commandWidth = Math.max(...onboardingCommands.map((c) => c.command.length));
+        quickStart.push(chalk.white('Quick start after setup:'));
+        for (const { command, description } of onboardingCommands) {
+            quickStart.push(`  ${chalk.yellow(command.padEnd(commandWidth + 1))} ${chalk.dim(description)}`);
+        }
+        // These are the canonical names. How each tool spells them differs
+        // (/opsx-propose, @opsx-propose, $openspec-propose ...) and cannot be known
+        // until tools are picked, one prompt later — so flag it rather than let the
+        // canonical form read as the literal thing to type. "Getting started"
+        // prints the real spelling once the selection is known.
+        quickStart.push(chalk.dim('  (spelling varies by tool)'));
+        quickStart.push('');
+    }
     return [
         chalk.white.bold('Welcome to OpenSpec'),
         chalk.dim('A lightweight spec-driven framework'),
         '',
         chalk.white('This setup will configure:'),
         chalk.dim('  • Agent Skills for AI tools'),
-        chalk.dim('  • /opsx:* slash commands'),
-        '',
-        chalk.white('Quick start after setup:'),
-        `  ${chalk.yellow('/opsx:new')}      ${chalk.dim('Create a change')}`,
-        `  ${chalk.yellow('/opsx:continue')} ${chalk.dim('Next artifact')}`,
-        `  ${chalk.yellow('/opsx:apply')}    ${chalk.dim('Implement tasks')}`,
+        // Not "opsx slash commands": this screen runs before tool selection, and
+        // skills-only tools (Codex, Kimi Code, ...) correctly get no command files
+        // at all. The exact spelling per tool is printed in "Getting started".
+        chalk.dim('  • Workflow commands, if supported'),
         '',
+        ...quickStart,
         chalk.cyan('Press Enter to select tools...'),
     ];
 }
@@ -46,6 +63,36 @@ function renderFrame(artLines, textLines) {
     }
     return lines.join('\n');
 }
+const REDUCED_MOTION_EXEC_OPTIONS = {
+    encoding: 'utf8',
+    timeout: 500,
+    // SIGKILL so a wedged lookup can never outlive the timeout and stall init.
+    killSignal: 'SIGKILL',
+    stdio: ['ignore', 'pipe', 'ignore'],
+};
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export function prefersReducedMotion(platform = process.platform) {
+    try {
+        if (platform === 'darwin') {
+            // The key only exists once the user has toggled Reduce Motion; when it
+            // is unset `defaults` exits non-zero and lands in the catch below.
+            const out = execFileSync('defaults', ['read', 'com.apple.universalaccess', 'reduceMotion'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === '1';
+        }
+        if (platform === 'linux') {
+            const out = execFileSync('gsettings', ['get', 'org.gnome.desktop.interface', 'enable-animations'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === 'false';
+        }
+    }
+    catch {
+        // Detection is best-effort only.
+    }
+    return false;
+}
 /**
  * Checks if the terminal supports animation
  */
@@ -56,54 +103,60 @@ function canAnimate() {
     // Respect NO_COLOR
     if (process.env.NO_COLOR)
         return false;
+    // Manual override for users who need reduced motion (#722). Presence is
+    // what counts: even an empty value disables the animation.
+    if (process.env.OPENSPEC_NO_ANIMATION !== undefined)
+        return false;
     // Check terminal width
     const columns = process.stdout.columns || 80;
     if (columns < MIN_WIDTH)
         return false;
+    // Last so only interactive terminals pay for the OS lookup
+    if (prefersReducedMotion())
+        return false;
     return true;
 }
 /**
  * Wait for Enter key press
  */
-function waitForEnter() {
-    return new Promise((resolve) => {
-        const { stdin } = process;
-        // Handle non-TTY gracefully
-        if (!stdin.isTTY) {
-            resolve();
-            return;
-        }
-        const wasRaw = stdin.isRaw;
-        stdin.setRawMode(true);
-        stdin.resume();
-        const onData = (data) => {
-            const char = data.toString();
-            // Enter key or Ctrl+C
-            if (char === '\r' || char === '\n' || char === '\u0003') {
-                stdin.removeListener('data', onData);
-                stdin.setRawMode(wasRaw);
-                stdin.pause();
-                // Handle Ctrl+C
-                if (char === '\u0003') {
-                    process.stdout.write('\n');
-                    process.exit(0);
-                }
-                resolve();
+async function waitForEnter() {
+    if (!process.stdin.isTTY) {
+        return;
+    }
+    // Keep all interactive input on Inquirer's keypress lifecycle. Mixing a raw
+    // `data` listener between Inquirer prompts breaks arrow/space keys on Windows.
+    const { createPrompt, isEnterKey, useKeypress } = await import('@inquirer/core');
+    const prompt = createPrompt((_config, done) => {
+        useKeypress((key) => {
+            if (key.ctrl && key.name === 'c') {
+                process.stdout.write('\n');
+                process.exit(0);
+            }
+            if (isEnterKey(key)) {
+                done(undefined);
             }
-        };
-        stdin.on('data', onData);
+        });
+        return '';
     });
+    await prompt({});
 }
 /**
  * Shows the animated welcome screen.
  * Returns when user presses Enter.
  */
-export async function showWelcomeScreen() {
-    const textLines = getWelcomeText();
-    if (!canAnimate()) {
-        // Fallback: show static welcome
+export async function showWelcomeScreen(workflows, options = {}) {
+    const textLines = getWelcomeText(workflows);
+    if (options.animate === false || !canAnimate()) {
+        // Fallback: show static welcome. The "Press Enter" line is only honest
+        // when we actually wait; in a TTY, returning immediately would let the
+        // Enter it asks for fall through into the tool picker and submit the
+        // pre-selected tools sight-unseen. Without a TTY, drop the line instead.
+        const staticLines = process.stdin.isTTY
+            ? textLines
+            : textLines.filter((line) => !line.includes('Press Enter'));
         const frame = WELCOME_ANIMATION.frames[3]; // Peak frame
-        process.stdout.write('\n' + renderFrame(frame, textLines) + '\n\n');
+        process.stdout.write('\n' + renderFrame(frame, staticLines) + '\n\n');
+        await waitForEnter();
         return;
     }
     let frameIndex = 0;

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

@@ -1,4 +1,5 @@
 import { type ChangeMetadata } from '../core/change-metadata/index.js';
+import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
 /**
  * Error thrown when change metadata validation fails.
@@ -37,6 +38,8 @@ export declare function writeChangeMetadata(changeDir: string, metadata: ChangeM
 export declare function readChangeMetadata(changeDir: string, projectRoot?: string): ChangeMetadata | null;
 export interface ResolveSchemaForChangeOptions {
     metadata?: ChangeMetadata | null;
+    /** Pre-read project config; suppresses the fallback config read when provided. */
+    projectConfig?: ProjectConfig | null;
 }
 /**
  * Resolves the schema for a change, with explicit override taking precedence.
@@ -52,4 +55,31 @@ export interface ResolveSchemaForChangeOptions {
  * @returns The resolved schema name
  */
 export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+export interface SkipSpecsMarker {
+    /**
+     * True when the metadata parses under ChangeMetadataSchema, sets
+     * skip_specs: true, and names a schema that loads.
+     */
+    declared: boolean;
+    /**
+     * Set when the marker cannot be honored: skip_specs appears in a file that
+     * fails the metadata contract, or the metadata file exists but cannot be
+     * read at all (so whether the marker is set cannot even be determined).
+     */
+    invalidReason?: string;
+}
+/**
+ * Non-throwing read of the skip_specs marker. The marker only counts when the
+ * metadata would load for status/instructions: the file parses under
+ * ChangeMetadataSchema, its schema name passes readChangeMetadata's
+ * listSchemas membership check, AND the schema itself loads via resolveSchema
+ * (a schema.yaml that exists but does not parse fails status just the same).
+ * Validate and archive must never honor metadata the rest of the CLI rejects,
+ * in either direction. The project root for schema resolution is derived from
+ * changeDir exactly like resolveSchemaForChange (changeDir is
+ * <root>/openspec/changes/<name> for every root type, including store roots).
+ * Missing metadata means "not declared"; a marker that cannot be honored
+ * yields invalidReason so callers can say why.
+ */
+export declare function readSkipSpecsMarker(changeDir: string): SkipSpecsMarker;
 //# sourceMappingURL=change-metadata.d.ts.map

package/dist/utils/change-metadata.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
 import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
-import { listSchemas } from '../core/artifact-graph/resolver.js';
+import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
 export const METADATA_FILENAME = '.openspec.yaml';
 /**
@@ -126,16 +126,110 @@ export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOve
         return metadata.schema;
     }
     // 3. Try reading from project config when metadata is absent.
-    try {
-        const config = readProjectConfig(projectRoot);
-        if (config?.schema) {
-            return config.schema;
+    if (options.projectConfig !== undefined) {
+        if (options.projectConfig?.schema) {
+            return options.projectConfig.schema;
         }
     }
-    catch {
-        // If config read fails, fall back to default
+    else {
+        try {
+            const config = readProjectConfig(projectRoot);
+            if (config?.schema) {
+                return config.schema;
+            }
+        }
+        catch {
+            // If config read fails, fall back to default
+        }
     }
     // 4. Default
     return 'spec-driven';
 }
+/**
+ * Non-throwing read of the skip_specs marker. The marker only counts when the
+ * metadata would load for status/instructions: the file parses under
+ * ChangeMetadataSchema, its schema name passes readChangeMetadata's
+ * listSchemas membership check, AND the schema itself loads via resolveSchema
+ * (a schema.yaml that exists but does not parse fails status just the same).
+ * Validate and archive must never honor metadata the rest of the CLI rejects,
+ * in either direction. The project root for schema resolution is derived from
+ * changeDir exactly like resolveSchemaForChange (changeDir is
+ * <root>/openspec/changes/<name> for every root type, including store roots).
+ * Missing metadata means "not declared"; a marker that cannot be honored
+ * yields invalidReason so callers can say why.
+ */
+export function readSkipSpecsMarker(changeDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return { declared: false };
+        }
+        // The file exists but cannot be read (EACCES, EISDIR, ...). Status and
+        // instructions reject the change outright here, and whether a marker is
+        // set cannot be determined - fail closed rather than let archive treat
+        // the change as unmarked while every metadata-reading surface errors.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            declared: false,
+            invalidReason: `the metadata file cannot be read (${message})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        // Anchored so a comment like "# maybe add skip_specs later" does not
+        // claim the marker was set.
+        return /^\s*(['"]?)skip_specs\1\s*:/m.test(raw)
+            ? { declared: false, invalidReason: 'the file is not valid YAML' }
+            : { declared: false };
+    }
+    const result = ChangeMetadataSchema.safeParse(parsed);
+    if (result.success) {
+        if (result.data.skip_specs !== true) {
+            return { declared: false };
+        }
+        // Schema loading is checked only when the marker is set: a broken schema
+        // on an ordinary change is status's problem to report, but honoring a
+        // marker that status rejects would let validate/archive pass what the
+        // rest of the CLI refuses to load. The membership check mirrors
+        // readChangeMetadata (which rejects names like 'spec-driven.yaml' that
+        // resolveSchema alone would normalize and accept); resolveSchema then
+        // proves the schema actually parses. Any failure fails closed.
+        try {
+            const projectRoot = path.resolve(changeDir, '../../..');
+            if (!listSchemas(projectRoot).includes(result.data.schema)) {
+                return {
+                    declared: false,
+                    invalidReason: `schema: unknown schema '${result.data.schema}'`,
+                };
+            }
+            resolveSchema(result.data.schema, projectRoot);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { declared: false, invalidReason: message };
+        }
+        return { declared: true };
+    }
+    // Key presence, not value: skip_specs: "yes" must surface as unhonorable,
+    // not vanish while the zero-delta guidance tells the user to set the very
+    // marker they set. An explicit skip_specs: false is the opposite of setting
+    // the marker, so it must not drag unrelated metadata problems into
+    // validate - the change simply is not marked.
+    const markerMentioned = typeof parsed === 'object' &&
+        parsed !== null &&
+        'skip_specs' in parsed &&
+        parsed.skip_specs !== false;
+    if (markerMentioned) {
+        const first = result.error.issues[0];
+        const where = first.path.length > 0 ? `${first.path.join('.')}: ` : '';
+        return { declared: false, invalidReason: `${where}${first.message}` };
+    }
+    return { declared: false };
+}
 //# sourceMappingURL=change-metadata.js.map

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

@@ -31,17 +31,23 @@ export interface ValidationResult {
 /**
  * Validates that a change name follows kebab-case conventions.
  *
- * Valid names:
- * - Start with a lowercase letter
+ * Uses OpenSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
  * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
  *
  * @param name - The change name to validate
  * @returns Validation result with `valid: true` or `valid: false` with an error message
  *
  * @example
  * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
  * validateChangeName('Add-Auth') // { valid: false, error: '...' }
  */
 export declare function validateChangeName(name: string): ValidationResult;