@codewalla_india/openspec 1.0.1

package/dist/commands/shared-gather.d.ts

@@ -0,0 +1,14 @@
+import { type RegistrySnapshot } from '../core/store/registry.js';
+import { type ProjectConfig } from '../core/project-config.js';
+import { type ReferenceIndexEntry } from '../core/references.js';
+import { type OpenSpecRootInspection } from '../core/openspec-root.js';
+import type { ResolvedOpenSpecRoot } from '../core/root-selection.js';
+export interface RelationshipData {
+    registrySnapshot: RegistrySnapshot;
+    projectConfig: ProjectConfig | null;
+    storeConfigPath: string;
+    referenceEntries: ReferenceIndexEntry[];
+    rootInspection: OpenSpecRootInspection;
+}
+export declare function gatherRelationshipData(root: ResolvedOpenSpecRoot): Promise<RelationshipData>;
+//# sourceMappingURL=shared-gather.d.ts.map

package/dist/commands/shared-gather.js

@@ -0,0 +1,31 @@
+/**
+ * The relationship-data gather shared by doctor and context (4.1): one
+ * registry snapshot, the health-mode reference index, and the root
+ * inspection. Doctor layers its health-only inputs (store facts,
+ * wrong-turn detection) on top.
+ */
+import * as path from 'node:path';
+import { readRegistrySnapshot } from '../core/store/registry.js';
+import { readProjectConfig, resolveConfigFilePath, } from '../core/project-config.js';
+import { assembleReferenceIndex } from '../core/references.js';
+import { inspectOpenSpecRoot } from '../core/openspec-root.js';
+export async function gatherRelationshipData(root) {
+    const registrySnapshot = await readRegistrySnapshot();
+    const projectConfig = readProjectConfig(root.path);
+    const storeConfigPath = resolveConfigFilePath(root.path) ?? path.join(root.path, 'openspec', 'config.yaml');
+    const referenceEntries = await assembleReferenceIndex({
+        references: projectConfig?.references ?? [],
+        resolvedRoot: root,
+        includeSpecs: false,
+        registryEntries: registrySnapshot.entries,
+    });
+    const rootInspection = await inspectOpenSpecRoot(root.path);
+    return {
+        registrySnapshot,
+        projectConfig,
+        storeConfigPath,
+        referenceEntries,
+        rootInspection,
+    };
+}
+//# sourceMappingURL=shared-gather.js.map

package/dist/commands/shared-output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared JSON/failure output plumbing for command groups whose errors
+ * carry the StoreDiagnostic envelope. One definition of the failure
+ * contract: exit code 1, Error:/Fix: lines in human mode, a status
+ * array in JSON mode.
+ */
+import { type StoreDiagnostic } from '../core/store/errors.js';
+export declare function printJson(payload: unknown): void;
+export declare function asErrorMessage(error: unknown): string;
+/**
+ * @inquirer prompts reject with ExitPromptError on Ctrl-C; commands
+ * translate that to `Cancelled.` + exit 130 (third caller extracted
+ * this here in slice 7.1).
+ */
+export declare function isPromptCancellationError(error: unknown): boolean;
+export declare function asStatus(error: unknown, fallbackCode: string): StoreDiagnostic;
+export declare function emitFailure(json: boolean | undefined, payload: Record<string, unknown>, error: unknown, fallbackCode: string): void;
+//# sourceMappingURL=shared-output.d.ts.map

package/dist/commands/shared-output.js

@@ -0,0 +1,61 @@
+/**
+ * Shared JSON/failure output plumbing for command groups whose errors
+ * carry the StoreDiagnostic envelope. One definition of the failure
+ * contract: exit code 1, Error:/Fix: lines in human mode, a status
+ * array in JSON mode.
+ */
+import { StoreError } from '../core/store/errors.js';
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function asErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * @inquirer prompts reject with ExitPromptError on Ctrl-C; commands
+ * translate that to `Cancelled.` + exit 130 (third caller extracted
+ * this here in slice 7.1).
+ */
+export function isPromptCancellationError(error) {
+    return (error instanceof Error &&
+        (error.name === 'ExitPromptError' ||
+            error.message.includes('force closed the prompt with SIGINT')));
+}
+export function asStatus(error, fallbackCode) {
+    if (error instanceof StoreError) {
+        return error.diagnostic;
+    }
+    // RootSelectionError (and siblings) carry the same envelope without
+    // sharing a class hierarchy; duck-type the diagnostic once, here.
+    const diagnostic = error.diagnostic;
+    if (diagnostic && typeof diagnostic.code === 'string') {
+        return diagnostic;
+    }
+    return {
+        severity: 'error',
+        code: fallbackCode,
+        message: asErrorMessage(error),
+    };
+}
+export function emitFailure(json, payload, error, fallbackCode) {
+    // Ctrl-C in a prompt is the user's choice, not an error: every
+    // command group gets the Cancelled./130 convention through here.
+    if (!json && isPromptCancellationError(error)) {
+        console.error('Cancelled.');
+        process.exitCode = 130;
+        return;
+    }
+    const status = asStatus(error, fallbackCode);
+    if (json) {
+        const prior = Array.isArray(payload.status) ? payload.status : [];
+        printJson({ ...payload, status: [...prior, status] });
+        process.exitCode = 1;
+        return;
+    }
+    console.error(`Error: ${status.message}`);
+    if (status.fix) {
+        console.error(`Fix: ${status.fix}`);
+    }
+    process.exitCode = 1;
+}
+//# sourceMappingURL=shared-output.js.map

package/dist/commands/show.d.ts

@@ -0,0 +1,19 @@
+interface ShowExecuteOptions {
+    json?: boolean;
+    type?: string;
+    noInteractive?: boolean;
+    store?: string;
+    storePath?: string;
+    [k: string]: any;
+}
+export declare class ShowCommand {
+    execute(itemName?: string, options?: ShowExecuteOptions): Promise<void>;
+    private normalizeType;
+    private delegateOptions;
+    private runInteractiveByType;
+    private showDirect;
+    private printNonInteractiveHint;
+    private warnIrrelevantFlags;
+}
+export {};
+//# sourceMappingURL=show.d.ts.map

package/dist/commands/show.js

@@ -0,0 +1,177 @@
+import { isInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
+import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../core/root-selection.js';
+import { ChangeCommand } from './change.js';
+import { SpecCommand } from './spec.js';
+import { nearestMatches } from '../utils/match.js';
+const CHANGE_FLAG_KEYS = new Set(['deltasOnly', 'requirementsOnly']);
+const SPEC_FLAG_KEYS = new Set(['requirements', 'scenarios', 'requirement']);
+export class ShowCommand {
+    async execute(itemName, options = {}) {
+        const root = await resolveRootForCommand(options, { json: options.json });
+        if (!root) {
+            return;
+        }
+        const interactive = isInteractive(options);
+        const typeOverride = this.normalizeType(options.type);
+        if (!itemName) {
+            if (interactive) {
+                const { select } = await import('@inquirer/prompts');
+                const type = await select({
+                    message: 'What would you like to show?',
+                    choices: [
+                        { name: 'Change', value: 'change' },
+                        { name: 'Spec', value: 'spec' },
+                    ],
+                });
+                await this.runInteractiveByType(type, options, root);
+                return;
+            }
+            this.printNonInteractiveHint(root);
+            process.exitCode = 1;
+            return;
+        }
+        await this.showDirect(itemName, { typeOverride, options, root });
+    }
+    normalizeType(value) {
+        if (!value)
+            return undefined;
+        const v = value.toLowerCase();
+        if (v === 'change' || v === 'spec')
+            return v;
+        return undefined;
+    }
+    delegateOptions(root, options) {
+        return {
+            ...options,
+            ...(options.json ? { rootOutput: toRootOutput(root) } : {}),
+        };
+    }
+    async runInteractiveByType(type, options, root) {
+        const { select } = await import('@inquirer/prompts');
+        if (type === 'change') {
+            const changes = await getActiveChangeIds(root.path);
+            if (changes.length === 0) {
+                console.error('No changes found.');
+                process.exitCode = 1;
+                return;
+            }
+            const picked = await select({ message: 'Pick a change', choices: changes.map(id => ({ name: id, value: id })) });
+            const cmd = new ChangeCommand(root.path);
+            await cmd.show(picked, this.delegateOptions(root, options));
+            return;
+        }
+        const specs = await getSpecIds(root.path);
+        if (specs.length === 0) {
+            console.error('No specs found.');
+            process.exitCode = 1;
+            return;
+        }
+        const picked = await select({ message: 'Pick a spec', choices: specs.map(id => ({ name: id, value: id })) });
+        const cmd = new SpecCommand(root.path);
+        await cmd.show(picked, this.delegateOptions(root, options));
+    }
+    async showDirect(itemName, params) {
+        const root = params.root;
+        // Optimize lookups when type is pre-specified
+        let isChange = false;
+        let isSpec = false;
+        let changes = [];
+        let specs = [];
+        if (params.typeOverride === 'change') {
+            changes = await getActiveChangeIds(root.path);
+            isChange = changes.includes(itemName);
+        }
+        else if (params.typeOverride === 'spec') {
+            specs = await getSpecIds(root.path);
+            isSpec = specs.includes(itemName);
+        }
+        else {
+            [changes, specs] = await Promise.all([getActiveChangeIds(root.path), getSpecIds(root.path)]);
+            isChange = changes.includes(itemName);
+            isSpec = specs.includes(itemName);
+        }
+        const resolvedType = params.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
+        if (!resolvedType) {
+            const suggestions = nearestMatches(itemName, [...changes, ...specs]);
+            const message = suggestions.length
+                ? `Unknown item '${itemName}'. Did you mean: ${suggestions.join(', ')}?`
+                : `Unknown item '${itemName}'.`;
+            if (params.options.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code: 'unknown_item', message }] }, null, 2));
+            }
+            else {
+                console.error(message);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (!params.typeOverride && isChange && isSpec) {
+            if (params.options.json) {
+                console.log(JSON.stringify({
+                    status: [
+                        {
+                            severity: 'error',
+                            code: 'ambiguous_item',
+                            message: `Ambiguous item '${itemName}' matches both a change and a spec.`,
+                            fix: 'Pass --type change|spec.',
+                        },
+                    ],
+                }, null, 2));
+                process.exitCode = 1;
+                return;
+            }
+            console.error(`Ambiguous item '${itemName}' matches both a change and a spec.`);
+            // The noun-form commands are cwd-based and cannot reach a selected store.
+            if (isStoreSelectedRoot(root)) {
+                console.error('Pass --type change|spec.');
+            }
+            else {
+                console.error('Pass --type change|spec, or use: openspec change show / openspec spec show');
+            }
+            process.exitCode = 1;
+            return;
+        }
+        this.warnIrrelevantFlags(resolvedType, params.options);
+        if (resolvedType === 'change') {
+            const cmd = new ChangeCommand(root.path);
+            await cmd.show(itemName, this.delegateOptions(root, params.options));
+            return;
+        }
+        const cmd = new SpecCommand(root.path);
+        await cmd.show(itemName, this.delegateOptions(root, params.options));
+    }
+    printNonInteractiveHint(root) {
+        console.error('Nothing to show. Try one of:');
+        console.error(`  ${withStoreFlag(root, 'openspec show <item>')}`);
+        if (isStoreSelectedRoot(root)) {
+            // The noun-form commands are cwd-based and cannot reach a selected store.
+            console.error(`  ${withStoreFlag(root, 'openspec show <item> --type change')}`);
+            console.error(`  ${withStoreFlag(root, 'openspec show <item> --type spec')}`);
+        }
+        else {
+            console.error('  openspec change show');
+            console.error('  openspec spec show');
+        }
+        console.error('Or run in an interactive terminal.');
+    }
+    warnIrrelevantFlags(type, options) {
+        const irrelevant = [];
+        if (type === 'change') {
+            for (const k of SPEC_FLAG_KEYS)
+                if (k in options)
+                    irrelevant.push(k);
+        }
+        else {
+            for (const k of CHANGE_FLAG_KEYS)
+                if (k in options)
+                    irrelevant.push(k);
+        }
+        if (irrelevant.length > 0) {
+            console.error(`Warning: Ignoring flags not applicable to ${type}: ${irrelevant.join(', ')}`);
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=show.js.map

package/dist/commands/spec.d.ts

@@ -0,0 +1,19 @@
+import { program } from 'commander';
+import type { RootOutput } from '../core/root-selection.js';
+interface ShowOptions {
+    json?: boolean;
+    requirements?: boolean;
+    scenarios?: boolean;
+    requirement?: string;
+    noInteractive?: boolean;
+    rootOutput?: RootOutput;
+}
+export declare class SpecCommand {
+    private specsDir;
+    private rootPath?;
+    constructor(rootPath?: string);
+    show(specId?: string, options?: ShowOptions): Promise<void>;
+}
+export declare function registerSpecCommand(rootProgram: typeof program): import("commander").Command;
+export {};
+//# sourceMappingURL=spec.d.ts.map

package/dist/commands/spec.js

@@ -0,0 +1,236 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { MarkdownParser } from '../core/parsers/markdown-parser.js';
+import { Validator } from '../core/validation/validator.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getSpecIds } from '../utils/item-discovery.js';
+const SPECS_DIR = 'openspec/specs';
+function parseSpecFromFile(specPath, specId) {
+    const content = readFileSync(specPath, 'utf-8');
+    const parser = new MarkdownParser(content);
+    return parser.parseSpec(specId);
+}
+function validateRequirementIndex(spec, requirementOpt) {
+    if (!requirementOpt)
+        return undefined;
+    const index = Number.parseInt(requirementOpt, 10);
+    if (!Number.isInteger(index) || index < 1 || index > spec.requirements.length) {
+        throw new Error(`Requirement ${requirementOpt} not found`);
+    }
+    return index - 1; // convert to 0-based
+}
+function filterSpec(spec, options) {
+    const requirementIndex = validateRequirementIndex(spec, options.requirement);
+    const includeScenarios = options.scenarios !== false && !options.requirements;
+    const filteredRequirements = (requirementIndex !== undefined
+        ? [spec.requirements[requirementIndex]]
+        : spec.requirements).map(req => ({
+        text: req.text,
+        scenarios: includeScenarios ? req.scenarios : [],
+    }));
+    const metadata = spec.metadata ?? { version: '1.0.0', format: 'openspec' };
+    return {
+        name: spec.name,
+        overview: spec.overview,
+        requirements: filteredRequirements,
+        metadata,
+    };
+}
+/**
+ * Print the raw markdown content for a spec file without any formatting.
+ * Raw-first behavior ensures text mode is a passthrough for deterministic output.
+ */
+function printSpecTextRaw(specPath) {
+    const content = readFileSync(specPath, 'utf-8');
+    console.log(content);
+}
+export class SpecCommand {
+    specsDir;
+    rootPath;
+    // rootPath is set only by root-aware callers (top-level `show`); the
+    // deprecated noun-form commands stay cwd-based.
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+        this.specsDir = rootPath ? join(rootPath, 'openspec', 'specs') : SPECS_DIR;
+    }
+    async show(specId, options = {}) {
+        if (!specId) {
+            const canPrompt = isInteractive(options);
+            const specIds = await getSpecIds(this.rootPath ?? process.cwd());
+            if (canPrompt && specIds.length > 0) {
+                const { select } = await import('@inquirer/prompts');
+                specId = await select({
+                    message: 'Select a spec to show',
+                    choices: specIds.map(id => ({ name: id, value: id })),
+                });
+            }
+            else {
+                throw new Error('Missing required argument <spec-id>');
+            }
+        }
+        const specPath = join(this.specsDir, specId, 'spec.md');
+        if (!existsSync(specPath)) {
+            // Root-aware callers get the absolute path; the cwd-based noun form
+            // keeps its historical forward-slash relative message on all platforms.
+            const displayPath = this.rootPath ? specPath : `openspec/specs/${specId}/spec.md`;
+            throw new Error(`Spec '${specId}' not found at ${displayPath}`);
+        }
+        if (options.json) {
+            if (options.requirements && options.requirement) {
+                throw new Error('Options --requirements and --requirement cannot be used together');
+            }
+            const parsed = parseSpecFromFile(specPath, specId);
+            const filtered = filterSpec(parsed, options);
+            const output = {
+                id: specId,
+                title: parsed.name,
+                overview: parsed.overview,
+                requirementCount: filtered.requirements.length,
+                requirements: filtered.requirements,
+                metadata: parsed.metadata ?? { version: '1.0.0', format: 'openspec' },
+                ...(options.rootOutput ? { root: options.rootOutput } : {}),
+            };
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        printSpecTextRaw(specPath);
+    }
+}
+export function registerSpecCommand(rootProgram) {
+    const specCommand = rootProgram
+        .command('spec')
+        .description('Manage and view OpenSpec specifications');
+    // Deprecation notice for noun-based commands
+    specCommand.hook('preAction', () => {
+        console.error('Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").');
+    });
+    specCommand
+        .command('show [spec-id]')
+        .description('Display a specific specification')
+        .option('--json', 'Output as JSON')
+        .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
+        .option('--no-scenarios', 'JSON only: Exclude scenario content')
+        .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+        .option('--no-interactive', 'Disable interactive prompts')
+        .action(async (specId, options) => {
+        try {
+            const cmd = new SpecCommand();
+            await cmd.show(specId, options);
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exitCode = 1;
+        }
+    });
+    specCommand
+        .command('list')
+        .description('List all available specifications')
+        .option('--json', 'Output as JSON')
+        .option('--long', 'Show id and title with counts')
+        .action((options) => {
+        try {
+            if (!existsSync(SPECS_DIR)) {
+                console.log('No items found');
+                return;
+            }
+            const specs = readdirSync(SPECS_DIR, { withFileTypes: true })
+                .filter(dirent => dirent.isDirectory())
+                .map(dirent => {
+                const specPath = join(SPECS_DIR, dirent.name, 'spec.md');
+                if (existsSync(specPath)) {
+                    try {
+                        const spec = parseSpecFromFile(specPath, dirent.name);
+                        return {
+                            id: dirent.name,
+                            title: spec.name,
+                            requirementCount: spec.requirements.length
+                        };
+                    }
+                    catch {
+                        return {
+                            id: dirent.name,
+                            title: dirent.name,
+                            requirementCount: 0
+                        };
+                    }
+                }
+                return null;
+            })
+                .filter((spec) => spec !== null)
+                .sort((a, b) => a.id.localeCompare(b.id));
+            if (options.json) {
+                console.log(JSON.stringify(specs, null, 2));
+            }
+            else {
+                if (specs.length === 0) {
+                    console.log('No items found');
+                    return;
+                }
+                if (!options.long) {
+                    specs.forEach(spec => console.log(spec.id));
+                    return;
+                }
+                specs.forEach(spec => {
+                    console.log(`${spec.id}: ${spec.title} [requirements ${spec.requirementCount}]`);
+                });
+            }
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exitCode = 1;
+        }
+    });
+    specCommand
+        .command('validate [spec-id]')
+        .description('Validate a specification structure')
+        .option('--strict', 'Enable strict validation mode')
+        .option('--json', 'Output validation report as JSON')
+        .option('--no-interactive', 'Disable interactive prompts')
+        .action(async (specId, options) => {
+        try {
+            if (!specId) {
+                const canPrompt = isInteractive(options);
+                const specIds = await getSpecIds();
+                if (canPrompt && specIds.length > 0) {
+                    const { select } = await import('@inquirer/prompts');
+                    specId = await select({
+                        message: 'Select a spec to validate',
+                        choices: specIds.map(id => ({ name: id, value: id })),
+                    });
+                }
+                else {
+                    throw new Error('Missing required argument <spec-id>');
+                }
+            }
+            const specPath = join(SPECS_DIR, specId, 'spec.md');
+            if (!existsSync(specPath)) {
+                throw new Error(`Spec '${specId}' not found at openspec/specs/${specId}/spec.md`);
+            }
+            const validator = new Validator(options.strict);
+            const report = await validator.validateSpec(specPath);
+            if (options.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                if (report.valid) {
+                    console.log(`Specification '${specId}' is valid`);
+                }
+                else {
+                    console.error(`Specification '${specId}' has issues`);
+                    report.issues.forEach(issue => {
+                        const label = issue.level === 'ERROR' ? 'ERROR' : issue.level;
+                        const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                        console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+                    });
+                }
+            }
+            process.exitCode = report.valid ? 0 : 1;
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exitCode = 1;
+        }
+    });
+    return specCommand;
+}
+//# sourceMappingURL=spec.js.map

package/dist/commands/store.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerStoreCommand(program: Command): void;
+//# sourceMappingURL=store.d.ts.map