@gordon.gan/specflow 1.1.1 → 1.2.0-beta.1

package/dist/cli/commands/show.js

@@ -0,0 +1,92 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { sortDiagnostics } from '../../core/diagnostics.js';
+import { resolveCommandPlanningRoot } from '../shared/store-option.js';
+export async function runShowSpec(options) {
+    let root = options.fixtures?.root;
+    let storeId = options.fixtures?.storeId ?? options.storeId;
+    let status = [];
+    if (root === undefined) {
+        const resolved = await resolveCommandPlanningRoot({
+            cwd: options.cwd,
+            store: options.storeId,
+        });
+        root = resolved.root;
+        storeId = resolved.storeId ?? options.storeId;
+        status = [...resolved.diagnostics];
+    }
+    const specPath = path.join(root, 'specflow', 'specs', options.specId, 'spec.md');
+    let content = options.fixtures?.content;
+    if (content === undefined) {
+        try {
+            content = await fs.readFile(specPath, 'utf-8');
+        }
+        catch {
+            return {
+                stdout: '',
+                stderr: `Spec '${options.specId}' not found.`,
+                status: sortDiagnostics([
+                    ...status,
+                    {
+                        severity: 'error',
+                        code: 'spec_not_found',
+                        message: `Spec '${options.specId}' not found.`,
+                        target: `specs.${options.specId}`,
+                    },
+                ]),
+                exitCode: 1,
+            };
+        }
+    }
+    if (options.json) {
+        return {
+            stdout: JSON.stringify({
+                id: options.specId,
+                type: options.type,
+                root,
+                store_id: storeId ?? null,
+                content,
+                status,
+            }, null, 2),
+            stderr: '',
+            status,
+            exitCode: 0,
+        };
+    }
+    const banner = storeId ? `Resolved store: ${storeId} (${root})\n` : `Resolved root: ${root}\n`;
+    return {
+        stdout: content,
+        stderr: banner,
+        status,
+        exitCode: 0,
+    };
+}
+import { addStoreOption } from '../shared/store-option.js';
+export function registerShowCommand(program) {
+    addStoreOption(program
+        .command('show <spec-id>')
+        .description('Show a baseline spec from the resolved planning root')
+        .option('--type <type>', 'Artifact type', 'spec')
+        .option('--json', 'Output as JSON')
+        .action(async (specId, opts) => {
+        const result = await runShowSpec({
+            specId,
+            type: opts.type === 'spec' ? 'spec' : 'spec',
+            storeId: opts.store,
+            json: opts.json,
+        });
+        if (result.stdout) {
+            process.stdout.write(result.stdout);
+            if (!result.stdout.endsWith('\n')) {
+                process.stdout.write('\n');
+            }
+        }
+        if (result.stderr) {
+            process.stderr.write(result.stderr);
+        }
+        if (result.exitCode !== 0 && opts.json) {
+            console.log(JSON.stringify({ status: result.status }, null, 2));
+        }
+        process.exit(result.exitCode);
+    }));
+}

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

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import { type Diagnostic } from '../../core/diagnostics.js';
+export interface StoreListOptions {
+    json?: boolean;
+    dataDir?: string;
+}
+export interface StoreListOutput {
+    stores: Array<{
+        id: string;
+        root: string;
+        provenance: string;
+    }>;
+    status: Diagnostic[];
+}
+export declare function runStoreList(options?: StoreListOptions): Promise<StoreListOutput>;
+export declare function registerStoreCommand(program: Command): void;

package/dist/cli/commands/store.js

@@ -0,0 +1,221 @@
+import { getGlobalDataDir } from '../../core/global-config.js';
+import { listRegisteredStores, prepareStoreSetup, prepareStoreRegistration, removeManagedStore, unregisterStore, } from '../../core/store/operations.js';
+import { readRegistry } from '../../core/store/registry.js';
+import { getStoreRegistryPath } from '../../core/global-config.js';
+import { sortDiagnostics, hasErrorDiagnostic } from '../../core/diagnostics.js';
+import { StoreError } from '../../core/store/foundation.js';
+import { flattenStoreDoctorDiagnostics, inspectAllStoresHealth } from '../../core/store/health.js';
+export async function runStoreList(options = {}) {
+    const dataDir = options.dataDir ?? getGlobalDataDir();
+    const stores = await listRegisteredStores(dataDir);
+    return {
+        stores: stores.map((s) => ({ id: s.id, root: s.root, provenance: s.provenance })),
+        status: [],
+    };
+}
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+async function confirmIdentityCreation(storeId) {
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    const readline = await import('node:readline/promises');
+    const { stdin, stdout } = await import('node:process');
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const answer = await rl.question(`Create store identity for '${storeId}'? [y/N] `);
+    rl.close();
+    return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes';
+}
+function emitFailure(json, payload, error) {
+    const diagnostics = error instanceof StoreError
+        ? [...error.diagnostics]
+        : [
+            {
+                severity: 'error',
+                code: 'store_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        ];
+    const output = { ...payload, status: sortDiagnostics(diagnostics) };
+    if (json) {
+        printJson(output);
+    }
+    else {
+        console.error(diagnostics.map((d) => d.message).join('\n'));
+    }
+    process.exit(hasErrorDiagnostic(diagnostics) ? 1 : 0);
+}
+export function registerStoreCommand(program) {
+    const store = program.command('store').description('Manage planning stores');
+    store
+        .command('list')
+        .description('List registered planning stores')
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
+        try {
+            const output = await runStoreList(opts);
+            if (opts.json) {
+                printJson(output);
+            }
+            else if (output.stores.length === 0) {
+                console.log('No stores registered.');
+            }
+            else {
+                for (const entry of output.stores) {
+                    console.log(`${entry.id}\t${entry.root}\t(${entry.provenance})`);
+                }
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, { stores: [], status: [] }, error);
+        }
+    });
+    store
+        .command('setup <id>')
+        .description('Create and register a new managed planning store')
+        .requiredOption('--path <path>', 'Target path that must not exist')
+        .option('--remote <url>', 'Optional canonical remote URL')
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        try {
+            const dataDir = opts.dataDir ?? getGlobalDataDir();
+            const result = await prepareStoreSetup({
+                id,
+                targetPath: opts.path,
+                dataDir,
+                remote: opts.remote,
+            });
+            const output = {
+                store: { id: result.identity.id, root: result.root },
+                created_files: result.createdArtifacts,
+                status: sortDiagnostics(result.diagnostics),
+            };
+            if (opts.json) {
+                printJson(output);
+            }
+            else {
+                console.log(`Created managed store '${id}' at ${result.root}`);
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, { store: null, created_files: [], status: [] }, error);
+        }
+    });
+    store
+        .command('register <path>')
+        .description('Register an existing checkout as an external store')
+        .requiredOption('--id <id>', 'Store ID to adopt')
+        .option('--yes', 'Non-interactive adoption confirmation')
+        .option('--json', 'Output as JSON')
+        .action(async (storePath, opts) => {
+        try {
+            const dataDir = opts.dataDir ?? getGlobalDataDir();
+            const confirmIdentity = opts.yes === true || (await confirmIdentityCreation(opts.id));
+            const result = await prepareStoreRegistration({
+                id: opts.id,
+                localPath: storePath,
+                dataDir,
+                confirmIdentity,
+            });
+            const output = {
+                store: result.store,
+                already_registered: result.alreadyRegistered,
+                created_files: result.createdArtifacts,
+                status: sortDiagnostics(result.diagnostics),
+            };
+            if (opts.json) {
+                printJson(output);
+            }
+            else {
+                console.log(result.alreadyRegistered
+                    ? `Store '${opts.id}' was already registered.`
+                    : `Registered external store '${opts.id}'.`);
+                for (const file of result.createdArtifacts) {
+                    console.log(`Created ${file}`);
+                }
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, { store: null, status: [] }, error);
+        }
+    });
+    store
+        .command('unregister <id>')
+        .description('Remove a store from the local registry without deleting its checkout')
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        try {
+            const dataDir = opts.dataDir ?? getGlobalDataDir();
+            const result = await unregisterStore({ id, dataDir });
+            const output = { store: { id }, removed: result.removed, status: sortDiagnostics(result.diagnostics) };
+            if (opts.json) {
+                printJson(output);
+            }
+            else {
+                console.log(`Unregistered store '${id}'.`);
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, { store: { id }, status: [] }, error);
+        }
+    });
+    store
+        .command('doctor')
+        .description('Inspect registered store health without mutating state')
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
+        const dataDir = opts.dataDir ?? getGlobalDataDir();
+        const registry = await readRegistry(getStoreRegistryPath(dataDir));
+        const inspected = await inspectAllStoresHealth(registry);
+        const stores = inspected.map(({ id, root, provenance }) => ({ id, root, provenance }));
+        const status = flattenStoreDoctorDiagnostics(inspected);
+        const output = { stores, status };
+        if (opts.json) {
+            printJson(output);
+        }
+        else if (stores.length === 0) {
+            console.log('No stores registered.');
+        }
+        else {
+            for (const store of stores) {
+                console.log(`${store.id}\t${store.root}\t(${store.provenance})`);
+            }
+            for (const diagnostic of status) {
+                console.error(`${diagnostic.severity}: ${diagnostic.message}`);
+            }
+            if (hasErrorDiagnostic(status)) {
+                process.exit(1);
+            }
+        }
+    });
+    store
+        .command('remove <id>')
+        .description('Unregister and delete a managed store checkout')
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        try {
+            const dataDir = opts.dataDir ?? getGlobalDataDir();
+            const result = await removeManagedStore({ id, dataDir });
+            const output = {
+                store: { id },
+                registry_removed: result.registryRemoved,
+                checkout_deleted: result.checkoutDeleted,
+                status: sortDiagnostics(result.diagnostics),
+            };
+            if (opts.json) {
+                printJson(output);
+            }
+            else if (result.checkoutDeleted) {
+                console.log(`Removed managed store '${id}'.`);
+            }
+            else {
+                console.error(result.diagnostics.map((d) => d.message).join('\n'));
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, { store: { id }, status: [] }, error);
+        }
+    });
+}

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

@@ -5,6 +5,22 @@
  */
 import type { Command } from 'commander';
 import type { ValidationResult } from '../../core/validation/types.js';
+import type { StoreRegistry } from '../../core/store/foundation.js';
+export interface ResolveValidatePathOptions {
+    store?: string;
+    cwd?: string;
+    registry?: StoreRegistry;
+}
+export interface ResolvedValidatePath {
+    readonly filePath: string;
+    readonly root: string;
+    readonly storeId?: string;
+}
+/**
+ * Resolves a validate target path against the selected planning root.
+ * Absolute paths are kept; relative paths are joined to the planning root.
+ */
+export declare function resolveValidateFilePath(filePath: string, options?: ResolveValidatePathOptions): Promise<ResolvedValidatePath>;
 /**
  * Validates a spec file at the given path.
  *

package/dist/cli/commands/validate.js

@@ -4,7 +4,28 @@
  * Validates a spec file for structural correctness.
  */
 import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
 import { validateSpec } from '../../core/validation/validator.js';
+import { addStoreOption, resolveCommandPlanningRoot } from '../shared/store-option.js';
+/**
+ * Resolves a validate target path against the selected planning root.
+ * Absolute paths are kept; relative paths are joined to the planning root.
+ */
+export async function resolveValidateFilePath(filePath, options = {}) {
+    const resolved = await resolveCommandPlanningRoot({
+        cwd: options.cwd,
+        store: options.store,
+        registry: options.registry,
+    });
+    const absolute = path.isAbsolute(filePath)
+        ? path.resolve(filePath)
+        : path.resolve(resolved.root, filePath);
+    return {
+        filePath: absolute,
+        root: resolved.root,
+        storeId: resolved.storeId,
+    };
+}
 /**
  * Validates a spec file at the given path.
  *
@@ -22,16 +43,25 @@ export async function validateSpecFile(filePath) {
  * Registers the `validate` command with Commander.
  */
 export function registerValidateCommand(program) {
-    program
+    addStoreOption(program
         .command('validate <file>')
         .description('Validate a spec file for structural correctness')
         .option('--json', 'Output as JSON')
         .action(async (file, opts) => {
-        const result = await validateSpecFile(file);
+        const resolved = await resolveValidateFilePath(file, { store: opts.store });
+        const result = await validateSpecFile(resolved.filePath);
         if (opts.json) {
-            console.info(JSON.stringify(result, null, 2));
+            console.info(JSON.stringify({
+                ...result,
+                root: resolved.root,
+                store_id: resolved.storeId ?? null,
+                file: resolved.filePath,
+            }, null, 2));
         }
         else if (result.valid) {
+            if (resolved.storeId) {
+                console.info(`Resolved store: ${resolved.storeId} (${resolved.root})`);
+            }
             console.info('Valid: no errors found.');
         }
         else {
@@ -42,5 +72,5 @@ export function registerValidateCommand(program) {
             }
             process.exitCode = 1;
         }
-    });
+    }));
 }

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

@@ -0,0 +1,12 @@
+import type { Workset } from '../../core/worksets.js';
+export interface PrepareWorksetOpenInput {
+    workset: Workset;
+    existingPaths?: Set<string>;
+}
+export interface PreparedWorksetOpen {
+    surviving: Workset['members'];
+    skipped: Workset['members'];
+}
+export declare function prepareWorksetOpen(input: PrepareWorksetOpenInput): Promise<PreparedWorksetOpen>;
+import type { Command } from 'commander';
+export declare function registerWorksetCommand(program: Command): void;

package/dist/cli/commands/workset.js

@@ -0,0 +1,235 @@
+import { promises as fs } from 'node:fs';
+import { StoreError } from '../../core/store/foundation.js';
+async function memberPathExists(memberPath) {
+    try {
+        await fs.stat(memberPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function prepareWorksetOpen(input) {
+    const existing = new Set();
+    if (input.existingPaths) {
+        for (const memberPath of input.existingPaths) {
+            existing.add(memberPath);
+        }
+    }
+    else {
+        for (const member of input.workset.members) {
+            if (await memberPathExists(member.path)) {
+                existing.add(member.path);
+            }
+        }
+    }
+    const primary = input.workset.members[0];
+    if (!existing.has(primary.path)) {
+        throw new StoreError('Primary workset member is unavailable.', {
+            severity: 'error',
+            code: 'workset_primary_missing',
+            message: 'The first saved member path is unavailable.',
+            target: `workset.members.${primary.name}`,
+            fix: 'Recreate the workset with a valid primary path.',
+        });
+    }
+    const surviving = [primary];
+    const skipped = input.workset.members.slice(1).filter((member) => {
+        if (existing.has(member.path)) {
+            surviving.push(member);
+            return false;
+        }
+        return true;
+    });
+    return { surviving, skipped };
+}
+import { getGlobalDataDir } from '../../core/global-config.js';
+import { defaultWorksetsStatePath, readWorksetsState, updateWorksetsState, withWorkset, validateWorksetMembers, validateWorksetName, getWorksetCodeWorkspacePath, removeWorksetByName, } from '../../core/worksets.js';
+import { BUILTIN_OPENERS, buildLaunchCommand, findOpener, isCliAgentOpener } from '../../core/openers.js';
+import { isOpenerAvailable, launchOpener } from '../../core/opener-launch.js';
+import { writeFileAtomically } from '../../core/file-state.js';
+export function registerWorksetCommand(program) {
+    const workset = program.command('workset').description('Manage machine-local worksets');
+    workset
+        .command('create <name>')
+        .description('Create a saved workset')
+        .requiredOption('--member <member>', 'Member label:absolute-path', collect, [])
+        .option('--tool <tool>', 'Preferred opener (cursor|code)')
+        .option('--json', 'Output as JSON')
+        .action(async (name, opts) => {
+        validateWorksetName(name);
+        const members = opts.member.map((entry) => {
+            const separator = entry.indexOf(':');
+            if (separator <= 0) {
+                throw new StoreError(`Invalid member '${entry}'.`, {
+                    severity: 'error',
+                    code: 'invalid_workset_member',
+                    message: 'Use label:absolute-path format.',
+                    target: 'workset.member',
+                });
+            }
+            return { name: entry.slice(0, separator), path: entry.slice(separator + 1) };
+        });
+        validateWorksetMembers(members);
+        if (opts.tool && isCliAgentOpener(opts.tool)) {
+            throw new StoreError('CLI-agent openers are disabled in V1.', {
+                severity: 'error',
+                code: 'workset_cli_opener_disabled',
+                message: 'V1 supports only Cursor and VS Code openers.',
+                target: 'workset.tool',
+            });
+        }
+        const dataDir = getGlobalDataDir();
+        const statePath = defaultWorksetsStatePath(dataDir);
+        const saved = await updateWorksetsState(statePath, (state) => withWorkset(state, { name, members, ...(opts.tool ? { tool: opts.tool } : {}) }));
+        const payload = { workset: saved.worksets.find((entry) => entry.name === name), status: [] };
+        if (opts.json) {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(`Saved workset '${name}'.`);
+        }
+    });
+    workset
+        .command('list')
+        .description('List saved worksets')
+        .option('--json', 'Output as JSON')
+        .action(async (opts) => {
+        const state = await readWorksetsState(defaultWorksetsStatePath(getGlobalDataDir()));
+        const payload = { worksets: state.worksets, status: [] };
+        if (opts.json) {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            for (const entry of state.worksets) {
+                console.log(`${entry.name}\t${entry.members.length} members`);
+            }
+        }
+    });
+    workset
+        .command('show <name>')
+        .description('Inspect a saved workset')
+        .option('--json', 'Output as JSON')
+        .action(async (name, opts) => {
+        const state = await readWorksetsState(defaultWorksetsStatePath(getGlobalDataDir()));
+        const entry = state.worksets.find((item) => item.name === name);
+        if (!entry) {
+            throw new StoreError(`Workset '${name}' not found.`, {
+                severity: 'error',
+                code: 'workset_not_found',
+                message: `Workset '${name}' not found.`,
+                target: 'workset.name',
+            });
+        }
+        const payload = { workset: entry, status: [] };
+        if (opts.json) {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(JSON.stringify(entry, null, 2));
+        }
+    });
+    workset
+        .command('remove <name>')
+        .description('Remove a saved workset and its derived workspace file')
+        .option('--json', 'Output as JSON')
+        .action(async (name, opts) => {
+        const dataDir = getGlobalDataDir();
+        const statePath = defaultWorksetsStatePath(dataDir);
+        const removed = await removeWorksetByName(statePath, name, dataDir);
+        if (!removed) {
+            throw new StoreError(`Workset '${name}' not found.`, {
+                severity: 'error',
+                code: 'workset_not_found',
+                message: `Workset '${name}' not found.`,
+                target: 'workset.name',
+            });
+        }
+        const payload = { workset: { name }, removed: true, status: [] };
+        if (opts.json) {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(`Removed workset '${name}'.`);
+        }
+    });
+    workset
+        .command('open <name>')
+        .description('Regenerate and optionally launch a workset editor view')
+        .option('--tool <tool>', 'Override preferred opener')
+        .option('--no-launch', 'Generate workspace file without launching the editor')
+        .option('--json', 'Output as JSON')
+        .action(async (name, opts) => {
+        const dataDir = getGlobalDataDir();
+        const state = await readWorksetsState(defaultWorksetsStatePath(dataDir));
+        const entry = state.worksets.find((item) => item.name === name);
+        if (!entry) {
+            throw new StoreError(`Workset '${name}' not found.`, {
+                severity: 'error',
+                code: 'workset_not_found',
+                message: `Workset '${name}' not found.`,
+                target: 'workset.name',
+            });
+        }
+        const prepared = await prepareWorksetOpen({ workset: entry });
+        const openerId = opts.tool ?? entry.tool ?? 'code';
+        if (isCliAgentOpener(openerId)) {
+            throw new StoreError('CLI-agent openers are disabled in V1.', {
+                severity: 'error',
+                code: 'workset_cli_opener_disabled',
+                message: 'V1 supports only Cursor and VS Code openers.',
+                target: 'workset.tool',
+            });
+        }
+        const opener = findOpener(BUILTIN_OPENERS, openerId);
+        if (!opener) {
+            throw new StoreError(`Unknown opener '${openerId}'.`, {
+                severity: 'error',
+                code: 'workset_unknown_opener',
+                message: `Unknown opener '${openerId}'.`,
+                target: 'workset.tool',
+            });
+        }
+        if (!isOpenerAvailable(opener)) {
+            throw new StoreError(`Opener '${openerId}' is not available on PATH.`, {
+                severity: 'error',
+                code: 'workset_opener_unavailable',
+                message: `Could not find '${opener.command}' on PATH.`,
+                target: 'workset.tool',
+                fix: 'Install the editor or choose another opener with --tool.',
+            });
+        }
+        const workspacePath = getWorksetCodeWorkspacePath(dataDir, name);
+        const folders = prepared.surviving.map((member) => ({ name: member.name, path: member.path }));
+        await writeFileAtomically(workspacePath, JSON.stringify({ folders }, null, 2) + '\n');
+        const launch = buildLaunchCommand(opener, {
+            members: [...prepared.surviving],
+            codeWorkspacePath: workspacePath,
+        });
+        if (opts.launch !== false) {
+            launchOpener(opener, workspacePath, launch.cwd);
+        }
+        const payload = {
+            workset: entry,
+            workspace_path: workspacePath,
+            launch,
+            skipped_members: prepared.skipped,
+            status: [],
+        };
+        if (opts.json) {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(`Generated ${workspacePath}`);
+            if (opts.launch !== false) {
+                console.log(`Launched ${launch.executable} ${launch.args.join(' ')}`);
+            }
+            else {
+                console.log(`Launch: ${launch.executable} ${launch.args.join(' ')}`);
+            }
+        }
+    });
+}
+function collect(value, previous) {
+    return [...previous, value];
+}

package/dist/cli/index.js

@@ -12,6 +12,10 @@ import { registerInitCommand } from './commands/init.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerParityReportCommand } from './commands/parity-report.js';
+import { registerStoreCommand } from './commands/store.js';
+import { registerShowCommand } from './commands/show.js';
+import { registerContextCommand } from './commands/context.js';
+import { registerWorksetCommand } from './commands/workset.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
@@ -35,6 +39,10 @@ registerInitCommand(program);
 registerSyncCommand(program);
 registerDoctorCommand(program);
 registerParityReportCommand(program);
+registerStoreCommand(program);
+registerShowCommand(program);
+registerContextCommand(program);
+registerWorksetCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync();