Skip to content

Latest commit

 

History

History
150 lines (109 loc) · 5.8 KB

development.md

File metadata and controls

150 lines (109 loc) · 5.8 KB

Development Workflow

Prerequisites

  • Bun installed for daemon and adapter development.
  • Git checkout on dev.
  • Optional providers documented in dependencies.md.
  • Website development uses the separate site workflow.

Clone & Install

Bun runs the daemon and adapter TypeScript directly, without a runtime build step. Link their workspace packages before developing them:

bun install

The runtime workspace packages are local; bun install also resolves the root development dependencies declared in package.json. It creates adapters/<host>/node_modules/@echo/shared, which is how each adapter resolves the shared package it declares instead of reaching up the tree. Skip it and a registered adapter fails to load. scripts/install.sh runs it for you, and scripts/install.sh --check reports a missing link as stale.

Public website

Run the website tooling from site/, separately from the Bun runtime workspace. Use the Node version in site/.node-version, then:

cd site
npm ci
npm run dev

The site checks are defined in site/package.json and run in site.yml; the root bun run verify does not run them. See site/AGENTS.md for content ownership and publishing rules.

Run Dev Server

Use a non-production port so the installed LaunchAgent on :3246 is not disturbed. Redirect the config reader with the test/development-only ECHO_CONFIG_FILE path selector:

mkdir -p .scratch
printf '%s\n' '{"PORT":8889,"ECHO_DAEMON_URL":"http://localhost:8889"}' > .scratch/echo-dev-config.json
ECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" bun run core/server.ts

Pointing Clients at Dev

Silent smoke request:

curl -fsS -X POST http://localhost:8889/notify \
  -H 'Content-Type: application/json' \
  -d '{"message":"dev smoke","voice_enabled":false}'

Point Pi (or omp) at the same isolated config:

ECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" pi

Hot Reload

ECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" bun --watch run core/server.ts

If a provider subprocess hangs, stop the watch process and clear the dev port.

Auditioning edge voices

Choose per-agent edge-tts voices by ear with bun scripts/preview-voices.ts before editing core/voices.json. Commands, flags, and the workflow live in voices.md. The script calls edge-tts directly and is not on the runtime request path.

Worktrees

Use local worktrees for isolated feature or release work when you do not want to disturb the main dev checkout:

mkdir -p .worktrees
git worktree add -b fix/example .worktrees/fix-example origin/dev

.worktrees/ is intentionally gitignored. Remove finished worktrees with git worktree remove .worktrees/<name> and then git worktree prune.

Tests

After bun install, bun run verify runs the repository's validation checks. Individual check aliases are defined in package.json; other script runners follow the README usage.

bun install                  # required before bun test - adapters import @echo/shared
bun run verify

The script definitions in package.json own the individual commands, including the adapter build list. CI runs the corresponding checks headlessly on every PR into dev/master and every push to those branches; its steps live in verify.yml.

Never test against the running daemon

The installed LaunchAgent on :3246 serves the operator's real notifications. Stopping it, retargeting it, overwriting its config, or speaking through it is a live-system incident, not a test.

tests/e2e-adapters.sh is the safe path. It starts its own core/server.ts on its own port (ECHO_E2E_PORT, default 8899) with every state path - mute, capture guard, audio cache, TTS cache, lifecycle log, and VOICES_PATH - redirected through a scratch config file, while exported copies exist only for inline test assertions. It kills only the pid it started. It refuses to run if the chosen port is 3246 or if anything is already listening there: it never attaches to a daemon it does not own. Before sending anything it prints an isolation proof (pid, port, adapter target, scratch dir).

tests/e2e-adapters.sh              # silent - safe anywhere
tests/e2e-adapters.sh --audible    # also speaks, on the isolated instance only

tests/e2e-converse.sh applies the same discipline to the voice ask, with two additions of its own. It starts a second isolated process (the echo-converse coordinator, ECHO_E2E_CONVERSE_PORT, default 8922) and refuses 32468 as well as 3246. And its recorder and transcriber are stand-in scripts, so it opens no microphone and needs neither sox nor yap - which is what lets it run on CI. Silence comes from enabling only say in its own scratch voices.json and routing it to a no-op executable: an ask forces voice_enabled on by design, so --audible is the only way to hear it (and the only way to exercise real synthesis timing in the drain wait). See converse.md.

Every spoken test line begins Echo Test engaged. Beep, boop, bop. so anything audible is unmistakably a test and never mistaken for a real notification.

Teardown

lsof -nP -iTCP:8889 | awk 'NR>1 {print $2}' | xargs kill 2>/dev/null || true

Troubleshooting

  • If :8889 is busy, choose another dev port.
  • If edge-tts fails, /notify should try real synthesis before falling back unless the Edge circuit is already open; inspect attempts[] in the resolution log for phase, reason, and stderr.
  • If production voice changes, confirm you did not run scripts against :3246 unintentionally.