humanish 0.104.3 → 0.106.0

package/dist/feedback/feedback.js

@@ -0,0 +1,282 @@
+// The feedback commands: resolve a run, draft a feedback issue from it, verify the draft, render it
+// as an issue body or URL, and list a run's candidates. What a draft contains is in draft.ts.
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
+import { bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { loadRunBundlePrepared } from "../run/locate.js";
+import { verifyRunPrepared } from "../verify/verify.js";
+import { buildAnalysisDraft, buildDraft, isUsableFeedbackCandidate, renderMarkdown, } from "./draft.js";
+const FEEDBACK_RESULT_SCHEMA = "humanish.feedback-result.v1";
+function summarizeCandidates(bundle) {
+    return bundle.feedbackCandidates
+        .filter((item) => isUsableFeedbackCandidate(item))
+        .map((item) => ({
+        id: item.id,
+        ...(item.stream_id === undefined ? {} : { stream_id: item.stream_id }),
+        persona_id: item.persona_id,
+        failure_owner: item.failure_owner,
+        summary: item.summary,
+    }));
+}
+export async function draftFeedback(cwdInput, runInput, options = {}) {
+    return (await draftFeedbackBound(cwdInput, runInput, options)).result;
+}
+async function draftFeedbackBound(cwdInput, runInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    const context = await resolveFeedbackRunContext(cwd, runInput);
+    if (!context) {
+        return {
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                error: {
+                    code: "HUMANISH_RUN_NOT_FOUND",
+                    message: `Run not found: ${runInput}`,
+                },
+            },
+        };
+    }
+    const verified = await verifyRunPrepared(context.physicalCwd, context.storedRunId, context.preparedRunPaths);
+    await validatePreparedRunArtifactPaths(context.preparedRunPaths);
+    if (!verified.ok) {
+        return {
+            context,
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                error: {
+                    code: "HUMANISH_INVALID_RUN_BUNDLE",
+                    message: verified.error?.message ?? "Run bundle failed verification.",
+                },
+            },
+        };
+    }
+    if (verified.shareSafety.status !== "share_ready") {
+        return {
+            context,
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                shareSafety: verified.shareSafety,
+                error: {
+                    code: "HUMANISH_FEEDBACK_SHARE_SAFETY_BLOCKED",
+                    message: `Run is ${verified.shareSafety.status}, not share_ready: ${verified.shareSafety.reasons.map((reason) => reason.code).join(", ")}`,
+                },
+            },
+        };
+    }
+    const candidates = summarizeCandidates(context.loaded.bundle);
+    if (options.candidate !== undefined &&
+        !candidates.some((item) => item.id === options.candidate)) {
+        return {
+            context,
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                candidates,
+                error: {
+                    code: "HUMANISH_FEEDBACK_CANDIDATE_NOT_FOUND",
+                    message: candidates.length === 0
+                        ? `No feedback candidate on run ${context.storedRunId}; \`--candidate ${options.candidate}\` cannot be drafted.`
+                        : `No feedback candidate \`${options.candidate}\` on run ${context.storedRunId}. Available: ${candidates.map((item) => item.id).join(", ")}.`,
+                },
+            },
+        };
+    }
+    const independent = options.analysis !== undefined || options.finding !== undefined;
+    const draft = independent
+        ? await buildAnalysisDraft(context, options)
+        : buildDraft(context.loaded.bundle, context.loaded.bundlePath, options.candidate);
+    if (!draft)
+        return {
+            context,
+            result: {
+                schema: FEEDBACK_RESULT_SCHEMA,
+                ok: false,
+                cwd,
+                run: runInput,
+                error: {
+                    code: "HUMANISH_INVALID_FEEDBACK_DRAFT",
+                    message: "Select a current valid analysis and finding together, without --candidate. Dismissed findings cannot be promoted into feedback.",
+                },
+            },
+        };
+    const draftPath = path.join(context.preparedRunPaths.relativeRunRoot, "feedback", "draft.json");
+    await writeJson(context.preparedRunPaths, path.join("feedback", "draft.json"), draft);
+    return {
+        context,
+        result: {
+            schema: FEEDBACK_RESULT_SCHEMA,
+            ok: true,
+            cwd,
+            run: runInput,
+            draftPath,
+            draft,
+            candidates,
+        },
+    };
+}
+export async function verifyFeedback(cwdInput, runInput, options = {}) {
+    return (await verifyFeedbackBound(cwdInput, runInput, options)).result;
+}
+async function verifyFeedbackBound(cwdInput, runInput, options = {}) {
+    const drafted = await draftFeedbackBound(cwdInput, runInput, options);
+    if (!drafted.result.ok || !drafted.result.draft || !drafted.context) {
+        return drafted;
+    }
+    const missingEvidence = [];
+    for (const evidence of drafted.result.draft.evidence) {
+        if (!(await isSafeFeedbackEvidenceFile(drafted.context, evidence.path))) {
+            missingEvidence.push(evidence.path);
+        }
+    }
+    if (missingEvidence.length > 0) {
+        return {
+            context: drafted.context,
+            result: {
+                ...drafted.result,
+                ok: false,
+                error: {
+                    code: "HUMANISH_INVALID_FEEDBACK_DRAFT",
+                    message: `Feedback evidence missing: ${missingEvidence.join(", ")}`,
+                },
+            },
+        };
+    }
+    return drafted;
+}
+async function isSafeFeedbackEvidenceFile(context, evidencePath) {
+    const absolute = path.resolve(context.physicalCwd, evidencePath);
+    const relative = path.relative(context.preparedRunPaths.physicalRunRoot, absolute);
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return false;
+    }
+    return (await readContainedRegularFile(context.preparedRunPaths, relative)) !== null;
+}
+export async function renderIssueMarkdown(cwdInput, runInput, repo, options = {}) {
+    const verified = await verifyFeedbackBound(cwdInput, runInput, options);
+    if (!verified.result.ok ||
+        !verified.result.draft ||
+        !verified.result.draftPath ||
+        !verified.context) {
+        return verified.result;
+    }
+    const issueMarkdown = renderMarkdown(verified.result.draft, repo);
+    const issuePath = path.join(verified.context.preparedRunPaths.relativeRunRoot, "feedback", "issue.md");
+    await writeContainedOutputFile(verified.context.preparedRunPaths, path.join("feedback", "issue.md"), issueMarkdown, "utf8");
+    return {
+        ...verified.result,
+        issuePath,
+        issueMarkdown,
+    };
+}
+export async function renderIssueUrl(cwdInput, runInput, repo, options = {}) {
+    const rendered = await renderIssueMarkdown(cwdInput, runInput, repo, options);
+    if (!rendered.ok || !rendered.issueMarkdown || !rendered.draft) {
+        return rendered;
+    }
+    const title = `[humanish] ${rendered.draft.summary}`;
+    return {
+        ...rendered,
+        issueUrl: `https://github.com/${encodeGitHubRepoPath(repo)}/issues/new?title=${encodeURIComponent(title)}&body=${encodeURIComponent(rendered.issueMarkdown)}`,
+    };
+}
+export async function listFeedback(cwdInput, runInput) {
+    const cwd = path.resolve(cwdInput);
+    const context = await resolveFeedbackRunContext(cwd, runInput);
+    if (!context) {
+        return {
+            schema: FEEDBACK_RESULT_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            error: {
+                code: "HUMANISH_RUN_NOT_FOUND",
+                message: `Run not found: ${runInput}`,
+            },
+        };
+    }
+    const draftBytes = await readContainedRegularFile(context.preparedRunPaths, path.join("feedback", "draft.json"));
+    const draft = draftBytes === null ? undefined : JSON.parse(draftBytes.toString("utf8"));
+    const draftPath = path.join(context.preparedRunPaths.relativeRunRoot, "feedback", "draft.json");
+    return {
+        schema: FEEDBACK_RESULT_SCHEMA,
+        ok: true,
+        cwd,
+        run: runInput,
+        ...(draft ? { draftPath, draft } : {}),
+        // The choice set for `draft --candidate`: a three-participant study has up to three findings,
+        // and until #609 only the first ever reached a draft.
+        candidates: summarizeCandidates(context.loaded.bundle),
+    };
+}
+async function resolveFeedbackRunContext(cwd, runInput) {
+    let physicalCwd;
+    try {
+        physicalCwd = await realpath(cwd);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    let storedRunId = runInput;
+    let preparedRunPaths;
+    if (runInput === "latest") {
+        const runsRoot = await bindExistingManagedHumanishOutputDirectory(physicalCwd, "runs");
+        if (!runsRoot)
+            return null;
+        const pointerBytes = await readContainedRegularFile(runsRoot, "latest.json");
+        if (!pointerBytes)
+            return null;
+        const pointer = JSON.parse(pointerBytes.toString("utf8"));
+        if (typeof pointer.runId !== "string" ||
+            typeof pointer.path !== "string" ||
+            !resolveLatestRunDirectory(physicalCwd, { path: pointer.path, runId: pointer.runId })) {
+            return null;
+        }
+        storedRunId = pointer.runId;
+        preparedRunPaths = await bindExistingRunArtifactPaths(physicalCwd, storedRunId);
+        if (preparedRunPaths.physicalRunsRoot !== runsRoot.physicalPath ||
+            preparedRunPaths.runsRootIdentity.birthtimeNs !== runsRoot.identity.birthtimeNs ||
+            preparedRunPaths.runsRootIdentity.dev !== runsRoot.identity.dev ||
+            preparedRunPaths.runsRootIdentity.ino !== runsRoot.identity.ino) {
+            throw new Error("Feedback runs root changed physical destination.");
+        }
+    }
+    else {
+        if (!isSafeRunIdSegment(runInput))
+            return null;
+        const boundRunPaths = await bindExistingRunArtifactPaths(physicalCwd, storedRunId).catch(() => null);
+        if (!boundRunPaths)
+            return null;
+        preparedRunPaths = boundRunPaths;
+    }
+    const loaded = await loadRunBundlePrepared(physicalCwd, preparedRunPaths);
+    if (!loaded)
+        return null;
+    await validatePreparedRunArtifactPaths(preparedRunPaths);
+    return { cwd, loaded, physicalCwd, preparedRunPaths, storedRunId };
+}
+function encodeGitHubRepoPath(repo) {
+    return repo
+        .split("/")
+        .map((part) => encodeURIComponent(part))
+        .join("/");
+}
+async function writeJson(root, relativePath, value) {
+    await writeContainedOutputFile(root, relativePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}

package/dist/feedback/proof.d.ts

@@ -0,0 +1,8 @@
+import type { RunBundle, RunFeedbackCandidate } from "../run/bundle.js";
+/** Commands run from the evidence workspace using an installed humanish CLI. */
+export declare function feedbackProofCommands(runId: string): {
+    verify: string;
+    watch: string;
+};
+/** Legacy command compatibility belongs in the draft, never in the source receipt. */
+export declare function projectFeedbackAcceptanceProof(bundle: RunBundle, candidate: RunFeedbackCandidate): string[];

package/dist/feedback/proof.js

@@ -0,0 +1,56 @@
+import { shellQuote } from "../substrates/shell.js";
+/** Commands run from the evidence workspace using an installed humanish CLI. */
+export function feedbackProofCommands(runId) {
+    // A plain id stays bare so the printed command reads naturally.
+    const argument = /^[a-z0-9][a-z0-9._-]*$/i.test(runId) ? runId : shellQuote(runId);
+    return {
+        verify: `humanish verify --run ${argument} --json`,
+        watch: `humanish watch --run ${argument} --no-open`,
+    };
+}
+/** Legacy command compatibility belongs in the draft, never in the source receipt. */
+export function projectFeedbackAcceptanceProof(bundle, candidate) {
+    if (!isFirstPartyCandidate(bundle, candidate))
+        return [...candidate.acceptance_proof];
+    const commands = feedbackProofCommands(bundle.runId);
+    return candidate.acceptance_proof.map((instruction) => {
+        if (instruction === `pnpm humanish -- verify --run ${bundle.runId} --json`)
+            return commands.verify;
+        if (instruction === `pnpm humanish -- watch --run ${bundle.runId} --no-open`)
+            return commands.watch;
+        return instruction;
+    });
+}
+function isFirstPartyCandidate(bundle, candidate) {
+    if (candidate.run_id !== bundle.runId ||
+        !candidate.stream_id ||
+        !bundle.streams.some((stream) => stream.id === candidate.stream_id))
+        return false;
+    if (candidate.actor === "computer-use" &&
+        candidate.failure_owner === "target-app" &&
+        candidate.proposed_next_state === "study-quality-review" &&
+        candidate.id.startsWith("participant-report-")) {
+        const participantId = candidate.id.slice("participant-report-".length);
+        return (participantId.length > 0 &&
+            candidate.idempotency_key === `humanish:${bundle.runId}:${participantId}:participant-report`);
+    }
+    // Only older bundles from the removed meta-lab carry oss-meta-lab candidates. The check
+    // stays so their proof can still be read.
+    if (candidate.adapter_id !== "oss-meta-lab" ||
+        candidate.actor !== "codex-tui" ||
+        candidate.substrate !== "e2b-desktop")
+        return false;
+    const streamToken = candidate.stream_id
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "artifact";
+    const kinds = [
+        { id: "setup-quality", owner: "actor", next: "setup-quality-review" },
+        { id: "published-cli-app-url", owner: "harness", next: "adapter-hardening" },
+        { id: "study-quality", owner: "actor", next: "study-quality-review" },
+    ];
+    return kinds.some((kind) => candidate.id === `${kind.id}-${streamToken}` &&
+        candidate.failure_owner === kind.owner &&
+        candidate.proposed_next_state === kind.next &&
+        candidate.idempotency_key === `humanish:${bundle.runId}:${candidate.stream_id}:${kind.id}`);
+}

package/dist/guest/bootstrap.d.ts

@@ -0,0 +1,55 @@
+import { type DesktopRecordingConfig } from "../evidence/desktop-recording-types.js";
+import type { Duplex } from "node:stream";
+import { type BrowserControlIdentity } from "../browser-control/protocol.js";
+import { createBrowserControlClient } from "../browser-control/client.js";
+import { type GuestMediaConfig } from "./media-config.js";
+export declare const GUEST_BOOTSTRAP_VERSION = 1;
+export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
+    bytes: number;
+    readyBytes: 1024;
+    initialUrlBytes: 65536;
+    admissionMs: 5000;
+    readyMs: 35000;
+    navigationMs: 30000;
+    paintMs: 5000;
+    connectMs: 3000;
+    port: 5251;
+}>;
+/** Same entry authority as the local desktop's opaque app-port forward. */
+export declare function validateGuestInitialUrl(value: string): string;
+export declare function guestReadyTimeoutMs(initialUrl?: string): number;
+export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Buffer;
+export declare function parseGuestBootstrap(bytes: Buffer, revision: string, ready?: boolean): BrowserControlIdentity;
+/** Own the first frame and continue refusing early bytes until synchronous handoff. */
+export declare class GuestBootstrapReader {
+    private readonly stream;
+    private readonly revision;
+    private readonly signal;
+    private readonly ready;
+    private readonly onFailure;
+    readonly identity: Promise<BrowserControlIdentity>;
+    initialUrl: string | undefined;
+    media: GuestMediaConfig | undefined;
+    recording: DesktopRecordingConfig | undefined;
+    private resolve;
+    private reject;
+    private readonly header;
+    private headerUsed;
+    private body;
+    private used;
+    private admitted;
+    private terminal;
+    private timer;
+    constructor(stream: Duplex, revision: string, signal: AbortSignal, ready?: boolean, onFailure?: () => void, readyTimeoutMs?: number);
+    private data;
+    private error;
+    private end;
+    private abort;
+    private release;
+    private fail;
+    /** Must be followed synchronously by installing the sole next stream owner. */
+    handoff(): void;
+    close(): void;
+}
+/** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
+export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<ReturnType<typeof createBrowserControlClient>>;