@epsilon-asi/actors 0.0.1 → 0.0.3

package/.ai/generators/site-actor.ts

@@ -1,125 +0,0 @@
-export default {
-  id: 'site-actor',
-  description: 'Create or update a website-specific actor, selector map, types, barrel exports, and focused unit tests.',
-  instructions: `
-Generate a site actor that follows the existing framework conventions.
-
-Rules:
-- Use defineActor from src/core/defineActor.ts.
-- Keep selectors in src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts.
-- Keep task input/output types in src/sites/{{siteKebab}}/{{siteKebab}}.types.ts.
-- Export the site through src/sites/{{siteKebab}}/index.ts and src/sites/index.ts.
-- Prefer context.nav, context.forms, context.cursor, context.extract, and context.pagination over raw Puppeteer APIs.
-- Use context.page.raw() only when the abstraction does not support the needed operation.
-- Never hard-code credentials or secrets.
-- If login is required, use defineLoginFlow and the typed LoginFlowDefinition shape.
-- If the task scrapes data, use Extractor/Pagination helpers before inventing new extraction logic.
-- Add or update focused unit tests when behavior is non-trivial.
-- Keep actor tasks small and named by what they do, for example scrapeDashboard or scrapeListings.
-- Update barrel exports when adding a new site.
-
-DO NOT INVENT selectors that were not supplied by the user unless the instructions explicitly say to make placeholders.
-DO NOT add CAPTCHA bypass, anti-bot evasion, or credential harvesting behavior.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'actor',
-        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
-        description: 'The site actor with auth definition, hooks, and task implementations.'
-      },
-      {
-        key: 'selectors',
-        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
-        description: 'Site-specific CSS selector constants grouped by page/flow.'
-      },
-      {
-        key: 'types',
-        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
-        description: 'Task input/output types for this site.'
-      },
-      {
-        key: 'site-index',
-        pathTemplate: 'src/sites/{{siteKebab}}/index.ts',
-        description: 'Per-site barrel exports.'
-      },
-      {
-        key: 'sites-index',
-        pathTemplate: 'src/sites/index.ts',
-        description: 'Global sites barrel export; add this site export if needed.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/sites/{{siteKebab}}.actor.test.ts',
-        description: 'Focused unit tests for task behavior or auth config when useful.'
-      }
-    ],
-    maxFiles: 6
-  },
-  parameters: {
-    site: {
-      description: 'The website/site name, for example Apple, Upwork, Example Marketplace, or Acme Dashboard.',
-      required: true
-    },
-    actorId: {
-      description: 'Actor id used at runtime. Defaults to the kebab-case site name when omitted.',
-      required: false
-    },
-    baseUrl: {
-      description: 'The site base URL, for example https://example.com.',
-      required: false
-    },
-    instructions: {
-      description: 'Specific login, task, selector, or scraping behavior to implement.',
-      required: false
-    }
-  },
-  examples: [
-    'src/sites/example/example.actor.ts',
-    'src/sites/example/example.selectors.ts',
-    'src/sites/example/example.types.ts',
-    'src/sites/example/index.ts',
-    'src/sites/index.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'src/core/defineActor.ts', description: 'Helper used to define actors.' },
-    { kind: 'path', path: 'src/core/Actor.ts', description: 'Actor/task/hook contracts.' },
-    { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Task context available to actor implementations.' },
-    { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Canonical example actor.' },
-    { kind: 'path', path: 'src/sites/example/example.selectors.ts', description: 'Canonical selector map.' },
-    { kind: 'path', path: 'src/sites/example/example.types.ts', description: 'Canonical site task types.' },
-    { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Auth/login configuration types.' },
-    { kind: 'path', path: 'src/extraction/Extractor.ts', description: 'Reusable extraction helper.' },
-    { kind: 'path', path: 'src/extraction/Pagination.ts', description: 'Reusable pagination helper.' },
-    { kind: 'path', path: 'src/sites/index.ts', description: 'Global site export pattern.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['login', 'auth', 'sign in', 'signin', 'multi-step', 'username', 'password'],
-      context: [
-        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Login execution behavior.' },
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Login config/test examples.' }
-      ]
-    },
-    {
-      keywords: ['scrape', 'extract', 'pagination', 'next page', 'table', 'href', 'jsonld'],
-      context: [
-        { kind: 'path', path: 'tests/unit/extraction/Extractor.test.ts', description: 'Extractor behavior examples.' },
-        { kind: 'path', path: 'tests/unit/extraction/Pagination.test.ts', description: 'Pagination behavior examples.' }
-      ]
-    },
-    {
-      keywords: ['form', 'type', 'click', 'navigation', 'wait', 'selector'],
-      context: [
-        { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Form filler helper.' },
-        { kind: 'path', path: 'src/interaction/Navigation.ts', description: 'Navigation helper.' },
-        { kind: 'path', path: 'src/interaction/PageAdapter.ts', description: 'Page wrapper methods available to actors.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/site-login-flow.ts

@@ -1,117 +0,0 @@
-export default {
-  id: 'site-login-flow',
-  description: 'Add or revise a site actor login flow, including simple, staged, and multi-step username/password flows.',
-  instructions: `
-Update the site auth configuration using defineLoginFlow.
-
-Rules:
-- Keep login configuration inside the site actor unless the repo already split auth into a separate file.
-- Use selectors.loggedInSignal for post-login verification.
-- Use selectors.errorMessage when the site exposes a visible error message.
-- For one-page login forms, selectors.username/password/submit are acceptable.
-- For staged forms, use the ordered steps array.
-- For username-first/password-second forms, use fill(username), click(continue with waitForSelector), fill(password), click(submit).
-- Preserve clearFieldBeforeTyping defaults unless the user explicitly requests otherwise.
-- Preserve human-like typing behavior through behavior.typing or per-fill-step typing overrides.
-- Use credential: 'username' and credential: 'password' for credential fields.
-- Use value or a value resolver only for non-credential fields, such as tenant/workspace/account id.
-- Add waitForSelector after intermediate click steps whenever the next field appears asynchronously.
-- Mark the final click step with submit: true so beforeSubmit/afterSubmit hooks apply.
-- Add or update tests for the login shape and any custom hook/step behavior.
-
-DO NOT hard-code real usernames, passwords, tokens, cookies, or private profile paths.
-DO NOT implement CAPTCHA bypass or anti-bot circumvention.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'actor',
-        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
-        description: 'The site actor whose auth definition should be added or updated.'
-      },
-      {
-        key: 'selectors',
-        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
-        description: 'Selectors for login fields, buttons, errors, and logged-in signals.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/sites/{{siteKebab}}.login.test.ts',
-        description: 'Focused tests for the generated site login config or custom login behavior.'
-      }
-    ],
-    maxFiles: 3
-  },
-  parameters: {
-    site: {
-      description: 'The site whose login should be implemented or edited.',
-      required: true
-    },
-    loginUrl: {
-      description: 'Login URL or path for the site.',
-      required: false
-    },
-    flowType: {
-      description: 'Login flow style, for example simple, multi-step, username-first, tenant-first, or custom.',
-      required: false
-    },
-    instructions: {
-      description: 'Selectors, step order, waits, hooks, and edge cases for this login form.',
-      required: false
-    }
-  },
-  examples: [
-    'src/sites/example/example.actor.ts',
-    'src/sites/example/example.selectors.ts',
-    'tests/unit/auth/LoginFlow.test.ts'
-  ],
-  context: [
-    {
-      kind: 'path',
-      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
-      description: 'Existing site actor to update when present.',
-      required: false
-    },
-    {
-      kind: 'path',
-      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
-      description: 'Existing site selectors to update when present.',
-      required: false
-    },
-    { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'LoginFlowDefinition and LoginStep types.' },
-    { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'How login steps execute.' },
-    { kind: 'path', path: 'src/auth/CredentialsProvider.ts', description: 'Credential references and providers.' },
-    { kind: 'path', path: 'src/auth/AuthStateDetector.ts', description: 'Logged-in detection behavior.' },
-    { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Form filling behavior used by fill steps.' },
-    { kind: 'path', path: 'src/interaction/FieldClearer.ts', description: 'clearFieldBeforeTyping implementation.' },
-    { kind: 'path', path: 'src/interaction/HumanTyping.ts', description: 'Human-like typing options used by login fill steps.' },
-    { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Canonical login flow tests.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['multi-step', 'multistep', 'apple', 'upwork', 'continue', 'next', 'waitForSelector'],
-      context: [
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Contains multi-step login expectations.' },
-        { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Step-specific wait and hook options.' }
-      ]
-    },
-    {
-      keywords: ['clearFieldBeforeTyping', 'clear', 'pre-filled', 'select-delete'],
-      context: [
-        { kind: 'path', path: 'tests/unit/interaction/FieldClearer.test.ts', description: 'Field clearing behavior tests.' }
-      ]
-    },
-    {
-      keywords: ['typing', 'wpm', 'human-like', 'jitter'],
-      context: [
-        { kind: 'path', path: 'tests/unit/interaction/HumanTyping.test.ts', description: 'Typing timing tests.' },
-        { kind: 'path', path: 'tests/unit/interaction/NativePuppeteerInteractor.test.ts', description: 'Typing integration tests.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/unit-test.ts

@@ -1,109 +0,0 @@
-export default {
-  id: 'unit-test',
-  description: 'Generate or update Vitest unit tests for framework modules, site actors, and test fixtures.',
-  instructions: `
-Write deterministic Vitest unit tests that match the repo style.
-
-Rules:
-- Use Vitest APIs and existing test structure under tests/unit.
-- Prefer FakePage, FakeCursor, FakeCredentialsProvider, and makeContext over live browser tests.
-- Do not launch Chrome in unit tests.
-- Test observable behavior, calls, returned data, and typed errors.
-- Cover success and failure paths for core/auth/browser changes.
-- Keep fixtures minimal and reusable.
-- If a source change requires fixture updates, update the fixture in the same result.
-- Match strict TypeScript settings; avoid any unless the existing test pattern requires it.
-
-DO NOT write brittle tests that depend on real websites, external network, or a user profile path.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'test',
-        pathTemplate: 'tests/unit/{{areaKebab}}/{{subjectPascal}}.test.ts',
-        description: 'Unit test file for the requested area and subject.'
-      },
-      {
-        key: 'fake-page',
-        pathTemplate: 'tests/fixtures/FakePage.ts',
-        description: 'Update only when page behavior required by the tests is missing.'
-      },
-      {
-        key: 'fake-cursor',
-        pathTemplate: 'tests/fixtures/FakeCursor.ts',
-        description: 'Update only when cursor behavior required by the tests is missing.'
-      },
-      {
-        key: 'fake-credentials',
-        pathTemplate: 'tests/fixtures/FakeCredentialsProvider.ts',
-        description: 'Update only when credential behavior required by the tests is missing.'
-      },
-      {
-        key: 'make-context',
-        pathTemplate: 'tests/fixtures/makeContext.ts',
-        description: 'Update only when ActorContext construction changes.'
-      }
-    ],
-    maxFiles: 5
-  },
-  parameters: {
-    area: {
-      description: 'Test area folder, for example auth, browser, core, extraction, interaction, logging, sites, or cli.',
-      required: true
-    },
-    subject: {
-      description: 'Class/function/component under test, for example LoginFlow, BrowserFactory, or HumanTyping.',
-      required: true
-    },
-    instructions: {
-      description: 'Specific behaviors, branches, errors, and edge cases that must be tested.',
-      required: false
-    }
-  },
-  examples: [
-    'tests/unit/auth/LoginFlow.test.ts',
-    'tests/unit/browser/BrowserFactory.test.ts',
-    'tests/unit/core/ActorRunner.test.ts',
-    'tests/unit/interaction/HumanTyping.test.ts',
-    'tests/fixtures/FakePage.ts',
-    'tests/fixtures/FakeCursor.ts',
-    'tests/fixtures/makeContext.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'vitest.config.ts', description: 'Vitest configuration.' },
-    { kind: 'pattern', pattern: 'tests/unit/{{areaKebab}}/*.test.ts', description: 'Existing tests in the target area.', limit: 8 },
-    { kind: 'pattern', pattern: 'tests/unit/**/*.test.ts', description: 'Representative test style from the rest of the repo.', limit: 5 },
-    { kind: 'path', path: 'tests/fixtures/FakePage.ts', description: 'Main fake page fixture.' },
-    { kind: 'path', path: 'tests/fixtures/FakeCursor.ts', description: 'Fake cursor fixture.' },
-    { kind: 'path', path: 'tests/fixtures/FakeCredentialsProvider.ts', description: 'Fake credentials fixture.' },
-    { kind: 'path', path: 'tests/fixtures/makeContext.ts', description: 'ActorContext test fixture.' },
-    { kind: 'path', path: 'src/{{areaKebab}}/{{subjectPascal}}.ts', description: 'Conventional source module under test, when present.', required: false }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['login', 'auth', 'credentials', 'multi-step'],
-      context: [
-        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Auth source likely under test.' },
-        { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Auth types likely under test.' }
-      ]
-    },
-    {
-      keywords: ['browser', 'chrome', 'profile', 'remote debugging'],
-      context: [
-        { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'Browser source likely under test.' },
-        { kind: 'path', path: 'src/browser/PuppeteerLike.ts', description: 'Fakeable browser/page interfaces.' }
-      ]
-    },
-    {
-      keywords: ['interaction', 'typing', 'cursor', 'forms'],
-      context: [
-        { kind: 'pattern', pattern: 'src/interaction/*.ts', description: 'Interaction source files.', limit: 10 }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/workflows/_template.ts

@@ -1,20 +0,0 @@
-export const workflow = {
-  "description": "Describe what this workflow orchestrates.",
-  "parameters": {
-    "instructions": {
-      "description": "User-provided instructions passed to the workflow steps.",
-      "required": true
-    }
-  },
-  "steps": [
-    {
-      "generationId": "abstract",
-      "description": "Run one generation step with interpolated instructions.",
-      "params": {
-        "instructions": "{{instructions}}"
-      }
-    }
-  ]
-}
-
-export default workflow;

package/.ai/workflows/starter.ts

@@ -1,20 +0,0 @@
-const starter = {
-  "description": "A minimal starter workflow that forwards instructions to the abstract generator.",
-  "parameters": {
-    "instructions": {
-      "description": "Guidance for what to generate.",
-      "required": true
-    }
-  },
-  "steps": [
-    {
-      "generationId": "abstract",
-      "description": "Run abstract generation with workflow-provided instructions.",
-      "params": {
-        "instructions": "{{instructions}}"
-      }
-    }
-  ]
-}
-
-export default starter;

package/ai-gen.config.ts

@@ -1,67 +0,0 @@
-export const config = {
-    "repoRoot": ".",
-    "generationsDir": ".ai/generators",
-    "workflowsDir": ".ai/workflows",
-    "model": "gpt-5.3-codex",
-    "maxToolRounds": 100,
-    "maxContextFileSizeBytes": 60000,
-    "defaultMaxOutputFiles": 10,
-    "ignore": [
-        ".git",
-        "node_modules",
-        "dist",
-        "build",
-        ".next",
-        ".turbo",
-        ".cache",
-        "coverage",
-        ".idea",
-        ".vscode",
-        ".langgraph_api",
-        ".langgraph_checkpoint",
-        ".easigen",
-        "dist",
-
-        "package-lock.json",
-    ],
-    "offLimits": [
-        ".env",
-        ".env.*",
-        "*.pem",
-        "*.key",
-        "*.crt",
-        "*.p12",
-        "*.pfx",
-        ".easigen",
-        "dist",
-        ".git",
-
-        "node_modules",
-        "dist",
-        "build",
-        ".next",
-        ".turbo",
-        ".cache",
-        "coverage",
-        ".idea",
-        ".vscode",
-        ".langgraph_api",
-        ".langgraph_checkpoint",
-        ".easigen",
-        "dist",
-
-        "package-lock.json",
-    ],
-    "defaultContext": [],
-    "defaultKeywordContexts": [],
-    "openai": {
-        "timeoutMs": 120000,
-        "reconnectPollTimeoutMs": 30000,
-        "reconnectPollIntervalMs": 2000
-    },
-    "logging": {
-        "level": "info",
-        "pretty": true
-    }
-};
-export default config;

package/src/auth/AuthStateDetector.ts

@@ -1,18 +0,0 @@
-import type { ActorContext } from '../core/ActorContext.js';
-import type { LoginFlowDefinition } from './LoginFlow.types.js';
-
-export class AuthStateDetector {
-  async isLoggedIn(context: ActorContext, definition: LoginFlowDefinition): Promise<boolean> {
-    if (definition.behavior?.authCheckUrl !== undefined) {
-      await context.nav.goto(definition.behavior.authCheckUrl);
-    }
-
-    if (definition.hooks?.verifyLoggedIn !== undefined) {
-      return Boolean(await definition.hooks.verifyLoggedIn(context));
-    }
-
-    return context.page.exists(definition.selectors.loggedInSignal, {
-      timeout: definition.behavior?.loggedInTimeoutMs ?? 2_000
-    });
-  }
-}

package/src/auth/CredentialsProvider.ts

@@ -1,48 +0,0 @@
-import { AuthError } from '../errors/AuthError.js';
-
-export interface Credentials {
-  username: string;
-  password: string;
-  accountId?: string;
-}
-
-export interface CredentialRef {
-  id: string;
-  usernameEnv?: string;
-  passwordEnv?: string;
-}
-
-export interface CredentialsProvider {
-  getCredentials(ref: CredentialRef): Promise<Credentials>;
-}
-
-export class EnvCredentialsProvider implements CredentialsProvider {
-  async getCredentials(ref: CredentialRef): Promise<Credentials> {
-    const usernameKey = ref.usernameEnv ?? `${ref.id.toUpperCase()}_USERNAME`;
-    const passwordKey = ref.passwordEnv ?? `${ref.id.toUpperCase()}_PASSWORD`;
-    const username = process.env[usernameKey];
-    const password = process.env[passwordKey];
-
-    if (username === undefined || username.length === 0) {
-      throw new AuthError(`Missing username environment variable: ${usernameKey}`);
-    }
-
-    if (password === undefined || password.length === 0) {
-      throw new AuthError(`Missing password environment variable: ${passwordKey}`);
-    }
-
-    return { username, password, accountId: ref.id };
-  }
-}
-
-export class StaticCredentialsProvider implements CredentialsProvider {
-  constructor(private readonly credentials: Record<string, Credentials>) {}
-
-  async getCredentials(ref: CredentialRef): Promise<Credentials> {
-    const credential = this.credentials[ref.id];
-    if (credential === undefined) {
-      throw new AuthError(`No static credentials registered for credential id: ${ref.id}`);
-    }
-    return credential;
-  }
-}