@selfcure/cli 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @selfcure/cli
+
+> Command-line entry point for **selfcure** — the preventive testability layer for frontend codebases.
+
+selfcure scores every interactive element in your React / Vue / Angular / HTML source, flags ambiguous locators and missing stable identifiers, and opens a Pull Request with `data-testid` fixes — **before** Cypress, Playwright, Selenium, TestCafe, or WebdriverIO ever run.
+
+## Install
+
+```bash
+npm install -g @selfcure/cli
+```
+
+## Usage
+
+```bash
+selfcure init       # scaffold selfcure.config.mjs in your project
+selfcure crawl      # crawl source files and print component metadata
+selfcure lint       # score testability + flag ambiguous locators + suggest data-testid
+selfcure web        # browser UI with checkbox-driven PR flow (http://localhost:3333/lint)
+selfcure mcp        # start the MCP stdio server for any AI client
+```
+
+Pro flags:
+
+```bash
+selfcure lint --fix          # apply patches to source
+selfcure lint --fix --pr     # apply + branch + push + open a Pull Request
+```
+
+Legacy BYOK pipeline (fallback when not using Playwright Test Agents):
+
+```bash
+selfcure run        # crawl → generate → run → heal → report
+selfcure heal       # re-attempt healing on the last failures
+selfcure report     # re-generate the HTML report
+```
+
+All commands accept `-c <path>` to point at a custom config file.
+
+## Docs
+
+Full documentation: https://github.com/ricardofrancocustodio/selfcure#readme

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import { AIConfig } from '@selfcure/generator';
+export { AIConfig, ProviderId } from '@selfcure/generator';
+
+/** Login via an HTML form (selfcure fills the fields and clicks submit). */
+interface AuthFormConfig {
+    type: 'form';
+    /** Path (relative to baseURL) of the login page, e.g. '/login' */
+    loginURL: string;
+    /** CSS / ARIA selector for the username input, e.g. '[name="username"]' */
+    usernameSelector: string;
+    /** CSS / ARIA selector for the password input, e.g. '[name="password"]' */
+    passwordSelector: string;
+    /** Credential — read from an env var in the config, never hardcode */
+    username: string;
+    /** Credential — read from an env var in the config, never hardcode */
+    password: string;
+    /** Selector for the submit button — default: 'button[type=submit]' */
+    submitSelector?: string;
+    /** URL (or glob) Playwright should wait for after a successful login */
+    waitForURL?: string;
+}
+/** Reuse a Playwright browser storage-state file (pre-authenticated). */
+interface AuthStorageStateConfig {
+    type: 'storageState';
+    /** Path to a storage-state JSON created by `selfcure auth-save` or Playwright */
+    storageState: string;
+}
+/** HTTP Basic Auth (e.g. .htaccess-protected staging environments). */
+interface AuthHttpCredentialsConfig {
+    type: 'httpCredentials';
+    username: string;
+    password: string;
+}
+/** Inject custom HTTP request headers (e.g. a Bearer token or API key). */
+interface AuthHeadersConfig {
+    type: 'headers';
+    /** Record of header name → value; read sensitive values from env vars */
+    extraHTTPHeaders: Record<string, string>;
+}
+type AuthConfig = AuthFormConfig | AuthStorageStateConfig | AuthHttpCredentialsConfig | AuthHeadersConfig;
+interface BrowserConfig {
+    /** Browser engine to use — default: 'chromium' */
+    type?: 'chromium' | 'firefox' | 'webkit';
+    /** Run browser without a visible UI — default: true */
+    headless?: boolean;
+    /** Viewport dimensions — default: { width: 1280, height: 720 } */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Default navigation and action timeout in ms — default: 30000 */
+    timeout?: number;
+    /** Slow-motion delay between actions in ms (useful for debugging) — default: 0 */
+    slowMo?: number;
+}
+interface DiscoveryConfig {
+    /** 'agentic' uses static + optional runtime discovery; 'static' is AST-only. */
+    mode?: 'agentic' | 'static';
+    /** Enable static (AST) discovery — default true */
+    static?: boolean;
+    /** Enable runtime Playwright discovery — default false */
+    runtime?: boolean;
+    /** Maximum routes to visit during runtime discovery — default 50 */
+    maxRoutes?: number;
+    /** Maximum link-follow depth from baseUrl — default 3 */
+    maxDepth?: number;
+    /** Also discover hidden states (modals, wizards) — default true */
+    includeHiddenStates?: boolean;
+    /** Extra route paths to always visit (e.g. auth-protected routes) */
+    routeHints?: string[];
+    /** Glob patterns to ignore during static discovery */
+    ignore?: string[];
+}
+interface TestabilityConfig {
+    /** Prefer role/accessible-name locators over CSS selectors — default true */
+    preferRoleLocators?: boolean;
+    /** Auto-suggest data-testid values for unidentifiable elements — default true */
+    suggestTestIds?: boolean;
+    /** Minimum testability score (0–100) before an element is flagged — default 80 */
+    minimumScore?: number;
+}
+/** Optional linter behaviour — only required for `selfcure lint --pr` */
+interface LintOptions {
+    /**
+     * Base branch the auto-generated PR will target.
+     * When omitted, selfcure asks `gh` / `glab` for the repo's default branch.
+     */
+    prBaseBranch?: string;
+    /**
+     * Force a specific git host provider. When `'auto'` (default), selfcure
+     * inspects `git remote get-url origin` and picks GitHub or GitLab based on
+     * the hostname. Set explicitly for self-hosted GitLab with custom domain.
+     */
+    gitProvider?: 'github' | 'gitlab' | 'auto';
+}
+/** Full selfcure configuration — used in selfcure.config.mjs */
+interface SelfcureConfig {
+    /** Project root — alternative to rootDir for the new config format. */
+    projectRoot?: string;
+    /** App base URL — alternative to baseURL for the new config format. */
+    baseUrl?: string;
+    /** Discovery configuration block. */
+    discovery?: DiscoveryConfig;
+    /** Testability scoring configuration. */
+    testability?: TestabilityConfig;
+    rootDir: string;
+    include: string[];
+    exclude: string[];
+    /** Optional framework hint — skips auto-detection — default: 'auto' */
+    framework?: 'react' | 'vue' | 'angular' | 'auto';
+    auth?: AuthConfig;
+    browser?: BrowserConfig;
+    ai: AIConfig;
+    testsDir: string;
+    maxInputTokens?: number;
+    playwrightConfig: string;
+    baseURL: string;
+    maxHealAttempts?: number;
+    reportDir: string;
+    reportTitle?: string;
+    /** Optional Pro flag — enables `selfcure lint --fix` and `--pr` without the env var. */
+    pro?: boolean;
+    /** Optional linter settings (currently just PR base branch). */
+    lint?: LintOptions;
+}
+
+export type { AuthConfig, AuthFormConfig, AuthHeadersConfig, AuthHttpCredentialsConfig, AuthStorageStateConfig, BrowserConfig, DiscoveryConfig, LintOptions, SelfcureConfig, TestabilityConfig };