@piup/contracts 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 piup contributors
+
+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,24 @@
+# @piup/contracts
+
+<p>
+<a href="https://www.npmjs.com/package/@piup/contracts"><img alt="NPM version" src="https://img.shields.io/npm/v/@piup/contracts.svg?logo=npm"></a>
+<a href="https://www.npmjs.com/package/@piup/contracts"><img alt="NPM downloads" src="https://img.shields.io/npm/dm/@piup/contracts.svg?logo=npm&color=blue"></a>
+<a href="https://bundlephobia.com/package/@piup/contracts">
+  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/@piup/contracts.svg?style=flat-square&logo=typescript&label=size">
+</a>
+<a href="https://www.npmjs.com/package/@piup/contracts"><img alt="Node Versions" src="https://img.shields.io/node/v/@piup/contracts.svg"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs-piup.keylenn.online">
+    <img src="https://docs-piup.keylenn.online/piup-logo.svg" alt="piup logo" width="128" height="128">
+  </a>
+</p>
+
+piup 的共享 TypeScript 协议与类型定义，覆盖请求路由、工作流、任务、检查门禁、Hook 和插件描述。
+
+## 快速开始
+
+本包是 piup 的基础依赖。使用 piup 时无需单独安装，统一通过 CLI 获取配套版本。
+
+完整使用指南与支持范围请查看 **[piup 文档](https://docs-piup.keylenn.online)**。

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+//#region src/index.d.ts
+export declare const PIUP_API_VERSION: 1;
+/** Tool schema generation: intent resolution, structured acceptance, recheck and read-only query. */
+export declare const PIUP_TOOL_PROTOCOL_VERSION: 2;
+export type RouteId = "debug" | "small" | "standard" | "foundation" | "infra";
+export type RequestKind = "read-only" | "change" | "delivery" | "ambiguous";
+export type DeliveryOperation = "commit" | "push";
+export type RequestDisposition = "continue" | "reroute" | "follow-up" | "read-only" | "delivery" | "clarify";
+export type Complexity = "low" | "medium" | "high";
+export type RiskLevel = "low" | "medium" | "high";
+export type DispatchMode = "inline";
+export interface RouteScope {
+  /** Workspace-relative paths. A single "." means the whole workspace. */
+  readonly paths: readonly string[];
+}
+/** A read-only routing decision. Producing this value must not create a task or mutate a workspace. */
+export interface RouteResult {
+  readonly requestKind: RequestKind;
+  /** Explicitly authorized Git delivery operations; never implies permission to edit source. */
+  readonly deliveryOperations?: readonly DeliveryOperation[];
+  readonly route: RouteId | null;
+  readonly complexity: Complexity | null;
+  readonly risk: RiskLevel | null;
+  readonly strategyId: string | null;
+  readonly dispatchMode: DispatchMode;
+  readonly scope: RouteScope;
+  readonly reason: string;
+}
+/** Semantic execution plan. Strategy IDs are derived by the host, never supplied by the agent. */
+export interface RoutingDecision {
+  readonly route: RouteId;
+  readonly complexity: Complexity;
+  readonly risk: RiskLevel;
+  readonly reason: string;
+}
+/** Agent interpretation of a pending turn; evidence refers only to supplied conversation sources. */
+export interface IntentDecision {
+  readonly turnId: string;
+  readonly kind: "read-only" | "change" | "clarify";
+  readonly relation: "none" | "new" | "continue" | "follow-up" | "recall";
+  readonly targetTaskId?: string;
+  /** Semantic task association, separate from current-turn authorization evidence. */
+  readonly matchReason?: string;
+  readonly basis: "standalone" | "contextual";
+  readonly goal: string;
+  /** Required for change decisions; optional for read-only/clarify and legacy persisted entries. */
+  readonly routing?: RoutingDecision;
+  readonly paths: readonly string[];
+  readonly evidence: readonly {
+    sourceId: string;
+    quote: string;
+  }[];
+  readonly constraints: readonly string[];
+  readonly clarification?: string;
+}
+export type StageStatus = "pending" | "running" | "validating" | "committed" | "waiting" | "blocked" | "failed" | "interrupted" | "cancelled";
+export type TaskStatus = "queued" | "running" | "completed" | "failed" | "interrupted" | "cancelled";
+export interface ExecutionIdentity {
+  readonly taskId: string;
+  readonly stageId: string;
+  readonly attempt: number;
+  readonly revision: number;
+  readonly leaseToken: string;
+}
+export type StageKind = "command" | "inline-agent";
+export type StagePhase = "analysis" | "implementation" | "check" | "acceptance";
+export interface CommandStageDefinition {
+  readonly id: string;
+  readonly type?: "command";
+  readonly phase?: StagePhase;
+  readonly command: readonly [string, ...string[]];
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+}
+export interface InlineAgentStageDefinition {
+  readonly id: string;
+  readonly type: "inline-agent";
+  readonly phase?: StagePhase;
+  readonly instructions?: string;
+}
+export type StageDefinition = CommandStageDefinition | InlineAgentStageDefinition;
+export type GateStatus = "pending" | "passed" | "failed" | "blocked" | "coverage_gap" | "not_applicable";
+export type AcceptanceStatus = "passed" | "failed" | "blocked" | "coverage_gap";
+/** References a persisted check execution, not a model-authored evidence string. */
+export interface AcceptanceEvidence {
+  readonly stageId: string;
+  readonly attempt: number;
+  readonly assertion: string;
+}
+export interface AcceptanceReport {
+  /** The complete original request, including authorized follow-up requests. */
+  readonly request: string;
+  readonly status: AcceptanceStatus;
+  /** Every listed requirement is mandatory; no implicit waivers. */
+  readonly requirements: readonly {
+    readonly requirement: string;
+    readonly status: AcceptanceStatus;
+    /** Required for passing requirements; manual reports remain review-only. */
+    readonly verification?: {
+      readonly method: "command" | "manual";
+      readonly scope: "whitespace" | "behavior";
+      readonly steps: readonly string[];
+    };
+    readonly evidence: readonly AcceptanceEvidence[];
+  }[];
+  readonly unverified: readonly string[];
+}
+export interface GateDefinition {
+  readonly id: string;
+  readonly required: boolean;
+  readonly description: string;
+}
+export interface Strategy {
+  readonly version: 1;
+  readonly id: string;
+  readonly route: RouteId;
+  readonly stages: readonly StageDefinition[];
+  readonly gates: readonly GateDefinition[];
+}
+export interface WorkflowDefinition {
+  readonly version: 1;
+  readonly name: string;
+  readonly stages: readonly StageDefinition[];
+  readonly gates?: readonly GateDefinition[];
+}
+export interface WorkspaceFileSnapshot {
+  readonly path: string;
+  readonly sha256: string;
+}
+export interface WorkspaceSnapshot {
+  readonly digest: string;
+  readonly files: readonly WorkspaceFileSnapshot[];
+}
+export interface TaskStageRecord {
+  readonly index: number;
+  readonly id: string;
+  readonly kind: StageKind;
+  readonly phase: StagePhase;
+  readonly status: StageStatus;
+  readonly attempt: number;
+  readonly command: readonly string[];
+  readonly cwd: string | null;
+  readonly instructions: string | null;
+  readonly startedAt: string | null;
+  readonly finishedAt: string | null;
+  readonly exitCode: number | null;
+  readonly logPath: string | null;
+  readonly summary: string | null;
+  readonly evidence: readonly string[];
+  readonly error: string | null;
+}
+export interface GateRecord {
+  readonly taskId: string;
+  readonly stageIndex: number;
+  readonly gateId: string;
+  readonly required: boolean;
+  readonly status: GateStatus;
+  readonly description: string;
+  readonly paths: readonly string[];
+  readonly workspaceDigest: string | null;
+  readonly details: Readonly<Record<string, unknown>>;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+export interface TaskRecord {
+  readonly id: string;
+  /** Isolates active task ownership between Pi terminal sessions. */
+  readonly ownerId: string;
+  readonly title: string;
+  readonly request: string;
+  readonly workflowName: string;
+  readonly workspace: string;
+  readonly status: TaskStatus;
+  readonly route: RouteId | null;
+  readonly strategyId: string | null;
+  readonly complexity: Complexity | null;
+  readonly risk: RiskLevel | null;
+  readonly scope: RouteScope;
+  readonly currentStageIndex: number;
+  readonly revision: number;
+  readonly planVersion: number;
+  readonly baselineDigest: string | null;
+  readonly validatedDigest: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly stages: readonly TaskStageRecord[];
+  readonly gates: readonly GateRecord[];
+}
+export interface TaskEvent {
+  readonly eventId: string;
+  readonly sequence: number;
+  readonly taskId: string;
+  readonly type: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly dedupeKey: string | null;
+  readonly createdAt: string;
+}
+export type HookKind = "transform" | "guard" | "observer" | "cleanup";
+export type HookInvocationStatus = "scheduled" | "started" | "succeeded" | "blocked" | "failed" | "timed_out" | "cancelled" | "interrupted";
+export interface HookInvocation {
+  readonly invocationId: string;
+  readonly taskId: string;
+  readonly stageId: string;
+  readonly attempt: number;
+  readonly revision: number;
+  readonly pluginId: string;
+  readonly hookName: string;
+  readonly kind: HookKind;
+  readonly inputRef: string;
+  readonly status: HookInvocationStatus;
+  readonly result: Readonly<Record<string, unknown>> | null;
+  readonly error: string | null;
+  readonly scheduledAt: string;
+  readonly startedAt: string | null;
+  readonly finishedAt: string | null;
+}
+export type GuardResult = {
+  readonly action: "continue";
+} | {
+  readonly action: "wait";
+  readonly request: string;
+} | {
+  readonly action: "block";
+  readonly reason: string;
+};
+export interface PluginDescriptor {
+  readonly id: string;
+  readonly apiVersion: typeof PIUP_API_VERSION;
+  readonly capabilities: readonly string[];
+}
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,8 @@
+//#region src/index.ts
+const PIUP_API_VERSION = 1;
+/** Tool schema generation: intent resolution, structured acceptance, recheck and read-only query. */
+const PIUP_TOOL_PROTOCOL_VERSION = 2;
+//#endregion
+export { PIUP_API_VERSION, PIUP_TOOL_PROTOCOL_VERSION };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export const PIUP_API_VERSION = 1 as const;\n/** Tool schema generation: intent resolution, structured acceptance, recheck and read-only query. */\nexport const PIUP_TOOL_PROTOCOL_VERSION = 2 as const;\n\nexport type RouteId = \"debug\" | \"small\" | \"standard\" | \"foundation\" | \"infra\";\nexport type RequestKind = \"read-only\" | \"change\" | \"delivery\" | \"ambiguous\";\nexport type DeliveryOperation = \"commit\" | \"push\";\nexport type RequestDisposition =\n  | \"continue\"\n  | \"reroute\"\n  | \"follow-up\"\n  | \"read-only\"\n  | \"delivery\"\n  | \"clarify\";\nexport type Complexity = \"low\" | \"medium\" | \"high\";\nexport type RiskLevel = \"low\" | \"medium\" | \"high\";\nexport type DispatchMode = \"inline\";\n\nexport interface RouteScope {\n  /** Workspace-relative paths. A single \".\" means the whole workspace. */\n  readonly paths: readonly string[];\n}\n\n/** A read-only routing decision. Producing this value must not create a task or mutate a workspace. */\nexport interface RouteResult {\n  readonly requestKind: RequestKind;\n  /** Explicitly authorized Git delivery operations; never implies permission to edit source. */\n  readonly deliveryOperations?: readonly DeliveryOperation[];\n  readonly route: RouteId | null;\n  readonly complexity: Complexity | null;\n  readonly risk: RiskLevel | null;\n  readonly strategyId: string | null;\n  readonly dispatchMode: DispatchMode;\n  readonly scope: RouteScope;\n  readonly reason: string;\n}\n\n/** Semantic execution plan. Strategy IDs are derived by the host, never supplied by the agent. */\nexport interface RoutingDecision {\n  readonly route: RouteId;\n  readonly complexity: Complexity;\n  readonly risk: RiskLevel;\n  readonly reason: string;\n}\n\n/** Agent interpretation of a pending turn; evidence refers only to supplied conversation sources. */\nexport interface IntentDecision {\n  readonly turnId: string;\n  readonly kind: \"read-only\" | \"change\" | \"clarify\";\n  readonly relation: \"none\" | \"new\" | \"continue\" | \"follow-up\" | \"recall\";\n  readonly targetTaskId?: string;\n  /** Semantic task association, separate from current-turn authorization evidence. */\n  readonly matchReason?: string;\n  readonly basis: \"standalone\" | \"contextual\";\n  readonly goal: string;\n  /** Required for change decisions; optional for read-only/clarify and legacy persisted entries. */\n  readonly routing?: RoutingDecision;\n  readonly paths: readonly string[];\n  readonly evidence: readonly { sourceId: string; quote: string }[];\n  readonly constraints: readonly string[];\n  readonly clarification?: string;\n}\n\nexport type StageStatus =\n  | \"pending\"\n  | \"running\"\n  | \"validating\"\n  | \"committed\"\n  | \"waiting\"\n  | \"blocked\"\n  | \"failed\"\n  | \"interrupted\"\n  | \"cancelled\";\n\nexport type TaskStatus =\n  | \"queued\"\n  | \"running\"\n  | \"completed\"\n  | \"failed\"\n  | \"interrupted\"\n  | \"cancelled\";\n\nexport interface ExecutionIdentity {\n  readonly taskId: string;\n  readonly stageId: string;\n  readonly attempt: number;\n  readonly revision: number;\n  readonly leaseToken: string;\n}\n\nexport type StageKind = \"command\" | \"inline-agent\";\nexport type StagePhase = \"analysis\" | \"implementation\" | \"check\" | \"acceptance\";\n\nexport interface CommandStageDefinition {\n  readonly id: string;\n  readonly type?: \"command\";\n  readonly phase?: StagePhase;\n  readonly command: readonly [string, ...string[]];\n  readonly cwd?: string;\n  readonly env?: Readonly<Record<string, string>>;\n}\n\nexport interface InlineAgentStageDefinition {\n  readonly id: string;\n  readonly type: \"inline-agent\";\n  readonly phase?: StagePhase;\n  readonly instructions?: string;\n}\n\nexport type StageDefinition =\n  | CommandStageDefinition\n  | InlineAgentStageDefinition;\n\nexport type GateStatus =\n  | \"pending\"\n  | \"passed\"\n  | \"failed\"\n  | \"blocked\"\n  | \"coverage_gap\"\n  | \"not_applicable\";\n\nexport type AcceptanceStatus = \"passed\" | \"failed\" | \"blocked\" | \"coverage_gap\";\n\n/** References a persisted check execution, not a model-authored evidence string. */\nexport interface AcceptanceEvidence {\n  readonly stageId: string;\n  readonly attempt: number;\n  readonly assertion: string;\n}\n\nexport interface AcceptanceReport {\n  /** The complete original request, including authorized follow-up requests. */\n  readonly request: string;\n  readonly status: AcceptanceStatus;\n  /** Every listed requirement is mandatory; no implicit waivers. */\n  readonly requirements: readonly {\n    readonly requirement: string;\n    readonly status: AcceptanceStatus;\n    /** Required for passing requirements; manual reports remain review-only. */\n    readonly verification?: {\n      readonly method: \"command\" | \"manual\";\n      readonly scope: \"whitespace\" | \"behavior\";\n      readonly steps: readonly string[];\n    };\n    readonly evidence: readonly AcceptanceEvidence[];\n  }[];\n  readonly unverified: readonly string[];\n}\n\nexport interface GateDefinition {\n  readonly id: string;\n  readonly required: boolean;\n  readonly description: string;\n}\n\nexport interface Strategy {\n  readonly version: 1;\n  readonly id: string;\n  readonly route: RouteId;\n  readonly stages: readonly StageDefinition[];\n  readonly gates: readonly GateDefinition[];\n}\n\nexport interface WorkflowDefinition {\n  readonly version: 1;\n  readonly name: string;\n  readonly stages: readonly StageDefinition[];\n  readonly gates?: readonly GateDefinition[];\n}\n\nexport interface WorkspaceFileSnapshot {\n  readonly path: string;\n  readonly sha256: string;\n}\n\nexport interface WorkspaceSnapshot {\n  readonly digest: string;\n  readonly files: readonly WorkspaceFileSnapshot[];\n}\n\nexport interface TaskStageRecord {\n  readonly index: number;\n  readonly id: string;\n  readonly kind: StageKind;\n  readonly phase: StagePhase;\n  readonly status: StageStatus;\n  readonly attempt: number;\n  readonly command: readonly string[];\n  readonly cwd: string | null;\n  readonly instructions: string | null;\n  readonly startedAt: string | null;\n  readonly finishedAt: string | null;\n  readonly exitCode: number | null;\n  readonly logPath: string | null;\n  readonly summary: string | null;\n  readonly evidence: readonly string[];\n  readonly error: string | null;\n}\n\nexport interface GateRecord {\n  readonly taskId: string;\n  readonly stageIndex: number;\n  readonly gateId: string;\n  readonly required: boolean;\n  readonly status: GateStatus;\n  readonly description: string;\n  readonly paths: readonly string[];\n  readonly workspaceDigest: string | null;\n  readonly details: Readonly<Record<string, unknown>>;\n  readonly createdAt: string;\n  readonly updatedAt: string;\n}\n\nexport interface TaskRecord {\n  readonly id: string;\n  /** Isolates active task ownership between Pi terminal sessions. */\n  readonly ownerId: string;\n  readonly title: string;\n  readonly request: string;\n  readonly workflowName: string;\n  readonly workspace: string;\n  readonly status: TaskStatus;\n  readonly route: RouteId | null;\n  readonly strategyId: string | null;\n  readonly complexity: Complexity | null;\n  readonly risk: RiskLevel | null;\n  readonly scope: RouteScope;\n  readonly currentStageIndex: number;\n  readonly revision: number;\n  readonly planVersion: number;\n  readonly baselineDigest: string | null;\n  readonly validatedDigest: string | null;\n  readonly createdAt: string;\n  readonly updatedAt: string;\n  readonly stages: readonly TaskStageRecord[];\n  readonly gates: readonly GateRecord[];\n}\n\nexport interface TaskEvent {\n  readonly eventId: string;\n  readonly sequence: number;\n  readonly taskId: string;\n  readonly type: string;\n  readonly payload: Readonly<Record<string, unknown>>;\n  readonly dedupeKey: string | null;\n  readonly createdAt: string;\n}\n\nexport type HookKind = \"transform\" | \"guard\" | \"observer\" | \"cleanup\";\nexport type HookInvocationStatus =\n  | \"scheduled\"\n  | \"started\"\n  | \"succeeded\"\n  | \"blocked\"\n  | \"failed\"\n  | \"timed_out\"\n  | \"cancelled\"\n  | \"interrupted\";\n\nexport interface HookInvocation {\n  readonly invocationId: string;\n  readonly taskId: string;\n  readonly stageId: string;\n  readonly attempt: number;\n  readonly revision: number;\n  readonly pluginId: string;\n  readonly hookName: string;\n  readonly kind: HookKind;\n  readonly inputRef: string;\n  readonly status: HookInvocationStatus;\n  readonly result: Readonly<Record<string, unknown>> | null;\n  readonly error: string | null;\n  readonly scheduledAt: string;\n  readonly startedAt: string | null;\n  readonly finishedAt: string | null;\n}\n\nexport type GuardResult =\n  | { readonly action: \"continue\" }\n  | { readonly action: \"wait\"; readonly request: string }\n  | { readonly action: \"block\"; readonly reason: string };\n\nexport interface PluginDescriptor {\n  readonly id: string;\n  readonly apiVersion: typeof PIUP_API_VERSION;\n  readonly capabilities: readonly string[];\n}\n"],"mappings":";AAAA,MAAa,mBAAmB;;AAEhC,MAAa,6BAA6B"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@piup/contracts",
+  "version": "0.0.1-beta.0",
+  "description": "Shared TypeScript contracts for piup workflows, tasks, Gates, and plugins.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keylenn/piup.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/Keylenn/piup#readme",
+  "bugs": {
+    "url": "https://github.com/Keylenn/piup/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}