@josharsh/demon-cli 0.1.0

package/dist/watchers/http.js

@@ -0,0 +1,149 @@
+import axios from 'axios';
+import { createHash } from 'crypto';
+import fs from 'fs-extra';
+import { join } from 'path';
+import { homedir } from 'os';
+function stateFilePath(url) {
+    const safe = url.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 80);
+    return join(homedir(), '.demon', 'watcher-state', `http_${safe}.json`);
+}
+function hashBody(data) {
+    const str = typeof data === 'string' ? data : JSON.stringify(data);
+    return createHash('sha256').update(str).digest('hex');
+}
+function diffSummary(prev, next) {
+    if (!prev)
+        return 'Response content changed (first baseline set)';
+    return `Response hash changed: ${prev.slice(0, 8)} → ${next.slice(0, 8)}`;
+}
+export class HttpWatcher {
+    type = 'http';
+    config;
+    stateFile;
+    state = {
+        lastHash: null,
+        lastStatusCode: null,
+        lastCheckedAt: null,
+    };
+    stateLoaded = false;
+    constructor(config) {
+        this.config = config;
+        this.stateFile = stateFilePath(config.url ?? 'unknown');
+    }
+    async loadState() {
+        if (this.stateLoaded)
+            return;
+        try {
+            await fs.ensureDir(join(homedir(), '.demon', 'watcher-state'));
+            if (await fs.pathExists(this.stateFile)) {
+                this.state = await fs.readJson(this.stateFile);
+            }
+        }
+        catch {
+            // Start fresh if state is corrupt
+        }
+        this.stateLoaded = true;
+    }
+    async saveState() {
+        try {
+            await fs.writeJson(this.stateFile, this.state, { spaces: 2 });
+        }
+        catch {
+            // Non-fatal — worst case we re-baseline next cycle
+        }
+    }
+    async collect() {
+        const { url, headers } = this.config;
+        if (!url)
+            throw new Error('http watcher requires a "url" field');
+        await this.loadState();
+        const startTime = Date.now();
+        let responseData;
+        let statusCode;
+        let error;
+        try {
+            const response = await axios.get(url, {
+                headers: headers ?? {},
+                timeout: 30_000,
+                validateStatus: () => true,
+            });
+            statusCode = response.status;
+            responseData = response.data;
+        }
+        catch (err) {
+            statusCode = 0;
+            error = err.message;
+        }
+        const latencyMs = Date.now() - startTime;
+        const isError = statusCode >= 400 || statusCode === 0;
+        const currentHash = error ? null : hashBody(responseData);
+        const contentChanged = currentHash !== null && currentHash !== this.state.lastHash;
+        const statusChanged = this.state.lastStatusCode !== null && statusCode !== this.state.lastStatusCode;
+        // Update persisted state
+        const prevHash = this.state.lastHash;
+        this.state = {
+            lastHash: currentHash ?? this.state.lastHash,
+            lastStatusCode: statusCode,
+            lastCheckedAt: new Date().toISOString(),
+        };
+        await this.saveState();
+        // Only emit an observation when something is notable
+        const shouldReport = isError || contentChanged || statusChanged || prevHash === null;
+        if (!shouldReport) {
+            return []; // No change, no error — skip this cycle
+        }
+        let summary;
+        if (error) {
+            summary = `HTTP GET ${url} failed: ${error}`;
+        }
+        else if (isError) {
+            summary = `HTTP GET ${url} → ${statusCode} ERROR (${latencyMs}ms)`;
+        }
+        else if (prevHash === null) {
+            summary = `HTTP GET ${url} → ${statusCode} OK (${latencyMs}ms) — baseline recorded`;
+        }
+        else if (statusChanged) {
+            summary = `HTTP GET ${url} status changed: ${this.state.lastStatusCode} → ${statusCode} (${latencyMs}ms)`;
+        }
+        else {
+            summary =
+                `HTTP GET ${url} → ${statusCode} OK (${latencyMs}ms) — ` +
+                    diffSummary(prevHash, currentHash);
+        }
+        return [
+            {
+                watcherType: this.type,
+                data: {
+                    url,
+                    statusCode,
+                    latencyMs,
+                    isOk: !isError,
+                    isError,
+                    contentChanged,
+                    statusChanged,
+                    currentHash: currentHash?.slice(0, 16) ?? null,
+                    previousHash: prevHash?.slice(0, 16) ?? null,
+                    error,
+                    body: error ? undefined : truncateBody(responseData),
+                },
+                summary,
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+}
+function truncateBody(data) {
+    if (typeof data === 'string') {
+        return data.length > 2000 ? data.slice(0, 2000) + '... [truncated]' : data;
+    }
+    if (typeof data === 'object' && data !== null) {
+        const json = JSON.stringify(data);
+        if (json.length > 2000) {
+            // Return a truncated string representation rather than broken JSON
+            return json.slice(0, 2000) + '... [truncated]';
+        }
+        return data;
+    }
+    return data;
+}
+//# sourceMappingURL=http.js.map

package/dist/watchers/http.js.map

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

package/dist/watchers/index.d.ts

@@ -0,0 +1,8 @@
+import { Watcher, WatcherConfig } from '../types.js';
+export { createWatcher } from './base.js';
+/**
+ * buildWatcher — convenience factory used by the daemon loop.
+ * Credentials are resolved inside each watcher from env/secrets/providers.
+ */
+export declare function buildWatcher(config: WatcherConfig): Watcher;
+//# sourceMappingURL=index.d.ts.map

package/dist/watchers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watchers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAKpD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAEzC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAe3D"}

package/dist/watchers/index.js

@@ -0,0 +1,25 @@
+import { buildGitHubWatcher } from './github.js';
+import { HttpWatcher } from './http.js';
+import { FilesystemWatcher } from './filesystem.js';
+export { createWatcher } from './base.js';
+/**
+ * buildWatcher — convenience factory used by the daemon loop.
+ * Credentials are resolved inside each watcher from env/secrets/providers.
+ */
+export function buildWatcher(config) {
+    switch (config.type) {
+        case 'github_prs':
+        case 'github_ci':
+        case 'github_commits':
+            return buildGitHubWatcher(config, {});
+        case 'http':
+            return new HttpWatcher(config);
+        case 'filesystem':
+            return new FilesystemWatcher(config);
+        default: {
+            const _exhaustive = config.type;
+            throw new Error(`Unknown watcher type: ${String(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/watchers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watchers/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAEzC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,YAAY,CAAC;QAClB,KAAK,WAAW,CAAC;QACjB,KAAK,gBAAgB;YACnB,OAAO,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QACvC,KAAK,MAAM;YACT,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;QAChC,KAAK,YAAY;YACf,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACtC,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,MAAM,CAAC,IAAI,CAAA;YACtC,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;QACjE,CAAC;IACH,CAAC;AACH,CAAC"}

package/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+Reference demons you can copy, fill in, and run.
+
+| Example | Description |
+|---|---|
+| [codebase-guardian](./codebase-guardian.yaml) | Watches a repo's PRs and CI, flags coverage drops, large diffs, and obvious bugs before they merge |
+| [competitor-watch](./competitor-watch.yaml) | Monitors competitor pages for pricing changes, new features, and announcements |
+| [founder-sentinel](./founder-sentinel.yaml) | Watches all your active projects and surfaces stale PRs, broken builds, and degraded health — only when something actually warrants it ([guide](./founder-sentinel.md)) |

package/examples/codebase-guardian.yaml

@@ -0,0 +1,22 @@
+name: codebase-guardian
+purpose: |
+  Keep this codebase healthy. Watch for PRs that drop test coverage,
+  introduce obvious bugs, or are too large to review properly. Flag
+  issues proactively before they merge. Track patterns over time.
+watch:
+  - type: github_prs
+    repo: OWNER/REPO
+  - type: github_ci
+    repo: OWNER/REPO
+interval: 15m
+action_mode: dry_run
+actions:
+  - provider: github
+    action: post_comment
+    on: pr
+  - provider: slack
+    action: send_message
+    channel: "#engineering"
+  - provider: log
+    action: info
+model: claude-sonnet-4-6

package/examples/competitor-watch.yaml

@@ -0,0 +1,18 @@
+name: competitor-watch
+purpose: |
+  Monitor competitor websites for meaningful changes — new features,
+  pricing changes, product announcements. Surface only what matters.
+watch:
+  - type: http
+    url: https://competitor.com/pricing
+  - type: http
+    url: https://competitor.com/changelog
+interval: 1h
+action_mode: dry_run
+actions:
+  - provider: slack
+    action: send_message
+    channel: "#competitive-intel"
+  - provider: log
+    action: info
+model: claude-sonnet-4-6

package/examples/founder-sentinel.md

@@ -0,0 +1,126 @@
+# founder-sentinel
+
+A demon that watches all your active projects simultaneously and surfaces only what actually needs your attention — stale PRs, broken builds, degraded health endpoints, blocked work. It stays quiet when things are fine.
+
+---
+
+## What it does
+
+You run multiple projects. Checking each one manually means either constant context switching or things slipping through. founder-sentinel runs on a 30-minute cycle, looks across all of them, and decides what matters right now.
+
+It does not alert on every CI run or every commit. It flags things that have crossed a threshold: a PR open for 48+ hours with no review, a health endpoint that just started returning errors, a build that's been red across three consecutive runs. The judgment about what matters lives in the model, not in a ruleset you had to write upfront.
+
+Over time, as it accumulates memory across runs, it gets better at knowing what's noise for your specific projects and what actually needs you.
+
+---
+
+## Setup
+
+**1. Copy the YAML and fill in your repos and URLs**
+
+```yaml
+watch:
+  - type: github_prs
+    repo: yourname/frontend-app
+  - type: github_ci
+    repo: yourname/frontend-app
+  - type: http
+    url: https://yourapp.com/health
+  - type: github_prs
+    repo: yourname/api-service
+```
+
+Add as many `watch` entries as you have active projects. Each `type: http` entry should point to a health or status endpoint that returns a non-200 when something is wrong.
+
+**2. Configure notifications**
+
+The `notify` provider sends a system notification (macOS/Linux). If you want Slack instead, swap it:
+
+```yaml
+actions:
+  - provider: slack
+    action: send_message
+    channel: "#founder-alerts"
+  - provider: log
+    action: info
+```
+
+Keep `provider: log` as a secondary action — it gives you a local audit trail.
+
+**3. Start in dry_run**
+
+Leave `action_mode: dry_run` for the first week. In this mode the demon runs its full analysis every 30 minutes but only logs what it would have done. Nothing gets sent. You can review the log to see whether its judgment matches yours.
+
+**4. When you're confident, switch to auto**
+
+```yaml
+action_mode: auto
+```
+
+That's it. From here it acts on its own judgments.
+
+---
+
+## The first week
+
+Run it in `dry_run` and check the log once a day. Look for two failure modes:
+
+**Too noisy** — it's flagging things you don't care about. Tighten your `watch` list, or add context to the `purpose` field to tell it what *not* to flag. Example:
+
+```yaml
+purpose: |
+  Watch all active projects for things that genuinely need attention.
+  Flag stale PRs, blocked work, degraded health, and important changes —
+  but only when something actually warrants it. Learn what matters over time.
+  Surface the right thing at the right moment, not noise.
+  
+  Do not flag PRs that are marked as draft. Do not flag CI failures
+  on feature branches — only flag main/master.
+```
+
+**Missing things** — it let something slip that you wish it had caught. Add that class of watch to your `watch` list, or describe the pattern in `purpose` so the model knows to look for it.
+
+After a week of the log matching your judgment, switch to `auto`.
+
+---
+
+## Example notifications
+
+What you will actually receive once it's running:
+
+> **[frontend-app]** PR #47 "Refactor auth flow" has been open 3 days with no review activity. Last CI run passed. Tagging for your attention.
+
+> **[api-service]** Build has failed on main for the past 4 runs (2h 15m). Last green commit: a3f92c1. Three commits since then, all from the same author.
+
+> **[yourapp.com/health]** Health endpoint returned 503 twice in the last two cycles. Previous 48 hours were clean. May be worth checking.
+
+> **[frontend-app]** PR #51 merged while CI was red. Build is now fixed but this pattern has happened twice this week.
+
+Notifications are batched per cycle. If nothing warrants attention in a given 30-minute window, nothing is sent.
+
+---
+
+## How it gets smarter over time
+
+Each run, the demon writes a summary of what it observed and what it flagged to its memory store. On subsequent runs, it has context about:
+
+- Which repos tend to have noisy CI that you don't care about
+- Which PRs have been intentionally parked (it stops re-flagging them)
+- What your normal baseline looks like for each health endpoint (so it can detect deviation, not just failure)
+- Patterns across projects — e.g., if deploys on one service consistently break the health check on another
+
+You do not configure any of this. It accumulates from observation. The longer it runs, the more it knows about your specific situation.
+
+---
+
+## Adjusting the interval
+
+30 minutes is a reasonable default for a founder context — frequent enough to catch things before they compound, infrequent enough not to burn API budget on noise.
+
+If your projects are high-velocity (multiple deploys per day), drop it to `15m`. If you're in a slower phase, `1h` is fine.
+
+```yaml
+interval: 15m  # high-velocity sprint
+interval: 30m  # default
+interval: 1h   # maintenance mode
+```

package/examples/founder-sentinel.yaml

@@ -0,0 +1,27 @@
+name: founder-sentinel
+purpose: |
+  Watch all active projects for things that genuinely need attention.
+  Flag stale PRs, blocked work, degraded health, and important changes —
+  but only when something actually warrants it. Learn what matters over time.
+  Surface the right thing at the right moment, not noise.
+
+watch:
+  - type: github_prs
+    repo: OWNER/REPO1
+  - type: github_ci
+    repo: OWNER/REPO1
+  - type: http
+    url: https://YOUR-APP.com/health
+  - type: github_prs
+    repo: OWNER/REPO2
+
+interval: 30m
+action_mode: dry_run
+
+actions:
+  - provider: notify
+    action: send
+  - provider: log
+    action: info
+
+model: claude-sonnet-4-6

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@josharsh/demon-cli",
+  "version": "0.1.0",
+  "description": "AI-native daemon runtime — run persistent demons (the CLI host for @josharsh/demon)",
+  "keywords": ["ai", "agent", "daemon", "llm", "automation", "demon"],
+  "author": "Harsh <engineering@spotlyte.live>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/josharsh/demon"
+  },
+  "homepage": "https://demon.josharsh.com",
+  "bugs": {
+    "url": "https://github.com/josharsh/demon/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "workspaces": ["packages/*"],
+  "files": ["dist", "README.md", "examples", "LICENSE"],
+  "type": "module",
+  "bin": { "demon": "./dist/index.js" },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "build:core": "npm run build -w @josharsh/demon",
+    "build:site": "npm run build -w @josharsh/demon && cp -R packages/core/dist/. site/core/",
+    "serve:site": "python3 -m http.server 8765 --directory site",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:core": "npm run test -w @josharsh/demon",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@josharsh/demon": "^0.1.0",
+    "@octokit/rest": "^21.0.0",
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^10.0.0",
+    "js-yaml": "^4.1.0",
+    "ms": "^2.1.3",
+    "ora": "^8.0.0",
+    "pretty-ms": "^9.0.0",
+    "winston": "^3.14.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.7",
+    "@types/js-yaml": "^4.0.9",
+    "@types/ms": "^0.7.34",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}