@noego/wood 0.4.9 → 0.5.0

package/dist/automation/actions_executor.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var actions_executor_exports = {};
+__export(actions_executor_exports, {
+  deriveReceiptChanges: () => deriveReceiptChanges,
+  executeAction: () => executeAction
+});
+module.exports = __toCommonJS(actions_executor_exports);
+var import_errors = require("./errors.cjs");
+var import_introspection_reader = require("./introspection_reader.cjs");
+var import_locator = require("./locator.cjs");
+var import_scrolling_executor = require("./scrolling_executor.cjs");
+var import_waits_executor = require("./waits_executor.cjs");
+let nextActionId = 1;
+async function readTarget(page, previous) {
+  const snapshot = await (0, import_introspection_reader.readAutomationSnapshot)(page);
+  const url = page.url();
+  const title = await page.title();
+  const currentRoute = (0, import_introspection_reader.formatRoute)(snapshot?.currentRoute ?? null);
+  return { targetId: previous?.targetId ?? "page", windowId: snapshot?.windowId ?? previous?.windowId ?? null, pageGeneration: previous?.pageGeneration ?? 0, url, title, ...currentRoute ? { currentRoute } : {}, woodBridgePresent: snapshot !== null, eligible: true };
+}
+function deriveReceiptChanges(before, after) {
+  return { changedDocument: before.url !== after.url || before.title !== after.title, changedTarget: before.targetId !== after.targetId || before.windowId !== after.windowId || before.pageGeneration !== after.pageGeneration, changedRoute: before.currentRoute !== after.currentRoute };
+}
+async function actionable(page, target) {
+  const locator = (0, import_locator.toPlaywrightLocator)(page, target);
+  const count = await locator.count();
+  if (count !== 1) {
+    const visibility = await Promise.all(Array.from({ length: count }, (_, index) => locator.nth(index).isVisible().catch(() => false)));
+    return (0, import_errors.automationError)("LOCATOR_INVALID", `Expected exactly one actionable match for ${(0, import_locator.describeLocator)(target)}, found ${count}.`, { details: { matchCount: count, candidateVisibility: visibility } });
+  }
+  return (0, import_errors.automationOk)(locator);
+}
+function actionTarget(action) {
+  return "target" in action ? action.target : void 0;
+}
+async function executeAction(page, action, options) {
+  const startedAt = /* @__PURE__ */ new Date();
+  const before = await readTarget(page);
+  const diagnostics = [];
+  const eventLike = options?.wait && (options.wait.kind === "route" || options.wait.kind === "url" || options.wait.kind === "target" || options.wait.kind === "trace");
+  const armedWait = eventLike && options?.wait ? (0, import_waits_executor.awaitCondition)(page, options.wait, { timeoutMs: options.timeoutMs }) : void 0;
+  try {
+    const target = actionTarget(action);
+    let locator;
+    if (target) {
+      const result = await actionable(page, target);
+      if (!result.ok) return result;
+      locator = result.value;
+    }
+    if (action.kind === "click") await locator.click({ button: action.button });
+    else if (action.kind === "double_click") await locator.dblclick();
+    else if (action.kind === "fill") await locator.fill(action.value);
+    else if (action.kind === "type") await locator.pressSequentially(action.value, { delay: action.delayMs });
+    else if (action.kind === "press") {
+      for (const keys of action.keys) action.target ? await locator.press(keys) : await page.keyboard.press(keys);
+    } else if (action.kind === "select") await locator.selectOption(action.option);
+    else if (action.kind === "toggle") await locator.setChecked(action.checked);
+    else if (action.kind === "scroll") {
+      const result = await (0, import_scrolling_executor.executeScroll)(page, action.command);
+      if (!result.ok) return result;
+      diagnostics.push(`scroll steps=${result.value.steps}`);
+    } else if (action.kind === "back") await page.goBack({ timeout: options?.timeoutMs });
+    else if (action.kind === "forward") await page.goForward({ timeout: options?.timeoutMs });
+    else if (action.kind === "reload") await page.reload({ timeout: options?.timeoutMs });
+    else {
+      const result = await (0, import_waits_executor.awaitCondition)(page, action.condition, { timeoutMs: options?.timeoutMs });
+      if (!result.ok) return result;
+      diagnostics.push(`waitedMs=${result.value.waitedMs}`);
+    }
+    const postcondition = armedWait ? await armedWait : options?.wait ? await (0, import_waits_executor.awaitCondition)(page, options.wait, { timeoutMs: options.timeoutMs }) : void 0;
+    if (postcondition && !postcondition.ok) return (0, import_errors.automationError)(postcondition.error.code, postcondition.error.message, { requiredAction: postcondition.error.requiredAction, details: postcondition.error.details });
+    const after = await readTarget(page, before);
+    const changes = deriveReceiptChanges(before, after);
+    return (0, import_errors.automationOk)({ actionId: `action-${nextActionId++}`, targetBefore: before, targetAfter: after, routeBefore: before.currentRoute, routeAfter: after.currentRoute, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), actionability: target ? "passed" : "bypassed", ...changes, diagnostics });
+  } catch (error) {
+    return (0, import_errors.automationError)("ACTION_FAILED", `Action ${action.kind} failed.`, { details: { cause: error instanceof Error ? error.message : String(error), diagnostics } });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deriveReceiptChanges,
+  executeAction
+});
+//# sourceMappingURL=actions_executor.cjs.map

package/dist/automation/actions_executor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/actions_executor.ts"],"sourcesContent":["import type { Page } from 'playwright';\nimport type { WoodAutomationAction } from './actions.cjs';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.cjs';\nimport { formatRoute, readAutomationSnapshot } from './introspection_reader.cjs';\nimport { describeLocator, toPlaywrightLocator, type WoodLocator } from './locator.cjs';\nimport type { WoodActionReceipt } from './receipts.cjs';\nimport { executeScroll } from './scrolling_executor.cjs';\nimport type { WoodLiveTarget } from './target_identity.cjs';\nimport { awaitCondition } from './waits_executor.cjs';\nimport type { WoodWaitCondition } from './waits.cjs';\n\nlet nextActionId = 1;\nasync function readTarget(page: Page, previous?: WoodLiveTarget): Promise<WoodLiveTarget> {\n  const snapshot = await readAutomationSnapshot(page);\n  const url = page.url();\n  const title = await page.title();\n  const currentRoute = formatRoute(snapshot?.currentRoute ?? null);\n  return { targetId: previous?.targetId ?? 'page', windowId: snapshot?.windowId ?? previous?.windowId ?? null, pageGeneration: previous?.pageGeneration ?? 0, url, title, ...(currentRoute ? { currentRoute } : {}), woodBridgePresent: snapshot !== null, eligible: true };\n}\nexport function deriveReceiptChanges(before: WoodLiveTarget, after: WoodLiveTarget): Pick<WoodActionReceipt, 'changedDocument' | 'changedTarget' | 'changedRoute'> {\n  return { changedDocument: before.url !== after.url || before.title !== after.title, changedTarget: before.targetId !== after.targetId || before.windowId !== after.windowId || before.pageGeneration !== after.pageGeneration, changedRoute: before.currentRoute !== after.currentRoute };\n}\nasync function actionable(page: Page, target: WoodLocator): Promise<WoodAutomationResult<ReturnType<typeof toPlaywrightLocator>>> {\n  const locator = toPlaywrightLocator(page, target);\n  const count = await locator.count();\n  if (count !== 1) {\n    const visibility = await Promise.all(Array.from({ length: count }, (_, index) => locator.nth(index).isVisible().catch(() => false)));\n    return automationError('LOCATOR_INVALID', `Expected exactly one actionable match for ${describeLocator(target)}, found ${count}.`, { details: { matchCount: count, candidateVisibility: visibility } });\n  }\n  return automationOk(locator);\n}\nfunction actionTarget(action: WoodAutomationAction): WoodLocator | undefined {\n  return 'target' in action ? action.target : undefined;\n}\nexport async function executeAction(page: Page, action: WoodAutomationAction, options?: { wait?: WoodWaitCondition; timeoutMs?: number }): Promise<WoodAutomationResult<WoodActionReceipt>> {\n  const startedAt = new Date();\n  const before = await readTarget(page);\n  const diagnostics: string[] = [];\n  const eventLike = options?.wait && (options.wait.kind === 'route' || options.wait.kind === 'url' || options.wait.kind === 'target' || options.wait.kind === 'trace');\n  const armedWait = eventLike && options?.wait ? awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : undefined;\n  try {\n    const target = actionTarget(action);\n    let locator;\n    if (target) {\n      const result = await actionable(page, target);\n      if (!result.ok) return result;\n      locator = result.value;\n    }\n    if (action.kind === 'click') await locator!.click({ button: action.button });\n    else if (action.kind === 'double_click') await locator!.dblclick();\n    else if (action.kind === 'fill') await locator!.fill(action.value);\n    else if (action.kind === 'type') await locator!.pressSequentially(action.value, { delay: action.delayMs });\n    else if (action.kind === 'press') {\n      for (const keys of action.keys) action.target ? await locator!.press(keys) : await page.keyboard.press(keys);\n    } else if (action.kind === 'select') await locator!.selectOption(action.option);\n    else if (action.kind === 'toggle') await locator!.setChecked(action.checked);\n    else if (action.kind === 'scroll') {\n      const result = await executeScroll(page, action.command);\n      if (!result.ok) return result;\n      diagnostics.push(`scroll steps=${result.value.steps}`);\n    } else if (action.kind === 'back') await page.goBack({ timeout: options?.timeoutMs });\n    else if (action.kind === 'forward') await page.goForward({ timeout: options?.timeoutMs });\n    else if (action.kind === 'reload') await page.reload({ timeout: options?.timeoutMs });\n    else {\n      const result = await awaitCondition(page, action.condition, { timeoutMs: options?.timeoutMs });\n      if (!result.ok) return result;\n      diagnostics.push(`waitedMs=${result.value.waitedMs}`);\n    }\n    const postcondition = armedWait ? await armedWait : (options?.wait ? await awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : undefined);\n    if (postcondition && !postcondition.ok) return automationError(postcondition.error.code, postcondition.error.message, { requiredAction: postcondition.error.requiredAction, details: postcondition.error.details });\n    const after = await readTarget(page, before);\n    const changes = deriveReceiptChanges(before, after);\n    return automationOk({ actionId: `action-${nextActionId++}`, targetBefore: before, targetAfter: after, routeBefore: before.currentRoute, routeAfter: after.currentRoute, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), actionability: target ? 'passed' : 'bypassed', ...changes, diagnostics });\n  } catch (error) {\n    return automationError('ACTION_FAILED', `Action ${action.kind} failed.`, { details: { cause: error instanceof Error ? error.message : String(error), diagnostics } });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/automation/actions_executor.d.cts

@@ -0,0 +1,16 @@
+import { Page } from 'playwright';
+import { WoodAutomationAction } from './actions.cjs';
+import { WoodAutomationResult } from './errors.cjs';
+import { WoodActionReceipt } from './receipts.cjs';
+import { WoodLiveTarget } from './target_identity.cjs';
+import { WoodWaitCondition } from './waits.cjs';
+import './locator.cjs';
+import './scrolling.cjs';
+
+declare function deriveReceiptChanges(before: WoodLiveTarget, after: WoodLiveTarget): Pick<WoodActionReceipt, 'changedDocument' | 'changedTarget' | 'changedRoute'>;
+declare function executeAction(page: Page, action: WoodAutomationAction, options?: {
+    wait?: WoodWaitCondition;
+    timeoutMs?: number;
+}): Promise<WoodAutomationResult<WoodActionReceipt>>;
+
+export { deriveReceiptChanges, executeAction };

package/dist/automation/actions_executor.d.ts

@@ -0,0 +1,16 @@
+import { Page } from 'playwright';
+import { WoodAutomationAction } from './actions.js';
+import { WoodAutomationResult } from './errors.js';
+import { WoodActionReceipt } from './receipts.js';
+import { WoodLiveTarget } from './target_identity.js';
+import { WoodWaitCondition } from './waits.js';
+import './locator.js';
+import './scrolling.js';
+
+declare function deriveReceiptChanges(before: WoodLiveTarget, after: WoodLiveTarget): Pick<WoodActionReceipt, 'changedDocument' | 'changedTarget' | 'changedRoute'>;
+declare function executeAction(page: Page, action: WoodAutomationAction, options?: {
+    wait?: WoodWaitCondition;
+    timeoutMs?: number;
+}): Promise<WoodAutomationResult<WoodActionReceipt>>;
+
+export { deriveReceiptChanges, executeAction };

package/dist/automation/actions_executor.js

@@ -0,0 +1,76 @@
+import { automationError, automationOk } from "./errors.js";
+import { formatRoute, readAutomationSnapshot } from "./introspection_reader.js";
+import { describeLocator, toPlaywrightLocator } from "./locator.js";
+import { executeScroll } from "./scrolling_executor.js";
+import { awaitCondition } from "./waits_executor.js";
+let nextActionId = 1;
+async function readTarget(page, previous) {
+  const snapshot = await readAutomationSnapshot(page);
+  const url = page.url();
+  const title = await page.title();
+  const currentRoute = formatRoute(snapshot?.currentRoute ?? null);
+  return { targetId: previous?.targetId ?? "page", windowId: snapshot?.windowId ?? previous?.windowId ?? null, pageGeneration: previous?.pageGeneration ?? 0, url, title, ...currentRoute ? { currentRoute } : {}, woodBridgePresent: snapshot !== null, eligible: true };
+}
+function deriveReceiptChanges(before, after) {
+  return { changedDocument: before.url !== after.url || before.title !== after.title, changedTarget: before.targetId !== after.targetId || before.windowId !== after.windowId || before.pageGeneration !== after.pageGeneration, changedRoute: before.currentRoute !== after.currentRoute };
+}
+async function actionable(page, target) {
+  const locator = toPlaywrightLocator(page, target);
+  const count = await locator.count();
+  if (count !== 1) {
+    const visibility = await Promise.all(Array.from({ length: count }, (_, index) => locator.nth(index).isVisible().catch(() => false)));
+    return automationError("LOCATOR_INVALID", `Expected exactly one actionable match for ${describeLocator(target)}, found ${count}.`, { details: { matchCount: count, candidateVisibility: visibility } });
+  }
+  return automationOk(locator);
+}
+function actionTarget(action) {
+  return "target" in action ? action.target : void 0;
+}
+async function executeAction(page, action, options) {
+  const startedAt = /* @__PURE__ */ new Date();
+  const before = await readTarget(page);
+  const diagnostics = [];
+  const eventLike = options?.wait && (options.wait.kind === "route" || options.wait.kind === "url" || options.wait.kind === "target" || options.wait.kind === "trace");
+  const armedWait = eventLike && options?.wait ? awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : void 0;
+  try {
+    const target = actionTarget(action);
+    let locator;
+    if (target) {
+      const result = await actionable(page, target);
+      if (!result.ok) return result;
+      locator = result.value;
+    }
+    if (action.kind === "click") await locator.click({ button: action.button });
+    else if (action.kind === "double_click") await locator.dblclick();
+    else if (action.kind === "fill") await locator.fill(action.value);
+    else if (action.kind === "type") await locator.pressSequentially(action.value, { delay: action.delayMs });
+    else if (action.kind === "press") {
+      for (const keys of action.keys) action.target ? await locator.press(keys) : await page.keyboard.press(keys);
+    } else if (action.kind === "select") await locator.selectOption(action.option);
+    else if (action.kind === "toggle") await locator.setChecked(action.checked);
+    else if (action.kind === "scroll") {
+      const result = await executeScroll(page, action.command);
+      if (!result.ok) return result;
+      diagnostics.push(`scroll steps=${result.value.steps}`);
+    } else if (action.kind === "back") await page.goBack({ timeout: options?.timeoutMs });
+    else if (action.kind === "forward") await page.goForward({ timeout: options?.timeoutMs });
+    else if (action.kind === "reload") await page.reload({ timeout: options?.timeoutMs });
+    else {
+      const result = await awaitCondition(page, action.condition, { timeoutMs: options?.timeoutMs });
+      if (!result.ok) return result;
+      diagnostics.push(`waitedMs=${result.value.waitedMs}`);
+    }
+    const postcondition = armedWait ? await armedWait : options?.wait ? await awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : void 0;
+    if (postcondition && !postcondition.ok) return automationError(postcondition.error.code, postcondition.error.message, { requiredAction: postcondition.error.requiredAction, details: postcondition.error.details });
+    const after = await readTarget(page, before);
+    const changes = deriveReceiptChanges(before, after);
+    return automationOk({ actionId: `action-${nextActionId++}`, targetBefore: before, targetAfter: after, routeBefore: before.currentRoute, routeAfter: after.currentRoute, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), actionability: target ? "passed" : "bypassed", ...changes, diagnostics });
+  } catch (error) {
+    return automationError("ACTION_FAILED", `Action ${action.kind} failed.`, { details: { cause: error instanceof Error ? error.message : String(error), diagnostics } });
+  }
+}
+export {
+  deriveReceiptChanges,
+  executeAction
+};
+//# sourceMappingURL=actions_executor.js.map

package/dist/automation/actions_executor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/actions_executor.ts"],"sourcesContent":["import type { Page } from 'playwright';\nimport type { WoodAutomationAction } from './actions.js';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.js';\nimport { formatRoute, readAutomationSnapshot } from './introspection_reader.js';\nimport { describeLocator, toPlaywrightLocator, type WoodLocator } from './locator.js';\nimport type { WoodActionReceipt } from './receipts.js';\nimport { executeScroll } from './scrolling_executor.js';\nimport type { WoodLiveTarget } from './target_identity.js';\nimport { awaitCondition } from './waits_executor.js';\nimport type { WoodWaitCondition } from './waits.js';\n\nlet nextActionId = 1;\nasync function readTarget(page: Page, previous?: WoodLiveTarget): Promise<WoodLiveTarget> {\n  const snapshot = await readAutomationSnapshot(page);\n  const url = page.url();\n  const title = await page.title();\n  const currentRoute = formatRoute(snapshot?.currentRoute ?? null);\n  return { targetId: previous?.targetId ?? 'page', windowId: snapshot?.windowId ?? previous?.windowId ?? null, pageGeneration: previous?.pageGeneration ?? 0, url, title, ...(currentRoute ? { currentRoute } : {}), woodBridgePresent: snapshot !== null, eligible: true };\n}\nexport function deriveReceiptChanges(before: WoodLiveTarget, after: WoodLiveTarget): Pick<WoodActionReceipt, 'changedDocument' | 'changedTarget' | 'changedRoute'> {\n  return { changedDocument: before.url !== after.url || before.title !== after.title, changedTarget: before.targetId !== after.targetId || before.windowId !== after.windowId || before.pageGeneration !== after.pageGeneration, changedRoute: before.currentRoute !== after.currentRoute };\n}\nasync function actionable(page: Page, target: WoodLocator): Promise<WoodAutomationResult<ReturnType<typeof toPlaywrightLocator>>> {\n  const locator = toPlaywrightLocator(page, target);\n  const count = await locator.count();\n  if (count !== 1) {\n    const visibility = await Promise.all(Array.from({ length: count }, (_, index) => locator.nth(index).isVisible().catch(() => false)));\n    return automationError('LOCATOR_INVALID', `Expected exactly one actionable match for ${describeLocator(target)}, found ${count}.`, { details: { matchCount: count, candidateVisibility: visibility } });\n  }\n  return automationOk(locator);\n}\nfunction actionTarget(action: WoodAutomationAction): WoodLocator | undefined {\n  return 'target' in action ? action.target : undefined;\n}\nexport async function executeAction(page: Page, action: WoodAutomationAction, options?: { wait?: WoodWaitCondition; timeoutMs?: number }): Promise<WoodAutomationResult<WoodActionReceipt>> {\n  const startedAt = new Date();\n  const before = await readTarget(page);\n  const diagnostics: string[] = [];\n  const eventLike = options?.wait && (options.wait.kind === 'route' || options.wait.kind === 'url' || options.wait.kind === 'target' || options.wait.kind === 'trace');\n  const armedWait = eventLike && options?.wait ? awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : undefined;\n  try {\n    const target = actionTarget(action);\n    let locator;\n    if (target) {\n      const result = await actionable(page, target);\n      if (!result.ok) return result;\n      locator = result.value;\n    }\n    if (action.kind === 'click') await locator!.click({ button: action.button });\n    else if (action.kind === 'double_click') await locator!.dblclick();\n    else if (action.kind === 'fill') await locator!.fill(action.value);\n    else if (action.kind === 'type') await locator!.pressSequentially(action.value, { delay: action.delayMs });\n    else if (action.kind === 'press') {\n      for (const keys of action.keys) action.target ? await locator!.press(keys) : await page.keyboard.press(keys);\n    } else if (action.kind === 'select') await locator!.selectOption(action.option);\n    else if (action.kind === 'toggle') await locator!.setChecked(action.checked);\n    else if (action.kind === 'scroll') {\n      const result = await executeScroll(page, action.command);\n      if (!result.ok) return result;\n      diagnostics.push(`scroll steps=${result.value.steps}`);\n    } else if (action.kind === 'back') await page.goBack({ timeout: options?.timeoutMs });\n    else if (action.kind === 'forward') await page.goForward({ timeout: options?.timeoutMs });\n    else if (action.kind === 'reload') await page.reload({ timeout: options?.timeoutMs });\n    else {\n      const result = await awaitCondition(page, action.condition, { timeoutMs: options?.timeoutMs });\n      if (!result.ok) return result;\n      diagnostics.push(`waitedMs=${result.value.waitedMs}`);\n    }\n    const postcondition = armedWait ? await armedWait : (options?.wait ? await awaitCondition(page, options.wait, { timeoutMs: options.timeoutMs }) : undefined);\n    if (postcondition && !postcondition.ok) return automationError(postcondition.error.code, postcondition.error.message, { requiredAction: postcondition.error.requiredAction, details: postcondition.error.details });\n    const after = await readTarget(page, before);\n    const changes = deriveReceiptChanges(before, after);\n    return automationOk({ actionId: `action-${nextActionId++}`, targetBefore: before, targetAfter: after, routeBefore: before.currentRoute, routeAfter: after.currentRoute, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), actionability: target ? 'passed' : 'bypassed', ...changes, diagnostics });\n  } catch (error) {\n    return automationError('ACTION_FAILED', `Action ${action.kind} failed.`, { details: { cause: error instanceof Error ? error.message : String(error), diagnostics } });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/automation/connection.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var connection_exports = {};
+__export(connection_exports, {
+  connectToWoodApp: () => connectToWoodApp,
+  readDevMetadata: () => readDevMetadata
+});
+module.exports = __toCommonJS(connection_exports);
+var import_dev_metadata = require("../dev/dev_metadata.cjs");
+var import_errors = require("./errors.cjs");
+async function loadPlaywright() {
+  try {
+    return (0, import_errors.automationOk)(await import("playwright"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (0, import_errors.automationError)("PLAYWRIGHT_UNAVAILABLE", `Playwright is not installed in this environment. ${message}`, {
+      requiredAction: "Install playwright as a dev dependency of the app project."
+    });
+  }
+}
+function readDevMetadata(projectRoot) {
+  try {
+    return (0, import_errors.automationOk)((0, import_dev_metadata.readWoodDevMetadata)(projectRoot));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const requiredAction = message.includes("wood dev") ? void 0 : 'Start the app with "wood dev" first.';
+    return (0, import_errors.automationError)("DEV_METADATA_MISSING", message, requiredAction ? { requiredAction } : void 0);
+  }
+}
+async function connectToWoodApp(projectRoot = process.cwd()) {
+  const metadata = readDevMetadata(projectRoot);
+  if (!metadata.ok) {
+    return metadata;
+  }
+  const playwright = await loadPlaywright();
+  if (!playwright.ok) {
+    return playwright;
+  }
+  try {
+    const browser = await playwright.value.chromium.connectOverCDP(metadata.value.browserUrl);
+    return (0, import_errors.automationOk)({
+      browser,
+      metadata: metadata.value,
+      close: async () => {
+        await browser.close();
+      }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (0, import_errors.automationError)("CONNECT_FAILED", `Could not connect to ${metadata.value.browserUrl}. ${message}`, {
+      requiredAction: "Verify the wood dev app is still running and the debug port matches .wood/dev.json."
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  connectToWoodApp,
+  readDevMetadata
+});
+//# sourceMappingURL=connection.cjs.map

package/dist/automation/connection.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/connection.ts"],"sourcesContent":["/**\n * Connection to a running `wood dev` Electron app over CDP.\n * Extracted from bin/axe.js (AXE-WP-01); the CLI is now a thin adapter.\n */\n\nimport type { Browser } from 'playwright';\nimport { readWoodDevMetadata, type WoodDevMetadata } from '../dev/dev_metadata.cjs';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.cjs';\n\nexport interface WoodAutomationConnection {\n  browser: Browser;\n  metadata: WoodDevMetadata;\n  close: () => Promise<void>;\n}\n\nasync function loadPlaywright(): Promise<WoodAutomationResult<typeof import('playwright')>> {\n  try {\n    return automationOk(await import('playwright'));\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    return automationError('PLAYWRIGHT_UNAVAILABLE', `Playwright is not installed in this environment. ${message}`, {\n      requiredAction: 'Install playwright as a dev dependency of the app project.',\n    });\n  }\n}\n\nexport function readDevMetadata(projectRoot: string): WoodAutomationResult<WoodDevMetadata> {\n  try {\n    return automationOk(readWoodDevMetadata(projectRoot));\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    // readWoodDevMetadata's own message already tells the user to run \"wood dev\".\n    const requiredAction = message.includes('wood dev') ? undefined : 'Start the app with \"wood dev\" first.';\n    return automationError('DEV_METADATA_MISSING', message, requiredAction ? { requiredAction } : undefined);\n  }\n}\n\nexport async function connectToWoodApp(\n  projectRoot: string = process.cwd(),\n): Promise<WoodAutomationResult<WoodAutomationConnection>> {\n  const metadata = readDevMetadata(projectRoot);\n  if (!metadata.ok) {\n    return metadata;\n  }\n\n  const playwright = await loadPlaywright();\n  if (!playwright.ok) {\n    return playwright;\n  }\n\n  try {\n    const browser = await playwright.value.chromium.connectOverCDP(metadata.value.browserUrl);\n    return automationOk({\n      browser,\n      metadata: metadata.value,\n      close: async () => {\n        await browser.close();\n      },\n    });\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    return automationError('CONNECT_FAILED', `Could not connect to ${metadata.value.browserUrl}. ${message}`, {\n      requiredAction: 'Verify the wood dev app is still running and the debug port matches .wood/dev.json.',\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,0BAA0D;AAC1D,oBAAyE;AAQzE,eAAe,iBAA6E;AAC1F,MAAI;AACF,eAAO,4BAAa,MAAM,OAAO,YAAY,CAAC;AAAA,EAChD,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,eAAO,+BAAgB,0BAA0B,oDAAoD,OAAO,IAAI;AAAA,MAC9G,gBAAgB;AAAA,IAClB,CAAC;AAAA,EACH;AACF;AAEO,SAAS,gBAAgB,aAA4D;AAC1F,MAAI;AACF,eAAO,gCAAa,yCAAoB,WAAW,CAAC;AAAA,EACtD,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAErE,UAAM,iBAAiB,QAAQ,SAAS,UAAU,IAAI,SAAY;AAClE,eAAO,+BAAgB,wBAAwB,SAAS,iBAAiB,EAAE,eAAe,IAAI,MAAS;AAAA,EACzG;AACF;AAEA,eAAsB,iBACpB,cAAsB,QAAQ,IAAI,GACuB;AACzD,QAAM,WAAW,gBAAgB,WAAW;AAC5C,MAAI,CAAC,SAAS,IAAI;AAChB,WAAO;AAAA,EACT;AAEA,QAAM,aAAa,MAAM,eAAe;AACxC,MAAI,CAAC,WAAW,IAAI;AAClB,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,UAAU,MAAM,WAAW,MAAM,SAAS,eAAe,SAAS,MAAM,UAAU;AACxF,eAAO,4BAAa;AAAA,MAClB;AAAA,MACA,UAAU,SAAS;AAAA,MACnB,OAAO,YAAY;AACjB,cAAM,QAAQ,MAAM;AAAA,MACtB;AAAA,IACF,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,eAAO,+BAAgB,kBAAkB,wBAAwB,SAAS,MAAM,UAAU,KAAK,OAAO,IAAI;AAAA,MACxG,gBAAgB;AAAA,IAClB,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/automation/connection.d.cts

@@ -0,0 +1,18 @@
+import { Browser } from 'playwright';
+import { WoodDevMetadata } from '../dev/dev_metadata.cjs';
+import { WoodAutomationResult } from './errors.cjs';
+
+/**
+ * Connection to a running `wood dev` Electron app over CDP.
+ * Extracted from bin/axe.js (AXE-WP-01); the CLI is now a thin adapter.
+ */
+
+interface WoodAutomationConnection {
+    browser: Browser;
+    metadata: WoodDevMetadata;
+    close: () => Promise<void>;
+}
+declare function readDevMetadata(projectRoot: string): WoodAutomationResult<WoodDevMetadata>;
+declare function connectToWoodApp(projectRoot?: string): Promise<WoodAutomationResult<WoodAutomationConnection>>;
+
+export { type WoodAutomationConnection, connectToWoodApp, readDevMetadata };

package/dist/automation/connection.d.ts

@@ -0,0 +1,18 @@
+import { Browser } from 'playwright';
+import { WoodDevMetadata } from '../dev/dev_metadata.js';
+import { WoodAutomationResult } from './errors.js';
+
+/**
+ * Connection to a running `wood dev` Electron app over CDP.
+ * Extracted from bin/axe.js (AXE-WP-01); the CLI is now a thin adapter.
+ */
+
+interface WoodAutomationConnection {
+    browser: Browser;
+    metadata: WoodDevMetadata;
+    close: () => Promise<void>;
+}
+declare function readDevMetadata(projectRoot: string): WoodAutomationResult<WoodDevMetadata>;
+declare function connectToWoodApp(projectRoot?: string): Promise<WoodAutomationResult<WoodAutomationConnection>>;
+
+export { type WoodAutomationConnection, connectToWoodApp, readDevMetadata };

package/dist/automation/connection.js

@@ -0,0 +1,51 @@
+import { readWoodDevMetadata } from "../dev/dev_metadata.js";
+import { automationError, automationOk } from "./errors.js";
+async function loadPlaywright() {
+  try {
+    return automationOk(await import("playwright"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return automationError("PLAYWRIGHT_UNAVAILABLE", `Playwright is not installed in this environment. ${message}`, {
+      requiredAction: "Install playwright as a dev dependency of the app project."
+    });
+  }
+}
+function readDevMetadata(projectRoot) {
+  try {
+    return automationOk(readWoodDevMetadata(projectRoot));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const requiredAction = message.includes("wood dev") ? void 0 : 'Start the app with "wood dev" first.';
+    return automationError("DEV_METADATA_MISSING", message, requiredAction ? { requiredAction } : void 0);
+  }
+}
+async function connectToWoodApp(projectRoot = process.cwd()) {
+  const metadata = readDevMetadata(projectRoot);
+  if (!metadata.ok) {
+    return metadata;
+  }
+  const playwright = await loadPlaywright();
+  if (!playwright.ok) {
+    return playwright;
+  }
+  try {
+    const browser = await playwright.value.chromium.connectOverCDP(metadata.value.browserUrl);
+    return automationOk({
+      browser,
+      metadata: metadata.value,
+      close: async () => {
+        await browser.close();
+      }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return automationError("CONNECT_FAILED", `Could not connect to ${metadata.value.browserUrl}. ${message}`, {
+      requiredAction: "Verify the wood dev app is still running and the debug port matches .wood/dev.json."
+    });
+  }
+}
+export {
+  connectToWoodApp,
+  readDevMetadata
+};
+//# sourceMappingURL=connection.js.map

package/dist/automation/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/connection.ts"],"sourcesContent":["/**\n * Connection to a running `wood dev` Electron app over CDP.\n * Extracted from bin/axe.js (AXE-WP-01); the CLI is now a thin adapter.\n */\n\nimport type { Browser } from 'playwright';\nimport { readWoodDevMetadata, type WoodDevMetadata } from '../dev/dev_metadata.js';\nimport { automationError, automationOk, type WoodAutomationResult } from './errors.js';\n\nexport interface WoodAutomationConnection {\n  browser: Browser;\n  metadata: WoodDevMetadata;\n  close: () => Promise<void>;\n}\n\nasync function loadPlaywright(): Promise<WoodAutomationResult<typeof import('playwright')>> {\n  try {\n    return automationOk(await import('playwright'));\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    return automationError('PLAYWRIGHT_UNAVAILABLE', `Playwright is not installed in this environment. ${message}`, {\n      requiredAction: 'Install playwright as a dev dependency of the app project.',\n    });\n  }\n}\n\nexport function readDevMetadata(projectRoot: string): WoodAutomationResult<WoodDevMetadata> {\n  try {\n    return automationOk(readWoodDevMetadata(projectRoot));\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    // readWoodDevMetadata's own message already tells the user to run \"wood dev\".\n    const requiredAction = message.includes('wood dev') ? undefined : 'Start the app with \"wood dev\" first.';\n    return automationError('DEV_METADATA_MISSING', message, requiredAction ? { requiredAction } : undefined);\n  }\n}\n\nexport async function connectToWoodApp(\n  projectRoot: string = process.cwd(),\n): Promise<WoodAutomationResult<WoodAutomationConnection>> {\n  const metadata = readDevMetadata(projectRoot);\n  if (!metadata.ok) {\n    return metadata;\n  }\n\n  const playwright = await loadPlaywright();\n  if (!playwright.ok) {\n    return playwright;\n  }\n\n  try {\n    const browser = await playwright.value.chromium.connectOverCDP(metadata.value.browserUrl);\n    return automationOk({\n      browser,\n      metadata: metadata.value,\n      close: async () => {\n        await browser.close();\n      },\n    });\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    return automationError('CONNECT_FAILED', `Could not connect to ${metadata.value.browserUrl}. ${message}`, {\n      requiredAction: 'Verify the wood dev app is still running and the debug port matches .wood/dev.json.',\n    });\n  }\n}\n"],"mappings":"AAMA,SAAS,2BAAiD;AAC1D,SAAS,iBAAiB,oBAA+C;AAQzE,eAAe,iBAA6E;AAC1F,MAAI;AACF,WAAO,aAAa,MAAM,OAAO,YAAY,CAAC;AAAA,EAChD,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,WAAO,gBAAgB,0BAA0B,oDAAoD,OAAO,IAAI;AAAA,MAC9G,gBAAgB;AAAA,IAClB,CAAC;AAAA,EACH;AACF;AAEO,SAAS,gBAAgB,aAA4D;AAC1F,MAAI;AACF,WAAO,aAAa,oBAAoB,WAAW,CAAC;AAAA,EACtD,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAErE,UAAM,iBAAiB,QAAQ,SAAS,UAAU,IAAI,SAAY;AAClE,WAAO,gBAAgB,wBAAwB,SAAS,iBAAiB,EAAE,eAAe,IAAI,MAAS;AAAA,EACzG;AACF;AAEA,eAAsB,iBACpB,cAAsB,QAAQ,IAAI,GACuB;AACzD,QAAM,WAAW,gBAAgB,WAAW;AAC5C,MAAI,CAAC,SAAS,IAAI;AAChB,WAAO;AAAA,EACT;AAEA,QAAM,aAAa,MAAM,eAAe;AACxC,MAAI,CAAC,WAAW,IAAI;AAClB,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,UAAU,MAAM,WAAW,MAAM,SAAS,eAAe,SAAS,MAAM,UAAU;AACxF,WAAO,aAAa;AAAA,MAClB;AAAA,MACA,UAAU,SAAS;AAAA,MACnB,OAAO,YAAY;AACjB,cAAM,QAAQ,MAAM;AAAA,MACtB;AAAA,IACF,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,WAAO,gBAAgB,kBAAkB,wBAAwB,SAAS,MAAM,UAAU,KAAK,OAAO,IAAI;AAAA,MACxG,gBAAgB;AAAA,IAClB,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/{middleware/__fixtures__/middleware/sequence.cjs → automation/errors.cjs}

@@ -16,32 +16,35 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var sequence_exports = {};
-__export(sequence_exports, {
-  step1: () => step1,
-  step2: () => step2,
-  step3: () => step3
+var errors_exports = {};
+__export(errors_exports, {
+  automationError: () => automationError,
+  automationOk: () => automationOk,
+  describeAutomationError: () => describeAutomationError
 });
-module.exports = __toCommonJS(sequence_exports);
-function step1(ctx) {
-  const order = ctx.get("order") ?? [];
-  order.push("step1");
-  ctx.set("order", order);
+module.exports = __toCommonJS(errors_exports);
+function automationOk(value) {
+  return { ok: true, value };
 }
-function step2(ctx) {
-  const order = ctx.get("order") ?? [];
-  order.push("step2");
-  ctx.set("order", order);
+function automationError(code, message, extra) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      ...extra?.requiredAction ? { requiredAction: extra.requiredAction } : {},
+      ...extra?.details ? { details: extra.details } : {}
+    }
+  };
 }
-function step3(ctx) {
-  const order = ctx.get("order") ?? [];
-  order.push("step3");
-  ctx.set("order", order);
+function describeAutomationError(error) {
+  const action = error.requiredAction ? ` ${error.requiredAction}` : "";
+  return `[${error.code}] ${error.message}${action}`;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  step1,
-  step2,
-  step3
+  automationError,
+  automationOk,
+  describeAutomationError
 });
-//# sourceMappingURL=sequence.cjs.map
+//# sourceMappingURL=errors.cjs.map

package/dist/automation/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/errors.ts"],"sourcesContent":["/**\n * Classified error model for the Wood automation core (Axe).\n *\n * Every failure is a structured, classified value rather than a bare thrown\n * string, so the CLI, test adapters, and future scenario runner can render\n * and branch on the same shape.\n */\n\nexport type WoodAutomationErrorCode =\n  | 'DEV_METADATA_MISSING'\n  | 'PLAYWRIGHT_UNAVAILABLE'\n  | 'CONNECT_FAILED'\n  | 'NO_ELIGIBLE_TARGETS'\n  | 'TARGET_NOT_FOUND'\n  | 'TARGET_AMBIGUOUS'\n  | 'LOCATOR_INVALID'\n  | 'ACTION_FAILED'\n  | 'UNSUPPORTED';\n\nexport interface WoodAutomationError {\n  code: WoodAutomationErrorCode;\n  message: string;\n  /** What the caller should do to recover, when known. */\n  requiredAction?: string;\n  /** Bounded structured context (candidate windowIds, selector, etc.). */\n  details?: Record<string, unknown>;\n}\n\nexport type WoodAutomationResult<T> =\n  | { ok: true; value: T }\n  | { ok: false; error: WoodAutomationError };\n\nexport function automationOk<T>(value: T): WoodAutomationResult<T> {\n  return { ok: true, value };\n}\n\nexport function automationError<T = never>(\n  code: WoodAutomationErrorCode,\n  message: string,\n  extra?: { requiredAction?: string; details?: Record<string, unknown> },\n): WoodAutomationResult<T> {\n  return {\n    ok: false,\n    error: {\n      code,\n      message,\n      ...(extra?.requiredAction ? { requiredAction: extra.requiredAction } : {}),\n      ...(extra?.details ? { details: extra.details } : {}),\n    },\n  };\n}\n\nexport function describeAutomationError(error: WoodAutomationError): string {\n  const action = error.requiredAction ? ` ${error.requiredAction}` : '';\n  return `[${error.code}] ${error.message}${action}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgCO,SAAS,aAAgB,OAAmC;AACjE,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAEO,SAAS,gBACd,MACA,SACA,OACyB;AACzB,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAI,OAAO,iBAAiB,EAAE,gBAAgB,MAAM,eAAe,IAAI,CAAC;AAAA,MACxE,GAAI,OAAO,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACrD;AAAA,EACF;AACF;AAEO,SAAS,wBAAwB,OAAoC;AAC1E,QAAM,SAAS,MAAM,iBAAiB,IAAI,MAAM,cAAc,KAAK;AACnE,SAAO,IAAI,MAAM,IAAI,KAAK,MAAM,OAAO,GAAG,MAAM;AAClD;","names":[]}

package/dist/automation/errors.d.cts

@@ -0,0 +1,31 @@
+/**
+ * Classified error model for the Wood automation core (Axe).
+ *
+ * Every failure is a structured, classified value rather than a bare thrown
+ * string, so the CLI, test adapters, and future scenario runner can render
+ * and branch on the same shape.
+ */
+type WoodAutomationErrorCode = 'DEV_METADATA_MISSING' | 'PLAYWRIGHT_UNAVAILABLE' | 'CONNECT_FAILED' | 'NO_ELIGIBLE_TARGETS' | 'TARGET_NOT_FOUND' | 'TARGET_AMBIGUOUS' | 'LOCATOR_INVALID' | 'ACTION_FAILED' | 'UNSUPPORTED';
+interface WoodAutomationError {
+    code: WoodAutomationErrorCode;
+    message: string;
+    /** What the caller should do to recover, when known. */
+    requiredAction?: string;
+    /** Bounded structured context (candidate windowIds, selector, etc.). */
+    details?: Record<string, unknown>;
+}
+type WoodAutomationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: WoodAutomationError;
+};
+declare function automationOk<T>(value: T): WoodAutomationResult<T>;
+declare function automationError<T = never>(code: WoodAutomationErrorCode, message: string, extra?: {
+    requiredAction?: string;
+    details?: Record<string, unknown>;
+}): WoodAutomationResult<T>;
+declare function describeAutomationError(error: WoodAutomationError): string;
+
+export { type WoodAutomationError, type WoodAutomationErrorCode, type WoodAutomationResult, automationError, automationOk, describeAutomationError };

package/dist/automation/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Classified error model for the Wood automation core (Axe).
+ *
+ * Every failure is a structured, classified value rather than a bare thrown
+ * string, so the CLI, test adapters, and future scenario runner can render
+ * and branch on the same shape.
+ */
+type WoodAutomationErrorCode = 'DEV_METADATA_MISSING' | 'PLAYWRIGHT_UNAVAILABLE' | 'CONNECT_FAILED' | 'NO_ELIGIBLE_TARGETS' | 'TARGET_NOT_FOUND' | 'TARGET_AMBIGUOUS' | 'LOCATOR_INVALID' | 'ACTION_FAILED' | 'UNSUPPORTED';
+interface WoodAutomationError {
+    code: WoodAutomationErrorCode;
+    message: string;
+    /** What the caller should do to recover, when known. */
+    requiredAction?: string;
+    /** Bounded structured context (candidate windowIds, selector, etc.). */
+    details?: Record<string, unknown>;
+}
+type WoodAutomationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: WoodAutomationError;
+};
+declare function automationOk<T>(value: T): WoodAutomationResult<T>;
+declare function automationError<T = never>(code: WoodAutomationErrorCode, message: string, extra?: {
+    requiredAction?: string;
+    details?: Record<string, unknown>;
+}): WoodAutomationResult<T>;
+declare function describeAutomationError(error: WoodAutomationError): string;
+
+export { type WoodAutomationError, type WoodAutomationErrorCode, type WoodAutomationResult, automationError, automationOk, describeAutomationError };

package/dist/automation/errors.js

@@ -0,0 +1,24 @@
+function automationOk(value) {
+  return { ok: true, value };
+}
+function automationError(code, message, extra) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      ...extra?.requiredAction ? { requiredAction: extra.requiredAction } : {},
+      ...extra?.details ? { details: extra.details } : {}
+    }
+  };
+}
+function describeAutomationError(error) {
+  const action = error.requiredAction ? ` ${error.requiredAction}` : "";
+  return `[${error.code}] ${error.message}${action}`;
+}
+export {
+  automationError,
+  automationOk,
+  describeAutomationError
+};
+//# sourceMappingURL=errors.js.map

package/dist/automation/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/automation/errors.ts"],"sourcesContent":["/**\n * Classified error model for the Wood automation core (Axe).\n *\n * Every failure is a structured, classified value rather than a bare thrown\n * string, so the CLI, test adapters, and future scenario runner can render\n * and branch on the same shape.\n */\n\nexport type WoodAutomationErrorCode =\n  | 'DEV_METADATA_MISSING'\n  | 'PLAYWRIGHT_UNAVAILABLE'\n  | 'CONNECT_FAILED'\n  | 'NO_ELIGIBLE_TARGETS'\n  | 'TARGET_NOT_FOUND'\n  | 'TARGET_AMBIGUOUS'\n  | 'LOCATOR_INVALID'\n  | 'ACTION_FAILED'\n  | 'UNSUPPORTED';\n\nexport interface WoodAutomationError {\n  code: WoodAutomationErrorCode;\n  message: string;\n  /** What the caller should do to recover, when known. */\n  requiredAction?: string;\n  /** Bounded structured context (candidate windowIds, selector, etc.). */\n  details?: Record<string, unknown>;\n}\n\nexport type WoodAutomationResult<T> =\n  | { ok: true; value: T }\n  | { ok: false; error: WoodAutomationError };\n\nexport function automationOk<T>(value: T): WoodAutomationResult<T> {\n  return { ok: true, value };\n}\n\nexport function automationError<T = never>(\n  code: WoodAutomationErrorCode,\n  message: string,\n  extra?: { requiredAction?: string; details?: Record<string, unknown> },\n): WoodAutomationResult<T> {\n  return {\n    ok: false,\n    error: {\n      code,\n      message,\n      ...(extra?.requiredAction ? { requiredAction: extra.requiredAction } : {}),\n      ...(extra?.details ? { details: extra.details } : {}),\n    },\n  };\n}\n\nexport function describeAutomationError(error: WoodAutomationError): string {\n  const action = error.requiredAction ? ` ${error.requiredAction}` : '';\n  return `[${error.code}] ${error.message}${action}`;\n}\n"],"mappings":"AAgCO,SAAS,aAAgB,OAAmC;AACjE,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAEO,SAAS,gBACd,MACA,SACA,OACyB;AACzB,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAI,OAAO,iBAAiB,EAAE,gBAAgB,MAAM,eAAe,IAAI,CAAC;AAAA,MACxE,GAAI,OAAO,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACrD;AAAA,EACF;AACF;AAEO,SAAS,wBAAwB,OAAoC;AAC1E,QAAM,SAAS,MAAM,iBAAiB,IAAI,MAAM,cAAc,KAAK;AACnE,SAAO,IAAI,MAAM,IAAI,KAAK,MAAM,OAAO,GAAG,MAAM;AAClD;","names":[]}