humanish 0.114.0 → 0.116.0

package/dist/cli/findings-text.js

@@ -0,0 +1,169 @@
+// The text of a run's `humanish.analysis-findings.v1` view (findings.ts): the full block `review`
+// and `analyze show` print, and the summary at the end of a live `run`. It reads only the view.
+import path from "node:path";
+import { findingLead } from "../analysis/finding-lead.js";
+import { plural } from "../run/text.js";
+const IMPACT_TEXT = {
+    blocked_task: "blocked task",
+    friction: "friction",
+    recovery: "recovery",
+    uncertain: "uncertain",
+};
+const RECOVERY_TEXT = {
+    recovered: "recovered",
+    not_observed: "no recovery observed",
+    unknown: "recovery unknown",
+};
+/** `+1:05` from milliseconds since the first retained capture. */
+function elapsedText(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const ss = String(seconds % 60).padStart(2, "0");
+    return hours > 0
+        ? `+${hours}:${String(minutes % 60).padStart(2, "0")}:${ss}`
+        : `+${minutes}:${ss}`;
+}
+/** One participant's cited moments: each frame once, at its earliest cited time. */
+function momentsText(evidence) {
+    const frames = new Map();
+    let unframed = 0;
+    for (const entry of evidence) {
+        if (entry.frame === null) {
+            unframed++;
+            continue;
+        }
+        const earlier = frames.get(entry.frame);
+        if (earlier === undefined ||
+            (entry.elapsedMs !== null && (earlier ?? Infinity) > entry.elapsedMs))
+            frames.set(entry.frame, entry.elapsedMs);
+    }
+    const parts = [...frames]
+        .sort(([a], [b]) => a - b)
+        .map(([frame, ms]) => `frame ${frame}${ms === null ? "" : ` at ${elapsedText(ms)}`}`);
+    if (unframed > 0)
+        parts.push(`${plural(unframed, "item")} with no frame`);
+    return parts.join(", ");
+}
+/** The capture files, relative to the run directory, in frame order. */
+function captureFiles(evidence, runRoot) {
+    return [
+        ...new Set(evidence
+            .filter((entry) => entry.capture !== null)
+            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
+            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
+    ];
+}
+function findingLines(finding, runRoot) {
+    const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
+    const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
+    const affectedIds = finding.affected.map((p) => p.streamId);
+    const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
+    const captures = captureFiles(finding.evidence, runRoot);
+    const correction = finding.correction;
+    const lead = findingLead(finding, correction);
+    return [
+        ...(lead === null
+            ? [`${finding.id} ${finding.title}`]
+            : [
+                `${finding.id} ${lead.headline}`,
+                ...(lead.account === null ? [] : [`   ${lead.account}`]),
+                `   evidence: ${finding.title}`,
+            ]),
+        `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
+        `   ${finding.summary}`,
+        `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
+        ...streams.map((streamId) => {
+            const moments = momentsText(finding.evidence.filter((entry) => entry.streamId === streamId));
+            const label = `${labels.get(streamId) ?? streamId}${labels.has(streamId) ? "" : " (cited, not affected)"}`;
+            return `   - ${label}${moments ? `: ${moments}` : ""}`;
+        }),
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+        `   next step: ${finding.nextStep}`,
+        ...(correction === null
+            ? []
+            : [
+                `   human review: ${correction.status}, ${correction.reason}${correction.replacementClaim ? ` Amended claim: ${correction.replacementClaim}` : ""}`,
+            ]),
+    ];
+}
+function designFindingLines(finding, runRoot) {
+    const captures = captureFiles(finding.evidence, runRoot);
+    return [
+        `${finding.id} ${finding.severity}: ${finding.headline}`,
+        `   screen: ${finding.screen}`,
+        `   notice: ${finding.notice}`,
+        `   why it matters: ${finding.whyItMatters}`,
+        `   suggestion: ${finding.suggestion}`,
+        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+    ];
+}
+/** Nothing for an analysis written before design findings. */
+function designSection(view) {
+    const design = view.designFindings;
+    if (design === null)
+        return [];
+    if (design.length === 0)
+        return ["", "design findings: none in the reviewed captures"];
+    return [
+        "",
+        `design findings: ${design.length}, most severe first`,
+        ...design.flatMap((finding, index) => [
+            ...(index === 0 ? [] : [""]),
+            ...designFindingLines(finding, view.runPath ?? ""),
+        ]),
+    ];
+}
+/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
+export function formatFindings(view) {
+    if (view.state !== "ready" && view.state !== "stale")
+        return [`findings: none. ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const model = [view.provider, view.model].filter(Boolean).join(" ");
+    const cost = view.estimatedCostUsd === null ? "" : `, estimated $${view.estimatedCostUsd.toFixed(2)}`;
+    return [
+        `findings: ${view.findings.length} from analysis ${view.analysisId} (${view.status}, ${model}${cost})`,
+        ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
+        ...(view.summary ? [view.summary] : []),
+        ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...designSection(view),
+        ...(view.limitations.length === 0
+            ? []
+            : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
+        ...view.warnings.map((warning) => `warning: ${warning}`),
+        "",
+        `analysis: ${view.path}`,
+    ];
+}
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+export function formatFindingsSummary(view, fullCommand, limit = 3) {
+    if (view.state !== "ready" && view.state !== "stale")
+        return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const shown = view.findings.slice(0, limit);
+    const design = view.designFindings;
+    return [
+        `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
+        ...shown.map((finding) => {
+            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
+            const lead = findingLead(finding, finding.correction);
+            if (lead === null)
+                return `- ${finding.id} ${qualities}: ${finding.title}`;
+            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
+        }),
+        ...(view.findings.length > limit
+            ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
+            : []),
+        ...(design === null
+            ? []
+            : [
+                `design findings: ${design.length === 0 ? "none" : design.length}`,
+                ...design
+                    .slice(0, limit)
+                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
+                ...(design.length > limit
+                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
+                    : []),
+            ]),
+        `all findings: ${fullCommand}`,
+    ];
+}

package/dist/cli/findings.d.ts

@@ -137,10 +137,6 @@ export declare function readRunAnalysis(cwd: string, run: string, analysisId?: s
 export declare function missingRunFindings(cwd: string, run: string): AnalysisFindings;
 /** The findings of a run's selected analysis, or why it has none. */
 export declare function readRunFindings(cwd: string, run: string, analysisId?: string): Promise<AnalysisFindings>;
-/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
-export declare function formatFindings(view: AnalysisFindings): string[];
-/** At most `limit` findings, one line each, and the command that prints all of them. */
-export declare function formatFindingsSummary(view: AnalysisFindings, fullCommand: string, limit?: number): string[];
 /**
  * The end of a live run's human output, after its `analysis:` line: the findings of the analysis
  * the run just completed. Prints nothing for --json, or when the run's analysis did not complete,

package/dist/cli/findings.js

@@ -1,9 +1,11 @@
 // A run's analysis findings for `review`, `analyze show` and the end of a live `run`: the
-// `humanish.analysis-findings.v1` projection and its text. The analysis artifact stays the record;
-// this reads the version `analyze show` selects and never starts an analysis.
+// `humanish.analysis-findings.v1` projection, read from the run. findings-text.ts prints it. The
+// analysis artifact stays the record; this reads the version `analyze show` selects and never
+// starts an analysis.
 import path from "node:path";
-import { admittingMaxCost, costRefusalText } from "../analysis/admission.js";
+import { costRefusal } from "../analysis/admission.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { bySeverity } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
@@ -14,6 +16,7 @@ import { routeOf } from "../study/routing.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText, wantsJson } from "./io.js";
+import { formatFindingsSummary } from "./findings-text.js";
 import { cli } from "./invocation.js";
 export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
@@ -64,20 +67,13 @@ function evidenceOf(finding, analysis, runRoot) {
         ...entry,
     }));
 }
-const SEVERITY_RANK = {
-    major: 0,
-    moderate: 1,
-    minor: 2,
-};
 /** Most severe first; equal severity keeps the analysis order. */
 function designFindingViews(analysis, runRoot) {
     const designFindings = analysis.result?.designFindings;
     if (designFindings === undefined)
         return null;
     const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
-    return [...designFindings]
-        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
-        .map((finding) => ({
+    return bySeverity(designFindings).map((finding) => ({
         id: finding.id,
         headline: finding.headline,
         screen: finding.screen,
@@ -200,8 +196,10 @@ export function analysisFindings(source) {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
     }
-    if (job?.state === "skipped" && job.admission)
-        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${costRefusalText(job.admission)}`, cli(`analyze --run ${source.runId}${source.cwdFlag} --max-cost ${admittingMaxCost(job.admission)}`));
+    if (job?.state === "skipped" && job.admission) {
+        const refusal = costRefusal(job.admission, `--run ${source.runId}${source.cwdFlag}`, cli);
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${refusal.text}`, refusal.command);
+    }
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run says why, and for a cost refusal names the --max-cost that admits it." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
@@ -291,188 +289,6 @@ export async function readRunFindings(cwd, run, analysisId) {
     const source = await readRunAnalysis(cwd, run, analysisId);
     return source ? analysisFindings(source) : missingRunFindings(cwd, run);
 }
-const IMPACT_TEXT = {
-    blocked_task: "blocked task",
-    friction: "friction",
-    recovery: "recovery",
-    uncertain: "uncertain",
-};
-const RECOVERY_TEXT = {
-    recovered: "recovered",
-    not_observed: "no recovery observed",
-    unknown: "recovery unknown",
-};
-/** `+1:05` from milliseconds since the first retained capture. */
-function elapsedText(ms) {
-    const seconds = Math.floor(ms / 1000);
-    const minutes = Math.floor(seconds / 60);
-    const hours = Math.floor(minutes / 60);
-    const ss = String(seconds % 60).padStart(2, "0");
-    return hours > 0
-        ? `+${hours}:${String(minutes % 60).padStart(2, "0")}:${ss}`
-        : `+${minutes}:${ss}`;
-}
-/** One participant's cited moments: each frame once, at its earliest cited time. */
-function momentsText(evidence) {
-    const frames = new Map();
-    let unframed = 0;
-    for (const entry of evidence) {
-        if (entry.frame === null) {
-            unframed++;
-            continue;
-        }
-        const earlier = frames.get(entry.frame);
-        if (earlier === undefined ||
-            (entry.elapsedMs !== null && (earlier ?? Infinity) > entry.elapsedMs))
-            frames.set(entry.frame, entry.elapsedMs);
-    }
-    const parts = [...frames]
-        .sort(([a], [b]) => a - b)
-        .map(([frame, ms]) => `frame ${frame}${ms === null ? "" : ` at ${elapsedText(ms)}`}`);
-    if (unframed > 0)
-        parts.push(`${plural(unframed, "item")} with no frame`);
-    return parts.join(", ");
-}
-/** The capture files, relative to the run directory, in frame order. */
-function captureFiles(evidence, runRoot) {
-    return [
-        ...new Set(evidence
-            .filter((entry) => entry.capture !== null)
-            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
-            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
-    ];
-}
-/**
- * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
- * since the headline and experience describe the claim it replaced. Null before headlines existed.
- */
-function leadOf(finding) {
-    const amended = finding.correction?.status === "amended" ? finding.correction : null;
-    if (finding.headline === null)
-        return null;
-    return amended?.replacementClaim
-        ? { headline: amended.replacementClaim, corrected: true }
-        : { headline: finding.headline, corrected: false };
-}
-function findingLines(finding, runRoot) {
-    const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
-    const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
-    const affectedIds = finding.affected.map((p) => p.streamId);
-    const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
-    const captures = captureFiles(finding.evidence, runRoot);
-    const correction = finding.correction;
-    const lead = leadOf(finding);
-    return [
-        ...(lead === null
-            ? [`${finding.id} ${finding.title}`]
-            : [
-                `${finding.id} ${lead.headline}`,
-                ...(lead.corrected
-                    ? [
-                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
-                    ]
-                    : finding.experience === null
-                        ? []
-                        : [`   ${finding.experience}`]),
-                `   evidence: ${finding.title}`,
-            ]),
-        `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
-        `   ${finding.summary}`,
-        `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
-        ...streams.map((streamId) => {
-            const moments = momentsText(finding.evidence.filter((entry) => entry.streamId === streamId));
-            const label = `${labels.get(streamId) ?? streamId}${labels.has(streamId) ? "" : " (cited, not affected)"}`;
-            return `   - ${label}${moments ? `: ${moments}` : ""}`;
-        }),
-        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
-        `   next step: ${finding.nextStep}`,
-        ...(correction === null
-            ? []
-            : [
-                `   human review: ${correction.status}, ${correction.reason}${correction.replacementClaim ? ` Amended claim: ${correction.replacementClaim}` : ""}`,
-            ]),
-    ];
-}
-function designFindingLines(finding, runRoot) {
-    const captures = captureFiles(finding.evidence, runRoot);
-    return [
-        `${finding.id} ${finding.severity}: ${finding.headline}`,
-        `   screen: ${finding.screen}`,
-        `   notice: ${finding.notice}`,
-        `   why it matters: ${finding.whyItMatters}`,
-        `   suggestion: ${finding.suggestion}`,
-        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
-        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
-    ];
-}
-/** Nothing for an analysis written before design findings. */
-function designSection(view) {
-    const design = view.designFindings;
-    if (design === null)
-        return [];
-    if (design.length === 0)
-        return ["", "design findings: none in the reviewed captures"];
-    return [
-        "",
-        `design findings: ${design.length}, most severe first`,
-        ...design.flatMap((finding, index) => [
-            ...(index === 0 ? [] : [""]),
-            ...designFindingLines(finding, view.runPath ?? ""),
-        ]),
-    ];
-}
-/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
-export function formatFindings(view) {
-    if (view.state !== "ready" && view.state !== "stale")
-        return [`findings: none. ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
-    const model = [view.provider, view.model].filter(Boolean).join(" ");
-    const cost = view.estimatedCostUsd === null ? "" : `, estimated $${view.estimatedCostUsd.toFixed(2)}`;
-    return [
-        `findings: ${view.findings.length} from analysis ${view.analysisId} (${view.status}, ${model}${cost})`,
-        ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
-        ...(view.summary ? [view.summary] : []),
-        ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
-        ...designSection(view),
-        ...(view.limitations.length === 0
-            ? []
-            : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
-        ...view.warnings.map((warning) => `warning: ${warning}`),
-        "",
-        `analysis: ${view.path}`,
-    ];
-}
-/** At most `limit` findings, one line each, and the command that prints all of them. */
-export function formatFindingsSummary(view, fullCommand, limit = 3) {
-    if (view.state !== "ready" && view.state !== "stale")
-        return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
-    const shown = view.findings.slice(0, limit);
-    const design = view.designFindings;
-    return [
-        `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
-        ...shown.map((finding) => {
-            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
-            const lead = leadOf(finding);
-            if (lead === null)
-                return `- ${finding.id} ${qualities}: ${finding.title}`;
-            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
-        }),
-        ...(view.findings.length > limit
-            ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
-            : []),
-        ...(design === null
-            ? []
-            : [
-                `design findings: ${design.length === 0 ? "none" : design.length}`,
-                ...design
-                    .slice(0, limit)
-                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
-                ...(design.length > limit
-                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
-                    : []),
-            ]),
-        `all findings: ${fullCommand}`,
-    ];
-}
 /**
  * The end of a live run's human output, after its `analysis:` line: the findings of the analysis
  * the run just completed. Prints nothing for --json, or when the run's analysis did not complete,

package/dist/cli/io.js

@@ -1,5 +1,5 @@
 import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
-import { admittingMaxCost, costRefusalText, refusedCost, } from "../analysis/admission.js";
+import { costRefusal, refusedCost } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
@@ -186,11 +186,17 @@ export function writeResult(command, io, result, formatHuman) {
     }
     else {
         writeHuman(command, io, formatHuman(output));
-        if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
+        // A run refused before it was created has no analysis to report, so its output ends with the
+        // refusal. Its JSON keeps the skip record.
+        if (output !== null &&
+            typeof output === "object" &&
+            "automaticAnalysis" in output &&
+            output.runId !== "not-created") {
             const analysis = output.automaticAnalysis;
             const cost = analysis?.result?.admission && refusedCost(analysis.result.admission);
-            if (cost)
-                io.writeOut(`analysis: refused before it started. ${refusedAnalysisText(cost, analysis.result?.run ?? "latest")}\n`);
+            const refusal = cost && costRefusal(cost, `--run ${analysis.result?.run ?? "latest"}`, cli);
+            if (refusal)
+                io.writeOut(`analysis: refused before it started. ${refusal.text} ${refusal.command}\n`);
             else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
@@ -306,10 +312,6 @@ export function analysisOutcomeText(analysis) {
         return analysis.state;
     return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
 }
-/** What a refused analysis would cost and the command that runs it with a cap that admits it. */
-function refusedAnalysisText(cost, runId) {
-    return `${costRefusalText(cost)} To run it, raise the cap: ${cli(`analyze --run ${runId} --max-cost ${admittingMaxCost(cost)}`)}`;
-}
 /** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||

package/dist/cli/telemetry.js

@@ -12,9 +12,9 @@
 import { isCuaDiagnosticCategory, isCuaDiagnosticStopCause, } from "../routes/computer-use/diagnostics.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import path from "node:path";
 import { STUDY_RESULT_SCHEMA } from "../run/study-result.js";
+import { envFlag, humanishConfigFile } from "./user-config.js";
 /** Write-only PostHog project key. Public by design: it can ingest, and can read nothing. */
 const INGEST_KEY = "phc_oeMeBqxDZhZ9tCHMSnuDFimLqHpU5Myc847WD33hAh4C";
 const INGEST_HOST = "https://us.i.posthog.com";
@@ -26,26 +26,16 @@ const STARTER_STUDIES = new Set([
     "local-browser",
     "lobby-trivia-3player",
 ]);
-export function telemetryStatePath(env = process.env, home = homedir()) {
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    // Same XDG rule the key store uses: a relative value must be ignored, or state becomes
-    // cwd-relative and follows people between projects.
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "telemetry.json");
+export function telemetryStatePath(env = process.env, home) {
+    return humanishConfigFile(env, "telemetry.json", home);
 }
 /**
  * Off means off, from any of the three switches people already expect: the cross-tool
  * `DO_NOT_TRACK` standard, our own env var, and the persisted opt-out.
  */
 export function disabledByEnvironment(env) {
-    const truthy = (value) => value !== undefined &&
-        value.trim() !== "" &&
-        value.trim() !== "0" &&
-        value.trim().toLowerCase() !== "false";
-    return (truthy(env.DO_NOT_TRACK) ||
-        truthy(env.HUMANISH_TELEMETRY_DISABLED) ||
+    return (envFlag(env.DO_NOT_TRACK) ||
+        envFlag(env.HUMANISH_TELEMETRY_DISABLED) ||
         // Our own development and test runs must never reach the adoption dataset. In the first two
         // days after telemetry shipped, 82% of events (4,042 of 4,932, from 49 of 59 anonymous ids)
         // came from humanish's own CI and suite: ~50 ids each running nearly every subcommand about
@@ -55,7 +45,7 @@ export function disabledByEnvironment(env) {
         // Deliberately not keyed on CI. An adopter running humanish in their pipeline is real usage
         // and stays countable; the `ci` property already separates it, which is what Next.js does.
         // This keys on being inside the humanish source tree, which only we ever are.
-        truthy(env.HUMANISH_DEV));
+        envFlag(env.HUMANISH_DEV));
 }
 /**
  * True when this process is running from a humanish source checkout rather than an install.
@@ -101,7 +91,7 @@ export function inHumanishCheckout(startDir, readFileSyncFn) {
 export function isOwnCheckoutRun(cwd, cliDir, readFileSyncFn) {
     return inHumanishCheckout(cwd, readFileSyncFn) || inHumanishCheckout(cliDir, readFileSyncFn);
 }
-export async function readTelemetryState(env = process.env, home = homedir()) {
+export async function readTelemetryState(env = process.env, home) {
     try {
         const raw = await readFile(telemetryStatePath(env, home), "utf8");
         const parsed = JSON.parse(raw);
@@ -115,7 +105,7 @@ export async function readTelemetryState(env = process.env, home = homedir()) {
         return { enabled: true, anonymousId: randomUUID(), noticed: false };
     }
 }
-export async function writeTelemetryState(state, env = process.env, home = homedir()) {
+export async function writeTelemetryState(state, env = process.env, home) {
     const file = telemetryStatePath(env, home);
     await mkdir(path.dirname(file), { recursive: true });
     await writeFile(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
@@ -162,15 +152,13 @@ export function buildPayload(args) {
         version: args.version,
         os: args.platform ?? process.platform,
         node: (args.nodeVersion ?? process.version).split(".")[0].replace("v", ""),
-        ci: env.CI !== undefined && env.CI !== "" && env.CI !== "0",
+        ci: envFlag(env.CI),
         // A humanish study participant is a real cold install on a machine we do not own, so it emits
         // like any other new adopter and is indistinguishable from one. It is also the exact
         // population we are trying to count, so a busy self-study day reads as an adoption spike.
         // Stamped rather than suppressed, the same shape as `ci`: participant runs stay visible and
         // stay separable, and we keep a genuine measurement of what a cold install does.
-        studyParticipant: env.HUMANISH_STUDY_PARTICIPANT !== undefined &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "" &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "0",
+        studyParticipant: envFlag(env.HUMANISH_STUDY_PARTICIPANT),
     };
     const given = args.properties ?? {};
     if (given.command !== undefined)

package/dist/cli/update-check.js

@@ -4,20 +4,12 @@
 // the command that started it.
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { disabledByEnvironment } from "./telemetry.js";
+import { envFlag, humanishConfigFile } from "./user-config.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
 const REGISTRY_DIST_TAGS = "https://registry.npmjs.org/-/package/humanish/dist-tags";
-/** Next to telemetry.json, under the same XDG rule the key store uses. */
-function updateCachePath(env, home = homedir()) {
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "update-check.json");
-}
 function readUpdateCache(cachePath) {
     try {
         const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
@@ -65,24 +57,23 @@ function dayPassed(timestamp, now) {
     const then = timestamp === undefined ? Number.NaN : Date.parse(timestamp);
     return Number.isNaN(then) || now - then >= DAY_MS;
 }
-const truthy = (value) => value !== undefined &&
-    value.trim() !== "" &&
-    value.trim() !== "0" &&
-    value.trim().toLowerCase() !== "false";
 /**
  * Only a person at a terminal is told, and only when nothing has switched the check off. A pipe,
  * CI and a JSON document have a program reading them. A study participant runs the version the
  * study chose, and a notice would send it to another. The telemetry switches turn this off too:
- * someone who opted out of telemetry expects no unprompted requests.
+ * someone who opted out of telemetry expects no unprompted requests. NO_UPDATE_NOTIFIER is the
+ * switch the update-notifier package reads, and it is read the same way, so any value, even `0`,
+ * turns the check off for someone who set it for the CLIs built on that package.
  */
 function checkAllowed(context) {
     const env = context.env;
     return (context.terminal &&
         !context.json &&
         !context.ownCheckout &&
-        !truthy(env.CI) &&
-        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
-        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !envFlag(env.CI) &&
+        !envFlag(env.HUMANISH_NO_UPDATE_CHECK) &&
+        env.NO_UPDATE_NOTIFIER === undefined &&
+        !envFlag(env.HUMANISH_STUDY_PARTICIPANT) &&
         !disabledByEnvironment(env));
 }
 /**
@@ -94,7 +85,7 @@ export function checkForUpdate(context) {
     try {
         if (!checkAllowed(context))
             return undefined;
-        const cachePath = updateCachePath(context.env, context.home);
+        const cachePath = humanishConfigFile(context.env, "update-check.json", context.home);
         const cache = readUpdateCache(cachePath);
         const stamp = new Date(context.now).toISOString();
         const next = { ...cache };
@@ -126,7 +117,7 @@ export function checkForUpdate(context) {
  * cache only; undefined until a check has succeeded on this machine.
  */
 export function recordedVersion(installed, env, home) {
-    const cache = readUpdateCache(updateCachePath(env, home));
+    const cache = readUpdateCache(humanishConfigFile(env, "update-check.json", home));
     if (cache.latest === undefined)
         return undefined;
     const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;

package/dist/cli/user-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export declare function humanishConfigFile(env: NodeJS.ProcessEnv, fileName: string, home?: string): string;
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export declare function envFlag(value: string | undefined): boolean;

package/dist/cli/user-config.js

@@ -0,0 +1,25 @@
+// Where humanish keeps per-user files (the key store, telemetry state, the update-check cache) and
+// how it reads an on/off environment variable. The key store, telemetry and the update check each
+// had their own copy of both.
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export function humanishConfigFile(env, fileName, home = homedir()) {
+    const declared = env.XDG_CONFIG_HOME?.trim();
+    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
+        ? declared
+        : path.join(home, ".config");
+    return path.join(configHome, "humanish", fileName);
+}
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export function envFlag(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed !== "" && trimmed !== "0" && trimmed.toLowerCase() !== "false";
+}