@overshift/sfs 1.1.0

package/README.md

@@ -0,0 +1,215 @@
+# SFS (StoryFlowSteps)
+
+An agent-oriented browser automation protocol for validating user story flows. SFS provides a high-level, natural language syntax for describing browser automation tests, designed to be executed by an AI agent using Playwright MCP.
+
+## Key Features
+
+- **Agent-Oriented Design** - Built for AI agents to understand context and make intelligent decisions
+- **Flexible Selectors** - Supports explicit selectors with fuzzy fallback matching
+- **User Story Traceability** - Each SFS file maps to a user story (US-XXX-001) for coverage tracking
+- **Natural Language Syntax** - Commands read like human actions
+- **Multi-Environment Config** - Environment layering for CI/staging/local
+- **Persona Management** - Define user roles with environment-specific credentials
+- **Lifecycle Hooks** - Complete session orchestration (before/after session, before/after each)
+
+## Installation
+
+```bash
+npm install @sfs/cli
+```
+
+Requires Node.js >= 18.0.0
+
+## Quick Start
+
+Initialize SFS in your project:
+
+```bash
+npx sfs init
+```
+
+This creates:
+- `sfs.config.md` - Base configuration
+- `example.sfs` - Example login flow
+
+## CLI Commands
+
+### Run SFS Flows
+
+```bash
+npx sfs run                           # Run all .sfs files
+npx sfs run stories/US-SHOP-01a.sfs   # Run specific file
+npx sfs run "stories/**/*.sfs"        # Run with glob pattern
+npx sfs run --env ci                  # Use CI-specific config
+npx sfs run --headed                  # Show browser GUI
+npx sfs run --verbose                 # Verbose output
+```
+
+### Validate Syntax
+
+```bash
+npx sfs validate stories/US-SHOP-01a.sfs
+npx sfs validate "stories/**/*.sfs"
+```
+
+### Coverage Report
+
+```bash
+npx sfs coverage                      # Table format
+npx sfs coverage --format json        # JSON output
+npx sfs coverage --format summary     # Summary only
+```
+
+## SFS File Syntax
+
+```sfs
+STORY       US-LOGIN-01a
+ENTRYPOINT  http://localhost:3000
+LOCALE      en-US
+
+HINT        Standard login form with email and password fields
+ON FAILURE  capture screenshot and describe visible state
+
+BEFORE THIS
+  ASSERT port 3000 is open
+
+--- page-load ---
+OBSERVE login form is visible
+
+--- enter-credentials ---
+TYPE "testuser@example.com" INTO email field >> selector:testid:email-input
+TYPE "password123" INTO password field >> selector:testid:password-input
+CAPTURE before-submit
+
+--- submit-login ---
+CLICK login button >> selector:testid:login-btn
+WAIT FOR url contains /dashboard
+
+--- verify-dashboard ---
+OBSERVE dashboard content is visible
+OBSERVE logout button is visible
+
+DONE WHEN user is logged in and dashboard is visible
+```
+
+### Command Reference
+
+| Category | Commands |
+|----------|----------|
+| **Interactions** | `CLICK`, `TYPE`, `SELECT`, `DOUBLE CLICK`, `HOVER`, `SCROLL TO`, `UPLOAD`, `PRESS`, `CLEAR` |
+| **Navigation** | `NAVIGATE TO`, `WAIT FOR` |
+| **Observations** | `OBSERVE`, `CAPTURE`, `READ ... INTO $var` |
+| **Tabs** | `TAB EXPECT NEW`, `TAB SWITCH TO`, `TAB CLOSE`, `TAB COUNT IS` |
+| **Dialogs** | `ACCEPT DIALOG`, `DISMISS DIALOG` |
+| **Assertions** | `ASSERT port`, `ASSERT env`, `ASSERT file` |
+
+### Selectors
+
+Commands support explicit selectors with fuzzy fallback:
+
+```sfs
+CLICK login button                                  # Fuzzy (agent resolves)
+CLICK login button >> selector:testid:login-btn    # Explicit with fallback
+CLICK login button >> selector:css:.btn-login      # CSS selector
+CLICK login button >> selector:xpath://button[1]   # XPath selector
+CLICK login button >> selector:text:Log In         # Text selector
+```
+
+## Configuration
+
+### sfs.config.md
+
+```markdown
+# SFS Configuration
+
+## Settings
+
+| Setting | Value |
+|---------|-------|
+| ENTRYPOINT | http://localhost:3000 |
+| LOCALE | en-US |
+| TIMEOUT | 30s |
+| ON FAILURE | capture screenshot |
+| PRESERVE STATE ON FAILURE | true |
+
+## Personas
+
+| Persona | Username | Password | Description |
+|---------|----------|----------|-------------|
+| user | testuser@example.com | {{TEST_USER_PASSWORD}} | Standard user |
+| admin | admin@example.com | {{ADMIN_PASSWORD}} | Administrator |
+| guest | | | Unauthenticated |
+```
+
+### Environment Layering
+
+Configuration files are merged in order:
+
+```
+sfs.config.md           → Base configuration
+sfs.config.{env}.md     → Environment-specific (ci, staging)
+sfs.config.local.md     → Local overrides (gitignored)
+```
+
+## Project Structure
+
+```
+/stories/
+  sfs.config.md              # Base config
+  sfs.config.ci.md           # CI overrides
+  sfs.config.local.md        # Local overrides (gitignored)
+
+  US-SHOP-01/
+    US-SHOP-01a.sfs          # Primary flow
+    US-SHOP-01a.edge.sfs     # Edge cases
+
+  /runs/                     # Test output (gitignored)
+    2024-02-04T14-30-00/
+      run.report.md
+```
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Run in development
+npm run build        # Build
+npm test             # Run tests
+npm run lint         # Lint
+npm run format       # Format
+```
+
+### Pre-commit Checks
+
+This project uses a Definition of Done (DoD) quality gate that runs before each commit. The checks include:
+
+**Critical (must pass):** build, test, lint, format
+**Warnings (informational):** longfiles, knip, seccheck, audit
+
+Run checks manually with npm scripts:
+
+```bash
+npm run dod          # Run all checks (default)
+npm run dod:all      # Run all checks (explicit)
+npm run dod:core     # Run only critical checks (faster)
+npm run dod:skip     # Skip all checks
+```
+
+Commit with check level control:
+
+```bash
+npm run commit:check -- -m "message"           # All checks (default)
+npm run commit:check:all -- -m "message"       # All checks (explicit)
+npm run commit:check:core -- -m "message"      # Core checks only
+npm run commit:check:skip -- -m "message"      # Skip DoD checks
+git commit --no-verify -m "message"            # Skip all hooks
+```
+
+## Documentation
+
+- [SFS Language Specification](SFS-SPEC.md)
+- [Configuration Specification](SFS-CONFIG-SPEC.md)
+
+## License
+
+MIT

package/dist/cli/coverage-output.d.ts

@@ -0,0 +1,3 @@
+import type { CoverageResult } from "./coverage-types.js";
+export declare function outputResults(result: CoverageResult, format: string): void;
+//# sourceMappingURL=coverage-output.d.ts.map

package/dist/cli/coverage-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-output.d.ts","sourceRoot":"","sources":["../../src/cli/coverage-output.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAe1E"}

package/dist/cli/coverage-output.js

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+export function outputResults(result, format) {
+    switch (format) {
+        case "json":
+            console.log(JSON.stringify(result, null, 2));
+            break;
+        case "summary":
+            outputSummary(result);
+            break;
+        case "table":
+        default:
+            outputTable(result);
+            break;
+    }
+}
+function outputSummary(result) {
+    const { stories, flows, covered, uncovered, coverage } = result;
+    console.log(`User Stories: ${stories.length}`);
+    console.log(`SFS Flows:    ${flows.length}`);
+    console.log(`Covered:      ${covered.length}`);
+    console.log(`Uncovered:    ${uncovered.length}`);
+    console.log();
+    const coverageColor = coverage >= 80 ? chalk.green : coverage >= 50 ? chalk.yellow : chalk.red;
+    console.log(`Coverage:     ${coverageColor(`${coverage.toFixed(1)}%`)}`);
+}
+function outputTable(result) {
+    const { stories, flows, covered, uncovered, coverage } = result;
+    console.log(chalk.bold("Summary"));
+    console.log(`  User Stories: ${stories.length}`);
+    console.log(`  SFS Flows:    ${flows.length}`);
+    console.log();
+    if (stories.length > 0) {
+        console.log(chalk.bold("Coverage by Story"));
+        console.log();
+        console.log("| Story ID | Title | Source | Status | Flows |");
+        console.log("|----------|-------|--------|--------|-------|");
+        for (const story of stories) {
+            const storyFlows = flows.filter((f) => f.storyId === story.id);
+            const status = storyFlows.length > 0
+                ? chalk.green("✓ Covered")
+                : chalk.red("✗ Missing");
+            const flowCount = storyFlows.length > 0 ? storyFlows.length.toString() : "0";
+            const title = story.title ? truncate(story.title, 30) : "-";
+            const source = story.source === "single" ? "file" : "multi";
+            console.log(`| ${story.id} | ${title} | ${source} | ${status} | ${flowCount} |`);
+        }
+        console.log();
+    }
+    if (uncovered.length > 0) {
+        console.log(chalk.bold.red("Uncovered Stories"));
+        for (const id of uncovered) {
+            const story = stories.find((s) => s.id === id);
+            console.log(chalk.red(`  ✗ ${id}${story?.title ? ` - ${story.title}` : ""}`));
+        }
+        console.log();
+    }
+    const orphanFlows = flows.filter((f) => !stories.some((s) => s.id === f.storyId));
+    if (orphanFlows.length > 0) {
+        console.log(chalk.bold.yellow("Flows without matching user stories"));
+        for (const flow of orphanFlows) {
+            console.log(chalk.yellow(`  ⚠ ${flow.path} (STORY ${flow.storyId})`));
+        }
+        console.log();
+    }
+    const coverageColor = coverage >= 80 ? chalk.green : coverage >= 50 ? chalk.yellow : chalk.red;
+    console.log(chalk.bold("Overall Coverage"));
+    console.log(`  ${coverageColor(`${coverage.toFixed(1)}%`)} (${covered.length}/${stories.length} stories)`);
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + "...";
+}
+//# sourceMappingURL=coverage-output.js.map

package/dist/cli/coverage-output.js.map

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

package/dist/cli/coverage-types.d.ts

@@ -0,0 +1,24 @@
+export interface CoverageOptions {
+    stories?: string;
+    sfs?: string;
+    format?: "table" | "json" | "summary";
+}
+export interface UserStory {
+    id: string;
+    title?: string;
+    path: string;
+    source: "single" | "multi";
+}
+export interface SfsFlow {
+    storyId: string;
+    path: string;
+    name: string;
+}
+export interface CoverageResult {
+    stories: UserStory[];
+    flows: SfsFlow[];
+    covered: string[];
+    uncovered: string[];
+    coverage: number;
+}
+//# sourceMappingURL=coverage-types.d.ts.map

package/dist/cli/coverage-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-types.d.ts","sourceRoot":"","sources":["../../src/cli/coverage-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/cli/coverage-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=coverage-types.js.map

package/dist/cli/coverage-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-types.js","sourceRoot":"","sources":["../../src/cli/coverage-types.ts"],"names":[],"mappings":""}

package/dist/cli/coverage.d.ts

@@ -0,0 +1,3 @@
+import type { CoverageOptions } from "./coverage-types.js";
+export declare function coverageCommand(options: CoverageOptions): Promise<void>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/cli/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/cli/coverage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,qBAAqB,CAAC;AAU7B,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB7E"}

package/dist/cli/coverage.js

@@ -0,0 +1,69 @@
+import { basename } from "path";
+import { glob } from "glob";
+import chalk from "chalk";
+import { extractStoryIdFromFilename, extractStoryTitle, extractStoriesFromMultiFile, deduplicateStories, extractSfsStoryId, } from "./story-extractor.js";
+import { outputResults } from "./coverage-output.js";
+export async function coverageCommand(options) {
+    const storiesDir = options.stories ?? "stories";
+    const sfsPattern = options.sfs ?? "**/*.sfs";
+    const format = options.format ?? "table";
+    // Only show header for non-JSON formats
+    if (format !== "json") {
+        console.log(chalk.blue("SFS - User Story Coverage Report"));
+        console.log();
+    }
+    try {
+        const result = await calculateCoverage(storiesDir, sfsPattern);
+        outputResults(result, format);
+    }
+    catch (error) {
+        console.log(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+        process.exit(1);
+    }
+}
+async function calculateCoverage(storiesDir, sfsPattern) {
+    const singleStoryFiles = await glob(`${storiesDir}/**/US-*.md`, {
+        ignore: ["**/node_modules/**", "**/*.sfs.md"],
+    });
+    const multiStoryFiles = await glob([
+        `${storiesDir}/**/*user-stories*.md`,
+        `${storiesDir}/**/*user.stories*.md`,
+        `${storiesDir}/**/*user_stories*.md`,
+    ], {
+        ignore: ["**/node_modules/**"],
+    });
+    const sfsFiles = await glob(sfsPattern, {
+        ignore: ["**/node_modules/**"],
+    });
+    const stories = [];
+    for (const file of singleStoryFiles) {
+        const id = extractStoryIdFromFilename(file);
+        if (id) {
+            const title = await extractStoryTitle(file);
+            stories.push({ id, title, path: file, source: "single" });
+        }
+    }
+    for (const file of multiStoryFiles) {
+        const multiStories = await extractStoriesFromMultiFile(file);
+        stories.push(...multiStories);
+    }
+    const uniqueStories = deduplicateStories(stories);
+    const flows = [];
+    for (const file of sfsFiles) {
+        const storyId = await extractSfsStoryId(file);
+        if (storyId) {
+            flows.push({
+                storyId,
+                path: file,
+                name: basename(file, ".sfs"),
+            });
+        }
+    }
+    const storyIds = new Set(uniqueStories.map((s) => s.id));
+    const coveredIds = new Set(flows.map((f) => f.storyId));
+    const covered = [...storyIds].filter((id) => coveredIds.has(id));
+    const uncovered = [...storyIds].filter((id) => !coveredIds.has(id));
+    const coverage = storyIds.size > 0 ? (covered.length / storyIds.size) * 100 : 100;
+    return { stories: uniqueStories, flows, covered, uncovered, coverage };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/cli/coverage.js.map

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

package/dist/cli/init-templates.d.ts

@@ -0,0 +1,5 @@
+export declare const CONFIG_TEMPLATE = "# SFS Configuration\n\n## Settings\n\n| Setting | Value |\n|---------|-------|\n| ENTRYPOINT | http://localhost:3000 |\n| LOCALE | en-US |\n| TIMEOUT | 30000 |\n| ON FAILURE | capture screenshot |\n| PRESERVE STATE ON FAILURE | true |\n\n## Hints\n\n- Add context about your application here\n- Describe the UI layout, navigation patterns\n- Note any authentication requirements\n- Mention relevant test data or fixtures\n\n## Personas\n\n| Persona | Username | Password | Description |\n|---------|----------|----------|-------------|\n| user | testuser@example.com | {{TEST_USER_PASSWORD}} | Standard user account |\n| admin | admin@example.com | {{ADMIN_PASSWORD}} | Administrator with full access |\n| guest | | | Unauthenticated visitor |\n\n## Before Session\n\n```sfs\n# Validate environment\nASSERT file .env exists\nASSERT env-check\n\n# Start services (uncomment as needed)\n# SHELL docker compose up -d\n# WAIT FOR http://localhost:3000 to respond\n```\n\n## After Session\n\n```sfs\n# Collect logs\nSHELL mkdir -p {{RUN_DIR}}\n# SHELL docker compose logs > {{RUN_DIR}}/docker.log\n```\n\n## Before Each\n\n```sfs\n# Reset browser state\nCLEAR cookies\nCLEAR local storage\n```\n\n## After Each\n\n```sfs\n# Log completion\nSHELL echo \"$(date): Completed {{SFS_NAME}}\" >> {{RUN_DIR}}/execution.log\n```\n";
+export declare const EXAMPLE_SFS = "# example.sfs\n# Example: Basic page load verification\n\nSTORY       EXAMPLE-001\nENTRYPOINT  http://localhost:3000\nLOCALE      en-US\n\nHINT        Replace with your application context\nHINT        Describe the page layout and key elements\n\nON FAILURE  capture screenshot and describe visible state\n\nBEFORE THIS\n  ASSERT port 3000 is open\n\n--- page-load ---\nAS user\nOBSERVE page has loaded\nOBSERVE main content is visible\n\n--- verify-elements ---\n# Add your verification steps here\nOBSERVE expected elements are present\n\nDONE WHEN page loaded successfully with expected content\n";
+export declare const GITIGNORE_ADDITIONS = "\n# SFS local config (may contain sensitive paths/settings)\nsfs.config.local.md\n\n# SFS run outputs\n/runs/\n/stories/runs/\n*.report.md\n\n# Failure screenshots\n/failures/\n";
+export declare const SFS_SKILLS: string[];
+//# sourceMappingURL=init-templates.d.ts.map

package/dist/cli/init-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/cli/init-templates.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,0yCA6D3B,CAAC;AAEF,eAAO,MAAM,WAAW,4lBAyBvB,CAAC;AAEF,eAAO,MAAM,mBAAmB,sLAW/B,CAAC;AAEF,eAAO,MAAM,UAAU,UAMtB,CAAC"}

package/dist/cli/init-templates.js

@@ -0,0 +1,108 @@
+export const CONFIG_TEMPLATE = `# SFS Configuration
+
+## Settings
+
+| Setting | Value |
+|---------|-------|
+| ENTRYPOINT | http://localhost:3000 |
+| LOCALE | en-US |
+| TIMEOUT | 30000 |
+| ON FAILURE | capture screenshot |
+| PRESERVE STATE ON FAILURE | true |
+
+## Hints
+
+- Add context about your application here
+- Describe the UI layout, navigation patterns
+- Note any authentication requirements
+- Mention relevant test data or fixtures
+
+## Personas
+
+| Persona | Username | Password | Description |
+|---------|----------|----------|-------------|
+| user | testuser@example.com | {{TEST_USER_PASSWORD}} | Standard user account |
+| admin | admin@example.com | {{ADMIN_PASSWORD}} | Administrator with full access |
+| guest | | | Unauthenticated visitor |
+
+## Before Session
+
+\`\`\`sfs
+# Validate environment
+ASSERT file .env exists
+ASSERT env-check
+
+# Start services (uncomment as needed)
+# SHELL docker compose up -d
+# WAIT FOR http://localhost:3000 to respond
+\`\`\`
+
+## After Session
+
+\`\`\`sfs
+# Collect logs
+SHELL mkdir -p {{RUN_DIR}}
+# SHELL docker compose logs > {{RUN_DIR}}/docker.log
+\`\`\`
+
+## Before Each
+
+\`\`\`sfs
+# Reset browser state
+CLEAR cookies
+CLEAR local storage
+\`\`\`
+
+## After Each
+
+\`\`\`sfs
+# Log completion
+SHELL echo "$(date): Completed {{SFS_NAME}}" >> {{RUN_DIR}}/execution.log
+\`\`\`
+`;
+export const EXAMPLE_SFS = `# example.sfs
+# Example: Basic page load verification
+
+STORY       EXAMPLE-001
+ENTRYPOINT  http://localhost:3000
+LOCALE      en-US
+
+HINT        Replace with your application context
+HINT        Describe the page layout and key elements
+
+ON FAILURE  capture screenshot and describe visible state
+
+BEFORE THIS
+  ASSERT port 3000 is open
+
+--- page-load ---
+AS user
+OBSERVE page has loaded
+OBSERVE main content is visible
+
+--- verify-elements ---
+# Add your verification steps here
+OBSERVE expected elements are present
+
+DONE WHEN page loaded successfully with expected content
+`;
+export const GITIGNORE_ADDITIONS = `
+# SFS local config (may contain sensitive paths/settings)
+sfs.config.local.md
+
+# SFS run outputs
+/runs/
+/stories/runs/
+*.report.md
+
+# Failure screenshots
+/failures/
+`;
+export const SFS_SKILLS = [
+    "from-user-story-to-sfs.md",
+    "write-sfs-session-reports.md",
+    "read-sfs-session-reports.md",
+    "validate-sfs-syntax.md",
+    "run-sfs-session.md",
+];
+//# sourceMappingURL=init-templates.js.map

package/dist/cli/init-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-templates.js","sourceRoot":"","sources":["../../src/cli/init-templates.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D9B,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyB1B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;CAWlC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,2BAA2B;IAC3B,8BAA8B;IAC9B,6BAA6B;IAC7B,wBAAwB;IACxB,oBAAoB;CACrB,CAAC"}

package/dist/cli/init.d.ts

@@ -0,0 +1,7 @@
+interface InitOptions {
+    force?: boolean;
+    skillsDir?: string;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAkBA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqErE"}