@pugi/sdk 0.1.0-alpha.10

package/dist/transport.d.ts

@@ -0,0 +1,559 @@
+import { z } from 'zod';
+import { type PugiSyncRequest, type PugiSyncResponse } from './handoff.js';
+import { type PugiDevicePollResponse, type PugiDeviceStartResponse } from './device-flow.js';
+export declare const anvilCapabilitySchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    enabled: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    enabled: boolean;
+    version: string;
+}, {
+    name: string;
+    enabled: boolean;
+    version: string;
+}>;
+export type AnvilCapability = z.infer<typeof anvilCapabilitySchema>;
+export declare const anvilCapabilitiesResponseSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    capabilities: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        enabled: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        enabled: boolean;
+        version: string;
+    }, {
+        name: string;
+        enabled: boolean;
+        version: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    endpoint: string;
+    capabilities: {
+        name: string;
+        enabled: boolean;
+        version: string;
+    }[];
+}, {
+    endpoint: string;
+    capabilities: {
+        name: string;
+        enabled: boolean;
+        version: string;
+    }[];
+}>;
+export type AnvilCapabilitiesResponse = z.infer<typeof anvilCapabilitiesResponseSchema>;
+/**
+ * Pugi runtime client config.
+ *
+ * Defaults: PUGI_API_URL=https://api.pugi.io, PUGI_API_KEY required for remote.
+ * Self-hosted override: PUGI_API_URL=https://anvil.acme.corp.
+ */
+export declare const pugiRuntimeConfigSchema: z.ZodObject<{
+    apiUrl: z.ZodString;
+    apiKey: z.ZodString;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    apiUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+}, {
+    apiUrl: string;
+    apiKey: string;
+    timeoutMs?: number | undefined;
+}>;
+export type PugiRuntimeConfig = z.infer<typeof pugiRuntimeConfigSchema>;
+/**
+ * Build a `PugiRuntimeConfig` from a known apiKey + apiUrl (e.g. resolved
+ * from a credentials store) plus the env for timeout override. Pure —
+ * does not touch the filesystem. The CLI's credential store layer is
+ * what reads disk / env first; this function exists so callers can
+ * provide credentials from any source (env, keychain, OAuth refresh)
+ * and still receive a validated config.
+ */
+export declare function buildRuntimeConfig(input: {
+    apiUrl: string;
+    apiKey: string;
+    env?: NodeJS.ProcessEnv;
+}): PugiRuntimeConfig;
+/**
+ * Convenience: env-only resolution. Returns `null` when `PUGI_API_KEY`
+ * is unset. Used by CI flows that authenticate purely via environment
+ * variables.
+ */
+export declare function loadRuntimeConfig(env?: NodeJS.ProcessEnv): PugiRuntimeConfig | null;
+/**
+ * Triple-review rubric (verbatim from /triple-review skill + OES MCP triple_review tool):
+ *   any P0                 -> BLOCK
+ *   P1 from >= 2 reviewers -> BLOCK
+ *   P1 from 1 reviewer     -> WARN
+ *   no P0/P1               -> PASS
+ *   all reviewers errored  -> BLOCK
+ */
+export declare const tripleReviewSeveritySchema: z.ZodEnum<["P0", "P1", "P2", "P3"]>;
+export type TripleReviewSeverity = z.infer<typeof tripleReviewSeveritySchema>;
+export declare const tripleReviewVerdictSchema: z.ZodEnum<["PASS", "WARN", "BLOCK"]>;
+export type TripleReviewVerdict = z.infer<typeof tripleReviewVerdictSchema>;
+export declare const pugiTripleReviewFindingSchema: z.ZodObject<{
+    reviewer: z.ZodString;
+    severity: z.ZodEnum<["P0", "P1", "P2", "P3"]>;
+    line: z.ZodNullable<z.ZodNumber>;
+    path: z.ZodOptional<z.ZodString>;
+    issue: z.ZodString;
+    fix: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    fix: string;
+    severity: "P0" | "P1" | "P2" | "P3";
+    line: number | null;
+    reviewer: string;
+    issue: string;
+    path?: string | undefined;
+}, {
+    fix: string;
+    severity: "P0" | "P1" | "P2" | "P3";
+    line: number | null;
+    reviewer: string;
+    issue: string;
+    path?: string | undefined;
+}>;
+export type PugiTripleReviewFinding = z.infer<typeof pugiTripleReviewFindingSchema>;
+export declare const pugiTripleReviewReviewerSchema: z.ZodObject<{
+    model: z.ZodString;
+    latencyMs: z.ZodNumber;
+    tokensUsed: z.ZodNullable<z.ZodNumber>;
+    rawContent: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<["P0", "P1", "P2", "P3"]>;
+        line: z.ZodNullable<z.ZodNumber>;
+        issue: z.ZodString;
+        fix: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        issue: string;
+    }, {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        issue: string;
+    }>, "many">;
+    declaredVerdict: z.ZodNullable<z.ZodEnum<["PASS", "WARN", "BLOCK"]>>;
+    error: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    tokensUsed: number | null;
+    error: string | null;
+    findings: {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        issue: string;
+    }[];
+    latencyMs: number;
+    rawContent: string;
+    declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+}, {
+    model: string;
+    tokensUsed: number | null;
+    error: string | null;
+    findings: {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        issue: string;
+    }[];
+    latencyMs: number;
+    rawContent: string;
+    declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+}>;
+export type PugiTripleReviewReviewer = z.infer<typeof pugiTripleReviewReviewerSchema>;
+export declare const pugiTripleReviewRequestSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    workspace: z.ZodObject<{
+        rootName: z.ZodString;
+        gitBranch: z.ZodNullable<z.ZodString>;
+        gitHead: z.ZodNullable<z.ZodString>;
+        baseRef: z.ZodNullable<z.ZodString>;
+        dirty: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        dirty: boolean;
+        rootName: string;
+        gitBranch: string | null;
+        gitHead: string | null;
+        baseRef: string | null;
+    }, {
+        dirty: boolean;
+        rootName: string;
+        gitBranch: string | null;
+        gitHead: string | null;
+        baseRef: string | null;
+    }>;
+    /**
+     * Branch diff vs baseRef (e.g. `origin/main`). Truncated to a server-side
+     * cap on the receiver. We do NOT send raw file contents outside of
+     * `--privacy selected-files` or `--privacy full-sync` modes; the diff
+     * itself is the evidence the reviewers inspect.
+     */
+    diffPatch: z.ZodString;
+    diffStats: z.ZodObject<{
+        filesChanged: z.ZodNumber;
+        insertions: z.ZodNumber;
+        deletions: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    }, {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    }>;
+    /**
+     * Optional prompt (`pugi review --triple "<prompt>"`). When absent the
+     * reviewers infer scope from the diff alone.
+     */
+    prompt: z.ZodOptional<z.ZodString>;
+    locale: z.ZodDefault<z.ZodString>;
+    /**
+     * Reviewer persona slug on the server side. Default 'oes-dev' (Sigma)
+     * is the tier-2 reviewer today and bumps to tier-3 transparently when
+     * the operator configures ANVIL_TIER1_MODELS with 3+ models.
+     */
+    reviewerPersona: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    schema: 1;
+    workspace: {
+        dirty: boolean;
+        rootName: string;
+        gitBranch: string | null;
+        gitHead: string | null;
+        baseRef: string | null;
+    };
+    diffPatch: string;
+    diffStats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+    locale: string;
+    reviewerPersona: string;
+    prompt?: string | undefined;
+}, {
+    schema: 1;
+    workspace: {
+        dirty: boolean;
+        rootName: string;
+        gitBranch: string | null;
+        gitHead: string | null;
+        baseRef: string | null;
+    };
+    diffPatch: string;
+    diffStats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+    prompt?: string | undefined;
+    locale?: string | undefined;
+    reviewerPersona?: string | undefined;
+}>;
+export type PugiTripleReviewRequest = z.infer<typeof pugiTripleReviewRequestSchema>;
+export declare const pugiTripleReviewResponseSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    verdict: z.ZodEnum<["PASS", "WARN", "BLOCK"]>;
+    reason: z.ZodString;
+    reviewerCount: z.ZodNumber;
+    effectiveTier: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    draft: z.ZodBoolean;
+    reviewers: z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        latencyMs: z.ZodNumber;
+        tokensUsed: z.ZodNullable<z.ZodNumber>;
+        rawContent: z.ZodString;
+        findings: z.ZodArray<z.ZodObject<{
+            severity: z.ZodEnum<["P0", "P1", "P2", "P3"]>;
+            line: z.ZodNullable<z.ZodNumber>;
+            issue: z.ZodString;
+            fix: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }, {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }>, "many">;
+        declaredVerdict: z.ZodNullable<z.ZodEnum<["PASS", "WARN", "BLOCK"]>>;
+        error: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        tokensUsed: number | null;
+        error: string | null;
+        findings: {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }[];
+        latencyMs: number;
+        rawContent: string;
+        declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+    }, {
+        model: string;
+        tokensUsed: number | null;
+        error: string | null;
+        findings: {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }[];
+        latencyMs: number;
+        rawContent: string;
+        declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+    }>, "many">;
+    findings: z.ZodArray<z.ZodObject<{
+        reviewer: z.ZodString;
+        severity: z.ZodEnum<["P0", "P1", "P2", "P3"]>;
+        line: z.ZodNullable<z.ZodNumber>;
+        path: z.ZodOptional<z.ZodString>;
+        issue: z.ZodString;
+        fix: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        reviewer: string;
+        issue: string;
+        path?: string | undefined;
+    }, {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        reviewer: string;
+        issue: string;
+        path?: string | undefined;
+    }>, "many">;
+    counts: z.ZodObject<{
+        P0: z.ZodNumber;
+        P1: z.ZodNumber;
+        P2: z.ZodNumber;
+        P3: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        P0: number;
+        P1: number;
+        P2: number;
+        P3: number;
+    }, {
+        P0: number;
+        P1: number;
+        P2: number;
+        P3: number;
+    }>;
+    /**
+     * ISO-8601 timestamp when the server completed the review. Pugi
+     * persists this in the local artifact so audit replay knows when
+     * the runtime gate fired.
+     */
+    completedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    findings: {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        reviewer: string;
+        issue: string;
+        path?: string | undefined;
+    }[];
+    schema: 1;
+    verdict: "PASS" | "WARN" | "BLOCK";
+    reviewerCount: number;
+    effectiveTier: 1 | 2 | 3;
+    draft: boolean;
+    reviewers: {
+        model: string;
+        tokensUsed: number | null;
+        error: string | null;
+        findings: {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }[];
+        latencyMs: number;
+        rawContent: string;
+        declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+    }[];
+    counts: {
+        P0: number;
+        P1: number;
+        P2: number;
+        P3: number;
+    };
+    completedAt: string;
+}, {
+    reason: string;
+    findings: {
+        fix: string;
+        severity: "P0" | "P1" | "P2" | "P3";
+        line: number | null;
+        reviewer: string;
+        issue: string;
+        path?: string | undefined;
+    }[];
+    schema: 1;
+    verdict: "PASS" | "WARN" | "BLOCK";
+    reviewerCount: number;
+    effectiveTier: 1 | 2 | 3;
+    draft: boolean;
+    reviewers: {
+        model: string;
+        tokensUsed: number | null;
+        error: string | null;
+        findings: {
+            fix: string;
+            severity: "P0" | "P1" | "P2" | "P3";
+            line: number | null;
+            issue: string;
+        }[];
+        latencyMs: number;
+        rawContent: string;
+        declaredVerdict: "PASS" | "WARN" | "BLOCK" | null;
+    }[];
+    counts: {
+        P0: number;
+        P1: number;
+        P2: number;
+        P3: number;
+    };
+    completedAt: string;
+}>;
+export type PugiTripleReviewResponse = z.infer<typeof pugiTripleReviewResponseSchema>;
+export type SubmitTripleReviewResult = {
+    status: 'ok';
+    response: PugiTripleReviewResponse;
+} | {
+    status: 'endpoint_missing';
+    code: number;
+    message: string;
+} | {
+    status: 'unauthenticated';
+    code: number;
+    message: string;
+} | {
+    status: 'rate_limited';
+    code: number;
+    retryAfterMs: number;
+    message: string;
+} | {
+    status: 'failed';
+    code: number;
+    message: string;
+};
+/**
+ * Submit a triple-review request to the Pugi runtime endpoint.
+ *
+ * Endpoint contract (admin-api side, ships in a separate PR):
+ *   POST {apiUrl}/api/pugi/triple-review
+ *   Authorization: Bearer {apiKey}
+ *   Content-Type: application/json
+ *   Body: PugiTripleReviewRequest
+ *   200: PugiTripleReviewResponse
+ *   401/403: unauthenticated
+ *   404: endpoint not yet deployed (graceful local-only fallback)
+ *   429: rate limited (per-tenant)
+ *   5xx: failed
+ *
+ * Local-first contract: this function never reads the local file system,
+ * never logs the diff payload, and never retries on transient errors —
+ * the caller decides whether a retry makes sense.
+ */
+export declare function submitTripleReview(config: PugiRuntimeConfig, request: PugiTripleReviewRequest): Promise<SubmitTripleReviewResult>;
+export type SubmitSyncResult = {
+    status: 'ok';
+    response: PugiSyncResponse;
+} | {
+    status: 'endpoint_missing';
+    code: number;
+    message: string;
+} | {
+    status: 'unauthenticated';
+    code: number;
+    message: string;
+} | {
+    status: 'rate_limited';
+    code: number;
+    retryAfterMs: number;
+    message: string;
+} | {
+    status: 'failed';
+    code: number;
+    message: string;
+};
+/**
+ * Submit an explicit-continuation sync to the Pugi runtime endpoint.
+ *
+ * Endpoint contract (admin-api side, ships in this PR):
+ *   POST {apiUrl}/api/pugi/sync
+ *   Authorization: Bearer {apiKey}
+ *   Content-Type: application/json
+ *   Body: PugiSyncRequest (handoff bundle + upload-enabled plan)
+ *   200: PugiSyncResponse
+ *   401/403: unauthenticated
+ *   404: endpoint not yet deployed (graceful local-only fallback)
+ *   429: rate limited (per-tenant)
+ *   5xx: failed
+ *
+ * Local-first contract (ADR-0037): this function never reads files,
+ * never logs the bundle payload, and never retries on transient
+ * errors. The caller has already surfaced the dry-run plan to the
+ * operator; this is the explicit upload step.
+ */
+export declare function submitSync(config: PugiRuntimeConfig, request: PugiSyncRequest): Promise<SubmitSyncResult>;
+export type DeviceStartResult = {
+    status: 'ok';
+    response: PugiDeviceStartResponse;
+} | {
+    status: 'endpoint_missing';
+    code: number;
+    message: string;
+} | {
+    status: 'failed';
+    code: number;
+    message: string;
+};
+/**
+ * RFC 8628 §3.1 — CLI initiates the device flow. Anonymous request
+ * (no Authorization header). The runtime returns a `device_code` the
+ * CLI must keep secret and a `user_code` the user types into the
+ * cabinet Approve page.
+ */
+export declare function startDeviceFlow(apiUrl: string, timeoutMs?: number): Promise<DeviceStartResult>;
+export type DevicePollResult = {
+    status: 'ok';
+    response: PugiDevicePollResponse;
+} | {
+    status: 'endpoint_missing';
+    code: number;
+    message: string;
+} | {
+    status: 'failed';
+    code: number;
+    message: string;
+};
+/**
+ * RFC 8628 §3.4 — CLI polls until the user authorizes. The runtime
+ * returns the outcome class in the response body (always HTTP 200)
+ * so older HTTP clients with weak 4xx handling can still poll
+ * reliably. See AuthDeviceController for the rationale.
+ */
+export declare function pollDeviceFlow(apiUrl: string, deviceCode: string, timeoutMs?: number): Promise<DevicePollResult>;
+//# sourceMappingURL=transport.d.ts.map