npm package: @garthub/gart-npm
Description: Artifact-driven npm CLI for Gart skills
Author: Stepan Mozyra
Latest version: 0.1.1

# Gart NPM

> Dependencies that teach your AI how to use them.

Gart extends npm to distribute **AI usage knowledge** alongside your dependencies.

When you add a library, you usually get only code and have to figure out how to use it yourself.

Gart changes that.

It allows library authors to package **AI skills** together with their artifacts, so when a dependency is added,
its usage knowledge can be resolved and installed automatically for your AI tools.

---

## Why Gart Exists

Adding a dependency gives you code, but not understanding.

- Documentation is static and often incomplete
- Examples cover only basic scenarios
- Best practices live in people’s heads
- AI assistants guess instead of knowing

This leads to slow onboarding, inconsistent usage, and fragile integrations.

---

## What Gart Does

Gart introduces a new concept: **skills as dependencies**.

With Gart:

- libraries publish AI-readable usage knowledge
- knowledge is versioned together with the artifact
- npm projects resolve and install it automatically
- AI assistants can use it to generate correct code

Dependencies are no longer just code. They carry their own knowledge.

---

## Quick Example

Install the CLI package:

```text
npm install --save-dev @garthub/gart-npm
```

Declare skill dependencies:

```js
// gart.config.js
module.exports = {
	resolution: {
		repositories: [
			{
				type: 'maven',
				url: 'http://localhost:5151/repository/garthub/',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:payment-sdk:1.2.0'],
		},
	},
};
```

After resolution, skills are installed into:

```text
.agents/skills
```

Your AI assistant can now use them to generate correct integration code.

---

## What This Package Does

`@garthub/gart-npm` integrates Gart into an npm-based project.

It allows your project to:

- package local skills into a distributable artifact (`*-skills.zip`)
- publish skills to Maven-style repositories
- resolve skill dependencies from Maven-style repositories
- install resolved skills into `.agents/skills`
- make them available for AI tools

In short:

> npm manages your JavaScript dependencies.
>
> Gart manages your AI knowledge dependencies.

---

## Basic Project Setup

Install:

```text
npm install --save-dev @garthub/gart-npm
```

By default, Gart reads local skills from:

```text
skills/
```

You can add more directories:

```js
// gart.config.js
module.exports = {
	srcDirs: ['skills', 'extra-skills', 'generated-skills'],
};
```

Recommended scripts:

```json
{
	"scripts": {
		"gart:resolve": "gart resolve",
		"gart:clean": "gart clean",
		"gart:build": "gart build",
		"gart:publish": "gart publish"
	}
}
```

`resolve` is also triggered automatically through `postinstall` when the package is installed in a consumer project.

---

## Commands

- `gart resolve` — resolves skill dependencies
- `gart clean` — removes Gart-managed skills
- `gart build` — builds the `*-skills.zip` archive
- `gart publish` — builds and publishes the archive together with its Maven POM

---

## Configuration

Recommended precedence:

1. `gart.config.js`
2. `gart.config.cjs`
3. `gart.config.json`
4. `package.json#gart`

`gart.config.js` is the recommended format because repository credentials, environment-dependent URLs,
and future advanced rules are easier to express in JavaScript.

Basic example:

```js
module.exports = {
	srcDirs: ['skills'],
	managedSkillsDir: '.agents/skills',
	buildDir: '.gart',
	cacheDir: '.gart/cache',
	resolution: {
		repositories: [
			{type: 'mavenLocal', rootDir: 'C:/Users/me/.m2/repository'},
			{
				type: 'maven',
				url: 'http://localhost:5151/repository/garthub/',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:shared-skills:1.2.3'],
			exposedSkills: ['com.example.gart:ddd-base-skill:0.0.1'],
		},
	},
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'maven',
			url: 'http://localhost:5151/repository/garthub/',
			credentials: {
				usernameEnv: 'GART_REPO_USERNAME',
				passwordEnv: 'GART_REPO_PASSWORD',
			},
		},
	},
};
```

---

## Publishing

### Publish to a Remote Maven Repository

```js
module.exports = {
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'maven',
			url: 'https://repo.example.com/maven-releases',
			credentials: {
				usernameEnv: 'GART_REPO_USERNAME',
				passwordEnv: 'GART_REPO_PASSWORD',
			},
		},
	},
};
```

Run:

```text
npm run gart:publish
```

---

### Publish to Local Maven

```js
module.exports = {
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'mavenLocal',
			rootDir: 'C:/Users/me/.m2/repository',
		},
	},
};
```

Artifact location:

```text
~/.m2/repository/<group>/<artifact>/<version>/<artifact>-<version>-skills.zip
```

If you prefer, publishing coordinates may also be provided as:

- `publishing.groupId`
- `publishing.artifactId`
- `publishing.version`

When `artifactId` or `version` are omitted, Gart falls back to `package.json`.

---

## Resolving Skill Dependencies

```js
module.exports = {
	resolution: {
		repositories: [
			{type: 'mavenLocal', rootDir: 'C:/Users/me/.m2/repository'},
			{
				type: 'maven',
				url: 'https://repo.example.com/maven-releases',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:shared-skills:1.2.3'],
			exposedSkills: ['com.example.gart:some-base-skill:0.0.1'],
		},
	},
};
```

- `skills` — local to the current project
- `exposedSkills` — also published transitively through the generated Maven POM

Resolved skills are unpacked into:

```text
.agents/skills
```

Gart also writes a managed index file:

```text
.agents/skills/gart.json
```

The index stores resolved dependencies, extracted file paths, checksums, and cleanup metadata.

---

## Transitive Resolution

When `exposedSkills` are published, Gart generates Maven POM dependencies with:

- the same `groupId`, `artifactId`, and `version`
- classifier `skills`
- type `zip`

Consumers resolve those dependencies transitively during `gart resolve`.

At the moment, POM parsing supports explicit dependency coordinates and does not yet resolve Maven properties or
`dependencyManagement` indirection.

---

## Artifact Model

Gart uses Maven-compatible coordinates:

- `groupId` = publishing group
- `artifactId` = publishing artifact
- `version` = publishing version
- classifier = `skills`
- extension = `zip`

Example:

```text
com/example/gart/my-project/1.2.3/my-project-1.2.3-skills.zip
```

The generated POM is published alongside the archive:

```text
com/example/gart/my-project/1.2.3/my-project-1.2.3.pom
```

---

## Safety Guarantees

Gart protects your workspace:

- does not overwrite user files silently
- removes only managed files
- fails on manual modifications of managed content
- prevents duplicate resource paths
- verifies checksums before deleting managed cache entries
- records checksums in build, publish, and managed index metadata

---

## Build Boundary

Only local skill sources (`skills/`, `srcDirs`) are included in the built archive.

Resolved dependencies in `.agents/skills` are **not** repackaged automatically.

---

## Summary

Gart introduces a missing layer in modern development:

> A way to distribute knowledge together with code.

Instead of teaching developers how to use your library,
you teach their AI once, and it applies the knowledge everywhere.

---

## License

### Package

`@garthub/gart-npm` is licensed under the Apache License 2.0.

### Skills

All skills are distributed as separate artifacts and may use different licenses depending on their author.

Typical options include:

- open-source licenses
- source-available licenses
- commercial licenses

Always check the license of each skill dependency before use.