agentwheel 0.2.0

package/dist/index.js

@@ -0,0 +1,1402 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { mkdir as mkdir6, rm as rm6, writeFile as writeFile3 } from "fs/promises";
+import { join as join12 } from "path";
+import { Command } from "commander";
+
+// src/adapters/claude.ts
+var claudeAdapter = {
+  name: "claude",
+  displayName: "Claude",
+  targets: {}
+};
+
+// src/adapters/copilot.ts
+var copilotAdapter = {
+  name: "copilot",
+  displayName: "GitHub Copilot",
+  targets: {
+    instructions: { enabled: true, dest: ".github/copilot-instructions.md" },
+    rules: { enabled: true, dest: ".github/instructions" },
+    commands: { enabled: true, dest: ".github/prompts" },
+    // GitHub Copilot has no native SKILL.md runtime surface; keep skills disabled
+    // until a conversion target is introduced.
+    skills: { enabled: false, dest: ".github/skills" }
+  }
+};
+
+// src/adapters/codex.ts
+var codexAdapter = {
+  name: "codex",
+  displayName: "Codex",
+  targets: {}
+};
+
+// src/adapters/hermes.ts
+var hermesAdapter = {
+  name: "hermes",
+  displayName: "Hermes",
+  targets: {
+    instructions: { enabled: true, dest: ".hermes/AGENTS.md" },
+    rules: { enabled: true, dest: ".hermes/rules" },
+    skills: { enabled: true, dest: ".hermes/skills" },
+    commands: { enabled: true, dest: ".hermes/commands" },
+    mcp: { enabled: true, dest: ".hermes/mcp" },
+    hooks: { enabled: true, dest: ".hermes/hooks" }
+  }
+};
+
+// src/adapters/openclaw.ts
+var openClawAdapter = {
+  name: "openclaw",
+  displayName: "OpenClaw",
+  targets: {
+    instructions: { enabled: true, dest: ".openclaw/AGENTS.md" },
+    rules: { enabled: true, dest: ".openclaw/rules" },
+    skills: { enabled: true, dest: ".openclaw/skills" },
+    commands: { enabled: true, dest: ".openclaw/commands" },
+    mcp: { enabled: true, dest: ".openclaw/mcp" },
+    hooks: { enabled: true, dest: ".openclaw/hooks" },
+    plugins: { enabled: true, dest: ".openclaw/plugins", semantic: "openclaw-plugin" }
+  }
+};
+
+// src/adapters/index.ts
+var adapters = [openClawAdapter, claudeAdapter, codexAdapter, hermesAdapter, copilotAdapter];
+function getAdapter(name) {
+  const adapter = adapters.find((candidate) => candidate.name === name);
+  if (!adapter) {
+    throw new Error(`Unknown adapter: ${name}`);
+  }
+  return adapter;
+}
+
+// src/model/adapter.ts
+import { readFile } from "fs/promises";
+import { parse, printParseErrorCode } from "jsonc-parser";
+import { z as z2 } from "zod";
+
+// src/model/artifact.ts
+import { z } from "zod";
+var artifactTypeSchema = z.enum([
+  "instructions",
+  "rules",
+  "skills",
+  "commands",
+  "subagents",
+  "mcp",
+  "hooks",
+  "plugins"
+]);
+var fileKindSchema = z.enum(["file", "dir"]);
+var artifactSchema = z.object({
+  type: artifactTypeSchema,
+  name: z.string().min(1),
+  sourcePath: z.string().min(1),
+  stagedPath: z.string().min(1).optional(),
+  relativePath: z.string().min(1),
+  kind: fileKindSchema,
+  hash: z.string().min(16),
+  packageName: z.string().min(1).optional(),
+  channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed")
+});
+
+// src/model/adapter.ts
+var targetMappingSchema = z2.object({
+  dest: z2.string().min(1),
+  enabled: z2.boolean().default(true),
+  semantic: z2.enum(["openclaw-plugin"]).optional()
+});
+var adapterSchema = z2.object({
+  name: z2.string().min(1),
+  displayName: z2.string().min(1).optional(),
+  targets: z2.partialRecord(
+    artifactTypeSchema,
+    targetMappingSchema
+  ).default({})
+});
+async function loadAdapterConfig(path) {
+  const content = await readFile(path, "utf8");
+  const errors = [];
+  const parsed = parse(content, errors, {
+    allowTrailingComma: true,
+    disallowComments: false
+  });
+  if (errors.length > 0) {
+    const details = errors.map((error) => `${printParseErrorCode(error.error)} at offset ${error.offset}`).join(", ");
+    throw new Error(`Invalid adapter config ${path}: ${details}`);
+  }
+  return adapterSchema.parse(parsed);
+}
+
+// src/install/apply.ts
+import { execFile } from "child_process";
+import { rm as rm3 } from "fs/promises";
+import { promisify } from "util";
+
+// src/utils/fs.ts
+import { createHash } from "crypto";
+import {
+  copyFile,
+  cp,
+  mkdir,
+  readdir,
+  readFile as readFile2,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import { dirname, join, relative } from "path";
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function hashPath(path) {
+  const stats = await stat(path);
+  if (stats.isFile()) {
+    const content = await readFile2(path);
+    return createHash("sha256").update("file\0").update(content).digest("hex");
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`Unsupported path kind: ${path}`);
+  }
+  const hash = createHash("sha256").update("dir\0");
+  const files = await listFiles(path);
+  for (const file of files) {
+    hash.update(relative(path, file).replaceAll("\\", "/")).update("\0");
+    hash.update(await hashPath(file)).update("\0");
+  }
+  return hash.digest("hex");
+}
+async function listFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+async function atomicCopy(source, dest, kind) {
+  await mkdir(dirname(dest), { recursive: true });
+  const temp = `${dest}.agentwheel-tmp-${process.pid}-${Date.now()}`;
+  await rm(temp, { recursive: true, force: true });
+  if (kind === "file") {
+    await copyFile(source, temp);
+  } else {
+    await cp(source, temp, { recursive: true, dereference: true });
+  }
+  await rm(dest, { recursive: true, force: true });
+  await rename(temp, dest);
+}
+async function writeJsonAtomic(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temp, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+  await rename(temp, path);
+}
+
+// src/install/manifest.ts
+import { readFile as readFile3, rm as rm2 } from "fs/promises";
+import { resolve } from "path";
+
+// src/model/manifest.ts
+import { z as z3 } from "zod";
+var manifestEntrySchema = z3.object({
+  path: z3.string().min(1),
+  artifactType: artifactTypeSchema,
+  artifactName: z3.string().min(1),
+  kind: fileKindSchema,
+  hash: z3.string().min(16),
+  sourceHash: z3.string().min(16),
+  updatedAt: z3.string().datetime(),
+  channel: z3.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
+  packageName: z3.string().min(1).optional(),
+  semanticCommand: z3.array(z3.string()).optional(),
+  executed: z3.boolean().optional()
+});
+var installManifestSchema = z3.object({
+  version: z3.literal(1),
+  adapter: z3.string().min(1),
+  targetRoot: z3.string().min(1),
+  generatedAt: z3.string().datetime(),
+  entries: z3.array(manifestEntrySchema)
+});
+var sourceLockSchema = z3.object({
+  version: z3.literal(1),
+  driver: z3.string().min(1),
+  source: z3.string().min(1),
+  resolvedPath: z3.string().min(1),
+  packageName: z3.string().min(1).optional(),
+  packageVersion: z3.string().min(1).optional(),
+  mode: z3.enum(["pinned", "tracking"]).default("pinned"),
+  requestedRef: z3.string().min(1).optional(),
+  resolvedCommit: z3.string().min(1).optional(),
+  sourceHash: z3.string().min(16).optional(),
+  generatedAt: z3.string().datetime(),
+  artifacts: z3.array(
+    z3.object({
+      type: artifactTypeSchema,
+      name: z3.string().min(1),
+      relativePath: z3.string().min(1),
+      kind: fileKindSchema,
+      hash: z3.string().min(16)
+    })
+  )
+});
+
+// src/install/paths.ts
+import { join as join2 } from "path";
+function metadataDir(targetRoot) {
+  return join2(targetRoot, ".agentwheel");
+}
+function installManifestPath(targetRoot, adapter) {
+  return join2(metadataDir(targetRoot), `${adapter}.install-manifest.json`);
+}
+function sourceLockPath(targetRoot, adapter) {
+  return join2(metadataDir(targetRoot), `${adapter}.source-lock.json`);
+}
+
+// src/install/manifest.ts
+async function readInstallManifest(targetRoot, adapter) {
+  const path = installManifestPath(targetRoot, adapter);
+  if (!await pathExists(path)) return void 0;
+  return installManifestSchema.parse(JSON.parse(await readFile3(path, "utf8")));
+}
+async function writeInstallManifest(manifest) {
+  await writeJsonAtomic(installManifestPath(manifest.targetRoot, manifest.adapter), manifest);
+}
+async function writeSourceLock(targetRoot, adapter, lock) {
+  await writeJsonAtomic(sourceLockPath(targetRoot, adapter), lock);
+}
+async function readSourceLock(targetRoot, adapter) {
+  const path = sourceLockPath(targetRoot, adapter);
+  if (!await pathExists(path)) return void 0;
+  return sourceLockSchema.parse(JSON.parse(await readFile3(path, "utf8")));
+}
+async function removeStateFiles(targetRoot, adapter) {
+  await rm2(installManifestPath(targetRoot, adapter), { force: true });
+  await rm2(sourceLockPath(targetRoot, adapter), { force: true });
+}
+function normalizeTargetRoot(path) {
+  return resolve(path);
+}
+
+// src/install/apply.ts
+var execFileAsync = promisify(execFile);
+async function applyInstallPlan(plan, sourceLock, options = {}) {
+  if (plan.hasBlockingChanges) {
+    const blockers = plan.operations.filter((operation) => operation.action === "drift" || operation.action === "conflict");
+    throw new Error(`Refusing to apply with blocking changes: ${blockers.map((item) => item.relativeDestPath).join(", ")}`);
+  }
+  const entries = [];
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const operation of plan.operations) {
+    if (operation.action === "plugin") {
+      if (!operation.desiredHash) {
+        throw new Error(`Invalid plugin operation missing hash: ${operation.relativeDestPath}`);
+      }
+      if (options.executePlugins) {
+        if (!operation.semanticCommand || operation.semanticCommand.length === 0) {
+          throw new Error(`Invalid plugin operation missing command: ${operation.relativeDestPath}`);
+        }
+        const command = operation.semanticCommand[0];
+        const args = operation.semanticCommand.slice(1);
+        if (!command) {
+          throw new Error(`Invalid plugin operation missing command: ${operation.relativeDestPath}`);
+        }
+        await execFileAsync(command, args);
+      }
+      entries.push({
+        path: operation.relativeDestPath,
+        artifactType: operation.artifactType,
+        artifactName: operation.artifactName,
+        kind: operation.kind,
+        hash: operation.desiredHash,
+        sourceHash: operation.desiredHash,
+        updatedAt: now,
+        channel: operation.channel,
+        packageName: operation.packageName,
+        semanticCommand: operation.semanticCommand,
+        executed: options.executePlugins === true
+      });
+    } else if (operation.action === "create" || operation.action === "update") {
+      if (!operation.sourcePath || !operation.desiredHash) {
+        throw new Error(`Invalid operation missing source/hash: ${operation.relativeDestPath}`);
+      }
+      await atomicCopy(operation.sourcePath, operation.destPath, operation.kind);
+      entries.push({
+        path: operation.relativeDestPath,
+        artifactType: operation.artifactType,
+        artifactName: operation.artifactName,
+        kind: operation.kind,
+        hash: await hashPath(operation.destPath),
+        sourceHash: operation.desiredHash,
+        updatedAt: now,
+        channel: operation.channel,
+        packageName: operation.packageName,
+        semanticCommand: operation.semanticCommand
+      });
+    } else if (operation.action === "skip") {
+      if (!operation.desiredHash) {
+        throw new Error(`Invalid skip operation missing hash: ${operation.relativeDestPath}`);
+      }
+      entries.push({
+        path: operation.relativeDestPath,
+        artifactType: operation.artifactType,
+        artifactName: operation.artifactName,
+        kind: operation.kind,
+        hash: operation.desiredHash,
+        sourceHash: operation.desiredHash,
+        updatedAt: now,
+        channel: operation.channel,
+        packageName: operation.packageName,
+        semanticCommand: operation.semanticCommand
+      });
+    } else if (operation.action === "remove") {
+      await rm3(operation.destPath, { recursive: true, force: true });
+    }
+  }
+  const manifest = {
+    version: 1,
+    adapter: plan.adapter,
+    targetRoot: plan.targetRoot,
+    generatedAt: now,
+    entries: entries.sort((a, b) => a.path.localeCompare(b.path))
+  };
+  await writeInstallManifest(manifest);
+  await writeSourceLock(plan.targetRoot, plan.adapter, sourceLock);
+  return manifest;
+}
+async function uninstall(plan, dryRun) {
+  if (plan.hasBlockingChanges) {
+    const blockers = plan.operations.filter((operation) => operation.action === "drift" || operation.action === "conflict");
+    throw new Error(`Refusing to uninstall with drift: ${blockers.map((item) => item.relativeDestPath).join(", ")}`);
+  }
+  if (dryRun) return;
+  for (const operation of plan.operations) {
+    await rm3(operation.destPath, { recursive: true, force: true });
+  }
+  await removeStateFiles(plan.targetRoot, plan.adapter);
+}
+
+// src/install/plan.ts
+import { join as join3, relative as relative2 } from "path";
+
+// src/targets/plugins/openclaw.ts
+function openClawPluginInstallCommand(request) {
+  return ["openclaw", "plugins", "install", "--link", request.path];
+}
+
+// src/install/plan.ts
+async function createInstallPlan(bundle, adapter, targetRoot, manifest) {
+  const desired = /* @__PURE__ */ new Map();
+  for (const artifact of bundle.artifacts) {
+    const op = operationForArtifact(artifact, adapter, targetRoot);
+    if (op) {
+      desired.set(op.relativeDestPath, op);
+    }
+  }
+  const manifestByPath = new Map((manifest?.entries ?? []).map((entry) => [entry.path, entry]));
+  const operations = [];
+  for (const op of desired.values()) {
+    if (op.action === "plugin") {
+      const existing2 = manifestByPath.get(op.relativeDestPath);
+      if (existing2 && existing2.hash === op.desiredHash) {
+        operations.push({ ...op, action: "skip", manifestHash: existing2.hash, reason: "plugin already planned" });
+      } else {
+        operations.push(op);
+      }
+      continue;
+    }
+    const existing = manifestByPath.get(op.relativeDestPath);
+    const exists = await pathExists(op.destPath);
+    if (!exists) {
+      operations.push({ ...op, action: "create", reason: "destination missing" });
+      continue;
+    }
+    const currentHash = await hashPath(op.destPath);
+    if (!existing) {
+      operations.push({ ...op, action: "conflict", currentHash, reason: "destination exists but is not managed" });
+      continue;
+    }
+    if (currentHash !== existing.hash) {
+      operations.push({
+        ...op,
+        action: "drift",
+        currentHash,
+        manifestHash: existing.hash,
+        reason: "managed destination changed outside agentwheel"
+      });
+      continue;
+    }
+    if (currentHash === op.desiredHash) {
+      operations.push({ ...op, action: "skip", currentHash, manifestHash: existing.hash, reason: "already up to date" });
+    } else {
+      operations.push({ ...op, action: "update", currentHash, manifestHash: existing.hash, reason: "source changed" });
+    }
+  }
+  for (const entry of manifest?.entries ?? []) {
+    if (desired.has(entry.path)) continue;
+    const destPath = join3(targetRoot, entry.path);
+    if (!await pathExists(destPath)) continue;
+    const currentHash = await hashPath(destPath);
+    if (currentHash !== entry.hash) {
+      operations.push({
+        action: "drift",
+        artifactType: entry.artifactType,
+        artifactName: entry.artifactName,
+        kind: entry.kind,
+        destPath,
+        relativeDestPath: entry.path,
+        currentHash,
+        manifestHash: entry.hash,
+        reason: "managed stale destination changed outside agentwheel",
+        channel: entry.channel,
+        packageName: entry.packageName
+      });
+    } else {
+      operations.push({
+        action: "remove",
+        artifactType: entry.artifactType,
+        artifactName: entry.artifactName,
+        kind: entry.kind,
+        destPath,
+        relativeDestPath: entry.path,
+        currentHash,
+        manifestHash: entry.hash,
+        reason: "artifact removed from source",
+        channel: entry.channel,
+        packageName: entry.packageName
+      });
+    }
+  }
+  operations.sort((a, b) => a.relativeDestPath.localeCompare(b.relativeDestPath));
+  return {
+    adapter: adapter.name,
+    targetRoot,
+    operations,
+    hasBlockingChanges: operations.some((op) => op.action === "drift" || op.action === "conflict")
+  };
+}
+function operationForArtifact(artifact, adapter, targetRoot) {
+  const target = adapter.targets[artifact.type];
+  if (!target?.enabled) return void 0;
+  if (artifact.type === "plugins" && target.semantic === "openclaw-plugin") {
+    const sourcePath = artifact.stagedPath ?? artifact.sourcePath;
+    return {
+      action: "plugin",
+      artifactType: artifact.type,
+      artifactName: artifact.name,
+      kind: artifact.kind,
+      sourcePath,
+      destPath: targetRoot,
+      relativeDestPath: `plugins/${artifact.name}`,
+      desiredHash: artifact.hash,
+      reason: "semantic plugin install planned",
+      channel: artifact.channel ?? "managed",
+      packageName: artifact.packageName,
+      semanticCommand: openClawPluginInstallCommand({ path: sourcePath, dryRun: true })
+    };
+  }
+  const destPath = artifact.type === "instructions" ? join3(targetRoot, target.dest) : join3(targetRoot, target.dest, artifact.name);
+  return {
+    action: "create",
+    artifactType: artifact.type,
+    artifactName: artifact.name,
+    kind: artifact.kind,
+    sourcePath: artifact.stagedPath ?? artifact.sourcePath,
+    destPath,
+    relativeDestPath: relative2(targetRoot, destPath).replaceAll("\\", "/"),
+    desiredHash: artifact.hash,
+    reason: "destination missing",
+    channel: artifact.channel ?? "managed",
+    packageName: artifact.packageName
+  };
+}
+function summarizePlan(plan) {
+  const summary = {
+    create: 0,
+    update: 0,
+    skip: 0,
+    remove: 0,
+    drift: 0,
+    conflict: 0,
+    plugin: 0
+  };
+  for (const operation of plan.operations) {
+    summary[operation.action]++;
+  }
+  return summary;
+}
+
+// src/install/uninstall.ts
+import { join as join4 } from "path";
+async function createUninstallPlan(manifest) {
+  const operations = [];
+  for (const entry of manifest.entries) {
+    const destPath = join4(manifest.targetRoot, entry.path);
+    if (!await pathExists(destPath)) continue;
+    const currentHash = await hashPath(destPath);
+    if (currentHash !== entry.hash) {
+      operations.push({
+        action: "drift",
+        artifactType: entry.artifactType,
+        artifactName: entry.artifactName,
+        kind: entry.kind,
+        destPath,
+        relativeDestPath: entry.path,
+        currentHash,
+        manifestHash: entry.hash,
+        reason: "managed destination changed outside agentwheel",
+        channel: entry.channel,
+        packageName: entry.packageName
+      });
+    } else {
+      operations.push({
+        action: "remove",
+        artifactType: entry.artifactType,
+        artifactName: entry.artifactName,
+        kind: entry.kind,
+        destPath,
+        relativeDestPath: entry.path,
+        currentHash,
+        manifestHash: entry.hash,
+        reason: "uninstall managed artifact",
+        channel: entry.channel,
+        packageName: entry.packageName
+      });
+    }
+  }
+  operations.sort((a, b) => a.relativeDestPath.localeCompare(b.relativeDestPath));
+  return {
+    adapter: manifest.adapter,
+    targetRoot: manifest.targetRoot,
+    operations,
+    hasBlockingChanges: operations.some((operation) => operation.action === "drift" || operation.action === "conflict")
+  };
+}
+
+// src/cli/format.ts
+var labels = {
+  create: "CREATE",
+  update: "UPDATE",
+  skip: "SKIP",
+  remove: "REMOVE",
+  drift: "DRIFT",
+  conflict: "CONFLICT",
+  plugin: "PLUGIN"
+};
+var channelLabels = {
+  managed: "MANAGED",
+  overlay: "OVERLAY",
+  addition: "ADDITION",
+  override: "OVERRIDE",
+  ejected: "EJECTED"
+};
+function formatPlan(plan) {
+  const lines = [`Plan for ${plan.adapter} at ${plan.targetRoot}`];
+  for (const operation of plan.operations) {
+    const source = operation.sourcePath ? `${operation.sourcePath} -> ` : "";
+    const command = operation.semanticCommand ? ` :: ${operation.semanticCommand.join(" ")}` : "";
+    lines.push(`${labels[operation.action].padEnd(8)} ${channelLabels[operation.channel].padEnd(8)} ${operation.artifactType}/${operation.artifactName} ${source}${operation.relativeDestPath} (${operation.reason})${command}`);
+  }
+  const summary = summarizePlan(plan);
+  lines.push(
+    `Summary: create ${summary.create}, update ${summary.update}, skip ${summary.skip}, remove ${summary.remove}, drift ${summary.drift}, conflict ${summary.conflict}, plugin ${summary.plugin}`
+  );
+  return lines.join("\n");
+}
+
+// src/source/git.ts
+import { execFile as execFile2 } from "child_process";
+import { mkdir as mkdir2, rm as rm4 } from "fs/promises";
+import { homedir } from "os";
+import { basename as basename2, join as join7, resolve as resolve3 } from "path";
+import { promisify as promisify2 } from "util";
+
+// src/model/package.ts
+import { readFile as readFile4 } from "fs/promises";
+import { join as join5 } from "path";
+import { parse as parse2, printParseErrorCode as printParseErrorCode2 } from "jsonc-parser";
+import { z as z4 } from "zod";
+var packageProvideSchema = z4.object({
+  type: artifactTypeSchema,
+  path: z4.string().min(1)
+});
+var packageManifestSchema = z4.object({
+  schemaVersion: z4.literal(1),
+  name: z4.string().min(1),
+  version: z4.string().min(1),
+  provides: z4.array(packageProvideSchema).min(1)
+});
+async function findPackageManifestPath(root) {
+  for (const name of ["agentwheel.json", "agentwheel.jsonc"]) {
+    const candidate = join5(root, name);
+    if (await pathExists(candidate)) return candidate;
+  }
+  return void 0;
+}
+async function readPackageManifest(root) {
+  const path = await findPackageManifestPath(root);
+  if (!path) return void 0;
+  const content = await readFile4(path, "utf8");
+  const errors = [];
+  const parsed = parse2(content, errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length > 0) {
+    const details = errors.map((error) => `${printParseErrorCode2(error.error)} at offset ${error.offset}`).join(", ");
+    throw new Error(`Invalid package manifest ${path}: ${details}`);
+  }
+  return packageManifestSchema.parse(parsed);
+}
+
+// src/source/local.ts
+import { readdir as readdir2, stat as stat2 } from "fs/promises";
+import { basename, join as join6, resolve as resolve2 } from "path";
+var LocalSourceDriver = class {
+  name = "local";
+  async resolve(source) {
+    const resolvedPath = resolve2(source);
+    if (!await pathExists(resolvedPath)) {
+      throw new Error(`Local source not found: ${resolvedPath}`);
+    }
+    const stats = await stat2(resolvedPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Local source must be a directory: ${resolvedPath}`);
+    }
+    const manifest = await readPackageManifest(resolvedPath);
+    return {
+      driver: this.name,
+      source,
+      resolvedPath,
+      packageName: manifest?.name,
+      packageVersion: manifest?.version,
+      mode: "pinned",
+      sourceHash: await hashPath(resolvedPath)
+    };
+  }
+  async list(resolved) {
+    const manifest = await readPackageManifest(resolved.resolvedPath);
+    if (manifest) {
+      return listFromManifest(resolved.resolvedPath, manifest.name);
+    }
+    const artifacts = [];
+    const root = resolved.resolvedPath;
+    const instructions = await firstExisting([join6(root, "instructions.md"), join6(root, "AGENTS.md")]);
+    if (instructions) {
+      artifacts.push({
+        type: "instructions",
+        name: basename(instructions),
+        sourcePath: instructions,
+        relativePath: basename(instructions),
+        kind: "file",
+        hash: await hashPath(instructions),
+        packageName: resolved.packageName,
+        channel: "managed"
+      });
+    }
+    const rulesDir = join6(root, "rules");
+    if (await pathExists(rulesDir)) {
+      for (const entry of await sortedDirEntries(rulesDir)) {
+        const full = join6(rulesDir, entry.name);
+        if (entry.isFile()) {
+          artifacts.push({
+            type: "rules",
+            name: entry.name,
+            sourcePath: full,
+            relativePath: join6("rules", entry.name),
+            kind: "file",
+            hash: await hashPath(full),
+            packageName: resolved.packageName,
+            channel: "managed"
+          });
+        }
+      }
+    }
+    const skillsDir = join6(root, "skills");
+    if (await pathExists(skillsDir)) {
+      for (const entry of await sortedDirEntries(skillsDir)) {
+        const full = join6(skillsDir, entry.name);
+        if (entry.isDirectory()) {
+          artifacts.push({
+            type: "skills",
+            name: entry.name,
+            sourcePath: full,
+            relativePath: join6("skills", entry.name),
+            kind: "dir",
+            hash: await hashPath(full),
+            packageName: resolved.packageName,
+            channel: "managed"
+          });
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          artifacts.push({
+            type: "skills",
+            name: entry.name.replace(/\.md$/, ""),
+            sourcePath: full,
+            relativePath: join6("skills", entry.name),
+            kind: "file",
+            hash: await hashPath(full),
+            packageName: resolved.packageName,
+            channel: "managed"
+          });
+        }
+      }
+    }
+    for (const type of ["commands", "mcp", "hooks", "plugins"]) {
+      const dir = join6(root, type);
+      if (!await pathExists(dir)) continue;
+      artifacts.push(...await listGenericArtifacts(type, dir, type, resolved.packageName));
+    }
+    return artifacts;
+  }
+  async fetch(resolved) {
+    return resolved;
+  }
+  async scan(resolved) {
+    const artifacts = await this.list(resolved);
+    const findings = [];
+    if (!artifacts.some((artifact) => artifact.type === "instructions")) {
+      findings.push({ level: "warning", message: "No instructions.md or AGENTS.md found", path: resolved.resolvedPath });
+    }
+    for (const artifact of artifacts.filter((item) => item.type === "skills" && item.kind === "dir")) {
+      if (!await pathExists(join6(artifact.sourcePath, "SKILL.md"))) {
+        findings.push({ level: "warning", message: `Skill directory has no SKILL.md: ${artifact.name}`, path: artifact.sourcePath });
+      }
+    }
+    return { ok: !findings.some((finding) => finding.level === "error"), findings };
+  }
+  async translate(resolved) {
+    return resolved;
+  }
+  async export(resolved) {
+    return resolved;
+  }
+};
+async function firstExisting(paths) {
+  for (const path of paths) {
+    if (await pathExists(path)) return path;
+  }
+  return void 0;
+}
+async function sortedDirEntries(path) {
+  return (await readdir2(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+}
+async function listFromManifest(root, packageName) {
+  const manifest = await readPackageManifest(root);
+  if (!manifest) return [];
+  const artifacts = [];
+  for (const provide of manifest.provides) {
+    const full = join6(root, provide.path);
+    if (!await pathExists(full)) continue;
+    const stats = await stat2(full);
+    if (provide.type === "instructions") {
+      if (stats.isFile()) {
+        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName));
+      }
+      continue;
+    }
+    if (stats.isDirectory()) {
+      for (const entry of await sortedDirEntries(full)) {
+        const child = join6(full, entry.name);
+        if (provide.type === "skills" && entry.isDirectory()) {
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName));
+        } else if (provide.type === "plugins" && entry.isDirectory()) {
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName));
+        } else if (entry.isFile()) {
+          const name = provide.type === "rules" && entry.name.endsWith(".md") ? entry.name : entry.name;
+          artifacts.push(await artifactForFile(provide.type, name, child, join6(provide.path, entry.name), packageName));
+        }
+      }
+    } else if (stats.isFile()) {
+      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName));
+    }
+  }
+  return artifacts;
+}
+async function listGenericArtifacts(type, dir, relativeRoot, packageName) {
+  const artifacts = [];
+  for (const entry of await sortedDirEntries(dir)) {
+    const full = join6(dir, entry.name);
+    if (entry.isDirectory()) {
+      artifacts.push(await artifactForDir(type, entry.name, full, join6(relativeRoot, entry.name), packageName));
+    } else if (entry.isFile()) {
+      artifacts.push(await artifactForFile(type, entry.name, full, join6(relativeRoot, entry.name), packageName));
+    }
+  }
+  return artifacts;
+}
+async function artifactForFile(type, name, sourcePath, relativePath, packageName) {
+  return {
+    type,
+    name,
+    sourcePath,
+    relativePath,
+    kind: "file",
+    hash: await hashPath(sourcePath),
+    packageName,
+    channel: "managed"
+  };
+}
+async function artifactForDir(type, name, sourcePath, relativePath, packageName) {
+  return {
+    type,
+    name,
+    sourcePath,
+    relativePath,
+    kind: "dir",
+    hash: await hashPath(sourcePath),
+    packageName,
+    channel: "managed"
+  };
+}
+
+// src/source/git.ts
+var execFileAsync2 = promisify2(execFile2);
+var GitSourceDriver = class {
+  name = "git";
+  local = new LocalSourceDriver();
+  async resolve(source, options = {}) {
+    const parsed = parseGitSource(source);
+    const requestedRef = options.ref ?? parsed.ref ?? "HEAD";
+    const mode = options.mode ?? (parsed.ref ? "pinned" : "tracking");
+    return {
+      driver: this.name,
+      source,
+      resolvedPath: cachePathFor(parsed.url, options.cacheRoot),
+      mode,
+      requestedRef
+    };
+  }
+  async fetch(resolved) {
+    const parsed = parseGitSource(resolved.source);
+    await mkdir2(resolve3(resolved.resolvedPath, ".."), { recursive: true });
+    if (!await pathExists(join7(resolved.resolvedPath, ".git"))) {
+      await rm4(resolved.resolvedPath, { recursive: true, force: true });
+      await git(["clone", "--no-tags", parsed.url, resolved.resolvedPath]);
+    } else {
+      await git(["-C", resolved.resolvedPath, "fetch", "--prune", "origin"]);
+    }
+    const ref = resolved.requestedRef ?? parsed.ref ?? "HEAD";
+    if (ref === "HEAD") {
+      await git(["-C", resolved.resolvedPath, "checkout", "--detach", "origin/HEAD"]);
+    } else if (/^[0-9a-f]{7,40}$/i.test(ref)) {
+      await git(["-C", resolved.resolvedPath, "checkout", "--detach", ref]);
+    } else {
+      try {
+        await git(["-C", resolved.resolvedPath, "checkout", ref]);
+        await git(["-C", resolved.resolvedPath, "reset", "--hard", `origin/${ref}`]);
+      } catch {
+        await git(["-C", resolved.resolvedPath, "checkout", "--detach", ref]);
+      }
+    }
+    const { stdout } = await git(["-C", resolved.resolvedPath, "rev-parse", "HEAD"]);
+    const resolvedCommit = stdout.trim();
+    const manifest = await readPackageManifest(resolved.resolvedPath);
+    return {
+      ...resolved,
+      packageName: manifest?.name,
+      packageVersion: manifest?.version,
+      resolvedCommit,
+      sourceHash: await hashPath(resolved.resolvedPath)
+    };
+  }
+  async list(resolved) {
+    return this.local.list({ ...resolved, driver: "local" });
+  }
+  async scan(resolved) {
+    return this.local.scan({ ...resolved, driver: "local" });
+  }
+  async translate(resolved) {
+    return resolved;
+  }
+  async export(resolved) {
+    return resolved;
+  }
+};
+function parseGitSource(source) {
+  if (source.startsWith("github:")) {
+    const rest = source.slice("github:".length);
+    const [repo, ref] = rest.split("#", 2);
+    if (!repo.includes("/")) throw new Error(`Invalid GitHub source: ${source}`);
+    return { url: `https://github.com/${repo}.git`, ref };
+  }
+  if (source.startsWith("git:")) {
+    const rest = source.slice("git:".length);
+    const hashIndex = rest.lastIndexOf("#");
+    if (hashIndex >= 0) {
+      return { url: rest.slice(0, hashIndex), ref: rest.slice(hashIndex + 1) };
+    }
+    return { url: rest };
+  }
+  throw new Error(`Invalid git source: ${source}`);
+}
+function cachePathFor(url, cacheRoot) {
+  const root = cacheRoot ? resolve3(cacheRoot) : join7(homedir(), ".agentwheel", "cache");
+  const slug = url.replace(/^[a-z]+:\/\//i, "").replace(/\.git$/i, "").replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "");
+  return join7(root, slug || basename2(url));
+}
+async function git(args) {
+  return execFileAsync2("git", args, { maxBuffer: 1024 * 1024 * 10 });
+}
+
+// src/source/index.ts
+var drivers = [new LocalSourceDriver(), new GitSourceDriver()];
+function getSourceDriver(name = "local") {
+  const driver = drivers.find((candidate) => candidate.name === name);
+  if (!driver) {
+    throw new Error(`Unknown source driver: ${name}`);
+  }
+  return driver;
+}
+
+// src/staging/staging.ts
+import { cp as cp3, mkdir as mkdir4, mkdtemp } from "fs/promises";
+import { dirname as dirname3, join as join9 } from "path";
+import { tmpdir } from "os";
+
+// src/staging/customize.ts
+import { cp as cp2, mkdir as mkdir3, readdir as readdir3, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join8 } from "path";
+async function applyCustomizations(artifacts, options) {
+  let next = [...artifacts];
+  next = await applyReplacements(next, options, "override");
+  next = await applyReplacements(next, options, "ejected");
+  next = await applyAdditions(next, options);
+  next = await applyInstructionOverlay(next, options);
+  return next.sort((a, b) => `${a.type}:${a.name}:${a.channel}`.localeCompare(`${b.type}:${b.name}:${b.channel}`));
+}
+async function applyInstructionOverlay(artifacts, options) {
+  const overlayPath = join8(options.workspaceRoot, ".agentwheel", "overlays", options.adapter.name, "instructions.local.md");
+  if (!await pathExists(overlayPath)) return artifacts;
+  const index = artifacts.findIndex((artifact2) => artifact2.type === "instructions");
+  if (index < 0) return artifacts;
+  const artifact = artifacts[index];
+  const managed = await readFile5(artifact.stagedPath ?? artifact.sourcePath, "utf8");
+  const local = await readFile5(overlayPath, "utf8");
+  const composedPath = join8(options.stageRoot, ".agentwheel-composed", "instructions", "AGENTS.md");
+  await mkdir3(dirname2(composedPath), { recursive: true });
+  await writeFile2(
+    composedPath,
+    [
+      "<!-- BEGIN agentwheel managed: upstream -->",
+      managed.trimEnd(),
+      "<!-- END agentwheel managed: upstream -->",
+      "",
+      "<!-- BEGIN agentwheel local: editable -->",
+      local.trimEnd(),
+      "<!-- END agentwheel local: editable -->",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  const updated = {
+    ...artifact,
+    sourcePath: composedPath,
+    stagedPath: composedPath,
+    relativePath: "instructions/AGENTS.md",
+    name: "AGENTS.md",
+    hash: await hashPath(composedPath),
+    channel: "overlay"
+  };
+  return [...artifacts.slice(0, index), updated, ...artifacts.slice(index + 1)];
+}
+async function applyAdditions(artifacts, options) {
+  const additionsRoot = join8(options.workspaceRoot, ".agentwheel", "additions");
+  const rulesRoot = join8(additionsRoot, "rules");
+  if (!await pathExists(rulesRoot)) return artifacts;
+  const additions = [];
+  for (const entry of await sortedDirEntries2(rulesRoot)) {
+    const full = join8(rulesRoot, entry.name);
+    if (!entry.isFile()) continue;
+    additions.push({
+      type: "rules",
+      name: entry.name,
+      sourcePath: full,
+      stagedPath: full,
+      relativePath: join8("additions", "rules", entry.name),
+      kind: "file",
+      hash: await hashPath(full),
+      packageName: options.packageName,
+      channel: "addition"
+    });
+  }
+  return [...artifacts, ...additions];
+}
+async function applyReplacements(artifacts, options, channel) {
+  const packageName = options.packageName;
+  if (!packageName) return artifacts;
+  const root = join8(options.workspaceRoot, ".agentwheel", channel === "override" ? "overrides" : "ejected", ...packageName.split("/"));
+  if (!await pathExists(root)) return artifacts;
+  const byKey = new Map(artifacts.map((artifact) => [artifactKey(artifact), artifact]));
+  for (const type of ["instructions", "rules", "skills", "commands", "subagents", "mcp", "hooks", "plugins"]) {
+    const typeRoot = join8(root, type);
+    if (!await pathExists(typeRoot)) continue;
+    for (const entry of await sortedDirEntries2(typeRoot)) {
+      const full = join8(typeRoot, entry.name);
+      const kind = entry.isDirectory() ? "dir" : "file";
+      const existing = byKey.get(`${type}:${entry.name}`);
+      const stagedPath = join8(options.stageRoot, ".agentwheel-composed", channel, type, entry.name);
+      await mkdir3(dirname2(stagedPath), { recursive: true });
+      await cp2(full, stagedPath, { recursive: kind === "dir", dereference: true });
+      byKey.set(`${type}:${entry.name}`, {
+        type,
+        name: entry.name,
+        sourcePath: full,
+        stagedPath,
+        relativePath: existing?.relativePath ?? join8(type, entry.name),
+        kind,
+        hash: await hashPath(stagedPath),
+        packageName,
+        channel
+      });
+    }
+  }
+  return [...byKey.values()];
+}
+function artifactKey(artifact) {
+  return `${artifact.type}:${artifact.name}`;
+}
+async function sortedDirEntries2(path) {
+  return (await readdir3(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// src/staging/staging.ts
+async function stageSource(driver, source, options = {}) {
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(source, options))));
+  const artifacts = await driver.list(resolved);
+  const root = await mkdtemp(join9(tmpdir(), "agentwheel-stage-"));
+  const stagedArtifacts = [];
+  for (const artifact of artifacts) {
+    const stagedPath = join9(root, artifact.relativePath);
+    await mkdir4(dirname3(stagedPath), { recursive: true });
+    await cp3(artifact.sourcePath, stagedPath, { recursive: artifact.kind === "dir", dereference: true });
+    stagedArtifacts.push({
+      ...artifact,
+      stagedPath,
+      hash: await hashPath(stagedPath),
+      channel: artifact.channel ?? "managed"
+    });
+  }
+  const finalArtifacts = options.workspaceRoot && options.adapter ? await applyCustomizations(stagedArtifacts, {
+    workspaceRoot: options.workspaceRoot,
+    adapter: options.adapter,
+    stageRoot: root,
+    packageName: resolved.packageName
+  }) : stagedArtifacts;
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    root,
+    source: resolved,
+    artifacts: finalArtifacts,
+    sourceLock: {
+      version: 1,
+      driver: resolved.driver,
+      source: resolved.source,
+      resolvedPath: resolved.resolvedPath,
+      packageName: resolved.packageName,
+      packageVersion: resolved.packageVersion,
+      mode: resolved.mode ?? "pinned",
+      requestedRef: resolved.requestedRef,
+      resolvedCommit: resolved.resolvedCommit,
+      sourceHash: resolved.sourceHash,
+      generatedAt,
+      artifacts: finalArtifacts.map((artifact) => ({
+        type: artifact.type,
+        name: artifact.name,
+        relativePath: artifact.relativePath,
+        kind: artifact.kind,
+        hash: artifact.hash
+      }))
+    }
+  };
+}
+
+// src/model/workspace.ts
+import { readFile as readFile6 } from "fs/promises";
+import { join as join10 } from "path";
+import { z as z5 } from "zod";
+var workspacePackageSchema = z5.object({
+  name: z5.string().min(1),
+  source: z5.string().min(1),
+  driver: z5.enum(["local", "git"]).default("local"),
+  adapter: z5.string().min(1).default("openclaw"),
+  adapterConfig: z5.string().min(1).optional(),
+  mode: z5.enum(["pinned", "tracking"]).default("pinned"),
+  requestedRef: z5.string().min(1).optional()
+});
+var workspaceConfigSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  packages: z5.array(workspacePackageSchema).default([])
+});
+function workspaceConfigPath(workspaceRoot) {
+  return join10(workspaceRoot, ".agentwheel", "config.json");
+}
+async function readWorkspaceConfig(workspaceRoot) {
+  const path = workspaceConfigPath(workspaceRoot);
+  if (!await pathExists(path)) return { schemaVersion: 1, packages: [] };
+  return workspaceConfigSchema.parse(JSON.parse(await readFile6(path, "utf8")));
+}
+async function writeWorkspaceConfig(workspaceRoot, config) {
+  await writeJsonAtomic(workspaceConfigPath(workspaceRoot), workspaceConfigSchema.parse(config));
+}
+function upsertPackage(config, entry) {
+  const packages = config.packages.filter((candidate) => candidate.name !== entry.name);
+  packages.push(entry);
+  packages.sort((a, b) => a.name.localeCompare(b.name));
+  return { schemaVersion: 1, packages };
+}
+
+// src/lifecycle/customization.ts
+import { appendFile, cp as cp4, mkdir as mkdir5, rm as rm5 } from "fs/promises";
+import { dirname as dirname4, join as join11 } from "path";
+async function remember(workspaceRoot, runtime, text) {
+  const overlayPath = join11(workspaceRoot, ".agentwheel", "overlays", runtime, "instructions.local.md");
+  await mkdir5(dirname4(overlayPath), { recursive: true });
+  await appendFile(overlayPath, `${text.trim()}
+`, "utf8");
+  return { overlayPath };
+}
+async function ejectArtifact(workspaceRoot, item) {
+  const parsed = parseEjectItem(item);
+  const config = await readWorkspaceConfig(workspaceRoot);
+  const pkg = config.packages.find((candidate) => candidate.name === parsed.packageName);
+  if (!pkg) {
+    throw new Error(`Package not configured: ${parsed.packageName}`);
+  }
+  const driver = getSourceDriver(pkg.driver);
+  const adapter = pkg.adapterConfig ? await loadAdapterConfig(pkg.adapterConfig) : getAdapter(pkg.adapter);
+  const bundle = await stageSource(driver, pkg.source, {
+    adapter,
+    cacheRoot: join11(workspaceRoot, ".agentwheel", "cache"),
+    mode: pkg.mode
+  });
+  try {
+    const artifact = bundle.artifacts.find((candidate) => candidate.type === parsed.type && candidate.name === parsed.name);
+    if (!artifact) {
+      throw new Error(`Artifact not found: ${item}`);
+    }
+    const ejectedPath = join11(workspaceRoot, ".agentwheel", "ejected", ...parsed.packageName.split("/"), parsed.type, parsed.name);
+    await mkdir5(dirname4(ejectedPath), { recursive: true });
+    await rm5(ejectedPath, { recursive: true, force: true });
+    await cp4(artifact.stagedPath ?? artifact.sourcePath, ejectedPath, { recursive: artifact.kind === "dir", dereference: true });
+    return { ...parsed, ejectedPath };
+  } finally {
+    await rm5(bundle.root, { recursive: true, force: true });
+  }
+}
+function parseEjectItem(item) {
+  const parts = item.split("/").filter(Boolean);
+  if (parts.length < 3) {
+    throw new Error("Eject item must be <package>/<type>/<name>");
+  }
+  const name = parts.pop();
+  const type = artifactTypeSchema.parse(parts.pop());
+  const packageName = parts.join("/");
+  return { packageName, type, name };
+}
+
+// src/lifecycle/update.ts
+function shouldUpdatePackage(pkg, lock) {
+  if (!lock) {
+    return { shouldUpdate: true, reason: "no source lock" };
+  }
+  if (pkg.mode === "tracking") {
+    return { shouldUpdate: true, reason: "tracking source" };
+  }
+  if (lock.source !== pkg.source) {
+    return { shouldUpdate: true, reason: "pinned source changed" };
+  }
+  if (lock.requestedRef !== pkg.requestedRef) {
+    return { shouldUpdate: true, reason: "pinned ref changed" };
+  }
+  return { shouldUpdate: false, reason: "pinned source unchanged" };
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.2.0");
+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") {
+    await initPackage(root);
+    console.log("Initialized agentwheel package.");
+    return;
+  }
+  if (kind !== "workspace") {
+    throw new Error(`Unknown init kind: ${kind}`);
+  }
+  await writeWorkspaceConfig(root, await readWorkspaceConfig(root));
+  console.log("Initialized .agentwheel/config.json.");
+});
+program.command("add").argument("<source>", "package source").option("--driver <driver>", "source driver (local or git)").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--target-root <path>", "workspace root", process.cwd()).option("--mode <mode>", "pinned or tracking", "pinned").option("--name <name>", "package alias").action(async (source, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const driverName = options.driver ?? inferDriver(source);
+  const driver = getSourceDriver(driverName);
+  const adapter = options.adapterConfig ? await loadAdapterConfig(options.adapterConfig) : getAdapter(options.adapter);
+  const bundle = await stageSource(driver, source, {
+    workspaceRoot: targetRoot,
+    adapter,
+    cacheRoot: join12(targetRoot, ".agentwheel", "cache"),
+    mode: options.mode
+  });
+  const name = options.name ?? bundle.source.packageName ?? source;
+  const entry = {
+    name,
+    source,
+    driver: driverName,
+    adapter: adapter.name,
+    adapterConfig: options.adapterConfig,
+    mode: options.mode,
+    requestedRef: bundle.source.requestedRef
+  };
+  await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
+  await rm6(bundle.root, { recursive: true, force: true });
+  console.log(`Added ${name}.`);
+});
+program.command("list").argument("<source>", "local source directory").option("--driver <driver>", "source driver", "local").action(async (source, options) => {
+  const driver = getSourceDriver(options.driver);
+  const resolved = await driver.resolve(source);
+  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", "local").action(async (source, options) => {
+  const driver = getSourceDriver(options.driver);
+  const resolved = await driver.resolve(source);
+  const result = await driver.scan(resolved);
+  if (result.findings.length === 0) {
+    console.log("Scan ok: no findings");
+  } else {
+    for (const finding of result.findings) {
+      console.log(`${finding.level.toUpperCase()}: ${finding.message}${finding.path ? ` (${finding.path})` : ""}`);
+    }
+  }
+  if (!result.ok) process.exitCode = 1;
+});
+program.command("plan").argument("<source>", "source directory").option("--driver <driver>", "source driver", "local").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--target-root <path>", "runtime/project root", process.cwd()).option("--mode <mode>", "pinned or tracking").action(async (source, options) => {
+  const { plan, bundle } = await buildPlan(source, options);
+  console.log(formatPlan(plan));
+  await rm6(bundle.root, { recursive: true, force: true });
+  if (plan.hasBlockingChanges) process.exitCode = 1;
+});
+program.command("sync").argument("<source>", "source directory").option("--driver <driver>", "source driver", "local").option("--adapter <adapter>", "built-in adapter", "openclaw").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--target-root <path>", "runtime/project root", process.cwd()).option("--mode <mode>", "pinned or tracking").option("--dry-run", "show plan without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).action(async (source, options) => {
+  const { plan, bundle } = await buildPlan(source, options);
+  console.log(formatPlan(plan));
+  if (!options.dryRun) {
+    await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins });
+    console.log("Applied.");
+  }
+  await rm6(bundle.root, { recursive: true, force: true });
+  if (plan.hasBlockingChanges) process.exitCode = 1;
+});
+program.command("update").option("--target-root <path>", "workspace root", process.cwd()).option("--dry-run", "show plans without writing", false).option("--execute-plugins", "execute semantic plugin installs", false).action(async (options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const config = await readWorkspaceConfig(targetRoot);
+  if (config.packages.length === 0) {
+    console.log("No packages configured.");
+    return;
+  }
+  for (const pkg of config.packages) {
+    const adapter = pkg.adapterConfig ? await loadAdapterConfig(pkg.adapterConfig) : getAdapter(pkg.adapter);
+    const lock = await readSourceLock(targetRoot, adapter.name);
+    const decision = shouldUpdatePackage(pkg, lock);
+    if (!decision.shouldUpdate) {
+      console.log(`Skipping ${pkg.name}: ${decision.reason}.`);
+      continue;
+    }
+    const { plan, bundle } = await buildPlan(pkg.source, {
+      driver: pkg.driver,
+      adapter: pkg.adapter,
+      adapterConfig: pkg.adapterConfig,
+      targetRoot,
+      mode: pkg.mode
+    });
+    console.log(`Update ${pkg.name}:`);
+    console.log(formatPlan(plan));
+    if (!options.dryRun) {
+      await applyInstallPlan(plan, bundle.sourceLock, { executePlugins: options.executePlugins });
+      console.log(`Applied ${pkg.name}.`);
+    }
+    await rm6(bundle.root, { recursive: true, force: true });
+    if (plan.hasBlockingChanges) process.exitCode = 1;
+  }
+});
+program.command("remember").requiredOption("--runtime <runtime>", "runtime/adapter name").option("--target-root <path>", "workspace root", process.cwd()).argument("<text>", "text to append to the local instructions overlay").action(async (text, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const result = await remember(targetRoot, options.runtime, text);
+  console.log(`Remembered in ${result.overlayPath}. Run: agentwheel sync <source> --adapter ${options.runtime}`);
+});
+program.command("eject").argument("<item>", "package/type/name").option("--target-root <path>", "workspace root", process.cwd()).action(async (item, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const result = await ejectArtifact(targetRoot, item);
+  console.log(`Ejected ${item} to ${result.ejectedPath}.`);
+});
+program.command("uninstall").option("--adapter <adapter>", "adapter", "openclaw").option("--target-root <path>", "runtime/project root", process.cwd()).option("--dry-run", "show removals without writing", false).action(async (options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const manifest = await readInstallManifest(targetRoot, options.adapter);
+  if (!manifest) {
+    console.log(`No install manifest for ${options.adapter} at ${targetRoot}`);
+    return;
+  }
+  const plan = await createUninstallPlan(manifest);
+  console.log(formatPlan(plan));
+  await uninstall(plan, options.dryRun);
+  if (!options.dryRun) console.log("Uninstalled.");
+  if (plan.hasBlockingChanges) process.exitCode = 1;
+});
+async function buildPlan(source, options) {
+  const driver = getSourceDriver(options.driver ?? inferDriver(source));
+  const adapter = options.adapterConfig ? await loadAdapterConfig(options.adapterConfig) : getAdapter(options.adapter);
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const bundle = await stageSource(driver, source, {
+    workspaceRoot: targetRoot,
+    adapter,
+    cacheRoot: join12(targetRoot, ".agentwheel", "cache"),
+    mode: options.mode
+  });
+  const manifest = await readInstallManifest(targetRoot, adapter.name);
+  const plan = await createInstallPlan(bundle, adapter, targetRoot, manifest);
+  return { plan, bundle };
+}
+async function initPackage(root) {
+  await mkdir6(join12(root, "instructions"), { recursive: true });
+  await mkdir6(join12(root, "rules"), { recursive: true });
+  await mkdir6(join12(root, "skills"), { recursive: true });
+  const manifestPath = join12(root, "agentwheel.json");
+  const manifest = {
+    schemaVersion: 1,
+    name: "example/agentwheel-package",
+    version: "0.1.0",
+    provides: [
+      { type: "instructions", path: "instructions/AGENTS.md" },
+      { type: "rules", path: "rules" },
+      { type: "skills", path: "skills" }
+    ]
+  };
+  await writeFile3(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  await writeFile3(join12(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+}
+function inferDriver(source) {
+  return source.startsWith("github:") || source.startsWith("git:") ? "git" : "local";
+}
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});