flowspec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Owens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# FlowSpec
+
+Immutable user flow specifications for the age of agentic coding.
+
+## The Problem
+
+AI coding agents can modify both implementation and tests. When a test fails, the agent might "fix" the test instead of fixing the bug. This breaks the feedback loop that catches regressions.
+
+## The Solution
+
+FlowSpec separates **what your app should do** (immutable specs) from **how it does it** (agent-modifiable code).
+
+- Write user flows in simple YAML
+- Use human-readable labels (accessibility-first, a la React Testing Library)
+- Protect specs from agent modification via Claude Code hooks
+- Run deterministically in CI or interactively with an agent
+
+## Installation
+
+```bash
+# Install globally
+npm install -g flowspec
+
+# Or with bun
+bun add -g flowspec
+```
+
+Requires [agent-browser](https://github.com/anthropics/agent-browser) for browser automation.
+
+## Usage
+
+### Initialize a New Project
+
+```bash
+# Scaffold a new FlowSpec project
+flowspec init
+```
+
+This creates:
+- `flowspec.config.yaml` - Project configuration
+- `specs/example.flow.yaml` - Sample flow to get started
+- `.claude/settings.local.json` - Hooks to protect specs from AI modification
+- Updates `package.json` with `test:e2e` script
+
+### Run Flows
+
+```bash
+# Run a single flow file
+flowspec run specs/checkout.flow.yaml
+
+# Run all flows in a directory
+flowspec run specs/
+
+# Specify a custom base URL
+flowspec run specs/ --base-url http://localhost:8080
+
+# Set assertion retry timeout (default: 5000ms)
+flowspec run specs/ --timeout 10000
+
+# Disable assertion retries (fail immediately)
+flowspec run specs/ --timeout 0
+
+# Show help
+flowspec --help
+```
+
+### Configuration File
+
+FlowSpec looks for `flowspec.config.yaml` in the current directory or parent directories:
+
+```yaml
+baseUrl: http://localhost:3000
+timeout: 10000
+specsDir: specs/
+```
+
+CLI options override config file values.
+
+### Exit Codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | All flows passed |
+| 1 | One or more flows failed |
+| 2 | Parse error (invalid YAML or schema) |
+
+## Flow File Format
+
+Flow files use YAML with a simple structure:
+
+```yaml
+name: user-login
+description: User can log in with valid credentials
+steps:
+  - visit: /login
+  - fill:
+      Email: user@example.com
+      Password: secretpassword
+  - click: Sign In
+expect:
+  - url: /dashboard
+  - visible: Welcome back
+```
+
+### Step Actions
+
+| Action | Description | Example |
+| ------ | ----------- | ------- |
+| `visit` | Navigate to a URL (relative or absolute) | `visit: /login` |
+| `click` | Click element by visible text | `click: "Sign In"` |
+| `fill` | Fill form fields by label | `fill: { Email: user@example.com }` |
+| `select` | Select dropdown option by label | `select: { Country: "United States" }` |
+| `wait_for` | Wait for text to appear (with retry) | `wait_for: "Loading complete"` |
+
+### Assertions
+
+| Assertion | Description | Example |
+| --------- | ----------- | ------- |
+| `url` | Check current URL contains value | `url: /dashboard` |
+| `visible` | Check text is visible on page | `visible: "Welcome back"` |
+| `matches` | Check page content matches regex | `matches: "Order #\\d+"` |
+| `not_visible` | Check text is NOT on page | `not_visible: "Error"` |
+
+## Quick Example
+
+```yaml
+# specs/checkout.flow.yaml
+name: checkout-flow
+description: |
+  User completes a purchase with items in cart.
+  Captures shipping/billing info and confirms order.
+
+steps:
+  - visit: "/cart"
+  - click: "Proceed to Checkout"
+  - fill:
+      "Email": "user@example.com"
+      "Shipping Address": "123 Main St"
+  - click: "Place Order"
+
+expect:
+  - url: "/order/confirmation"
+  - visible: "Order confirmed"
+  - matches: "Order #\\d+"
+```
+
+## Development
+
+```bash
+bun install                    # Install dependencies
+bun run build                  # Build CLI (required for bun link)
+bun link                       # Link CLI locally as 'flowspec'
+bun test                       # Run tests
+bun run typecheck              # Type check
+bun run lint                   # Lint with Biome
+bun run lint:fix               # Auto-fix lint issues
+bun run format                 # Format with Biome
+bun run test:coverage          # Run with coverage
+```
+
+### Project Structure
+
+```text
+FlowSpec/
+├── src/
+│   ├── types.ts          # Zod schemas for FlowSpec
+│   ├── parser.ts         # YAML parsing with Zod validation
+│   ├── runner.ts         # Flow execution via agent-browser
+│   ├── reporter.ts       # Result formatting for terminal
+│   └── index.ts          # CLI entry point
+├── test/
+│   ├── fixtures/
+│   │   ├── pages/        # HTML test fixtures
+│   │   └── flows/        # YAML flow fixtures
+│   └── *.test.ts         # Test files
+├── docs/
+│   └── specification.md  # Full framework design
+└── specs/                # User flow specs (immutable)
+```
+
+## Documentation
+
+- [Full Specification](docs/specification.md) - Complete framework design and rationale
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/**
+ * Schema for FlowSpec project configuration
+ */
+export declare const FlowSpecConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    specsDir: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    baseUrl: string;
+    timeout: number;
+    specsDir: string;
+}, {
+    baseUrl?: string | undefined;
+    timeout?: number | undefined;
+    specsDir?: string | undefined;
+}>;
+export type FlowSpecConfig = z.infer<typeof FlowSpecConfigSchema>;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: FlowSpecConfig;
+/**
+ * The standard configuration file name
+ */
+export declare const CONFIG_FILE_NAME = "flowspec.config.yaml";
+/**
+ * Find the configuration file by walking up the directory tree
+ * @param startDir - Directory to start searching from
+ * @returns Path to config file if found, undefined otherwise
+ */
+export declare function findConfigFile(startDir?: string): string | undefined;
+/**
+ * Load and parse a FlowSpec configuration file
+ * @param configPath - Path to the config file
+ * @returns Parsed configuration
+ * @throws Error if file not found or invalid
+ */
+export declare function loadConfigFile(configPath: string): FlowSpecConfig;
+/**
+ * Load configuration from the default location or return defaults
+ * @param startDir - Directory to start searching from
+ * @returns Configuration (from file if found, defaults otherwise)
+ */
+export declare function loadConfig(startDir?: string): FlowSpecConfig;
+/**
+ * Merge CLI options with configuration file values
+ * CLI options take precedence over config file values
+ */
+export declare function mergeConfig(config: FlowSpecConfig, cliOptions: {
+    baseUrl?: string;
+    timeout?: number;
+}): FlowSpecConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAI/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAI5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAsB,GAC/B,MAAM,GAAG,SAAS,CAmBpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAkCjE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,cAAc,CAQ3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,cAAc,CAMhB"}

package/dist/config.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+/**
+ * Schema for FlowSpec project configuration
+ */
+export const FlowSpecConfigSchema = z.object({
+    baseUrl: z.string().url().optional().default("http://localhost:3000"),
+    timeout: z.number().positive().optional().default(10000),
+    specsDir: z.string().optional().default("specs/"),
+});
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    baseUrl: "http://localhost:3000",
+    timeout: 10000,
+    specsDir: "specs/",
+};
+/**
+ * The standard configuration file name
+ */
+export const CONFIG_FILE_NAME = "flowspec.config.yaml";
+/**
+ * Find the configuration file by walking up the directory tree
+ * @param startDir - Directory to start searching from
+ * @returns Path to config file if found, undefined otherwise
+ */
+export function findConfigFile(startDir = process.cwd()) {
+    let currentDir = resolve(startDir);
+    const root = resolve("/");
+    while (currentDir !== root) {
+        const configPath = join(currentDir, CONFIG_FILE_NAME);
+        if (existsSync(configPath)) {
+            return configPath;
+        }
+        currentDir = resolve(currentDir, "..");
+    }
+    // Check root as well
+    const rootConfig = join(root, CONFIG_FILE_NAME);
+    if (existsSync(rootConfig)) {
+        return rootConfig;
+    }
+    return undefined;
+}
+/**
+ * Load and parse a FlowSpec configuration file
+ * @param configPath - Path to the config file
+ * @returns Parsed configuration
+ * @throws Error if file not found or invalid
+ */
+export function loadConfigFile(configPath) {
+    if (!existsSync(configPath)) {
+        throw new Error(`Configuration file not found: ${configPath}`);
+    }
+    const content = readFileSync(configPath, "utf-8");
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch (error) {
+        if (error instanceof yaml.YAMLException) {
+            throw new Error(`Invalid YAML in config file: ${error.reason} at line ${error.mark?.line ?? "unknown"}`);
+        }
+        throw error;
+    }
+    // Handle empty file case
+    if (parsed === undefined || parsed === null) {
+        return DEFAULT_CONFIG;
+    }
+    const result = FlowSpecConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+        throw new Error(`Invalid configuration: ${issues.join("; ")}`);
+    }
+    return result.data;
+}
+/**
+ * Load configuration from the default location or return defaults
+ * @param startDir - Directory to start searching from
+ * @returns Configuration (from file if found, defaults otherwise)
+ */
+export function loadConfig(startDir = process.cwd()) {
+    const configPath = findConfigFile(startDir);
+    if (configPath) {
+        return loadConfigFile(configPath);
+    }
+    return DEFAULT_CONFIG;
+}
+/**
+ * Merge CLI options with configuration file values
+ * CLI options take precedence over config file values
+ */
+export function mergeConfig(config, cliOptions) {
+    return {
+        baseUrl: cliOptions.baseUrl ?? config.baseUrl,
+        timeout: cliOptions.timeout ?? config.timeout,
+        specsDir: config.specsDir,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env bun
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadConfig, mergeConfig } from "./config";
+import { formatInitResult, initProject } from "./init";
+import { parseFlowFile } from "./parser";
+import { formatResult, formatSummary } from "./reporter";
+import { DEFAULT_TIMEOUT, runFlow } from "./runner";
+function showHelp() {
+    console.log(`
+Usage: flowspec <command> [options]
+
+Commands:
+  init              Initialize FlowSpec in the current directory
+  run <path>        Run FlowSpec flow files
+
+Run Command Options:
+  --base-url <url>  Base URL for relative paths (default from config or http://localhost:3000)
+  --timeout <ms>    Assertion retry timeout in milliseconds (default: ${DEFAULT_TIMEOUT})
+  --help            Show help
+
+Init Command:
+  Creates FlowSpec configuration in the current directory:
+    - flowspec.config.yaml (project settings)
+    - specs/example.flow.yaml (sample flow)
+    - .claude/settings.local.json (protects specs from AI edits)
+
+Exit codes:
+  0  All flows passed
+  1  One or more flows failed
+  2  Parse error (invalid YAML/schema)
+`);
+}
+function parseArgs(args) {
+    const options = {
+        showHelp: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            options.showHelp = true;
+        }
+        else if (arg === "--base-url" && i + 1 < args.length) {
+            options.baseUrl = args[++i];
+        }
+        else if (arg === "--timeout" && i + 1 < args.length) {
+            const timeoutValue = Number.parseInt(args[++i], 10);
+            if (!Number.isNaN(timeoutValue)) {
+                options.timeout = timeoutValue;
+            }
+        }
+        else if (!arg.startsWith("-") && !options.path) {
+            options.path = arg;
+        }
+    }
+    return options;
+}
+function discoverFlowFiles(path) {
+    const absolutePath = resolve(path);
+    if (!existsSync(absolutePath)) {
+        return [];
+    }
+    const stats = statSync(absolutePath);
+    if (stats.isFile()) {
+        return [absolutePath];
+    }
+    if (stats.isDirectory()) {
+        const files = readdirSync(absolutePath);
+        return files
+            .filter((file) => file.endsWith(".flow.yaml"))
+            .map((file) => join(absolutePath, file))
+            .sort();
+    }
+    return [];
+}
+function parseFlowFiles(filePaths) {
+    const flows = [];
+    const errors = [];
+    for (const filePath of filePaths) {
+        try {
+            const flow = parseFlowFile(filePath);
+            flows.push({ filePath, flow });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push({ filePath, error: message });
+        }
+    }
+    return { flows, errors };
+}
+async function runFlows(parsedFlows, baseUrl, timeout) {
+    const results = [];
+    for (const { flow } of parsedFlows) {
+        const result = await runFlow(flow, { baseUrl, timeout });
+        console.log(formatResult(result));
+        results.push(result);
+    }
+    return results;
+}
+function handleInitCommand() {
+    const result = initProject(process.cwd());
+    console.log(formatInitResult(result));
+    process.exit(result.success ? 0 : 1);
+}
+async function handleRunCommand(args) {
+    const options = parseArgs(args);
+    if (options.showHelp) {
+        showHelp();
+        process.exit(0);
+    }
+    if (!options.path) {
+        console.error("Error: No path specified");
+        showHelp();
+        process.exit(1);
+    }
+    const absolutePath = resolve(options.path);
+    if (!existsSync(absolutePath)) {
+        console.error(`Error: Path not found: ${options.path}`);
+        process.exit(1);
+    }
+    // Load configuration and merge with CLI options
+    const config = loadConfig();
+    const mergedConfig = mergeConfig(config, {
+        baseUrl: options.baseUrl,
+        timeout: options.timeout,
+    });
+    const flowFiles = discoverFlowFiles(options.path);
+    if (flowFiles.length === 0) {
+        console.log("No flow files found");
+        process.exit(0);
+    }
+    // Parse all flow files first
+    const { flows, errors } = parseFlowFiles(flowFiles);
+    // If there are parse errors, report them and exit with code 2
+    if (errors.length > 0) {
+        for (const { filePath, error } of errors) {
+            console.error(`Error parsing ${filePath}:`);
+            console.error(`  ${error}`);
+        }
+        process.exit(2);
+    }
+    // Run all flows
+    const results = await runFlows(flows, mergedConfig.baseUrl, mergedConfig.timeout);
+    // Print summary
+    console.log();
+    console.log(formatSummary(results));
+    // Exit with appropriate code
+    const allPassed = results.every((r) => r.success);
+    process.exit(allPassed ? 0 : 1);
+}
+async function main() {
+    // Skip first two args: "bun" and script path
+    const args = process.argv.slice(2);
+    // Handle case when no arguments
+    if (args.length === 0) {
+        showHelp();
+        process.exit(0);
+    }
+    // Extract the command
+    const command = args[0];
+    if (command === "init") {
+        handleInitCommand();
+    }
+    else if (command === "run") {
+        await handleRunCommand(args.slice(1));
+    }
+    else if (command === "--help" || command === "-h") {
+        showHelp();
+        process.exit(0);
+    }
+    else {
+        console.error(`Unknown command: ${command}`);
+        showHelp();
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Unexpected error:", error.message);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAUpD,SAAS,QAAQ;IACf,OAAO,CAAC,GAAG,CAAC;;;;;;;;;wEAS0D,eAAe;;;;;;;;;;;;;CAatF,CAAC,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,OAAO,GAAe;QAC1B,QAAQ,EAAE,KAAK;KAChB,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpB,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACrC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC1B,CAAC;aAAM,IAAI,GAAG,KAAK,YAAY,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,GAAG,KAAK,WAAW,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACtD,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,OAAO,CAAC,OAAO,GAAG,YAAY,CAAC;YACjC,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACjD,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAErC,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACnB,OAAO,CAAC,YAAY,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;QACxC,OAAO,KAAK;aACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;aAC7C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;aACvC,IAAI,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAYD,SAAS,cAAc,CAAC,SAAmB;IAIzC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAiB,EAAE,CAAC;IAEhC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,WAAyB,EACzB,OAAe,EACf,OAAgB;IAEhB,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,iBAAiB;IACxB,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAc;IAC5C,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC1C,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,0BAA0B,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE;QACvC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,6BAA6B;IAC7B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAEpD,8DAA8D;IAC9D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;YACzC,OAAO,CAAC,KAAK,CAAC,iBAAiB,QAAQ,GAAG,CAAC,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,gBAAgB;IAChB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAC5B,KAAK,EACL,YAAY,CAAC,OAAO,EACpB,YAAY,CAAC,OAAO,CACrB,CAAC;IAEF,gBAAgB;IAChB,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpC,6BAA6B;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,6CAA6C;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,gCAAgC;IAChC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,sBAAsB;IACtB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,iBAAiB,EAAE,CAAC;IACtB,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QAC7B,MAAM,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;SAAM,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACpD,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QAC7C,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Result of creating a single file during init
+ */
+export interface InitFileResult {
+    path: string;
+    created: boolean;
+    skipped: boolean;
+    error?: string;
+}
+/**
+ * Result of the init command
+ */
+export interface InitResult {
+    files: InitFileResult[];
+    success: boolean;
+}
+/**
+ * Default content for flowspec.config.yaml
+ */
+export declare const DEFAULT_CONFIG_CONTENT = "baseUrl: http://localhost:3000\ntimeout: 10000\nspecsDir: specs/\n";
+/**
+ * Default content for example flow file
+ */
+export declare const DEFAULT_EXAMPLE_FLOW_CONTENT = "name: example-flow\ndescription: Example flow - customize this for your app\nsteps:\n  - visit: /\nexpect:\n  - visible: Welcome\n";
+/**
+ * Default content for Claude settings to protect specs
+ */
+export declare const DEFAULT_CLAUDE_SETTINGS_CONTENT = "{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": { \"tool\": [\"Edit\", \"Write\"], \"path\": \"specs/**/*.flow.yaml\" },\n      \"command\": \"echo '\u274C Flow specs are immutable. Fix the implementation, not the spec.' && exit 1\"\n    }]\n  }\n}\n";
+/**
+ * Initialize FlowSpec in a project directory
+ * Creates configuration files and example flow
+ *
+ * @param projectDir - Directory to initialize (defaults to cwd)
+ * @returns Result with details about each file created
+ */
+export declare function initProject(projectDir?: string): InitResult;
+/**
+ * Format the init result for console output
+ */
+export declare function formatInitResult(result: InitResult): string;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,uEAGlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,uIAMxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,+BAA+B,6QAQ3C,CAAC;AAiGF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,GAAE,MAAsB,GAAG,UAAU,CAgC1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAuC3D"}