humanish 0.37.0 → 0.39.0

package/dist/persona-resolve.js

@@ -0,0 +1,109 @@
+// Resolve committed persona files into compiled personas, for EVERY lane (#381).
+//
+// #308 gave the terminal lane this: read `humanish/personas/<id>.yaml`, compile the traits into
+// behavioral directives, and record truthfully which traits were applied. The computer-use lanes
+// never got it — they composed a bare `Persona: <id>.` line and hardcoded `traitsApplied: []`, so
+// on browser routes the persona axis was a label rather than a behavior. A live two-lane contrast
+// (an impatient expert vs a patient newcomer, same app, same mission) came back with near-identical
+// action profiles, which read like evidence that personas do not matter and was actually evidence
+// that personas were never applied.
+//
+// This module is the shared implementation so the two routes cannot drift again: one containment
+// rule, one compiler, one fallback polarity.
+//
+// FAIL-SAFE, not fail-closed — deliberately the opposite polarity to the scorer loader. A persona
+// that declared nothing must never be given fabricated traits, so an unsafe id, a missing file, or
+// unparseable YAML falls back to the bare id line with a truthful EMPTY traitsApplied (warning only
+// when the file existed but could not be read). Silence here is honest; invention would not be.
+import { parse as parseYaml } from "yaml";
+import path from "node:path";
+import { parseResolvedPersona } from "./persona.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile } from "./selected-output-paths.js";
+import { realpath } from "node:fs/promises";
+/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+export const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
+export function personaTitleFromId(personaId) {
+    return personaId
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+/**
+ * Resolve ONE committed persona. Returns `null` (never a throw, never a guess) when the id is
+ * unsafe or no file exists, so a lane always runs.
+ */
+export async function resolveCommittedPersona(projectRoot, personaId) {
+    if (!PERSONA_ID_PATTERN.test(personaId)) {
+        return { persona: null, warnings: [] };
+    }
+    for (const candidate of [
+        path.posix.join("humanish", "personas", `${personaId}.yaml`),
+        path.posix.join("humanish", "personas", `${personaId}.yml`)
+    ]) {
+        const bytes = await readContainedRegularFile(projectRoot, candidate);
+        if (!bytes)
+            continue;
+        let raw;
+        try {
+            raw = parseYaml(bytes.toString("utf8"));
+        }
+        catch {
+            return {
+                persona: null,
+                warnings: [`${candidate} could not be parsed as YAML; the lane ran with the persona id only (no traits applied).`]
+            };
+        }
+        return { persona: parseResolvedPersona(raw, { id: personaId, name: personaTitleFromId(personaId) }), warnings: [] };
+    }
+    return { persona: null, warnings: [] };
+}
+/**
+ * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
+ * async file reads happen here, and the composer only does a lookup.
+ */
+export async function resolveCommittedPersonas(projectRoot, personaIds) {
+    const personas = new Map();
+    const warnings = [];
+    for (const personaId of new Set(personaIds.filter((id) => typeof id === "string" && id.length > 0))) {
+        const resolved = await resolveCommittedPersona(projectRoot, personaId);
+        if (resolved.persona)
+            personas.set(personaId, resolved.persona);
+        warnings.push(...resolved.warnings);
+    }
+    return { personas, warnings };
+}
+/**
+ * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
+ * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ */
+export function labPersonaIds(config) {
+    const ids = [];
+    for (const actor of config.actors ?? []) {
+        if (actor.persona)
+            ids.push(actor.persona);
+        for (const lane of actor.lanes ?? []) {
+            if (lane.persona)
+                ids.push(lane.persona);
+        }
+    }
+    return [...new Set(ids)];
+}
+/**
+ * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
+ * already-prepared root. Realpath-then-prepare mirrors the cua lab so a symlinked cwd still reads
+ * personas from the physical project.
+ */
+export async function resolveCommittedPersonasForCwd(cwd, personaIds) {
+    try {
+        const physical = await realpath(path.resolve(cwd));
+        const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physical), physical);
+        return await resolveCommittedPersonas(projectRoot, personaIds);
+    }
+    catch {
+        return { personas: new Map(), warnings: [] };
+    }
+}
+//# sourceMappingURL=persona-resolve.js.map

package/dist/persona-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-resolve.js","sourceRoot":"","sources":["../src/persona-resolve.ts"],"names":[],"mappings":"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"}

package/dist/program.js

@@ -22,6 +22,8 @@ import { DEFAULT_OSS_REPOS, runOssLab } from "./oss-lab.js";
 import { cleanupOssMetaLabSandboxes, cleanupStaleOssMetaLabSandboxes, runOssMetaLab, startOssMetaLabLiveRefresh } from "./oss-meta-lab.js";
 import { cleanupRun, doctor, listRuns, readReview, runDryRun, verifyRun } from "./run.js";
 import { reclaimRunSandboxes } from "./reclaim.js";
+import { runCommsCatchHost } from "./comms-catch-host.js";
+import { DEFAULT_SANDBOX_CATCH_PORT } from "./comms-sandbox-catch.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
     const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
@@ -167,6 +169,7 @@ export function createProgram(io = {}) {
     registerCleanupCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
     registerRunsCommand(program, cliIo);
+    registerCommsCommands(program, cliIo);
     registerReclaimCommand(program, cliIo);
     registerWatchCommand(program, cliIo);
     registerObserveCommand(program, cliIo);
@@ -372,6 +375,50 @@ function registerRunsCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+function registerCommsCommands(parent, io) {
+    const comms = parent
+        .command("comms")
+        .description("Off-app comms surfaces (email/SMS the app under test sends).")
+        .summary("Off-app comms surfaces.");
+    comms
+        .command("catch")
+        .description("Run the email catch on THIS host so humanish can study an app it does not provision (#328). Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.")
+        .summary("Run the adopter-hosted email catch.")
+        .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
+        .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
+        .option("--token <value>", "Require this bearer token on GET /deliveries (recommended when reachable off-host).")
+        .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
+        .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous = []) => [...previous, value])
+        .action(async (options) => {
+        const port = Number.parseInt(options.port, 10);
+        if (!Number.isInteger(port) || port <= 0 || port > 65_534) {
+            io.writeErr("--port must be an integer between 1 and 65534.\n");
+            io.setExitCode(2);
+            return;
+        }
+        let inboxPort;
+        if (options.inboxPort !== undefined) {
+            inboxPort = Number.parseInt(options.inboxPort, 10);
+            if (!Number.isInteger(inboxPort) || inboxPort <= 0 || inboxPort > 65_534) {
+                io.writeErr("--inbox-port must be an integer between 1 and 65534.\n");
+                io.setExitCode(2);
+                return;
+            }
+            if (inboxPort === port) {
+                io.writeErr("--inbox-port must differ from --port (the capture listener is loopback-only; the inbox listener is not).\n");
+                io.setExitCode(2);
+                return;
+            }
+        }
+        await runCommsCatchHost({
+            port,
+            dir: options.dir,
+            ...(options.token ? { token: options.token } : {}),
+            ...(inboxPort === undefined ? {} : { inboxPort }),
+            ...(options.recipient && options.recipient.length > 0 ? { recipients: options.recipient } : {})
+        }, io);
+    });
+}
 function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")