# Package Management

**Page:** api/exec/package-management

[Download Raw Markdown](./api/exec/package-management.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Package Management

The Package Management API provides programmatic access to the `package.json` lifecycle within an Exec project. Use these endpoints to read, initialize, update, compare, install, and pin dependency versions, enabling automation of dependency management without manual file editing.

---

### `GET /api/v1/exec/package/read`

Reads the current `package.json` file, returning its raw content along with parsed `dependencies`, `devDependencies`, and `scripts` blocks and their respective counts.

This endpoint takes no parameters.



```bash
curl -X GET https://api.hoody.com/api/v1/exec/package/read \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.exec.package.readJson();
```


```json
{
  "path": "/projects/hoody-exec/package.json",
  "content": {
    "name": "hoody-exec-project",
    "version": "1.0.0",
    "description": "Hoody Exec project",
    "main": "src/index.ts"
  },
  "dependencies": {
    "hono": "^4.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "bun-types": "^1.0.0"
  },
  "scripts": {
    "start": "bun src/index.ts",
    "build": "bun build src/index.ts"
  },
  "dependencyCount": 2,
  "devDependencyCount": 2
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "field": "path",
    "reason": "Invalid path format"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "resource": "package.json"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```



---

### `POST /api/v1/exec/package/init`

Initializes a new `package.json` in the current Exec project directory. By default, the file is created with sensible Hoody Exec defaults. Set `force: true` to overwrite an existing `package.json`.

This endpoint takes no parameters.

**Request Body**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | string | No | `"hoody-exec-project"` | Name of the package |
| `version` | string | No | `"1.0.0"` | Initial version string |
| `description` | string | No | `"Hoody Exec project"` | Human-readable description |
| `force` | boolean | No | `false` | Overwrite an existing `package.json` if present |



```bash
curl -X POST https://api.hoody.com/api/v1/exec/package/init \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-hoody-app",
    "version": "0.1.0",
    "description": "My Hoody Exec application",
    "force": false
  }'
```


```typescript
const result = await client.exec.package.initJson({
  name: "my-hoody-app",
  version: "0.1.0",
  description: "My Hoody Exec application",
  force: false
});
```


```json
{
  "message": "package.json created successfully",
  "path": "/projects/my-hoody-app/package.json",
  "content": {
    "name": "my-hoody-app",
    "version": "0.1.0",
    "description": "My Hoody Exec application",
    "main": "src/index.ts",
    "scripts": {
      "start": "bun src/index.ts",
      "compile:modern": "bun build --compile --external=* --outfile bin/hoody-exec src/index.ts",
      "build:openapi": "bun run src/scripts/generate-openapi-auto.ts"
    },
    "dependencies": {}
  },
  "created": true
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "field": "name",
    "reason": "Invalid package name"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "CONFLICT",
  "code": "ERROR_409",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "resource": "package.json",
    "reason": "File already exists"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CONFLICT` | Resource conflict | Operation conflicts with existing resource state | Check resource state and retry |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```



---

### `POST /api/v1/exec/package/update`

Updates an existing `package.json` by merging in new dependencies, scripts, and metadata, or by removing keys. The response lists the changes that were applied.

This endpoint takes no parameters.

**Request Body**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `dependencies` | string | No | — | JSON-encoded string of dependencies to merge into the `dependencies` block |
| `scripts` | string | No | — | JSON-encoded string of npm scripts to merge into the `scripts` block |
| `metadata` | object | No | — | Additional top-level metadata fields to merge (e.g. `author`, `license`) |
| `remove` | string | No | — | Comma-separated list of top-level keys or dependency names to remove |



```bash
curl -X POST https://api.hoody.com/api/v1/exec/package/update \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dependencies": "{\"hono\":\"^4.0.0\",\"zod\":\"^3.22.0\"}",
    "scripts": "{\"dev\":\"bun --watch src/index.ts\"}",
    "metadata": {"author": "Hoody Team", "license": "MIT"},
    "remove": "old-dep,old-dep2"
  }'
```


```typescript
const result = await client.exec.package.updateJson({
  dependencies: "{\"hono\":\"^4.0.0\",\"zod\":\"^3.22.0\"}",
  scripts: "{\"dev\":\"bun --watch src/index.ts\"}",
  metadata: { author: "Hoody Team", license: "MIT" },
  remove: "old-dep,old-dep2"
});
```


```json
{
  "message": "package.json updated successfully",
  "changes": [
    "added dependency: hono",
    "added dependency: zod",
    "added script: dev",
    "set metadata.author",
    "set metadata.license",
    "removed dependency: old-dep",
    "removed dependency: old-dep2"
  ],
  "changeCount": 7,
  "dependencies": {
    "hono": "^4.0.0",
    "zod": "^3.22.0"
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "field": "dependencies",
    "reason": "Invalid JSON string"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "resource": "package.json"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```



---

### `POST /api/v1/exec/package/compare`

Compares the dependencies declared in `package.json` against the packages actually installed in `node_modules`. The response includes a summary, lists of missing / outdated / extra packages, and aggregate boolean flags.

This endpoint takes no parameters.

**Request Body**

This endpoint accepts an optional JSON payload. No specific fields are required or documented.



```bash
curl -X POST https://api.hoody.com/api/v1/exec/package/compare \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```


```typescript
const result = await client.exec.package.compare({});
```


```json
{
  "summary": {
    "total": 4,
    "installed": 3,
    "missing": 1,
    "outdated": 1,
    "extra": 0
  },
  "missing": ["hono"],
  "outdated": [
    {
      "package": "zod",
      "declared": "^3.20.0",
      "installed": "3.19.0"
    }
  ],
  "extra": [],
  "allInstalled": false,
  "upToDate": false
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "reason": "Invalid request payload"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "resource": "package.json"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```



---

### `POST /api/v1/exec/package/install`

Queues an asynchronous install of dependencies. By default, all dependencies listed in `package.json` are installed. Pass an explicit `packages` array to install a subset, and use `dev: true` to install into `devDependencies` instead. The endpoint returns `202 Accepted` with the underlying install command.

This endpoint takes no parameters.

**Request Body**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `packages` | array | No | — | Specific package names to install; omit to install all declared dependencies |
| `dev` | boolean | No | `false` | Install the packages as `devDependencies` |
| `save` | boolean | No | `true` | Persist the installed packages to `package.json` |
| `force` | boolean | No | `false` | Force a clean reinstall, removing the existing `node_modules` first |



```bash
curl -X POST https://api.hoody.com/api/v1/exec/package/install \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "packages": ["hono", "zod"],
    "dev": false,
    "save": true,
    "force": false
  }'
```


```typescript
const result = await client.exec.package.install({
  packages: ["hono", "zod"],
  dev: false,
  save: true,
  force: false
});
```


```json
{
  "status": "installing",
  "command": "bun add hono zod",
  "message": "Install started in the background"
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "field": "packages",
    "reason": "Invalid package name"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```



---

### `POST /api/v1/exec/package/pin`

Rewrites all declared dependencies in `package.json` to their exact installed versions, removing range operators such as `^` or `~`. If `packages` is provided, only those packages are pinned; otherwise every dependency is processed.

This endpoint takes no parameters.

**Request Body**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `packages` | array | No | — | Subset of package names to pin; omit to pin every dependency |



```bash
curl -X POST https://api.hoody.com/api/v1/exec/package/pin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "packages": ["hono", "zod"]
  }'
```


```typescript
const result = await client.exec.package.pinVersions({
  packages: ["hono", "zod"]
});
```


```json
{
  "message": "Dependencies pinned to exact versions",
  "pinned": ["hono", "zod"],
  "count": 2,
  "dependencies": {
    "hono": "4.1.5",
    "zod": "3.22.2"
  }
}
```


```json
{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "field": "packages",
    "reason": "Invalid package name"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {
    "resource": "package.json"
  }
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```




When no version pinning is required, the pin endpoint returns `"All dependencies are already pinned to exact versions"` with an empty `pinned` array and `count: 0`.