@sous-io/sous 0.1.0 → 0.2.0

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

@@ -1,140 +0,0 @@
-/**
- * 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

@@ -1,140 +0,0 @@
-#!/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

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

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

@@ -1,185 +0,0 @@
-/**
- * ctx.utils — generic, site-agnostic helpers for automation scripts.
- *
- * These are the patterns proven during the POC, promoted out of any single
- * script. Site-specific logic (dismissing a particular app's modals, parsing a
- * particular tool's output) stays in the script as step functions.
- *
- * Built per-run and bound to the live `page`/`logger`, so scripts call them as
- * `ctx.utils.foo(...)` without threading `page` through every call.
- */
-
-/**
- * Build the utils object for a run.
- *
- * @param {import('playwright').Page} page
- * @param {object} logger - The script's logger (a child is created per helper)
- * @returns {object} the ctx.utils surface
- */
-export function createUtils(page, logger) {
-  const log = logger.child('utils');
-
-  return {
-    /**
-     * RECOMMENDED way to handle modals/banners that appear at an unpredictable
-     * time and would block later actions. Registers a Playwright locator handler:
-     * whenever `triggerLocator` is present and blocks an action, `dismiss` runs.
-     * This is fully timing-independent — no sleeps, no races. Prefer this over
-     * `dismissModals` for anything that may appear asynchronously.
-     *
-     * @param {import('playwright').Locator} triggerLocator - The modal/overlay.
-     * @param {(locator) => Promise<void>} dismiss - How to dismiss it.
-     * @returns {Promise<void>}
-     */
-    async autoDismiss(triggerLocator, dismiss) {
-      await page.addLocatorHandler(triggerLocator, dismiss);
-      log.info('registered auto-dismiss handler');
-    },
-
-    /**
-     * Best-effort one-shot dismissal of modals KNOWN to already be present. Clicks
-     * the first of each candidate selector that currently exists; failures are
-     * swallowed. Does NOT wait for modals that may appear later — use
-     * `autoDismiss` for those. No fixed delays.
-     *
-     * @param {string[]} selectors
-     * @param {object} [opts] - { timeout }
-     * @returns {Promise<number>} count of elements clicked
-     */
-    async dismissModals(selectors, opts = {}) {
-      const { timeout = 2000 } = opts;
-      let dismissed = 0;
-      for (const sel of selectors) {
-        const el = await page.$(sel);
-        if (!el) continue;
-        try {
-          await el.click({ timeout });
-          dismissed++;
-        } catch {
-          // best-effort; modal may have already closed or be non-actionable
-        }
-      }
-      if (dismissed) log.info(`dismissed ${dismissed} modal element(s)`);
-      return dismissed;
-    },
-
-    /**
-     * Click an element located by visible text (regex or string). Defaults to a
-     * NON-forced click so Playwright auto-waits for the element to be actionable
-     * (visible, stable, not covered) — the resilient default. Pass `force: true`
-     * only for the rare element a component library (e.g. Blueprint.js) wrongly
-     * reports as disabled, and verify the outcome afterward.
-     *
-     * @param {RegExp|string} text
-     * @param {object} [opts] - { force, timeout }
-     */
-    async clickByText(text, opts = {}) {
-      const { force = false, timeout = 15000 } = opts;
-      const locator = page.getByText(text).first();
-      await locator.waitFor({ timeout });
-      await locator.click({ force });
-    },
-
-    /**
-     * Wait for any element matching `text` (regex or string) to appear, without
-     * clicking. Useful for asserting a list/view has rendered.
-     *
-     * @param {RegExp|string} text
-     * @param {object} [opts] - { timeout }
-     */
-    async waitForText(text, opts = {}) {
-      const { timeout = 15000 } = opts;
-      await page.getByText(text).first().waitFor({ timeout });
-    },
-
-    /**
-     * Try each selector in order; return the longest text content found among
-     * all matches, or null if nothing exceeds `minLength`. Built for "find the
-     * log/output blob on the page" cases where the exact container is unknown.
-     *
-     * @param {string[]} selectors
-     * @param {object} [opts] - { minLength }
-     * @returns {Promise<string|null>}
-     */
-    async extractLongestText(selectors, opts = {}) {
-      const { minLength = 50 } = opts;
-      for (const sel of selectors) {
-        const els = await page.$$(sel);
-        if (!els.length) continue;
-        const texts = await Promise.all(els.map((el) => el.textContent()));
-        const longest = texts
-          .filter(Boolean)
-          .map((t) => t.trim())
-          .sort((a, b) => b.length - a.length)[0];
-        if (longest && longest.length >= minLength) return longest;
-      }
-      return null;
-    },
-
-    /**
-     * Extract the first match of a regex from page text (or supplied text).
-     * Returns the trimmed match string, or null.
-     *
-     * @param {RegExp} pattern
-     * @param {object} [opts] - { source: string, group: number }
-     * @returns {Promise<string|null>}
-     */
-    async extractTextByPattern(pattern, opts = {}) {
-      const { source = null, group = 0 } = opts;
-      const haystack = source ?? (await page.textContent('body')) ?? '';
-      const m = haystack.match(pattern);
-      return m ? m[group].trim() : null;
-    },
-
-    /**
-     * Capture a screenshot for debugging. No-op-safe: failures are logged, not
-     * thrown, so a debug aid never breaks a run.
-     *
-     * @param {string} path - Absolute file path for the PNG
-     * @param {object} [opts] - { fullPage }
-     */
-    async screenshot(path, opts = {}) {
-      const { fullPage = true } = opts;
-      try {
-        await page.screenshot({ path, fullPage });
-        log.info(`screenshot saved: ${path}`);
-      } catch (err) {
-        log.warn(`screenshot failed: ${err.message}`);
-      }
-    },
-
-    /**
-     * Scroll an element matching `selector` into view. Returns true if found.
-     *
-     * @param {string} selector
-     */
-    async scrollIntoView(selector) {
-      const el = await page.$(selector);
-      if (!el) return false;
-      await el.scrollIntoViewIfNeeded().catch(() => {});
-      return true;
-    },
-
-    /**
-     * Retry an async function until it succeeds or attempts are exhausted.
-     * Throws the last error on final failure.
-     *
-     * @param {Function} fn - async () => result
-     * @param {object} [opts] - { attempts, delay, label }
-     */
-    async retry(fn, opts = {}) {
-      const { attempts = 3, delay = 1000, label = 'operation' } = opts;
-      let lastErr;
-      for (let i = 1; i <= attempts; i++) {
-        try {
-          return await fn();
-        } catch (err) {
-          lastErr = err;
-          log.warn(`${label} failed (attempt ${i}/${attempts}): ${err.message}`);
-          if (i < attempts) await page.waitForTimeout(delay);
-        }
-      }
-      throw lastErr;
-    },
-  };
-}

package/shared-prompts/skills/automated-browser-tasks/create-automated-browser-task/SKILL.tpl.md

@@ -1,52 +0,0 @@
----
-name: create-automated-browser-task
-description: >
-  YOU MUST load this skill when you need to create a new headless browser
-  automation script — i.e. a browser task is required and no existing script
-  performs it. Produces a convention-compliant script in the project's
-  automation scripts directory.
----
-
-# Create an Automated Browser Task
-
-A thin action skill. The architecture, `ctx` API, and full conventions live in
-the parent topic skill; the agent performing this work MUST load
-`about-automated-browser-tasks`.
-
-## Delegation
-
-Per the sub-agent delegation pattern
-(`~sous-shared/_partials/sub-agent-delegation.md`), writing and iterating on a script is
-delegated work: one Opus sub-agent writes it, runs it, and iterates against the
-real page until it works, then reports the script path and result. Give it the
-target URL, the data to extract, and the params wanted.
-
-## Steps
-
-1. **Confirm none exists.** Search the project's automation scripts directory for
-   a script that already does this. If one is close, prefer
-   `update-automated-browser-task` instead.
-2. **Name the file** `verb-noun-qualifier.mjs` (e.g. `get-repo-ci-error.mjs`).
-3. **Declare `meta`** — `name`, a descriptive `description`, and `params`. For each
-   param set `required`, `default`, a genuinely descriptive `description`, and a
-   `validate` rule (RegExp or function) with an `invalidMessage`. Pull shared
-   values (URLs, resource IDs, profile) from `ctx.settings` rather than hardcoding.
-4. **Write `execute(ctx)`** as a thin orchestrator that calls small, named step
-   functions. Destructure off `ctx`/`params` at the top. Use `ctx.logger`, never
-   `console.log`. Use `ctx.utils` for generic patterns; keep site-specific logic
-   in step functions. Give EVERY function a full JSDoc block.
-5. **Return a result object** (`found`, `content`, `outputFile`, a URL, `message`).
-6. **Run it** to verify — see `running-automated-browser-tasks`. Iterate on the
-   real page; do not guess selectors.
-
-## Reference
-
-The exact param spec, `ctx.utils` surface, return shape, and worked examples are
-in the topic skill's references and `examples/`. Read them — do not improvise.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/automated-browser-tasks/running-automated-browser-tasks/SKILL.tpl.md

@@ -1,59 +0,0 @@
----
-name: running-automated-browser-tasks
-description: >
-  YOU MUST load this skill when you need to run an existing headless browser
-  automation script for the user — to execute a task, fetch data from a site, or
-  verify a script you just wrote or changed.
----
-
-# Run an Automated Browser Task
-
-A thin action skill. The agent performing this work MUST load
-`about-automated-browser-tasks` for the architecture and the meaning of `ctx`,
-auth handling, and result shapes.
-
-## Delegation
-
-Per the sub-agent delegation pattern
-(`~sous-shared/_partials/sub-agent-delegation.md`), a browser run is a slow, multi-step
-execution: delegate it to a background sub-agent, which runs the command,
-interprets the outcome below, and reports the result plus any link or actionable
-message. Run a one-off script inline only when its result blocks the very next
-step.
-
-## Invocation
-
-Run a script by its absolute path through the runner in this system's `scripts/`
-directory:
-
-```bash
-node <scriptsDir>/run.mjs <absolute-path-to-script.mjs> [--param=value ...]
-```
-
-- Pass script params as `--paramName=value`.
-- Harness options: `--profileName=<name>` (Chrome profile), `--timeout=<ms>`.
-- The runner loads compiled project `settings.mjs` automatically and prints the
-  resolved params (marking which came from defaults/settings) before running.
-
-## Reading the outcome
-
-- **Success** → `✓` and the result is printed; if the script returned an
-  `outputFile` + `content`, the runner writes the file and reports the path.
-- **`error: params`** → a required param was missing or failed validation. Fix the
-  invocation; do not edit the script to bypass validation.
-- **`error: auth`** → the session was redirected to a login page. The user must log
-  in to the site in their Chrome profile, then the SAME command is re-run; no
-  script change needed. A sub-agent cannot ask for this: return the actionable
-  message and the link to the orchestrator, which relays them to the user and
-  re-dispatches the run afterward.
-- **`error: script`** → an unexpected failure with a stack. Inspect, then use
-  `update-automated-browser-task` to fix the root cause and re-run.
-
-Never silently swallow a failure or fake a result. Report what happened.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/automated-browser-tasks/update-automated-browser-task/SKILL.tpl.md

@@ -1,47 +0,0 @@
----
-name: update-automated-browser-task
-description: >
-  YOU MUST load this skill when you need to modify, fix, or extend an existing
-  headless browser automation script — for example when a script breaks because
-  a site's markup changed, or a new param/behavior is needed.
----
-
-# Update an Automated Browser Task
-
-A thin action skill. The agent performing this work MUST load
-`about-automated-browser-tasks` for the architecture, `ctx` API, and full
-conventions.
-
-## Delegation
-
-Per the sub-agent delegation pattern
-(`~sous-shared/_partials/sub-agent-delegation.md`), the fix-and-re-run loop below
-is delegated to one Opus sub-agent, which reports what broke, what it changed, and the verified
-result. Give it the script path and the failing run output.
-
-## Steps
-
-1. **Read the script** and the run output. Identify the failing step from the
-   logger prefixes (`[script:section]`) in the output.
-2. **Reproduce** by running it (see `running-automated-browser-tasks`). For
-   selector/markup failures, inspect the live page — use `ctx.utils.screenshot`
-   or widen selectors; do not guess.
-3. **Make the smallest correct change.** Fix the root cause, not the symptom. Keep
-   the existing decomposition: edit the relevant step function, add a new one if a
-   new discrete action is needed.
-4. **Preserve conventions.** Maintain JSDoc blocks, `ctx`/`params` destructuring,
-   `ctx.logger` usage, and `meta.params` validation. If you add a param, give it a
-   description and a `validate` rule.
-5. **Re-run to verify** the fix end-to-end.
-
-## When NOT to update
-
-If the change amounts to a different task, create a new script instead
-(`create-automated-browser-task`). Keep each script focused on one job.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/approve/SKILL.tpl.md

@@ -1,26 +0,0 @@
----
-name: approve
-description: Approve the current plan and instruct Claude to proceed with maximum parallelism.
-disable-model-invocation: true
----
-
-Your plan looks good, and I approve.
-
-While executing the plan, maximize parallelism:
-- Delegate the steps that have any complexity to background sub-agents, per the sub-agent
-  delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), batching independent
-  dispatches into one message.
-- Batch independent investigations (searches, file reads, greps, listings) into concurrent tool
-  calls whenever practical.
-- Keep dependent steps sequential (especially edits, formatting/linting, and tests that rely on
-  prior changes).
-
-Use the best-fit tools for the job. If you can't parallelize a step, say why briefly and proceed
-sequentially.
-
-## Source for this Skill
-
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
-template and the output file should not be edited directly.
-
-- Source Path: {{ sousTemplatePath }}