mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00

Refresh desktop integration control plane (#123 )

* feat(dev): add desktop tools-dev control plane

* refactor(sidecar): split Open Design contracts

Move Open Design-specific sidecar protocol definitions into @open-design/contracts so sidecar and platform can remain descriptor-driven primitives.

* refactor(daemon): organize package sources

Keep daemon app code, tests, and sidecar entrypoints in separate package directories so each layer can be built and verified independently.

* chore(repo): streamline maintenance entrypoints

Centralize agent guidance by directory and reduce root command chains while preserving the existing build scope.

* docs: translate agent guidance to English

* fix(sidecar): tolerate stale IPC sockets

Remove stale Unix socket files only after confirming no listener is active, so tools-dev can restart after unclean shutdowns.

2026-04-30 14:23:53 +08:00

7 KiB

Raw Blame History

Directory guide

This file is the single source of truth for agents entering this repository. Read this file first; after entering apps/, packages/, or tools/, read that layer's AGENTS.md for module-level details. Do not copy module details back into the root file; root stays focused on cross-repository boundaries, workflow, and commands.

Core documentation index

Product and onboarding: README.md, README.zh-CN.md, QUICKSTART.md.
Contribution and environment: CONTRIBUTING.md, CONTRIBUTING.zh-CN.md.
Architecture and protocols: docs/spec.md, docs/architecture.md, docs/skills-protocol.md, docs/agent-adapters.md, docs/modes.md.
Roadmap and references: docs/roadmap.md, docs/references.md, specs/current/maintainability-roadmap.md.
Directory-level agent guidance: apps/AGENTS.md, packages/AGENTS.md, tools/AGENTS.md.

Workspace directories

Workspace packages come from pnpm-workspace.yaml: apps/*, packages/*, tools/*, and e2e.
apps/web is the Next.js 16 App Router + React 18 web runtime; do not restore apps/nextjs.
apps/daemon is the local privileged daemon and od bin. It owns /api/*, agent spawning, skills, design systems, artifacts, and static serving.
apps/desktop is the Electron shell; it discovers the web URL through sidecar IPC.
packages/contracts is the pure TypeScript web/daemon app contract layer.
packages/sidecar-proto owns the Open Design sidecar business protocol; packages/sidecar owns the generic sidecar runtime; packages/platform owns generic OS process primitives.
tools/dev is the only currently active local development lifecycle control plane.
e2e contains Playwright UI specs and Vitest/jsdom integration tests.

Inactive or placeholder directories

apps/nextjs and packages/shared have been removed; do not recreate or reference them.
apps/packaged is only a placeholder for future packaged app assembly; do not add active code there in this round.
tools/pack is only a placeholder for future tools-pack; do not add commands or packaging logic there in this round.
.od/, .tmp/, e2e/.od-data, Playwright reports, and agent scratch directories are local runtime data and must stay out of git.

Development workflow

Environment baseline

Runtime target is Node ~24 and pnpm@10.33.2; use Corepack so the pnpm version pinned in package.json is selected.
New project-owned entrypoints, modules, scripts, tests, reporters, and configs should default to TypeScript.
Residual JavaScript is limited to generated output, vendored dependencies, explicitly documented compatibility build artifacts, and the allowlist in scripts/check-residual-js.ts.

Local lifecycle

Use pnpm tools-dev as the only local development lifecycle entry point.
Do not add or restore root lifecycle aliases: pnpm dev, pnpm dev:all, pnpm daemon, pnpm preview, or pnpm start.
Ports are governed by tools-dev flags: --daemon-port and --web-port.
tools-dev exports OD_PORT for the web proxy target and OD_WEB_PORT for the web listener; do not use NEXT_PORT.

Boundary constraints

App business logic must not know about sidecar/control-plane concepts. Keep sidecar awareness in apps/<app>/sidecar or the desktop sidecar entry wrapper.
Shared web/daemon app contracts belong in packages/contracts; that package must not depend on Next.js, Express, Node filesystem/process APIs, browser APIs, SQLite, daemon internals, or the sidecar control-plane protocol.
Sidecar process stamps must have exactly five fields: app, mode, namespace, ipc, and source.
Orchestration layers (tools-dev, future tools-pack, packaged launchers) must call package primitives; do not hand-build --od-stamp-* args or process-scan regexes.
Default runtime files live under <project-root>/.tmp/<source>/<namespace>/...; POSIX IPC sockets are fixed at /tmp/open-design/ipc/<namespace>/<app>.sock.

Validation strategy

After package, workspace, or command-entry changes, run pnpm install so workspace links and generated dist entries stay fresh.
Before marking regular work ready, run at least pnpm typecheck and pnpm test; run pnpm build as well when build boundaries are involved.
For the web/e2e loop, prefer pnpm tools-dev run web --daemon-port <port> --web-port <port>.
On a GUI-capable machine, validate desktop by running pnpm tools-dev, then pnpm tools-dev inspect desktop status.
Stamp/namespace changes must validate two concurrent namespaces and run desktop inspect eval plus inspect screenshot for each namespace.
Path/log changes must run pnpm tools-dev logs --namespace <name> --json and confirm log paths are under .tmp/tools-dev/<namespace>/....

Common commands

pnpm install
pnpm tools-dev
pnpm tools-dev start web
pnpm tools-dev run web --daemon-port 17456 --web-port 17573
pnpm tools-dev status --json
pnpm tools-dev logs --json
pnpm tools-dev inspect desktop status --json
pnpm tools-dev inspect desktop screenshot --path /tmp/open-design.png
pnpm tools-dev stop
pnpm tools-dev check

pnpm typecheck
pnpm test
pnpm build
pnpm test:ui
pnpm test:ui:headed
pnpm test:e2e:live
pnpm check:residual-js

pnpm --filter @open-design/web typecheck
pnpm --filter @open-design/daemon test
pnpm --filter @open-design/desktop build
pnpm --filter @open-design/tools-dev build
pnpm -r --if-present run typecheck
pnpm -r --if-present run test

FAQ

Why is there no root `pnpm dev` / `pnpm start`?

To avoid starting daemon, web, and desktop through inconsistent env, port, namespace, or log paths. All local lifecycle flows must go through pnpm tools-dev.

Why should `apps/nextjs` not be restored?

The current web runtime is apps/web. The historical apps/nextjs layout has been removed from the active repo shape; restoring it would reintroduce duplicate app boundaries and stale scripts.

How does desktop discover the web URL?

Desktop queries runtime status through sidecar IPC. The web URL comes from tools-dev launch status, not from desktop guessing ports or reading web internals.

How are sidecar-proto, sidecar, and platform split?

@open-design/sidecar-proto owns Open Design app/mode/source constants, namespace validation, stamp fields/flags, IPC message schema, status shapes, and error semantics. @open-design/sidecar provides only generic bootstrap, IPC transport, path/runtime resolution, launch env, and JSON runtime files. @open-design/platform provides only generic OS process stamp serialization, command parsing, and process matching/search primitives, consuming the proto descriptor.

Where is data written?

The daemon writes .od/ by default: SQLite at .od/app.sqlite, agent CWDs under .od/projects/<id>/, and saved renders under .od/artifacts/. OD_DATA_DIR can relocate data relative to the repo root; Playwright uses it to isolate test data.

When is `pnpm install` required?

Run pnpm install after changing package manifests, workspace layout, command entrypoints, bin/link-related content, or after adding/removing workspace packages.

7 KiB Raw Blame History