@kbdavis07/openspec 1.5.0-nov.1

package/dist/ui/welcome-screen.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+import chalk from 'chalk';
+import { WELCOME_ANIMATION } from './ascii-patterns.js';
+// Minimum terminal width for side-by-side layout
+const MIN_WIDTH = 60;
+// Width of the ASCII art column (with padding)
+const ART_COLUMN_WIDTH = 24;
+/**
+ * Welcome text content (right column)
+ */
+function getWelcomeText() {
+    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')}`,
+        '',
+        chalk.cyan('Press Enter to select tools...'),
+    ];
+}
+/**
+ * Renders a single frame with side-by-side layout
+ */
+function renderFrame(artLines, textLines) {
+    const maxLines = Math.max(artLines.length, textLines.length);
+    const lines = [];
+    for (let i = 0; i < maxLines; i++) {
+        const artLine = artLines[i] || '';
+        const textLine = textLines[i] || '';
+        // Pad the art column to fixed width
+        const paddedArt = artLine.padEnd(ART_COLUMN_WIDTH);
+        // Color the ASCII art with cyan for visual appeal
+        const coloredArt = chalk.cyan(paddedArt);
+        // Clear line before writing to prevent residual characters
+        lines.push(`\x1b[2K${coloredArt}${textLine}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Checks if the terminal supports animation
+ */
+function canAnimate() {
+    // Must be TTY
+    if (!process.stdout.isTTY)
+        return false;
+    // Respect NO_COLOR
+    if (process.env.NO_COLOR)
+        return false;
+    // Check terminal width
+    const columns = process.stdout.columns || 80;
+    if (columns < MIN_WIDTH)
+        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();
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+/**
+ * Shows the animated welcome screen.
+ * Returns when user presses Enter.
+ */
+export async function showWelcomeScreen() {
+    const textLines = getWelcomeText();
+    if (!canAnimate()) {
+        // Fallback: show static welcome
+        const frame = WELCOME_ANIMATION.frames[3]; // Peak frame
+        process.stdout.write('\n' + renderFrame(frame, textLines) + '\n\n');
+        return;
+    }
+    let frameIndex = 0;
+    let running = true;
+    let isFirstRender = true;
+    // Content height for cursor movement between frames
+    const numContentLines = Math.max(WELCOME_ANIMATION.frames[0].length, textLines.length);
+    const frameHeight = numContentLines + 1; // internal newlines (11) + trailing newlines (2) = 13
+    // Total height including initial newline (for cleanup)
+    const totalHeight = frameHeight + 1; // 14
+    // Initial render
+    process.stdout.write('\n');
+    // Animation loop
+    const interval = setInterval(() => {
+        if (!running)
+            return;
+        const frame = WELCOME_ANIMATION.frames[frameIndex];
+        // Move cursor up to overwrite previous frame (always after first render)
+        if (!isFirstRender) {
+            process.stdout.write(`\x1b[${frameHeight}A`);
+        }
+        isFirstRender = false;
+        // Render current frame
+        process.stdout.write(renderFrame(frame, textLines) + '\n\n');
+        // Advance to next frame
+        frameIndex = (frameIndex + 1) % WELCOME_ANIMATION.frames.length;
+    }, WELCOME_ANIMATION.interval);
+    // Wait for Enter
+    await waitForEnter();
+    // Stop animation
+    running = false;
+    clearInterval(interval);
+    // Clear the welcome screen and move on
+    process.stdout.write(`\x1b[${totalHeight}A`);
+    for (let i = 0; i < totalHeight; i++) {
+        process.stdout.write('\x1b[2K\n'); // Clear line
+    }
+    process.stdout.write(`\x1b[${totalHeight}A`); // Move back up
+}
+//# sourceMappingURL=welcome-screen.js.map

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

@@ -0,0 +1,55 @@
+import { type ChangeMetadata } from '../core/change-metadata/index.js';
+export declare const METADATA_FILENAME = ".openspec.yaml";
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export declare class ChangeMetadataError extends Error {
+    readonly metadataPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, metadataPath: string, cause?: Error | undefined);
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export declare function validateSchemaName(schemaName: string, projectRoot?: string): string;
+/**
+ * Writes change metadata to .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export declare function writeChangeMetadata(changeDir: string, metadata: ChangeMetadata, projectRoot?: string): void;
+/**
+ * Reads change metadata from .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export declare function readChangeMetadata(changeDir: string, projectRoot?: string): ChangeMetadata | null;
+export interface ResolveSchemaForChangeOptions {
+    metadata?: ChangeMetadata | null;
+}
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists)
+ * 3. Schema from openspec/config.yaml (if exists)
+ * 4. Default 'spec-driven'
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+//# sourceMappingURL=change-metadata.d.ts.map

package/dist/utils/change-metadata.js

@@ -0,0 +1,141 @@
+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 { readProjectConfig } from '../core/project-config.js';
+export const METADATA_FILENAME = '.openspec.yaml';
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export class ChangeMetadataError extends Error {
+    metadataPath;
+    cause;
+    constructor(message, metadataPath, cause) {
+        super(message);
+        this.metadataPath = metadataPath;
+        this.cause = cause;
+        this.name = 'ChangeMetadataError';
+    }
+}
+/**
+ * Validates that a schema name is valid (exists in available schemas).
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated schema name
+ * @throws Error if schema is not found
+ */
+export function validateSchemaName(schemaName, projectRoot) {
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(schemaName)) {
+        throw new Error(`Unknown schema '${schemaName}'. Available: ${availableSchemas.join(', ')}`);
+    }
+    return schemaName;
+}
+/**
+ * Writes change metadata to .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param metadata - The metadata to write
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @throws ChangeMetadataError if validation fails or write fails
+ */
+export function writeChangeMetadata(changeDir, metadata, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    // Validate schema exists
+    validateSchemaName(metadata.schema, projectRoot);
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(metadata);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Write YAML file
+    const content = yaml.stringify(parseResult.data);
+    try {
+        fs.writeFileSync(metaPath, content, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to write metadata: ${ioError.message}`, metaPath, ioError);
+    }
+}
+/**
+ * Reads change metadata from .openspec.yaml in the change directory.
+ *
+ * @param changeDir - The path to the change directory
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The validated metadata, or null if no metadata file exists
+ * @throws ChangeMetadataError if the file exists but is invalid
+ */
+export function readChangeMetadata(changeDir, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    if (!fs.existsSync(metaPath)) {
+        return null;
+    }
+    let content;
+    try {
+        content = fs.readFileSync(metaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to read metadata: ${ioError.message}`, metaPath, ioError);
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(content);
+    }
+    catch (err) {
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Invalid YAML in metadata file: ${parseError.message}`, metaPath, parseError);
+    }
+    // Validate with Zod
+    const parseResult = ChangeMetadataSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    // Validate that the schema exists
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(parseResult.data.schema)) {
+        throw new ChangeMetadataError(`Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`, metaPath);
+    }
+    return parseResult.data;
+}
+/**
+ * Resolves the schema for a change, with explicit override taking precedence.
+ *
+ * Resolution order:
+ * 1. Explicit schema (if provided)
+ * 2. Schema from .openspec.yaml metadata (if exists)
+ * 3. Schema from openspec/config.yaml (if exists)
+ * 4. Default 'spec-driven'
+ *
+ * @param changeDir - The path to the change directory
+ * @param explicitSchema - Optional explicit schema override
+ * @returns The resolved schema name
+ */
+export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOverride, options = {}) {
+    // Derive project root from changeDir (changeDir is typically projectRoot/openspec/changes/change-name)
+    const projectRoot = projectRootOverride ?? path.resolve(changeDir, '../../..');
+    // 1. Explicit override wins
+    if (explicitSchema) {
+        return explicitSchema;
+    }
+    const metadata = options.metadata !== undefined ? options.metadata : readChangeMetadata(changeDir, projectRoot);
+    if (metadata?.schema) {
+        return metadata.schema;
+    }
+    // 3. Try reading from project config when metadata is absent.
+    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';
+}
+//# sourceMappingURL=change-metadata.js.map

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

@@ -0,0 +1,85 @@
+import type { ChangeMetadata } from '../core/change-metadata/index.js';
+/**
+ * Options for creating a change.
+ */
+export interface CreateChangeOptions {
+    /** The workflow schema to use (default: 'spec-driven') */
+    schema?: string;
+    /** Default schema to use when no explicit schema or project config is present */
+    defaultSchema?: string;
+    /** Directory that should contain the change directories */
+    changesDir?: string;
+    /** Additional metadata to persist in the change's .openspec.yaml */
+    metadata?: Partial<Pick<ChangeMetadata, 'goal' | 'affected_areas' | 'initiative'>>;
+}
+/**
+ * Result of creating a change.
+ */
+export interface CreateChangeResult {
+    /** The schema that was actually used (resolved from options, config, or default) */
+    schema: string;
+    /** Absolute path to the created change directory */
+    changeDir: string;
+}
+/**
+ * Result of validating a change name.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates an existing change path for safe filesystem lookup.
+ *
+ * Accepts paths that include a single feature-group prefix, e.g.
+ * "02-Session/10-session-token-rotation". Enforces only security rules
+ * (no path traversal, no absolute paths, max one separator level).
+ * Does NOT enforce kebab-case, so numbered or mixed-case group/change
+ * folder names used in this project are all accepted.
+ *
+ * @param name - The change name or group/change path to validate
+ * @returns Validation result
+ */
+export declare function validateChangeExistingPath(name: string): ValidationResult;
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter OR digit (numeric prefixes like 10- are allowed)
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @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('10-session-flow')   // { valid: true }
+ * validateChangeName('Add-Auth')          // { valid: false, error: '...' }
+ */
+export declare function validateChangeName(name: string): ValidationResult;
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @returns Result containing the resolved schema name
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with default schema
+ * const result = await createChange('/path/to/project', 'add-auth')
+ * console.log(result.schema) // 'spec-driven' or value from config
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with custom schema
+ * const result = await createChange('/path/to/project', 'add-auth', { schema: 'my-workflow' })
+ * console.log(result.schema) // 'my-workflow'
+ */
+export declare function createChange(projectRoot: string, name: string, options?: CreateChangeOptions): Promise<CreateChangeResult>;
+//# sourceMappingURL=change-utils.d.ts.map

package/dist/utils/change-utils.js

@@ -0,0 +1,173 @@
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
+import { readProjectConfig } from '../core/project-config.js';
+const DEFAULT_SCHEMA = 'spec-driven';
+/**
+ * Validates an existing change path for safe filesystem lookup.
+ *
+ * Accepts paths that include a single feature-group prefix, e.g.
+ * "02-Session/10-session-token-rotation". Enforces only security rules
+ * (no path traversal, no absolute paths, max one separator level).
+ * Does NOT enforce kebab-case, so numbered or mixed-case group/change
+ * folder names used in this project are all accepted.
+ *
+ * @param name - The change name or group/change path to validate
+ * @returns Validation result
+ */
+export function validateChangeExistingPath(name) {
+    if (!name) {
+        return { valid: false, error: 'Change name cannot be empty' };
+    }
+    if (name.includes('\0')) {
+        return { valid: false, error: 'Change name cannot contain null bytes' };
+    }
+    if (path.isAbsolute(name)) {
+        return { valid: false, error: 'Change name cannot be an absolute path' };
+    }
+    // Normalise to forward slashes for consistent traversal check
+    const normalised = name.replace(/\\/g, '/');
+    if (normalised.split('/').some((seg) => seg === '..')) {
+        return { valid: false, error: 'Change name cannot contain path traversal ("..")' };
+    }
+    const parts = normalised.split('/');
+    if (parts.length > 2) {
+        return { valid: false, error: 'Change path may contain at most one group prefix ("group/change-name")' };
+    }
+    return { valid: true };
+}
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter OR digit (numeric prefixes like 10- are allowed)
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @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('10-session-flow')   // { valid: true }
+ * validateChangeName('Add-Auth')          // { valid: false, error: '...' }
+ */
+export function validateChangeName(name) {
+    // Pattern: starts with a lowercase letter or digit, followed by lowercase letters/numbers,
+    // optionally followed by hyphen + lowercase letters/numbers (repeatable)
+    const kebabCasePattern = /^[a-z0-9][a-z0-9]*(-[a-z0-9]+)*$/;
+    if (!name) {
+        return { valid: false, error: 'Change name cannot be empty' };
+    }
+    if (!kebabCasePattern.test(name)) {
+        // Provide specific error messages for common mistakes
+        if (/[A-Z]/.test(name)) {
+            return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
+        }
+        if (/\s/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain spaces (use hyphens instead)' };
+        }
+        if (/_/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain underscores (use hyphens instead)' };
+        }
+        if (name.startsWith('-')) {
+            return { valid: false, error: 'Change name cannot start with a hyphen' };
+        }
+        if (name.endsWith('-')) {
+            return { valid: false, error: 'Change name cannot end with a hyphen' };
+        }
+        if (/--/.test(name)) {
+            return { valid: false, error: 'Change name cannot contain consecutive hyphens' };
+        }
+        if (/[^a-z0-9-]/.test(name)) {
+            return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
+        }
+        return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, 10-session-flow)' };
+    }
+    return { valid: true };
+}
+/**
+ * Creates a new change directory with metadata file.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @param options - Optional settings for the change
+ * @throws Error if the change name is invalid
+ * @throws Error if the schema name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @returns Result containing the resolved schema name
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with default schema
+ * const result = await createChange('/path/to/project', 'add-auth')
+ * console.log(result.schema) // 'spec-driven' or value from config
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/ with custom schema
+ * const result = await createChange('/path/to/project', 'add-auth', { schema: 'my-workflow' })
+ * console.log(result.schema) // 'my-workflow'
+ */
+export async function createChange(projectRoot, name, options = {}) {
+    // For paths with a group prefix (e.g. "02-Session/10-my-change") use the
+    // security-only validator; for plain names use the full kebab-case validator.
+    const hasGroupPrefix = name.replace(/\\/g, '/').includes('/');
+    const validation = hasGroupPrefix
+        ? validateChangeExistingPath(name)
+        : validateChangeName(name);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    const defaultSchema = options.defaultSchema ?? DEFAULT_SCHEMA;
+    // Determine schema: explicit option → project config → supplied default
+    let schemaName;
+    if (options.schema) {
+        schemaName = options.schema;
+    }
+    else {
+        // Try to read from project config
+        try {
+            const config = readProjectConfig(projectRoot);
+            schemaName = config?.schema ?? defaultSchema;
+        }
+        catch {
+            // If config read fails, use default
+            schemaName = defaultSchema;
+        }
+    }
+    // Validate the resolved schema
+    validateSchemaName(schemaName, projectRoot);
+    // Build the change directory path
+    const changeDir = path.join(options.changesDir ?? path.join(projectRoot, 'openspec', 'changes'), name);
+    // Check if change already exists
+    if (await FileSystemUtils.directoryExists(changeDir)) {
+        throw new Error(`Change '${name}' already exists at ${changeDir}`);
+    }
+    // Creating a change may scaffold or complete the root itself (an
+    // implicit root, or a config-only/incomplete clone). Never leave a
+    // half-root behind that doctor immediately calls unhealthy: ensure
+    // specs/ and changes/archive/ exist, and write a config only when
+    // none exists. The config records the PROJECT default schema, never
+    // a one-change --schema override.
+    const openspecDir = path.join(projectRoot, 'openspec');
+    // Create the directory (including parent directories if needed)
+    await FileSystemUtils.createDirectory(changeDir);
+    await FileSystemUtils.createDirectory(path.join(openspecDir, 'specs'));
+    await FileSystemUtils.createDirectory(path.join(openspecDir, 'changes', 'archive'));
+    const configPath = path.join(openspecDir, 'config.yaml');
+    const configYmlPath = path.join(openspecDir, 'config.yml');
+    if (!(await FileSystemUtils.fileExists(configPath)) &&
+        !(await FileSystemUtils.fileExists(configYmlPath))) {
+        await FileSystemUtils.writeFile(configPath, `schema: ${defaultSchema}\n`);
+    }
+    // Write metadata file with schema and creation date
+    const today = new Date().toISOString().split('T')[0];
+    writeChangeMetadata(changeDir, {
+        schema: schemaName,
+        created: today,
+        ...options.metadata,
+    }, projectRoot);
+    return { schema: schemaName, changeDir };
+}
+//# sourceMappingURL=change-utils.js.map

package/dist/utils/command-references.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Command Reference Utilities
+ *
+ * Utilities for transforming command references to tool-specific formats.
+ */
+/**
+ * Transforms colon-based command references to hyphen-based format.
+ * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to hyphen format
+ *
+ * @example
+ * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
+ * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ */
+export declare function transformToHyphenCommands(text: string): string;
+//# sourceMappingURL=command-references.d.ts.map

package/dist/utils/command-references.js

@@ -0,0 +1,20 @@
+/**
+ * Command Reference Utilities
+ *
+ * Utilities for transforming command references to tool-specific formats.
+ */
+/**
+ * Transforms colon-based command references to hyphen-based format.
+ * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to hyphen format
+ *
+ * @example
+ * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
+ * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ */
+export function transformToHyphenCommands(text) {
+    return text.replace(/\/opsx:/g, '/opsx-');
+}
+//# sourceMappingURL=command-references.js.map

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

@@ -0,0 +1,41 @@
+export declare class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p: string): string;
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath: string): string;
+    private static isWindowsBasePath;
+    private static normalizeSegments;
+    static joinPath(basePath: string, ...segments: string[]): string;
+    static createDirectory(dirPath: string): Promise<void>;
+    static fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    private static findFirstExistingDirectory;
+    static canWriteFile(filePath: string): Promise<boolean>;
+    static directoryExists(dirPath: string): Promise<boolean>;
+    static writeFile(filePath: string, content: string): Promise<void>;
+    static readFile(filePath: string): Promise<string>;
+    static updateFileWithMarkers(filePath: string, content: string, startMarker: string, endMarker: string): Promise<void>;
+    static ensureWritePermissions(dirPath: string): Promise<boolean>;
+}
+/**
+ * Removes a marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with markers
+ * @param startMarker - The start marker string
+ * @param endMarker - The end marker string
+ * @returns Content with marker block removed, or original content if markers not found/invalid
+ */
+export declare function removeMarkerBlock(content: string, startMarker: string, endMarker: string): string;
+//# sourceMappingURL=file-system.d.ts.map