npm package: @pipeline-studio/local-agent
Description: Local agent for Pipeline Studio — runs Claude CLI pipelines and syncs with cloud dashboard
Author: Felipe Moreira Lanna
Latest version: 0.1.10

# @pipeline-studio/local-agent (psa)

Local agent for Pipeline Studio. Runs Claude CLI pipelines on your machine and syncs status, logs, and events with the cloud dashboard in real time.

## Architecture

```
Browser (Dashboard)
    |  HTTP / SSE
Cloud Backend (Railway + PostgreSQL)
    |  poll commands / post events
Local Agent (psa)          <-- this package
    |  spawn + signals
Claude CLI (child process)
```

The agent polls the cloud for commands (`start`, `stop`, `pause`, `resume`), spawns Claude CLI as a child process, watches the filesystem for phase reports and human tasks, and streams everything back to the cloud via buffered event posting.

## Install

```bash
npm install -g @pipeline-studio/local-agent
```

## Usage

```bash
# 1. Connect to your cloud instance
psa connect https://your-instance.up.railway.app

# 2. Start the agent daemon
psa start

# 3. Check status
psa status

# 4. Stop the daemon
psa stop
```

## Commands

| Command | Description |
|---------|-------------|
| `psa connect <url>` | Authenticate and link this machine to a Pipeline Studio cloud instance |
| `psa start` | Start the agent daemon (background by default) |
| `psa start -f` | Start in foreground mode (useful for debugging) |
| `psa stop` | Stop the running agent daemon |
| `psa status` | Show connection status and agent health |
| `psa --version` | Show installed version |

---

## Publishing a New Version

Step-by-step guide for deploying a new version of `psa` to npm.

### Prerequisites

- Node.js >= 18
- npm account with publish access to the `@pipeline-studio` scope

### Step 1: Login to npm

If this is your first time publishing, or your session expired, authenticate first:

```bash
npm login
```

The CLI will open your browser at `https://www.npmjs.com/login`. Log in with your npm account, authorize the session, and return to the terminal. Verify it worked:

```bash
npm whoami
# should print your npm username
```

If your account has 2FA enabled, npm will ask for the OTP code during `npm publish` (step 4).

### Step 2: Make your changes

Edit source files inside `packages/local-agent/src/`. The CLI entry point is `src/cli.ts`.

### Step 3: Bump the version

Edit `packages/local-agent/package.json` and increment the `version` field following semver:

```
0.1.2 -> 0.1.3  (patch: bug fixes)
0.1.3 -> 0.2.0  (minor: new features)
0.2.0 -> 1.0.0  (major: breaking changes)
```

### Step 4: Build and publish

```bash
cd /path/to/pipeline-studio/packages/local-agent
npm publish --access public
```

The `prepublishOnly` script runs `npm run build` automatically before publishing, so you don't need to build manually.

If your npm account has 2FA enabled, you'll be prompted for an OTP code from your authenticator app.

Expected output:

```
> @pipeline-studio/local-agent@0.1.3 prepublishOnly
> npm run build

CLI Building entry: src/cli.ts
ESM Build start
ESM dist/cli.js 26.66 KB
ESM Build success in 39ms
DTS Build start
DTS Build success in 663ms
DTS dist/cli.d.ts 13.00 B

npm notice @pipeline-studio/local-agent@0.1.3
npm notice Tarball Contents
npm notice   README.md
npm notice   bin/psa.js
npm notice   dist/cli.d.ts
npm notice   dist/cli.js
npm notice   package.json
npm notice + @pipeline-studio/local-agent@0.1.3
```

### Step 5: Verify publication

```bash
npm view @pipeline-studio/local-agent version
# should print the version you just published
```

### Step 6: Update your global install

```bash
npm install -g @pipeline-studio/local-agent@latest
```

Confirm:

```bash
psa --version
# should print the new version
```

### Quick Reference (copy-paste)

```bash
cd /path/to/pipeline-studio/packages/local-agent
npm publish --access public
npm install -g @pipeline-studio/local-agent@latest
psa --version
```

---

## Project Structure

```
packages/local-agent/
  bin/
    psa.js              # Entry point (shebang, imports dist/cli.js)
  src/
    cli.ts              # Commander setup, defines commands
    commands/
      connect.ts        # psa connect — auth + link to cloud
      start.ts          # psa start — daemon + command polling
      stop.ts           # psa stop — kill daemon
      status.ts         # psa status — show health
    client/
      cloud-client.ts   # HTTP client for cloud API
    runner/
      pipeline-runner.ts # Spawn + manage Claude CLI process
  dist/                 # Build output (git-ignored)
  package.json
  tsconfig.json
  .npmignore
```

## License

MIT