@agentrhq/webcmd 0.2.2 → 0.2.4

package/clis/zepto/product.js

@@ -0,0 +1,52 @@
+import { EmptyResultError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, SITE, ZEPTO_NAV_OPTIONS, cleanText, normalizeProductRow, resolveProductInput, safeGoto } from './utils.js';
+
+function productEvaluate(productId) {
+  return `
+    (() => {
+      const productId = ${JSON.stringify(productId)};
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const text = clean(document.body?.innerText || document.body?.textContent || '');
+      const prices = Array.from(document.querySelectorAll('span,div'))
+        .map((node) => clean(node.textContent))
+        .filter((value) => /^₹\\s*\\d/i.test(value));
+      const title = clean(document.querySelector('h1')?.textContent)
+        || text.split('\\n').map(clean).find((line) => /[A-Za-z]/.test(line) && !/Delivery|Search|Login|Cart|Home|₹|Add to Cart/i.test(line))
+        || '';
+      return {
+        product_id: productId,
+        title,
+        brand: clean(Array.from(document.querySelectorAll('div,span')).find((node) => clean(node.textContent) === 'Brand')?.nextElementSibling?.textContent),
+        pack_size: text.match(/\\b\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)\\b/i)?.[0] || '',
+        price: prices[0] || '',
+        mrp: prices[1] || '',
+        availability: /out of stock|unavailable/i.test(text) ? 'Out of stock' : '',
+        url: location.href,
+      };
+    })()
+  `;
+}
+
+cli({
+  site: SITE,
+  name: 'product',
+  access: 'read',
+  description: 'Read Zepto product details',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'product', required: true, positional: true, help: 'Product URL from Zepto search results' },
+  ],
+  columns: ['product_id', 'title', 'brand', 'pack_size', 'price', 'mrp', 'availability', 'url'],
+  func: async (page, kwargs) => {
+    const product = resolveProductInput(kwargs.product);
+    await safeGoto(page, product.url, 'zepto product', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(2);
+    const row = normalizeProductRow(await page.evaluate(productEvaluate(product.productId)), 0);
+    if (!row.product_id || !cleanText(row.title)) throw new EmptyResultError('zepto product', `No product details found for ${product.productId}.`);
+    return [row];
+  },
+});

package/clis/zepto/search.js

@@ -0,0 +1,30 @@
+import { AuthRequiredError, EmptyResultError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, SITE, ZEPTO_NAV_OPTIONS, buildSearchUrl, normalizeProductRow, parseLimitArg, productCardsEvaluate, safeGoto } from './utils.js';
+
+cli({
+  site: SITE,
+  name: 'search',
+  access: 'read',
+  description: 'Search Zepto products',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'query', required: true, positional: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum products to return (max 50)' },
+  ],
+  columns: ['rank', 'product_id', 'title', 'brand', 'pack_size', 'price', 'mrp', 'availability', 'url'],
+  func: async (page, kwargs) => {
+    const url = buildSearchUrl(kwargs.query);
+    const limit = parseLimitArg(kwargs.limit, 20, 50);
+    await safeGoto(page, url, 'zepto search', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(2);
+    const result = await page.evaluate(productCardsEvaluate(limit));
+    if (result?.authRequired) throw new AuthRequiredError(DOMAIN, 'Log into Zepto in the Webcmd browser session to search products.');
+    const rows = (result?.rows || []).map(normalizeProductRow).filter((row) => row.product_id && row.title);
+    if (!rows.length) throw new EmptyResultError('zepto search', `No Zepto products matched "${kwargs.query}".`);
+    return rows;
+  },
+});

package/clis/zepto/utils.js

@@ -0,0 +1,228 @@
+import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+
+export const SITE = 'zepto';
+export const DOMAIN = 'www.zepto.com';
+export const HOME_URL = 'https://www.zepto.com';
+export const MAX_LIMIT = 50;
+export const ZEPTO_NAV_OPTIONS = { waitUntil: 'none', settleMs: 1500 };
+
+export function cleanText(value) {
+  return typeof value === 'string'
+    ? value.replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim()
+    : '';
+}
+
+export function parseMoney(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value > 999 ? value / 100 : value;
+  const match = cleanText(String(value ?? '')).replace(/,/g, '').match(/(\d+(?:\.\d+)?)/);
+  return match ? Number(match[1]) : null;
+}
+
+export function parseLimitArg(raw, fallback, max = MAX_LIMIT) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const num = Number(raw);
+  if (!Number.isInteger(num) || num < 1 || num > max) {
+    throw new ArgumentError(`--limit must be an integer between 1 and ${max} (got ${raw})`);
+  }
+  return num;
+}
+
+export function parseQuantityArg(raw, fallback, max = 12) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const num = Number(raw);
+  if (!Number.isInteger(num) || num < 1 || num > max) {
+    throw new ArgumentError(`--quantity must be an integer between 1 and ${max} (got ${raw})`);
+  }
+  return num;
+}
+
+export function buildSearchUrl(query) {
+  const normalized = cleanText(query);
+  if (!normalized) throw new ArgumentError('zepto search query cannot be empty');
+  return `${HOME_URL}/search?query=${encodeURIComponent(normalized)}`;
+}
+
+export function toZeptoUrl(value) {
+  const text = cleanText(value);
+  if (!text) return '';
+  try {
+    const url = new URL(text.startsWith('http') ? text : text.startsWith('/') ? text : `/${text}`, HOME_URL);
+    if (url.hostname !== DOMAIN && url.hostname !== 'zepto.com') throw new Error('not zepto');
+    url.hostname = DOMAIN;
+    url.hash = '';
+    return url.toString();
+  } catch {
+    return '';
+  }
+}
+
+export function resolveProductInput(input) {
+  const text = cleanText(input);
+  if (!text) throw new ArgumentError('zepto product requires a product URL');
+  const url = toZeptoUrl(text);
+  const match = url && new URL(url).pathname.match(/\/pvid\/([0-9a-f-]{36})(?:\/|$)/i);
+  if (!match) throw new ArgumentError('zepto product expects a Zepto /pn/.../pvid/<id> URL from search results');
+  return { productId: match[1], url };
+}
+
+export function normalizeProductRow(raw, rank) {
+  const url = toZeptoUrl(raw.url || raw.href || '');
+  const productId = cleanText(raw.product_id || raw.productId || raw.id || url.match(/\/pvid\/([0-9a-f-]{36})/i)?.[1] || '');
+  return {
+    rank: rank + 1,
+    product_id: productId,
+    title: cleanText(raw.title || raw.name),
+    brand: cleanText(raw.brand),
+    pack_size: cleanText(raw.pack_size || raw.packSize || raw.size),
+    price: parseMoney(raw.price),
+    mrp: parseMoney(raw.mrp || raw.original_price || raw.originalPrice),
+    availability: cleanText(raw.availability || raw.stock),
+    url,
+  };
+}
+
+function parsePersisted(raw) {
+  try {
+    const outer = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const value = typeof outer?.value === 'string' ? JSON.parse(outer.value) : outer;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+export function normalizeLocationState(raw = {}) {
+  const rawAddressText = cleanText(raw.addressText);
+  const addressText = /^select location$/i.test(rawAddressText) ? '' : rawAddressText;
+  const rawLabel = addressText.match(/^(Home|Work|Other)\b/i)?.[1] || '';
+  const label = rawLabel ? rawLabel[0].toUpperCase() + rawLabel.slice(1).toLowerCase() : '';
+  const publicAddressText = addressText
+    .replace(/^(Home|Work|Other)\s*[:-]?\s*/i, '')
+    .replace(/\b(?:house\s*number|floor|flat|apartment|door|building)\b\s*[-:#]?\s*[^,•\n]*/gi, '');
+  const parts = publicAddressText.split(/[,•\n]/).map(cleanText).filter(Boolean);
+  const position = raw.userPosition || raw.userGpsCoords || {};
+  const pincode = cleanText(raw.pincode || raw.pin || addressText.match(/\b\d{6}\b/)?.[0]);
+  const cityPart = parts.length > 1 ? (parts[parts.length - 1].toLowerCase() === 'india' && parts.length > 2 ? parts[parts.length - 2] : parts[parts.length - 1]) : cleanText(raw.city);
+  return {
+    selected: Boolean(addressText || position.latitude || position.longitude || raw.pincode),
+    label,
+    area: label ? '' : parts[0] || '',
+    city: cleanText(cityPart.replace(/\b\d{6}\b/g, '')),
+    pincode,
+    hasCoordinates: Boolean(position.latitude || position.longitude),
+    source: 'browser',
+  };
+}
+
+export async function safeGoto(page, url, label, options) {
+  await page.goto(url, options || ZEPTO_NAV_OPTIONS).catch((error) => {
+    const message = error?.message || String(error);
+    if (/net::ERR_ABORTED|Browser navigate command timed out/i.test(message)) return;
+    throw new CommandExecutionError(`${label} navigation failed: ${error?.message || error}`);
+  });
+}
+
+export function productCardsEvaluate(limit) {
+  return `
+    (() => {
+      const limit = ${Number(limit) || 20};
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const bodyText = clean(document.body?.innerText || document.body?.textContent || '');
+      if (/please login to continue searching|please login/i.test(bodyText) && location.pathname.includes('/search')) {
+        return { authRequired: true, rows: [], href: location.href };
+      }
+      const rows = [];
+      const seen = new Set();
+      const anchors = Array.from(document.querySelectorAll('a[href*="/pn/"][href*="/pvid/"]'));
+      for (const anchor of anchors) {
+        const href = anchor.href || anchor.getAttribute('href') || '';
+        const productId = href.match(/\\/pvid\\/([0-9a-f-]{36})/i)?.[1] || '';
+        if (!productId || seen.has(productId)) continue;
+        let root = anchor;
+        for (let i = 0; i < 6 && root?.parentElement; i += 1) {
+          const rootText = clean(root.innerText || root.textContent || '');
+          if (/₹|ADD|Add to Cart/i.test(rootText)) break;
+          root = root.parentElement;
+        }
+        const texts = Array.from(root.querySelectorAll('*'))
+          .filter((node) => node.children.length === 0)
+          .map((node) => clean(node.textContent))
+          .filter(Boolean);
+        const joined = texts.join(' ');
+        const prices = texts.filter((text) => /₹/.test(text));
+        const title = texts.find((text) => /[A-Za-z]/.test(text) && !/add|cart|off|bestseller|₹|\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)/i.test(text)) || clean(anchor.textContent);
+        if (!title) continue;
+        seen.add(productId);
+        rows.push({
+          product_id: productId,
+          title,
+          pack_size: texts.find((text) => /\\b\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)\\b/i.test(text)) || '',
+          price: prices[0] || '',
+          mrp: prices[1] || '',
+          availability: /out of stock|unavailable/i.test(joined) ? 'Out of stock' : '',
+          url: href,
+        });
+        if (rows.length >= limit) break;
+      }
+      return { rows, href: location.href };
+    })()
+  `;
+}
+
+export const CART_EVALUATE = `
+  (() => {
+    const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+    const parse = (key) => {
+      try { return JSON.parse(localStorage.getItem(key) || 'null'); } catch { return null; }
+    };
+    const cart = parse('cart')?.state || {};
+    const content = cart.cartContent || {};
+    const rows = Object.entries(content).map(([id, item]) => {
+      const product = item?.productVariant || item?.product || item || {};
+      const productId = clean(product.id || product.productVariantId || item?.productVariantId || id);
+      const price = Number(item?.superSaverSellingPrice ?? item?.discountedSellingPrice ?? item?.sellingPrice ?? product.price ?? product.discountedSellingPrice ?? product.sellingPrice);
+      const mrp = Number(item?.mrp ?? product.mrp ?? product.mrpPrice);
+      return {
+        product_id: productId,
+        title: clean(product.name || product.productName || item?.title || item?.name),
+        pack_size: clean(product.formattedPacksize || product.packsize || product.unitOfMeasure || item?.quantityText),
+        quantity: Number(item?.quantity || item?.qty || 0),
+        price: Number.isFinite(price) ? (price > 999 ? price / 100 : price) : null,
+        mrp: Number.isFinite(mrp) ? (mrp > 999 ? mrp / 100 : mrp) : null,
+        availability: clean(product.availability || ''),
+      };
+    }).filter((row) => row.product_id && row.title && row.quantity);
+    return { rows, href: location.href, cartId: cart.cartId || '' };
+  })()
+`;
+
+export function normalizeCartRows(result) {
+  return (result?.rows || []).map((row, index) => ({
+    rank: index + 1,
+    product_id: cleanText(row.product_id),
+    title: cleanText(row.title),
+    pack_size: cleanText(row.pack_size),
+    quantity: Number(row.quantity || 0),
+    price: parseMoney(row.price),
+    mrp: parseMoney(row.mrp),
+    availability: cleanText(row.availability),
+  })).filter((row) => row.product_id && row.title && row.quantity);
+}
+
+export function readLocationEvaluate() {
+  return `
+    (() => {
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const parse = (key) => {
+        try { return JSON.parse(localStorage.getItem(key) || 'null'); } catch { return null; }
+      };
+      const persisted = parse('user-position');
+      const state = typeof persisted?.value === 'string' ? JSON.parse(persisted.value)?.state : persisted?.state;
+      return {
+        addressText: clean(document.querySelector('[data-testid="user-address"]')?.textContent || ''),
+        userPosition: state?.userPosition || null,
+        userGpsCoords: state?.userGpsCoords || null,
+      };
+    })()
+  `;
+}

package/clis/zepto/zepto.test.js

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
+import { ArgumentError, AuthRequiredError } from '@agentrhq/webcmd/errors';
+import { getRegistry } from '@agentrhq/webcmd/registry';
+import './auth.js';
+import './location.js';
+import './search.js';
+import './product.js';
+import './add-to-cart.js';
+import './cart.js';
+import './checkout.js';
+import './place-order.js';
+import {
+  CART_EVALUATE,
+  buildSearchUrl,
+  normalizeLocationState,
+  normalizeProductRow,
+  parseLimitArg,
+  parseQuantityArg,
+  productCardsEvaluate,
+  resolveProductInput,
+  safeGoto,
+} from './utils.js';
+
+describe('zepto helpers', () => {
+  it('builds search URLs and validates numeric args', () => {
+    expect(buildSearchUrl('amul milk')).toBe('https://www.zepto.com/search?query=amul%20milk');
+    expect(() => buildSearchUrl('   ')).toThrow(ArgumentError);
+    expect(() => parseLimitArg(0, 20, 50)).toThrow(ArgumentError);
+    expect(() => parseLimitArg(51, 20, 50)).toThrow(ArgumentError);
+    expect(() => parseQuantityArg(0, 1, 12)).toThrow(ArgumentError);
+  });
+
+  it('parses product pvids and URLs', () => {
+    expect(resolveProductInput('https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089')).toMatchObject({
+      productId: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      url: 'https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    });
+    expect(() => resolveProductInput('5f54bb83-f3e0-4d8d-89b0-6339f3312089')).toThrow(ArgumentError);
+  });
+
+  it('normalizes product rows', () => {
+    expect(normalizeProductRow({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      pack_size: '1 pack (2 kg)',
+      price: '₹179',
+      mrp: '₹260',
+      url: '/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    }, 0)).toMatchObject({
+      rank: 1,
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      price: 179,
+      mrp: 260,
+      url: 'https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    });
+  });
+
+  it('extracts rendered product cards', () => {
+    const dom = new JSDOM(`
+      <a href="/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089">
+        <div>
+          <button>ADD</button>
+          <span>₹ 179</span><span>₹ 260</span>
+          <span>Rin Matic Top Load Detergent Liquid | Pouch</span>
+          <span>1 pack (2 kg)</span>
+        </div>
+      </a>
+    `, { runScripts: 'outside-only', url: 'https://www.zepto.com/search?query=rin' });
+
+    const result = dom.window.eval(productCardsEvaluate(5));
+
+    expect(result.rows[0]).toMatchObject({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      price: '₹ 179',
+      mrp: '₹ 260',
+    });
+  });
+
+  it('normalizes selected location without leaking exact coordinates', () => {
+    expect(normalizeLocationState({
+      addressText: 'Home: HSR Layout, Bengaluru',
+      userPosition: { latitude: 12.911, longitude: 77.629 },
+    })).toEqual({
+      selected: true,
+      label: 'Home',
+      area: '',
+      city: 'Bengaluru',
+      pincode: '',
+      hasCoordinates: true,
+      source: 'browser',
+    });
+  });
+
+  it('redacts exact house and floor details from location output', () => {
+    expect(normalizeLocationState({
+      addressText: 'home - House number - 5, Floor - 5th, HSR Layout, Bengaluru, India',
+      userPosition: { latitude: 12.911, longitude: 77.629 },
+    })).toEqual({
+      selected: true,
+      label: 'Home',
+      area: '',
+      city: 'Bengaluru',
+      pincode: '',
+      hasCoordinates: true,
+      source: 'browser',
+    });
+  });
+
+  it('does not treat the Select Location placeholder as selected', () => {
+    expect(normalizeLocationState({ addressText: 'Select Location' })).toEqual({
+      selected: false,
+      label: '',
+      area: '',
+      city: '',
+      pincode: '',
+      hasCoordinates: false,
+      source: 'browser',
+    });
+  });
+
+  it('tolerates Zepto SPA navigation aborts but keeps real navigation failures', async () => {
+    await expect(safeGoto({
+      goto: async () => { throw new Error('page.goto: net::ERR_ABORTED at https://www.zepto.com/'); },
+    }, 'https://www.zepto.com/', 'zepto cart')).resolves.toBeUndefined();
+
+    await expect(safeGoto({
+      goto: async () => { throw new Error('page.goto: net::ERR_NAME_NOT_RESOLVED'); },
+    }, 'https://www.zepto.com/', 'zepto cart')).rejects.toThrow('zepto cart navigation failed');
+  });
+
+  it('extracts cart items from Zepto cart storage without recommendations', () => {
+    const cart = {
+      state: {
+        cartContent: {
+          '5f54bb83-f3e0-4d8d-89b0-6339f3312089': {
+            quantity: 2,
+            productVariant: {
+              id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+              name: 'Rin Matic Top Load Detergent Liquid | Pouch',
+              formattedPacksize: '1 pack (2 kg)',
+              price: 17900,
+              mrp: 26000,
+            },
+          },
+        },
+      },
+    };
+    const dom = new JSDOM('', { runScripts: 'outside-only', url: 'https://www.zepto.com/' });
+    dom.window.localStorage.setItem('cart', JSON.stringify(cart));
+
+    const result = dom.window.eval(CART_EVALUATE);
+
+    expect(result.rows).toEqual([expect.objectContaining({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      quantity: 2,
+      price: 179,
+    })]);
+  });
+
+  it('extracts top-level Zepto cart item fields', () => {
+    const cart = {
+      state: {
+        cartContent: {
+          'ba77f9b3-0525-4ce8-bc4b-a2480419b780': {
+            quantity: 1,
+            title: 'Godrej Jersey Toned Fresh Milk | Pouch',
+            productVariantId: 'ba77f9b3-0525-4ce8-bc4b-a2480419b780',
+            quantityText: '1 pack (490 ml or 500 ml)',
+            superSaverSellingPrice: 2600,
+            mrp: 2700,
+          },
+        },
+      },
+    };
+    const dom = new JSDOM('', { runScripts: 'outside-only', url: 'https://www.zepto.com/' });
+    dom.window.localStorage.setItem('cart', JSON.stringify(cart));
+
+    const result = dom.window.eval(CART_EVALUATE);
+
+    expect(result.rows).toEqual([expect.objectContaining({
+      product_id: 'ba77f9b3-0525-4ce8-bc4b-a2480419b780',
+      title: 'Godrej Jersey Toned Fresh Milk | Pouch',
+      pack_size: '1 pack (490 ml or 500 ml)',
+      quantity: 1,
+      price: 26,
+      mrp: 27,
+    })]);
+  });
+});
+
+describe('zepto registry shape', () => {
+  it('registers the buying-path commands', () => {
+    for (const name of ['login', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
+      expect(getRegistry().get(`zepto/${name}`)).toBeDefined();
+    }
+  });
+
+  it('marks only cart-changing commands as write', () => {
+    expect(getRegistry().get('zepto/location').access).toBe('read');
+    expect(getRegistry().get('zepto/search').access).toBe('read');
+    expect(getRegistry().get('zepto/product').access).toBe('read');
+    expect(getRegistry().get('zepto/cart').access).toBe('read');
+    expect(getRegistry().get('zepto/login').access).toBe('write');
+    expect(getRegistry().get('zepto/add-to-cart').access).toBe('write');
+    expect(getRegistry().get('zepto/checkout').access).toBe('write');
+    expect(getRegistry().get('zepto/place-order').access).toBe('write');
+  });
+
+  it('lets commands own Zepto navigation instead of framework pre-navigation', () => {
+    for (const name of ['login', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
+      expect(getRegistry().get(`zepto/${name}`).navigateBefore).toBe(false);
+    }
+  });
+});
+
+describe('zepto command behavior', () => {
+  it('search reports auth-required when Zepto blocks web search', async () => {
+    const command = getRegistry().get('zepto/search');
+    const calls = [];
+    const fakePage = {
+      goto: async (...args) => { calls.push(args); },
+      wait: async () => {},
+      evaluate: async () => ({ authRequired: true, rows: [] }),
+    };
+
+    await expect(command.func(fakePage, { query: 'milk' })).rejects.toThrow(AuthRequiredError);
+    expect(calls[0]).toEqual(['https://www.zepto.com/search?query=milk', { waitUntil: 'none', settleMs: 1500 }]);
+  });
+
+  it('keeps place-order no-op unless --confirm is passed', async () => {
+    const command = getRegistry().get('zepto/place-order');
+    const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+    await expect(command.func(fakePage, {})).resolves.toMatchObject([{ status: 'no-op', confirmed: false }]);
+  });
+});

package/dist/src/browser/daemon-lifecycle.d.ts

@@ -23,8 +23,10 @@ export declare function waitForDaemonStatus(timeoutMs: number): Promise<DaemonSt
 export declare const daemonLifecycleHooks: {
     requestDaemonShutdown: typeof requestDaemonShutdown;
     spawnDaemonProcess: typeof spawnDaemonProcess;
+    signalDaemonProcessTree: typeof signalDaemonProcessTree;
     waitForDaemonStop: typeof waitForDaemonStop;
 };
+export declare function signalDaemonProcessTree(pid: number, signal: NodeJS.Signals): boolean;
 export declare function restartDaemon(opts?: {
     stopTimeoutMs?: number;
     startTimeoutMs?: number;

package/dist/src/browser/daemon-lifecycle.js

@@ -53,8 +53,31 @@ export async function waitForDaemonStatus(timeoutMs) {
 export const daemonLifecycleHooks = {
     requestDaemonShutdown,
     spawnDaemonProcess,
+    signalDaemonProcessTree,
     waitForDaemonStop,
 };
+export function signalDaemonProcessTree(pid, signal) {
+    let signaled = false;
+    if (process.platform !== 'win32') {
+        try {
+            process.kill(-pid, signal);
+            signaled = true;
+        }
+        catch {
+            // Fall back to the daemon PID below.
+        }
+    }
+    if (!signaled) {
+        try {
+            process.kill(pid, signal);
+            signaled = true;
+        }
+        catch {
+            // The process may have already exited; the caller polls the daemon port.
+        }
+    }
+    return signaled;
+}
 export async function restartDaemon(opts = {}) {
     const previousStatus = await fetchDaemonStatus();
     let stopped = previousStatus === null;
@@ -91,13 +114,12 @@ export async function ensureBrowserBridgeReady(opts = {}) {
         if (!portReleased) {
             const stalePid = health.status?.pid;
             if (typeof stalePid === 'number' && Number.isInteger(stalePid) && stalePid > 0) {
-                try {
-                    process.kill(stalePid, 'SIGKILL');
-                }
-                catch {
-                    // EPERM / ESRCH are both resolved by polling the fixed daemon port.
+                daemonLifecycleHooks.signalDaemonProcessTree(stalePid, 'SIGTERM');
+                portReleased = await daemonLifecycleHooks.waitForDaemonStop(1000);
+                if (!portReleased) {
+                    daemonLifecycleHooks.signalDaemonProcessTree(stalePid, 'SIGKILL');
+                    portReleased = await daemonLifecycleHooks.waitForDaemonStop(2000);
                 }
-                portReleased = await daemonLifecycleHooks.waitForDaemonStop(2000);
             }
         }
         if (!portReleased) {

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -3,6 +3,7 @@ import { launchPersistentContext as cloakLaunchPersistentContext } from 'cloakbr
 import type { BrowserSurface, SiteSessionMode } from '../../protocol.js';
 import { CloakNetworkCapture } from './network.js';
 export type LaunchPersistentContext = typeof cloakLaunchPersistentContext;
+export type RecoverLockedProfile = (userDataDir: string) => Promise<boolean>;
 export interface SessionKeyInput {
     profileId?: string;
     session?: string;
@@ -33,13 +34,16 @@ export interface CloakTabInfo {
 export interface CloakSessionManagerOptions {
     baseDir?: string;
     launchPersistentContext?: LaunchPersistentContext;
+    recoverLockedProfile?: RecoverLockedProfile;
 }
 export declare function resolveLeaseKey(input: SessionKeyInput): string;
 export declare class CloakSessionManager {
     private readonly opts;
     readonly networkCapture: CloakNetworkCapture;
     private readonly launchPersistentContext;
+    private readonly recoverLockedProfile;
     private readonly profiles;
+    private readonly profileLaunches;
     constructor(opts?: CloakSessionManagerOptions);
     profileStatuses(): {
         contextId: string;
@@ -72,6 +76,7 @@ export declare class CloakSessionManager {
     release(input: SessionKeyInput): Promise<void>;
     shutdown(): Promise<void>;
     private getProfileRuntime;
+    private launchProfileRuntime;
     private openEntries;
     private findEntryByPageId;
     private refreshIdleTimer;