@codewalla_india/openspec 1.0.1

package/dist/commands/workflow/shared.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared Types and Utilities for Artifact Workflow Commands
+ *
+ * This module contains types, constants, and validation helpers used across
+ * multiple artifact workflow commands.
+ */
+import type { ReferenceIndexEntry } from '../../core/references.js';
+export interface ChangeCommandStatus {
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+    target?: string;
+    fix?: string;
+}
+export interface TaskItem {
+    id: string;
+    description: string;
+    done: boolean;
+}
+export interface ApplyComprehensionInfo {
+    required: boolean;
+    passed: boolean;
+    thresholdPercent: number;
+    bestScorePercent?: number;
+    questionCount: number;
+    requirementCount: number;
+    scenarioCount: number;
+    pendingTaskCount: number;
+    attempts?: number;
+}
+export interface ApplyInstructions {
+    changeName: string;
+    changeDir: string;
+    schemaName: string;
+    contextFiles: Record<string, string[]>;
+    progress: {
+        total: number;
+        complete: number;
+        remaining: number;
+    };
+    tasks: TaskItem[];
+    state: 'blocked' | 'all_done' | 'ready';
+    missingArtifacts?: string[];
+    missingComprehension?: boolean;
+    comprehension?: ApplyComprehensionInfo;
+    instruction: string;
+    /** Referenced-store index (read-only upstream context; omitted when none declared) */
+    references?: ReferenceIndexEntry[];
+}
+export declare const DEFAULT_SCHEMA = "spec-driven";
+export declare function printJson(payload: unknown): void;
+export declare function statusFromError(error: unknown): ChangeCommandStatus;
+/**
+ * Checks if color output is disabled via NO_COLOR env or --no-color flag.
+ */
+export declare function isColorDisabled(): boolean;
+/**
+ * Gets the color function based on status.
+ */
+export declare function getStatusColor(status: 'done' | 'ready' | 'blocked'): (text: string) => string;
+/**
+ * Gets the status indicator for an artifact.
+ */
+export declare function getStatusIndicator(status: 'done' | 'ready' | 'blocked'): string;
+/**
+ * Returns the list of available change directory names under openspec/changes/.
+ * Excludes the archive directory and hidden directories.
+ */
+export declare function getAvailableChanges(projectRoot: string, changesDir?: string): Promise<string[]>;
+/**
+ * Validates that a change exists and returns available changes if not.
+ * Checks directory existence directly to support scaffolded changes (without proposal.md).
+ */
+export declare function validateChangeExists(changeName: string | undefined, projectRoot: string, changesDir?: string, hints?: {
+    newChangeHint?: string;
+}): Promise<string>;
+/**
+ * Validates that a schema exists and returns available schemas if not.
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ */
+export declare function validateSchemaExists(schemaName: string, projectRoot?: string): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/workflow/shared.js

@@ -0,0 +1,133 @@
+/**
+ * Shared Types and Utilities for Artifact Workflow Commands
+ *
+ * This module contains types, constants, and validation helpers used across
+ * multiple artifact workflow commands.
+ */
+import chalk from 'chalk';
+import path from 'path';
+import * as fs from 'fs';
+import { getSchemaDir, listSchemas } from '../../core/artifact-graph/index.js';
+import { isRootSelectionError } from '../../core/root-selection.js';
+import { validateChangeName } from '../../utils/change-utils.js';
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+export const DEFAULT_SCHEMA = 'spec-driven';
+// -----------------------------------------------------------------------------
+// Utility Functions
+// -----------------------------------------------------------------------------
+export function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+export function statusFromError(error) {
+    if (isRootSelectionError(error)) {
+        return { ...error.diagnostic };
+    }
+    return {
+        severity: 'error',
+        code: 'change_error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+/**
+ * Checks if color output is disabled via NO_COLOR env or --no-color flag.
+ */
+export function isColorDisabled() {
+    return process.env.NO_COLOR === '1' || process.env.NO_COLOR === 'true';
+}
+/**
+ * Gets the color function based on status.
+ */
+export function getStatusColor(status) {
+    if (isColorDisabled()) {
+        return (text) => text;
+    }
+    switch (status) {
+        case 'done':
+            return chalk.green;
+        case 'ready':
+            return chalk.yellow;
+        case 'blocked':
+            return chalk.red;
+    }
+}
+/**
+ * Gets the status indicator for an artifact.
+ */
+export function getStatusIndicator(status) {
+    const color = getStatusColor(status);
+    switch (status) {
+        case 'done':
+            return color('[x]');
+        case 'ready':
+            return color('[ ]');
+        case 'blocked':
+            return color('[-]');
+    }
+}
+/**
+ * Returns the list of available change directory names under openspec/changes/.
+ * Excludes the archive directory and hidden directories.
+ */
+export async function getAvailableChanges(projectRoot, changesDir = path.join(projectRoot, 'openspec', 'changes')) {
+    const changesPath = changesDir;
+    try {
+        const entries = await fs.promises.readdir(changesPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && e.name !== 'archive' && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/**
+ * Validates that a change exists and returns available changes if not.
+ * Checks directory existence directly to support scaffolded changes (without proposal.md).
+ */
+export async function validateChangeExists(changeName, projectRoot, changesDir = path.join(projectRoot, 'openspec', 'changes'), hints = {}) {
+    // Hints must stay pasteable: callers with a selected store pass a
+    // store-carrying hint so following it lands in the same root.
+    const newChangeHint = hints.newChangeHint ?? 'openspec new change <name>';
+    if (!changeName) {
+        const available = await getAvailableChanges(projectRoot, changesDir);
+        if (available.length === 0) {
+            throw new Error(`No changes found. Create one with: ${newChangeHint}`);
+        }
+        throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    // Validate change name format to prevent path traversal
+    const nameValidation = validateChangeName(changeName);
+    if (!nameValidation.valid) {
+        throw new Error(`Invalid change name '${changeName}': ${nameValidation.error}`);
+    }
+    // Check directory existence directly
+    const changePath = path.join(changesDir, changeName);
+    const exists = fs.existsSync(changePath) && fs.statSync(changePath).isDirectory();
+    if (!exists) {
+        const available = await getAvailableChanges(projectRoot, changesDir);
+        if (available.length === 0) {
+            throw new Error(`Change '${changeName}' not found. No changes exist. Create one with: ${newChangeHint}`);
+        }
+        throw new Error(`Change '${changeName}' not found. Available changes:\n  ${available.join('\n  ')}`);
+    }
+    return changeName;
+}
+/**
+ * Validates that a schema exists and returns available schemas if not.
+ *
+ * @param schemaName - The schema name to validate
+ * @param projectRoot - Optional project root for project-local schema resolution
+ */
+export function validateSchemaExists(schemaName, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
+    if (!schemaDir) {
+        const availableSchemas = listSchemas(projectRoot);
+        throw new Error(`Schema '${schemaName}' not found. Available schemas:\n  ${availableSchemas.join('\n  ')}`);
+    }
+    return schemaName;
+}
+//# sourceMappingURL=shared.js.map

package/dist/commands/workflow/status.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Status Command
+ *
+ * Displays artifact completion status for a change.
+ */
+import { type ChangeStatus } from '../../core/artifact-graph/index.js';
+export interface StatusOptions {
+    change?: string;
+    schema?: string;
+    store?: string;
+    storePath?: string;
+    json?: boolean;
+}
+export declare function statusCommand(options: StatusOptions): Promise<void>;
+export declare function printStatusText(status: ChangeStatus): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/workflow/status.js

@@ -0,0 +1,92 @@
+/**
+ * Status Command
+ *
+ * Displays artifact completion status for a change.
+ */
+import ora from 'ora';
+import chalk from 'chalk';
+import { getChangeDir } from '../../core/planning-home.js';
+import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
+import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
+import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
+// -----------------------------------------------------------------------------
+// Command Implementation
+// -----------------------------------------------------------------------------
+export async function statusCommand(options) {
+    // The root resolves (and the store banner prints) before the spinner starts
+    // so the two do not fight over stderr.
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
+    const spinner = options.json ? undefined : ora('Loading change status...').start();
+    try {
+        const planningHome = toPlanningHome(root);
+        const projectRoot = root.path;
+        const rootOutput = toRootOutput(root);
+        const newChangeHint = withStoreFlag(root, 'openspec new change <name>');
+        // Handle no-changes case gracefully — status is informational,
+        // so "no changes" is a valid state, not an error.
+        if (!options.change) {
+            const available = await getAvailableChanges(projectRoot, root.changesDir);
+            if (available.length === 0) {
+                spinner?.stop();
+                if (options.json) {
+                    console.log(JSON.stringify({ changes: [], message: 'No active changes.', root: rootOutput }, null, 2));
+                    return;
+                }
+                console.log(`No active changes. Create one with: ${newChangeHint}`);
+                return;
+            }
+            // Changes exist but --change not provided
+            spinner?.stop();
+            throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+        }
+        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint });
+        // Validate schema if explicitly provided
+        if (options.schema) {
+            validateSchemaExists(options.schema, projectRoot);
+        }
+        // loadChangeContext will auto-detect schema from metadata if not provided
+        const context = loadChangeContext(projectRoot, changeName, options.schema, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        });
+        const status = formatChangeStatus(context, isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
+        spinner?.stop();
+        if (options.json) {
+            console.log(JSON.stringify({ ...status, root: rootOutput }, null, 2));
+            return;
+        }
+        printStatusText(status);
+    }
+    catch (error) {
+        spinner?.stop();
+        throw error;
+    }
+}
+export function printStatusText(status) {
+    const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
+    const total = status.artifacts.length;
+    console.log(`Change: ${status.changeName}`);
+    console.log(`Schema: ${status.schemaName}`);
+    if (status.changeRoot) {
+        console.log(`Change root: ${status.changeRoot}`);
+    }
+    console.log(`Progress: ${doneCount}/${total} artifacts complete`);
+    console.log();
+    for (const artifact of status.artifacts) {
+        const indicator = getStatusIndicator(artifact.status);
+        const color = getStatusColor(artifact.status);
+        let line = `${indicator} ${artifact.id}`;
+        if (artifact.status === 'blocked' && artifact.missingDeps && artifact.missingDeps.length > 0) {
+            line += color(` (blocked by: ${artifact.missingDeps.join(', ')})`);
+        }
+        console.log(line);
+    }
+    if (status.isComplete) {
+        console.log();
+        console.log(chalk.green('All artifacts complete!'));
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/workflow/templates.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Templates Command
+ *
+ * Shows resolved template paths for all artifacts in a schema.
+ */
+export interface TemplatesOptions {
+    schema?: string;
+    json?: boolean;
+}
+export interface TemplateInfo {
+    artifactId: string;
+    templatePath: string;
+    source: 'project' | 'user' | 'package';
+}
+export declare function templatesCommand(options: TemplatesOptions): Promise<void>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/commands/workflow/templates.js

@@ -0,0 +1,69 @@
+/**
+ * Templates Command
+ *
+ * Shows resolved template paths for all artifacts in a schema.
+ */
+import ora from 'ora';
+import path from 'path';
+import { resolveSchema, getSchemaDir, ArtifactGraph, } from '../../core/artifact-graph/index.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { validateSchemaExists, DEFAULT_SCHEMA } from './shared.js';
+// -----------------------------------------------------------------------------
+// Command Implementation
+// -----------------------------------------------------------------------------
+export async function templatesCommand(options) {
+    const spinner = options.json ? undefined : ora('Loading templates...').start();
+    try {
+        const projectRoot = process.cwd();
+        const schemaName = validateSchemaExists(options.schema ?? DEFAULT_SCHEMA, projectRoot);
+        const schema = resolveSchema(schemaName, projectRoot);
+        const graph = ArtifactGraph.fromSchema(schema);
+        const schemaDir = getSchemaDir(schemaName, projectRoot);
+        // Determine the source (project, user, or package)
+        const { getUserSchemasDir, getProjectSchemasDir, } = await import('../../core/artifact-graph/resolver.js');
+        const projectSchemasDir = getProjectSchemasDir(projectRoot);
+        const userSchemasDir = getUserSchemasDir();
+        // Determine source by checking if schemaDir is inside each base directory
+        // Using path.relative is more robust than startsWith for path comparisons
+        const isInsideDir = (child, parent) => {
+            const relative = path.relative(parent, child);
+            return !relative.startsWith('..') && !path.isAbsolute(relative);
+        };
+        let source;
+        if (isInsideDir(schemaDir, projectSchemasDir)) {
+            source = 'project';
+        }
+        else if (isInsideDir(schemaDir, userSchemasDir)) {
+            source = 'user';
+        }
+        else {
+            source = 'package';
+        }
+        const templates = graph.getAllArtifacts().map((artifact) => ({
+            artifactId: artifact.id,
+            templatePath: FileSystemUtils.canonicalizeExistingPath(path.join(schemaDir, 'templates', artifact.template)),
+            source,
+        }));
+        spinner?.stop();
+        if (options.json) {
+            const output = {};
+            for (const t of templates) {
+                output[t.artifactId] = { path: t.templatePath, source: t.source };
+            }
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        console.log(`Schema: ${schemaName}`);
+        console.log(`Source: ${source}`);
+        console.log();
+        for (const t of templates) {
+            console.log(`${t.artifactId}:`);
+            console.log(`  ${t.templatePath}`);
+        }
+    }
+    catch (error) {
+        spinner?.stop();
+        throw error;
+    }
+}
+//# sourceMappingURL=templates.js.map

package/dist/commands/workset-input.d.ts

@@ -0,0 +1,19 @@
+import { type OpenerDefinition, type OpenerScanOptions } from '../core/openers.js';
+import { StoreError } from '../core/store/errors.js';
+import { type Workset, type WorksetMember } from '../core/worksets.js';
+/** Concurrent stats; the first invalid flag (by flag order) reports. */
+export declare function resolveMemberFlags(flags: string[]): Promise<WorksetMember[]>;
+/** One spelling of "this tool id must exist in the merged table". */
+export declare function assertKnownTool(tool: string, table: OpenerDefinition[]): void;
+/** Final assembly shared by both compose paths: one validation rule. */
+export declare function finalizeWorkset(name: string, members: WorksetMember[], tool: string | undefined, table: OpenerDefinition[]): Workset;
+/** The aligned `<name>  <path>` rows used by list, remove, and the
+ * open fallback; callers pick the stream and indent. */
+export declare function formatMemberRows(members: WorksetMember[]): string[];
+export declare function toolUnknownError(toolId: string, table: OpenerDefinition[]): StoreError;
+/** Stops at the first installed alternative instead of scanning all. */
+export declare function firstInstalledAlternative(table: OpenerDefinition[], excludeId: string | undefined, scan?: OpenerScanOptions): string | null;
+export declare function toolUnavailableError(opener: OpenerDefinition, table: OpenerDefinition[], worksetName: string, scan?: OpenerScanOptions): StoreError;
+/** Interactive open with no saved tool and nothing installed at all. */
+export declare function noToolInstalledError(table: OpenerDefinition[], worksetName: string): StoreError;
+//# sourceMappingURL=workset-input.d.ts.map

package/dist/commands/workset-input.js

@@ -0,0 +1,112 @@
+/**
+ * Input resolution and error builders shared by the workset command
+ * and its interactive prompt flows.
+ */
+import * as path from 'node:path';
+import { pathIsDirectory } from '../core/file-state.js';
+import { findOpener, isOpenerCommandAvailable, isOpenerEnabled, } from '../core/openers.js';
+import { StoreError } from '../core/store/errors.js';
+import { expandUserPath } from '../core/store/operations.js';
+import { getGlobalConfigPath } from '../core/global-config.js';
+import { memberLabelProblem, memberListProblem, } from '../core/worksets.js';
+function memberInvalidError(problem) {
+    return new StoreError(`Invalid workset member: ${problem}.`, 'workset_member_invalid', {
+        target: 'workset.member',
+        fix: 'Pass --member <path> with an existing folder, or --member <name>=<path> to label it.',
+    });
+}
+/** `--member <path>` or `--member <name>=<path>` (the first `=` splits). */
+async function resolveMemberFlag(raw) {
+    const separator = raw.indexOf('=');
+    const label = separator > 0 ? raw.slice(0, separator) : undefined;
+    const rawPath = separator > 0 ? raw.slice(separator + 1) : raw;
+    if (rawPath.length === 0) {
+        throw memberInvalidError(`'${raw}' has no path`);
+    }
+    const resolvedPath = path.resolve(expandUserPath(rawPath));
+    if (!(await pathIsDirectory(resolvedPath))) {
+        throw memberInvalidError(`'${rawPath}' is not an existing folder`);
+    }
+    const name = label ?? path.basename(resolvedPath);
+    const labelProblem = memberLabelProblem(name);
+    if (labelProblem !== null) {
+        throw memberInvalidError(labelProblem);
+    }
+    return { name, path: resolvedPath };
+}
+/** Concurrent stats; the first invalid flag (by flag order) reports. */
+export async function resolveMemberFlags(flags) {
+    const settled = await Promise.allSettled(flags.map(resolveMemberFlag));
+    const members = [];
+    for (const result of settled) {
+        if (result.status === 'rejected') {
+            throw result.reason;
+        }
+        members.push(result.value);
+    }
+    return members;
+}
+/** One spelling of "this tool id must exist in the merged table". */
+export function assertKnownTool(tool, table) {
+    if (findOpener(table, tool) === null) {
+        throw toolUnknownError(tool, table);
+    }
+}
+/** Final assembly shared by both compose paths: one validation rule. */
+export function finalizeWorkset(name, members, tool, table) {
+    const problem = memberListProblem(members);
+    if (problem !== null) {
+        throw memberInvalidError(problem);
+    }
+    if (tool !== undefined) {
+        assertKnownTool(tool, table);
+    }
+    return {
+        name,
+        ...(tool !== undefined ? { tool } : {}),
+        members,
+    };
+}
+/** The aligned `<name>  <path>` rows used by list, remove, and the
+ * open fallback; callers pick the stream and indent. */
+export function formatMemberRows(members) {
+    const width = Math.max(...members.map((member) => member.name.length));
+    return members.map((member) => `${member.name.padEnd(width)}  ${member.path}`);
+}
+export function toolUnknownError(toolId, table) {
+    const knownIds = table
+        .filter((opener) => isOpenerEnabled(opener))
+        .map((opener) => opener.id)
+        .join(', ');
+    return new StoreError(`Unknown tool '${toolId}'.`, 'workset_tool_unknown', {
+        target: 'workset.tool',
+        fix: `Known tools: ${knownIds}. Add new tools under "openers" in ${getGlobalConfigPath()}.`,
+    });
+}
+/** Stops at the first installed alternative instead of scanning all. */
+export function firstInstalledAlternative(table, excludeId, scan) {
+    return (table.find((candidate) => candidate.id !== excludeId &&
+        isOpenerEnabled(candidate) &&
+        isOpenerCommandAvailable(candidate.command, scan))?.id ?? null);
+}
+export function toolUnavailableError(opener, table, worksetName, scan) {
+    const alternative = firstInstalledAlternative(table, opener.id, scan);
+    return new StoreError(`${opener.label} ('${opener.command}') is not on PATH.`, 'workset_tool_unavailable', {
+        target: 'workset.tool',
+        fix: alternative !== null
+            ? `Install '${opener.command}' or run: openspec workset open ${worksetName} --tool ${alternative}`
+            : `Install '${opener.command}', then rerun: openspec workset open ${worksetName}`,
+    });
+}
+/** Interactive open with no saved tool and nothing installed at all. */
+export function noToolInstalledError(table, worksetName) {
+    const commands = table
+        .filter((opener) => isOpenerEnabled(opener))
+        .map((opener) => opener.command)
+        .join(', ');
+    return new StoreError('None of the known tools is on PATH.', 'workset_tool_unavailable', {
+        target: 'workset.tool',
+        fix: `Install one of: ${commands}. Then rerun: openspec workset open ${worksetName}`,
+    });
+}
+//# sourceMappingURL=workset-input.js.map

package/dist/commands/workset-prompts.d.ts

@@ -0,0 +1,12 @@
+import { type OpenerChoice, type OpenerDefinition } from '../core/openers.js';
+import { type Workset } from '../core/worksets.js';
+export interface ComposeInput {
+    memberFlags: string[];
+    tool?: string;
+}
+export declare function composeInteractively(givenName: string | undefined, input: ComposeInput, table: OpenerDefinition[]): Promise<Workset>;
+export declare function promptToolFromChoices(available: OpenerChoice[]): Promise<string>;
+export declare function promptOpenNow(label: string): Promise<boolean>;
+/** Prints the workset (decision 13: remove shows what it removes). */
+export declare function confirmRemoveInteractively(workset: Workset): Promise<boolean>;
+//# sourceMappingURL=workset-prompts.d.ts.map