agentwheel 0.4.1 → 0.5.0

package/README.md

@@ -33,9 +33,9 @@ No lock-in. No central gatekeeper. Your packages live in plain git repos, your c
 
 ---
 
-> **Status: early (v0.4).** The lifecycle core is real and tested — local/git/skillkit/vercel
+> **Status: early (v0.5).** The lifecycle core is real and tested — local/git/skillkit/vercel
 > sources, optional registry discovery, plan/sync/update/drift/uninstall, overlays, eject/remember,
-> profiles, runtime auto-detection, fleet targeting, rich JSON merge, and pluggable adapters.
+> profiles, runtime auto-detection, fleet targeting, asset-includes, rich JSON merge, and pluggable adapters.
 > Expect sharp edges.
 
 ## What it does
@@ -147,6 +147,28 @@ A package is a git repo (or folder) with a JSON manifest and a canonical layout:
 }
 ```
 
+Packages can compose shared files into each directory artifact at staging time. This keeps one
+canonical copy in the package repo while installing self-contained skills:
+
+```jsonc
+{
+  "type": "skills",
+  "path": "skills",
+  "assets": [
+    {
+      "from": "packages/tmux-bridge/bin",
+      "into": "bin",
+      "include": ["*.sh"],
+      "mode": "preserve"
+    }
+  ]
+}
+```
+
+`mode: "preserve"` keeps executable bits on copied scripts. The composed files are included in
+the skill directory hash, so idempotency and drift detection work as if the assets had always
+belonged to the skill.
+
 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.
 
@@ -221,6 +243,7 @@ clear conversion format.
 - [x] **v0.2** — git source driver; `update` (pinned & tracking); overlays/additive/override/eject; `init`; hermes + copilot adapters; commands/mcp/hooks artifacts; OpenClaw semantic plugin planning.
 - [x] **v0.3** — skillkit/vercel source drivers; optional registry & federation; programmatic adapters behind `--allow-adapter-code`; rich JSON merge for mcp/hooks/settings; profiles.
 - [x] **v0.4** — runtime auto-detection; no `--target-root` needed for normal use; fleet config with named agents; global + project config merge; `--agent` and `--all`.
+- [x] **v0.5** — asset-includes compose shared files into skills at install time; executable bits preserved; hashes include composed assets.
 
 ## Design docs
 

package/dist/index.js

@@ -34,6 +34,12 @@ var artifactTypeSchema = z.enum([
   "plugins"
 ]);
 var fileKindSchema = z.enum(["file", "dir"]);
+var packageAssetSchema = z.object({
+  from: z.string().min(1),
+  into: z.string().min(1),
+  include: z.array(z.string().min(1)).optional(),
+  mode: z.enum(["preserve", "copy"]).default("preserve")
+});
 var artifactSchema = z.object({
   type: artifactTypeSchema,
   name: z.string().min(1),
@@ -43,7 +49,8 @@ var artifactSchema = z.object({
   kind: fileKindSchema,
   hash: z.string().min(16),
   packageName: z.string().min(1).optional(),
-  channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed")
+  channel: z.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
+  assets: z.array(packageAssetSchema).optional()
 });
 
 // src/model/adapter.ts
@@ -804,7 +811,8 @@ import { parse as parse2, printParseErrorCode as printParseErrorCode2 } from "js
 import { z as z4 } from "zod";
 var packageProvideSchema = z4.object({
   type: artifactTypeSchema,
-  path: z4.string().min(1)
+  path: z4.string().min(1),
+  assets: z4.array(packageAssetSchema).optional()
 });
 var packageManifestSchema = z4.object({
   schemaVersion: z4.literal(1),
@@ -973,7 +981,7 @@ async function listFromManifest(root, packageName) {
     const stats = await stat2(full);
     if (provide.type === "instructions") {
       if (stats.isFile()) {
-        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName));
+        artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets));
       }
       continue;
     }
@@ -981,16 +989,16 @@ async function listFromManifest(root, packageName) {
       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));
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets));
         } else if (provide.type === "plugins" && entry.isDirectory()) {
-          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName));
+          artifacts.push(await artifactForDir(provide.type, entry.name, child, join6(provide.path, entry.name), packageName, provide.assets));
         } 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));
+          artifacts.push(await artifactForFile(provide.type, name, child, join6(provide.path, entry.name), packageName, provide.assets));
         }
       }
     } else if (stats.isFile()) {
-      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName));
+      artifacts.push(await artifactForFile(provide.type, basename(full), full, provide.path, packageName, provide.assets));
     }
   }
   return artifacts;
@@ -1007,7 +1015,7 @@ async function listGenericArtifacts(type, dir, relativeRoot, packageName) {
   }
   return artifacts;
 }
-async function artifactForFile(type, name, sourcePath, relativePath, packageName) {
+async function artifactForFile(type, name, sourcePath, relativePath, packageName, assets) {
   return {
     type,
     name,
@@ -1016,10 +1024,11 @@ async function artifactForFile(type, name, sourcePath, relativePath, packageName
     kind: "file",
     hash: await hashPath(sourcePath),
     packageName,
-    channel: "managed"
+    channel: "managed",
+    assets
   };
 }
-async function artifactForDir(type, name, sourcePath, relativePath, packageName) {
+async function artifactForDir(type, name, sourcePath, relativePath, packageName, assets) {
   return {
     type,
     name,
@@ -1028,7 +1037,8 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName)
     kind: "dir",
     hash: await hashPath(sourcePath),
     packageName,
-    channel: "managed"
+    channel: "managed",
+    assets
   };
 }
 
@@ -1463,8 +1473,8 @@ function getSourceDriver(name = "local") {
 }
 
 // src/staging/staging.ts
-import { cp as cp3, mkdir as mkdir5, mkdtemp } from "fs/promises";
-import { dirname as dirname5, join as join12 } from "path";
+import { chmod, cp as cp3, mkdir as mkdir5, mkdtemp, readdir as readdir4, stat as stat6 } from "fs/promises";
+import { basename as basename7, dirname as dirname5, join as join12, relative as relative2, resolve as resolve8, sep } from "path";
 import { tmpdir as tmpdir2 } from "os";
 
 // src/staging/customize.ts
@@ -1583,6 +1593,7 @@ async function stageSource(driver, source, options = {}) {
     const stagedPath = join12(root, artifact.relativePath);
     await mkdir5(dirname5(stagedPath), { recursive: true });
     await cp3(artifact.sourcePath, stagedPath, { recursive: artifact.kind === "dir", dereference: true });
+    await composeAssets(artifact, resolved.resolvedPath, stagedPath);
     stagedArtifacts.push({
       ...artifact,
       stagedPath,
@@ -1623,11 +1634,93 @@ async function stageSource(driver, source, options = {}) {
     }
   };
 }
+async function composeAssets(artifact, packageRoot, stagedPath) {
+  if (!artifact.assets?.length) return;
+  if (artifact.kind !== "dir") {
+    throw new Error(`Asset includes require a directory artifact: ${artifact.type}/${artifact.name}`);
+  }
+  for (const asset of artifact.assets) {
+    const source = resolvePackagePath(packageRoot, asset.from);
+    const dest = join12(stagedPath, asset.into);
+    await copyAsset(asset, source, dest);
+  }
+}
+async function copyAsset(asset, source, dest) {
+  const sourceStats = await stat6(source);
+  if (sourceStats.isFile()) {
+    if (matchesAny(basename7(source), asset.include)) {
+      await mkdir5(dest, { recursive: true });
+      await copyAssetFile(source, join12(dest, basename7(source)), asset);
+    }
+    return;
+  }
+  if (!sourceStats.isDirectory()) {
+    throw new Error(`Asset include source is not a file or directory: ${source}`);
+  }
+  if (!asset.include?.length) {
+    await mkdir5(dirname5(dest), { recursive: true });
+    await cp3(source, dest, { recursive: true, dereference: true });
+    if (asset.mode === "copy") await normalizeCopiedModes(dest);
+    return;
+  }
+  for (const file of await listFiles(source)) {
+    const rel = relative2(source, file).replaceAll("\\", "/");
+    if (!matchesAny(rel, asset.include) && !matchesAny(basename7(file), asset.include)) continue;
+    await copyAssetFile(file, join12(dest, rel), asset);
+  }
+}
+async function copyAssetFile(source, dest, asset) {
+  await mkdir5(dirname5(dest), { recursive: true });
+  await cp3(source, dest, { dereference: true });
+  if (asset.mode === "copy") await chmod(dest, 420);
+}
+function resolvePackagePath(packageRoot, path) {
+  const resolved = resolve8(packageRoot, path);
+  const root = resolve8(packageRoot);
+  if (resolved !== root && !resolved.startsWith(`${root}${sep}`)) {
+    throw new Error(`Asset include escapes package root: ${path}`);
+  }
+  return resolved;
+}
+async function listFiles(root) {
+  const out = [];
+  async function walk2(dir) {
+    for (const entry of (await readdir4(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join12(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk2(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await walk2(root);
+  return out;
+}
+async function normalizeCopiedModes(path) {
+  const stats = await stat6(path);
+  if (stats.isFile()) {
+    await chmod(path, 420);
+    return;
+  }
+  if (!stats.isDirectory()) return;
+  for (const entry of await readdir4(path, { withFileTypes: true })) {
+    await normalizeCopiedModes(join12(path, entry.name));
+  }
+}
+function matchesAny(path, patterns) {
+  if (!patterns?.length) return true;
+  return patterns.some((pattern) => matchesGlob(path, pattern));
+}
+function matchesGlob(path, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`).test(path);
+}
 
 // src/model/workspace.ts
 import { readFile as readFile8 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname6, join as join13, resolve as resolve8 } from "path";
+import { dirname as dirname6, join as join13, resolve as resolve9 } from "path";
 import { z as z5 } from "zod";
 var workspacePackageSchema = z5.object({
   name: z5.string().min(1),
@@ -1687,11 +1780,11 @@ function globalWorkspaceConfigPath(globalRoot = homedir3()) {
   return join13(globalRoot, ".agentwheel", "config.json");
 }
 async function findWorkspaceRoot(start = process.cwd()) {
-  let current = resolve8(start);
+  let current = resolve9(start);
   while (true) {
     if (await pathExists(workspaceConfigPath(current))) return current;
     const parent = dirname6(current);
-    if (parent === current) return resolve8(start);
+    if (parent === current) return resolve9(start);
     current = parent;
   }
 }
@@ -1715,9 +1808,9 @@ function mergeWorkspaceConfig(global, project) {
   });
 }
 function resolveConfigPath(path, baseRoot) {
-  if (path.startsWith("~/")) return resolve8(homedir3(), path.slice(2));
+  if (path.startsWith("~/")) return resolve9(homedir3(), path.slice(2));
   if (path === "~") return homedir3();
-  return path.startsWith("/") ? resolve8(path) : resolve8(baseRoot, path);
+  return path.startsWith("/") ? resolve9(path) : resolve9(baseRoot, path);
 }
 function emptyWorkspaceConfig() {
   return { schemaVersion: 1, packages: [], registry: {}, profiles: {}, agents: {} };
@@ -1781,9 +1874,9 @@ import { rm as rm7 } from "fs/promises";
 import { join as join16 } from "path";
 
 // src/registry/client.ts
-import { readFile as readFile9, rm as rm6, stat as stat6 } from "fs/promises";
+import { readFile as readFile9, rm as rm6, stat as stat7 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname8, join as join15, resolve as resolve9 } from "path";
+import { dirname as dirname8, join as join15, resolve as resolve10 } from "path";
 import { fileURLToPath } from "url";
 
 // src/model/registry.ts
@@ -1886,8 +1979,8 @@ var RegistryClient = class {
     }
     const filePath = source.startsWith("file:") ? fileURLToPath(source) : source;
     if (await pathExists(filePath)) {
-      const fullPath = resolve9(filePath);
-      const stats = await stat6(fullPath);
+      const fullPath = resolve10(filePath);
+      const stats = await stat7(fullPath);
       return readFile9(stats.isDirectory() ? join15(fullPath, "index.json") : fullPath, "utf8");
     }
     const resolved = await this.git.fetch(await this.git.resolve(source, { cacheRoot: join15(dirname8(this.cachePath), "registry-repos") }));
@@ -2021,7 +2114,7 @@ function shouldUpdatePackage(pkg, lock) {
 }
 
 // src/runtime/target.ts
-import { basename as basename7, dirname as dirname9, join as join18, resolve as resolve10 } from "path";
+import { basename as basename8, dirname as dirname9, join as join18, resolve as resolve11 } from "path";
 var runtimeMarkers = [
   { adapter: "openclaw", dirs: [".openclaw", ".clawdbot", ".moltbot"] },
   { adapter: "claude", dirs: [".claude"] },
@@ -2030,9 +2123,9 @@ var runtimeMarkers = [
   { adapter: "copilot", dirs: [".github"] }
 ];
 async function resolveRuntimeTarget(request = {}) {
-  const cwd = resolve10(request.cwd ?? process.cwd());
+  const cwd = resolve11(request.cwd ?? process.cwd());
   if (request.targetRoot) {
-    const targetRoot = resolve10(request.targetRoot);
+    const targetRoot = resolve11(request.targetRoot);
     return {
       adapter: request.adapter ?? "openclaw",
       targetRoot,
@@ -2059,7 +2152,7 @@ async function resolveRuntimeTarget(request = {}) {
 async function resolveAllRuntimeTargets(request = {}) {
   if (request.targetRoot) return [await resolveRuntimeTarget(request)];
   if (request.agent) return [await resolveRuntimeTarget(request)];
-  const cwd = resolve10(request.cwd ?? process.cwd());
+  const cwd = resolve11(request.cwd ?? process.cwd());
   const workspaceRoot = await findWorkspaceRoot(cwd);
   const config = await readMergedWorkspaceConfig(workspaceRoot, { globalRoot: request.globalRoot });
   const targets = Object.entries(config.agents).map(([name]) => targetFromAgent(name, config, workspaceRoot));
@@ -2069,12 +2162,12 @@ async function resolveAllRuntimeTargets(request = {}) {
   return targets;
 }
 async function detectRuntimeTarget(cwd = process.cwd(), adapterFilter) {
-  const root = resolve10(cwd);
+  const root = resolve11(cwd);
   const matches = [];
   for (const marker of runtimeMarkers) {
     if (adapterFilter && marker.adapter !== adapterFilter) continue;
     for (const dir of marker.dirs) {
-      if (basename7(root) === dir) {
+      if (basename8(root) === dir) {
         matches.push({ adapter: marker.adapter, targetRoot: dirname9(root) });
       } else if (await pathExists(join18(root, dir))) {
         matches.push({ adapter: marker.adapter, targetRoot: root });
@@ -2110,7 +2203,7 @@ function dedupeTargets(matches) {
 
 // src/cli/index.ts
 var program = new Command();
-program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.4.1");
+program.name("agentwheel").description("Multi-runtime agent artifact orchestrator").version("0.5.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") {

package/package.json

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