# DesignX

AI-powered product design pipeline — from brief to working app.

DesignX is a local-first design tool that runs entirely on your machine. It uses your GitHub Copilot subscription to guide you through a structured design process: research, personas, journey maps, feature trees, data models, and generated code — all in one place.

## Requirements

- Node.js 18 or later
- An active [GitHub Copilot](https://github.com/features/copilot) subscription

## Getting started

```bash
npx @studioindia/designx
```

That's it. DesignX starts a local server on port 3000 and opens the UI in your default browser. All your data is stored in `~/DesignX/` on your own machine — nothing is sent to any external server.

On first launch, click **Connect GitHub Copilot** and follow the Device Flow prompt to authenticate with your GitHub account.

## Options

```
designx [options]

  --port <port>       Port to listen on            (default: 3000)
  --data-dir <path>   Where to store project data  (default: ~/DesignX)
  --no-open           Do not open browser automatically
  --version, -v       Print version
  --help,    -h       Print help
```

## Examples

```bash
# Default
npx @studioindia/designx

# Custom port
npx @studioindia/designx --port 8080

# Custom data directory
npx @studioindia/designx --data-dir ~/Documents/my-designx

# Headless (no browser auto-open)
npx @studioindia/designx --no-open
```

## Data directory layout

```
~/DesignX/
├── data/
│   ├── kb-jobs.json
│   └── agent-runs.json
└── projects/
    └── {project-slug}/
        ├── project.json
        ├── conversation.json
        ├── artifacts.json
        ├── session.json
        ├── uploads/        ← knowledge base files
        └── built-app/      ← exported generated code
```

## How authentication works

DesignX uses [GitHub Device Flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow) — the same flow used by the GitHub CLI. You are redirected to `github.com/login/device`, enter a short code, and authorize the app with your own GitHub account. No passwords are stored by DesignX. Your access token lives only in your local `~/DesignX/` directory.

## Updates

DesignX checks for new versions on startup. When an update is available, a banner appears in the UI with a **Relaunch to update** button — click it and DesignX restarts with the latest version automatically.

To update manually:

```bash
npx @studioindia/designx@latest
```

## Troubleshooting

### Port already in use (`EADDRINUSE`)

If you see an error like `Error: listen EADDRINUSE: address already in use 127.0.0.1:3000`, the port is already occupied by another process.

**Option 1: Use a different port**
```bash
npx @studioindia/designx --port 3001
```

**Option 2: Kill the process using port 3000**

*macOS/Linux:*
```bash
lsof -ti tcp:3000 | xargs kill -9
```

*Windows (PowerShell):*
```powershell
netstat -ano | findstr :3000
taskkill /PID <PID> /F
```
(Replace `<PID>` with the process ID from the first command)

### Command not found

If you get `command not found: designx` or `command not found: npx`, Node.js is not installed or not on your PATH.

**Install Node.js:**
- Visit [nodejs.org](https://nodejs.org) and download Node.js 18 or later
- Verify installation: `node --version` (should print v18.x.x or higher)

Then try:
```bash
npx @studioindia/designx
```

### Browser doesn't open automatically

DesignX starts a server on localhost, but the browser window may not open on some systems.

**Manual fix:** Open your browser and navigate to:
```
http://localhost:3000
```

Or run DesignX with the `--no-open` flag acknowledged, then open the URL manually:
```bash
npx @studioindia/designx --no-open
```

### Data directory permission error

If you see permission errors accessing `~/DesignX/`, ensure the directory is readable and writable:

*macOS/Linux:*
```bash
chmod -R 755 ~/DesignX
```

Or use a custom data directory with proper permissions:
```bash
npx @studioindia/designx --data-dir ~/Documents/designx-data
```

### GitHub authentication fails

- Ensure you have an active [GitHub Copilot subscription](https://github.com/features/copilot)
- On the Device Flow prompt, verify you entered the correct code at `github.com/login/device`
- Clear your local token and try again:
  ```bash
  rm ~/DesignX/data/*.json
  npx @studioindia/designx
  ```

## License

MIT
