@jonit-dev/night-watch-cli 1.1.3 → 1.1.5

package/dist/utils/notify.js

@@ -0,0 +1,237 @@
+/**
+ * Notification utilities for Night Watch CLI
+ * Sends webhook notifications to Slack, Discord, and Telegram
+ */
+import { warn, info } from "./ui.js";
+import { extractSummary } from "./github.js";
+/**
+ * Get the emoji for a notification event
+ */
+export function getEventEmoji(event) {
+    switch (event) {
+        case "run_succeeded":
+            return "\u2705";
+        case "run_failed":
+            return "\u274C";
+        case "run_timeout":
+            return "\u23F0";
+        case "review_completed":
+            return "\uD83D\uDD0D";
+    }
+}
+/**
+ * Get a human-readable title for a notification event
+ */
+export function getEventTitle(event) {
+    switch (event) {
+        case "run_succeeded":
+            return "PRD Execution Succeeded";
+        case "run_failed":
+            return "PRD Execution Failed";
+        case "run_timeout":
+            return "PRD Execution Timed Out";
+        case "review_completed":
+            return "PR Review Completed";
+    }
+}
+/**
+ * Get the Discord embed color for a notification event
+ */
+export function getEventColor(event) {
+    switch (event) {
+        case "run_succeeded":
+            return 0x00ff00;
+        case "run_failed":
+            return 0xff0000;
+        case "run_timeout":
+            return 0xff0000;
+        case "review_completed":
+            return 0x0099ff;
+    }
+}
+/**
+ * Build a description string from notification context
+ */
+export function buildDescription(ctx) {
+    const lines = [];
+    lines.push(`Project: ${ctx.projectName}`);
+    lines.push(`Provider: ${ctx.provider}`);
+    lines.push(`Exit code: ${ctx.exitCode}`);
+    if (ctx.prdName) {
+        lines.push(`PRD: ${ctx.prdName}`);
+    }
+    if (ctx.branchName) {
+        lines.push(`Branch: ${ctx.branchName}`);
+    }
+    if (ctx.prNumber !== undefined) {
+        lines.push(`PR: #${ctx.prNumber}`);
+    }
+    if (ctx.duration !== undefined) {
+        lines.push(`Duration: ${ctx.duration}s`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Escape special characters for Telegram MarkdownV2 format
+ */
+function escapeMarkdownV2(text) {
+    return text.replace(/[_*[\]()~`>#+=|{}.!-]/g, "\\$&");
+}
+/**
+ * Format a notification payload for Slack incoming webhooks
+ */
+export function formatSlackPayload(ctx) {
+    const emoji = getEventEmoji(ctx.event);
+    const title = getEventTitle(ctx.event);
+    const description = buildDescription(ctx);
+    let color;
+    if (ctx.event === "run_succeeded") {
+        color = "#00ff00";
+    }
+    else if (ctx.event === "review_completed") {
+        color = "#0099ff";
+    }
+    else {
+        color = "#ff0000";
+    }
+    return {
+        attachments: [
+            {
+                color,
+                blocks: [
+                    {
+                        type: "section",
+                        text: {
+                            type: "mrkdwn",
+                            text: `*${emoji} ${title}*\n${description}`,
+                        },
+                    },
+                ],
+            },
+        ],
+    };
+}
+/**
+ * Format a notification payload for Discord webhooks
+ */
+export function formatDiscordPayload(ctx) {
+    const emoji = getEventEmoji(ctx.event);
+    const title = getEventTitle(ctx.event);
+    const description = buildDescription(ctx);
+    return {
+        embeds: [
+            {
+                title: `${emoji} ${title}`,
+                description,
+                color: getEventColor(ctx.event),
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    };
+}
+/**
+ * Build a structured Telegram message when PR details are available.
+ * Falls back to the basic format when they are not.
+ */
+export function formatTelegramPayload(ctx) {
+    const emoji = getEventEmoji(ctx.event);
+    const title = getEventTitle(ctx.event);
+    // If PR details are present, use the rich structured template
+    if (ctx.prUrl && ctx.prTitle) {
+        const lines = [];
+        lines.push(`*${escapeMarkdownV2(emoji + " " + title)}*`);
+        lines.push("");
+        lines.push(`${escapeMarkdownV2("📋")} *${escapeMarkdownV2("PR #" + (ctx.prNumber ?? "") + ": " + ctx.prTitle)}*`);
+        lines.push(`${escapeMarkdownV2("🔗")} ${escapeMarkdownV2(ctx.prUrl)}`);
+        // Summary from PR body
+        if (ctx.prBody && ctx.prBody.trim().length > 0) {
+            const summary = extractSummary(ctx.prBody);
+            if (summary) {
+                lines.push("");
+                lines.push(`${escapeMarkdownV2("📝 Summary")}`);
+                lines.push(escapeMarkdownV2(summary));
+            }
+        }
+        // Stats
+        if (ctx.filesChanged !== undefined || ctx.additions !== undefined) {
+            lines.push("");
+            lines.push(`${escapeMarkdownV2("📊 Stats")}`);
+            const stats = [];
+            if (ctx.filesChanged !== undefined) {
+                stats.push(`Files changed: ${ctx.filesChanged}`);
+            }
+            if (ctx.additions !== undefined && ctx.deletions !== undefined) {
+                stats.push(`+${ctx.additions} / -${ctx.deletions}`);
+            }
+            lines.push(escapeMarkdownV2(stats.join(" | ")));
+        }
+        // Footer
+        lines.push("");
+        lines.push(escapeMarkdownV2(`⚙️ Project: ${ctx.projectName} | Provider: ${ctx.provider}`));
+        return {
+            text: lines.join("\n"),
+            parse_mode: "MarkdownV2",
+        };
+    }
+    // Fallback: basic format (no PR details)
+    const description = buildDescription(ctx);
+    return {
+        text: `*${escapeMarkdownV2(emoji + " " + title)}*\n\n${escapeMarkdownV2(description)}`,
+        parse_mode: "MarkdownV2",
+    };
+}
+/**
+ * Send a notification to a single webhook endpoint
+ * Silently catches errors — never throws
+ */
+export async function sendWebhook(webhook, ctx) {
+    // Skip if this event is not in the webhook's configured events
+    if (!webhook.events.includes(ctx.event)) {
+        return;
+    }
+    try {
+        let url;
+        let body;
+        switch (webhook.type) {
+            case "slack": {
+                url = webhook.url;
+                body = JSON.stringify(formatSlackPayload(ctx));
+                break;
+            }
+            case "discord": {
+                url = webhook.url;
+                body = JSON.stringify(formatDiscordPayload(ctx));
+                break;
+            }
+            case "telegram": {
+                url = `https://api.telegram.org/bot${webhook.botToken}/sendMessage`;
+                const telegramPayload = formatTelegramPayload(ctx);
+                body = JSON.stringify({ chat_id: webhook.chatId, ...telegramPayload });
+                break;
+            }
+        }
+        await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warn(`Notification failed (${webhook.type}): ${message}`);
+    }
+}
+/**
+ * Send notifications to all configured webhooks
+ */
+export async function sendNotifications(config, ctx) {
+    if (!config.notifications || config.notifications.webhooks.length === 0) {
+        return;
+    }
+    const webhooks = config.notifications.webhooks;
+    const results = await Promise.allSettled(webhooks.map((wh) => sendWebhook(wh, ctx)));
+    const sent = results.filter((r) => r.status === "fulfilled").length;
+    const total = webhooks.length;
+    info(`Sent ${sent}/${total} notifications`);
+}
+//# sourceMappingURL=notify.js.map

package/dist/utils/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/utils/notify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jonit-dev/night-watch-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Autonomous PRD execution using AI Provider CLIs + cron",
   "type": "module",
   "bin": {
@@ -40,11 +40,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/joaopio/night-watch-cli.git"
+    "url": "https://github.com/jonit-dev/night-watch-cli.git"
   },
-  "homepage": "https://github.com/joaopio/night-watch-cli#readme",
+  "homepage": "https://github.com/jonit-dev/night-watch-cli#readme",
   "bugs": {
-    "url": "https://github.com/joaopio/night-watch-cli/issues"
+    "url": "https://github.com/jonit-dev/night-watch-cli/issues"
   },
   "dependencies": {
     "chalk": "^5.6.2",

package/scripts/night-watch-cron.sh

@@ -55,16 +55,26 @@ fi
 
 cleanup_worktrees "${PROJECT_DIR}"
 
-ELIGIBLE_PRD=$(find_eligible_prd "${PRD_DIR}")
+ELIGIBLE_PRD=$(find_eligible_prd "${PRD_DIR}" "${MAX_RUNTIME}")
 
 if [ -z "${ELIGIBLE_PRD}" ]; then
   log "SKIP: No eligible PRDs (all done, in-progress, or blocked)"
   exit 0
 fi
 
+# Claim the PRD to prevent other runs from selecting it
+claim_prd "${PRD_DIR}" "${ELIGIBLE_PRD}"
+
+# Update EXIT trap to also release claim
+trap "rm -f '${LOCK_FILE}'; release_claim '${PRD_DIR}' '${ELIGIBLE_PRD}'" EXIT
+
 PRD_NAME="${ELIGIBLE_PRD%.md}"
 BRANCH_NAME="night-watch/${PRD_NAME}"
-DEFAULT_BRANCH=$(detect_default_branch "${PROJECT_DIR}")
+if [ -n "${NW_DEFAULT_BRANCH:-}" ]; then
+  DEFAULT_BRANCH="${NW_DEFAULT_BRANCH}"
+else
+  DEFAULT_BRANCH=$(detect_default_branch "${PROJECT_DIR}")
+fi
 
 log "START: Processing ${ELIGIBLE_PRD} on branch ${BRANCH_NAME}"
 
@@ -142,6 +152,7 @@ esac
 if [ ${EXIT_CODE} -eq 0 ]; then
   PR_EXISTS=$(gh pr list --state open --json headRefName --jq '.[].headRefName' 2>/dev/null | grep -cF "${BRANCH_NAME}" || echo "0")
   if [ "${PR_EXISTS}" -gt 0 ]; then
+    release_claim "${PRD_DIR}" "${ELIGIBLE_PRD}"
     mark_prd_done "${PRD_DIR}" "${ELIGIBLE_PRD}"
     git -C "${PROJECT_DIR}" add -A docs/PRDs/night-watch/
     git -C "${PROJECT_DIR}" commit -m "chore: mark ${ELIGIBLE_PRD} as done (PR opened on ${BRANCH_NAME})

package/scripts/night-watch-helpers.sh

@@ -118,10 +118,55 @@ detect_default_branch() {
   echo "main"
 }
 
+# ── Claim management ─────────────────────────────────────────────────────────
+
+claim_prd() {
+  local prd_dir="${1:?prd_dir required}"
+  local prd_file="${2:?prd_file required}"
+  local claim_file="${prd_dir}/${prd_file}.claim"
+
+  printf '{"timestamp":%d,"hostname":"%s","pid":%d}\n' \
+    "$(date +%s)" "$(hostname)" "$$" > "${claim_file}"
+}
+
+release_claim() {
+  local prd_dir="${1:?prd_dir required}"
+  local prd_file="${2:?prd_file required}"
+  local claim_file="${prd_dir}/${prd_file}.claim"
+
+  rm -f "${claim_file}"
+}
+
+is_claimed() {
+  local prd_dir="${1:?prd_dir required}"
+  local prd_file="${2:?prd_file required}"
+  local max_runtime="${3:-7200}"
+  local claim_file="${prd_dir}/${prd_file}.claim"
+
+  if [ ! -f "${claim_file}" ]; then
+    return 1
+  fi
+
+  local claim_ts
+  claim_ts=$(grep -o '"timestamp":[0-9]*' "${claim_file}" 2>/dev/null | grep -o '[0-9]*' || echo "0")
+  local now
+  now=$(date +%s)
+  local age=$(( now - claim_ts ))
+
+  if [ "${age}" -lt "${max_runtime}" ]; then
+    return 0  # actively claimed
+  else
+    # Stale claim — remove it
+    rm -f "${claim_file}"
+    return 1
+  fi
+}
+
 # ── Find next eligible PRD ───────────────────────────────────────────────────
 
 find_eligible_prd() {
   local prd_dir="${1:?prd_dir required}"
+  local max_runtime="${2:-7200}"
   local done_dir="${prd_dir}/done"
 
   local prd_files
@@ -139,6 +184,12 @@ find_eligible_prd() {
     prd_file=$(basename "${prd_path}")
     local prd_name="${prd_file%.md}"
 
+    # Skip if claimed by another process
+    if is_claimed "${prd_dir}" "${prd_file}" "${max_runtime}"; then
+      log "SKIP-PRD: ${prd_file} — claimed by another process"
+      continue
+    fi
+
     # Skip if a PR already exists for this PRD
     if echo "${open_branches}" | grep -qF "${prd_name}"; then
       log "SKIP-PRD: ${prd_file} — open PR already exists"

package/scripts/test-helpers.bats

@@ -0,0 +1,77 @@
+#!/usr/bin/env bats
+
+# Tests for night-watch-helpers.sh claim functions
+
+setup() {
+  # Source the helpers
+  SCRIPT_DIR="$(cd "$(dirname "${BATS_TEST_FILENAME}")" && pwd)"
+
+  # Set required globals
+  export LOG_FILE="/tmp/night-watch-test-$$.log"
+
+  source "${SCRIPT_DIR}/night-watch-helpers.sh"
+
+  # Create temp PRD directory
+  TEST_PRD_DIR=$(mktemp -d)
+  echo "# Test PRD" > "${TEST_PRD_DIR}/01-test-prd.md"
+  echo "# Test PRD 2" > "${TEST_PRD_DIR}/02-test-prd.md"
+}
+
+teardown() {
+  rm -rf "${TEST_PRD_DIR}"
+  rm -f "${LOG_FILE}"
+}
+
+@test "claim_prd creates .claim file with JSON" {
+  claim_prd "${TEST_PRD_DIR}" "01-test-prd.md"
+
+  [ -f "${TEST_PRD_DIR}/01-test-prd.md.claim" ]
+
+  local content
+  content=$(cat "${TEST_PRD_DIR}/01-test-prd.md.claim")
+
+  # Check JSON contains expected fields
+  echo "${content}" | grep -q '"timestamp":'
+  echo "${content}" | grep -q '"hostname":'
+  echo "${content}" | grep -q '"pid":'
+}
+
+@test "is_claimed returns 0 for active claim" {
+  claim_prd "${TEST_PRD_DIR}" "01-test-prd.md"
+
+  run is_claimed "${TEST_PRD_DIR}" "01-test-prd.md" 7200
+  [ "$status" -eq 0 ]
+}
+
+@test "is_claimed returns 1 for stale claim" {
+  # Write a claim with an old timestamp (1 second)
+  printf '{"timestamp":1000000000,"hostname":"test","pid":1}\n' \
+    > "${TEST_PRD_DIR}/01-test-prd.md.claim"
+
+  run is_claimed "${TEST_PRD_DIR}" "01-test-prd.md" 7200
+  [ "$status" -eq 1 ]
+}
+
+@test "is_claimed returns 1 for no claim" {
+  run is_claimed "${TEST_PRD_DIR}" "01-test-prd.md" 7200
+  [ "$status" -eq 1 ]
+}
+
+@test "release_claim removes .claim file" {
+  claim_prd "${TEST_PRD_DIR}" "01-test-prd.md"
+  [ -f "${TEST_PRD_DIR}/01-test-prd.md.claim" ]
+
+  release_claim "${TEST_PRD_DIR}" "01-test-prd.md"
+  [ ! -f "${TEST_PRD_DIR}/01-test-prd.md.claim" ]
+}
+
+@test "find_eligible_prd skips claimed PRD" {
+  # Claim the first PRD
+  claim_prd "${TEST_PRD_DIR}" "01-test-prd.md"
+
+  # find_eligible_prd should skip 01 and return 02
+  local result
+  result=$(find_eligible_prd "${TEST_PRD_DIR}" 7200)
+
+  [ "${result}" = "02-test-prd.md" ]
+}

package/templates/prd.md

@@ -0,0 +1,26 @@
+# PRD: {{TITLE}}
+
+{{DEPENDS_ON}}
+
+**Complexity: {{COMPLEXITY_SCORE}} → {{COMPLEXITY_LEVEL}} mode**
+{{COMPLEXITY_BREAKDOWN}}
+
+---
+
+## Problem
+
+<!-- What problem does this solve? Describe in 1-2 sentences. -->
+
+## Solution
+
+<!-- How will you solve it? 3-5 bullets explaining the approach. -->
+
+## Phases
+
+{{PHASES}}
+
+## Acceptance Criteria
+
+- [ ] All phases complete
+- [ ] All tests pass
+- [ ] Feature is reachable (not orphaned code)