@gordon.gan/specflow 1.0.0

package/dist/integrations/shared/parity-manifest.js

@@ -0,0 +1,58 @@
+import { COMMAND_IDS } from './command-catalog.js';
+export const CAPABILITY_MANIFEST = [
+    ...COMMAND_IDS.map((id) => ({
+        id: `command.${id}`,
+        commandId: id,
+        level: 'command',
+        required: true,
+    })),
+    { id: 'sub.scan.planned_v03_notice', commandId: 'scan', level: 'sub-capability', required: true },
+    { id: 'sub.plan.first_iteration', commandId: 'plan', level: 'sub-capability', required: true },
+    { id: 'sub.refine.multi_round', commandId: 'refine', level: 'sub-capability', required: true },
+    { id: 'sub.refine.challenge_scope', commandId: 'refine', level: 'sub-capability', required: true },
+    { id: 'sub.build.phase_a', commandId: 'build', level: 'sub-capability', required: true },
+    { id: 'sub.build.phase_b', commandId: 'build', level: 'sub-capability', required: true },
+    { id: 'sub.build.gap_detection', commandId: 'build', level: 'sub-capability', required: true },
+    { id: 'sub.review.spec_regression', commandId: 'review', level: 'sub-capability', required: true },
+    { id: 'sub.test.full_scope', commandId: 'test', level: 'sub-capability', required: true },
+    { id: 'sub.verify.dual_validation', commandId: 'verify', level: 'sub-capability', required: true },
+    { id: 'sub.done.archive_merge', commandId: 'done', level: 'sub-capability', required: true },
+    { id: 'sub.fix.urgent_mode', commandId: 'fix', level: 'sub-capability', required: true },
+    { id: 'sub.snap.posthoc', commandId: 'snap', level: 'sub-capability', required: true },
+    { id: 'failure.scan.not_implemented_guard', commandId: 'scan', level: 'failure-path', required: true },
+    { id: 'failure.build.phase_gate', commandId: 'build', level: 'failure-path', required: true },
+    { id: 'failure.verify.explicit_skip_marker', commandId: 'verify', level: 'failure-path', required: true },
+];
+export const IDE_ASSET_MANIFEST = [
+    {
+        ide: 'claude',
+        requiredAssetKeys: [
+            'commandsDir',
+            'skillsDir',
+            'runtimePromptsDir',
+            'runtimeSchemasDir',
+            'runtimeTemplatesDir',
+        ],
+    },
+    {
+        ide: 'cursor',
+        requiredAssetKeys: [
+            'commandsDir',
+            'skillsDir',
+            'rulesFile',
+            'runtimePromptsDir',
+            'runtimeSchemasDir',
+            'runtimeTemplatesDir',
+        ],
+    },
+    {
+        ide: 'codex',
+        requiredAssetKeys: [
+            'skillsDir',
+            'agentsFile',
+            'runtimePromptsDir',
+            'runtimeSchemasDir',
+            'runtimeTemplatesDir',
+        ],
+    },
+];

package/dist/integrations/shared/runtime-assets.d.ts

@@ -0,0 +1,2 @@
+import type { IdeTarget } from './types.js';
+export declare function copyRuntimeAssets(packageRoot: string, projectRoot: string, ide: IdeTarget): Promise<readonly string[]>;

package/dist/integrations/shared/runtime-assets.js

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { copyDirRecursive, copyDirRecursiveRendered } from './asset-copy.js';
+import { renderIdeContent } from './skill-renderer.js';
+function ideRootDir(ide) {
+    if (ide === 'claude') {
+        return '.claude';
+    }
+    if (ide === 'cursor') {
+        return '.cursor';
+    }
+    return '.agents';
+}
+export async function copyRuntimeAssets(packageRoot, projectRoot, ide) {
+    const root = join(projectRoot, ideRootDir(ide), 'specflow');
+    const promptsSrc = join(packageRoot, 'prompts');
+    const promptsDest = join(root, 'prompts');
+    await copyDirRecursiveRendered(promptsSrc, promptsDest, (content) => renderIdeContent(content, ide));
+    await copyDirRecursive(join(packageRoot, 'schemas'), join(root, 'schemas'));
+    await copyDirRecursive(join(packageRoot, 'templates'), join(root, 'templates'));
+    return [`${ideRootDir(ide)}/specflow/prompts`, `${ideRootDir(ide)}/specflow/schemas`, `${ideRootDir(ide)}/specflow/templates`];
+}

package/dist/integrations/shared/skill-renderer.d.ts

@@ -0,0 +1,5 @@
+import type { IdeTarget } from './types.js';
+export declare function renderIdeContent(content: string, ide: IdeTarget): string;
+/** @deprecated Use renderIdeContent */
+export declare const renderSkillContent: typeof renderIdeContent;
+export declare function validateSkillFrontmatter(content: string, skillLabel: string): void;

package/dist/integrations/shared/skill-renderer.js

@@ -0,0 +1,77 @@
+import { COMMAND_CATALOG } from './command-catalog.js';
+function runtimePrefix(ide) {
+    if (ide === 'claude') {
+        return '.claude/specflow/';
+    }
+    if (ide === 'cursor') {
+        return '.cursor/specflow/';
+    }
+    return '.agents/specflow/';
+}
+function replaceRuntimePaths(content, ide) {
+    const prefix = runtimePrefix(ide);
+    return content
+        .replace(/\.claude\/specflow\//g, prefix)
+        .replace(/\.cursor\/specflow\//g, prefix)
+        .replace(/\.agents\/specflow\//g, prefix);
+}
+function replaceInvocationSyntax(content, ide) {
+    if (ide !== 'codex') {
+        return content;
+    }
+    let result = content;
+    for (const command of COMMAND_CATALOG) {
+        const slash = `/specflow:${command.id}`;
+        const bare = `specflow:${command.id}`;
+        const dollar = `$specflow-${command.id}`;
+        result = result.replaceAll(slash, dollar);
+        result = result.replace(new RegExp(`\\b${bare.replace(':', '\\:')}\\b`, 'g'), dollar);
+    }
+    return result;
+}
+function replaceScanInitHint(content, ide) {
+    const fullHint = 'creates `specflow/` and IDE assets under `.cursor/`, `.claude/`, and/or `.agents/`.';
+    if (ide === 'claude') {
+        return content.replace(fullHint, 'creates `specflow/` and IDE assets under `.claude/`.');
+    }
+    if (ide === 'cursor') {
+        return content.replace(fullHint, 'creates `specflow/` and IDE assets under `.cursor/`.');
+    }
+    return content.replace(fullHint, 'creates `specflow/` and IDE assets under `.agents/`.');
+}
+function replaceScanDispatchPaths(content, ide) {
+    const prefix = runtimePrefix(ide);
+    const dispatchPath = `${prefix}prompts/shared/dispatching-parallel-agents.md`;
+    const label = ide === 'codex' ? 'Codex' : ide === 'cursor' ? 'Cursor' : 'Claude';
+    const block = `- ${label}: \`${dispatchPath}\``;
+    return content.replace(/- Cursor: `\.cursor\/specflow\/prompts\/shared\/dispatching-parallel-agents\.md`\n- Claude: `\.claude\/specflow\/prompts\/shared\/dispatching-parallel-agents\.md`(?:\n- Codex: `\.agents\/specflow\/prompts\/shared\/dispatching-parallel-agents\.md`)?/, block);
+}
+function replaceToolDocReferences(content) {
+    return content
+        .replace('`references/copilot-tools.md`', '`reference/superpowers/copilot-tools.md`')
+        .replace('`references/codex-tools.md`', '`reference/superpowers/codex-tools.md`');
+}
+export function renderIdeContent(content, ide) {
+    let result = content;
+    result = replaceRuntimePaths(result, ide);
+    result = replaceInvocationSyntax(result, ide);
+    result = replaceScanInitHint(result, ide);
+    result = replaceScanDispatchPaths(result, ide);
+    result = replaceToolDocReferences(result);
+    return result;
+}
+/** @deprecated Use renderIdeContent */
+export const renderSkillContent = renderIdeContent;
+export function validateSkillFrontmatter(content, skillLabel) {
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+        throw new Error(`${skillLabel} missing YAML frontmatter`);
+    }
+    const frontmatter = frontmatterMatch[1];
+    if (!/^name:\s*.+/m.test(frontmatter)) {
+        throw new Error(`${skillLabel} missing frontmatter name`);
+    }
+    if (!/^description:\s*.+/m.test(frontmatter)) {
+        throw new Error(`${skillLabel} missing frontmatter description`);
+    }
+}

package/dist/integrations/shared/types.d.ts

@@ -0,0 +1,35 @@
+export type IdeTarget = 'claude' | 'cursor' | 'codex';
+export type InitIdeTarget = IdeTarget | 'both' | 'all';
+export interface AssetState {
+    readonly exists: boolean;
+    readonly hash?: string;
+}
+export interface CapabilityReport {
+    readonly ide: IdeTarget;
+    readonly supportedCommandIds: readonly string[];
+    readonly supportedCapabilityIds: readonly string[];
+    readonly assets: Readonly<Record<string, AssetState>>;
+}
+export interface ParityDelta {
+    readonly id: string;
+    readonly severity: 'P0' | 'P1';
+    readonly message: string;
+}
+export interface ParityStatus {
+    readonly ok: boolean;
+    readonly deltas: readonly ParityDelta[];
+}
+export interface GenerateContext {
+    readonly projectRoot: string;
+    readonly packageRoot: string;
+    readonly forceAssets?: boolean;
+}
+export interface GenerateResult {
+    readonly ide: IdeTarget;
+    readonly generatedPaths: readonly string[];
+}
+export interface Adapter {
+    readonly ide: IdeTarget;
+    generate(ctx: GenerateContext): Promise<GenerateResult>;
+    inspect(projectRoot: string): Promise<CapabilityReport>;
+}

package/dist/integrations/shared/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/change-metadata.d.ts

@@ -0,0 +1,38 @@
+/**
+ * All valid lifecycle phases a change can be in.
+ *
+ * - `plan`: Initial phase, created by `specflow change new`.
+ * - `refined`: After `/specflow:refine` iterative deep review completes.
+ * - `built`: After `/specflow:build` Phase B execution finishes.
+ * - `archived`: Post-archive state; assigned automatically on successful archive.
+ */
+export declare const CHANGE_PHASES: readonly ["plan", "refined", "built", "archived"];
+/**
+ * Union type of valid lifecycle phases.
+ */
+export type ChangePhase = (typeof CHANGE_PHASES)[number];
+/**
+ * Metadata stored in each change's .specflow.yaml file.
+ */
+export interface ChangeMetadata {
+    readonly schema: string;
+    readonly created: string;
+    readonly phase?: ChangePhase;
+    readonly [key: string]: unknown;
+}
+/**
+ * Reads change metadata from .specflow.yaml in the change directory.
+ *
+ * @param changeDir - Absolute path to the change directory
+ * @returns The parsed metadata, or null if the file does not exist
+ * @throws When the file exists but cannot be read or parsed
+ */
+export declare function readChangeMetadata(changeDir: string): Promise<ChangeMetadata | null>;
+/**
+ * Writes change metadata to .specflow.yaml in the change directory.
+ * Creates parent directories if they do not exist.
+ *
+ * @param changeDir - Absolute path to the change directory
+ * @param metadata - The metadata to write
+ */
+export declare function writeChangeMetadata(changeDir: string, metadata: ChangeMetadata): Promise<void>;

package/dist/utils/change-metadata.js

@@ -0,0 +1,82 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+const METADATA_FILENAME = '.specflow.yaml';
+/**
+ * All valid lifecycle phases a change can be in.
+ *
+ * - `plan`: Initial phase, created by `specflow change new`.
+ * - `refined`: After `/specflow:refine` iterative deep review completes.
+ * - `built`: After `/specflow:build` Phase B execution finishes.
+ * - `archived`: Post-archive state; assigned automatically on successful archive.
+ */
+export const CHANGE_PHASES = ['plan', 'refined', 'built', 'archived'];
+/**
+ * Zod schema for validating change metadata.
+ *
+ * Uses `passthrough` so that unknown fields (e.g. user-added comments) survive
+ * round-tripping rather than being stripped silently.
+ */
+const changeMetadataSchema = z
+    .object({
+    schema: z.string(),
+    created: z.string(),
+    phase: z.enum(CHANGE_PHASES).optional(),
+})
+    .passthrough();
+/**
+ * Formats a Zod error into a user-friendly message.
+ *
+ * - Invalid phase values get a canonical enum list.
+ * - Missing schema/created fields get the legacy "Invalid metadata format" message.
+ */
+function formatZodError(error, metaPath) {
+    const hasInvalidPhase = error.issues.some((issue) => issue.path[0] === 'phase' && issue.code === 'invalid_enum_value');
+    if (hasInvalidPhase) {
+        return new Error('Invalid phase in metadata: expected one of plan|refined|built|archived');
+    }
+    return new Error(`Invalid metadata format in ${metaPath}: ${error.message}`);
+}
+/**
+ * Reads change metadata from .specflow.yaml in the change directory.
+ *
+ * @param changeDir - Absolute path to the change directory
+ * @returns The parsed metadata, or null if the file does not exist
+ * @throws When the file exists but cannot be read or parsed
+ */
+export async function readChangeMetadata(changeDir) {
+    const metaPath = join(changeDir, METADATA_FILENAME);
+    let content;
+    try {
+        content = await fs.readFile(metaPath, 'utf-8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+    const parsed = yaml.load(content);
+    if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
+        throw new Error(`Invalid metadata format in ${metaPath}`);
+    }
+    const result = changeMetadataSchema.safeParse(parsed);
+    if (!result.success) {
+        throw formatZodError(result.error, metaPath);
+    }
+    return result.data;
+}
+/**
+ * Writes change metadata to .specflow.yaml in the change directory.
+ * Creates parent directories if they do not exist.
+ *
+ * @param changeDir - Absolute path to the change directory
+ * @param metadata - The metadata to write
+ */
+export async function writeChangeMetadata(changeDir, metadata) {
+    await fs.mkdir(changeDir, { recursive: true });
+    const metaPath = join(changeDir, METADATA_FILENAME);
+    const content = yaml.dump(metadata);
+    await fs.writeFile(metaPath, content, 'utf-8');
+}

package/dist/utils/change-utils.d.ts

@@ -0,0 +1,53 @@
+import type { ChangeMetadata, ChangePhase } from './change-metadata.js';
+export { CHANGE_PHASES } from './change-metadata.js';
+export type { ChangePhase } from './change-metadata.js';
+/**
+ * Validates that a change name uses only lowercase alphanumeric characters
+ * separated by single hyphens. Prevents path traversal and invalid directory names.
+ *
+ * @param name - The change name to validate
+ * @throws When the name does not match the required pattern
+ */
+export declare function validateChangeName(name: string): void;
+/**
+ * Returns the relative path for a change directory (with trailing slash).
+ *
+ * @param changeName - Name of the change (kebab-case)
+ * @returns The relative path, e.g. "specflow/changes/my-feature/"
+ */
+export declare function getChangeDir(changeName: string): string;
+/**
+ * Reads the .specflow.yaml metadata for a given change.
+ *
+ * @param changeName - Name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The parsed metadata, or null if the file does not exist
+ */
+export declare function getChangeMetadata(changeName: string, projectRoot: string): Promise<ChangeMetadata | null>;
+/**
+ * Writes .specflow.yaml metadata for a given change.
+ * Creates the change directory and parent directories if needed.
+ *
+ * @param changeName - Name of the change
+ * @param metadata - The metadata to write
+ * @param projectRoot - Absolute path to the project root
+ */
+export declare function writeChangeMetadata(changeName: string, metadata: ChangeMetadata, projectRoot: string): Promise<void>;
+/**
+ * Updates the `phase` field of an existing change's metadata, preserving all
+ * other fields. Throws if the change does not exist.
+ *
+ * @param changeName - Name of the change
+ * @param phase - The new phase value
+ * @param projectRoot - Absolute path to the project root (or archive root)
+ * @throws When the change does not exist or the name is invalid
+ */
+export declare function updatePhase(changeName: string, phase: ChangePhase, projectRoot: string): Promise<void>;
+/**
+ * Lists all change directory names under specflow/changes/.
+ * Returns an empty array if the directory does not exist or is empty.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Array of change directory names
+ */
+export declare function listChanges(projectRoot: string): Promise<string[]>;

package/dist/utils/change-utils.js

@@ -0,0 +1,97 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { readChangeMetadata, writeChangeMetadata as writeMetaInternal } from './change-metadata.js';
+export { CHANGE_PHASES } from './change-metadata.js';
+const CHANGES_REL_PATH = 'specflow/changes';
+const VALID_CHANGE_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Validates that a change name uses only lowercase alphanumeric characters
+ * separated by single hyphens. Prevents path traversal and invalid directory names.
+ *
+ * @param name - The change name to validate
+ * @throws When the name does not match the required pattern
+ */
+export function validateChangeName(name) {
+    if (!VALID_CHANGE_NAME.test(name)) {
+        throw new Error(`Invalid change name "${name}". Use lowercase alphanumeric with hyphens (e.g., "my-feature").`);
+    }
+}
+/**
+ * Returns the relative path for a change directory (with trailing slash).
+ *
+ * @param changeName - Name of the change (kebab-case)
+ * @returns The relative path, e.g. "specflow/changes/my-feature/"
+ */
+export function getChangeDir(changeName) {
+    validateChangeName(changeName);
+    return `${CHANGES_REL_PATH}/${changeName}/`;
+}
+/**
+ * Reads the .specflow.yaml metadata for a given change.
+ *
+ * @param changeName - Name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The parsed metadata, or null if the file does not exist
+ */
+export async function getChangeMetadata(changeName, projectRoot) {
+    validateChangeName(changeName);
+    const changeDir = join(projectRoot, CHANGES_REL_PATH, changeName);
+    return await readChangeMetadata(changeDir);
+}
+/**
+ * Writes .specflow.yaml metadata for a given change.
+ * Creates the change directory and parent directories if needed.
+ *
+ * @param changeName - Name of the change
+ * @param metadata - The metadata to write
+ * @param projectRoot - Absolute path to the project root
+ */
+export async function writeChangeMetadata(changeName, metadata, projectRoot) {
+    validateChangeName(changeName);
+    const changeDir = join(projectRoot, CHANGES_REL_PATH, changeName);
+    await writeMetaInternal(changeDir, metadata);
+}
+/**
+ * Updates the `phase` field of an existing change's metadata, preserving all
+ * other fields. Throws if the change does not exist.
+ *
+ * @param changeName - Name of the change
+ * @param phase - The new phase value
+ * @param projectRoot - Absolute path to the project root (or archive root)
+ * @throws When the change does not exist or the name is invalid
+ */
+export async function updatePhase(changeName, phase, projectRoot) {
+    validateChangeName(changeName);
+    const changeDir = join(projectRoot, CHANGES_REL_PATH, changeName);
+    const existing = await readChangeMetadata(changeDir);
+    if (existing === null) {
+        throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+    }
+    const updated = {
+        ...existing,
+        phase,
+    };
+    await writeMetaInternal(changeDir, updated);
+}
+/**
+ * Lists all change directory names under specflow/changes/.
+ * Returns an empty array if the directory does not exist or is empty.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Array of change directory names
+ */
+export async function listChanges(projectRoot) {
+    const changesDir = join(projectRoot, CHANGES_REL_PATH);
+    try {
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}

package/dist/utils/file-system.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Checks whether a directory exists at the given path.
+ *
+ * @param dirPath - Absolute path to check
+ * @returns true if the path is an existing directory, false otherwise
+ */
+export declare function directoryExists(dirPath: string): Promise<boolean>;
+/**
+ * Checks whether a file (not a directory) exists at the given path.
+ *
+ * @param filePath - Absolute path to check
+ * @returns true if the path is an existing file, false otherwise
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Reads a file and returns its contents as a UTF-8 string.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns The file contents
+ * @throws When the file does not exist or cannot be read
+ */
+export declare function readFile(filePath: string): Promise<string>;
+/**
+ * Writes content to a file, auto-creating parent directories as needed.
+ *
+ * @param filePath - Absolute path where the file should be written
+ * @param content - The string content to write
+ */
+export declare function writeFile(filePath: string, content: string): Promise<void>;
+/**
+ * Ensures a directory exists, creating it and all parent directories as needed.
+ *
+ * @param dirPath - Absolute path to the directory
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;

package/dist/utils/file-system.js

@@ -0,0 +1,67 @@
+import { promises as fs } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Checks whether a directory exists at the given path.
+ *
+ * @param dirPath - Absolute path to check
+ * @returns true if the path is an existing directory, false otherwise
+ */
+export async function directoryExists(dirPath) {
+    try {
+        const stats = await fs.stat(dirPath);
+        return stats.isDirectory();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Checks whether a file (not a directory) exists at the given path.
+ *
+ * @param filePath - Absolute path to check
+ * @returns true if the path is an existing file, false otherwise
+ */
+export async function fileExists(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isFile();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Reads a file and returns its contents as a UTF-8 string.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns The file contents
+ * @throws When the file does not exist or cannot be read
+ */
+export async function readFile(filePath) {
+    return await fs.readFile(filePath, 'utf-8');
+}
+/**
+ * Writes content to a file, auto-creating parent directories as needed.
+ *
+ * @param filePath - Absolute path where the file should be written
+ * @param content - The string content to write
+ */
+export async function writeFile(filePath, content) {
+    const dir = dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Ensures a directory exists, creating it and all parent directories as needed.
+ *
+ * @param dirPath - Absolute path to the directory
+ */
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+export { directoryExists, fileExists, readFile, writeFile, ensureDir, } from './file-system.js';
+export { readChangeMetadata, writeChangeMetadata as writeChangeMetadataToDir, CHANGE_PHASES, } from './change-metadata.js';
+export type { ChangeMetadata, ChangePhase } from './change-metadata.js';
+export { getChangeDir, getChangeMetadata, writeChangeMetadata, listChanges, updatePhase, } from './change-utils.js';
+export { parseTask, toggleTask, countTasks, } from './task-progress.js';
+export type { ParsedTask, TaskCount } from './task-progress.js';
+export { findProjectRoot, requireProjectRoot, } from './project-root.js';

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+export { directoryExists, fileExists, readFile, writeFile, ensureDir, } from './file-system.js';
+export { readChangeMetadata, writeChangeMetadata as writeChangeMetadataToDir, CHANGE_PHASES, } from './change-metadata.js';
+export { getChangeDir, getChangeMetadata, writeChangeMetadata, listChanges, updatePhase, } from './change-utils.js';
+export { parseTask, toggleTask, countTasks, } from './task-progress.js';
+export { findProjectRoot, requireProjectRoot, } from './project-root.js';

package/dist/utils/project-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project root detection utility.
+ *
+ * Walks upward from a starting directory looking for `specflow/config.yaml`,
+ * similar to how `git` finds `.git/`. This lets the CLI work from any
+ * subdirectory within a specflow-initialized project.
+ */
+/**
+ * Find the specflow project root by walking up from a starting directory.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the project root, or null if not found
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Resolve project root with a clear error if not found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the project root
+ * @throws Error with actionable message if no specflow project is detected
+ */
+export declare function requireProjectRoot(startDir?: string): string;

package/dist/utils/project-root.js

@@ -0,0 +1,44 @@
+/**
+ * Project root detection utility.
+ *
+ * Walks upward from a starting directory looking for `specflow/config.yaml`,
+ * similar to how `git` finds `.git/`. This lets the CLI work from any
+ * subdirectory within a specflow-initialized project.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const CONFIG_MARKER = join('specflow', 'config.yaml');
+/**
+ * Find the specflow project root by walking up from a starting directory.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the project root, or null if not found
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, CONFIG_MARKER))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+/**
+ * Resolve project root with a clear error if not found.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the project root
+ * @throws Error with actionable message if no specflow project is detected
+ */
+export function requireProjectRoot(startDir = process.cwd()) {
+    const root = findProjectRoot(startDir);
+    if (root === null) {
+        throw new Error(`No specflow project found at or above ${startDir}. ` +
+            `Run \`specflow init\` in your project root to initialize one.`);
+    }
+    return root;
+}