ts-plugin-kit

Framework-agnostic plugin/marketplace toolkit: typed git/npm sources, ref/sha pinning, install registry, and default-set reconciliation. Zero runtime dependencies.

It is the install mechanism shared by Agent-IX CLIs and any other host (the ix CLI, quoin, a future desktop app). It knows nothing about oclif or any particular plugin payload — a host supplies a readName callback and decides what to do with the resolved files.

Usage

import {
  reconcile,
  validateMarketplaceManifest,
} from "@agent-ix/ts-plugin-kit";

// host parses YAML/JSON itself, then validates the object
const manifest = validateMarketplaceManifest(parsedYaml);

const result = reconcile(manifest, {
  mode: "lazy", // install only what's missing/repinned; zero git when settled
  cacheRoot: "~/.cache/ix/ts-plugin-kit",
  targetRoot: "~/.ix/filament/modules", // <name>/ materialized here
  registryPath: "~/.ix/filament/registry.json",
  readName: (dir) => /* derive a name from the resolved content */ "...",
});
// result.{installed, unchanged, updated, skipped}

A manifest entry's source is one of:

| type | fetches | | ------------- | ---------------------------------------------------- | | github | owner/repo at a ref/sha | | git-subdir | one sparse-checked-out subdir of a repo at a pin | | git | any git URL at a ref/sha | | path | a local directory (dev) | | url / npm | reserved — resolution not yet implemented |

All operations are synchronous (git is the only side effect) and pins are recorded as resolved commit shas, so a settled lazy reconcile performs no git at all.

Included:

• ✅ CI via agent-ix/nodejs-actions
• 📦 Local Development via PNPM + Corepack
• 🧪 Jest for unit testing (supports coverage, JSON output)
• 💃 Prettier and ESLint for code quality
• 🏷 Tag-triggered release workflow with registry support
• 🔖 Automatic versioning based on Git tags

🚀 Getting Started

This project uses pnpm with Corepack for local development.

Prerequisites

• Node.js 20+
• Corepack enabled (corepack enable)

Setup

# Install dependencies (uses pnpm version from package.json)
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm run test

📜 Scripts

All development commands are defined in package.json scripts. Run pnpm run help or pnpm run to see the full list.

Core Development

| Command | Description | | ----------------- | --------------------------------------- | | pnpm run build | Compile TypeScript | | pnpm test | Run tests | | pnpm run lint | Run ESLint | | pnpm run format | Run Prettier | | pnpm run clean | Remove build artifacts and node_modules |

Package Management

| Command | Description | | ------------------------------ | ---------------------------------------- | | pnpm run pkg:add <pkg> | Add dependency | | pnpm run pkg:add-dev <pkg> | Add dev dependency | | pnpm run pkg:update | Update dependencies | | pnpm run pkg:use-local <pkg> | Link local package via @agent-ix/js-deps |

Publishing & Docker

| Command | Description | | ------------------------ | --------------------------------------------- | | pnpm run publish | Publish to GitHub Packages (upstream) | | pnpm run publish:local | Publish to local npm.ix registry (via Docker) | | pnpm run docker:build | Build release Docker image |

🛠 Makefile

A Makefile is provided for backwards compatibility. It delegates all commands to the equivalent pnpm run scripts.

make build          # -> pnpm run build
make test           # -> pnpm run test
make local-publish  # -> pnpm run publish:local