@allocator-one/rcl 4.4.19

package/dist/telemetry/credentials.js

@@ -0,0 +1,87 @@
+import { defaultCredentialsPath, findHarnessRepoConfig, readStoredCredentials, } from '../config/harness.js';
+const LOOPBACK = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|[a-z0-9.-]+\.localhost)$/i;
+/**
+ * The token travels only over TLS, except to loopback hosts (a local
+ * development server). A base URL carries no user-info, query or fragment;
+ * the result is the canonical origin plus path, without a trailing slash.
+ */
+export function normalizeUrl(raw) {
+    try {
+        const url = new URL(raw.trim());
+        if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '')
+            return null;
+        const plain = url.protocol === 'http:' && LOOPBACK.test(url.hostname);
+        if (url.protocol !== 'https:' && !plain)
+            return null;
+        return `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+/** The host of a URL for a note — never its user-info or query. */
+function hostOf(raw) {
+    try {
+        return new URL(raw.trim()).host || '(no host)';
+    }
+    catch {
+        return '(unparseable)';
+    }
+}
+export async function resolveHarnessCredential(options = {}) {
+    const env = options.env ?? process.env;
+    const repoManaged = findHarnessRepoConfig(options.cwd ?? process.cwd()) !== null;
+    if (!repoManaged && options.requireRepo !== false)
+        return { repoManaged: false };
+    const envToken = (env['HARNESS_API_TOKEN'] ?? '').trim();
+    const envUrl = (env['HARNESS_API_URL'] ?? '').trim();
+    if (envToken !== '' || envUrl !== '') {
+        // Half a pair is a configuration error, never a fallback to the login.
+        if (envUrl === '') {
+            return {
+                repoManaged,
+                note: 'HARNESS_API_TOKEN is set without HARNESS_API_URL — an environment token never pairs with the stored login host.',
+            };
+        }
+        if (envToken === '') {
+            return {
+                repoManaged,
+                note: 'HARNESS_API_URL is set without HARNESS_API_TOKEN — the environment names a host but no token; the stored login is not used in its place.',
+            };
+        }
+        const url = normalizeUrl(envUrl);
+        if (url === null) {
+            return {
+                repoManaged,
+                note: `HARNESS_API_URL must be an absolute https URL without user-info, query or fragment (http only for loopback hosts): ${hostOf(envUrl)}`,
+            };
+        }
+        return { repoManaged, credential: { url, token: envToken, source: 'env' } };
+    }
+    const stored = await readStoredCredentials(options.credentialsPath ?? defaultCredentialsPath(env));
+    if (stored === null) {
+        return {
+            repoManaged,
+            note: 'not logged in to Harness — run `harness login` (or set HARNESS_API_TOKEN and HARNESS_API_URL in CI).',
+        };
+    }
+    const storedUrl = normalizeUrl(stored.url);
+    if (storedUrl === null) {
+        return { repoManaged, note: `the stored Harness login names a host the token must not travel to in plain text: ${hostOf(stored.url)}` };
+    }
+    const token = typeof stored.token === 'string' ? stored.token.trim() : '';
+    if (token === '') {
+        return { repoManaged, note: 'the stored Harness login carries no token — run `harness login` again.' };
+    }
+    return { repoManaged, credential: { url: storedUrl, token, source: 'login' } };
+}
+/** The host name a status line may name (never the token). */
+export function credentialHost(credential) {
+    try {
+        return new URL(credential.url).host;
+    }
+    catch {
+        return credential.url;
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/telemetry/credentials.js.map

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

package/dist/telemetry/deliver.d.ts

@@ -0,0 +1,152 @@
+import { type Config } from '../config/schema.js';
+import type { ReviewResult } from '../consensus/types.js';
+import { type HarnessCredential } from './credentials.js';
+import { type ReviewerRecoverySource, type ArtifactBytes, type TelemetryLevel } from './envelope.js';
+import { type EvidenceDiagnostic } from './envelope-validation.js';
+import { Quarantine, type RetentionOutcome } from './quarantine.js';
+import { type WireEvent } from './events.js';
+import { Outbox, type FlushOptions, type FlushSummary } from './outbox.js';
+import { HarnessSink } from './sink.js';
+import { type ReviewerArtifact } from '../report/reviewer-artifact.js';
+import { AttestedReviewerDelivery } from './attested-reviewer-delivery.js';
+/**
+ * Evidence delivery for a finished review and for the converge commands
+ * (epic IO-12475, section 8): resolve where the evidence goes, send it,
+ * spool what could not be sent, and say in one dim line what happened.
+ * Delivery never blocks a review on the network beyond its own timeouts,
+ * never changes the review's result, and never turns a local failure of its
+ * own (a read-only data dir, a torn file) into a failed review — only
+ * `--evidence-required` turns an unacknowledged delivery into an exit code.
+ */
+export declare const STARTUP_FLUSH_DEADLINE_MS = 5000;
+export declare const EVIDENCE_REQUIRED_EXIT_CODE = 4;
+export interface TelemetryRuntime {
+    level: TelemetryLevel;
+    /** Whether the working tree carries `.harness-cli/config.json`. */
+    repoManaged: boolean;
+    parseFailures: boolean;
+    credential?: HarnessCredential;
+    /**
+     * The credential is the run-bound one of `--attest` (RCL-40): it does not
+     * outlive the workflow run, so nothing recorded under it is spooled.
+     */
+    attested?: boolean;
+    /** The current run-bound credential expiry; retries must finish before it. */
+    attestedExpiresAt?: string;
+    /** Why there is no credential, when telemetry would otherwise apply. */
+    note?: string;
+    sink?: HarnessSink;
+    outbox: Outbox;
+    quarantine?: Quarantine;
+    dataDir: string;
+    rclVersion: string;
+    stderr: (line: string) => void;
+}
+export interface RuntimeOptions {
+    rclVersion: string;
+    /** The loaded project config; when omitted, the `harness` section is read from the project's config file. */
+    config?: Config;
+    /** `--no-telemetry` (commander passes `telemetry: false`). */
+    noTelemetry?: boolean;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    dataDir?: string;
+    credentialsPath?: string;
+    fetchImpl?: typeof fetch;
+    /** Explicit envelope-only POST timeout for delivery retries. */
+    envelopeTimeoutMs?: number;
+    stderr?: (line: string) => void;
+    /** `rcl telemetry` works on the user's outbox from any directory. */
+    requireRepo?: boolean;
+    /**
+     * A credential already in hand — the run-bound one `rcl review --attest`
+     * minted: no resolution, the repository counts as Harness-managed (the
+     * attestation is the membership proof), and an attested run never spools.
+     */
+    credential?: HarnessCredential;
+    /** The expiry from the attestation that supplied `credential`. */
+    attestedExpiresAt?: string;
+}
+/**
+ * What `RCL_TELEMETRY` asks for: `off` (also `0`, `false`, `no`), a level
+ * name, or nothing when unset. A value that is set but not understood is a
+ * failed opt-out and reads as `off` — never as the default.
+ */
+export declare function envTelemetryLevel(env: Record<string, string | undefined>): TelemetryLevel | undefined;
+/**
+ * Why `--evidence-required` cannot be honored, or undefined when it can:
+ * evidence cannot be required and withheld at the same time. The flag and
+ * the environment are known up front; the project config once loaded.
+ */
+export declare function evidenceRequirementConflict(opts: {
+    evidenceRequired?: boolean;
+    telemetry?: boolean;
+}, config: Pick<Config, 'harness'> | undefined, env: Record<string, string | undefined>): string | undefined;
+/** `--no-telemetry` wins, then `RCL_TELEMETRY`, then `harness.telemetry`; default `full`. */
+export declare function resolveTelemetryLevel(config: Pick<Config, 'harness'> | undefined, flags: {
+    noTelemetry?: boolean;
+}, env: Record<string, string | undefined>): TelemetryLevel;
+/**
+ * The `harness` section of the project's config file, read without the
+ * full loader (whose fleet degradation warns on stderr — noise no startup
+ * flush should print). A missing or unusable file reads as no settings;
+ * `configPath` (`--config`) names the file instead of searching from `cwd`,
+ * and one that cannot be read fails closed like an unparseable section.
+ */
+export declare function loadHarnessSettings(cwd: string, configPath?: string): Promise<Pick<Config, 'harness'> | undefined>;
+export declare function createTelemetryRuntime(options: RuntimeOptions): Promise<TelemetryRuntime>;
+/** Flush the outbox through the runtime's sink, the notice shown first. */
+export declare function flushOutbox(runtime: TelemetryRuntime, options?: FlushOptions): Promise<FlushSummary>;
+/** Bounded: an offline machine must never stall a command. Fail-soft. */
+export declare function flushOutboxAtStart(runtime: TelemetryRuntime, deadlineMs?: number): Promise<void>;
+export type DeliveryStatus = 'recorded' | 'spooled' | 'disabled' | 'rejected' | 'conflict' | 'skipped' | 'off' | 'error';
+export interface DeliveryOutcome {
+    status: DeliveryStatus;
+    /** The one dim status line to print (empty when telemetry is off and nothing was required). */
+    line: string;
+    url?: string;
+    runId?: string;
+    /** Something waits in the outbox for `rcl telemetry flush`. */
+    spooled: boolean;
+    /** Validation rejected before any network operation; never retryable delivery. */
+    failureDisposition?: 'local-invalid';
+    /** Original recovery inputs retained locally; never means server acknowledgment or auto-retry. */
+    retention?: RetentionOutcome;
+    /**
+     * 4 when `--evidence-required` and the evidence is incomplete: the envelope
+     * was not acknowledged, or a declared artifact was spooled or refused.
+     */
+    exitCode: 0 | typeof EVIDENCE_REQUIRED_EXIT_CODE;
+}
+export interface DeliverRunInput {
+    result: ReviewResult;
+    artifacts: ArtifactBytes;
+    /** Already sealed local private evidence, never copied into generic artifact/outbox paths. */
+    reviewerArtifact?: ReviewerArtifact;
+    /** Independently bound immediate parent for a supplemented artifact. */
+    reviewerSource?: ReviewerRecoverySource;
+    /** Explicit current-workflow coordinator; never reconstructed from an ordinary credential or queue. */
+    attestedReviewer?: AttestedReviewerDelivery;
+    evidenceRequired?: boolean;
+    events?: WireEvent[];
+    /** Requested report files that could not be written; the rendered originals still exist in memory. */
+    outputDiagnostics?: EvidenceDiagnostic[];
+}
+/** The wire builder defaults an absent finding label to `none`; inspect the immutable report first. */
+export declare function verifiedConsensusDiagnostics(result: ReviewResult): EvidenceDiagnostic[];
+/**
+ * POST the envelope, PUT the artifacts (at `full`), POST any events; spool
+ * whatever the server could not take because it was unreachable. Local
+ * failures (notice file, outbox) are reported, never thrown.
+ */
+export declare function deliverRun(runtime: TelemetryRuntime, input: DeliverRunInput): Promise<DeliveryOutcome>;
+/**
+ * Converge commands report their events through the same sink, fail-soft:
+ * unreachable spools, anything else is noted and dropped.
+ */
+export declare function emitConvergeEvents(runtime: TelemetryRuntime, events: WireEvent[]): Promise<'sent' | 'spooled' | 'skipped' | 'refused'>;
+/** Keep transport uncertainty conservative, while distinguishing proven pre-network rejection. */
+export declare function guardedDeliveryState(delivery: Pick<DeliveryOutcome, 'spooled' | 'exitCode' | 'failureDisposition'>): {
+    deliveryFailure?: "local-invalid" | undefined;
+    deliveryPending: boolean;
+};