@epsilon-asi/actors 0.0.3 → 0.0.5

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

@@ -0,0 +1,117 @@
+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

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,67 @@
+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/package.json

@@ -1,28 +1,20 @@
 {
   "name": "@epsilon-asi/actors",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A TypeScript Puppeteer actor framework using existing Chrome profiles and ghost-cursor.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "mainDir": "./",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-
-    "./package.json": "./package.json"
+      "require": "./dist/index.js"
+    }
   },
   "bin": {
     "paf": "./dist/cli/run.js"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -38,7 +30,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@vitest/coverage-v8": "^4.1.7",
-    "typescript": "^6.0.3",
+
     "vitest": "^4.1.7"
   },
   "engines": {

package/src/auth/AuthStateDetector.ts

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,48 @@
+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;
+  }
+}