humanish 0.60.0 → 0.62.0

package/dist/telemetry.d.ts

@@ -0,0 +1,64 @@
+/** The ONLY event names. */
+export type TelemetryEvent = "cli_command" | "project_initialized" | "study_finished";
+export interface TelemetryProperties {
+    command?: string;
+    /** A starter lab id, or "custom" — never an adopter's own lab id. */
+    lab?: string;
+    mode?: "dry-run" | "live";
+    outcome?: string;
+    /** Bucketed, not exact: a duration is a fingerprint at full precision. */
+    durationBucket?: string;
+    /** Which brain ran it, as a route name — never a model id the adopter configured. */
+    brain?: "provider-key" | "local-agent" | "none";
+    ok?: boolean;
+    exitCode?: number;
+}
+export interface TelemetryState {
+    enabled: boolean;
+    /** Random, generated locally, tied to nothing. */
+    anonymousId: string;
+    /** Whether the first-run notice has been shown. */
+    noticed: boolean;
+}
+export declare function telemetryStatePath(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * 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 declare function disabledByEnvironment(env: NodeJS.ProcessEnv): boolean;
+export declare function readTelemetryState(env?: NodeJS.ProcessEnv, home?: string): Promise<TelemetryState>;
+export declare function writeTelemetryState(state: TelemetryState, env?: NodeJS.ProcessEnv, home?: string): Promise<void>;
+/** Coarse enough that a duration cannot fingerprint a session. */
+export declare function durationBucket(ms: number): string;
+/** A lab id only if it is one of ours. An adopter's lab id can name an unannounced product. */
+export declare function safeLabId(lab: string | undefined): string | undefined;
+export interface TelemetryPayload {
+    event: TelemetryEvent;
+    distinct_id: string;
+    properties: Record<string, string | number | boolean>;
+}
+/**
+ * The exact document that would be sent. Built separately from sending so that
+ * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it — "you can read exactly
+ * what we collect" is the part of this convention that makes it honest rather than merely legal.
+ */
+export declare function buildPayload(args: {
+    event: TelemetryEvent;
+    anonymousId: string;
+    version: string;
+    properties?: TelemetryProperties;
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    nodeVersion?: string;
+}): TelemetryPayload;
+/** The notice, shown once, before anything is sent. */
+export declare const TELEMETRY_NOTICE: string;
+export interface SendDeps {
+    fetchFn?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * Fire and forget, bounded, and incapable of affecting the command that triggered it. A tool whose
+ * telemetry can slow down or fail a run has made its users pay for its metrics.
+ */
+export declare function sendTelemetry(payload: TelemetryPayload, deps?: SendDeps): Promise<void>;

package/dist/telemetry.js

@@ -0,0 +1,147 @@
+// Anonymous usage telemetry, on the convention Next.js and the Vercel CLI established: collected by
+// default, disclosed the first time it happens, trivially switched off, and inspectable.
+//
+// WHY IT EXISTS: humanish shipped 61 releases without being able to answer "does anyone get to a
+// working first run". The funnel was broken at the first live run for months and we learned it from
+// an adoption post-mortem, not from data. A tool that cannot see its own activation is guessing.
+//
+// WHAT IT WILL NEVER SEND, and this is stricter than the convention because of what humanish is:
+// no paths, no cwd, no repo names, no URLs, no lab titles or ids that are not our own starter labs,
+// no persona or mission text, no run ids, no evidence, no key values, no key names. A study's
+// subject is the adopter's product and often unannounced; leaking a lab id would leak a roadmap.
+// The allowlist below is the whole vocabulary — anything not on it cannot be sent by construction.
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+/** 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";
+/** The ONLY lab ids that may be named. Ours, shipped by `init`; everything else is "custom". */
+const STARTER_LABS = new Set(["first-run", "try-live", "cua-browser", "lobby-trivia-3player", "oss"]);
+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");
+}
+/**
+ * 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);
+}
+export async function readTelemetryState(env = process.env, home = homedir()) {
+    try {
+        const raw = await readFile(telemetryStatePath(env, home), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            enabled: parsed.enabled !== false,
+            anonymousId: typeof parsed.anonymousId === "string" ? parsed.anonymousId : randomUUID(),
+            noticed: parsed.noticed === true
+        };
+    }
+    catch {
+        return { enabled: true, anonymousId: randomUUID(), noticed: false };
+    }
+}
+export async function writeTelemetryState(state, env = process.env, home = homedir()) {
+    const file = telemetryStatePath(env, home);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+/** Coarse enough that a duration cannot fingerprint a session. */
+export function durationBucket(ms) {
+    if (ms < 1_000)
+        return "<1s";
+    if (ms < 10_000)
+        return "1-10s";
+    if (ms < 60_000)
+        return "10-60s";
+    if (ms < 300_000)
+        return "1-5m";
+    if (ms < 900_000)
+        return "5-15m";
+    return ">15m";
+}
+/** A lab id only if it is one of ours. An adopter's lab id can name an unannounced product. */
+export function safeLabId(lab) {
+    if (lab === undefined)
+        return undefined;
+    return STARTER_LABS.has(lab) ? lab : "custom";
+}
+/**
+ * The exact document that would be sent. Built separately from sending so that
+ * `HUMANISH_TELEMETRY_DEBUG=1` can show it and so tests can assert on it — "you can read exactly
+ * what we collect" is the part of this convention that makes it honest rather than merely legal.
+ */
+export function buildPayload(args) {
+    const env = args.env ?? process.env;
+    const properties = {
+        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"
+    };
+    const given = args.properties ?? {};
+    if (given.command !== undefined)
+        properties.command = given.command;
+    if (given.lab !== undefined)
+        properties.lab = given.lab;
+    if (given.mode !== undefined)
+        properties.mode = given.mode;
+    if (given.outcome !== undefined)
+        properties.outcome = given.outcome;
+    if (given.durationBucket !== undefined)
+        properties.duration = given.durationBucket;
+    if (given.brain !== undefined)
+        properties.brain = given.brain;
+    if (given.ok !== undefined)
+        properties.ok = given.ok;
+    if (given.exitCode !== undefined)
+        properties.exit_code = given.exitCode;
+    return { event: args.event, distinct_id: args.anonymousId, properties };
+}
+/** The notice, shown once, before anything is sent. */
+export const TELEMETRY_NOTICE = [
+    "humanish collects anonymous usage data (which command ran, whether it worked, how long it took).",
+    "It never sends your labs, subjects, personas, paths, or evidence. Opt out any time:",
+    "  humanish telemetry disable        (or set DO_NOT_TRACK=1)",
+    "  humanish telemetry status         shows exactly what is collected"
+].join("\n");
+/**
+ * Fire and forget, bounded, and incapable of affecting the command that triggered it. A tool whose
+ * telemetry can slow down or fail a run has made its users pay for its metrics.
+ */
+export async function sendTelemetry(payload, deps = {}) {
+    const fetchFn = deps.fetchFn ?? globalThis.fetch;
+    if (typeof fetchFn !== "function" || INGEST_KEY.length === 0)
+        return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2_000);
+    try {
+        await fetchFn(`${INGEST_HOST}/i/v0/e/`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                api_key: INGEST_KEY,
+                event: payload.event,
+                distinct_id: payload.distinct_id,
+                properties: payload.properties
+            }),
+            signal: controller.signal
+        });
+    }
+    catch {
+        // Never surfaces. Metrics are our problem, not the operator's.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.60.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.62.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.

package/docs/goals/current.md

@@ -29,7 +29,7 @@ study completed, reproduced, and produced a real accessibility finding via a
 keyboard-first participant
 ([docs/goals/email-gated-signup/receipts/](email-gated-signup/receipts/)).
 
-## Current Program Truth (source `0.60.0`)
+## Current Program Truth (source `0.62.0`)
 
 The package source and repository implementation in this tree agree on these
 points:

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.60.0` (2026-08-31). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.62.0` (2026-08-31). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [