dx-devkit 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+Notable changes to dx, newest first. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+## 1.1.0 (2026-11-03)
+
+Your AI coding agent can now run your app and see what it does, whole stacks start with one command at readable `.localhost` addresses, and nothing needs setting up. Install it with `npm install -g dx-devkit`.
+
+### Added
+
+- **Published on npm as `dx-devkit`**: one global install gives the `dx` command, the dashboard and the MCP server.
+- **Stacks**: a project's front end, API, workers and databases start together, in order, with one command or button (`dx up`, `dx go`, Run, or an AI agent's `start_dev_server`).
+  - **Found with no configuration** from:
+    - Procfiles;
+    - turbo, nx, concurrently, npm-run-all or lerna dev scripts, with their output split back into services;
+    - `dev:*` scripts;
+    - npm, yarn and pnpm workspaces;
+    - databases in docker-compose.
+  - **Order**: databases first, then back ends, then front ends. A service whose dependency failed isn't started.
+  - **Addresses passed along** as `DX_<SERVICE>_URL` and `DX_<SERVICE>_PUBLIC_URL`.
+  - **Two repositories**: `set_stack` (MCP) or `"stack"` in `.devrc.json` define a stack dx can't guess.
+- **Local domains**: running apps at `http://<project>.localhost`, stack services at `http://<service>.<project>.localhost`, and the dashboard at `http://dx.localhost`.
+  - **Nothing to set up**: browsers resolve `*.localhost` by themselves.
+  - **Live reload works**: WebSockets pass through, and redirects are rewritten.
+  - **Port**: 80, or 1355 when 80 isn't available.
+- **Dashboard**:
+  - A stack shows as one card, with a row per service (status, address, errors) and their combined output labelled by service, with a filter.
+  - Errors show which service they came from.
+- **`dx up` and `dx down`** start and stop a stack in the background.
+- **`dx doctor`** checks Docker (when a stack needs it) and whether local domains got port 80, with fixes.
+- **Project detection**: projects with only a Gemfile, a Procfile or a compose file are found too.
+- **AI agents can run your app and see what it does.** Nine new MCP tools:
+  - `start_dev_server` waits until the app is ready and reports its URL, errors and output.
+  - `wait_for_rebuild` says whether an edit added or fixed errors.
+  - `check_url` requests a page and returns what the server logged while answering.
+  - `dev_errors` and `dev_logs` read errors and output.
+  - `dev_servers`, `stop_dev_server` and `restart_dev_server` list, stop and restart servers.
+  - `dx_setup_check` gives each setup problem with its fix.
+- **Error detection in dev server output**:
+  - TypeScript, Vite, esbuild, webpack and Next.js, Node stack traces and syntax errors, Python tracebacks, Go errors and panics.
+  - Each error has its file and line and a repeat count, and is cleared once the server rebuilds cleanly.
+- **Dashboard**:
+  - Each dev server shows its errors; clicking an error's file opens your editor at that line.
+  - A "Started by AI" label marks servers an agent started.
+  - The Health page shows which AI tools are connected, with buttons, and how to fix each failed check.
+- **No setup**:
+  - On first use dx finds your code folders and editor, and connects itself to Claude Code, Claude Desktop, Cursor, Windsurf and VS Code, whichever are installed.
+  - AI tools start the dashboard in the background when they need it; it stops itself when idle.
+- **New commands**:
+  - `dx setup` (`--list`, `--undo`) manages the AI tool connections.
+  - `dx logs <project> -f` follows a server's output.
+  - `dx errors` lists current errors.
+  - `dx ui --background` and `dx ui --stop` start and stop the dashboard without a terminal.
+- **Better `dx doctor`**: each problem now comes with how to fix it.
+
+### Changed
+
+- `dx ui` opens the running dashboard instead of starting a second one.
+- On a new install, the default projects folder is the code folders dx finds, rather than `~/Desktop/projects`.
+
+## 1.0.0 (2026-11-03)
+
+The first public release, on GitHub only (its git tag is `v0.1.0`).
+
+### Added
+
+- **The dashboard, `dx ui`**: a local web interface with eight pages: Projects, New project, Ports, Journal, Summary, Cleanup, Dependencies, and Health & settings. Dev servers run inside it, with live output.
+- **The `dx` command**:
+  - `go` opens a project, starts its dev server and opens the browser.
+  - `new` creates a project from a template or a copy of another.
+  - `projects`, `port` and `kill` list projects and free ports.
+  - `log` keeps a work journal.
+  - `summary` reports your week: commits, pull requests, journal, where the time went, uncommitted work.
+  - `clean` deletes `node_modules` and build folders in idle projects.
+  - `deps` lists outdated packages and vulnerabilities across projects.
+  - `config`, `runs` and `doctor` cover settings and setup.
+- **An MCP server** with nine tools, so Claude and other AI tools can list and open projects, free ports, write and read the journal, summarise your week, and check cleanup and dependencies.
+- **A Raycast extension** with Open Project, Kill Port, Log Work and Work Journal. It's an early preview that hasn't been tested in Raycast yet.
+- **Windows, macOS and Linux support**, tested in CI with Node 22 and 24.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dx-toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,476 @@
-# Temporary Holding Version
+# dx toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your projects, dev servers, ports, work journal and weekly summary in one place: a local dashboard, a `dx` command, and tools your AI assistant can call. Runs on Windows, macOS and Linux.
+
+**Your AI coding agent can run your app and see what it does.** Claude Code, Cursor and the others start the dev server through dx, read its output, see compile errors and stack traces with their file and line, request pages, and check that a fix worked, while you watch the same server in the dashboard. dx connects itself to the AI tools on your computer: there's nothing to configure.
+
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/images/projects-light.png">
+  <img alt="The dx dashboard's Projects page: a running stack called shop, with its api and web services at api.shop.localhost and web.shop.localhost; a todo-app dev server marked Started by AI with 1 error; and the project list below." src="docs/images/projects.png">
+</picture>
+
+Each tool is written once in `packages/core` and can be used four ways:
+
+```
+packages/core   the tools (projects, ports, journal, …), plain Node, no dependencies
+   ├── packages/web      → the dashboard in your browser: `dx ui`
+   ├── packages/cli      → `dx` in any terminal, VS Code included
+   ├── packages/raycast  → Raycast commands with hotkeys
+   └── packages/mcp      → Claude (Desktop / Code) and Raycast AI can call the tools
+```
+
+Everything dx stores is in one folder: `~/.dx` (`C:\Users\<you>\.dx`).
+
+| File | What it is |
+|---|---|
+| `config.json` | Settings: where your projects are, which editor to open |
+| `journal.md` | Your work journal, plain markdown, edit it by hand any time |
+| `runs.jsonl` | One line per tool run, so a failure is never silent (`dx runs`) |
+| `summaries/` | Saved work summaries, one markdown file per day you ran `dx summary --save` |
+| `templates/` | Your project templates for `dx new`, one folder each |
+| `dashboard.json` | While the dashboard runs: its address and access token, readable by you only, so the `dx` command and AI tools can reach it |
+
+---
+
+## Setup
+
+dx runs on **Windows, macOS and Linux**. You need **Node 22 or newer** (`node -v`) and git. Then, in a terminal (PowerShell on Windows):
+
+```bash
+npm install -g dx-devkit
+```
+
+```bash
+dx ui
+```
+
+That's all. The first time you use dx it sets itself up:
+- **Your projects**: it looks in the usual code folders (`~/projects`, `~/code`, `~/dev`, `~/src`, `~/repos`, `~/Documents/GitHub`, `~/Desktop/projects` and similar) and uses the ones you have.
+- **Your editor**: the first of VS Code, Cursor, Windsurf, Zed, Sublime Text or JetBrains it finds.
+- **Your AI tools**: it adds itself to Claude Code, Claude Desktop, Cursor, Windsurf and VS Code, whichever are installed, and says so. A tool you install later is connected the next time the dashboard starts. `dx setup --undo` takes it all back.
+
+Projects somewhere else? `dx config add-root <folder>`, or add the folder on the dashboard's Health page. `dx doctor` checks everything and says how to fix what isn't right; your AI tool can run the fixes for you (ask it to "check dx's setup").
+
+- **macOS and Linux**: if `npm install -g` fails with a permissions error, your global npm folder belongs to root. Use a Node version manager (nvm, fnm, Volta) rather than `sudo`.
+- **Linux**: `dx port` and `dx kill` need `lsof` (`sudo apt install lsof` or your distro's equivalent). Copying a summary needs `wl-copy` or `xclip`, and "open in a terminal window" uses `x-terminal-emulator`.
+- **macOS**: "open in a terminal window" uses Terminal.app; the first time, macOS asks whether your terminal may control it.
+
+> If you switch Node versions with nvm, install dx again on the new version; dx repoints your AI tools at it the next time the dashboard starts.
+
+**Updating**: `npm install -g dx-devkit@latest`. **Removing**: `dx setup --undo` (takes dx out of your AI tools), then `npm uninstall -g dx-devkit`; your settings and journal stay in `~/.dx`.
+
+**From source**, to change dx itself: clone this repository, then run `npm install`, `npm run build` and `npm run link` in it. [CONTRIBUTING.md](CONTRIBUTING.md) has the rest.
+
+---
+
+## The dashboard: `dx ui`
+
+```powershell
+dx ui
+```
+
+It opens the dx dashboard in your browser, where everything `dx` does is a button:
+
+| Page | What you can do there |
+|---|---|
+| **Projects** | Search your projects; **Run** a dev server right in the page and watch its output live, open it in the browser when it's ready, **Stop** it; see its **errors** with file and line, and open your editor at that line; see servers your AI agent started; open a project in your editor, in a terminal window or in File Explorer; save one as a template |
+| **New project** | Create a project from a template or a copy of another, with git and packages installed |
+| **Ports** | See what's listening and stop it (it asks first, naming the process) |
+| **Journal** | Add what you did, read back 7, 30 or 90 days |
+| **Summary** | Your week: commits, pull requests, journal, where the time went, uncommitted work; copy it as markdown or save it |
+| **Cleanup** | See which `node_modules` and build folders can go, pick them, delete them (it asks first) |
+| **Dependencies** | Run the audit across all projects with a progress bar; open a row for its outdated packages |
+| **Health & settings** | `dx doctor`'s checks with how to fix each problem, which AI tools are connected (with Connect and Disconnect buttons), your projects folders, editor and GitHub username, and recent activity |
+
+| Summary | Cleanup |
+|---|---|
+| ![The Summary page: 11 commits in 3 projects, 4 journal entries, and the week's journal and commits.](docs/images/summary.png) | ![The Cleanup page: 168 MB of node_modules and build folders in three idle projects, selected for deletion.](docs/images/cleanup.png) |
+
+- **It runs on your computer only**, at `http://dx.localhost` (or `http://127.0.0.1:4646`). Every action needs a secret the page gets when it loads, so other websites can't use it.
+- **It's started for you when needed.** When an AI tool asks dx to run a dev server, dx starts the dashboard in the background; `dx ui` then just opens it. A background dashboard stops itself after 30 minutes with no dev servers running and nobody using it. `dx ui --stop` stops it now.
+- **Dev servers you start from the dashboard stop when the dashboard stops**, like a dev server stops when you close its terminal. For one that keeps running, use **More → Run in a terminal window**.
+- Light and dark follow your system, or pick one at the bottom of the sidebar. It works on a phone-sized window too.
+- `dx ui --port 5000` uses another port; `dx ui --no-open` doesn't open the browser. From the project folder, `npm run ui` does the same as `dx ui`.
+
+---
+
+## Stacks and local domains
+
+**A stack is everything an app needs running**: its front end, API, worker and database. dx finds it by itself, starts every part in order, and serves each one at a readable address:
+
+```bash
+dx up shop
+```
+```
+  postgres  ready    http://localhost:5432
+  api       ready    http://api.shop.localhost
+  web       ready    http://web.shop.localhost
+✓ shop is up at http://shop.localhost
+```
+
+**How dx finds a stack**, with nothing to configure:
+
+| The project has | dx runs |
+|---|---|
+| `Procfile.dev` or `Procfile` | one service per line, with `PORT` set like foreman does |
+| a root `dev` script that runs turbo, nx, concurrently, npm-run-all or lerna | that one command, as the project intends; its output is split back into services by the prefixes those tools print |
+| root scripts `dev:web`, `dev:api`, … | each one as a service |
+| npm, yarn or pnpm workspaces whose packages have a `dev` script | each package, in its own folder |
+| databases in `docker-compose.yml` (postgres, mysql, mongo, redis, …) | `docker compose up -d` for them, first; services built from your own code are left to run natively |
+| a `stack` in `.devrc.json` | exactly that: see below |
+
+- **Start order**: databases first, then back ends (`api`, `server`, `worker`, …), then front ends, each group only once the one before is ready. A service whose dependency failed isn't started, and the dashboard says so.
+- **Addresses passed along**: each service gets the others' addresses as environment variables: `DX_API_URL` (direct, for server code) and `DX_API_PUBLIC_URL` (the `.localhost` one, for the browser).
+- **One place to watch**: in the dashboard a stack is one card, with a row per service (status, address, errors) and their output combined, labelled by service, with a filter. In the terminal, `dx go shop` follows it the same way, and Ctrl+C stops it all.
+- **Two repositories**, such as `shop-web` and `shop-api`, can't be guessed safely. Ask your AI tool to "run shop-web together with shop-api": it uses the `set_stack` tool to write the stack for you. Or write it yourself (below).
+
+**Local domains**: every running app is also at `http://<project>.localhost`, and each stack service at `http://<service>.<project>.localhost`, so you don't need to remember port numbers, and ports clashing stops mattering.
+- **No setup**: browsers send every `*.localhost` name to your own computer. There's no hosts file to edit.
+- **Live reload keeps working**: WebSocket connections pass through. Redirects to `localhost:<port>` are rewritten to the `.localhost` address.
+- **Port 80, or a fallback**: dx serves these on port 80 when it can. When something else has port 80 (or on Linux, where it needs one system setting), it uses port 1355, and the addresses become `shop.localhost:1355`. `dx doctor` says which one and how to get 80; your AI tool can apply that fix for you.
+- **Safety**: it listens on your computer only, and forwards only to dev servers dx is running. Any other name gets a "not a dx address" page.
+- **Off**: set `"localDomains": false` in `~/.dx/config.json` to turn it off.
+
+---
+
+## The `dx` command
+
+| Command | What it does |
+|---|---|
+| `dx ui` | The dashboard: everything below, with buttons, in your browser |
+| `dx ui --background` / `dx ui --stop` | Start it without a terminal / stop it and the dev servers it runs |
+| `dx up shop` / `dx down shop` | Start a project's whole stack in the background, and print its addresses / stop it |
+| `dx logs todo-app -f` | Follow the output of a dev server running in the dashboard, one your AI agent started included |
+| `dx errors` | Errors in every running dev server, with file and line (`dx errors todo-app` for one) |
+| `dx setup` | Connect dx to your AI tools (it does this by itself; `--list` shows them, `--undo` removes dx from them) |
+| `dx go todo-app` | Open the project in your editor, start its dev server here (its whole stack, if it has one), open the browser when it's ready |
+| `dx go todo-app -w` | Same, but the dev server runs in a new terminal window |
+| `dx go` | Pick from your most recently active projects |
+| `dx go .` | The project in the current folder |
+| `dx new vite-app shop` | New project `shop` from a template or a copy of a project, then open it |
+| `dx projects` / `dx ls flam` | List projects (most recent first) / search them |
+| `dx port` | Every listening port 1024+, with the process and its command line |
+| `dx port 3000` | What's on port 3000 |
+| `dx kill 3000` | Kill it (asks first; `-y` skips the question) |
+| `dx log "fixed seat map overflow"` | Add a line to your work journal |
+| `dx log` / `dx log --days 30` | Read the journal back |
+| `dx summary` | Your commits across all projects plus your journal for the last 7 days, as markdown |
+| `dx summary --copy` / `--save` | Copy it to the clipboard / save it to `~/.dx/summaries/` |
+| `dx clean` | Delete `node_modules` and build folders in projects idle for 30+ days (asks first) |
+| `dx deps` | Outdated packages and known vulnerabilities in every Node project |
+| `dx runs` / `dx runs --failed` | Recent tool runs |
+| `dx config` | Show settings; `dx config edit`, `dx config add-root <folder>`, `dx config editor <cmd>`, `dx config github <user>` |
+| `dx doctor` | Check the setup |
+
+`dx help <command>` shows every option.
+
+**`dx go` details:**
+- It reads the dev command from `package.json` (`dev`, then `start`, `serve`) and uses the right package manager (npm, pnpm, yarn, bun).
+- If the port is already taken by this project's own server, it just opens the browser.
+- If the port is taken by something else, it offers to kill it.
+- Ctrl+C stops the server as usual.
+
+**`dx summary` details:**
+- It reads `git log` in every project that's a git repo (all branches, merges left out) and your journal, for the last 7 days with today included. `--days 1` is just today, for a standup.
+- Only your commits count: the ones made under the `user.name` or `user.email` git has for that repo. `--all-authors` counts everyone's.
+- Commits are listed per project, oldest first, with each message once even if you committed it several times.
+- A repo git can't read is skipped with a warning instead of failing the whole summary.
+- **Pull requests**: the ones you merged and the ones you reviewed on GitHub. Your username comes from `dx config github <user>`, or is guessed from your repos' GitHub remotes. Without a token only public repos are searched; for private ones set `GITHUB_TOKEN` (a fine-grained token with read access to pull requests), or install the GitHub CLI and run `gh auth login`. `--no-github` skips this.
+- **Where the time went**: per project, the days you committed or opened it with `dx go`, and how long its dev server ran when `dx go` ran it in the same terminal.
+- **Not committed yet**: projects active in the period with changes you haven't committed. It's a reminder for you; delete the section before sending if you like.
+
+**Every Thursday, automatically:** these save the summary at 4 pm each Thursday. Run them once, after installing dx; they find where npm put it. The file lands in `~/.dx/summaries/<date>.md`, and `dx runs` shows whether it ran.
+
+<details>
+<summary><b>Windows</b>: Task Scheduler. If the computer is off or asleep at 4 pm, it runs as soon as it's back on.</summary>
+
+```powershell
+$script   = Join-Path (npm root -g) "dx-devkit\dist\index.js"
+$action   = New-ScheduledTaskAction -Execute (Get-Command node).Source -Argument "`"$script`" summary --save"
+$trigger  = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Thursday -At 4pm
+$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable
+Register-ScheduledTask -TaskName "dx weekly summary" -Action $action -Trigger $trigger -Settings $settings
+```
+
+To remove it: `Unregister-ScheduledTask -TaskName "dx weekly summary"`.
+</details>
+
+<details>
+<summary><b>macOS</b>: a launchd agent. If the Mac is asleep at 4 pm, it runs when it wakes; if it's shut down, that week is skipped.</summary>
+
+```bash
+cat > ~/Library/LaunchAgents/dev.dx.weekly-summary.plist <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.dx.weekly-summary</string>
+  <key>ProgramArguments</key><array>
+    <string>$(command -v node)</string>
+    <string>$(npm root -g)/dx-devkit/dist/index.js</string>
+    <string>summary</string><string>--save</string>
+  </array>
+  <key>StartCalendarInterval</key><dict>
+    <key>Weekday</key><integer>4</integer>
+    <key>Hour</key><integer>16</integer>
+    <key>Minute</key><integer>0</integer>
+  </dict>
+</dict></plist>
+EOF
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.dx.weekly-summary.plist
+```
+
+To remove it: `launchctl bootout gui/$(id -u)/dev.dx.weekly-summary`, then delete the `.plist` file.
+</details>
+
+<details>
+<summary><b>Linux</b>: a systemd user timer. If the computer is off at 4 pm, it runs as soon as it's back on.</summary>
+
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/dx-summary.service <<EOF
+[Service]
+Type=oneshot
+ExecStart="$(command -v node)" "$(npm root -g)/dx-devkit/dist/index.js" summary --save
+EOF
+cat > ~/.config/systemd/user/dx-summary.timer <<EOF
+[Timer]
+OnCalendar=Thu 16:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now dx-summary.timer
+```
+
+`systemctl --user list-timers` shows when it runs next. To remove it: `systemctl --user disable --now dx-summary.timer`, then delete the two files. Without systemd, a crontab line does the same, but skips a week the computer was off: `0 16 * * 4 "$(command -v node)" "$(npm root -g)/dx-devkit/dist/index.js" summary --save` (write the two paths out in full; cron doesn't run `$(…)` for you).
+</details>
+
+**`dx clean` details:**
+- It only looks at projects you haven't touched for 30 days (`--days` changes that), and only at folders an install or a build recreates: `node_modules`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `dist`, `build`, `out`, `coverage`, `target` and similar, up to three levels down for monorepos.
+- In a git repo a folder only counts if git ignores it, so a committed `build/` folder is never touched. Outside git, `dist`, `build` and the like are left alone, since they may be the only copy.
+- It lists everything with sizes and asks before deleting. `--list` only shows, `-y` skips the question. Run `npm install` to get a project's `node_modules` back.
+
+**`dx deps` details:**
+- It runs `npm outdated` and `npm audit` in every Node project, four at a time, so it needs the internet and takes a few seconds per project. `dx deps todo-app` checks one, `--active 30` only the projects active in the last 30 days.
+- The table shows how many packages are outdated, how many of those are a major version behind (an update that may need code changes), and the vulnerabilities by severity. `--details` lists each package.
+- pnpm projects are checked with pnpm when it's installed; yarn and bun projects are skipped for now. Nothing is changed: fix with `npm update` or `npm audit fix` in the project.
+
+**`dx new` details:**
+- `dx new <source> <name>`: the source is a template in `~/.dx/templates`, or an existing project. A git project is copied as the files git tracks plus new files it doesn't ignore, so local reports, uploads and caches stay behind; `.git`, `node_modules`, build output and `.env` files are always left out (`.env.example` is kept). The new project goes in your first projects folder (`--in <folder>` to choose), gets a git repository and its packages installed, then opens like `dx go`.
+- Make a template from a project with `dx new --save todo-app vite-app`. In template files, `{{name}}` is replaced with the new project's name, in file names too; `package.json` always gets the new name.
+- `--no-install`, `--no-git`, `--no-open` and `--no-dev` skip those steps. `dx new` alone lists your templates.
+
+### Per-project settings: `.devrc.json`
+
+Optional, in a project's folder, when the detected values aren't right:
+
+```json
+{
+  "name": "shop",
+  "dev": "npm run dev -- --turbo",
+  "url": "http://localhost:3000",
+  "editor": "cursor"
+}
+```
+
+A folder containing only a `.devrc.json` also counts as a project.
+
+**A stack of your own**, for when dx can't find it by itself (two repositories, say). Each service has a command (`dev`), another project's folder (`project`, whose own dev command is used), or a docker compose service (`docker`):
+
+```json
+{
+  "stack": {
+    "web": { "dev": "npm run dev", "dependsOn": ["api"] },
+    "api": { "project": "../shop-api", "dependsOn": ["db"] },
+    "db": { "docker": "postgres" }
+  }
+}
+```
+
+`dir` runs a command in another folder, `url` says where a service listens if it doesn't print it, and `role` (`data`, `backend`, `frontend`) sets the order when there's no `dependsOn`.
+
+### Settings: `~/.dx/config.json`
+
+Created on first run, with the code folders and editor dx found:
+
+```json
+{
+  "projectsRoots": ["~/code", "~/Documents/GitHub"],
+  "editor": "cursor",
+  "scanDepth": 2,
+  "ignore": ["node_modules", "dist", "build", "out", "vendor", "target", "bin", "obj"],
+  "devServerTimeout": 90,
+  "aiToolsSeen": ["claude-code", "cursor"]
+}
+```
+
+- **`localDomains`** / **`localDomainsPort`**: `false` turns `*.localhost` addresses off; a number picks their port instead of 80 (or 1355).
+- **`aiToolsSeen`**: the AI tools dx has connected itself to once. A tool you disconnect stays disconnected. Set `"autoConnectAi": false` to stop dx connecting itself to new ones (`dx setup --undo` does both).
+
+A folder counts as a project when it has a `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `requirements.txt`, a `.sln`/`.csproj`, a `.git` folder or a `.devrc.json`.
+
+- **`scanDepth: 2`** also finds projects one folder down, e.g. `projects/archive/old-thing`. To skip a folder like that, add `"archive"` to `ignore`.
+- **Folders starting with `.`** are always skipped.
+
+---
+
+## Raycast
+
+Works from a source checkout (see Setup). Needs [Raycast for Windows](https://www.raycast.com) installed and running, and `npm run build` done first.
+
+```powershell
+npm run raycast:install
+npm run raycast:dev
+```
+
+Four commands appear in Raycast:
+- **Open Project**: open in the editor, start the dev server, open in the browser, terminal here, show in File Explorer.
+- **Kill Port**
+- **Log Work**
+- **Work Journal**
+
+To give them hotkeys, go to Raycast Settings → Extensions → DX Toolkit and assign one per command (for example Alt+P for Open Project, Alt+K for Kill Port).
+
+If the `dx` command is installed, "Start Dev Server" runs `dx go .` in the new terminal window, so you also get the port check and the browser opening.
+
+---
+
+## Claude and other AI tools (MCP)
+
+dx connects itself to **Claude Code, Claude Desktop, Cursor, Windsurf and VS Code** (Copilot's agent mode), whichever you have: see [Setup](#setup). Restart Claude Desktop once afterwards; the others pick it up in new chats.
+
+### Let your AI run your app
+
+Ask your agent to work on a project and check its own work, for example *"Start todo-app, then fix whatever error the checkout page shows."* It can:
+
+| Tool | What the agent gets |
+|---|---|
+| `start_dev_server` | Starts the project's dev server, waits until it's ready or has failed, and returns the URL, any errors and the output |
+| `wait_for_rebuild` | After it edits files: waits for the server to rebuild, then says whether the change added or fixed errors |
+| `check_url` | Requests a page or API route (localhost only) and returns the status, title and start of the body, plus anything the server logged and any error it hit while answering |
+| `dev_errors` | Current errors across running servers: TypeScript, Vite, esbuild, webpack and Next.js, Node stack traces, Python tracebacks, Go panics, with file and line. An error disappears once the server rebuilds cleanly |
+| `dev_logs` | The server's output, only what's new since it last looked |
+| `dev_servers`, `stop_dev_server`, `restart_dev_server` | What's running, and stopping or restarting it |
+| `set_stack` | Defines a stack dx can't find by itself, such as two repositories, by writing it to `.devrc.json` |
+| `dx_setup_check` | dx's health checks, each problem with the command that fixes it, so the agent can fix your setup for you |
+
+These work on stacks too: `start_dev_server` starts every service in order and reports each with its address, errors are labelled with their service, and `check_url` accepts `.localhost` addresses such as `http://api.shop.localhost/health`.
+
+The servers run in the dx dashboard, not inside the AI tool, so they keep running after the chat ends, and you can watch them, with a **Started by AI** label and their errors, in the Projects page or with `dx logs <project> -f`.
+
+### Your projects, ports, journal and week
+
+- `list_projects`, `open_project`
+- `list_ports`, `kill_port`
+- `add_log_entry`, `read_log`
+- `work_summary`: your commits, pull requests and journal for the last few days
+- `find_cleanup`: which folders `dx clean` would delete and how much space that frees (it never deletes)
+- `audit_dependencies`: outdated packages and vulnerabilities per project
+
+Then you can say things like "free port 3000 and start todo-app" or "write my standup from what I did this week".
+
+### Connecting by hand
+
+Only needed for a tool dx doesn't know, such as Raycast AI. The server is the `dx-mcp` command. For apps that don't see your PATH, run it with Node instead: `node <global folder>/dx-devkit/node_modules/@dx/mcp/dist/index.js`, where `npm root -g` prints the global folder. In JSON on Windows, double the backslashes. From a source checkout, it's `packages/mcp/dist/index.js`.
+
+For reference, this is what `dx setup` writes for Claude Desktop in `claude_desktop_config.json` (`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "dx": {
+      "command": "/usr/local/bin/node",
+      "args": ["/usr/local/lib/node_modules/dx-devkit/node_modules/@dx/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+And for Claude Code:
+
+```bash
+claude mcp add -s user dx -- node "$(npm root -g)/dx-devkit/node_modules/@dx/mcp/dist/index.js"
+```
+
+**Raycast AI**: add an MCP server in Raycast with the same command (`node`) and path.
+
+---
+
+## Adding a new tool
+
+1. **Write the logic** in `packages/core/src/tools/<tool>.ts` and export it from `packages/core/src/index.ts`.
+2. **Terminal**: add `packages/cli/src/commands/<tool>.ts` (copy `log.ts` as a template) and add it to the list in `packages/cli/src/index.ts`.
+3. **Raycast** (optional): add `packages/raycast/src/<tool>.tsx` and an entry under `commands` in `packages/raycast/package.json`.
+4. **AI** (optional): add one `server.registerTool(...)` block in `packages/mcp/src/index.ts`.
+5. **Dashboard** (optional): add a route in `packages/web/src/api.ts` (it must check the project with `scanProjects()` like the others) and a page in `packages/web/public/app.js`.
+6. **Build**: run `npm run build`, then `npm test`. Tests go in `packages/<pkg>/src/__tests__`.
+
+Call `recordRun(tool, ok, detail)` from anything that changes something, so it shows up in `dx runs`.
+
+## Tests and CI
+
+`npm test` builds everything and runs the tests in `packages/core`, `packages/web` and `packages/mcp`:
+- **core**: the tools, including error detection on real output from each tool it knows and connecting to AI tools on a pretend computer.
+- **web**:
+  - the dashboard's server: its security checks, and a real dev server started, streamed, checked for errors and stopped through it;
+  - a real two-service stack: started in order, reached through `shop.localhost` (WebSockets and redirects included), then stopped.
+- **mcp**: a real MCP client that starts an app, finds an error through a request and sees it cleared, as an agent would. On GitHub, [.github/workflows/ci.yml](.github/workflows/ci.yml) runs them on every push to `main` and every pull request, on Windows, macOS and Linux with Node 22 and 24, and tries the `dx` command itself.
+
+## Working on dx with Claude Code
+
+[CLAUDE.md](CLAUDE.md) tells Claude Code how this repo is built, its conventions and the dashboard's security rules. [docs/MEMORY.md](docs/MEMORY.md) keeps the decisions made so far and why, the gotchas, and the backlog. CLAUDE.md imports it, so both load in every session here. Update MEMORY.md when a decision is made.
+
+## Next on the list
+
+- **Raycast**: install and check the extension, and add commands for the summary and cleanup.
+- **Local HTTPS** (`https://shop.localhost`): it needs a certificate your system trusts, which means an admin prompt once, so it'll be an opt-in step your AI tool can do for you.
+- **Browser console errors** for agents: dx sees the server's output; pairing it with a browser MCP server covers what happens in the page.
+- **Tests for the CLI**: `core`, the dashboard and the MCP server are tested today.
+- **`dx deps --fix`**, and yarn and bun projects in `dx deps`.
+
+The full backlog is in [docs/MEMORY.md](docs/MEMORY.md).
+
+## Troubleshooting
+
+- **"Access is denied" when killing a process**: it belongs to another user or needs admin rights. Run the terminal as administrator.
+- **`dx` not found after `npm run link`**: open a new terminal. If it still isn't found, check that the folder `npm prefix -g` prints is on your PATH.
+- **Editor doesn't open**: run `dx doctor`, then set the editor with `dx config editor "C:\Path\To\Editor.exe"`.
+- **Debug output**: set `DX_DEBUG=1` to print full error stacks.
+
+## Releasing
+
+For maintainers:
+1. Move the CHANGELOG's *Unreleased* notes under a new version, and bump `version` in every `package.json`.
+2. Build and check the package:
+
+   ```bash
+   npm run release
+   ```
+
+   This puts it in `release/` and packs it.
+
+3. Install that package into a temporary folder and try it:
+
+   ```bash
+   node scripts/smoke-package.mjs
+   ```
+
+4. Publish, after `npm login`:
+
+   ```bash
+   npm publish ./release
+   ```
+
+5. Tag `vX.Y.Z` and draft a GitHub release from the CHANGELOG.
+
+CI runs steps 2 and 3 on every push.
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome: [CONTRIBUTING.md](CONTRIBUTING.md) has the setup and the conventions, and [CHANGELOG.md](CHANGELOG.md) what changed in each version. Please follow the [code of conduct](CODE_OF_CONDUCT.md), and report security problems privately as [SECURITY.md](SECURITY.md) explains.
+
+## License
+
+[MIT](LICENSE)

package/bin/dx-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "@dx/mcp/dist/index.js";

package/dist/command.d.ts

@@ -0,0 +1,9 @@
+/** Every dx subcommand has this shape. To add a tool: write a file in commands/ and list it in index.ts. */
+export interface Command {
+    name: string;
+    aliases?: string[];
+    summary: string;
+    usage: string;
+    run(args: string[]): Promise<number | void>;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7C"}

package/dist/command.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":""}

package/dist/commands/ai.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "../command.js";
+export declare const setupCommand: Command;
+/** Runs once, the first time dx is used, so connecting AI tools needs no setup step. */
+export declare function firstRunSetup(): Promise<void>;
+export declare const logsCommand: Command;
+export declare const errorsCommand: Command;
+//# sourceMappingURL=ai.d.ts.map

package/dist/commands/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/commands/ai.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7C,eAAO,MAAM,YAAY,EAAE,OAgD1B,CAAC;AAEF,wFAAwF;AACxF,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAYnD;AAqBD,eAAO,MAAM,WAAW,EAAE,OAiCzB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,OA2B3B,CAAC"}