@pugi/sdk 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yurii Bulakh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @pugi/sdk
+
+Shared contracts + zod schemas used by the Pugi CLI, docs, and the Anvil
+runtime backend. This package is a peer dependency of [`@pugi/cli`](https://www.npmjs.com/package/@pugi/cli);
+end users rarely install it directly.
+
+## Install
+
+```bash
+npm install @pugi/sdk
+```
+
+## Usage
+
+```ts
+import { engineLoopRequestSchema } from '@pugi/sdk';
+```
+
+Full contract surface: `agent-contracts`, `audit-trace`, `device-flow`
+(RFC 8628), `engine-adapter`, `engine-loop`, `handoff`, `mcp-schemas`,
+`permission-rules`, `transport`.
+
+## Versioning
+
+`@pugi/sdk` ships in lockstep with `@pugi/cli` — minor/patch bumps are
+shared. Until 1.0 the SDK API surface is alpha-stable; breaking changes
+are recorded in [the CLI README](https://github.com/pugi-io/pugi).
+
+License: MIT.

package/dist/agent-contracts.d.ts

@@ -0,0 +1,311 @@
+import { z } from 'zod';
+export declare const artifactKindSchema: z.ZodEnum<["brief", "prd_lite", "execution_graph", "risk_review", "acceptance_criteria", "diff", "review_verdict", "test_result", "debug_export"]>;
+export type ArtifactKind = z.infer<typeof artifactKindSchema>;
+export declare const artifactRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<["brief", "prd_lite", "execution_graph", "risk_review", "acceptance_criteria", "diff", "review_verdict", "test_result", "debug_export"]>;
+    path: z.ZodOptional<z.ZodString>;
+    uri: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    sha256: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+    title: string;
+    createdAt: string;
+    path?: string | undefined;
+    uri?: string | undefined;
+    sha256?: string | undefined;
+}, {
+    id: string;
+    kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+    title: string;
+    createdAt: string;
+    path?: string | undefined;
+    uri?: string | undefined;
+    sha256?: string | undefined;
+}>;
+export type ArtifactRef = z.infer<typeof artifactRefSchema>;
+export declare const ideaBriefSchema: z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    targetUser: z.ZodOptional<z.ZodString>;
+    currentStatusQuo: z.ZodOptional<z.ZodString>;
+    narrowestWedge: z.ZodOptional<z.ZodString>;
+    risks: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    acceptanceCriteria: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["brief", "prd_lite", "execution_graph", "risk_review", "acceptance_criteria", "diff", "review_verdict", "test_result", "debug_export"]>;
+        path: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }, {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    prompt: string;
+    risks: string[];
+    acceptanceCriteria: string[];
+    artifacts: {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }[];
+    targetUser?: string | undefined;
+    currentStatusQuo?: string | undefined;
+    narrowestWedge?: string | undefined;
+}, {
+    id: string;
+    prompt: string;
+    targetUser?: string | undefined;
+    currentStatusQuo?: string | undefined;
+    narrowestWedge?: string | undefined;
+    risks?: string[] | undefined;
+    acceptanceCriteria?: string[] | undefined;
+    artifacts?: {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }[] | undefined;
+}>;
+export type IdeaBrief = z.infer<typeof ideaBriefSchema>;
+export declare const executionGraphNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    kind: z.ZodEnum<["research", "plan", "code", "review", "test", "ship"]>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    owner: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "in_progress", "done", "blocked"]>>;
+    acceptanceCriteria: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "in_progress" | "done" | "blocked";
+    id: string;
+    kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+    title: string;
+    acceptanceCriteria: string[];
+    dependsOn: string[];
+    owner?: string | undefined;
+}, {
+    id: string;
+    kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+    title: string;
+    status?: "pending" | "in_progress" | "done" | "blocked" | undefined;
+    acceptanceCriteria?: string[] | undefined;
+    dependsOn?: string[] | undefined;
+    owner?: string | undefined;
+}>;
+export type ExecutionGraphNode = z.infer<typeof executionGraphNodeSchema>;
+export declare const executionGraphSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        kind: z.ZodEnum<["research", "plan", "code", "review", "test", "ship"]>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        owner: z.ZodOptional<z.ZodString>;
+        status: z.ZodDefault<z.ZodEnum<["pending", "in_progress", "done", "blocked"]>>;
+        acceptanceCriteria: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "in_progress" | "done" | "blocked";
+        id: string;
+        kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+        title: string;
+        acceptanceCriteria: string[];
+        dependsOn: string[];
+        owner?: string | undefined;
+    }, {
+        id: string;
+        kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+        title: string;
+        status?: "pending" | "in_progress" | "done" | "blocked" | undefined;
+        acceptanceCriteria?: string[] | undefined;
+        dependsOn?: string[] | undefined;
+        owner?: string | undefined;
+    }>, "many">;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["brief", "prd_lite", "execution_graph", "risk_review", "acceptance_criteria", "diff", "review_verdict", "test_result", "debug_export"]>;
+        path: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }, {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    artifacts: {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }[];
+    nodes: {
+        status: "pending" | "in_progress" | "done" | "blocked";
+        id: string;
+        kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+        title: string;
+        acceptanceCriteria: string[];
+        dependsOn: string[];
+        owner?: string | undefined;
+    }[];
+}, {
+    id: string;
+    title: string;
+    nodes: {
+        id: string;
+        kind: "code" | "plan" | "research" | "review" | "test" | "ship";
+        title: string;
+        status?: "pending" | "in_progress" | "done" | "blocked" | undefined;
+        acceptanceCriteria?: string[] | undefined;
+        dependsOn?: string[] | undefined;
+        owner?: string | undefined;
+    }[];
+    artifacts?: {
+        id: string;
+        kind: "brief" | "prd_lite" | "execution_graph" | "risk_review" | "acceptance_criteria" | "diff" | "review_verdict" | "test_result" | "debug_export";
+        title: string;
+        createdAt: string;
+        path?: string | undefined;
+        uri?: string | undefined;
+        sha256?: string | undefined;
+    }[] | undefined;
+}>;
+export type ExecutionGraph = z.infer<typeof executionGraphSchema>;
+export declare const testResultSchema: z.ZodObject<{
+    command: z.ZodString;
+    status: z.ZodEnum<["passed", "failed", "skipped"]>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    outputRef: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "passed" | "skipped";
+    command: string;
+    durationMs?: number | undefined;
+    outputRef?: string | undefined;
+}, {
+    status: "failed" | "passed" | "skipped";
+    command: string;
+    durationMs?: number | undefined;
+    outputRef?: string | undefined;
+}>;
+export type TestResult = z.infer<typeof testResultSchema>;
+export declare const reviewVerdictSchema: z.ZodObject<{
+    status: z.ZodEnum<["pass", "block"]>;
+    summary: z.ZodString;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<["low", "medium", "high", "critical"]>;
+        title: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodNumber>;
+        recommendation: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        severity: "low" | "medium" | "high" | "critical";
+        path?: string | undefined;
+        line?: number | undefined;
+        recommendation?: string | undefined;
+    }, {
+        title: string;
+        severity: "low" | "medium" | "high" | "critical";
+        path?: string | undefined;
+        line?: number | undefined;
+        recommendation?: string | undefined;
+    }>, "many">>;
+    testsRun: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        status: z.ZodEnum<["passed", "failed", "skipped"]>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        outputRef: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "failed" | "passed" | "skipped";
+        command: string;
+        durationMs?: number | undefined;
+        outputRef?: string | undefined;
+    }, {
+        status: "failed" | "passed" | "skipped";
+        command: string;
+        durationMs?: number | undefined;
+        outputRef?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    status: "pass" | "block";
+    summary: string;
+    findings: {
+        title: string;
+        severity: "low" | "medium" | "high" | "critical";
+        path?: string | undefined;
+        line?: number | undefined;
+        recommendation?: string | undefined;
+    }[];
+    testsRun: {
+        status: "failed" | "passed" | "skipped";
+        command: string;
+        durationMs?: number | undefined;
+        outputRef?: string | undefined;
+    }[];
+}, {
+    status: "pass" | "block";
+    summary: string;
+    findings?: {
+        title: string;
+        severity: "low" | "medium" | "high" | "critical";
+        path?: string | undefined;
+        line?: number | undefined;
+        recommendation?: string | undefined;
+    }[] | undefined;
+    testsRun?: {
+        status: "failed" | "passed" | "skipped";
+        command: string;
+        durationMs?: number | undefined;
+        outputRef?: string | undefined;
+    }[] | undefined;
+}>;
+export type ReviewVerdict = z.infer<typeof reviewVerdictSchema>;
+//# sourceMappingURL=agent-contracts.d.ts.map

package/dist/agent-contracts.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+export const artifactKindSchema = z.enum([
+    'brief',
+    'prd_lite',
+    'execution_graph',
+    'risk_review',
+    'acceptance_criteria',
+    'diff',
+    'review_verdict',
+    'test_result',
+    'debug_export',
+]);
+export const artifactRefSchema = z.object({
+    id: z.string().min(1),
+    kind: artifactKindSchema,
+    path: z.string().min(1).optional(),
+    uri: z.string().min(1).optional(),
+    title: z.string().min(1),
+    sha256: z.string().min(1).optional(),
+    createdAt: z.string().datetime(),
+});
+export const ideaBriefSchema = z.object({
+    id: z.string().min(1),
+    prompt: z.string().min(1),
+    targetUser: z.string().min(1).optional(),
+    currentStatusQuo: z.string().min(1).optional(),
+    narrowestWedge: z.string().min(1).optional(),
+    risks: z.array(z.string()).default([]),
+    acceptanceCriteria: z.array(z.string()).default([]),
+    artifacts: z.array(artifactRefSchema).default([]),
+});
+export const executionGraphNodeSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    kind: z.enum(['research', 'plan', 'code', 'review', 'test', 'ship']),
+    dependsOn: z.array(z.string()).default([]),
+    owner: z.string().min(1).optional(),
+    status: z.enum(['pending', 'in_progress', 'done', 'blocked']).default('pending'),
+    acceptanceCriteria: z.array(z.string()).default([]),
+});
+export const executionGraphSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    nodes: z.array(executionGraphNodeSchema),
+    artifacts: z.array(artifactRefSchema).default([]),
+});
+export const testResultSchema = z.object({
+    command: z.string().min(1),
+    status: z.enum(['passed', 'failed', 'skipped']),
+    durationMs: z.number().int().nonnegative().optional(),
+    outputRef: z.string().min(1).optional(),
+});
+export const reviewVerdictSchema = z.object({
+    status: z.enum(['pass', 'block']),
+    summary: z.string().min(1),
+    findings: z
+        .array(z.object({
+        severity: z.enum(['low', 'medium', 'high', 'critical']),
+        title: z.string().min(1),
+        path: z.string().min(1).optional(),
+        line: z.number().int().positive().optional(),
+        recommendation: z.string().min(1).optional(),
+    }))
+        .default([]),
+    testsRun: z.array(testResultSchema).default([]),
+});
+//# sourceMappingURL=agent-contracts.js.map