npm package: @squiz/dpx-ai-tool-deployer
Description: Tool deployment utilities for DXP AI Platform
Latest version: 0.0.16

# @squiz/dpx-ai-tool-deployer

Tool deployment utilities for DXP AI Platform.

## Overview

This package provides scripts and utilities to build, prepare, and deploy AI tools in the DXP platform. It handles the complete deployment lifecycle from building tools to publishing them to the package registry.

## Installation

```bash
npm install @squiz/dpx-ai-tool-deployer
```

## CLI Commands

### `tool-prepare`

Prepares a tool for compilation by generating the handler file.

```bash
tool-prepare /path/to/tool
```

### `tool-extract-metadata`

Extracts metadata from a compiled tool including schemas and configuration.

```bash
tool-extract-metadata /path/to/tool
```

### `tool-clean`

Cleans build artifacts from a tool directory.

```bash
tool-clean /path/to/tool
```

### `tools-build-all`

Builds all tools in the tools directory.

```bash
tools-build-all
```

### `tools-create-manifest`

Creates a deployment manifest listing all tools and their build status.

```bash
tools-create-manifest
```

Output: `tools/deployment-manifest.json`

### `tools-publish`

Publishes tools to the package registry using semantic-release.

```bash
tools-publish
```

Environment variables:
- `SEMANTIC_RELEASE_DRY_RUN=true` - Run without actually publishing
- `SEMANTIC_RELEASE_NO_CI=true` - Bypass CI checks and publish from any branch

### `install-tools-from-manifest`

Installs tools from a deployment manifest into a specified directory.

```bash
install-tools-from-manifest <manifest-path> <registry-project-id> <dist-tag> <output-dir>
```

Arguments:
- `manifest-path` - Path to deployment-manifest.json
- `registry-project-id` - GitLab project ID for package registry
- `dist-tag` - Optional npm dist-tag to override manifest versions (e.g., alpha, dev)
- `output-dir` - Directory to install tools into

Environment prerequisites:
- `CI_JOB_TOKEN` (or `GITLAB_TOKEN`) for authenticating against the GitLab package registry.
- `NPM_TOKEN` with access to private `@squiz/*` packages.

The script exports `TOOLS_DIRECTORY` pointing at the installed scope directory (for example `.tools-cache/node_modules/@squiz-ai-tool`).

## Tool Structure

Each tool must have:

```
tool-name/
├── package.json          # Tool configuration
├── tool.ts              # Tool implementation
├── dist/
│   └── handler.js       # Compiled handler (generated)
└── metadata.json        # Tool metadata (generated)
```

### package.json Configuration

```json
{
  "name": "@squiz/tool-example",
  "version": "1.0.0",
  "description": "Example tool",
  "squiz": {
    "tool": {
      "id": "example-tool",
      "name": "Example Tool",
      "type": "CUSTOM",
      "permissions": ["s3:read"]
    }
  }
}
```

## Deployment Workflow

1. **Build**: `tools-build-all` compiles all tools
2. **Prepare**: `tool-prepare` generates handler files
3. **Extract**: `tool-extract-metadata` extracts schemas
4. **Manifest**: `tools-create-manifest` creates deployment manifest
5. **Publish**: `tools-publish` publishes to registry
6. **Install**: `install-tools-from-manifest` installs in target environment

## Types

### DeploymentManifest

```typescript
interface DeploymentManifest {
  tools: DeploymentTool[];
  buildInfo: {
    totalTools: number;
    readyTools: number;
    buildTime: string;
  };
}
```

### DeploymentTool

```typescript
interface DeploymentTool {
  id: string;
  packageName: string;
  version: string;
  packagePath: string;
  readyForDeployment: boolean;
}
```

**Note:** The deployment manifest contains only the minimal information needed for tool installation and publishing. Tool configuration and schemas are loaded at deployment time from each tool's `metadata.json` file:
- **From manifest**: `id`, `packageName`, `version`, `packagePath`, `readyForDeployment`
- **From metadata.json**: `name`, `description`, `type`, `permissions`, `inputSchema`, `outputSchema`, `buildTime`

## CI/CD Integration

### GitLab CI Example

```yaml
tools:build:
  script:
    - npm run tools:build-all
    - npm run tools:create-deployment-manifest
  artifacts:
    paths:
      - tools/deployment-manifest.json

tools:publish:
  script:
    - npm run tools:publish
  only:
    - main
    - develop

deploy:
  script:
    - npx @squiz/dpx-ai-tool-deployer install-tools-from-manifest \
        tools/deployment-manifest.json \
        $CI_PROJECT_ID \
        latest \
        .tools-cache
```

## License

Internal use only.