session-orchestrator 4.1.0 → 5.0.0

package/templates/_shared/ux-manifest.template.md

@@ -0,0 +1,149 @@
+<!-- source: session-orchestrator plugin (canonical: templates/_shared/ux-manifest.template.md) -->
+---
+# ux-grill manifest — copy to `.orchestrator/ux-manifest.md` in the target repo.
+#
+# Every value below is a PLACEHOLDER. Replace them; never paste a credential,
+# a token or a production host into this file — it is tracked by git.
+
+# REQUIRED. Must be loopback (127.0.0.1 / localhost / [::1]). A non-loopback
+# base-url aborts the mechanical run with "base-url must be loopback".
+base-url: http://127.0.0.1:3100
+
+# REQUIRED. `dev` or `prod`. A dev build is not a geometry measurement basis,
+# so target-size findings from it are marked `provisional: true`.
+build: dev
+
+# Filename (relative to the target repo root) of the GITIGNORED env file that
+# holds the VALUES for every env NAME named below. Omit it if no run needs
+# credentials or guarded endpoints.
+env-file: .env.e2e.local
+
+# Env NAMES whose values must point at loopback. Use this for every endpoint
+# the app talks to (API base, database URL, storage) so a stray production
+# value cannot be written to by a seed or a journey. The value is checked but
+# never printed.
+guarded-url-envs:
+  - APP_API_BASE_URL
+  - APP_DATABASE_URL
+
+# Optional command that seeds deterministic test data before the run.
+seed-command: npm run seed:e2e
+
+# Evaluation personas. Credentials are env NAMES only — the values live in
+# `env-file`. Use `personas: []` for an app that needs no login.
+personas:
+  - name: solo-operator
+    login-env-email: LOGIN_EMAIL_SOLO
+    login-env-password: LOGIN_PASSWORD_SOLO
+    goal: Get from the dashboard to a finished document without help.
+  - name: accountant
+    login-env-email: LOGIN_EMAIL_ACCOUNTANT
+    login-env-password: LOGIN_PASSWORD_ACCOUNTANT
+    goal: Review a client's numbers and export them.
+
+# Routes to measure. `title-pattern` is a regular expression matched against
+# the page title. `frame` is optional and only used by the Pencil coverage
+# step (`desktop` | `mobile` | `both` | `none`).
+routes:
+  - path: /dashboard
+    title-pattern: ^Dashboard
+    persona: solo-operator
+    frame: both
+  - path: /documents/new
+    title-pattern: ^New document
+    persona: solo-operator
+
+# Journeys are replayed verbatim: every entry of `steps` is one agent-browser
+# command line, so the mechanical stage can count them without judging them.
+#
+# TRUST: each step line is split into an argv array and handed to the
+# `agent-browser` binary (never to a shell) — but NOT verbatim: the first token
+# must be one of the ALLOWLISTED UI verbs below, anything else aborts the run
+# with `step-verb-not-allowed`.
+#
+#   back  check  click  dblclick  drag  fill  find  focus  forward  get
+#   hover  is  keyboard  open  press  reload  scroll  scrollintoview
+#   select  snapshot  type  uncheck  wait
+#
+# The denied half of the CLI is what the allowlist exists for: `upload` and
+# `cookies set --curl` read arbitrary HOST FILES into the page, `download` and
+# `pdf` write arbitrary host paths, `eval` can exfiltrate off-origin, `connect`
+# retargets a foreign browser, and `close --all` kills every other agent's
+# session on the machine. So the trust model is "allowlisted UI verbs", not
+# "anything the CLI accepts" — whoever can commit this file can drive the
+# BROWSER, not the host.
+#
+# An `open` step must resolve to the same origin as `base-url`, else
+# `step-open-off-origin`. A step may not carry `--session`: the run owns its
+# session, and a step that retargets it aborts with `step-session-override`.
+#
+# `start` must resolve to the SAME ORIGIN as `base-url` (a path is the normal
+# form). An off-origin `start` aborts with `journey-start-off-origin` — with a
+# persona attached, an absolute foreign URL would type real credentials into a
+# foreign page. The same rule holds for every `routes[].path`.
+journeys:
+  - name: create-first-document
+    persona: solo-operator
+    start: /dashboard
+    steps:
+      - click "New document"
+      - type "#title" "Placeholder title"
+      - click "Save"
+    success: /documents/
+    max-steps: 6
+
+# Viewports. Defaults to exactly these two when the key is absent.
+#
+# Every viewport is VERIFIED after it is applied: `window.innerWidth` must equal
+# the expectation, else the viewport is skipped as `device-mismatch` rather than
+# captured under a wrong label. The expectation is the `viewport:` width, the
+# built-in width of a known `device:` name (iPhone 15/16 393, iPhone 16 Pro 402,
+# iPhone 17 402, iPad 820, iPad Pro 1024, Pixel 9 412, Galaxy S25 360 — measured
+# against agent-browser 0.37.1), or an explicit `expected-width:`. A `device:`
+# outside that list NEEDS `expected-width:`, otherwise the viewport is skipped:
+# an unknown device name leaves the previous device in place, so an unverified
+# width is exactly how desktop captures end up labelled `mobile`.
+viewports:
+  - name: desktop
+    viewport: 1440x900
+  - name: mobile
+    device: iPhone 15
+
+# Optional design-coverage source.
+pencil:
+  file: design/app.pen
+---
+
+# UX Manifest — <REPO NAME>
+
+> Per-repo UX truth: what a real user walks through, and what the mechanical
+> stage is allowed to touch. Last verified: <YYYY-MM-DD> by <operator>
+
+## Notes
+
+Free-form notes below the frontmatter. They are preserved verbatim and are not
+parsed — use them for context the fields cannot carry.
+
+**Credentials never go in this file.** The frontmatter names env VARIABLES
+(`login-env-email`, `login-env-password`, `guarded-url-envs`); their values are
+read at run time from the gitignored file named by `env-file`. A value pasted
+here is a secret in a tracked file, and the run itself will never print one:
+guarded-env and persona errors name the variable, never its content. `env-file`
+must resolve INSIDE the repo (`env-file-outside-repo` otherwise) — it names a
+file of this repo, never a host-wide secrets file.
+
+**Run artefacts can carry a credential even though findings cannot.** Three
+classes: journey step screenshots (one is taken after EVERY step, including the
+one right after `fill #pw ${LOGIN_PASSWORD}`), the text of `errors --json`, and
+the `html` snippets inside axe JSON. They all live under
+`.orchestrator/metrics/ux-grill/`, which `/ux-grill` adds to this repo's
+`.gitignore` on bootstrap — keep that line, and never commit a run directory.
+
+## Known exceptions
+
+Findings that are known and deliberately accepted — with the reason and a
+revisit trigger, so they are not re-filed every run.
+
+| Finding | Why accepted | Revisit trigger |
+|---------|--------------|-----------------|
+| <…> | <…> | <…> |

package/templates/nextjs-minimal/package.json

@@ -22,6 +22,6 @@
     "eslint": "^9.0.0",
     "eslint-config-next": "^15.3.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^4.1.11"
   }
 }

package/templates/node-minimal/package.json

@@ -16,6 +16,6 @@
     "eslint": "^9.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^4.1.11"
   }
 }

package/scripts/lib/multi-provider-build/providers.mjs

@@ -1,64 +0,0 @@
-/**
- * scripts/lib/multi-provider-build/providers.mjs
- *
- * Provider configuration for the single-source → many-provider build PoC.
- *
- * Scope: the THREE harnesses session-orchestrator actually targets
- * (Claude Code primary, Codex CLI, Cursor IDE). Inspired by pbakaus/impeccable's
- * 12-provider build (Apache-2.0) — we deliberately keep the templating mechanic
- * and drop the 12-provider breadth (maintenance ≫ value for providers with ~0
- * users; see the linked backlog issue's overengineering verdict).
- *
- * Each provider entry:
- *   {
- *     key,            // canonical id used in build output paths
- *     tags,           // <tag> block markers this provider keeps (rest are stripped)
- *     configDir,      // on-disk harness dir
- *     placeholders: { model, configFile, commandPrefix, askInstruction }
- *   }
- */
-
-/** @typedef {{key:string, tags:string[], configDir:string, placeholders:{model:string, configFile:string, commandPrefix:string, askInstruction:string}}} ProviderConfig */
-
-/** @type {Record<string, ProviderConfig>} */
-export const PROVIDERS = {
-  'claude-code': {
-    key: 'claude-code',
-    tags: ['claude-code', 'claude'],
-    configDir: '.claude',
-    placeholders: {
-      model: 'Claude',
-      configFile: 'CLAUDE.md',
-      commandPrefix: '/',
-      askInstruction: 'STOP and call the AskUserQuestion tool to clarify.',
-    },
-  },
-  codex: {
-    key: 'codex',
-    tags: ['codex'],
-    configDir: '.codex',
-    placeholders: {
-      model: 'GPT',
-      configFile: 'AGENTS.md',
-      commandPrefix: '$',
-      askInstruction: "STOP and use Codex's structured user-input tool to clarify.",
-    },
-  },
-  cursor: {
-    key: 'cursor',
-    tags: ['cursor'],
-    configDir: '.cursor',
-    placeholders: {
-      model: 'the model',
-      configFile: '.cursorrules',
-      commandPrefix: '/',
-      askInstruction: 'ask the user directly to clarify before proceeding.',
-    },
-  },
-};
-
-/** The full set of recognized provider block tags across ALL providers. */
-export const ALL_BLOCK_TAGS = new Set(Object.values(PROVIDERS).flatMap((p) => p.tags));
-
-/** Provider keys in a stable order. */
-export const PROVIDER_KEYS = Object.keys(PROVIDERS);

package/scripts/lib/multi-provider-build/templating.mjs

@@ -1,130 +0,0 @@
-/**
- * scripts/lib/multi-provider-build/templating.mjs
- *
- * Single-source → many-provider templating (PoC). One source document with
- * provider-conditional blocks + placeholders renders to a provider-specific
- * artifact. This replaces the "maintain N near-identical copies by hand" model
- * our codex-install.mjs / cursor-install.mjs currently imply.
- *
- * Two primitives (clean-room reimplementation of impeccable's mechanic):
- *   1. compileProviderBlocks(content, activeTags)
- *        <codex> … </codex> blocks: keep body iff the tag is active, else drop.
- *        Unknown tags are left untouched (so real HTML/JSX isn't mangled).
- *   2. replacePlaceholders(content, providerKey, opts)
- *        {{model}} {{config_file}} {{command_prefix}} {{ask_instruction}}
- *        {{available_commands}} substitution + optional /cmd → $cmd rewrite.
- *
- * renderForProvider() composes both in the correct order (blocks first, then
- * placeholders — matching impeccable's pipeline).
- */
-
-import { PROVIDERS, ALL_BLOCK_TAGS } from './providers.mjs';
-
-/**
- * Keep `<tag>…</tag>` blocks whose tag is in `activeTags`; strip the rest.
- * Only tags in `knownTags` are treated as conditional blocks — any other
- * `<foo>…</foo>` (e.g. real markup) is left exactly as-is.
- *
- * Tags must sit on their own line, e.g.:
- *   <codex>
- *   Codex-only text.
- *   </codex>
- *
- * @param {string} content
- * @param {Iterable<string>} activeTags
- * @param {Iterable<string>} [knownTags] — defaults to ALL_BLOCK_TAGS
- * @returns {string}
- */
-export function compileProviderBlocks(content, activeTags, knownTags = ALL_BLOCK_TAGS) {
-  const active = new Set(activeTags);
-  const known = new Set(knownTags);
-  let compiledAny = false;
-
-  // Match a block: leading newline (or start), <tag> on its own line, body,
-  // </tag> on its own line. Non-greedy body; the backreference enforces matching.
-  const blockRe = /(^|\r?\n)[ \t]*<([a-z][a-z0-9-]*)>[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*<\/\2>[ \t]*(?=\r?\n|$)/g;
-
-  const out = content.replace(blockRe, (match, prefix, tag, body) => {
-    if (!known.has(tag)) return match; // not a provider block — leave untouched
-    compiledAny = true;
-    return active.has(tag) ? `${prefix}${body}` : prefix;
-  });
-
-  // Collapse the 3+ blank-line runs that stripping can leave behind.
-  return compiledAny ? out.replace(/(\r?\n){3,}/g, '\n\n') : out;
-}
-
-/**
- * Substitute {{placeholders}} for a provider and (optionally) rewrite command
- * invocations from `/name` to the provider's prefix.
- *
- * @param {string} content
- * @param {string} providerKey
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {string}
- */
-export function replacePlaceholders(content, providerKey, opts = {}) {
-  const provider = PROVIDERS[providerKey];
-  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
-  const { model, configFile, commandPrefix, askInstruction } = provider.placeholders;
-  const commandNames = opts.commandNames ?? [];
-
-  const availableCommands = commandNames.map((n) => `${commandPrefix}${n}`).join(', ');
-
-  let result = content
-    .replace(/\{\{model\}\}/g, model)
-    .replace(/\{\{config_file\}\}/g, configFile)
-    .replace(/\{\{ask_instruction\}\}/g, askInstruction)
-    .replace(/\{\{available_commands\}\}/g, availableCommands)
-    .replace(/\{\{command_prefix\}\}/g, commandPrefix);
-
-  // Rewrite `/cmd` invocations to the provider prefix (e.g. Codex uses `$`).
-  // Longest names first so `/session-end` is rewritten before `/session`.
-  if (commandPrefix !== '/' && commandNames.length > 0) {
-    const sorted = [...commandNames].sort((a, b) => b.length - a.length);
-    for (const name of sorted) {
-      // `/name` where name is followed by a non-identifier char or end.
-      const re = new RegExp(`\\/(${escapeRegex(name)})(?=[^a-zA-Z0-9_-]|$)`, 'g');
-      // Use a replacement FUNCTION, not a string — a `$` commandPrefix would
-      // otherwise collide with String.replace's `$$`/`$1` escape syntax.
-      result = result.replace(re, (_match, g1) => `${commandPrefix}${g1}`);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Render a source document for a single provider: compile blocks, then
- * substitute placeholders.
- *
- * @param {string} source
- * @param {string} providerKey
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {string}
- */
-export function renderForProvider(source, providerKey, opts = {}) {
-  const provider = PROVIDERS[providerKey];
-  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
-  const compiled = compileProviderBlocks(source, provider.tags);
-  return replacePlaceholders(compiled, providerKey, opts);
-}
-
-/**
- * Render a source for every configured provider.
- * @param {string} source
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {Record<string,string>} keyed by provider key
- */
-export function renderAll(source, opts = {}) {
-  const out = {};
-  for (const key of Object.keys(PROVIDERS)) {
-    out[key] = renderForProvider(source, key, opts);
-  }
-  return out;
-}
-
-/** @param {string} s */
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/scripts/lib/owner-config/coerce.mjs

@@ -1,29 +0,0 @@
-/**
- * owner-config/coerce.mjs — Strict-mode wrapper around validate().
- *
- * Imports: validate + OwnerConfigError. Throws on validation failure, returns
- * the normalized value on success. Convenient for CLI entrypoints and tests
- * that want to assert on success without inspecting `ok`.
- */
-
-import { validate } from './validate.mjs';
-import { OwnerConfigError } from './error.mjs';
-
-/**
- * Strict-mode wrapper around validate(). Returns the normalized value when
- * the input passes the gate, otherwise throws OwnerConfigError with the
- * full error list attached as `.errors`.
- *
- * @param {unknown} raw
- * @returns {object}
- */
-export function coerce(raw) {
-  const result = validate(raw);
-  if (!result.ok) {
-    throw new OwnerConfigError(
-      `owner config validation failed (${result.errors.length} error${result.errors.length === 1 ? '' : 's'})`,
-      result.errors
-    );
-  }
-  return result.value;
-}

package/scripts/lib/owner-config/constants.mjs

@@ -1,21 +0,0 @@
-/**
- * owner-config/constants.mjs — Schema constants for the owner persona config.
- *
- * Leaf module. No imports. All exported arrays are frozen so consumers cannot
- * accidentally mutate the canonical enum sets.
- */
-
-/** Current owner-config schema version. New writes are stamped with this. */
-export const CURRENT_OWNER_SCHEMA_VERSION = 1;
-
-/** Valid values for tone.style. */
-export const VALID_TONE_STYLES = Object.freeze(['direct', 'neutral', 'friendly']);
-
-/** Valid values for efficiency.output-level. */
-export const VALID_OUTPUT_LEVELS = Object.freeze(['lite', 'full', 'ultra']);
-
-/** Valid values for efficiency.preamble. */
-export const VALID_PREAMBLE_LEVELS = Object.freeze(['minimal', 'verbose']);
-
-/** Valid values for efficiency.comments-in-code. */
-export const VALID_COMMENTS_LEVELS = Object.freeze(['minimal', 'full']);

package/scripts/lib/owner-config/defaults.mjs

@@ -1,50 +0,0 @@
-/**
- * owner-config/defaults.mjs — Canonical default-filled owner config factory.
- *
- * Imports constants only. Leaf in the dependency sense (no circular deps).
- * Returns the fully-default-filled config with `owner.name` and
- * `owner.language` intentionally left blank — those are required from the user;
- * the bootstrap interview (D2) fills them in.
- */
-
-import { CURRENT_OWNER_SCHEMA_VERSION } from './constants.mjs';
-
-/**
- * Returns the canonical default-filled owner config. `owner.name` and
- * `owner.language` are intentionally empty — those are user-required fields
- * the bootstrap interview (D2) fills in. The `defaults()` shape is what
- * `merge()` uses as its base when callers pass partial overrides.
- *
- * @returns {object}
- */
-export function defaults() {
-  return {
-    'schema-version': CURRENT_OWNER_SCHEMA_VERSION,
-    owner: {
-      name: '',
-      'email-hash': null,
-      language: '',
-    },
-    tone: {
-      style: 'neutral',
-      tonality: null,
-    },
-    efficiency: {
-      'output-level': 'full',
-      preamble: 'minimal',
-      'comments-in-code': 'minimal',
-    },
-    'hardware-sharing': {
-      enabled: false,
-      'hash-salt': null,
-    },
-    defaults: {
-      'preferred-test-command': null,
-      'preferred-editor': null,
-    },
-    metadata: {
-      created_at: null,
-      updated_at: null,
-    },
-  };
-}

package/scripts/lib/owner-config/error.mjs

@@ -1,19 +0,0 @@
-/**
- * owner-config/error.mjs — OwnerConfigError class.
- *
- * Leaf module. No imports. Thrown by coerce() when validation fails. The
- * `.errors` array carries the full list of human-readable failure messages
- * collected by validate().
- */
-
-export class OwnerConfigError extends Error {
-  /**
-   * @param {string} message
-   * @param {string[]} [errors]
-   */
-  constructor(message, errors = []) {
-    super(message);
-    this.name = 'OwnerConfigError';
-    this.errors = errors;
-  }
-}

package/scripts/lib/owner-config/index.mjs

@@ -1,13 +0,0 @@
-/**
- * owner-config/index.mjs — Re-export hub for all 10 public symbols.
- *
- * DAG: constants/error (leaves) → defaults → merge; constants/error → validate → coerce.
- * This hub is the single import target for `scripts/lib/owner-config.mjs` (top wrapper).
- */
-
-export { CURRENT_OWNER_SCHEMA_VERSION, VALID_TONE_STYLES, VALID_OUTPUT_LEVELS, VALID_PREAMBLE_LEVELS, VALID_COMMENTS_LEVELS } from './constants.mjs';
-export { OwnerConfigError } from './error.mjs';
-export { defaults } from './defaults.mjs';
-export { validate } from './validate.mjs';
-export { coerce } from './coerce.mjs';
-export { merge } from './merge.mjs';

package/scripts/lib/owner-config/merge.mjs

@@ -1,52 +0,0 @@
-/**
- * owner-config/merge.mjs — Deep merge for owner persona configs.
- *
- * Imports: constants + defaults. One-level-deep section merge because the
- * schema has no nested object leaves beyond top-level sections. The output is
- * always a full default-filled config — either input may be partial.
- */
-
-import { CURRENT_OWNER_SCHEMA_VERSION } from './constants.mjs';
-import { defaults } from './defaults.mjs';
-
-function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-
-/**
- * Deep merge two owner configs. `override` values win on every leaf key
- * where they are defined (i.e. not undefined). The returned value is a
- * full default-filled config — either input may be partial.
- *
- * Used by D3 (`soul.md` runtime-merge) and D4 (baseline-propagation +
- * per-session override). The merge is one level deep on each top-level
- * section (owner, tone, efficiency, hardware-sharing, defaults, metadata)
- * because the schema has no nested object leaves beyond that.
- *
- * @param {object|null|undefined} base
- * @param {object|null|undefined} override
- * @returns {object}
- */
-export function merge(base, override) {
-  const baseSafe = isPlainObject(base) ? base : {};
-  const overSafe = isPlainObject(override) ? override : {};
-  const def = defaults();
-
-  const sections = ['owner', 'tone', 'efficiency', 'hardware-sharing', 'defaults', 'metadata'];
-  const out = {
-    'schema-version': CURRENT_OWNER_SCHEMA_VERSION,
-  };
-
-  for (const section of sections) {
-    const baseSection = isPlainObject(baseSafe[section]) ? baseSafe[section] : {};
-    const overSection = isPlainObject(overSafe[section]) ? overSafe[section] : {};
-    out[section] = { ...def[section], ...baseSection };
-    for (const [k, v] of Object.entries(overSection)) {
-      if (v !== undefined) {
-        out[section][k] = v;
-      }
-    }
-  }
-
-  return out;
-}