@agentrules/core 0.1.0 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 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 presets, use the [CLI](../cli) instead.
+**This package is for developers building custom registries or alternative clients.** If you just want to install or publish rules, use the [CLI](../cli) instead.
 
 ## Installation
 
@@ -14,9 +14,9 @@ npm install @agentrules/core
 
 | Module | Description |
 |--------|-------------|
-| **Types & Schemas** | TypeScript types and Zod schemas for presets, bundles, configs |
-| **Registry Builder** | Build registry artifacts from preset inputs |
-| **Registry Client** | Fetch and resolve presets from registries |
+| **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 |
 
@@ -24,65 +24,91 @@ This package contains **pure functions with no environment assumptions**. It doe
 
 ## Usage
 
-### Validating Preset Config
+### Validating Rule Config
 
 ```ts
-import { presetConfigSchema, validatePresetConfig } from "@agentrules/core";
+import {
+  normalizePlatformEntry,
+  ruleConfigSchema,
+  validateRule,
+} from "@agentrules/core";
 
-// Using Zod schema directly
-const result = presetConfigSchema.safeParse(jsonData);
-if (!result.success) {
-  console.error(result.error.issues);
+// 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);
+  }
 }
-
-// Or use the helper (throws on error)
-const config = validatePresetConfig(jsonData, "my-preset");
 ```
 
+Note: `description` and `tags` are optional in `agentrules.json` (they default to `""` and `[]`).
+
 ### Building Registry Artifacts
 
 ```ts
-import { buildPresetRegistry } from "@agentrules/core";
-
-const result = await buildPresetRegistry({
-  presets: [
-    {
-      slug: "my-preset",
-      config: {
-        name: "my-preset",
-        title: "My Preset",
-        version: 1,
-        description: "A helpful preset",
-        tags: ["starter"],
-        license: "MIT",
-        platforms: ["opencode", "claude"], // or use `platform: "opencode"` for single platform
-        path: "files",
-      },
-      files: [
-        { path: "AGENT_RULES.md", contents: "# Rules\n" },
-      ],
+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.entries  → Preset[] for registry listing
-// result.index    → PresetIndex for lookups
-// result.bundles  → PresetBundle[] with encoded files
+// result.rules   → ResolvedRule[] (metadata + bundle URLs)
+// result.bundles → RuleBundle[] (per-platform bundles)
 ```
 
 ### Fetching from a Registry
 
 ```ts
-import { resolvePreset, fetchBundle } from "@agentrules/core";
+import { fetchBundle, resolveSlug } from "@agentrules/core";
 
-// Resolve a preset (gets metadata and bundle URL)
-const { preset, bundleUrl } = await resolvePreset(
+// Resolve metadata + variant bundle URLs
+const resolved = await resolveSlug(
   "https://agentrules.directory/",
-  "my-preset",
-  "opencode"
+  "my-rule" // or "username/my-rule" for namespaced registries
 );
 
-// Fetch the bundle
+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);
 ```
 
@@ -119,8 +145,8 @@ console.log(PLATFORM_IDS); // ["opencode", "claude", "cursor", "codex"]
 
 // Get paths for a platform
 const opencode = PLATFORMS.opencode;
-console.log(opencode.projectDir); // ".opencode"
-console.log(opencode.globalDir);  // "~/.config/opencode"
+console.log(opencode.platformDir); // ".opencode"
+console.log(opencode.globalDir);   // "~/.config/opencode"
 ```
 
 ## Types
@@ -129,16 +155,16 @@ Key types exported:
 
 ```ts
 import type {
-  // Preset configuration (agentrules.json)
-  PresetConfig,
+  // Rule configuration (agentrules.json)
+  RuleConfig,
   
   // What clients send to publish
-  PresetPublishInput,
+  RulePublishInput,
   
   // What registries store and return
-  PresetBundle,
-  Preset,
-  PresetIndex,
+  RuleBundle,
+  Rule,
+  RuleIndex,
   
   // Bundle file structure
   BundledFile,
@@ -155,9 +181,9 @@ Zod schemas for validation:
 
 ```ts
 import {
-  presetConfigSchema,
-  presetBundleSchema,
-  presetPublishInputSchema,
+  ruleConfigSchema,
+  ruleBundleSchema,
+  rulePublishInputSchema,
   platformIdSchema,
   nameSchema,
   titleSchema,