humanish 0.105.0 → 0.106.0

package/dist/lab/init.js

@@ -0,0 +1,287 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { AGENTS_SECTION_MARKER, agentsSection, firstRunGuidance, starterActorFor, starterLocalAgentFor, } from "../cli/first-run-path.js";
+import { detectLocalAgents } from "../actors/local-agent/cli.js";
+import { probeKeySources } from "../keys/key-resolution.js";
+import { DEFAULT_LOCAL_BROWSER_STARTER, runtimeDirectories, starterFilesFor, } from "./init-templates.js";
+import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
+import { validateCwd } from "../run/project.js";
+import { pathExists, readTextIfExists, validateInitProjectPaths } from "./init-paths.js";
+import { planGitignore, planPackageJson } from "./init-plan.js";
+const INIT_RESPONSE_SCHEMA = "humanish.init-result.v1";
+export async function runInit(options) {
+    const requestedCwd = path.resolve(options.cwd);
+    const mode = getMode(options);
+    const plan = { changes: [], warnings: [], writes: [], dirs: [] };
+    const failed = (error) => ({
+        schema: INIT_RESPONSE_SCHEMA,
+        ok: false,
+        mode,
+        cwd: requestedCwd,
+        changes: plan.changes,
+        warnings: plan.warnings,
+        error,
+    });
+    const cwdCheck = await validateCwd(requestedCwd);
+    if (cwdCheck) {
+        return failed(cwdCheck);
+    }
+    const localBrowser = validateLocalBrowserStarter(options.localBrowser);
+    if (!localBrowser.ok) {
+        return failed({ code: "HUMANISH_INVALID_LOCAL_BROWSER", message: localBrowser.message });
+    }
+    const cwd = await realpath(requestedCwd);
+    const preparedProjectRoot = await prepareSelectedOutputDirectory(path.dirname(cwd), cwd);
+    const initialPathCheck = await validateInitProjectPaths(cwd);
+    if (initialPathCheck) {
+        return failed(initialPathCheck);
+    }
+    await planAgentsFile(preparedProjectRoot, cwd, plan);
+    // The starter live lab is written for the brain this machine can actually use. Shipping it as
+    // openai-computer-use on a machine with no provider key but a signed-in Codex would hand someone
+    // a file that asks for a credential they were just told they do not need (#505).
+    const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
+    const starterActor = starterActorFor(machine);
+    await planStarterFiles(preparedProjectRoot, cwd, starterFilesFor(starterActor, localBrowser.value, starterLocalAgentFor(machine)), options.localBrowser !== undefined, plan);
+    await planRuntimeDirectories(preparedProjectRoot, cwd, plan);
+    const gitignorePlan = await planGitignore(preparedProjectRoot, cwd);
+    plan.changes.push(gitignorePlan.change);
+    if (gitignorePlan.write) {
+        plan.writes.push(gitignorePlan.write);
+    }
+    const packagePlan = await planPackageJson(preparedProjectRoot, cwd);
+    plan.changes.push(packagePlan.change);
+    plan.warnings.push(...packagePlan.warnings);
+    if (packagePlan.error) {
+        return failed(packagePlan.error);
+    }
+    if (packagePlan.write) {
+        plan.writes.push(packagePlan.write);
+    }
+    if (mode === "needs-confirmation") {
+        return failed({
+            code: "HUMANISH_CONFIRMATION_REQUIRED",
+            message: "Re-run with --dry-run to inspect or --yes to apply safe generated changes.",
+        });
+    }
+    if (mode === "applied") {
+        const applyPathCheck = await applyInitPlan(preparedProjectRoot, cwd, plan);
+        if (applyPathCheck) {
+            return failed(applyPathCheck);
+        }
+    }
+    return {
+        schema: INIT_RESPONSE_SCHEMA,
+        ok: true,
+        mode,
+        cwd: requestedCwd,
+        changes: plan.changes,
+        warnings: plan.warnings,
+        // Resolved against THIS machine, because a next step that cannot work is worse than none.
+        ...(mode === "applied" ? { nextSteps: firstRunGuidance(machine) } : {}),
+    };
+}
+// Leave instructions for the NEXT agent. AGENTS.md is the cross-vendor convention (agents.md) —
+// Codex, Claude Code, Cursor, Aider and others read it — and increasingly the thing that runs
+// `humanish init` is a coding agent doing setup on someone's behalf. Without this, the agent
+// that arrives tomorrow finds a humanish/ directory and no idea what to do with it.
+//
+// APPEND-ONLY and idempotent: an existing AGENTS.md is a file someone wrote, so humanish adds its
+// own section once and never rewrites theirs.
+async function planAgentsFile(preparedProjectRoot, cwd, plan) {
+    const agentsPath = "AGENTS.md";
+    const existingAgents = await readTextIfExists(preparedProjectRoot, agentsPath);
+    const section = agentsSection();
+    if (existingAgents === null) {
+        plan.changes.push({
+            path: agentsPath,
+            action: "create",
+            target: "source",
+            reason: "how a coding agent runs humanish here",
+        });
+        plan.writes.push({
+            absolutePath: path.join(cwd, agentsPath),
+            relativePath: agentsPath,
+            contents: `# AGENTS.md\n${section}`,
+            target: "source",
+        });
+    }
+    else if (existingAgents.includes(AGENTS_SECTION_MARKER)) {
+        plan.changes.push({
+            path: agentsPath,
+            action: "skip",
+            target: "source",
+            reason: "humanish section already present",
+        });
+    }
+    else {
+        plan.changes.push({
+            path: agentsPath,
+            action: "update",
+            target: "source",
+            reason: "append how a coding agent runs humanish",
+        });
+        plan.writes.push({
+            absolutePath: path.join(cwd, agentsPath),
+            relativePath: agentsPath,
+            contents: `${existingAgents.replace(/\s*$/, "")}\n${section}`,
+            target: "source",
+        });
+    }
+}
+/** Create each starter file that is missing; never overwrite one that exists. */
+async function planStarterFiles(preparedProjectRoot, cwd, files, localBrowserRequested, plan) {
+    for (const file of files) {
+        const absolutePath = path.join(cwd, file.path);
+        const existing = await readTextIfExists(preparedProjectRoot, file.path);
+        if (existing !== null &&
+            localBrowserRequested &&
+            file.path === "humanish/labs/local-browser.yaml") {
+            plan.warnings.push("Skipped --local-browser/--local-mission: humanish/labs/local-browser.yaml already exists and init never overwrites it.");
+        }
+        if (existing === null) {
+            plan.changes.push({
+                path: file.path,
+                action: "create",
+                target: file.plane,
+                reason: "public-safe starter file",
+            });
+            plan.writes.push({
+                absolutePath,
+                relativePath: file.path,
+                contents: file.contents,
+                target: file.plane,
+            });
+        }
+        else if (existing === file.contents) {
+            plan.changes.push({
+                path: file.path,
+                action: "skip",
+                target: file.plane,
+                reason: "already matches starter",
+            });
+        }
+        else {
+            plan.changes.push({
+                path: file.path,
+                action: "skip",
+                target: file.plane,
+                reason: "existing file would not be overwritten",
+            });
+            plan.warnings.push(`Skipped existing ${file.path}; humanish never overwrites user files during init.`);
+        }
+    }
+}
+/** Create each ignored runtime directory that is missing. */
+async function planRuntimeDirectories(preparedProjectRoot, cwd, plan) {
+    for (const directory of runtimeDirectories) {
+        const absolutePath = path.join(cwd, directory.path);
+        const exists = await pathExists(preparedProjectRoot, directory.path);
+        plan.changes.push({
+            path: directory.path,
+            action: exists ? "skip" : "mkdir",
+            target: directory.plane,
+            reason: exists ? "already exists" : "ignored runtime directory",
+        });
+        if (!exists) {
+            plan.dirs.push({ absolutePath, relativePath: directory.path });
+        }
+    }
+}
+/**
+ * Recheck the project paths, then make the planned directories and write the planned files.
+ * Returns the path check's error when the project changed since planning, and writes nothing then.
+ */
+async function applyInitPlan(preparedProjectRoot, cwd, plan) {
+    await assertPreparedSelectedOutputDirectory(preparedProjectRoot);
+    const applyPathCheck = await validateInitProjectPaths(cwd);
+    if (applyPathCheck) {
+        return applyPathCheck;
+    }
+    for (const directory of plan.dirs) {
+        await prepareContainedOutputDirectory(preparedProjectRoot, directory.relativePath);
+    }
+    for (const write of plan.writes) {
+        await writeContainedOutputFile(preparedProjectRoot, write.relativePath, write.contents, "utf8");
+    }
+    return null;
+}
+function validateLocalBrowserStarter(input) {
+    const value = {
+        appUrl: input?.appUrl.trim() || DEFAULT_LOCAL_BROWSER_STARTER.appUrl,
+        mission: input?.mission?.trim() || DEFAULT_LOCAL_BROWSER_STARTER.mission,
+    };
+    let url;
+    try {
+        url = new URL(value.appUrl);
+    }
+    catch {
+        return {
+            ok: false,
+            message: "--local-browser must be a loopback HTTP(S) URL with an explicit port above 1023.",
+        };
+    }
+    if (!["http:", "https:"].includes(url.protocol) ||
+        !["localhost", "127.0.0.1"].includes(url.hostname) ||
+        url.username ||
+        url.password ||
+        Number(url.port) < 1024) {
+        return {
+            ok: false,
+            message: "--local-browser must be a loopback HTTP(S) URL with an explicit port above 1023.",
+        };
+    }
+    if (value.mission.length > 4_000)
+        return { ok: false, message: "--local-mission must be 4,000 characters or fewer." };
+    return { ok: true, value };
+}
+/**
+ * What this machine can run, for the starter lab and the next steps. Local CLI status is
+ * classified without returning its output or reading its credential file. Provider keys go
+ * through the same discovery chain as every other command (process env, the project overlay,
+ * `e2b auth login`, the `humanish keys set` store) and only their presence is read, never a value.
+ * Local authentication status is not a fresh provider/account-validity test.
+ */
+async function firstRunEnvironment(env, cwd) {
+    const agents = await detectLocalAgents({ env }).catch(() => []);
+    const keys = await probeKeySources(["OPENAI_API_KEY", "E2B_API_KEY"], {
+        cwd,
+        env,
+        // The same home as os.homedir() for a real environment; a test's env picks its own. The gh
+        // probe is skipped because init reads no GitHub credential.
+        deps: { ...(env.HOME ? { homeDir: env.HOME } : {}), execText: async () => null },
+    }).catch(() => []);
+    const present = (name) => keys.some((key) => key.name === name && key.source !== null);
+    let hasDesktopSdk = false;
+    try {
+        // Resolution from the PROJECT, not from wherever humanish itself lives.
+        const { createRequire } = await import("node:module");
+        createRequire(path.join(process.cwd(), "package.json")).resolve("@e2b/desktop");
+        hasDesktopSdk = true;
+    }
+    catch {
+        hasDesktopSdk = false;
+    }
+    const { fileURLToPath } = await import("node:url");
+    const here = fileURLToPath(import.meta.url);
+    return {
+        installedInProject: here.startsWith(path.join(process.cwd(), "node_modules") + path.sep),
+        hasDesktopSdk,
+        hasE2bKey: present("E2B_API_KEY"),
+        hasProviderKey: present("OPENAI_API_KEY"),
+        localAgents: agents
+            .filter((agent) => agent.authStatus === "authenticated")
+            .map((agent) => ({ id: agent.id, label: agent.label })),
+        platform: process.platform,
+        arch: process.arch,
+    };
+}
+function getMode(options) {
+    if (options.dryRun) {
+        return "dry-run";
+    }
+    if (options.yes) {
+        return "applied";
+    }
+    return "needs-confirmation";
+}

package/dist/lab/keys.d.ts

@@ -0,0 +1,2 @@
+/** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
+export declare function findUnknownLabKey(raw: unknown): string | undefined;

package/dist/lab/keys.js

@@ -0,0 +1,264 @@
+// Every mapping key parseLabConfig reads, by path. A key that is not listed fails the lab as
+// unknown, so a typo stops the run instead of being dropped. `true` marks a leaf: its parser
+// checks the value (scalars, lists, and mappings that check their own keys). Each level satisfies
+// the parsed type's keys, so a field added to a Lab* interface must be added here too.
+const STOP_WHEN = {
+    any: {
+        id: true,
+        urlIncludes: true,
+        urlPathEquals: true,
+        textIncludes: true,
+        appStatePathEquals: {
+            path: true,
+            equals: true,
+        },
+    },
+};
+const DWELL = {
+    ms: true,
+    everyMs: true,
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` is the documented dwell field of humanish.lab.v2
+    then: true,
+    when: STOP_WHEN,
+};
+const CAPS = {
+    maxUsd: true,
+    maxTotalUsd: true,
+    maxJobs: true,
+    maxMinutes: true,
+};
+const PARTICIPANT_ENTRY = {
+    id: true,
+    actorType: true,
+    surface: true,
+    caseGroup: true,
+    persona: true,
+    device: true,
+    instruction: true,
+    target: true,
+    entry: true,
+    host: true,
+    reasoningEffort: true,
+    stopWhen: STOP_WHEN,
+    dwell: DWELL,
+};
+const SUBJECT = {
+    source: true,
+    topology: true,
+    exposure: true,
+    appUrl: true,
+    repos: true,
+    env: true,
+    envValues: true,
+    clone: { depth: true, fanout: true, keep: true },
+    localTree: {
+        exclude: true,
+        keep: true,
+        maxArchiveBytes: true,
+    },
+    product: {
+        name: true,
+        install: true,
+        workdir: true,
+        upload: true,
+        publicSurfaces: true,
+    },
+    publicTarget: { owner: true, authorized: true },
+    serve: {
+        install: true,
+        installTimeoutMs: true,
+        build: true,
+        buildTimeoutMs: true,
+        start: true,
+        url: true,
+        readyTimeoutMs: true,
+    },
+    state: {
+        seed: {
+            name: true,
+            command: true,
+            when: true,
+            timeoutMs: true,
+        },
+        external: true,
+        checkpoint: {
+            name: true,
+            command: true,
+            redact: true,
+        },
+    },
+};
+const ACTOR = {
+    type: true,
+    count: true,
+    lanes: PARTICIPANT_ENTRY,
+    // Roster groups are lanes with a count; the parser expands them into lanes.
+    roster: { ...PARTICIPANT_ENTRY, count: true },
+    persona: true,
+    mission: true,
+    model: true,
+    maxOutputTokens: true,
+    localAgent: true,
+    reasoningEffort: true,
+    stopWhen: STOP_WHEN,
+    dwell: DWELL,
+    tasks: { id: true, goal: true, success: STOP_WHEN },
+    laneFocus: {
+        id: true,
+        label: true,
+        instruction: true,
+    },
+};
+const EXECUTION = {
+    target: true,
+    runtime: { version: true },
+    runtimeAuth: true,
+    concurrency: true,
+    timeoutMs: true,
+    completionTimeoutMs: true,
+    egressAllow: true,
+    caps: CAPS,
+    terminal: { stdin: true, transport: true },
+    desktop: {
+        template: true,
+        browser: true,
+        device: true,
+        resolution: true,
+        sandboxTimeoutMs: true,
+        codexAppServer: true,
+        // Checks its own keys.
+        recording: true,
+        fidelity: {
+            mobileEmulation: true,
+            deviceScaleFactor: true,
+            touch: true,
+            userAgent: true,
+        },
+        media: {
+            camera: { source: true },
+            microphone: { source: true },
+        },
+    },
+};
+const EMAIL = {
+    kind: true,
+    connection: true,
+    port: true,
+    smtp: {
+        hostEnv: true,
+        portEnv: true,
+        port: true,
+        userEnv: true,
+        user: true,
+        passwordEnv: true,
+        password: true,
+    },
+    external: {
+        catchBaseUrl: true,
+        inboxBaseUrl: true,
+        authTokenEnv: true,
+    },
+    injectEnv: true,
+    linkOrigin: true,
+    allowedOrigins: true,
+    recipients: { lane: true, address: true },
+};
+const LAB_KEYS = {
+    schema: true,
+    id: true,
+    title: true,
+    description: true,
+    subject: SUBJECT,
+    actors: ACTOR,
+    execution: EXECUTION,
+    // Inline personas are validated by the persona resolver.
+    personas: true,
+    scenario: {
+        ref: true,
+        mode: true,
+        inline: true,
+        caps: CAPS,
+    },
+    policies: {
+        redactRepos: true,
+        redactScreenshots: true,
+        allowPublicTargets: true,
+        mediaPermission: true,
+        allowPrivateRepoAccess: true,
+        allowProviderCredentials: true,
+        allowPaymentCredentials: true,
+        allowGitHubMutation: true,
+    },
+    review: {
+        scoring: true,
+        milestones: true,
+        vocabulary: true,
+        scorer: { ref: true },
+        // resolveAutomaticAnalysis checks its own keys.
+        analysis: true,
+    },
+    defaults: { open: true },
+    comms: { email: EMAIL },
+};
+/** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
+export function findUnknownLabKey(raw) {
+    return walk(raw, LAB_KEYS, "");
+}
+function walk(value, shape, path) {
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const found = walk(item, shape, `${path}[${index}]`);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const known = Object.keys(shape);
+    // Object.hasOwn: a key like `constructor` must not match Object.prototype.
+    const unknown = Object.keys(record).filter((key) => !Object.hasOwn(shape, key));
+    if (unknown.length > 0)
+        return unknownKeysMessage(path, unknown, known);
+    for (const [key, child] of Object.entries(record)) {
+        const expected = shape[key];
+        if (expected !== true && expected !== undefined) {
+            const found = walk(child, expected, path ? `${path}.${key}` : key);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function unknownKeysMessage(path, unknown, known) {
+    const named = unknown.map((key) => {
+        const suggestion = closest(key, known);
+        return suggestion ? `${key} (did you mean \`${suggestion}\`?)` : key;
+    });
+    return `Unknown lab field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
+}
+// The known key within edit distance 2, or one that differs only in case.
+function closest(key, known) {
+    let best;
+    for (const name of known) {
+        const distance = name.toLowerCase() === key.toLowerCase()
+            ? 0
+            : editDistance(key.toLowerCase(), name.toLowerCase());
+        if (distance <= 2 && (!best || distance < best.distance))
+            best = { name, distance };
+    }
+    return best?.name;
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}

package/dist/lab/parse/actors.d.ts

@@ -0,0 +1,14 @@
+import type { LabActor, LabParticipantEntry, LabParticipantFocus, LabConfigParseFailure } from "../types.js";
+export declare const PARTICIPANT_ID_PATTERN: RegExp;
+export declare const PARTICIPANT_ID_MAX_CHARS = 40;
+/** The participant entries an actor declares, after roster groups expand into them. The manifest
+ *  spells them `actors[].lanes`. Undefined when the actor declares none. */
+export declare function rosterOf<Entry = LabParticipantEntry>(actor: {
+    readonly lanes?: readonly Entry[];
+} | undefined): readonly Entry[] | undefined;
+/** An actor's per-participant focus on the app-url route. The manifest spells it `laneFocus`. */
+export declare function focusOf(actor: Pick<LabActor, "laneFocus"> | undefined): LabParticipantFocus | undefined;
+export declare function parseActors(raw: unknown): {
+    ok: true;
+    value: LabActor[];
+} | LabConfigParseFailure;