Package Management

Manage package.json lifecycle inside an exec container: read, initialize, install, compare, update, and pin dependencies. These endpoints operate on the project root inside the container’s working directory and are most useful for CI flows, dependency audits, and reproducible builds.

Read Package Json

Retrieve the current package.json and a summary of its dependencies, dev dependencies, and scripts.

GET /api/v1/exec/package/read

This endpoint takes no parameters.

curl -X GET "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/read" \
  -H "Authorization: Bearer <token>"

await client.exec.package.readJson();

{
  "path": "/app/package.json",
  "content": {
    "name": "hoody-exec-project",
    "version": "1.0.0",
    "description": "Hoody Exec project"
  },
  "dependencies": {
    "express": "^4.19.2",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "typescript": "^5.5.4"
  },
  "scripts": {
    "start": "bun src/index.ts"
  },
  "dependencyCount": 2,
  "devDependencyCount": 1
}

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

{
  "error": "package.json not found in project root",
  "code": "NOT_FOUND",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

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

Init Package Json

Create a new package.json in the project root. Returns 409 if one already exists, unless force is set to true.

POST /api/v1/exec/package/init

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
`name`	string	No	`"hoody-exec-project"`	Package name
`version`	string	No	`"1.0.0"`	Package version
`description`	string	No	`"Hoody Exec project"`	Package description
`force`	boolean	No	`false`	Overwrite an existing `package.json`

curl -X POST "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/init" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-exec-project",
    "version": "0.1.0",
    "description": "My exec project",
    "force": false
  }'

await client.exec.package.initJson({
  name: "my-exec-project",
  version: "0.1.0",
  description: "My exec project",
  force: false
});

{
  "message": "package.json created successfully",
  "path": "/app/package.json",
  "content": {
    "name": "my-exec-project",
    "version": "0.1.0",
    "description": "My exec project",
    "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"
    },
    "dependencies": {}
  },
  "created": true
}

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

{
  "error": "package.json already exists",
  "code": "CONFLICT",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

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

Update Package Json

Apply incremental updates to package.json: add or change dependencies, replace scripts, set metadata, or remove specific keys. The endpoint returns the list of changes that were applied.

POST /api/v1/exec/package/update

This endpoint takes no parameters.

Request Body

Field	Type	Required	Description
`dependencies`	string	No	JSON string of dependencies to merge into the `dependencies` block
`scripts`	string	No	JSON string of scripts to merge into the `scripts` block
`metadata`	object	No	Top-level metadata fields to set (e.g. `author`, `license`)
`remove`	string	No	Dot-notation path of a key to remove from `package.json`

curl -X POST "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/update" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dependencies": "{\"lodash\":\"^4.17.21\"}",
    "scripts": "{\"lint\":\"eslint .\"}",
    "metadata": {"author": "Hoody", "license": "MIT"},
    "remove": "devDependencies.typescript"
  }'

await client.exec.package.updateJson({
  dependencies: "{\"lodash\":\"^4.17.21\"}",
  scripts: "{\"lint\":\"eslint .\"}",
  metadata: { author: "Hoody", license: "MIT" },
  remove: "devDependencies.typescript"
});

{
  "message": "package.json updated successfully",
  "changes": [
    "added dependency: lodash@^4.17.21",
    "added script: lint",
    "set metadata.author",
    "set metadata.license",
    "removed devDependencies.typescript"
  ],
  "changeCount": 5,
  "dependencies": {
    "express": "^4.19.2",
    "lodash": "^4.17.21",
    "zod": "^3.23.8"
  }
}

{
  "error": "Invalid JSON in dependencies field",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {
    "field": "dependencies"
  }
}

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

{
  "error": "package.json not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

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

Install Packages

Install npm packages into the project. When called with no body, installs all declared dependencies. Returns 202 because installation runs asynchronously.

POST /api/v1/exec/package/install

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
`packages`	array	No	—	Specific packages to install (e.g. `["lodash", "zod"]`). If omitted, all declared dependencies are installed.
`dev`	boolean	No	`false`	Add the packages to `devDependencies` instead of `dependencies`
`save`	boolean	No	`true`	Write the installed packages to `package.json`
`force`	boolean	No	`false`	Force reinstall even if a lockfile is present

curl -X POST "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/install" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "packages": ["lodash", "zod"],
    "dev": false,
    "save": true,
    "force": false
  }'

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

{
  "status": "installing",
  "command": "npm install lodash zod",
  "message": "Installation started in the background"
}

{
  "error": "Invalid package list",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {
    "field": "packages"
  }
}

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

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

Compare Packages

Compare the dependencies and devDependencies declared in package.json against the packages actually installed in node_modules. Returns a summary plus lists of missing, outdated, and extra packages.

POST /api/v1/exec/package/compare

This endpoint takes no parameters.

Request Body

This endpoint accepts an optional request body with no defined fields.

curl -X POST "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/compare" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

await client.exec.package.compare({});

{
  "summary": {
    "total": 4,
    "installed": 2,
    "missing": 1,
    "outdated": 1,
    "extra": 0
  },
  "missing": ["zod"],
  "outdated": [
    {
      "package": "express",
      "declared": "^4.19.2",
      "installed": "4.18.2"
    }
  ],
  "extra": [],
  "allInstalled": false,
  "upToDate": false
}

{
  "error": "Invalid request payload",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

{
  "error": "package.json not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

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

Pin Versions

Rewrite ranges and tags in package.json to exact installed versions for reproducible builds. If every dependency is already pinned, the response reports no changes.

POST /api/v1/exec/package/pin

This endpoint takes no parameters.

Request Body

Field	Type	Required	Description
`packages`	array	No	Specific packages to pin. If omitted, all declared dependencies are pinned.

curl -X POST "https://proj-abc123-cont-xyz789-exec-1.us-east-1.containers.hoody.icu/api/v1/exec/package/pin" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "packages": ["express", "zod"]
  }'

await client.exec.package.pinVersions({
  packages: ["express", "zod"]
});

{
  "message": "Dependencies pinned to exact versions",
  "pinned": ["express", "zod"],
  "count": 2,
  "dependencies": {
    "express": "4.19.2",
    "zod": "3.23.8"
  }
}

{
  "error": "Invalid package list",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {
    "field": "packages"
  }
}

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

{
  "error": "package.json not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {}
}

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

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