agentwheel 0.3.0 → 0.3.1

package/README.md

@@ -102,6 +102,34 @@ A package is a git repo (or folder) with a JSON manifest and a canonical layout:
 Publish by pushing to any git host. A registry exists only for short names and discovery — it's
 optional, and `agentwheel add <url|path>` always works without it.
 
+## How to add a package
+
+The public package registry lives at
+[`NestDevLab/agentwheel-registry`](https://github.com/NestDevLab/agentwheel-registry).
+
+1. Create a public repo with `agentwheel.json` and a standard layout such as `instructions/`, `rules/`, `skills/`, `commands/`, `mcp/`, or `hooks/`.
+2. Open a pull request to `agentwheel-registry` that adds an entry to `index.json`.
+3. Users install by short name:
+
+```bash
+agentwheel registry update
+agentwheel add your-package-name --adapter openclaw
+agentwheel update --dry-run
+agentwheel update
+```
+
+Example registry entry:
+
+```json
+{
+  "name": "your-package-name",
+  "source": "github:your-org/your-agent-package",
+  "type": "package",
+  "description": "Reusable skills, rules, and instructions for agentwheel.",
+  "tags": ["skills", "rules", "instructions"]
+}
+```
+
 ## Customizing without getting overwritten
 
 Drift detection blocks *accidental* edits to generated files. *Intentional* changes have four channels,

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 
 // src/cli/index.ts
 import { mkdir as mkdir7, rm as rm8, writeFile as writeFile4 } from "fs/promises";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 import { Command } from "commander";
 
 // src/adapters/resolve.ts
@@ -1882,6 +1882,23 @@ async function packageFromSource(source, options) {
   };
 }
 
+// src/lifecycle/source-plan.ts
+import { join as join17 } from "path";
+async function createSourcePlan(options) {
+  const resolvedInput = await resolvePackageSource(options.source, options.targetRoot);
+  const resolvedSource = resolvedInput.source;
+  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedSource));
+  const bundle = await stageSource(driver, resolvedSource, {
+    workspaceRoot: options.targetRoot,
+    adapter: options.adapter,
+    cacheRoot: join17(options.targetRoot, ".agentwheel", "cache"),
+    mode: options.mode
+  });
+  const manifest = await readInstallManifest(options.targetRoot, options.adapter.name);
+  const plan = await createInstallPlan(bundle, options.adapter, options.targetRoot, manifest);
+  return { plan, bundle, resolvedSource, registryEntryName: resolvedInput.registryEntry?.name };
+}
+
 // src/lifecycle/update.ts
 function shouldUpdatePackage(pkg, lock) {
   if (!lock) {
@@ -1901,7 +1918,7 @@ function shouldUpdatePackage(pkg, lock) {
 
 // src/cli/index.ts
 var program = new Command();
-program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.2.0");
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.3.1");
 program.command("init").argument("[kind]", "workspace or package", "workspace").option("--target-root <path>", "workspace root", process.cwd()).action(async (kind, options) => {
   const root = normalizeTargetRoot(options.targetRoot);
   if (kind === "package") {
@@ -1932,7 +1949,7 @@ program.command("add").argument("<source>", "package source").option("--driver <
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join17(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join18(targetRoot, ".agentwheel", "cache"),
     mode: options.mode
   });
   const name = options.name ?? resolvedInput.registryEntry?.name ?? bundle.source.packageName ?? source;
@@ -1951,17 +1968,21 @@ program.command("add").argument("<source>", "package source").option("--driver <
   await rm8(bundle.root, { recursive: true, force: true });
   console.log(`Added ${name}.`);
 });
-program.command("list").argument("<source>", "local source directory").option("--driver <driver>", "source driver").action(async (source, options) => {
-  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(source));
-  const resolved = await driver.resolve(source);
+program.command("list").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const resolvedInput = await resolvePackageSource(source, targetRoot);
+  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join18(targetRoot, ".agentwheel", "cache") }))));
   const artifacts = await driver.list(resolved);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
   }
 });
-program.command("scan").argument("<source>", "local source directory").option("--driver <driver>", "source driver").action(async (source, options) => {
-  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(source));
-  const resolved = await driver.resolve(source);
+program.command("scan").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const resolvedInput = await resolvePackageSource(source, targetRoot);
+  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join18(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -1972,7 +1993,7 @@ program.command("scan").argument("<source>", "local source directory").option("-
   }
   if (!result.ok) process.exitCode = 1;
 });
-program.command("plan").argument("<source>", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("--target-root <path>", "runtime/project root", process.cwd()).option("--mode <mode>", "pinned or tracking").action(async (source, options) => {
+program.command("plan").argument("<source>", "source directory").option("--driver <driver>", "source driver").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("--target-root <path>", "runtime/project root", process.cwd()).option("--mode <mode>", "pinned or tracking").option("--dry-run", "accepted for symmetry; plan never writes", false).action(async (source, options) => {
   const { plan, bundle } = await buildPlan(source, options);
   console.log(formatPlan(plan));
   await rm8(bundle.root, { recursive: true, force: true });
@@ -2105,7 +2126,6 @@ program.command("uninstall").option("--adapter <adapter>", "adapter", "openclaw"
   if (plan.hasBlockingChanges) process.exitCode = 1;
 });
 async function buildPlan(source, options) {
-  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(source));
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const adapter = await resolveAdapter({
     adapter: options.adapter,
@@ -2115,21 +2135,20 @@ async function buildPlan(source, options) {
     baseDir: targetRoot,
     warn: (message) => console.warn(message)
   });
-  const bundle = await stageSource(driver, source, {
-    workspaceRoot: targetRoot,
+  const result = await createSourcePlan({
+    source,
+    targetRoot,
     adapter,
-    cacheRoot: join17(targetRoot, ".agentwheel", "cache"),
+    driver: options.driver,
     mode: options.mode
   });
-  const manifest = await readInstallManifest(targetRoot, adapter.name);
-  const plan = await createInstallPlan(bundle, adapter, targetRoot, manifest);
-  return { plan, bundle };
+  return { plan: result.plan, bundle: result.bundle };
 }
 async function initPackage(root) {
-  await mkdir7(join17(root, "instructions"), { recursive: true });
-  await mkdir7(join17(root, "rules"), { recursive: true });
-  await mkdir7(join17(root, "skills"), { recursive: true });
-  const manifestPath = join17(root, "agentwheel.json");
+  await mkdir7(join18(root, "instructions"), { recursive: true });
+  await mkdir7(join18(root, "rules"), { recursive: true });
+  await mkdir7(join18(root, "skills"), { recursive: true });
+  const manifestPath = join18(root, "agentwheel.json");
   const manifest = {
     schemaVersion: 1,
     name: "example/agentwheel-package",
@@ -2142,7 +2161,7 @@ async function initPackage(root) {
   };
   await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile4(join17(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile4(join18(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 function printRegistryEntries(entries) {
   for (const entry of entries) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",