@sous-io/sous 0.1.0

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/eslint.config.mjs

@@ -0,0 +1,56 @@
+/**
+ * ESLint flat config for automation scripts.
+ *
+ * Scope: mechanical correctness only — unused vars, missing awaits, undeclared
+ * globals, obvious foot-guns. The *conventions* (decomposition, doc-blocks,
+ * destructuring, no self-validation, logger usage) are enforced by the skill
+ * instructions and review, NOT by lint rules; do not try to encode them here.
+ *
+ * Usage (from a project that has eslint installed):
+ *   npx eslint --config <this-file> <scriptsDir> <examplesDir>
+ *
+ * Requires: eslint >= 9 (flat config). No plugins needed.
+ */
+
+export default [
+  {
+    files: ['**/*.mjs'],
+    // Templates are LiquidJS, not valid JS until compiled by sous.
+    ignores: ['**/*.tpl.mjs'],
+    languageOptions: {
+      ecmaVersion: 2023,
+      sourceType: 'module',
+      globals: {
+        // Node globals scripts and the harness rely on.
+        process: 'readonly',
+        console: 'readonly',
+        Buffer: 'readonly',
+        URL: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        __dirname: 'readonly',
+      },
+    },
+    rules: {
+      // Catch real bugs.
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-undef': 'error',
+      'no-constant-condition': ['error', { checkLoops: false }],
+      'no-unreachable': 'error',
+      'no-dupe-keys': 'error',
+      'no-self-assign': 'error',
+      'require-await': 'warn',
+      'no-return-await': 'warn',
+
+      // Async foot-guns: a forgotten await on a Playwright call is the most
+      // common scripting mistake.
+      'no-async-promise-executor': 'error',
+      'no-await-in-loop': 'off', // sequential page steps legitimately await in loops
+
+      // Style nudges that aid debugging without dictating structure.
+      'prefer-const': 'warn',
+      'no-var': 'error',
+      eqeqeq: ['warn', 'smart'],
+    },
+  },
+];

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/harness.mjs

@@ -0,0 +1,169 @@
+/**
+ * Execution Harness
+ *
+ * Launches headless Playwright with cookies extracted from a Chrome profile.
+ * Handles auth detection, structured output, and error reporting.
+ */
+
+import { chromium } from 'playwright';
+import { buildStorageState } from './chrome-state.mjs';
+import { createLogger } from './logger.mjs';
+import { createUtils } from './utils.mjs';
+import { createDebug } from './debug.mjs';
+import { resolveParams, ParamError } from './params.mjs';
+
+export class AuthError extends Error {
+  constructor(message, { url, indicators } = {}) {
+    super(message);
+    this.name = 'AuthError';
+    this.url = url;
+    this.indicators = indicators || [];
+  }
+}
+
+/**
+ * Run an automation script with Chrome session state injected.
+ *
+ * @param {object} script - The script module (must export `execute` and `meta`)
+ * @param {object} params - Explicit parameters (e.g. from CLI)
+ * @param {object} options - Harness options
+ * @param {string} options.profileName - Chrome profile name (default: 'Default')
+ * @param {string[]} options.domains - Limit cookie extraction to these domain substrings
+ * @param {number} options.timeout - Overall timeout in ms (default: 60000)
+ * @param {object} options.settings - Compiled project settings (ctx.settings)
+ */
+export async function runScript(script, params = {}, options = {}) {
+  const {
+    profileName = 'Default',
+    domains = null,
+    timeout = 60000,
+    settings = {},
+  } = options;
+
+  const meta = script.meta || {};
+  const sessionLog = createLogger('session');
+
+  let browser = null;
+  let debug = null;
+
+  try {
+    // Resolve + validate params BEFORE launching anything. A script never
+    // validates its own input; a ParamError here surfaces before browser work.
+    const resolvedParams = resolveParams(meta, params, settings);
+
+    sessionLog.info(`Extracting cookies from Chrome profile: "${profileName}"`);
+    const storageState = await buildStorageState(profileName, domains);
+    sessionLog.info(`Extracted ${storageState.cookies.length} cookies`);
+    if (domains) {
+      sessionLog.info(`Filtered to domains: ${domains.join(', ')}`);
+    }
+
+    sessionLog.info('Launching headless browser...');
+    browser = await chromium.launch({
+      headless: true,
+      args: [
+        '--disable-blink-features=AutomationControlled',
+        '--no-first-run',
+        '--no-default-browser-check',
+      ],
+    });
+
+    const context = await browser.newContext({
+      storageState,
+      viewport: { width: 1920, height: 1080 },
+    });
+
+    const page = await context.newPage();
+    sessionLog.info('Browser ready\n');
+
+    const logger = createLogger(meta.name || 'script');
+    debug = createDebug(page, logger, { runId: meta.name || 'script' });
+
+    const ctx = {
+      page,
+      context,
+      browser,
+      params: resolvedParams,
+      settings,
+      timeout,
+      logger,
+      utils: createUtils(page, logger),
+      debug,
+
+      async checkAuth() {
+        const currentUrl = page.url();
+        const authIndicators = [
+          '/login', '/auth/', '/sso', 'signin', 'multipass',
+          'accounts.google.com', 'login.microsoftonline.com',
+        ];
+
+        for (const indicator of authIndicators) {
+          if (currentUrl.includes(indicator)) {
+            throw new AuthError(
+              `Authentication required. The browser was redirected to a login page.\n` +
+              `Current URL: ${currentUrl}\n\n` +
+              `Action needed: Log in to the target site in your Chrome browser ` +
+              `(profile: "${profileName}"), then retry this script.`,
+              { url: currentUrl, indicators: [indicator] }
+            );
+          }
+        }
+      },
+
+      async runChild(childScript, childParams = {}) {
+        const childMeta = childScript.meta || {};
+        const childResolved = resolveParams(childMeta, childParams, settings);
+        const childLogger = createLogger(childMeta.name || 'child');
+        const childCtx = {
+          ...ctx,
+          params: childResolved,
+          logger: childLogger,
+          utils: createUtils(page, childLogger),
+          debug: createDebug(page, childLogger, { runId: childMeta.name || 'child' }),
+        };
+        return childScript.execute(childCtx);
+      },
+    };
+
+    const result = await Promise.race([
+      script.execute(ctx),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Script timed out after ${timeout}ms`)), timeout)
+      ),
+    ]);
+
+    return { success: true, data: result };
+  } catch (error) {
+    if (error instanceof ParamError) {
+      return { success: false, error: 'params', message: error.message };
+    }
+
+    if (error instanceof AuthError) {
+      return {
+        success: false,
+        error: 'auth',
+        message: error.message,
+        url: error.url,
+        indicators: error.indicators,
+      };
+    }
+
+    // Auto-capture page state on an unexpected script failure — the single most
+    // useful debugging artifact. Done before `finally` closes the browser.
+    let debugDump = null;
+    if (debug) {
+      const snapshot = await debug.dump('failure').catch(() => null);
+      debugDump = snapshot?.dir || null;
+    }
+
+    return {
+      success: false,
+      error: 'script',
+      message: error.message,
+      stack: error.stack,
+      debugDir: debugDump,
+    };
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/keyring.mjs

@@ -0,0 +1,59 @@
+/**
+ * Read Chrome's encryption password from the GNOME keyring via D-Bus Secret Service API.
+ * Pure JS — no Python, no native dependencies beyond dbus-next.
+ */
+
+import dbus from 'dbus-next';
+
+const SECRET_SERVICE_IFACE = 'org.freedesktop.Secret.Service';
+const SECRET_SERVICE_PATH = '/org/freedesktop/secrets';
+const SECRET_SERVICE_BUS = 'org.freedesktop.secrets';
+
+/**
+ * Reads the Chrome Safe Storage password from gnome-keyring.
+ * Returns a Buffer containing the password bytes.
+ */
+export async function getChromeSafeStoragePassword() {
+  const bus = dbus.sessionBus();
+
+  try {
+    const serviceProxy = await bus.getProxyObject(SECRET_SERVICE_BUS, SECRET_SERVICE_PATH);
+    const service = serviceProxy.getInterface(SECRET_SERVICE_IFACE);
+
+    // Open a plain-text session (no encryption over D-Bus — it's local)
+    const sessionResult = await service.OpenSession('plain', new dbus.Variant('s', ''));
+    const sessionPath = sessionResult[1];
+
+    // Search for the Chrome Safe Storage item
+    // SearchItems takes a{ss} — plain string dict, not Variants
+    const searchResult = await service.SearchItems({
+      'application': 'chrome',
+      'xdg:schema': 'chrome_libsecret_os_crypt_password_v2',
+    });
+
+    const unlocked = searchResult[0];
+    if (!unlocked || unlocked.length === 0) {
+      throw new Error(
+        'Chrome Safe Storage key not found in keyring. ' +
+        'Make sure Chrome has been launched at least once and the keyring is unlocked.'
+      );
+    }
+
+    const itemPath = unlocked[0];
+
+    // Get the secret
+    const secretsResult = await service.GetSecrets([itemPath], sessionPath);
+
+    // secretsResult is a dict: {itemPath: (session_path, params_bytes, value_bytes, content_type)}
+    const secret = secretsResult[itemPath];
+    if (!secret) {
+      throw new Error('Failed to retrieve secret from keyring');
+    }
+
+    // secret is [session_path, params_bytes, value_bytes, content_type_string]
+    const valueBytes = secret[2];
+    return Buffer.from(valueBytes);
+  } finally {
+    bus.disconnect();
+  }
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/logger.mjs

@@ -0,0 +1,25 @@
+/**
+ * Logger
+ *
+ * Plain prefixed-line logger for automation scripts. Output format:
+ *   [script-name] message
+ *   [script-name:section] message   (from a child logger)
+ *
+ * warn/error are routed to stderr and tagged with their level.
+ */
+
+/**
+ * Create a logger for a script. `child(section)` returns a logger whose
+ * prefix is extended with `:section`.
+ *
+ * @param {string} prefix - Initial prefix (usually the script's meta.name)
+ * @returns {{info: Function, warn: Function, error: Function, child: Function}}
+ */
+export function createLogger(prefix) {
+  return {
+    info: (msg) => console.log(`[${prefix}] ${msg}`),
+    warn: (msg) => console.warn(`[${prefix}] WARN ${msg}`),
+    error: (msg) => console.error(`[${prefix}] ERROR ${msg}`),
+    child: (section) => createLogger(`${prefix}:${section}`),
+  };
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/params.mjs

@@ -0,0 +1,140 @@
+/**
+ * Param resolution and validation.
+ *
+ * Scripts declare their params in `meta.params`. The framework resolves and
+ * validates them BEFORE `execute()` runs, so a script never validates its own
+ * input.
+ *
+ * Resolution order (lowest to highest priority):
+ *   ctx.settings  <  meta.params[x].default  <  explicit (CLI) params
+ *
+ * A param spec supports:
+ *   required        {boolean}  - error if no value resolves
+ *   default         {*}        - fallback value
+ *   description     {string}   - shown in CLI listings and error messages
+ *   validate        {RegExp|Function}
+ *       RegExp   - the resolved value (coerced to string) must match
+ *       Function - (value, resolvedParams) => true | false | string
+ *                  true   = valid
+ *                  string = invalid; the string is used as the error message
+ *                  false  = invalid; `invalidMessage` (or a default) is used
+ *   invalidMessage  {string}   - error message for a failing RegExp, or for a
+ *                                validate function that returns `false`
+ */
+
+export class ParamError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ParamError';
+  }
+}
+
+/**
+ * Resolve and validate params for a script.
+ *
+ * @param {object} meta - The script's `meta` export (may have `.params`).
+ * @param {object} explicit - Params explicitly provided (e.g. from CLI).
+ * @param {object} settings - Compiled project settings (ctx.settings).
+ * @returns {object} The fully-resolved params object.
+ * @throws {ParamError} If a required param is missing or a value fails validation.
+ */
+export function resolveParams(meta, explicit = {}, settings = {}) {
+  const spec = meta?.params || {};
+  const scriptName = meta?.name || 'script';
+  const resolved = {};
+  const missing = [];
+
+  for (const [key, def] of Object.entries(spec)) {
+    let value;
+    if (key in explicit) value = explicit[key];
+    else if (def.default !== undefined) value = def.default;
+    else if (key in settings) value = settings[key];
+
+    if (value === undefined) {
+      if (def.required) missing.push(key);
+      continue;
+    }
+    resolved[key] = value;
+  }
+
+  // Pass through any explicit params not declared in meta (escape hatch).
+  for (const [key, value] of Object.entries(explicit)) {
+    if (!(key in resolved)) resolved[key] = value;
+  }
+
+  if (missing.length) {
+    throw new ParamError(
+      `Missing required param(s) for "${scriptName}":\n${missing
+        .map((k) => describeParam(k, spec[k]))
+        .join('\n')}`
+    );
+  }
+
+  const invalid = validateParams(spec, resolved);
+  if (invalid.length) {
+    throw new ParamError(
+      `Invalid param(s) for "${scriptName}":\n${invalid
+        .map(({ key, message }) => `  - ${key}: ${message}`)
+        .join('\n')}`
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Run each declared param's `validate` rule against its resolved value.
+ *
+ * @param {object} spec - The `meta.params` spec object.
+ * @param {object} resolved - The resolved param values.
+ * @returns {Array<{key: string, message: string}>} One entry per failure.
+ */
+function validateParams(spec, resolved) {
+  const failures = [];
+
+  for (const [key, def] of Object.entries(spec)) {
+    if (!(key in resolved) || !def?.validate) continue;
+    const message = runValidator(def, resolved[key], resolved);
+    if (message) failures.push({ key, message });
+  }
+
+  return failures;
+}
+
+/**
+ * Apply a single param's validator to a value.
+ *
+ * @param {object} def - The param spec (has `validate` and optional `invalidMessage`).
+ * @param {*} value - The resolved value to check.
+ * @param {object} resolved - All resolved params (passed to function validators).
+ * @returns {string|null} An error message if invalid, otherwise null.
+ */
+function runValidator(def, value, resolved) {
+  const { validate, invalidMessage } = def;
+
+  if (validate instanceof RegExp) {
+    return validate.test(String(value))
+      ? null
+      : invalidMessage || `value "${value}" does not match ${validate}`;
+  }
+
+  if (typeof validate === 'function') {
+    const result = validate(value, resolved);
+    if (result === true) return null;
+    if (typeof result === 'string') return result;
+    return invalidMessage || `value "${value}" is invalid`;
+  }
+
+  return null;
+}
+
+/**
+ * Format a param for inclusion in a "missing required" error message.
+ *
+ * @param {string} key - The param name.
+ * @param {object} [def] - The param spec (may carry a description).
+ * @returns {string} A single indented line.
+ */
+function describeParam(key, def) {
+  return def?.description ? `  - ${key}: ${def.description}` : `  - ${key}`;
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/run.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * Runner — executes an automation script by absolute path with given params.
+ *
+ * Usage:
+ *   node run.mjs <absolute-path-to-script.mjs> [--param=value ...]
+ *
+ * Harness options are passed the same way and intercepted before params:
+ *   --profileName=<name>   Chrome profile to pull cookies from
+ *   --timeout=<ms>         Overall script timeout
+ *   --headless=false       (debug) run headed — rarely useful for this system
+ *
+ * Everything else (--foo=bar) becomes a script param. The harness resolves
+ * defaults + settings and validates required params before execute() runs.
+ *
+ * Project settings compiled by sous (settings.mjs, a sibling of this file) are
+ * loaded automatically and passed to the harness as ctx.settings.
+ */
+
+import { resolve, dirname, join } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const HARNESS_OPTIONS = ['headless', 'profileName', 'timeout'];
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === '--help') {
+  console.log('Usage: node run.mjs <absolute-path-to-script.mjs> [--param=value ...]');
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+const scriptPath = resolve(args[0]);
+if (!existsSync(scriptPath)) {
+  console.error(`Script not found: ${scriptPath}`);
+  process.exit(1);
+}
+
+const { params, options } = parseArgs(args.slice(1));
+const settings = await loadSettings();
+const script = await import(pathToFileURL(scriptPath).href);
+const meta = script.meta || {};
+
+printRunHeader(meta, params, options, settings);
+
+// Imported lazily so --help and arg validation don't require playwright et al.
+const { runScript } = await import('./harness.mjs');
+const result = await runScript(script, params, { ...options, settings });
+
+reportResult(result);
+process.exit(result.success ? 0 : 1);
+
+/**
+ * Split `--key=value` args into harness options and script params.
+ *
+ * @param {string[]} rest - CLI args after the script path.
+ * @returns {{params: object, options: object}}
+ */
+function parseArgs(rest) {
+  const params = {};
+  const options = {};
+  for (const arg of rest) {
+    const match = arg.match(/^--([\w-]+)=(.*)$/s);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (!HARNESS_OPTIONS.includes(key)) {
+      params[key] = value;
+    } else if (key === 'headless') {
+      options.headless = value !== 'false';
+    } else if (key === 'timeout') {
+      options.timeout = parseInt(value, 10);
+    } else {
+      options[key] = value;
+    }
+  }
+  return { params, options };
+}
+
+/**
+ * Load compiled project settings (settings.mjs) sitting beside this runner.
+ *
+ * @returns {Promise<object>} The settings object, or {} if none is present.
+ */
+async function loadSettings() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const settingsPath = join(here, 'settings.mjs');
+  if (!existsSync(settingsPath)) return {};
+  const mod = await import(pathToFileURL(settingsPath).href);
+  return mod.default || {};
+}
+
+/**
+ * Print the resolved params (with defaults/settings marked) before running.
+ *
+ * @param {object} meta - The script's meta export.
+ * @param {object} params - Explicit CLI params.
+ * @param {object} options - Harness options.
+ * @param {object} settings - Compiled project settings.
+ * @returns {void}
+ */
+function printRunHeader(meta, params, options, settings) {
+  console.log(`\n▶ Running: ${meta.name || '(unnamed script)'}`);
+  console.log('  Params:');
+  const spec = meta.params || {};
+  const keys = new Set([...Object.keys(spec), ...Object.keys(params)]);
+  for (const key of keys) {
+    let value, origin;
+    if (key in params) { value = params[key]; origin = ''; }
+    else if (spec[key]?.default !== undefined) { value = spec[key].default; origin = ' (default)'; }
+    else if (key in settings) { value = settings[key]; origin = ' (settings)'; }
+    else continue;
+    console.log(`    ${key}: ${value}${origin}`);
+  }
+  if (Object.keys(options).length) console.log(`  Options: ${JSON.stringify(options)}`);
+  console.log('');
+}
+
+/**
+ * Print the run outcome and, on success, write any requested output file.
+ *
+ * @param {object} result - The harness result envelope.
+ * @returns {void}
+ */
+function reportResult(result) {
+  console.log('\n' + '─'.repeat(60));
+  if (result.success) {
+    console.log('✓ Script completed successfully\n');
+    if (result.data?.outputFile && result.data?.content) {
+      writeFileSync(result.data.outputFile, result.data.content);
+      console.log(`Output written to: ${result.data.outputFile}`);
+    } else {
+      console.log(JSON.stringify(result.data, null, 2));
+    }
+  } else {
+    console.log(`✗ Script failed (${result.error})\n`);
+    console.log(result.message);
+    if (result.stack && result.error === 'script') console.log(`\nStack:\n${result.stack}`);
+    if (result.debugDir) console.log(`\nDebug snapshot (screenshot, HTML, text): ${result.debugDir}`);
+  }
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/settings.tpl.mjs

@@ -0,0 +1 @@
+{% exportScalarVarsJs %}