@gordon.gan/specflow 1.1.1 → 1.2.0-beta

package/dist/core/store/health.js

@@ -0,0 +1,117 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import yaml from 'js-yaml';
+import { sortDiagnostics } from '../diagnostics.js';
+import { getStoreIdentityPath, StoreIdentitySchema, } from './foundation.js';
+import { hasPlanningContent } from '../root-selection.js';
+const execFileAsync = promisify(execFile);
+async function pathExists(targetPath) {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIdentity(root) {
+    const identityPath = getStoreIdentityPath(root);
+    try {
+        const raw = yaml.load(await fs.readFile(identityPath, 'utf-8'));
+        const parsed = StoreIdentitySchema.safeParse(raw);
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readGitOrigin(checkoutPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], {
+            cwd: checkoutPath,
+        });
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function inspectStoreEntry(storeId, entry) {
+    const diagnostics = [];
+    const checkoutPath = entry.backend.local_path;
+    if (!(await pathExists(checkoutPath))) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'store_checkout_missing',
+            message: `Registered checkout for '${storeId}' does not exist at ${checkoutPath}.`,
+            target: `stores.${storeId}`,
+            fix: `Relink with specflow store register --id ${storeId} <path> or specflow store unregister ${storeId}.`,
+        });
+        return diagnostics;
+    }
+    const identity = await readIdentity(checkoutPath);
+    if (!identity) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'store_identity_missing',
+            message: `Store '${storeId}' checkout has no committed identity.`,
+            target: `stores.${storeId}`,
+            fix: `Run specflow store register --id ${storeId} ${checkoutPath} --yes to adopt identity.`,
+        });
+    }
+    else if (identity.id !== storeId) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'store_identity_mismatch',
+            message: `Store '${storeId}' registry ID does not match committed identity '${identity.id}'.`,
+            target: `stores.${storeId}`,
+            fix: 'Unregister and re-register with the matching store ID.',
+        });
+    }
+    const configPath = path.join(checkoutPath, 'specflow', 'config.yaml');
+    if (!(await pathExists(configPath))) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'store_unhealthy_root',
+            message: `Store '${storeId}' checkout is missing specflow/config.yaml.`,
+            target: `stores.${storeId}`,
+        });
+    }
+    else if (!(await hasPlanningContent(checkoutPath))) {
+        diagnostics.push({
+            severity: 'info',
+            code: 'store_empty_planning',
+            message: `Store '${storeId}' has no baseline specs or active changes yet.`,
+            target: `stores.${storeId}`,
+        });
+    }
+    const canonicalRemote = identity?.remote ?? entry.backend.remote;
+    if (canonicalRemote) {
+        const observedOrigin = await readGitOrigin(checkoutPath);
+        if (observedOrigin && observedOrigin !== canonicalRemote) {
+            diagnostics.push({
+                severity: 'info',
+                code: 'store_remote_divergence',
+                message: `Store '${storeId}' canonical remote differs from Git origin.`,
+                target: `stores.${storeId}`,
+                fix: 'Update the committed identity remote or reconcile the checkout manually.',
+            });
+        }
+    }
+    return diagnostics;
+}
+export async function inspectAllStoresHealth(registry) {
+    const results = await Promise.all(Object.entries(registry.stores).map(async ([id, entry]) => ({
+        id,
+        root: entry.backend.local_path,
+        provenance: entry.provenance,
+        diagnostics: [...(await inspectStoreEntry(id, entry))],
+    })));
+    return results;
+}
+export function flattenStoreDoctorDiagnostics(stores) {
+    return sortDiagnostics(stores.flatMap((store) => store.diagnostics));
+}

package/dist/core/store/operations.d.ts

@@ -0,0 +1,56 @@
+import type { Diagnostic } from '../diagnostics.js';
+import { type StoreIdentity } from './foundation.js';
+export interface StoreSetupInput {
+    id: string;
+    targetPath: string;
+    dataDir: string;
+    remote?: string;
+}
+export interface StoreSetupResult {
+    readonly root: string;
+    readonly identity: StoreIdentity;
+    readonly createdArtifacts: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function prepareStoreSetup(input: StoreSetupInput): Promise<StoreSetupResult>;
+export interface RemoveManagedStoreInput {
+    id: string;
+    dataDir: string;
+    deleteCheckout?: (checkoutPath: string) => Promise<void>;
+}
+export interface RemoveManagedStoreResult {
+    readonly registryRemoved: boolean;
+    readonly checkoutDeleted: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function removeManagedStore(input: RemoveManagedStoreInput): Promise<RemoveManagedStoreResult>;
+export declare function listRegisteredStores(dataDir: string): Promise<{
+    id: string;
+    root: string;
+    provenance: "managed" | "external";
+}[]>;
+export interface StoreRegisterInput {
+    id: string;
+    localPath: string;
+    dataDir: string;
+    confirmIdentity?: boolean;
+}
+export interface StoreRegisterResult {
+    readonly store: {
+        id: string;
+        root: string;
+    };
+    readonly alreadyRegistered: boolean;
+    readonly createdArtifacts: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function prepareStoreRegistration(input: StoreRegisterInput): Promise<StoreRegisterResult>;
+export interface UnregisterStoreInput {
+    id: string;
+    dataDir: string;
+}
+export interface UnregisterStoreResult {
+    readonly removed: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function unregisterStore(input: UnregisterStoreInput): Promise<UnregisterStoreResult>;

package/dist/core/store/operations.js

@@ -0,0 +1,268 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { getStoreIdentityPath, StoreError, StoreIdentitySchema, validateStoreId, } from './foundation.js';
+import { registerStoreEntry, unregisterStoreEntry, readRegistry } from './registry.js';
+import { getStoreRegistryPath } from '../global-config.js';
+import { ensureDir } from '../../utils/file-system.js';
+const SPECFLOW_DIR = 'specflow';
+async function pathExists(targetPath) {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeStoreIdentity(root, identity) {
+    const identityPath = getStoreIdentityPath(root);
+    await ensureDir(path.dirname(identityPath));
+    await fs.writeFile(identityPath, yaml.dump(identity, { lineWidth: -1 }), 'utf-8');
+    return identityPath;
+}
+async function createPlanningRoot(root) {
+    const created = [];
+    const specflowDir = path.join(root, SPECFLOW_DIR);
+    await ensureDir(path.join(specflowDir, 'changes'));
+    await ensureDir(path.join(specflowDir, 'specs'));
+    const configPath = path.join(specflowDir, 'config.yaml');
+    if (!(await pathExists(configPath))) {
+        await fs.writeFile(configPath, 'schema: specflow\n', 'utf-8');
+        created.push(configPath);
+    }
+    created.push(specflowDir);
+    return created;
+}
+async function rollbackLedger(ledger) {
+    for (const artifact of [...ledger].reverse()) {
+        await fs.rm(artifact, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function prepareStoreSetup(input) {
+    validateStoreId(input.id);
+    const targetPath = path.resolve(input.targetPath);
+    if (await pathExists(targetPath)) {
+        throw new StoreError('Store setup target already exists.', {
+            severity: 'error',
+            code: 'store_target_exists',
+            message: 'Store setup accepts only a path that does not exist.',
+            target: 'store.path',
+            fix: 'Choose a missing path or adopt an existing directory with store register.',
+        });
+    }
+    const ledger = [];
+    const identity = {
+        version: 1,
+        id: input.id,
+        ...(input.remote ? { remote: input.remote } : {}),
+    };
+    try {
+        await fs.mkdir(targetPath, { recursive: false });
+        ledger.push(targetPath);
+        const created = await createPlanningRoot(targetPath);
+        ledger.push(...created);
+        const identityPath = await writeStoreIdentity(targetPath, identity);
+        ledger.push(identityPath);
+        const registryPath = getStoreRegistryPath(input.dataDir);
+        await registerStoreEntry(registryPath, {
+            id: input.id,
+            localPath: targetPath,
+            provenance: 'managed',
+            remote: input.remote,
+        });
+        return {
+            root: targetPath,
+            identity,
+            createdArtifacts: ledger,
+            diagnostics: [],
+        };
+    }
+    catch (error) {
+        await rollbackLedger(ledger);
+        throw error;
+    }
+}
+export async function removeManagedStore(input) {
+    const registryPath = getStoreRegistryPath(input.dataDir);
+    const registry = await readRegistry(registryPath);
+    const entry = registry.stores[input.id];
+    if (!entry) {
+        throw new StoreError(`Store '${input.id}' is not registered.`, {
+            severity: 'error',
+            code: 'store_not_registered',
+            message: `Store '${input.id}' is not registered.`,
+            target: `stores.${input.id}`,
+            fix: 'Run specflow store list to inspect registered stores.',
+        });
+    }
+    if (entry.provenance !== 'managed') {
+        throw new StoreError('Refusing to delete an external checkout.', {
+            severity: 'error',
+            code: 'store_external_delete_forbidden',
+            message: 'External checkouts cannot be deleted by SpecFlow.',
+            target: `stores.${input.id}`,
+            fix: 'Unregister the store instead of removing it.',
+        });
+    }
+    const checkoutPath = entry.backend.local_path;
+    const identityPath = getStoreIdentityPath(checkoutPath);
+    let identityMatches = false;
+    try {
+        const raw = yaml.load(await fs.readFile(identityPath, 'utf-8'));
+        const parsed = StoreIdentitySchema.safeParse(raw);
+        identityMatches = parsed.success && parsed.data.id === input.id;
+    }
+    catch {
+        identityMatches = false;
+    }
+    if (!identityMatches) {
+        throw new StoreError('Refusing to delete checkout with missing or mismatched identity.', {
+            severity: 'error',
+            code: 'store_identity_mismatch',
+            message: 'Checkout identity does not match the requested store ID.',
+            target: `stores.${input.id}`,
+            fix: 'Unregister the store instead of removing it.',
+        });
+    }
+    await unregisterStoreEntry(registryPath, input.id);
+    const deleteCheckout = input.deleteCheckout ??
+        (async (target) => {
+            await fs.rm(target, { recursive: true, force: true });
+        });
+    try {
+        await deleteCheckout(checkoutPath);
+        return { registryRemoved: true, checkoutDeleted: true, diagnostics: [] };
+    }
+    catch (error) {
+        return {
+            registryRemoved: true,
+            checkoutDeleted: false,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'store_delete_failed',
+                    message: `Managed store was unregistered but checkout deletion failed: ${error instanceof Error ? error.message : String(error)}`,
+                    target: `stores.${input.id}`,
+                    fix: `Manually remove ${checkoutPath} or re-register the store if you still need it.`,
+                },
+            ],
+        };
+    }
+}
+export async function listRegisteredStores(dataDir) {
+    const registry = await readRegistry(getStoreRegistryPath(dataDir));
+    return Object.entries(registry.stores).map(([id, entry]) => ({
+        id,
+        root: entry.backend.local_path,
+        provenance: entry.provenance,
+    }));
+}
+async function readStoreIdentity(root) {
+    const identityPath = getStoreIdentityPath(root);
+    try {
+        const raw = yaml.load(await fs.readFile(identityPath, 'utf-8'));
+        const parsed = StoreIdentitySchema.safeParse(raw);
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function isHealthySpecflowRoot(root) {
+    const configPath = path.join(root, 'specflow', 'config.yaml');
+    return pathExists(configPath);
+}
+export async function prepareStoreRegistration(input) {
+    validateStoreId(input.id);
+    const targetPath = path.resolve(input.localPath);
+    if (!(await pathExists(targetPath))) {
+        throw new StoreError('Registration path does not exist.', {
+            severity: 'error',
+            code: 'store_path_missing',
+            message: `Path '${targetPath}' does not exist.`,
+            target: 'store.path',
+            fix: 'Provide an existing checkout path.',
+        });
+    }
+    const stat = await fs.stat(targetPath);
+    if (!stat.isDirectory()) {
+        throw new StoreError('Registration path must be a directory.', {
+            severity: 'error',
+            code: 'store_path_not_directory',
+            message: 'Store registration requires a directory checkout.',
+            target: 'store.path',
+        });
+    }
+    if (!(await isHealthySpecflowRoot(targetPath))) {
+        throw new StoreError('Registration path is not a healthy SpecFlow root.', {
+            severity: 'error',
+            code: 'store_unhealthy_root',
+            message: 'Expected specflow/config.yaml under the checkout.',
+            target: 'store.path',
+            fix: 'Run specflow init in the checkout or choose a valid planning root.',
+        });
+    }
+    const existingIdentity = await readStoreIdentity(targetPath);
+    if (existingIdentity && existingIdentity.id !== input.id) {
+        throw new StoreError('Committed store identity conflicts with requested ID.', {
+            severity: 'error',
+            code: 'store_identity_conflict',
+            message: `Checkout identity is '${existingIdentity.id}' but registration requested '${input.id}'.`,
+            target: 'store.id',
+            fix: `Register as '${existingIdentity.id}' or choose a different checkout.`,
+        });
+    }
+    const createdArtifacts = [];
+    let identityToWrite = existingIdentity;
+    if (!existingIdentity) {
+        if (!input.confirmIdentity) {
+            throw new StoreError('Identity adoption requires explicit confirmation.', {
+                severity: 'error',
+                code: 'store_identity_confirmation_required',
+                message: 'Non-interactive registration must pass --yes to create store identity.',
+                target: 'store.id',
+                fix: `Re-run with --yes to create .specflow-store/store.yaml for '${input.id}'.`,
+            });
+        }
+        identityToWrite = { version: 1, id: input.id };
+        const identityPath = await writeStoreIdentity(targetPath, identityToWrite);
+        createdArtifacts.push(identityPath);
+    }
+    const registryPath = getStoreRegistryPath(input.dataDir);
+    try {
+        const { alreadyRegistered } = await registerStoreEntry(registryPath, {
+            id: input.id,
+            localPath: targetPath,
+            provenance: 'external',
+            remote: identityToWrite?.remote,
+        });
+        return {
+            store: { id: input.id, root: targetPath },
+            alreadyRegistered,
+            createdArtifacts,
+            diagnostics: [],
+        };
+    }
+    catch (error) {
+        for (const artifact of [...createdArtifacts].reverse()) {
+            await fs.rm(artifact, { force: true }).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+export async function unregisterStore(input) {
+    const registryPath = getStoreRegistryPath(input.dataDir);
+    const registry = await readRegistry(registryPath);
+    if (!registry.stores[input.id]) {
+        throw new StoreError(`Store '${input.id}' is not registered.`, {
+            severity: 'error',
+            code: 'store_not_registered',
+            message: `Store '${input.id}' is not registered.`,
+            target: `stores.${input.id}`,
+            fix: 'Run specflow store list to inspect registered stores.',
+        });
+    }
+    await unregisterStoreEntry(registryPath, input.id);
+    return { removed: true, diagnostics: [] };
+}

package/dist/core/store/registry.d.ts

@@ -0,0 +1,15 @@
+import { type StoreRegistry } from './foundation.js';
+export declare function readRegistry(registryPath: string): Promise<StoreRegistry>;
+export declare function updateRegistry(registryPath: string, updater: (state: StoreRegistry) => StoreRegistry): Promise<StoreRegistry>;
+export declare function findPathConflict(registry: StoreRegistry, targetPath: string, storeId: string, platform?: NodeJS.Platform): string | null;
+export declare function registerStoreEntry(registryPath: string, input: {
+    id: string;
+    localPath: string;
+    provenance: 'managed' | 'external';
+    remote?: string;
+    branch?: string;
+}): Promise<{
+    registry: StoreRegistry;
+    alreadyRegistered: boolean;
+}>;
+export declare function unregisterStoreEntry(registryPath: string, storeId: string): Promise<StoreRegistry>;

package/dist/core/store/registry.js

@@ -0,0 +1,128 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { acquireFileLock, releaseFileLock, writeFileAtomically, makeLockErrorFactory, } from '../file-state.js';
+import { StoreRegistrySchema, emptyRegistry, pathsReferToSameCheckout, StoreError, } from './foundation.js';
+function lockPathFor(registryPath) {
+    return `${registryPath}.lock`;
+}
+function makeRegistryLockError() {
+    return makeLockErrorFactory({
+        createSubject: 'the registry lock file',
+        busyMessage: 'Store registry is busy.',
+        code: 'registry_busy',
+        target: 'stores.registry',
+    });
+}
+export async function readRegistry(registryPath) {
+    try {
+        const content = await fs.readFile(registryPath, 'utf-8');
+        const parsed = yaml.load(content);
+        const result = StoreRegistrySchema.safeParse(parsed);
+        if (!result.success) {
+            throw new StoreError('Store registry is corrupt.', {
+                severity: 'error',
+                code: 'registry_corrupt',
+                message: 'Store registry failed schema validation.',
+                target: 'stores.registry',
+                fix: 'Repair or delete the registry file and re-register stores.',
+            });
+        }
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof StoreError) {
+            throw error;
+        }
+        if (error.code === 'ENOENT') {
+            return emptyRegistry();
+        }
+        throw error;
+    }
+}
+async function writeRegistry(registryPath, state) {
+    const content = yaml.dump(state, { lineWidth: -1, noRefs: true });
+    await writeFileAtomically(registryPath, content);
+}
+export async function updateRegistry(registryPath, updater) {
+    const lock = await acquireFileLock({
+        lockPath: lockPathFor(registryPath),
+        errorFor: makeRegistryLockError(),
+    });
+    try {
+        const current = await readRegistry(registryPath);
+        const next = updater(current);
+        const validated = StoreRegistrySchema.parse(next);
+        await writeRegistry(registryPath, validated);
+        return validated;
+    }
+    finally {
+        await releaseFileLock(lock, lockPathFor(registryPath));
+    }
+}
+export function findPathConflict(registry, targetPath, storeId, platform = process.platform) {
+    for (const [existingId, entry] of Object.entries(registry.stores)) {
+        if (existingId === storeId) {
+            continue;
+        }
+        if (pathsReferToSameCheckout(entry.backend.local_path, targetPath, platform)) {
+            return existingId;
+        }
+    }
+    return null;
+}
+export async function registerStoreEntry(registryPath, input) {
+    const canonicalPath = path.resolve(input.localPath);
+    let alreadyRegistered = false;
+    const registry = await updateRegistry(registryPath, (state) => {
+        const existing = state.stores[input.id];
+        if (existing) {
+            if (pathsReferToSameCheckout(existing.backend.local_path, canonicalPath)) {
+                alreadyRegistered = true;
+                return state;
+            }
+            throw new StoreError(`Store '${input.id}' is already registered at another path.`, {
+                severity: 'error',
+                code: 'store_id_conflict',
+                message: `Store '${input.id}' is already registered elsewhere.`,
+                target: `stores.${input.id}`,
+                fix: 'Unregister the existing checkout or choose another store ID.',
+            });
+        }
+        const aliasConflict = findPathConflict(state, canonicalPath, input.id);
+        if (aliasConflict) {
+            throw new StoreError(`Path already registered as '${aliasConflict}'.`, {
+                severity: 'error',
+                code: 'store_path_conflict',
+                message: `The checkout path is already registered under '${aliasConflict}'.`,
+                target: 'stores.registry',
+                fix: 'Use the existing registration or unregister the conflicting store first.',
+            });
+        }
+        return {
+            version: 1,
+            stores: {
+                ...state.stores,
+                [input.id]: {
+                    provenance: input.provenance,
+                    backend: {
+                        type: 'git',
+                        local_path: canonicalPath,
+                        ...(input.remote ? { remote: input.remote } : {}),
+                        ...(input.branch ? { branch: input.branch } : {}),
+                    },
+                },
+            },
+        };
+    });
+    return { registry, alreadyRegistered };
+}
+export async function unregisterStoreEntry(registryPath, storeId) {
+    return updateRegistry(registryPath, (state) => {
+        if (!state.stores[storeId]) {
+            return state;
+        }
+        const { [storeId]: _removed, ...rest } = state.stores;
+        return { version: 1, stores: rest };
+    });
+}

package/dist/core/working-set.d.ts

@@ -0,0 +1,30 @@
+import type { Diagnostic } from './diagnostics.js';
+export interface WorkingSetMember {
+    readonly storeId: string;
+    readonly path?: string;
+    readonly healthy: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly fetchRecipe?: string;
+}
+export interface WorkingSet {
+    readonly members: readonly WorkingSetMember[];
+}
+export declare function assembleWorkingSet(input: {
+    root: {
+        storeId: string;
+        path: string;
+        healthy: boolean;
+    };
+    references: Array<{
+        storeId: string;
+        healthy: boolean;
+        path?: string;
+        diagnostics: Diagnostic[];
+    }>;
+}): WorkingSet;
+export declare function buildWorkingSetCodeWorkspaceJson(workingSet: WorkingSet): {
+    folders: Array<{
+        name: string;
+        path: string;
+    }>;
+};

package/dist/core/working-set.js

@@ -0,0 +1,26 @@
+export function assembleWorkingSet(input) {
+    const members = [
+        {
+            storeId: input.root.storeId,
+            path: input.root.path,
+            healthy: input.root.healthy,
+            diagnostics: [],
+            fetchRecipe: `specflow context --store ${input.root.storeId}`,
+        },
+        ...input.references.map((ref) => ({
+            storeId: ref.storeId,
+            path: ref.healthy ? ref.path : undefined,
+            healthy: ref.healthy,
+            diagnostics: ref.diagnostics,
+            fetchRecipe: ref.healthy ? `specflow show <spec-id> --type spec --store ${ref.storeId}` : undefined,
+        })),
+    ];
+    return { members };
+}
+export function buildWorkingSetCodeWorkspaceJson(workingSet) {
+    return {
+        folders: workingSet.members
+            .filter((member) => member.healthy && member.path)
+            .map((member) => ({ name: member.storeId, path: member.path })),
+    };
+}