@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

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

CLI Commands

tool-prepare

Prepares a tool for compilation by generating the handler file.

tool-prepare /path/to/tool

tool-extract-metadata

Extracts metadata from a compiled tool including schemas and configuration.

tool-extract-metadata /path/to/tool

tool-clean

Cleans build artifacts from a tool directory.

tool-clean /path/to/tool

tools-build-all

Builds all tools in the tools directory.

tools-build-all

tools-create-manifest

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

tools-create-manifest

Output: tools/deployment-manifest.json

tools-publish

Publishes tools to the package registry using semantic-release.

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.

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

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

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

DeploymentTool

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

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.