@fission-ai/openspec 1.6.0 → 1.8.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/config.d.ts

@@ -1,9 +1,8 @@
+import { type TelemetryConfig } from '../core/global-config.js';
 export declare const CONFIG_DIR_NAME = "openspec";
 export declare const CONFIG_FILE_NAME = "config.json";
-export interface TelemetryConfig {
-    anonymousId?: string;
-    noticeSeen?: boolean;
-}
+/** Re-export shared telemetry section type (single source of truth in global-config). */
+export type { TelemetryConfig };
 export interface GlobalConfig {
     telemetry?: TelemetryConfig;
     [key: string]: unknown;

package/dist/telemetry/index.d.ts

@@ -1,10 +1,15 @@
 /**
  * Check if telemetry is enabled.
  *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
+ * Precedence (first match wins):
+ * 1. OPENSPEC_TELEMETRY=0 → disabled
+ * 2. DO_NOT_TRACK=1 → disabled
+ * 3. CI set to a truthy/on value → disabled (same rule as version-check)
+ * 4. global config telemetry.enabled === false → disabled
+ * 5. otherwise enabled (unset config means on; opt-out model)
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
  */
 export declare function isTelemetryEnabled(): boolean;
 /**
@@ -24,7 +29,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

@@ -4,12 +4,24 @@
  * Privacy-first design:
  * - Only tracks command name and version
  * - No arguments, file paths, or content
- * - Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
+ * - Opt-out via OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, or
+ *   `openspec config set telemetry.enabled false`
  * - 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 { getGlobalConfig } from '../core/global-config.js';
+import { isCiEnvironment } from '../utils/ci.js';
 import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
 // PostHog API key - public key for client-side analytics
 // This is safe to embed as it only allows sending events, not reading data
@@ -17,11 +29,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;
         }
@@ -34,10 +58,15 @@ async function safeTelemetryFetch(url, options) {
 /**
  * Check if telemetry is enabled.
  *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
+ * Precedence (first match wins):
+ * 1. OPENSPEC_TELEMETRY=0 → disabled
+ * 2. DO_NOT_TRACK=1 → disabled
+ * 3. CI set to a truthy/on value → disabled (same rule as version-check)
+ * 4. global config telemetry.enabled === false → disabled
+ * 5. otherwise enabled (unset config means on; opt-out model)
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
  */
 export function isTelemetryEnabled() {
     // Check explicit opt-out
@@ -48,8 +77,12 @@ export function isTelemetryEnabled() {
     if (process.env.DO_NOT_TRACK === '1') {
         return false;
     }
-    // Auto-disable in CI environments
-    if (process.env.CI === 'true') {
+    // Auto-disable in CI environments (providers use true/1/yes/…)
+    if (isCiEnvironment()) {
+        return false;
+    }
+    // Global config opt-out (env/CI remain hard overrides above)
+    if (getGlobalConfig().telemetry?.enabled === false) {
         return false;
     }
     return true;
@@ -75,24 +108,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 +145,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 {
@@ -135,7 +169,7 @@ export async function maybeShowTelemetryNotice() {
             return;
         }
         // Display notice
-        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0');
+        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false');
         // Mark as seen
         await updateTelemetryConfig({ noticeSeen: true });
     }
@@ -144,21 +178,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,44 @@ export interface ResolveSchemaForChangeOptions {
  * @returns The resolved schema name
  */
 export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+export interface MetadataMarker {
+    /**
+     * True when the metadata parses under ChangeMetadataSchema, sets
+     * the requested boolean marker to true, and names a schema that loads.
+     */
+    declared: boolean;
+    /**
+     * Set when the marker cannot be honored: it 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;
+}
+/** @deprecated Use MetadataMarker. */
+export type SkipSpecsMarker = MetadataMarker;
+/**
+ * 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): MetadataMarker;
+/**
+ * Non-throwing read of the retire_capabilities marker, with exactly the
+ * semantics `readSkipSpecsMarker` documents above.
+ *
+ * Gates the one archive action that removes a file from `openspec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export declare function readRetireCapabilitiesMarker(changeDir: string): MetadataMarker;
 //# sourceMappingURL=change-metadata.d.ts.map