@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/commands/init.js

@@ -10,6 +10,9 @@
  *      .git/info/exclude), when Claude Code is in use here;
  *   2. a short marked block in AGENTS.md (and in CLAUDE.md when the repository
  *      keeps one) telling coding agents to run `haystack verify` after a change.
+ *   3. telemetry (init-telemetry.ts, CAPTURE-V1 rule 8): the app's server instrumentation and the CLI dependency it needs,
+ *      the settings proposal and the browser tag, once the user's answers (which app, its origins, consent) are given;
+ *      until then only the telemetry report stops, saying what to ask.
  * It then starts onboarding the app at the base `haystack verify` would use, so
  * the app is usually ready by the first verify. With --notes, the coding agent's
  * notes on how the app runs, signs people in and is used (onboarding-notes.ts)
@@ -22,7 +25,7 @@
  * installed, 6 set up but onboarding stopped before finishing (run init again).
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
@@ -300,6 +303,20 @@ function applyChange(gitRoot, planned) {
         assertNoSymlinkOnPath(gitRoot, planned.target);
     else if (isLink(planned.target))
         throw new Error(`Refusing to write ${planned.target}: it is a symlink.`);
+    if (planned.action === 'delete') {
+        unlinkSync(planned.target);
+        return;
+    }
+    if (planned.run) {
+        const before = existsSync(planned.target) ? readFileSync(planned.target, 'utf8') : '';
+        // Its output goes to stderr: in --json mode stdout carries only the one document.
+        execFileSync(planned.run.argv[0], planned.run.argv.slice(1), { cwd: planned.run.cwd, stdio: ['ignore', 2, 2] });
+        const failed = planned.run.check?.() ?? null;
+        if (failed !== null)
+            throw new Error(`\`${planned.run.argv.join(' ')}\` ran, but ${failed}.`);
+        planned.diff = lineDiff(before, existsSync(planned.target) ? readFileSync(planned.target, 'utf8') : '');
+        return;
+    }
     mkdirSync(dirname(planned.target), { recursive: true });
     writeFileSync(planned.target, planned.content);
 }
@@ -340,12 +357,28 @@ export async function initCommand(options) {
     // Read before anything else, so notes that cannot be used stop init with nothing done.
     const notes = options.notes === undefined ? null : readNotes(options.notes);
     const plan = planInit(gitRoot);
+    // Telemetry is part of onboarding (CAPTURE-V1 rule 8): planned on every run; a missing answer stops only it.
+    const telemetryModule = await import('./init-telemetry.js');
+    const telemetryOptions = { app: options.app, origins: options.origin ?? [], consent: options.consent, urlRewrites: options.urlRewrites };
+    let telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, telemetryOptions);
+    const telemetryFrom = plan.changes.length;
+    plan.changes.push(...telemetryPlan.changes);
+    plan.notices.push(...telemetryPlan.notices);
     let notesWritten = null;
+    let telemetry = null;
+    // Before the apply (a preview, or no login), the report is the preview: what telemetry will do, `received` unchecked (null).
+    const report = () => telemetry ?? telemetryModule.previewTelemetry(telemetryPlan, repository, notes);
+    const showPreview = () => {
+        const preview = telemetryModule.previewTelemetry(telemetryPlan, repository, notes);
+        for (const line of telemetryModule.formatTelemetry(preview.telemetry, preview.steps))
+            say(line);
+        say('');
+    };
     const finish = (status, onboarding, exitCode) => {
         if (options.json) {
             const changes = plan.changes.map(({ path, action, reason, diff }) => ({ path, action, reason, diff }));
             process.stdout.write(`${JSON.stringify(withSchema('init', { status, repository, changes, notices: plan.notices, notes: notesWritten,
-                onboarding }), null, 2)}\n`);
+                onboarding, telemetry: report().telemetry, telemetrySteps: report().steps }), null, 2)}\n`);
         }
         process.exitCode = exitCode;
     };
@@ -354,7 +387,7 @@ export async function initCommand(options) {
         say(chalk.dim('Nothing in this checkout needs changing.'));
     for (const planned of plan.changes) {
         say('');
-        say(`${chalk.bold(planned.action === 'create' ? 'Create' : 'Update')} ${planned.path}: ${planned.reason}`);
+        say(`${chalk.bold(planned.action === 'create' ? 'Create' : planned.action === 'delete' ? 'Delete' : 'Update')} ${planned.path}: ${planned.reason}`);
         for (const line of planned.diff)
             say(`  ${colored(line)}`);
     }
@@ -372,6 +405,7 @@ export async function initCommand(options) {
     catch (error) {
         if (!(error instanceof NotLoggedInError))
             throw error;
+        showPreview();
         say(chalk.yellow('Not logged in, so nothing was changed. Run `haystack login`, then `haystack init` again.'));
         finish('login-required', null, EXIT_CODES['login-required']);
         return;
@@ -379,15 +413,50 @@ export async function initCommand(options) {
     if (plan.changes.length > 0 && !options.yes) {
         const interactive = !options.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
         if (!interactive || !await confirmed()) {
+            showPreview();
             say('Nothing was changed. Run `haystack init --yes` to make these changes.');
             finish('planned', null, EXIT_CODES.planned);
             return;
         }
     }
+    // Browser capture's registration (rule 8b), which the preview announced: checked with Haystack now, and when the files
+    // need a new key the telemetry changes are planned again with it (or without capture's, when it is refused).
+    const approved = options.yes === true || plan.changes.length > 0;
+    const capture = telemetryPlan.captureRegistration
+        ? await telemetryModule.prepareCapture(telemetryPlan.captureRegistration, token, say, approved) : null;
+    if (capture?.replan) {
+        telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, { ...telemetryOptions, registration: capture.replan });
+        plan.changes.splice(telemetryFrom, plan.changes.length - telemetryFrom, ...telemetryPlan.changes);
+    }
+    // All or nothing: a change that fails (an install that does not end as planned) restores every file the changes
+    // touched, so no edit is left referencing what was never installed.
+    // Bytes, not text: a lockfile can be binary (bun.lockb).
+    const before = new Map();
     for (const planned of plan.changes) {
-        applyChange(gitRoot, planned);
-        say(chalk.green(`✓ ${planned.action === 'create' ? 'Created' : 'Updated'} ${planned.path}`));
+        for (const path of [planned.target, ...(planned.run?.touches ?? [])]) {
+            if (!before.has(path))
+                before.set(path, existsSync(path) ? readFileSync(path) : null);
+        }
     }
+    try {
+        for (const planned of plan.changes) {
+            applyChange(gitRoot, planned);
+            say(chalk.green(`✓ ${planned.action === 'create' ? 'Created' : planned.action === 'delete' ? 'Deleted' : 'Updated'} ${planned.path}`));
+        }
+    }
+    catch (error) {
+        for (const [path, content] of before) {
+            if (content !== null)
+                writeFileSync(path, content);
+            else if (existsSync(path))
+                unlinkSync(path);
+        }
+        await capture?.rollback(say);
+        throw new Error(`${error instanceof Error ? error.message : String(error)} Every file init changed was restored; nothing was changed.`);
+    }
+    const captureFollowUp = await capture?.finish(say);
+    if (captureFollowUp)
+        telemetryPlan.capture = telemetryModule.withCaptureStep(telemetryPlan.capture, captureFollowUp);
     let onboarding;
     try {
         // The notes first: onboarding plans from the facts it starts with, and new notes are new facts (a new onboarding).
@@ -411,6 +480,10 @@ export async function initCommand(options) {
     reportOnboardingState(onboarding);
     say(formatOnboarding(onboarding));
     say('');
+    telemetry = await telemetryModule.telemetryReport(telemetryPlan, { repository, token, onboarding, notes });
+    for (const line of telemetryModule.formatTelemetry(telemetry.telemetry, telemetry.steps))
+        say(line);
+    say('');
     if (onboarding.state === 'ready')
         say(chalk.green('Ready. After your next change, run `haystack verify`.'));
     else if (onboarding.state === 'onboarding') {

package/dist/commands/server-telemetry-contract.d.ts

@@ -0,0 +1,66 @@
+/** FIXED CONTRACT — mirror of CAPTURE-V1 Part B (rule 9, server telemetry sampler 5) and rule 13(b)
+ * (infra/lambda/haystack-design-verifier-shared/capture_contracts.ts) for the published CLI, whose build cannot import
+ * repository files outside src. The source file wins. The customer runtime (src/assets/telemetry/runtime.cjs) receives
+ * these constants and the category vocabulary from serverRuntimeContract() when the runtime is authenticated, so the
+ * runtime holds no copy of its own. */
+export declare const SERVER_SAMPLER_VERSION = 5;
+export declare const SERVER_SAMPLE_AFTER_CALLS = 4096;
+export declare const SERVER_SAMPLE_RATE = 64;
+export declare const SERVER_OBSERVATIONS_PER_SECOND = 20000;
+export declare const SERVER_FIELDS_PER_SITE = 48;
+export declare const SERVER_BUILD_OVERHEAD_PERCENT = 15;
+export declare const SERVER_SEND_TIMEOUT_MS = 10000;
+export declare const SERVER_EXIT_FLUSH_MS = 2000;
+export declare const SERVER_RUNTIME_MAX_BYTES: number;
+export declare const SETTINGS_MAX_DOMAIN = 32;
+export declare const SETTINGS_MAX_LITERAL_CHARS = 32;
+export declare const SIZE_BUCKETS: readonly ["0", "1", "2-5", "6-20", "21-100", "101+"];
+export declare const MAGNITUDE_BUCKETS: readonly ["0", "<1", "1-9", "10-99", "100-999", "1000+"];
+export declare const SERVER_VALUE_CATEGORIES: readonly ["undefined", "null", "boolean", "bigint", "symbol", "function", "object", "error", "opaque", "overflow", "string:0", "string:1", "string:2-5", "string:6-20", "string:21-100", "string:101+", "array:0", "array:1", "array:2-5", "array:6-20", "array:21-100", "array:101+", "map:0", "map:1", "map:2-5", "map:6-20", "map:21-100", "map:101+", "set:0", "set:1", "set:2-5", "set:6-20", "set:21-100", "set:101+", "number:0", "number:nonfinite", "number:+<1", "number:+1-9", "number:+10-99", "number:+100-999", "number:+1000+", "number:-<1", "number:-1-9", "number:-10-99", "number:-100-999", "number:-1000+"];
+export declare const SERVER_BRANCH_CATEGORIES: readonly ["true", "false", "overflow"];
+export declare const SERVER_FIELD_STATES: readonly ["present", "missing", "null", "undefined", "opaque"];
+export declare const SERVER_SETTING_CATEGORY_PREFIX: "setting:";
+export declare const SERVER_SETTING_OTHER: "other";
+export declare const SERVER_FIELD_NAME_PATTERN: RegExp;
+export declare const SETTINGS_FILE_PATH: ".haystack/telemetry-settings.json";
+export declare const SETTINGS_PROPOSAL_PATH: ".haystack/telemetry-settings.proposed.json";
+export type SettingLiteral = string | number | boolean;
+export interface TelemetrySettingsEntryV1 {
+    sourcePath: string;
+    qualifiedName: string;
+    label: string;
+    domain: SettingLiteral[];
+}
+export interface TelemetrySettingsFileV1 {
+    version: 1;
+    settings: TelemetrySettingsEntryV1[];
+}
+export declare const SETTINGS_REFUSED_WORDS: readonly ["id", "email", "name", "token", "password", "key", "secret", "address", "phone"];
+export declare const SETTINGS_REFUSED_LITERAL_PATTERNS: readonly ["@", "[0-9]{6,}", "[0-9A-Fa-f]{16,}", "[A-Za-z0-9+/=_]{24,}"];
+export interface TelemetrySettingsProposal {
+    /** Where the proposal was written (SETTINGS_PROPOSAL_PATH): never read as approval. */
+    path: string;
+    /** The allowlist `haystack telemetry settings --approve` promotes it into (SETTINGS_FILE_PATH). */
+    approvedPath: string;
+    file: TelemetrySettingsFileV1;
+    added: TelemetrySettingsEntryV1[];
+    refused: Array<{
+        sourcePath: string;
+        qualifiedName: string;
+        label: string;
+        why: string;
+    }>;
+    typedSource: boolean;
+}
+/** What runtime.cjs reads as CONTRACT: the constants it enforces and every category string it may count, prebuilt so a
+ * classified call concatenates nothing. */
+export declare function serverRuntimeContract(): Record<string, unknown>;
+/** Rule 9(c): an approvable literal is a boolean, a safe integer, or a string of 1 to SETTINGS_MAX_LITERAL_CHARS
+ * printable characters (no control characters, no lone surrogates), so its category `setting:<JSON>` has exactly one
+ * spelling that the runtime, the ingestion and the readers all produce. Null when it is approvable. */
+export declare function settingLiteralProblem(literal: unknown): string | null;
+/** The category of an approved literal: exactly `setting:` and its JSON. */
+export declare function settingCategory(literal: SettingLiteral): string;
+/** Rule 9(c): why a setting must not be recorded as its literals, or null. `names` are the parameter or binding and the
+ * type it is declared with; classification against the contract's fixed word list, never fuzzy matching of data. */
+export declare function settingRefusal(names: string[], domain: SettingLiteral[]): string | null;

package/dist/commands/server-telemetry-contract.js

@@ -0,0 +1,127 @@
+/** FIXED CONTRACT — mirror of CAPTURE-V1 Part B (rule 9, server telemetry sampler 5) and rule 13(b)
+ * (infra/lambda/haystack-design-verifier-shared/capture_contracts.ts) for the published CLI, whose build cannot import
+ * repository files outside src. The source file wins. The customer runtime (src/assets/telemetry/runtime.cjs) receives
+ * these constants and the category vocabulary from serverRuntimeContract() when the runtime is authenticated, so the
+ * runtime holds no copy of its own. */
+export const SERVER_SAMPLER_VERSION = 5;
+export const SERVER_SAMPLE_AFTER_CALLS = 4_096;
+export const SERVER_SAMPLE_RATE = 64;
+export const SERVER_OBSERVATIONS_PER_SECOND = 20_000;
+export const SERVER_FIELDS_PER_SITE = 48;
+export const SERVER_BUILD_OVERHEAD_PERCENT = 15;
+export const SERVER_SEND_TIMEOUT_MS = 10_000;
+export const SERVER_EXIT_FLUSH_MS = 2_000;
+export const SERVER_RUNTIME_MAX_BYTES = 32 * 1024 * 1024;
+export const SETTINGS_MAX_DOMAIN = 32;
+export const SETTINGS_MAX_LITERAL_CHARS = 32;
+export const SIZE_BUCKETS = ['0', '1', '2-5', '6-20', '21-100', '101+'];
+export const MAGNITUDE_BUCKETS = ['0', '<1', '1-9', '10-99', '100-999', '1000+'];
+export const SERVER_VALUE_CATEGORIES = [
+    'undefined', 'null', 'boolean', 'bigint', 'symbol', 'function', 'object', 'error', 'opaque', 'overflow',
+    'string:0', 'string:1', 'string:2-5', 'string:6-20', 'string:21-100', 'string:101+',
+    'array:0', 'array:1', 'array:2-5', 'array:6-20', 'array:21-100', 'array:101+',
+    'map:0', 'map:1', 'map:2-5', 'map:6-20', 'map:21-100', 'map:101+',
+    'set:0', 'set:1', 'set:2-5', 'set:6-20', 'set:21-100', 'set:101+',
+    'number:0', 'number:nonfinite',
+    'number:+<1', 'number:+1-9', 'number:+10-99', 'number:+100-999', 'number:+1000+',
+    'number:-<1', 'number:-1-9', 'number:-10-99', 'number:-100-999', 'number:-1000+',
+];
+export const SERVER_BRANCH_CATEGORIES = ['true', 'false', 'overflow'];
+export const SERVER_FIELD_STATES = ['present', 'missing', 'null', 'undefined', 'opaque'];
+export const SERVER_SETTING_CATEGORY_PREFIX = 'setting:';
+export const SERVER_SETTING_OTHER = 'other';
+export const SERVER_FIELD_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/;
+export const SETTINGS_FILE_PATH = '.haystack/telemetry-settings.json';
+export const SETTINGS_PROPOSAL_PATH = '.haystack/telemetry-settings.proposed.json';
+export const SETTINGS_REFUSED_WORDS = ['id', 'email', 'name', 'token', 'password', 'key', 'secret', 'address', 'phone'];
+export const SETTINGS_REFUSED_LITERAL_PATTERNS = ['@', '[0-9]{6,}', '[0-9A-Fa-f]{16,}', '[A-Za-z0-9+/=_]{24,}'];
+/** What runtime.cjs reads as CONTRACT: the constants it enforces and every category string it may count, prebuilt so a
+ * classified call concatenates nothing. */
+export function serverRuntimeContract() {
+    const sized = (prefix) => SIZE_BUCKETS.map(bucket => `${prefix}:${bucket}`);
+    const signed = (sign) => MAGNITUDE_BUCKETS.slice(1).map(bucket => `number:${sign}${bucket}`);
+    const categories = {
+        undefined: 'undefined', null: 'null', boolean: 'boolean', bigint: 'bigint', symbol: 'symbol', function: 'function',
+        object: 'object', error: 'error', opaque: 'opaque', overflow: 'overflow', other: SERVER_SETTING_OTHER,
+        true: 'true', false: 'false',
+        string: sized('string'), array: sized('array'), map: sized('map'), set: sized('set'),
+        numberZero: 'number:0', numberNonfinite: 'number:nonfinite', numberPositive: signed('+'), numberNegative: signed('-'),
+    };
+    // Every string the runtime can emit is in the vocabulary (a broken mirror fails the build that writes the runtime,
+    // never a customer's process).
+    const vocabulary = new Set([...SERVER_VALUE_CATEGORIES, ...SERVER_BRANCH_CATEGORIES, SERVER_SETTING_OTHER]);
+    for (const value of Object.values(categories).flat()) {
+        if (!vocabulary.has(value))
+            throw new Error(`Telemetry runtime category ${value} is not in the contract's vocabulary`);
+    }
+    return {
+        SERVER_SAMPLER_VERSION, SERVER_SAMPLE_AFTER_CALLS, SERVER_SAMPLE_RATE, SERVER_OBSERVATIONS_PER_SECOND,
+        SERVER_FIELDS_PER_SITE, SERVER_SEND_TIMEOUT_MS, SERVER_EXIT_FLUSH_MS, SERVER_RUNTIME_MAX_BYTES,
+        SETTINGS_MAX_DOMAIN, SETTINGS_MAX_LITERAL_CHARS, SERVER_FIELD_STATES, SERVER_SETTING_CATEGORY_PREFIX,
+        SERVER_FIELD_NAME_PATTERN: SERVER_FIELD_NAME_PATTERN.source,
+        categories,
+    };
+}
+/** Rule 9(c): an approvable literal is a boolean, a safe integer, or a string of 1 to SETTINGS_MAX_LITERAL_CHARS
+ * printable characters (no control characters, no lone surrogates), so its category `setting:<JSON>` has exactly one
+ * spelling that the runtime, the ingestion and the readers all produce. Null when it is approvable. */
+export function settingLiteralProblem(literal) {
+    if (typeof literal === 'boolean')
+        return null;
+    if (typeof literal === 'number')
+        return Number.isSafeInteger(literal) ? null : 'a number literal is not a safe integer';
+    if (typeof literal !== 'string')
+        return 'a literal is not a boolean, an integer or a string';
+    if (literal.length < 1 || literal.length > SETTINGS_MAX_LITERAL_CHARS) {
+        return `a literal is not 1 to ${SETTINGS_MAX_LITERAL_CHARS} characters`;
+    }
+    for (let index = 0; index < literal.length; index++) {
+        const code = literal.charCodeAt(index);
+        if (code < 0x20 || (code >= 0xd800 && code <= 0xdfff))
+            return 'a literal has a control character or a lone surrogate';
+    }
+    return null;
+}
+/** The category of an approved literal: exactly `setting:` and its JSON. */
+export function settingCategory(literal) {
+    return `${SERVER_SETTING_CATEGORY_PREFIX}${JSON.stringify(literal)}`;
+}
+function words(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .split(/[^A-Za-z]+/)
+        .filter(Boolean)
+        .map(word => word.toLowerCase());
+}
+const REFUSED_WORDS = new Set(SETTINGS_REFUSED_WORDS);
+const REFUSED_LITERALS = SETTINGS_REFUSED_LITERAL_PATTERNS.map(pattern => new RegExp(pattern));
+/** Rule 9(c): why a setting must not be recorded as its literals, or null. `names` are the parameter or binding and the
+ * type it is declared with; classification against the contract's fixed word list, never fuzzy matching of data. */
+export function settingRefusal(names, domain) {
+    for (const name of names) {
+        const hit = words(name).find(word => REFUSED_WORDS.has(word));
+        if (hit)
+            return `the name ${name} looks like identity or a secret (${hit})`;
+    }
+    if (domain.length === 0)
+        return 'no literal domain';
+    const strings = domain.filter(literal => typeof literal !== 'boolean');
+    if (strings.length > SETTINGS_MAX_DOMAIN)
+        return `more than ${SETTINGS_MAX_DOMAIN} literals`;
+    for (const literal of domain) {
+        const problem = settingLiteralProblem(literal);
+        if (problem)
+            return problem;
+        if (typeof literal === 'boolean')
+            continue;
+        const text = String(literal);
+        const hit = words(text).find(word => REFUSED_WORDS.has(word));
+        if (hit)
+            return `the literal ${JSON.stringify(literal)} looks like identity or a secret (${hit})`;
+        if (REFUSED_LITERALS.some(pattern => pattern.test(text))) {
+            return `the literal ${JSON.stringify(literal)} looks like identity or a secret`;
+        }
+    }
+    return null;
+}

package/dist/commands/telemetry-token.js

@@ -0,0 +1,238 @@
+/**
+ * `haystack telemetry token --repo <owner/name> [--rotate] [--out <file>]`: a person mints the server-telemetry ingest
+ * token for one repository's production (CAPTURE-V1 rule 8c; telemetry_token_contracts.ts).
+ *
+ * The token is a production credential, so only a person issues it: the command runs only in an interactive terminal
+ * and asks first, the route needs admin or maintain permission on the repository, and the auth proxy refuses an hsk_live
+ * (automation) login. init and coding agents never run it; init tells the agent to ask its user to.
+ *
+ * Custody: this command generates the token (32 random bytes), writes it to a new file only the person can read (0600, in
+ * a 0700 directory) BEFORE Haystack records anything, and sends only its SHA-256. The token is never printed, logged,
+ * piped or sent: Haystack stores the hash, the ingestion endpoint authenticates by it, and the plaintext exists only in
+ * that file until the person moves it into production's environment. A rerun mints nothing while a token is active and
+ * says whether the file here holds it; --rotate replaces it, and the old token stops authenticating in the same write.
+ * A run holds `<file>.lock` from its first read to its last write, so concurrent runs cannot leave the file holding a
+ * revoked token. When the request's outcome is unknown (no answer, a server error), the token stays in its 0600 pending
+ * file and the next run keeps it if it became active, else removes it; only a refusal removes it at once.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import chalk from 'chalk';
+import { resolveAuthContext } from '../utils/auth.js';
+import { classifyHttpError, HaystackApiError } from '../utils/haystack-api.js';
+import { gatewayFetch } from './case-batch.js';
+import { TELEMETRY_ENVIRONMENT, TELEMETRY_SERVER_STATUS_PATH, TELEMETRY_TOKEN_PATH, TELEMETRY_TOKEN_SHA256, TELEMETRY_TOKEN_VERSION, } from './capture-contract.js';
+/** GitHub's owner and repository name alphabets. */
+const REPOSITORY = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9_.-]{1,100})$/u;
+function sha256(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+function parseAnswer(value, repository) {
+    const answer = value;
+    if (!answer || answer.version !== TELEMETRY_TOKEN_VERSION || (answer.status !== 'minted' && answer.status !== 'active')
+        || typeof answer.repository !== 'string' || answer.repository.toLowerCase() !== repository.toLowerCase()
+        || answer.environment !== TELEMETRY_ENVIRONMENT || typeof answer.endpoint !== 'string' || typeof answer.createdAt !== 'string'
+        || typeof answer.tokenSha256 !== 'string' || !TELEMETRY_TOKEN_SHA256.test(answer.tokenSha256)) {
+        throw new Error(`Haystack answered the token request with something that is not a ${TELEMETRY_TOKEN_VERSION} answer for ${repository}.`);
+    }
+    return answer;
+}
+async function confirmed(question) {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await prompt.question(question)).trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+/** GET the repository's server-telemetry status: its active token's hash, the endpoint, the newest flush. */
+export async function readTelemetryServerStatus(repository, token) {
+    const path = `${TELEMETRY_SERVER_STATUS_PATH}?repository=${encodeURIComponent(repository)}`;
+    const response = await gatewayFetch(path, token);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${TELEMETRY_SERVER_STATUS_PATH}`);
+    const value = await response.json();
+    const flush = value?.newestFlush;
+    const active = value?.token;
+    if (!value || value.version !== TELEMETRY_TOKEN_VERSION || typeof value.repository !== 'string' || typeof value.endpoint !== 'string'
+        || value.repository.toLowerCase() !== repository.toLowerCase() || value.environment !== TELEMETRY_ENVIRONMENT
+        || !(active === null || (typeof active?.tokenSha256 === 'string' && TELEMETRY_TOKEN_SHA256.test(active.tokenSha256) && typeof active.createdAt === 'string'))
+        || !(flush === null || (typeof flush?.storedAt === 'string' && typeof flush.buildId === 'string'))) {
+        throw new Error(`Haystack API ${TELEMETRY_SERVER_STATUS_PATH} answered something that is not a ${TELEMETRY_TOKEN_VERSION} status for ${repository}.`);
+    }
+    return value;
+}
+function activeElsewhere(repository, active, file) {
+    console.log(chalk.yellow(`${repository} already has an active telemetry token (minted ${active.createdAt}, SHA-256 `
+        + `${active.tokenSha256.slice(0, 12)}…), and ${file} does not hold it.`));
+    console.log('Nothing was minted. If production already has that token, nothing more is needed. If it is lost, run this command again '
+        + 'with --rotate: the new token replaces it, and the old one stops working at once.');
+    process.exitCode = 3;
+}
+function environmentLines(endpoint, file) {
+    return [
+        'Set these in production\'s server environment (never a public or client-side variable), then restart it:',
+        '  HAYSTACK_TELEMETRY=1',
+        `  HAYSTACK_TELEMETRY_ENDPOINT=${endpoint}`,
+        `  HAYSTACK_TELEMETRY_TOKEN=<the contents of ${file}>`,
+        'HAYSTACK_TELEMETRY=0 turns server telemetry off again at the next restart.',
+    ];
+}
+/** True when process `pid` is running (EPERM: it runs as someone else). */
+function running(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** Exclusive use of `file` for this run (`<file>.lock`, created exclusively, naming this process), so two runs can never
+ * interleave a mint with a rename and leave the file holding a token the other run revoked. A lock whose process is gone
+ * is taken over. Returns the release. */
+function lockTokenFile(file) {
+    const lock = `${file}.lock`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+            return () => unlinkSync(lock);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const holder = Number(readFileSync(lock, 'utf8'));
+            if (Number.isSafeInteger(holder) && holder > 0 && running(holder)) {
+                throw new Error(`Another \`haystack telemetry token\` (process ${holder}) is writing ${file}; wait for it to finish.`);
+            }
+            unlinkSync(lock);
+        }
+    }
+    throw new Error(`Could not take ${lock}.`);
+}
+/** Tokens a run left beside `file` because its answer was lost (`<file>.<random>.pending`). */
+function pendingTokens(file) {
+    const prefix = `${basename(file)}.`;
+    return readdirSync(dirname(file)).filter(name => name.startsWith(prefix) && name.endsWith('.pending')).map(name => join(dirname(file), name));
+}
+/** A failure after which Haystack provably recorded nothing: it answered and refused (4xx), before or by the write. */
+function provenNotRecorded(error) {
+    return error instanceof HaystackApiError && error.status >= 400 && error.status < 500;
+}
+export async function telemetryTokenCommand(options) {
+    const match = options.repo === undefined ? null : REPOSITORY.exec(options.repo);
+    if (!match)
+        throw new Error('Name the repository: `haystack telemetry token --repo <owner/name>`.');
+    const repository = options.repo;
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        throw new Error('Run `haystack telemetry token` yourself, in your own terminal: it creates a production credential, so a coding agent '
+            + 'or a script never runs it.');
+    }
+    const [, owner, name] = match;
+    const file = resolve(options.out ?? join(homedir(), '.haystack', 'telemetry-ingest-tokens', `${owner}__${name}-${TELEMETRY_ENVIRONMENT}.token`));
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner, repo: name });
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const release = lockTokenFile(file);
+    try {
+        await mintUnderLock(repository, file, auth.token, options);
+    }
+    finally {
+        release();
+    }
+}
+async function mintUnderLock(repository, file, authToken, options) {
+    // An earlier run's token whose answer was lost is settled first: the active token (that run's mint went through, so
+    // this file becomes it) or not (it never authenticated, or no longer does: removed).
+    const pending = pendingTokens(file);
+    if (pending.length > 0) {
+        const status = await readTelemetryServerStatus(repository, authToken);
+        for (const path of pending) {
+            if (status.token !== null && sha256(readFileSync(path, 'utf8')) === status.token.tokenSha256) {
+                renameSync(path, file);
+                chmodSync(file, 0o600);
+                console.log(chalk.green(`An earlier run's token for ${status.repository} did become active (minted ${status.token.createdAt}); ${file} now holds it.`));
+            }
+            else {
+                unlinkSync(path);
+            }
+        }
+    }
+    if (!options.rotate) {
+        // While a token is active nothing is minted: the file either holds it (nothing to do) or does not (--rotate replaces
+        // it). With none active, a stale default file (this command's own) is replaced; a file named with --out never is.
+        const status = await readTelemetryServerStatus(repository, authToken);
+        const held = existsSync(file) ? sha256(readFileSync(file, 'utf8')) : null;
+        if (status.token !== null && status.token.tokenSha256 === held) {
+            console.log(chalk.green(`${status.repository} already has an active telemetry token (minted ${status.token.createdAt}); ${file} holds it.`));
+            for (const line of environmentLines(status.endpoint, file))
+                console.log(line);
+            console.log(chalk.dim('Nothing was minted. `--rotate` replaces the token.'));
+            return;
+        }
+        if (status.token !== null) {
+            activeElsewhere(status.repository, status.token, file);
+            return;
+        }
+        if (options.out !== undefined && held !== null) {
+            throw new Error(`${file} exists and holds no active token of ${repository}. Name a new file with --out, or remove that one.`);
+        }
+    }
+    console.log(`${options.rotate ? 'Replace' : 'Mint'} the server-telemetry ingest token for ${chalk.bold(repository)} (${TELEMETRY_ENVIRONMENT}).`);
+    console.log(chalk.dim(`The token is written to ${file} (readable only by you) and never printed; Haystack keeps only its SHA-256.`));
+    if (options.rotate)
+        console.log(chalk.yellow('The active token stops working as soon as this one is minted.'));
+    if (!await confirmed('Continue? [y/N] ')) {
+        console.log('Nothing was minted.');
+        process.exitCode = 2;
+        return;
+    }
+    const token = randomBytes(32).toString('hex');
+    const tokenSha256 = sha256(token);
+    // The file first: Haystack never records a hash whose token was not saved.
+    const pendingPath = `${file}.${randomBytes(6).toString('hex')}.pending`;
+    writeFileSync(pendingPath, token, { flag: 'wx', mode: 0o600 });
+    chmodSync(pendingPath, 0o600);
+    let answer;
+    try {
+        const request = { repository, tokenSha256, rotate: options.rotate === true };
+        const response = await gatewayFetch(`${TELEMETRY_TOKEN_PATH}?repository=${encodeURIComponent(repository)}`, authToken, {
+            method: 'POST', body: JSON.stringify(request),
+        });
+        if (!response.ok)
+            throw await classifyHttpError(response, `Haystack API ${TELEMETRY_TOKEN_PATH}`);
+        answer = parseAnswer(await response.json(), repository);
+    }
+    catch (error) {
+        // Only a refusal proves nothing was recorded. Anything else (no answer, a server error, an unreadable answer) may
+        // follow a write that went through, and this file is then the only copy of the active token: it is kept, and the
+        // next run settles it.
+        if (provenNotRecorded(error)) {
+            unlinkSync(pendingPath);
+            throw error;
+        }
+        throw new Error(`${error instanceof Error ? error.message : String(error)} The request may have reached Haystack, so the token is kept in `
+            + `${pendingPath} (mode 0600). Run this command again: it finds out whether that token became active and keeps or removes it.`);
+    }
+    if (answer.status === 'active' && answer.tokenSha256 !== tokenSha256) {
+        // Another mint won since the status read: nothing was recorded for this token.
+        unlinkSync(pendingPath);
+        activeElsewhere(answer.repository, answer, file);
+        return;
+    }
+    // Minted (or the answer to a retry of this very mint): this file is now the active token's.
+    renameSync(pendingPath, file);
+    chmodSync(file, 0o600);
+    console.log(chalk.green(`Minted the telemetry ingest token for ${answer.repository} (${TELEMETRY_ENVIRONMENT}).`));
+    console.log(`  token file: ${file} (mode 0600; the token is not printed)`);
+    console.log(`  SHA-256:    ${tokenSha256} (all Haystack keeps)`);
+    if (answer.status === 'minted' && answer.replaced)
+        console.log(chalk.yellow(`  replaced:   ${answer.replaced.slice(0, 12)}… no longer authenticates`));
+    for (const line of environmentLines(answer.endpoint, file))
+        console.log(line);
+    console.log(chalk.dim('Keep the file private until production has the token. Running this command again names the active token; '
+        + '--rotate replaces it.'));
+}