@viewportai/daemon 0.1.0

package/docs/protocol-matrix.json

@@ -0,0 +1,155 @@
+{
+  "version": 1,
+  "messages": [
+    {
+      "type": "launch",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#LaunchSchema",
+      "handler": "src/server/ws-command-handlers.ts#launch",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-session-lifecycle.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": true
+    },
+    {
+      "type": "kill",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#KillSchema",
+      "handler": "src/server/ws-command-handlers.ts#kill",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-session-lifecycle.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "prompt",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#PromptSchema",
+      "handler": "src/server/ws-command-handlers.ts#prompt",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-session-lifecycle.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": true
+    },
+    {
+      "type": "respond-permission",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#RespondPermissionSchema",
+      "handler": "src/server/ws-command-handlers.ts#respond-permission",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-session-lifecycle.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": true
+    },
+    {
+      "type": "subscribe",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#SubscribeSchema",
+      "handler": "src/server/ws-command-handlers.ts#subscribe",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ring-buffer.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": true
+    },
+    {
+      "type": "unsubscribe",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#UnsubscribeSchema",
+      "handler": "src/server/ws-command-handlers.ts#unsubscribe",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "rollback",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#RollbackSchema",
+      "handler": "src/server/ws-command-handlers.ts#rollback",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "branch-retry",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#BranchRetrySchema",
+      "handler": "src/server/ws-command-handlers.ts#branch-retry",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "squash-merge",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#SquashMergeSchema",
+      "handler": "src/server/ws-command-handlers.ts#squash-merge",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "list-sessions",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#ListSessionsSchema",
+      "handler": "src/server/ws-command-handlers.ts#list-sessions",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "resume",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#ResumeSchema",
+      "handler": "src/server/ws-command-handlers.ts#resume",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-session-lifecycle.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "watch-discovered-session",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#WatchDiscoveredSessionSchema",
+      "handler": "src/server/ws-command-handlers.ts#watch-discovered-session",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-discovery-hooks.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "unwatch-discovered-session",
+      "class": "stable",
+      "schema": "src/server/ws-protocol.ts#UnwatchDiscoveredSessionSchema",
+      "handler": "src/server/ws-command-handlers.ts#unwatch-discovered-session",
+      "unitTests": ["tests/server/ws-protocol.test.ts", "tests/server/ws-command-handlers.test.ts"],
+      "integrationTests": ["tests/server/ws-server.test.ts", "tests/e2e/protocol-discovery-hooks.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "supervise",
+      "class": "experimental",
+      "schema": "src/server/ws-protocol.ts#SuperviseSchema",
+      "handler": "src/server/ws-command-handlers.ts#supervise",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/e2e/protocol-discovery-hooks.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    },
+    {
+      "type": "respond-hook-permission",
+      "class": "experimental",
+      "schema": "src/server/ws-protocol.ts#RespondHookPermissionSchema",
+      "handler": "src/server/ws-command-handlers.ts#respond-hook-permission",
+      "unitTests": ["tests/server/ws-protocol.test.ts"],
+      "integrationTests": ["tests/e2e/protocol-discovery-hooks.test.ts"],
+      "surfacedInUi": true,
+      "surfacedInCli": false
+    }
+  ]
+}

package/docs/releasing.md

@@ -0,0 +1,65 @@
+# Releasing and npm Publish
+
+## Current source of truth
+
+1. npm package name: `@viewportai/daemon` (`package.json` `name`).
+2. Version source: semantic-release from commit history on `main`.
+3. Publish trigger: `.github/workflows/release.yml` after `CI` succeeds on a push to `main`.
+4. npm auth: granular `NPM_TOKEN` secret in GitHub Actions.
+
+## Version rules
+
+1. `feat:` => `minor` (for example `0.4.0` -> `0.5.0`).
+2. `fix:` => `patch` (for example `0.4.1` -> `0.4.2`).
+3. `perf:` / `refactor:` / `revert:` => `patch`.
+4. `BREAKING CHANGE:` footer or `!` in type/scope => `major`.
+5. `docs:`, `test:`, `chore:` alone => no release.
+
+## One-time setup for production publish
+
+1. Create npm organization scope `@viewportai` (or verify ownership if it already exists).
+2. Ensure repository package name remains `@viewportai/daemon`.
+3. Create a granular npm token with publish rights to `@viewportai/daemon`.
+4. Add GitHub Actions secret `NPM_TOKEN` in repo settings.
+5. Ensure branch protection on `main` requires the `CI` workflow to pass before merge.
+6. Ensure branch protection on `main` requires the `Semantic PR` workflow to pass before merge.
+7. Use squash-merge so the semantic PR title becomes the release-driving commit on `main`.
+8. Ensure npm package access is public (already configured via `publishConfig.access=public`).
+9. For this repository, enforce a pre-1.0 stream with a one-time baseline tag on the bootstrap `main` commit: `git tag v0.0.0 && git push origin v0.0.0`.
+10. Keep `package.json` publish metadata canonical for provenance:
+   - `repository.url` must be exactly `https://github.com/viewportai/daemon`
+   - `bin.vpd` must be exactly `bin/vpd.js`
+
+## Release flow
+
+1. Open PR with semantic commits.
+2. Merge to `main` after CI green.
+3. `release.yml` runs semantic-release:
+   - calculates next version,
+   - updates `CHANGELOG.md`, `package.json`, and `package-lock.json`,
+   - creates git tag,
+   - creates GitHub release,
+   - publishes package to npm.
+4. Validate via:
+   - GitHub release/tag exists (`vX.Y.Z`),
+   - npm package version appears in registry,
+   - `vpd --version` from fresh global install matches.
+
+## Local dry run
+
+Use this before rollout changes to release config:
+
+```bash
+npx -y \
+  -p semantic-release \
+  -p @semantic-release/changelog \
+  -p @semantic-release/commit-analyzer \
+  -p conventional-changelog-conventionalcommits \
+  -p @semantic-release/git \
+  -p @semantic-release/github \
+  -p @semantic-release/npm \
+  -p @semantic-release/release-notes-generator \
+  semantic-release --dry-run
+```
+
+This does not publish; it only reports what version would be released.

package/docs/security.md

@@ -0,0 +1,48 @@
+# Viewport Daemon Security Profiles
+
+## Profiles
+
+- `local`
+  - Host must be loopback.
+  - Auth optional.
+  - Intended for single-machine use.
+- `lan`
+  - Requires explicit host allowlist (`--allowed-hosts` or config/env equivalent).
+  - Auth required.
+- `relay`
+  - Requires explicit host allowlist.
+  - Auth required.
+  - Relay transport and key exchange are next-phase work.
+
+## Current controls
+
+- Host header allowlist enforcement.
+- Origin allowlist enforcement.
+- Token auth (`~/.viewport/auth-token`) for protected API/WS.
+- WS auth supports `?token=` query fallback for browser compatibility.
+  - Tradeoff: query tokens can leak via logs/history.
+  - Preferred path is `Authorization: Bearer ...`.
+- WebSocket payload limits, backpressure handling, and rate limiting.
+- Path traversal protection for file APIs.
+
+## Pairing foundations (current phase)
+
+- `vpd pair` creates short-lived offers (default 10 minutes, max 60 minutes).
+- Offer URL contains `offerId`, one-time proof, trust-anchor fingerprint, and connection metadata, not the auth token.
+- Offers are persisted and can be listed/revoked:
+  - `vpd pair list`
+  - `vpd pair revoke <offer-id>`
+- Daemon trust anchor can be inspected:
+  - `vpd pair anchor`
+- Offer redemption is one-time:
+  - `POST /api/pair/redeem` with `offerId` + `proof` + `trustAnchor`
+  - Local loopback profile can bypass bearer auth for redeem; LAN/relay profiles cannot.
+- Pairing events are written to `~/.viewport/pairing-audit.jsonl`.
+
+## Relay-phase extensions
+
+The next phase should add:
+
+- Explicit device identity binding.
+- Revocation propagation across relay sessions.
+- Short-lived capability tokens scoped by command/permission class.

package/docs/testing.md

@@ -0,0 +1,112 @@
+# Daemon Testing Guide
+
+## Layers
+
+1. Unit tests: fast behavior checks for isolated modules.
+2. Integration tests: daemon + HTTP/WS route behavior in-process.
+3. Protocol e2e tests: WS command/event lifecycle with harness.
+4. Fullstack net e2e: real CLI -> real daemon HTTP/WS over localhost.
+
+## Commands
+
+Fast confidence:
+
+```bash
+npm run check:protocol-matrix
+npm run typecheck
+npm run test -- tests/cli tests/server
+```
+
+Single-entry test command with modes:
+
+```bash
+npm run test
+npm run test --verify
+npm run test --e2e
+npm run test --fullstack
+npm run test --env
+npm run test --service
+```
+
+Protocol e2e:
+
+```bash
+npm run test:e2e
+```
+
+Fullstack CLI proof (network bind required):
+
+```bash
+npm run test:e2e:fullstack
+```
+
+Full gate:
+
+```bash
+npm run check
+```
+
+Local environment verification:
+
+```bash
+# isolated daemon lifecycle verification (temp VIEWPORT_HOME + dedicated listen target)
+npm run verify:env
+
+# includes launchd/systemd install + active status checks
+npm run verify:env:service
+
+# validates local tarball install + binary lifecycle in isolated npm prefix
+npm run verify:install
+```
+
+`verify:install` requires network access to resolve package runtime dependencies.
+
+One-command local checker:
+
+```bash
+# repo gates only
+npm run verify:repo
+
+# repo gates + env verification + service checks
+bash ./scripts/verify.sh --env --service
+
+# repo gates + fullstack net e2e + env verification + service checks
+bash ./scripts/verify.sh --fullstack --env --service
+```
+
+## CI Linux verification
+
+GitHub Actions now runs a dedicated Linux runtime verification path:
+
+```bash
+npm run verify:linux:ci
+```
+
+This validates:
+1. Tarball install verification (`verify:install`)
+2. Dev install + isolated daemon lifecycle verification (`verify:env`)
+3. systemd user-service verification when available on runner (`verify:env:service`)
+
+## What fullstack e2e proves
+
+`tests/e2e/cli-fullstack-workflow.test.ts` verifies in one workflow:
+
+1. `vpd run` launches over real WS.
+2. `vpd ls` and `vpd agent mode` hit real HTTP routes.
+3. `vpd worktree diffs/summary/retry/squash` use live daemon state.
+4. Pairing trust-anchor flow: offer + redeem success and mismatch rejection.
+5. `vpd session stop` terminates the live session.
+
+The test is opt-in via `VIEWPORT_RUN_NET_E2E=1` because it requires binding a localhost port.
+
+## Dev install flows
+
+Use local source without publishing to npm:
+
+```bash
+# tarball install flow (recommended)
+./scripts/install-dev.sh --yes --no-service --no-prereqs --no-hooks
+
+# npm link flow
+./scripts/install-dev.sh --link --yes --no-service --no-prereqs --no-hooks
+```

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@viewportai/daemon",
+  "version": "0.1.0",
+  "description": "Viewport daemon — supervision and orchestration layer for AI coding agents",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/viewportai/daemon"
+  },
+  "bugs": {
+    "url": "https://github.com/viewportai/daemon/issues"
+  },
+  "homepage": "https://github.com/viewportai/daemon#readme",
+  "bin": {
+    "vpd": "bin/vpd.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "bash ./scripts/test.sh",
+    "test:unit": "vitest run",
+    "test:verify": "npm run test -- --verify",
+    "test:setup": "vitest run tests/cli/setup-command.test.ts tests/cli/service-commands.test.ts tests/startup-prereqs.test.ts tests/core/built-in-agents.test.ts",
+    "test:e2e": "vitest run tests/e2e",
+    "test:e2e:fullstack": "VIEWPORT_RUN_NET_E2E=1 vitest run tests/e2e/cli-fullstack-workflow.test.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "check:file-size": "node ./scripts/check-file-sizes.mjs",
+    "check:protocol-matrix": "node ./scripts/check-protocol-matrix.mjs",
+    "lint": "eslint src/ tests/ --no-error-on-unmatched-pattern",
+    "format": "prettier --write \"{src,tests}/**/*.ts\"",
+    "format:check": "prettier --check \"{src,tests}/**/*.ts\"",
+    "check": "npm run check:file-size && npm run check:protocol-matrix && npm run typecheck && npm run lint && npm run format:check && npm run test",
+    "dev:install": "bash ./scripts/install-dev.sh --yes --no-service --no-prereqs --no-hooks",
+    "dev:link": "bash ./scripts/install-dev.sh --link --yes --no-service --no-prereqs --no-hooks",
+    "dev:uninstall": "bash ./scripts/uninstall.sh --service",
+    "dev:uninstall:all": "bash ./scripts/uninstall.sh --service --purge-home",
+    "dev:reinstall": "npm run dev:uninstall && npm run dev:install",
+    "verify:repo": "bash ./scripts/verify.sh",
+    "verify:linux:ci": "bash ./scripts/verify-linux-ci.sh",
+    "verify:env": "bash ./scripts/test-env.sh",
+    "verify:env:service": "bash ./scripts/test-env.sh --service",
+    "verify:install": "bash ./scripts/install-verify.sh"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.63",
+    "@fastify/cors": "^10.0.1",
+    "@fastify/websocket": "^11.0.1",
+    "@openai/codex-sdk": "^0.107.0",
+    "fastify": "^5.2.1",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^3.0.5",
+    "conventional-changelog-conventionalcommits": "^9.2.0",
+    "eslint": "^9.20.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.3",
+    "prettier": "^3.5.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1",
+    "vitest": "^3.0.5"
+  }
+}