@pugi/sdk 0.1.0-alpha.3

package/dist/transport.js

@@ -0,0 +1,482 @@
+import { z } from 'zod';
+import { pugiSyncRequestSchema, pugiSyncResponseSchema, } from './handoff.js';
+import { pugiDevicePollResponseSchema, pugiDeviceStartResponseSchema, } from './device-flow.js';
+export const anvilCapabilitySchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    enabled: z.boolean(),
+});
+export const anvilCapabilitiesResponseSchema = z.object({
+    endpoint: z.string().min(1),
+    capabilities: z.array(anvilCapabilitySchema),
+});
+/**
+ * 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 const pugiRuntimeConfigSchema = z.object({
+    apiUrl: z.string().url(),
+    apiKey: z.string().min(1),
+    timeoutMs: z.number().int().positive().default(120_000),
+});
+/**
+ * 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 function buildRuntimeConfig(input) {
+    const env = input.env ?? process.env;
+    return pugiRuntimeConfigSchema.parse({
+        apiUrl: input.apiUrl,
+        apiKey: input.apiKey,
+        timeoutMs: env.PUGI_API_TIMEOUT_MS ? Number.parseInt(env.PUGI_API_TIMEOUT_MS, 10) : 120_000,
+    });
+}
+/**
+ * Convenience: env-only resolution. Returns `null` when `PUGI_API_KEY`
+ * is unset. Used by CI flows that authenticate purely via environment
+ * variables.
+ */
+export function loadRuntimeConfig(env = process.env) {
+    const apiUrl = env.PUGI_API_URL ?? 'https://api.pugi.io';
+    const apiKey = env.PUGI_API_KEY;
+    if (!apiKey)
+        return null;
+    return buildRuntimeConfig({ apiUrl, apiKey, env });
+}
+/**
+ * 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 const tripleReviewSeveritySchema = z.enum(['P0', 'P1', 'P2', 'P3']);
+export const tripleReviewVerdictSchema = z.enum(['PASS', 'WARN', 'BLOCK']);
+export const pugiTripleReviewFindingSchema = z.object({
+    reviewer: z.string().min(1),
+    severity: tripleReviewSeveritySchema,
+    line: z.number().int().positive().nullable(),
+    path: z.string().min(1).optional(),
+    issue: z.string().min(1),
+    fix: z.string(),
+});
+export const pugiTripleReviewReviewerSchema = z.object({
+    model: z.string().min(1),
+    latencyMs: z.number().int().nonnegative(),
+    tokensUsed: z.number().int().nonnegative().nullable(),
+    rawContent: z.string(),
+    findings: z.array(z.object({
+        severity: tripleReviewSeveritySchema,
+        line: z.number().int().positive().nullable(),
+        issue: z.string().min(1),
+        fix: z.string(),
+    })),
+    declaredVerdict: tripleReviewVerdictSchema.nullable(),
+    error: z.string().nullable(),
+});
+export const pugiTripleReviewRequestSchema = z.object({
+    schema: z.literal(1),
+    workspace: z.object({
+        rootName: z.string().min(1),
+        gitBranch: z.string().min(1).nullable(),
+        gitHead: z.string().min(1).nullable(),
+        baseRef: z.string().min(1).nullable(),
+        dirty: z.boolean(),
+    }),
+    /**
+     * 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.string(),
+    diffStats: z.object({
+        filesChanged: z.number().int().nonnegative(),
+        insertions: z.number().int().nonnegative(),
+        deletions: z.number().int().nonnegative(),
+    }),
+    /**
+     * Optional prompt (`pugi review --triple "<prompt>"`). When absent the
+     * reviewers infer scope from the diff alone.
+     */
+    prompt: z.string().optional(),
+    locale: z.string().default('en-US'),
+    /**
+     * 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.string().default('oes-dev'),
+});
+export const pugiTripleReviewResponseSchema = z.object({
+    schema: z.literal(1),
+    verdict: tripleReviewVerdictSchema,
+    reason: z.string().min(1),
+    reviewerCount: z.number().int().nonnegative(),
+    effectiveTier: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    draft: z.boolean(),
+    reviewers: z.array(pugiTripleReviewReviewerSchema),
+    findings: z.array(pugiTripleReviewFindingSchema),
+    counts: z.object({
+        P0: z.number().int().nonnegative(),
+        P1: z.number().int().nonnegative(),
+        P2: z.number().int().nonnegative(),
+        P3: z.number().int().nonnegative(),
+    }),
+    /**
+     * 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.string().datetime(),
+});
+/**
+ * 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 async function submitTripleReview(config, request) {
+    const body = pugiTripleReviewRequestSchema.parse(request);
+    // Admin-api mounts every route under the global `/api` prefix. Pugi
+    // CLI talks to `/api/pugi/triple-review`; the server-side endpoint
+    // ships in apps/admin-api/src/pugi/.
+    const url = `${config.apiUrl.replace(/\/+$/, '')}/api/pugi/triple-review`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+                'user-agent': 'pugi-cli/0.0.1',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const code = res.status;
+        const text = await res.text();
+        if (code === 200) {
+            let raw;
+            try {
+                raw = JSON.parse(text);
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    code,
+                    message: `runtime returned 200 with non-JSON body: ${error.message}`,
+                };
+            }
+            const parsed = pugiTripleReviewResponseSchema.safeParse(raw);
+            if (!parsed.success) {
+                return {
+                    status: 'failed',
+                    code,
+                    message: `runtime response failed schema: ${parsed.error.issues
+                        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                        .join('; ')}`,
+                };
+            }
+            return { status: 'ok', response: parsed.data };
+        }
+        if (code === 404) {
+            return {
+                status: 'endpoint_missing',
+                code,
+                message: 'POST /api/pugi/triple-review not deployed on this runtime',
+            };
+        }
+        if (code === 401 || code === 403) {
+            return {
+                status: 'unauthenticated',
+                code,
+                message: `runtime rejected credentials (HTTP ${code})`,
+            };
+        }
+        if (code === 429) {
+            const retryAfterHeader = res.headers.get('retry-after');
+            const retryAfterMs = retryAfterHeader
+                ? Number.parseInt(retryAfterHeader, 10) * 1000
+                : 60_000;
+            return {
+                status: 'rate_limited',
+                code,
+                retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : 60_000,
+                message: 'runtime rate limit reached for this tenant',
+            };
+        }
+        return {
+            status: 'failed',
+            code,
+            message: `runtime returned HTTP ${code}${text ? `: ${text.slice(0, 200)}` : ''}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.name === 'AbortError'
+                ? `runtime call timed out after ${config.timeoutMs}ms`
+                : error.message
+            : 'unknown error';
+        return { status: 'failed', code: 0, message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 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 async function submitSync(config, request) {
+    const body = pugiSyncRequestSchema.parse(request);
+    const url = `${config.apiUrl.replace(/\/+$/, '')}/api/pugi/sync`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+                'user-agent': 'pugi-cli/0.0.1',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const code = res.status;
+        const text = await res.text();
+        if (code === 200) {
+            let raw;
+            try {
+                raw = JSON.parse(text);
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    code,
+                    message: `runtime returned 200 with non-JSON body: ${error.message}`,
+                };
+            }
+            const parsed = pugiSyncResponseSchema.safeParse(raw);
+            if (!parsed.success) {
+                return {
+                    status: 'failed',
+                    code,
+                    message: `runtime response failed schema: ${parsed.error.issues
+                        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                        .join('; ')}`,
+                };
+            }
+            return { status: 'ok', response: parsed.data };
+        }
+        if (code === 404) {
+            return {
+                status: 'endpoint_missing',
+                code,
+                message: 'POST /api/pugi/sync not deployed on this runtime',
+            };
+        }
+        if (code === 401 || code === 403) {
+            return {
+                status: 'unauthenticated',
+                code,
+                message: `runtime rejected credentials (HTTP ${code})`,
+            };
+        }
+        if (code === 429) {
+            const retryAfterHeader = res.headers.get('retry-after');
+            const retryAfterMs = retryAfterHeader
+                ? Number.parseInt(retryAfterHeader, 10) * 1000
+                : 60_000;
+            return {
+                status: 'rate_limited',
+                code,
+                retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : 60_000,
+                message: 'runtime rate limit reached for this tenant',
+            };
+        }
+        return {
+            status: 'failed',
+            code,
+            message: `runtime returned HTTP ${code}${text ? `: ${text.slice(0, 200)}` : ''}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.name === 'AbortError'
+                ? `runtime call timed out after ${config.timeoutMs}ms`
+                : error.message
+            : 'unknown error';
+        return { status: 'failed', code: 0, message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 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 async function startDeviceFlow(apiUrl, timeoutMs = 15_000) {
+    const url = `${apiUrl.replace(/\/+$/, '')}/api/auth/device/start`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'user-agent': 'pugi-cli/0.0.1' },
+            body: JSON.stringify({ clientId: 'pugi-cli' }),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        if (res.status === 200) {
+            try {
+                const parsed = pugiDeviceStartResponseSchema.safeParse(JSON.parse(text));
+                if (!parsed.success) {
+                    return {
+                        status: 'failed',
+                        code: 200,
+                        message: `runtime response failed schema: ${parsed.error.issues
+                            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                            .join('; ')}`,
+                    };
+                }
+                return { status: 'ok', response: parsed.data };
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    code: 200,
+                    message: `runtime returned 200 with non-JSON body: ${error.message}`,
+                };
+            }
+        }
+        if (res.status === 404) {
+            return {
+                status: 'endpoint_missing',
+                code: 404,
+                message: 'POST /api/auth/device/start not deployed on this runtime',
+            };
+        }
+        return {
+            status: 'failed',
+            code: res.status,
+            message: `runtime returned HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.name === 'AbortError'
+                ? `runtime call timed out after ${timeoutMs}ms`
+                : error.message
+            : 'unknown error';
+        return { status: 'failed', code: 0, message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 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 async function pollDeviceFlow(apiUrl, deviceCode, timeoutMs = 15_000) {
+    const url = `${apiUrl.replace(/\/+$/, '')}/api/auth/device/poll`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'user-agent': 'pugi-cli/0.0.1' },
+            body: JSON.stringify({ deviceCode }),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        if (res.status === 200) {
+            try {
+                const parsed = pugiDevicePollResponseSchema.safeParse(JSON.parse(text));
+                if (!parsed.success) {
+                    return {
+                        status: 'failed',
+                        code: 200,
+                        message: `runtime response failed schema: ${parsed.error.issues
+                            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                            .join('; ')}`,
+                    };
+                }
+                return { status: 'ok', response: parsed.data };
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    code: 200,
+                    message: `runtime returned 200 with non-JSON body: ${error.message}`,
+                };
+            }
+        }
+        if (res.status === 404) {
+            return {
+                status: 'endpoint_missing',
+                code: 404,
+                message: 'POST /api/auth/device/poll not deployed on this runtime',
+            };
+        }
+        return {
+            status: 'failed',
+            code: res.status,
+            message: `runtime returned HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? error.name === 'AbortError'
+                ? `runtime call timed out after ${timeoutMs}ms`
+                : error.message
+            : 'unknown error';
+        return { status: 'failed', code: 0, message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pugi/sdk",
+  "version": "0.1.0-alpha.3",
+  "description": "Pugi CLI contracts shared by the CLI, docs, and Anvil runtime",
+  "homepage": "https://pugi.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pugi-io/pugi.git",
+    "directory": "packages/pugi-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/pugi-io/pugi/issues"
+  },
+  "keywords": [
+    "pugi",
+    "sdk",
+    "contracts",
+    "schemas"
+  ],
+  "author": "Pugi <hello@pugi.io>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}