@hover-dev/core 0.20.0 → 0.21.0

package/dist/specs/humanSteps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAwDxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}
+{"version":3,"file":"humanSteps.d.ts","sourceRoot":"","sources":["../../src/specs/humanSteps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAoExE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAmBvD"}

package/dist/specs/humanSteps.js

@@ -40,6 +40,18 @@ export function humanStep(tool, rawInput) {
             const key = String(input.key ?? '');
             return key ? `Press ${key}` : null;
         }
+        // Grounded control tools (MCP-first) — the target is role+name/testId/text
+        // ON the input itself, not an `element` string.
+        case 'click_control':
+            return `Click ${describeGrounded(input)}`;
+        case 'fill_control':
+            return `Fill ${describeGrounded(input)} with ${quote(String(input.value ?? ''))}`;
+        case 'select_control':
+            return `Select ${quote(String(input.value ?? ''))} in ${describeGrounded(input)}`;
+        case 'check_control':
+            return `${input.checked === false ? 'Uncheck' : 'Check'} ${describeGrounded(input)}`;
+        case 'assert_visible':
+            return `Expect ${describeGrounded(input)} to be visible`;
         // Diagnostic / read-only — same skip list as writeSpec.translateStep.
         case 'browser_wait_for':
         case 'browser_tabs':
@@ -91,6 +103,23 @@ function describe(raw) {
     const s = String(raw ?? '').trim();
     return s.length > 0 ? s : 'the target element';
 }
+/** Human phrase for a GROUNDED target ({ role, name, testId, text }) — the shape
+ *  the *_control tools carry, vs the old browser_* tools' `element` string. */
+function describeGrounded(input) {
+    const role = typeof input.role === 'string' ? input.role : '';
+    const name = typeof input.name === 'string' ? input.name : '';
+    const testId = typeof input.testId === 'string' ? input.testId : '';
+    const text = typeof input.text === 'string' ? input.text : '';
+    if (role && name)
+        return `${role} "${name}"`;
+    if (name)
+        return `"${name}"`;
+    if (testId)
+        return `testId "${testId}"`;
+    if (text)
+        return `"${text}"`;
+    return 'the target element';
+}
 /** Wrap in double-quotes for prose; escape internal quotes. A redacted
  *  credential (stored as a `process.env.X …` expression) shows as the masked
  *  `$X` instead — the prose, like the code, never reveals the secret. */

package/dist/specs/writeSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AA+mBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AA2CD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB;;;;yEAIqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;sFAIkF;IAClF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;qEAIiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiDD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD;;;;;2DAKuD;IACvD,gBAAgB,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAQD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAchF;AAonBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAMxE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}

package/dist/specs/writeSpec.js

@@ -201,13 +201,17 @@ async function writeOneSpec(opts, slug, displayName, rawSteps) {
     const envVars = (opts.redactions ?? []).map(r => r.envVar);
     const detectedPrefix = authPrefixLength(cleanActions, envVars);
     const userConfigName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(opts.devRoot, n)));
+    // A config Hover scaffolded earlier this run (e.g. a non-login spec wrote a
+    // plain one first) is OURS to upgrade — treat it like "no user config", not a
+    // hands-off user file. ensurePlaywrightConfig adds the setup project to it.
+    const ownScaffold = !!userConfigName && readFileSync(join(opts.devRoot, userConfigName), 'utf-8').includes(SCAFFOLD_MARKER);
     // Already opted in: auth.setup.ts exists from a prior approval (and the config
     // already registers it), so engage AUTOMATICALLY — don't re-ask or re-edit.
     const authSetupExists = existsSync(join(dir, 'auth.setup.ts'));
     // Engage the fixture when a login is detected AND we can register the setup
-    // project: we scaffold the config (no user config), the caller approved editing
-    // it (opts.authFixture, Stage 4), or the fixture was already set up earlier.
-    const engage = detectedPrefix > 0 && (!userConfigName || opts.authFixture === true || authSetupExists);
+    // project: we scaffold/own the config, the caller approved editing a user
+    // config (opts.authFixture, Stage 4), or the fixture was already set up earlier.
+    const engage = detectedPrefix > 0 && (!userConfigName || ownScaffold || opts.authFixture === true || authSetupExists);
     const authPrefix = engage ? detectedPrefix : 0;
     const authFile = engage ? AUTH_STATE_FILE : undefined;
     let authFixtureOffer;
@@ -1005,28 +1009,24 @@ async function ensureResetStateHelper(devRoot, keys) {
     ].join('\n');
     await writeFile(join(dir, 'resetState.ts'), source, 'utf-8');
 }
-async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
-    if (PLAYWRIGHT_CONFIG_NAMES.some(n => existsSync(join(devRoot, n))))
-        return;
-    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
-    if (!origin)
-        return;
-    // Auth-as-fixture: register a `setup` project (matches auth.setup.ts) that the
-    // main project depends on, so login runs ONCE before the specs. Only emitted
-    // when scaffolding our own config (we never touch a user's existing one).
+const SCAFFOLD_MARKER = 'Scaffolded by Hover';
+/** The scaffolded config source. When `authFile` is set, a `setup` project runs
+ *  auth.setup.ts ONCE and the main `chromium` project reuses the saved
+ *  storageState — so EVERY spec starts authenticated, not just the login flow. */
+function renderScaffoldConfig(origin, authFile) {
     const projects = authFile
         ? [
             `  projects: [`,
             `    { name: 'setup', testMatch: /.*\\.setup\\.ts$/ },`,
-            `    { name: 'chromium', dependencies: ['setup'] },`,
+            `    { name: 'chromium', dependencies: ['setup'], use: { storageState: ${JSON.stringify(authFile)} } },`,
             `  ],`,
         ]
         : [];
-    const source = [
+    return [
         `import { defineConfig } from '@playwright/test';`,
         ``,
         `/**`,
-        ` * Scaffolded by Hover so crystallized specs (which use relative URLs like`,
+        ` * ${SCAFFOLD_MARKER} so crystallized specs (which use relative URLs like`,
         ` * page.goto("/")) resolve against a base. Override HOVER_BASE_URL in CI to`,
         ` * point the same specs at staging/prod.`,
         ` */`,
@@ -1039,7 +1039,50 @@ async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
         `});`,
         ``,
     ].join('\n');
-    await writeFile(join(devRoot, 'playwright.config.ts'), source, 'utf-8');
+}
+async function ensurePlaywrightConfig(devRoot, steps, startUrl, authFile) {
+    const origin = firstNavigateOrigin(steps) ?? originOf(startUrl);
+    if (!origin)
+        return;
+    const existingName = PLAYWRIGHT_CONFIG_NAMES.find(n => existsSync(join(devRoot, n)));
+    if (existingName) {
+        // A config already exists. Only ever UPGRADE our OWN scaffold — and only to
+        // add the auth `setup` project when a login was just lifted (authFile) and
+        // it isn't there yet. This makes auth order-independent: whichever spec in
+        // the run triggers auth-fixture upgrades the config, even if a non-login
+        // spec scaffolded a plain config first. A user's own config is never touched
+        // (that's the Stage-4 approval flow via authFixtureOffer).
+        if (!authFile)
+            return;
+        try {
+            const cur = readFileSync(join(devRoot, existingName), 'utf-8');
+            if (!cur.includes(SCAFFOLD_MARKER) || cur.includes(`name: 'setup'`))
+                return;
+            await writeFile(join(devRoot, existingName), renderScaffoldConfig(origin, authFile), 'utf-8');
+        }
+        catch { /* upgrade is best-effort */ }
+        return;
+    }
+    await writeFile(join(devRoot, 'playwright.config.ts'), renderScaffoldConfig(origin, authFile), 'utf-8');
+    await ensurePlaywrightDep(devRoot);
+}
+/** When Hover scaffolds the config it also ensures `@playwright/test` is a
+ *  devDependency — otherwise `npx playwright test` can't run the specs locally.
+ *  Best-effort + idempotent: skips if already present (either dep list) or if
+ *  there's no package.json. Reformats to 2-space JSON (the npm norm). */
+const PLAYWRIGHT_TEST_RANGE = '^1.50.0';
+async function ensurePlaywrightDep(devRoot) {
+    const pkgPath = join(devRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg.dependencies?.['@playwright/test'] || pkg.devDependencies?.['@playwright/test'])
+            return;
+        pkg.devDependencies = { ...(pkg.devDependencies ?? {}), '@playwright/test': PLAYWRIGHT_TEST_RANGE };
+        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* best-effort — never break Save */ }
 }
 function stripBaseUrl(url) {
     // http://localhost:5173/checkout → /checkout, http://localhost:5173/ → /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",