@gordon.gan/specflow 1.0.0

package/dist/cli/commands/change-phase.js

@@ -0,0 +1,66 @@
+/**
+ * CLI command: specflow change phase <name> [--set <value>]
+ *
+ * Read or update the lifecycle phase of a change.
+ */
+import { CHANGE_PHASES, getChangeMetadata, updatePhase, } from '../../utils/change-utils.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+/**
+ * Returns true if the candidate value is a valid ChangePhase.
+ */
+function isChangePhase(value) {
+    return CHANGE_PHASES.includes(value);
+}
+/**
+ * Reads the current phase of a change.
+ *
+ * @param name - Name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The current phase, or undefined for legacy files without a phase field
+ * @throws When the change does not exist
+ */
+export async function getPhase(name, projectRoot) {
+    const metadata = await getChangeMetadata(name, projectRoot);
+    if (metadata === null) {
+        throw new Error(`Change not found: "${name}"`);
+    }
+    return metadata.phase;
+}
+/**
+ * Sets the phase of a change, validating the phase value first.
+ *
+ * @param name - Name of the change
+ * @param phase - The new phase value (validated against CHANGE_PHASES)
+ * @param projectRoot - Absolute path to the project root
+ * @throws When the phase is invalid or the change does not exist
+ */
+export async function setPhase(name, phase, projectRoot) {
+    if (!isChangePhase(phase)) {
+        const valid = CHANGE_PHASES.join(' | ');
+        throw new Error(`Invalid phase "${phase}": expected one of ${valid}`);
+    }
+    await updatePhase(name, phase, projectRoot);
+}
+/**
+ * Registers the `change phase` subcommand with Commander.
+ *
+ * Usage:
+ *   specflow change phase <name>            # print current phase
+ *   specflow change phase <name> --set plan # update phase
+ */
+export function registerChangePhaseCommand(changeCmd) {
+    changeCmd
+        .command('phase <name>')
+        .description('Show or set the lifecycle phase of a change')
+        .option('--set <value>', 'Set the phase to the given value')
+        .action(async (name, opts) => {
+        const projectRoot = requireProjectRoot();
+        if (opts.set !== undefined) {
+            await setPhase(name, opts.set, projectRoot);
+            console.info(`Change "${name}" phase set to ${opts.set}`);
+            return;
+        }
+        const phase = await getPhase(name, projectRoot);
+        console.info(phase ?? '(unset)');
+    });
+}

package/dist/cli/commands/change-status.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI command: specflow change status <name>
+ *
+ * Shows the status of artifacts for a given change.
+ */
+import type { Command } from 'commander';
+import type { ArtifactStatusEntry } from '../../core/artifact-graph/outputs.js';
+/**
+ * Extended status output with change-level metadata.
+ */
+export interface ChangeStatusOutput {
+    readonly changeName: string;
+    readonly artifacts: readonly ArtifactStatusEntry[];
+    readonly isComplete: boolean;
+}
+/**
+ * Gets the status of all artifacts for a given change.
+ *
+ * @param changeName - The name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns Status output with per-artifact state and completion flag
+ * @throws When the change directory does not exist
+ */
+export declare function getChangeStatus(changeName: string, projectRoot: string): Promise<ChangeStatusOutput>;
+/**
+ * Formats a ChangeStatusOutput as human-readable checkbox text.
+ *
+ * @param status - The status output to format
+ * @returns Formatted string with [x] and [ ] checkboxes
+ */
+export declare function formatChangeStatus(status: ChangeStatusOutput): string;
+/**
+ * Registers the `change status` subcommand with Commander.
+ */
+export declare function registerChangeStatusCommand(changeCmd: Command): void;

package/dist/cli/commands/change-status.js

@@ -0,0 +1,95 @@
+/**
+ * CLI command: specflow change status <name>
+ *
+ * Shows the status of artifacts for a given change.
+ */
+import { join } from 'node:path';
+import * as fs from 'node:fs';
+import yaml from 'js-yaml';
+import { resolveSchema } from '../../core/artifact-graph/resolver.js';
+import { getCompletedArtifacts } from '../../core/artifact-graph/state.js';
+import { formatStatus } from '../../core/artifact-graph/outputs.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+import { readChangeMetadata } from '../../utils/change-metadata.js';
+/**
+ * Reads the project config to determine the schema name.
+ */
+function readSchemaName(projectRoot) {
+    const configPath = join(projectRoot, 'specflow', 'config.yaml');
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const parsed = yaml.load(content);
+        if (typeof parsed?.schema === 'string') {
+            return parsed.schema;
+        }
+    }
+    catch {
+        // Fall through to default
+    }
+    return 'specflow';
+}
+/**
+ * Gets the status of all artifacts for a given change.
+ *
+ * @param changeName - The name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns Status output with per-artifact state and completion flag
+ * @throws When the change directory does not exist
+ */
+export async function getChangeStatus(changeName, projectRoot) {
+    const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
+    if (!fs.existsSync(changeDir)) {
+        throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+    }
+    // Validate change metadata (including phase enum) before proceeding.
+    // If .specflow.yaml contains an invalid phase, Zod will throw a clear error
+    // listing the valid enum values. Missing metadata is tolerated (null return).
+    await readChangeMetadata(changeDir);
+    const schemaName = readSchemaName(projectRoot);
+    // Resolve schema from project-local schemas/ directory, falling back to package schemas
+    const schema = resolveSchema(schemaName, projectRoot);
+    const completed = getCompletedArtifacts(changeDir, schema);
+    const statusOutput = formatStatus(schema.artifacts, completed);
+    const completedSet = new Set(completed);
+    const allDone = schema.artifacts.every((a) => completedSet.has(a.id));
+    return {
+        changeName,
+        artifacts: statusOutput.artifacts,
+        isComplete: allDone,
+    };
+}
+/**
+ * Formats a ChangeStatusOutput as human-readable checkbox text.
+ *
+ * @param status - The status output to format
+ * @returns Formatted string with [x] and [ ] checkboxes
+ */
+export function formatChangeStatus(status) {
+    const lines = status.artifacts.map((entry) => {
+        const checkbox = entry.status === 'done' ? '[x]' : '[ ]';
+        const suffix = entry.missingDeps && entry.missingDeps.length > 0
+            ? ` (blocked by: ${entry.missingDeps.join(', ')})`
+            : '';
+        return `${checkbox} ${entry.id}${suffix}`;
+    });
+    return lines.join('\n');
+}
+/**
+ * Registers the `change status` subcommand with Commander.
+ */
+export function registerChangeStatusCommand(changeCmd) {
+    changeCmd
+        .command('status <name>')
+        .description('Show artifact status for a change')
+        .option('--json', 'Output as JSON')
+        .action(async (name, opts) => {
+        const projectRoot = requireProjectRoot();
+        const status = await getChangeStatus(name, projectRoot);
+        if (opts.json) {
+            console.info(JSON.stringify(status, null, 2));
+        }
+        else {
+            console.info(formatChangeStatus(status));
+        }
+    });
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+export interface DoctorOutput {
+    readonly ok: boolean;
+    readonly migrationState: string;
+    readonly checks: readonly string[];
+    readonly errors: readonly string[];
+}
+export declare function runDoctor(projectRoot: string, parity: boolean): Promise<DoctorOutput>;
+export declare function registerDoctorCommand(program: Command): void;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,48 @@
+import { ALL_ADAPTERS } from '../../integrations/shared/adapter-registry.js';
+import { compareHealthyReports, validateReportAgainstManifest } from '../../integrations/shared/parity-comparator.js';
+import { detectMigrationState } from '../../integrations/shared/migration-state.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+export async function runDoctor(projectRoot, parity) {
+    const reports = await Promise.all(ALL_ADAPTERS.map((adapter) => adapter.inspect(projectRoot)));
+    const checks = [];
+    const errors = [];
+    const migrationState = await detectMigrationState(projectRoot);
+    checks.push(`migration state: ${migrationState}`);
+    for (const report of reports) {
+        const status = validateReportAgainstManifest(report);
+        checks.push(`${report.ide} capabilities: ${status.ok ? 'ok' : 'fail'}`);
+        errors.push(...status.deltas.map((d) => d.message));
+    }
+    if (parity) {
+        const healthyReports = reports.filter((report) => validateReportAgainstManifest(report).ok);
+        const parityStatus = compareHealthyReports(healthyReports);
+        checks.push(`cross-ide parity: ${parityStatus.ok ? 'ok' : 'fail'}`);
+        errors.push(...parityStatus.deltas.map((d) => d.message));
+    }
+    return { ok: errors.length === 0, migrationState, checks, errors };
+}
+export function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Diagnose specflow IDE assets and parity')
+        .option('--json', 'Output as JSON')
+        .option('--parity', 'Include cross-IDE parity diagnostics')
+        .action(async (opts) => {
+        const projectRoot = requireProjectRoot();
+        const result = await runDoctor(projectRoot, opts.parity ?? false);
+        if (opts.json) {
+            console.info(JSON.stringify(result, null, 2));
+        }
+        else {
+            for (const line of result.checks) {
+                console.info(`- ${line}`);
+            }
+            for (const err of result.errors) {
+                console.error(`  error: ${err}`);
+            }
+        }
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import type { InitIdeTarget } from '../../integrations/shared/types.js';
+/**
+ * Result of an init operation.
+ */
+export interface InitResult {
+    readonly status: 'initialized' | 'already_initialized' | 'updated_assets';
+    readonly message: string;
+}
+export interface InitOptions {
+    readonly ide?: InitIdeTarget;
+    readonly forceAssets?: boolean;
+    readonly parityStrict?: boolean;
+}
+export declare function initProject(projectRoot: string, packageRoot: string, options?: InitOptions): Promise<InitResult>;
+export declare function registerInitCommand(program: Command): void;

package/dist/cli/commands/init.js

@@ -0,0 +1,122 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import * as fsSync from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { getAdapter, resolveAdapters } from '../../integrations/shared/adapter-registry.js';
+import { validateReportAgainstManifest } from '../../integrations/shared/parity-comparator.js';
+import { appendManagedBlock } from '../../integrations/shared/marker-write.js';
+import { getRegeneratableIgnoreLines } from '../../integrations/shared/managed-assets.js';
+import { detectMigrationState } from '../../integrations/shared/migration-state.js';
+const CONFIG_YAML = `schema: specflow
+
+# Project context (customize for your project)
+# context: |
+#   Tech stack: ...
+#   Architecture: ...
+`;
+function findPackageRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    let dir = join(currentFile, '..');
+    const root = '/';
+    while (dir !== root) {
+        if (fsSync.existsSync(join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = join(dir, '..');
+    }
+    throw new Error('Could not find package root (no package.json found in parent directories)');
+}
+async function createDirectoryStructure(projectRoot) {
+    await Promise.all([
+        fs.mkdir(join(projectRoot, 'specflow', 'changes'), { recursive: true }),
+        fs.mkdir(join(projectRoot, 'specflow', 'specs'), { recursive: true }),
+    ]);
+}
+async function writeConfig(projectRoot) {
+    await fs.writeFile(join(projectRoot, 'specflow', 'config.yaml'), CONFIG_YAML, 'utf-8');
+}
+async function pathExists(path) {
+    try {
+        await fs.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isProjectInitialized(projectRoot) {
+    return pathExists(join(projectRoot, 'specflow', 'config.yaml'));
+}
+async function hasIdeAssets(projectRoot, ide) {
+    const report = await getAdapter(ide).inspect(projectRoot);
+    return validateReportAgainstManifest(report).ok;
+}
+export async function initProject(projectRoot, packageRoot, options = {}) {
+    const ide = options.ide ?? 'both';
+    const forceAssets = options.forceAssets ?? false;
+    const parityStrict = options.parityStrict ?? true;
+    const adapters = resolveAdapters(ide);
+    const initialized = await isProjectInitialized(projectRoot);
+    const migrationState = await detectMigrationState(projectRoot);
+    if (!initialized) {
+        await createDirectoryStructure(projectRoot);
+        await writeConfig(projectRoot);
+    }
+    const selectedIdeTargets = adapters.map((a) => a.ide);
+    const allTargetsHealthy = (await Promise.all(selectedIdeTargets.map((target) => hasIdeAssets(projectRoot, target)))).every(Boolean);
+    if (initialized && !forceAssets && allTargetsHealthy) {
+        return {
+            status: 'already_initialized',
+            message: `Project at ${projectRoot} is already initialized for ide=${ide} (state=${migrationState}). Use --force-assets to refresh managed assets.`,
+        };
+    }
+    for (const adapter of adapters) {
+        await adapter.generate({ projectRoot, packageRoot, forceAssets });
+    }
+    await updateGitignore(projectRoot, selectedIdeTargets);
+    if (parityStrict) {
+        for (const adapter of adapters) {
+            const report = await adapter.inspect(projectRoot);
+            const status = validateReportAgainstManifest(report);
+            if (!status.ok) {
+                throw new Error(`Parity strict check failed for ${adapter.ide}: ${status.deltas.map((d) => d.message).join('; ')}`);
+            }
+        }
+    }
+    return {
+        status: initialized ? 'updated_assets' : 'initialized',
+        message: initialized
+            ? `Updated ${ide} assets at ${projectRoot}`
+            : `Initialized specflow project at ${projectRoot}`,
+    };
+}
+async function updateGitignore(projectRoot, ideTargets) {
+    const gitignorePath = join(projectRoot, '.gitignore');
+    const markerStart = '# Added by specflow init (regeneratable assets)';
+    const markerEnd = '# End specflow init';
+    const lines = ideTargets.flatMap((target) => getRegeneratableIgnoreLines(target));
+    await appendManagedBlock(gitignorePath, markerStart, markerEnd, lines);
+}
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('Initialize a project with specflow directory structure and assets')
+        .option('--ide <target>', 'Target IDE assets: claude | cursor | codex | both | all', 'both')
+        .option('--force-assets', 'Refresh managed IDE assets even when project is initialized')
+        .option('--no-parity-strict', 'Disable strict parity validation after asset generation')
+        .action(async (opts) => {
+        const projectRoot = process.cwd();
+        const packageRoot = findPackageRoot();
+        const result = await initProject(projectRoot, packageRoot, {
+            ide: opts.ide ?? 'both',
+            forceAssets: opts.forceAssets ?? false,
+            parityStrict: opts.parityStrict ?? true,
+        });
+        if (result.status === 'already_initialized') {
+            console.warn(`Warning: ${result.message}`);
+        }
+        else {
+            console.info(result.message);
+        }
+    });
+}

package/dist/cli/commands/instructions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI command: specflow instructions <artifact-id> <change-name>
+ *
+ * Loads and displays instructions for creating an artifact.
+ */
+import type { Command } from 'commander';
+import type { ArtifactInstructions } from '../../core/artifact-graph/instruction-loader.js';
+/**
+ * Gets instructions for creating an artifact within a change.
+ *
+ * @param artifactId - The artifact ID to get instructions for
+ * @param changeName - The name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The artifact instructions with dependencies and output path
+ * @throws When the artifact or change is not found
+ */
+export declare function getInstructions(artifactId: string, changeName: string, projectRoot: string): Promise<ArtifactInstructions>;
+/**
+ * Registers the `instructions` command with Commander.
+ */
+export declare function registerInstructionsCommand(program: Command): void;

package/dist/cli/commands/instructions.js

@@ -0,0 +1,75 @@
+/**
+ * CLI command: specflow instructions <artifact-id> <change-name>
+ *
+ * Loads and displays instructions for creating an artifact.
+ */
+import { join } from 'node:path';
+import * as fs from 'node:fs';
+import yaml from 'js-yaml';
+import { resolveSchema } from '../../core/artifact-graph/resolver.js';
+import { loadInstructions } from '../../core/artifact-graph/instruction-loader.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+/**
+ * Reads the project config to determine the schema name and optional context.
+ */
+function readProjectConfig(projectRoot) {
+    const configPath = join(projectRoot, 'specflow', 'config.yaml');
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const parsed = yaml.load(content);
+        const schemaName = typeof parsed?.schema === 'string' ? parsed.schema : 'specflow';
+        const config = { context: typeof parsed?.context === 'string' ? parsed.context : undefined };
+        return { schemaName, config };
+    }
+    catch {
+        return { schemaName: 'specflow' };
+    }
+}
+/**
+ * Gets instructions for creating an artifact within a change.
+ *
+ * @param artifactId - The artifact ID to get instructions for
+ * @param changeName - The name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The artifact instructions with dependencies and output path
+ * @throws When the artifact or change is not found
+ */
+export async function getInstructions(artifactId, changeName, projectRoot) {
+    const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
+    if (!fs.existsSync(changeDir)) {
+        throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+    }
+    const { schemaName, config } = readProjectConfig(projectRoot);
+    const schema = resolveSchema(schemaName, projectRoot);
+    return loadInstructions(artifactId, changeDir, schema, config);
+}
+/**
+ * Registers the `instructions` command with Commander.
+ */
+export function registerInstructionsCommand(program) {
+    program
+        .command('instructions <artifact-id> <change-name>')
+        .description('Show instructions for creating an artifact')
+        .option('--json', 'Output as JSON')
+        .action(async (artifactId, changeName, opts) => {
+        const projectRoot = requireProjectRoot();
+        const instructions = await getInstructions(artifactId, changeName, projectRoot);
+        if (opts.json) {
+            console.info(JSON.stringify(instructions, null, 2));
+        }
+        else {
+            console.info(`Artifact: ${artifactId}`);
+            console.info(`Generates: ${instructions.generates}`);
+            console.info(`Description: ${instructions.description}`);
+            if (instructions.instruction) {
+                console.info(`\nInstruction:\n${instructions.instruction}`);
+            }
+            if (instructions.dependencies.length > 0) {
+                console.info('\nDependencies:');
+                for (const dep of instructions.dependencies) {
+                    console.info(`  - ${dep.id}: ${dep.description}`);
+                }
+            }
+        }
+    });
+}

package/dist/cli/commands/parity-report.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import type { IdeTarget, ParityStatus } from '../../integrations/shared/types.js';
+export interface ParityReportOutput {
+    readonly migrationState: string;
+    readonly reports: Readonly<Record<IdeTarget, ParityStatus>>;
+    readonly parity: ParityStatus;
+    readonly ok: boolean;
+}
+export declare function getParityReport(projectRoot: string): Promise<ParityReportOutput>;
+export declare function registerParityReportCommand(program: Command): void;

package/dist/cli/commands/parity-report.js

@@ -0,0 +1,67 @@
+import { ALL_ADAPTERS } from '../../integrations/shared/adapter-registry.js';
+import { directoryExists } from '../../integrations/shared/asset-hash.js';
+import { compareHealthyReports, validateReportAgainstManifest } from '../../integrations/shared/parity-comparator.js';
+import { detectMigrationState } from '../../integrations/shared/migration-state.js';
+import { join } from 'node:path';
+import { requireProjectRoot } from '../../utils/project-root.js';
+async function isIdeInstalled(projectRoot, ide) {
+    if (ide === 'claude') {
+        return directoryExists(join(projectRoot, '.claude'));
+    }
+    if (ide === 'cursor') {
+        return directoryExists(join(projectRoot, '.cursor'));
+    }
+    return directoryExists(join(projectRoot, '.agents'));
+}
+export async function getParityReport(projectRoot) {
+    const migrationState = await detectMigrationState(projectRoot);
+    const inspected = await Promise.all(ALL_ADAPTERS.map((adapter) => adapter.inspect(projectRoot)));
+    const reports = {
+        claude: validateReportAgainstManifest(inspected[0]),
+        cursor: validateReportAgainstManifest(inspected[1]),
+        codex: validateReportAgainstManifest(inspected[2]),
+    };
+    const installedFlags = await Promise.all(ALL_ADAPTERS.map((adapter) => isIdeInstalled(projectRoot, adapter.ide)));
+    const healthyReports = inspected.filter((report) => reports[report.ide].ok);
+    const parity = compareHealthyReports(healthyReports);
+    const manifestOk = ALL_ADAPTERS.every((adapter, index) => {
+        if (!installedFlags[index]) {
+            return true;
+        }
+        return reports[adapter.ide].ok;
+    });
+    return {
+        migrationState,
+        reports,
+        parity,
+        ok: manifestOk && parity.ok,
+    };
+}
+export function registerParityReportCommand(program) {
+    program
+        .command('parity-report')
+        .description('Compare Claude, Cursor, and Codex capability parity')
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
+        const projectRoot = requireProjectRoot();
+        const report = await getParityReport(projectRoot);
+        if (opts.json) {
+            console.info(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.info(`Migration state: ${report.migrationState}`);
+            console.info(`Parity: ${report.ok ? 'PASS' : 'FAIL'}`);
+            for (const delta of [
+                ...report.reports.claude.deltas,
+                ...report.reports.cursor.deltas,
+                ...report.reports.codex.deltas,
+                ...report.parity.deltas,
+            ]) {
+                console.info(`- [${delta.severity}] ${delta.message}`);
+            }
+        }
+        if (!report.ok) {
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/sync.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { type InitOptions } from './init.js';
+export declare function syncProjectAssets(projectRoot: string, options: InitOptions): Promise<void>;
+export declare function registerSyncCommand(program: Command): void;

package/dist/cli/commands/sync.js

@@ -0,0 +1,40 @@
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import * as fsSync from 'node:fs';
+import { requireProjectRoot } from '../../utils/project-root.js';
+import { initProject } from './init.js';
+function findPackageRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    let dir = join(currentFile, '..');
+    const root = '/';
+    while (dir !== root) {
+        if (fsSync.existsSync(join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = join(dir, '..');
+    }
+    throw new Error('Could not find package root (no package.json found in parent directories)');
+}
+export async function syncProjectAssets(projectRoot, options) {
+    const packageRoot = findPackageRoot();
+    await initProject(projectRoot, packageRoot, {
+        ide: options.ide ?? 'both',
+        forceAssets: true,
+        parityStrict: options.parityStrict ?? true,
+    });
+}
+export function registerSyncCommand(program) {
+    program
+        .command('sync')
+        .description('Sync managed IDE assets from specflow package')
+        .option('--ide <target>', 'Target IDE assets: claude | cursor | codex | both | all', 'both')
+        .option('--no-parity-strict', 'Disable strict parity validation after sync')
+        .action(async (opts) => {
+        const projectRoot = requireProjectRoot();
+        await syncProjectAssets(projectRoot, {
+            ide: opts.ide ?? 'both',
+            parityStrict: opts.parityStrict ?? true,
+        });
+        console.info(`Synced ${opts.ide ?? 'both'} assets`);
+    });
+}

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI command: specflow validate <file>
+ *
+ * Validates a spec file for structural correctness.
+ */
+import type { Command } from 'commander';
+import type { ValidationResult } from '../../core/validation/types.js';
+/**
+ * Validates a spec file at the given path.
+ *
+ * Reads the file and runs the spec validator, returning structured results.
+ *
+ * @param filePath - Absolute path to the spec file
+ * @returns Validation result with valid flag and any errors
+ * @throws When the file cannot be read
+ */
+export declare function validateSpecFile(filePath: string): Promise<ValidationResult>;
+/**
+ * Registers the `validate` command with Commander.
+ */
+export declare function registerValidateCommand(program: Command): void;