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.

cURL

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

SDK

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

200

{
  "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
}

400

{
  "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

404

{
  "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

500

{
  "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

cURL

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
  }'

SDK

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

200

{
  "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
}

400

{
  "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

409

{
  "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

500

{
  "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

cURL

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"
  }'

SDK

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"
});

200

{
  "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"
  }
}

400

{
  "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

404

{
  "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

500

{
  "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.

cURL

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

SDK

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

200

{
  "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
}

400

{
  "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

404

{
  "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

500

{
  "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

cURL

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
  }'

SDK

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

202

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

400

{
  "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

500

{
  "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

cURL

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"]
  }'

SDK

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

200

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

400

{
  "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

404

{
  "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

500

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

Note

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.