todo-enforcer 1.0.0

package/src/type-guards.ts

@@ -0,0 +1,105 @@
+/**
+ * type-guards — Runtime type guards for todo-enforcer
+ *
+ * Replaces `as X` type assertions with safe runtime checks.
+ * Each guard narrows `unknown` to a specific type.
+ */
+// @ts-nocheck
+
+// 
+
+
+// ─── Primitive guards ────────────────────────────────────────────────────────
+
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Check if a value is a string.
+ */
+export function isString(v: unknown): v is string {
+	return typeof v === "string";
+}
+
+// ─── Session entry guards ─────────────────────────────────────────────────────
+
+/**
+ * Check if a value has a `message` property (session entry shape).
+ */
+export function hasMessage(
+	v: unknown,
+): v is { message?: { customType?: string; role?: string; toolName?: string; content?: unknown } } {
+	if (!isRecord(v)) return false;
+	return "message" in v;
+}
+
+/**
+ * Check if a value has a `role` property (session message shape).
+ */
+export function hasRole(v: unknown): v is { role?: string; [key: string]: unknown } {
+	return isRecord(v) && "role" in v;
+}
+
+/**
+ * Check if a value has a `stopReason` property.
+ */
+export function hasStopReason(v: unknown): v is { stopReason?: string; [key: string]: unknown } {
+	return isRecord(v) && "stopReason" in v;
+}
+
+// ─── Safe extractors ──────────────────────────────────────────────────────────
+
+/**
+ * Safely extract string content from unknown value.
+ * Returns the string if it's a string, empty string otherwise.
+ */
+export function getStringContent(content: unknown): string {
+	return isString(content) ? content : "";
+}
+
+/**
+ * Safely extract `role` from an unknown value.
+ * Returns the role string if present, undefined otherwise.
+ */
+export function extractRole(m: unknown): string | undefined {
+	if (!hasRole(m)) return undefined;
+	return typeof m.role === "string" ? m.role : undefined;
+}
+
+/**
+ * Safely extract `stopReason` from an unknown value.
+ * Returns the stopReason string if present, undefined otherwise.
+ */
+export function extractStopReason(m: unknown): string | undefined {
+	if (!hasStopReason(m)) return undefined;
+	return typeof m.stopReason === "string" ? m.stopReason : undefined;
+}
+
+// ─── Array guards ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if a value is an array of session entries.
+ * Each entry must be an object with a `type` property (string).
+ */
+export function isSessionEntryArray(v: unknown): v is Array<{ type: string; message?: unknown }> {
+	if (!Array.isArray(v)) return false;
+	return v.every(
+		(entry) => isRecord(entry) && typeof entry.type === "string",
+	);
+}
+
+// ─── Config guards ────────────────────────────────────────────────────────────
+
+/**
+ * Check if a value looks like a partial TodoEnforcerConfig.
+ * At minimum it must be a non-null plain object.
+ */
+export function isPartialTodoConfig(
+	v: unknown,
+): v is Partial<import("./config").TodoEnforcerConfig> {
+	return isRecord(v);
+}

package/todo-enforcer.example.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "./todo-enforcer/config.schema.json",
+  "enabled": true,
+  "maxInjections": 5,
+  "cooldownMs": 60000,
+  "completionSummary": false,
+  "detectStagnation": true,
+  "stagnationThreshold": 3,
+  "messageDelivery": {
+    "customType": "todo-enforcer",
+    "display": true,
+    "triggerTurn": true,
+    "deliverAs": "followUp"
+  },
+  "contextFeed": {
+    "userMode": "latest",
+    "assistantMode": "allSinceLatestUser",
+    "includeSessionMetadata": true,
+    "excludePreviousEnforcerMessages": true
+  },
+  "rules": [
+    {
+      "name": "incomplete-tasks-remain",
+      "condition": "has_incomplete",
+      "action": "prompt",
+      "prompt": "You have incomplete tasks. Continue working on them.\n\n[Status: {{completed_count}}/{{total_count}} completed, {{incomplete_count}} remaining]\n\nRemaining tasks:\n{{incomplete_list}}\n\nLatest user message:\n{{latest_user_message}}\n\nRecent assistant messages:\n{{assistant_messages}}\n\nPick up where you left off. Do NOT stop until all tasks are completed or explicitly blocked."
+    },
+    {
+      "name": "all-complete-celebration",
+      "condition": "all_complete",
+      "action": "prompt",
+      "prompt": "All {{total_count}} tasks are complete. Great work.\n\nCompleted tasks:\n{{completed_list}}\n\nYou may now summarize the results or ask the user for next steps."
+    },
+    {
+      "name": "remote-followup",
+      "condition": "has_incomplete",
+      "action": "external",
+      "external": {
+        "silent": true,
+        "errorFallback": "default_prompt",
+        "http": {
+          "url": "https://example.com/todo-enforcer",
+          "method": "POST",
+          "headers": {
+            "authorization": "Bearer <token>"
+          },
+          "timeoutMs": 15000
+        }
+      }
+    }
+  ]
+}