README.md

@agentrules/core

Shared types and utilities for the AGENT_RULES ecosystem.

This package is for developers building custom registries or alternative clients. If you just want to install or publish rules, use the CLI instead.

Installation

npm install @agentrules/core

What's Included

Module	Description
Types & Schemas	TypeScript types and Zod schemas for rules, bundles, configs
Registry Builder	Build registry artifacts from rule inputs
Registry Client	Fetch and resolve rules from registries
Bundle Utilities	Encode/decode bundles, verify checksums
Platform Config	Platform IDs and directory paths

This package contains pure functions with no environment assumptions. It doesn't touch the file system or make network requests directly — that's left to the consumer (like the CLI).

Usage

Validating Rule Config

import {
  normalizePlatformEntry,
  ruleConfigSchema,
  validateRule,
} from "@agentrules/core";

// Parse/validate user-provided JSON (agentrules.json)
const parsed = ruleConfigSchema.safeParse(jsonData);
if (!parsed.success) {
  console.error(parsed.error.issues);
} else {
  // Normalize platform entries (string shorthand → object form)
  const config = {
    ...parsed.data,
    platforms: parsed.data.platforms.map(normalizePlatformEntry),
  };

  // Additional cross-field checks (platform/type compatibility, placeholders, etc.)
  const result = validateRule(config);
  if (!result.valid) {
    console.error(result.errors);
  }
}

Note: description and tags are optional in agentrules.json (they default to "" and []).

Building Registry Artifacts

import { buildRegistry, type RuleInput } from "@agentrules/core";

const rules: RuleInput[] = [
  {
    name: "my-rule",
    config: {
      name: "my-rule",
      title: "My Rule",
      description: "A helpful rule",
      license: "MIT",
      // Optional metadata
      tags: ["starter"],
      features: ["Fast install"],
      // Platforms (object form)
      platforms: [{ platform: "opencode" }, { platform: "claude" }],
    },
    platformFiles: [
      {
        platform: "opencode",
        files: [{ path: "AGENTS.md", content: "# Rules\n" }],
      },
      {
        platform: "claude",
        files: [{ path: "CLAUDE.md", content: "# Rules\n" }],
      },
    ],
  },
];

const result = await buildRegistry({ rules, bundleBase: "https://example.com" });

// result.rules   → ResolvedRule[] (metadata + bundle URLs)
// result.bundles → RuleBundle[] (per-platform bundles)

Fetching from a Registry

import { fetchBundle, resolveSlug } from "@agentrules/core";

// Resolve metadata + variant bundle URLs
const resolved = await resolveSlug(
  "https://agentrules.directory/",
  "my-rule" // or "username/my-rule" for namespaced registries
);

if (!resolved) throw new Error("Rule not found");

// Pick a variant bundle URL (example: first variant of latest version)
const bundleUrl = resolved.versions[0].variants[0].bundleUrl;

// Fetch the per-platform bundle
const bundle = await fetchBundle(bundleUrl);

Working with Bundles

import {
  decodeBundledFile,
  verifyBundledFileChecksum,
  isLikelyText,
} from "@agentrules/core";

for (const file of bundle.files) {
  // Decode base64 contents
  const data = decodeBundledFile(file);
  
  // Verify integrity
  await verifyBundledFileChecksum(file, data);
  
  // Check if it's text or binary
  if (isLikelyText(data)) {
    const text = new TextDecoder().decode(data);
  }
}

Types

Key types exported:

import type {
  // Rule configuration (agentrules.json)
  RuleConfig,
  
  // What clients send to publish
  RulePublishInput,
  
  // What registries store and return
  RuleBundle,
  Rule,
  RuleIndex,
  
  // Bundle file structure
  BundledFile,
  
  // Platform types
  PlatformId,
  PlatformConfig,
} from "@agentrules/core";

Schemas

Zod schemas for validation:

import {
  ruleConfigSchema,
  ruleBundleSchema,
  rulePublishInputSchema,
  platformIdSchema,
  nameSchema,
  titleSchema,
  descriptionSchema,
} from "@agentrules/core";