@workflow-cannon/workspace-kit 0.16.0 → 0.17.0

package/dist/modules/task-engine/strict-task-validation.js

@@ -0,0 +1,52 @@
+import { validateKnownTaskTypeRequirements } from "./task-type-validation.js";
+const TASK_ID_RE = /^T\d+$/;
+const ALLOWED_STATUS = new Set(["proposed", "ready", "in_progress", "blocked", "completed", "cancelled"]);
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isIsoDateLike(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+export function validateTaskEntityForStrictMode(task) {
+    if (!TASK_ID_RE.test(task.id)) {
+        return `task '${task.id}' has invalid id format`;
+    }
+    if (typeof task.title !== "string" || task.title.trim().length === 0) {
+        return `task '${task.id}' has empty title`;
+    }
+    if (!ALLOWED_STATUS.has(task.status)) {
+        return `task '${task.id}' has unsupported status '${String(task.status)}'`;
+    }
+    if (typeof task.type !== "string" || task.type.trim().length === 0) {
+        return `task '${task.id}' has empty type`;
+    }
+    if (!isIsoDateLike(task.createdAt) || !isIsoDateLike(task.updatedAt)) {
+        return `task '${task.id}' has invalid createdAt/updatedAt timestamps`;
+    }
+    if (task.dependsOn !== undefined && !isStringArray(task.dependsOn)) {
+        return `task '${task.id}' has invalid dependsOn values`;
+    }
+    if (task.unblocks !== undefined && !isStringArray(task.unblocks)) {
+        return `task '${task.id}' has invalid unblocks values`;
+    }
+    if (task.technicalScope !== undefined && !isStringArray(task.technicalScope)) {
+        return `task '${task.id}' has invalid technicalScope values`;
+    }
+    if (task.acceptanceCriteria !== undefined && !isStringArray(task.acceptanceCriteria)) {
+        return `task '${task.id}' has invalid acceptanceCriteria values`;
+    }
+    const knownTypeValidation = validateKnownTaskTypeRequirements(task);
+    if (knownTypeValidation) {
+        return `task '${task.id}': ${knownTypeValidation.message}`;
+    }
+    return null;
+}
+export function validateTaskSetForStrictMode(tasks) {
+    for (const task of tasks) {
+        const issue = validateTaskEntityForStrictMode(task);
+        if (issue) {
+            return issue;
+        }
+    }
+    return null;
+}

package/dist/modules/task-engine/task-type-validation.d.ts

@@ -0,0 +1,10 @@
+import type { TaskEntity } from "./types.js";
+export type KnownTaskTypeValidationError = {
+    code: "invalid-task-type-requirements";
+    message: string;
+};
+/**
+ * Optional strictness for known task types.
+ * Unknown/custom task types remain passthrough for compatibility.
+ */
+export declare function validateKnownTaskTypeRequirements(task: TaskEntity): KnownTaskTypeValidationError | null;

package/dist/modules/task-engine/task-type-validation.js

@@ -0,0 +1,26 @@
+function nonEmptyStringArray(value) {
+    return Array.isArray(value) && value.some((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+/**
+ * Optional strictness for known task types.
+ * Unknown/custom task types remain passthrough for compatibility.
+ */
+export function validateKnownTaskTypeRequirements(task) {
+    if (task.type !== "improvement") {
+        return null;
+    }
+    const missing = [];
+    if (!nonEmptyStringArray(task.acceptanceCriteria)) {
+        missing.push("acceptanceCriteria");
+    }
+    if (!nonEmptyStringArray(task.technicalScope)) {
+        missing.push("technicalScope");
+    }
+    if (missing.length === 0) {
+        return null;
+    }
+    return {
+        code: "invalid-task-type-requirements",
+        message: `Type '${task.type}' requires non-empty fields: ${missing.join(", ")}`
+    };
+}

package/dist/modules/task-engine/types.d.ts

@@ -65,7 +65,7 @@ export type TaskEngineError = {
     code: TaskEngineErrorCode;
     message: string;
 };
-export type TaskEngineErrorCode = "invalid-transition" | "guard-rejected" | "dependency-unsatisfied" | "task-not-found" | "duplicate-task-id" | "invalid-task-schema" | "invalid-task-update" | "invalid-task-id-format" | "task-archived" | "dependency-cycle" | "duplicate-dependency" | "storage-read-error" | "storage-write-error" | "invalid-adapter" | "import-parse-error";
+export type TaskEngineErrorCode = "invalid-transition" | "guard-rejected" | "dependency-unsatisfied" | "task-not-found" | "duplicate-task-id" | "invalid-task-schema" | "invalid-task-type-requirements" | "invalid-task-update" | "invalid-task-id-format" | "task-archived" | "dependency-cycle" | "duplicate-dependency" | "storage-read-error" | "storage-write-error" | "invalid-adapter" | "import-parse-error";
 export type TaskAdapter = {
     name: string;
     supports: () => TaskAdapterCapability[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit && node scripts/check-task-engine-run-contracts.mjs",
     "clean": "rm -rf dist",
     "test": "pnpm run build && node --test test/**/*.test.mjs",
     "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",
@@ -48,6 +48,7 @@
   "files": [
     "dist",
     "src/modules/documentation",
+    "schemas",
     "package.json"
   ],
   "dependencies": {

package/schemas/compatibility-matrix.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workflow-cannon.dev/schemas/compatibility-matrix.schema.json",
+  "title": "Workflow Cannon Compatibility Matrix",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "runtime", "modules", "channels"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "runtime": {
+      "type": "object",
+      "required": ["runtimeVersion", "moduleContractVersion", "configSchema", "policyTraceSchema"],
+      "properties": {
+        "runtimeVersion": { "type": "string", "minLength": 1 },
+        "moduleContractVersion": { "type": "string", "enum": ["1"] },
+        "configSchema": { "type": "integer", "minimum": 1 },
+        "policyTraceSchema": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "modules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "version", "contractVersion", "compatibilityLevel", "supportedRuntime", "severity"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+          "contractVersion": { "type": "string", "enum": ["1"] },
+          "compatibilityLevel": { "type": "string", "enum": ["strict", "compatible", "warn-only"] },
+          "supportedRuntime": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "enum": ["error", "warn"] },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "channels": {
+      "type": "array",
+      "minItems": 3,
+      "items": {
+        "type": "object",
+        "required": ["name", "npmDistTag", "releaseLabel", "tagPrefix", "allowPrerelease"],
+        "properties": {
+          "name": { "type": "string", "enum": ["canary", "stable", "lts"] },
+          "npmDistTag": { "type": "string", "minLength": 1 },
+          "releaseLabel": { "type": "string", "minLength": 1 },
+          "tagPrefix": { "type": "string", "minLength": 1 },
+          "allowPrerelease": { "type": "boolean" },
+          "rollback": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/parity-evidence.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/NJLaPrell/workflow-cannon/schemas/parity-evidence.schema.json",
+  "title": "Parity Evidence",
+  "description": "Machine-readable evidence artifact from parity validation runs.",
+  "type": "object",
+  "required": ["schemaVersion", "runner", "timestamp", "overall", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version for forward compatibility."
+    },
+    "runner": {
+      "type": "string",
+      "description": "Path to the runner script that produced this evidence."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of when the run completed."
+    },
+    "overall": {
+      "type": "string",
+      "enum": ["pass", "fail"],
+      "description": "Aggregate outcome of the parity run."
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered results for each step in the parity command chain.",
+      "items": {
+        "type": "object",
+        "required": ["name", "status", "durationMs"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Step identifier matching the canonical command chain."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail"],
+            "description": "Outcome for this step."
+          },
+          "durationMs": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Wall-clock duration of this step in milliseconds."
+          },
+          "error": {
+            "type": "string",
+            "description": "First 500 characters of stderr on failure. Absent on pass."
+          }
+        }
+      }
+    }
+  }
+}