daimon 0.4.2

package/LICENSE

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Yosi Azulay (FlyCoTech) (https://flycotech.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,196 @@
+# Daimon
+
+A local manager for Angular / Nx / Vite / Storybook dev servers. One daemon owns all your `serve` processes, auto-assigns ports, dedup'd error captures, exposes a loopback HTTP API + JSON CLI + MCP server. Built so you and Claude Code can both query app state without parsing thousands of log lines.
+
+Loopback only. Single user. No cloud. No telemetry.
+
+## Install
+
+```bash
+npm i -g daimon
+```
+
+After install, `daimon` is on your PATH globally.
+
+## Quick start
+
+```bash
+daimon init             # interactive scaffolder; writes ./daimon.config.json or ~/.daimon/config.json
+daimon list             # auto-spawns the daemon on first call
+daimon daemon status
+```
+
+Config lookup order:
+
+1. `./daimon.config.json` (cwd)
+2. `~/.daimon/config.json`
+
+If neither exists, the first call to `daimon` creates a stub and exits — edit `searchRoots` to point at your workspace and try again.
+
+## Config (minimal)
+
+```jsonc
+{
+  "searchRoots": ["D:\\code\\my-nx-workspace"],
+  "portRange": [4200, 4299],
+  "apiPort": 4999,
+
+  "autoStart": ["web-admin"],
+  "profiles": { "fullstack": ["web-admin", "api"] },
+  "depends": { "web-admin": ["api"] },
+
+  "healthProbe": { "enabled": true, "intervalMs": 30000, "path": "/" },
+
+  "overrides": {
+    "web-admin": {
+      "port": 4250,
+      "command": "npx nx serve web-admin --configuration=dev",
+      "env": { "API_BASE": "http://localhost:3000" }
+    }
+  }
+}
+```
+
+All sections except `searchRoots` are optional with safe defaults. See `daimon.config.example.json` for every field.
+
+## Daemon lifecycle
+
+```bash
+daimon daemon start [--detach] [--headless]   # foreground TUI by default
+daimon daemon status                          # { running, pid, port, uptime, version }
+daimon daemon stop
+daimon daemon restart                          # state-handoff: serving apps come back on the same ports
+daimon daemon attach                           # HTTP-client TUI against a running detached daemon
+daimon daemon install-service                  # emits service unit for Windows (nssm) / macOS (launchd) / Linux (systemd)
+```
+
+The daemon auto-spawns on the first `daimon` call that needs it. To suppress: `DAIMON_NO_SPAWN=1` or `--no-spawn`. To target a non-default daemon: `DAIMON_PORT=5000`.
+
+## CLI
+
+```bash
+daimon list [--tag <name>] [--workspace <label>]
+daimon status <name>
+daimon errors <name> [--since 2m] [--since-last] [--client <id>] [--structured]
+daimon events [--since 1h] [--app <name>]
+daimon wait <name> [--until serving|healthy|stopped|error] [--timeout 60s]
+daimon logs <name> [--tail N] [--since 30s]
+daimon start <name> [--with-deps]
+daimon stop <name>
+daimon restart <name>
+daimon up [<profile>]              # topological start; waits for each level to reach healthy
+daimon down [<profile>]
+daimon history <name>              # uptime%, restart count, compile p50/p95, top errors
+daimon why <name>                  # last transition + 5 preceding events (great for "what just broke")
+daimon tasks <name>                # discovered non-serve tasks
+daimon run <name> <task> [--watch] [-- args...]
+daimon snapshot <name>             # bundle state for bug reports
+daimon env <name> [--use <file>]   # env-file switcher
+daimon clean <name> [--deep] [--yes]
+daimon record / replay
+daimon doctor                      # config sanity checks; does not need the daemon
+daimon free-port <port> [--force]
+daimon init                        # interactive config scaffolder
+```
+
+All CLI commands print compact JSON on stdout. Errors are compact JSON on stderr with non-zero exit. Exit codes: `0` success, `1` generic error, `2` timeout (used by `daimon wait`).
+
+## HTTP API
+
+Bound to `127.0.0.1:<apiPort>` only. The dashboard at `/` lets you inspect state, restart apps, expand error drawers, and (in v0.4) edit configuration.
+
+```
+GET  /api/apps
+GET  /api/apps/:name
+GET  /api/apps/:name/errors[?since=2m]
+GET  /api/apps/:name/errors/since-last?client=<id>
+GET  /api/apps/:name/logs?tail=N&since=30s
+GET  /api/apps/:name/logs/stream         # Server-Sent Events
+GET  /api/apps/:name/wait?until=serving&timeout=60
+GET  /api/events?since=5m&app=<name>
+GET  /api/history/{events,compile-times,tasks,summary/:name,why/:name}
+GET  /api/config                          # current config (env redacted)
+POST /api/apps/:name/(start|stop|restart|snapshot|clean|run/:task)
+PATCH /api/config                         # If-Match: <etag>; 412 on conflict
+POST /api/config/reload                   # soft reload — no running children killed
+POST /api/shutdown
+```
+
+If `config.apiToken` is set, mutating endpoints require `Authorization: Bearer <token>`. Read endpoints stay open.
+
+## Claude Code integration
+
+```bash
+daimon claude install --all
+# or pick: --skill, --commands, --agent
+# or interactive: daimon claude install
+```
+
+Three selectable artifacts:
+
+- **Skill** at `~/.claude/skills/daimon/SKILL.md` — comprehensive how-to and recipes.
+- **Slash commands** at `~/.claude/commands/daimon-{status,start,stop,restart,errors,logs,up,doctor,why,wait}.md`.
+- **Subagent** at `~/.claude/agents/daimon-runner.md` — specialized dev-loop orchestrator.
+
+Templates are rendered from a single source of truth (`src/cliSurface.ts`), so they cannot drift from the actual command surface.
+
+Daimon stamps the current version into the artifact frontmatter. When you upgrade daimon, the next CLI call nudges you (once per 24h) to run `daimon claude update`. Silence with `DAIMON_NO_CLAUDE_NUDGE=1`.
+
+```bash
+daimon claude status        # what's installed and at which version
+daimon claude update        # refresh based on the install manifest
+daimon claude uninstall [--all|--skill|--commands|--agent]
+```
+
+For raw MCP use (without slash commands or a subagent):
+
+```bash
+claude mcp add daimon -- daimon mcp
+```
+
+The MCP server exposes: `list_apps`, `get_status`, `get_errors`, `get_logs`, `start_app`, `stop_app`, `restart_app`, `wait_for_app`.
+
+## State files (in `~/.daimon/`)
+
+- `config.json` — your config (above)
+- `daemon.lock` — `{ pid, apiPort, version, startedAt, headless }`
+- `state.json` — sticky port assignments
+- `cursors.json` — per-client error cursors for `--since-last`
+- `history.db` — SQLite of events, compile times, task runs
+- `logs/<name>.log[.N]` — when `logs.enabled` is true
+- `snapshots/<name>-<ts>.json` — `daimon snapshot` output
+- `notifications.log` — desktop notification audit
+- `crashes/<ts>.txt` — daemon fatal dumps
+- `audit.log` — dashboard config edits
+- `secrets.json` — `${NAME}` substitutions for `overrides.env`
+- `sessions/<ts>.jsonl` — `daimon record` output
+
+## Migrating from v0.3 (when it was `appman`)
+
+- Binary renamed: `appman` → `daimon`. `npm start` is no longer the way; use `npm i -g daimon` then `daimon daemon start`.
+- Environment variables: `APPMAN_PORT` → `DAIMON_PORT`, `APPMAN_NO_SPAWN` → `DAIMON_NO_SPAWN`, `APPMAN_TOKEN` → `DAIMON_TOKEN`, `APPMAN_NO_CLAUDE_NUDGE` → `DAIMON_NO_CLAUDE_NUDGE`.
+- Config file: `appman.config.json` → `daimon.config.json` (filename change only; schema is preserved).
+- State directory: `~/.appman/` → `~/.daimon/`. If you had v0.3 state, move it: `mv ~/.appman ~/.daimon`.
+- Claude artifacts: `~/.claude/skills/appman/`, `~/.claude/commands/appman-*.md`, `~/.claude/agents/appman-runner.md` → run `daimon claude install --all` after upgrading to write the new paths. Delete the old appman-named files manually if desired.
+
+## Migrating from v0.2 (`summary.url` semantics)
+
+The `summary.url` field returned by the API was synthetic `http://127.0.0.1:<port>` in v0.2. From v0.3 onwards it is the **resolved probe URL** — `overrides.<name>.url` overrides win, then `healthProbe.scheme`/`host`, then the URL the dev server announced (`Local: …`), then a fallback host. Field name unchanged; value is more accurate (HTTPS, IPv6, custom paths all preserved).
+
+## Tests
+
+```bash
+npm test
+```
+
+Four small `node:test` files cover dependency-graph math, bundle parsing, notifier throttling, and compile-time regression. No vitest dependency.
+
+## License
+
+**[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0)** — see `LICENSE`.
+
+- Free for personal, hobby, academic, and other noncommercial use
+- Free for charities, schools, government, and other noncommercial organizations
+- **Not licensed for commercial use** (use by or for a for-profit business)
+
+For a commercial license, contact yosi@flycotech.com.