@piup/contracts 0.1.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,5 @@
+# @piup/contracts
+
+Shared TypeScript contracts for piup routes, workflows, tasks, Gates, Hooks, and plugin descriptors.
+
+See the [piup repository](https://github.com/Keylenn/piup) for documentation.

package/dist/index.d.mts

@@ -0,0 +1,175 @@
+//#region src/index.d.ts
+export declare const PIUP_API_VERSION: 1;
+export type RouteId = "debug" | "small" | "standard" | "foundation" | "infra";
+export type RequestKind = "read-only" | "change" | "ambiguous";
+export type RequestDisposition = "continue" | "reroute" | "follow-up" | "read-only" | "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;
+  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;
+}
+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 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,6 @@
+//#region src/index.ts
+const PIUP_API_VERSION = 1;
+//#endregion
+export { PIUP_API_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\nexport type RouteId = \"debug\" | \"small\" | \"standard\" | \"foundation\" | \"infra\";\nexport type RequestKind = \"read-only\" | \"change\" | \"ambiguous\";\nexport type RequestDisposition =\n  | \"continue\"\n  | \"reroute\"\n  | \"follow-up\"\n  | \"read-only\"\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  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\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 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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@piup/contracts",
+  "version": "0.1.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"
+  }
+}