Sundial Try the demo
# Development This page explains how to build, test and run Sundial from a checkout without touching your own install, and the rules every change follows. Read [architecture.md](/sundial/docs/architecture/) first if you have not seen the code before. ## Prerequisites - macOS 14 or newer. The sensors are native Swift, so Sundial does not run elsewhere. - Node.js 22 or newer. - [pnpm](https://pnpm.io). CI uses pnpm 10. - Xcode Command Line Tools, for `swiftc`: `xcode-select --install`. - `sqlite3`, which ships with macOS. `node bin/sundial doctor` checks all of these and prints a fix for anything missing. ## Repository layout | Path | What is there | |---|---| | `packages/` | The TypeScript core: kernel, rules, sensors, database, memory, model transport, MCP server | | `plugins/` | The dsh plugins that run it, including the web client in `plugins/sundial-theme/shell/` | | `apps/harness/` | The pinned dsh dependency and the sidecar lifecycle script | | `apps/daemon/` | Swift sidecar sources and the scripts that build `Sundial.app` | | `bin/sundial` | The CLI. Plain Node, no dependencies, runs before anything is built | | `test/` | The CLI tests and the end-to-end install script | ## Install dependencies This is a pnpm workspace with a pnpm lockfile. Never run `npm install` here. ```bash pnpm install ``` ## Build dsh loads the packages from their built `dist/` folders, not from source. Build after any change to a package that another package or a plugin imports: ```bash npx tsc -b tsconfig.json ``` A green editor typecheck is not enough. If the harness fails to boot with an error such as `does not provide an export named X`, a `dist/` folder is stale: build again. Plugins are plain JavaScript and need no build. ## Test Run the whole suite: ```bash npx vitest run ``` Run one file: ```bash npx vitest run packages/rules/src/notice-gate.test.ts ``` [../vitest.config.ts](https://github.com/Angelista-Enterprise/sundial/blob/develop/vitest.config.ts) gives every run its own empty `SUNDIAL_HOME` and `DSH_HOME` in a temporary folder, so a test cannot read or write a real install even if it forgets to stub something. ## Change the web client The web client in `plugins/sundial-theme/shell/` is plain ES modules served as files. There is no bundler. After editing a file there, reload the browser. A change on the host side (a plugin's `index.js`, `shell/server.js`, a package) needs a build if it touched a package, then a restart of the install you are running: ```bash node bin/sundial restart ``` ## Run a test install A test install uses its own data folder, LaunchAgent label and ports, so it never shares anything with your real one. Every path the CLI touches comes from these variables: | Variable | Default | Test value | |---|---|---| | `SUNDIAL_HOME` | `~/.sundial` | `~/.sundial-test` | | `SUNDIAL_LABEL` | `dev.sundial.agent` | `dev.sundial.test` | | `SUNDIAL_WEB_PORT` | `3080` | `3180` | | `SUNDIAL_PHONE_PORT` | `8767` | `8867` | | `SUNDIAL_CHROME_PORT` | `9223` | `9323` | `--no-sidecars` still builds the Swift helpers but never starts them, so no macOS permission prompt appears. Install with all of them set: ```bash SUNDIAL_HOME=$HOME/.sundial-test SUNDIAL_LABEL=dev.sundial.test SUNDIAL_WEB_PORT=3180 SUNDIAL_PHONE_PORT=8867 SUNDIAL_CHROME_PORT=9323 node bin/sundial install --no-sidecars ``` Later commands for that install need only `SUNDIAL_HOME`: the install records its label and ports in `$SUNDIAL_HOME/.sundial-install.json`, and `open`, `status`, `restart` and `uninstall` read them from there. For example, to remove it (without `--yes` it only prints what it would delete): ```bash SUNDIAL_HOME=$HOME/.sundial-test node bin/sundial uninstall --yes ``` Other install flags: `--no-launchagent` (write `start.sh` but do not register it with launchd), `--skip-build`, `--no-open`, and `--no-mcp` (do not offer to add the MCP server to Claude Code). Logs are in `$SUNDIAL_HOME/logs/`. The end-to-end script does all of this in one go: install, check the auth fence and that signals arrive, then uninstall. It uses the test values above, so it removes `~/.sundial-test` when it finishes. ```bash zsh test/e2e-install.sh ``` With `E2E_NO_LAUNCHD=1` it runs `start.sh` directly instead of through launchd, which is how CI runs it. ## Rebuild the Swift sidecars The build scripts write into `/Applications/Sundial.app` for the real install and into `$SUNDIAL_HOME/Sundial.app` for a test or `--no-app` install (`SUNDIAL_APP_PATH` overrides both). Set `SUNDIAL_HOME` when you run them, or they rebuild your real install: ```bash SUNDIAL_HOME=$HOME/.sundial-test pnpm sidecars:build ``` The helpers are ad hoc signed, so a rebuilt helper has a new identity and macOS treats it as a new app. After rebuilding the helpers of an install that uses them, grant the permissions again (see [permissions.md](/sundial/docs/permissions/)) and restart. ## Never run dsh without DSH_HOME Sundial's install keeps its own dsh folder at `$SUNDIAL_HOME/dsh`, and its start script sets `DSH_HOME` to it. Running `dsh` by hand from a checkout without `DSH_HOME` set, even `dsh --help`, re-points the module links under `~/.dsh`, which can break another dsh setup on the same Mac. Always set it first. ## Continuous integration [../.github/workflows/ci.yml](https://github.com/Angelista-Enterprise/sundial/blob/develop/.github/workflows/ci.yml) runs three jobs: - **test** (macOS): `pnpm install --frozen-lockfile`, `npx tsc -b tsconfig.json`, `npx vitest run`. - **secrets** (Linux): gitleaks over the tree and the full history. - **e2e-install** (macOS, after `test`): `E2E_NO_LAUNCHD=1 zsh test/e2e-install.sh`. Run the first and last locally before you open a pull request. ## Conventions - **Sundial is the software, Gnomon is the agent.** Name software things `sundial-*` and `SUNDIAL_*` (the app, CLI, install, data folder). Keep `gnomon_*` for the agent's own tools, voice, chat and notices. - **A new capability is a new `KernelState` field and a new rule in `RULE_MANIFEST`.** Never a module with its own mutable state. If you are about to add a module-level variable, timer or set to remember "have we done X yet", that memory belongs on `KernelState`. - **Rules are pure.** A rule takes `(state, event)` and returns `{ state, effects }`. No disk, network or timers inside a rule, and no reading the clock: use the event's timestamp. - **Side effects happen only in the effect executor** ([../packages/harness-runtime/src/runtime.ts](https://github.com/Angelista-Enterprise/sundial/blob/develop/packages/harness-runtime/src/runtime.ts)). - **Redaction happens only at ingest.** A new sensor field that can hold free text, a path, a URL or an address gets a line in [../packages/helpers/src/sanitize-at-ingest.ts](https://github.com/Angelista-Enterprise/sundial/blob/develop/packages/helpers/src/sanitize-at-ingest.ts) and a test in `sanitize-at-ingest.test.ts`. A read path never redacts again. If you reach for a redaction function in a read path, the value should already have been safe. - **Every web route goes through `registerRoute` / `guard()`** in `plugins/sundial-theme/shell/`. `guard.test.js` fails otherwise. An in-process caller adds `internalHeaders()`. - **Nothing binds beyond loopback.** Remote access goes through Tailscale Serve. - **Embeddings stay local.** Do not add a remote embedding path. - **Capture that costs privacy ships off by default**, behind a `config.json` switch, fully built. - **Laziest change that works.** The fewest lines and files. No new dependency unless there is no other way. - **Every fix comes with a test** that fails without it. ## Commit messages Use the conventional style the history already follows: ``` type(scope): what is true after this change ``` - `type` is one of `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`. - `scope` is the area touched, such as `install`, `sidecars`, `shell`, `llm`, `config`, `security` or `build`. It is optional. - The summary is lowercase, in plain words, and says what the change makes true, for example `fix(install): a restart restarts the sensor helpers`. ## Pull requests One change per pull request, with a test when behaviour changes. Say what you ran. Report security problems privately as described in `SECURITY.md`, not in the issue tracker.