allagents 0.2.2 → 0.3.0

package/README.md

@@ -130,9 +130,21 @@ allagents plugin validate <path>
 
 ## .allagents/workspace.yaml
 
-The workspace configuration file lives in `.allagents/workspace.yaml` and defines repositories, plugins, and target clients:
+The workspace configuration file lives in `.allagents/workspace.yaml` and defines repositories, plugins, workspace files, and target clients:
 
 ```yaml
+# Workspace file sync (optional) - copy files from a shared source
+workspace:
+  source: ../shared-config              # Default base for relative paths
+  files:
+    - AGENTS.md                         # String shorthand: same source and dest
+    - source: docs/guide.md             # Object form: explicit source
+      dest: GUIDE.md                    # Optional dest (defaults to basename)
+    - dest: CUSTOM.md                   # File-level source override
+      source: ../other-config/CUSTOM.md
+    - dest: AGENTS.md                   # GitHub source
+      source: owner/repo/path/AGENTS.md
+
 repositories:
   - path: ../my-project
     owner: myorg
@@ -154,6 +166,25 @@ clients:
   - cursor
 ```
 
+### Workspace File Sync
+
+The `workspace:` section enables syncing files from external sources to your workspace root. This is useful for sharing agent configurations (AGENTS.md, CLAUDE.md) across multiple projects.
+
+**Key behaviors:**
+- **Source of truth is remote** - Local copies are overwritten on every sync
+- **Deleted files are restored** - If you delete AGENTS.md locally, sync restores it
+- **WORKSPACE-RULES injection** - AGENTS.md and CLAUDE.md automatically get workspace discovery rules injected
+
+**Source resolution:**
+| Format | Example | Resolves to |
+|--------|---------|-------------|
+| String shorthand | `AGENTS.md` | `{workspace.source}/AGENTS.md` |
+| Relative source | `source: docs/guide.md` | `{workspace.source}/docs/guide.md` |
+| File-level override | `source: ../other/file.md` | `../other/file.md` (relative to workspace) |
+| GitHub source | `source: owner/repo/path/file.md` | Fetched from GitHub cache |
+
+**GitHub sources** are fetched fresh on every sync (always pulls latest).
+
 ### Plugin Spec Format
 
 Plugins use the `plugin@marketplace` format:

package/dist/index.js

@@ -17720,12 +17720,12 @@ var RepositorySchema = exports_external.object({
 var WorkspaceFileSchema = exports_external.union([
   exports_external.string(),
   exports_external.object({
-    source: exports_external.string(),
+    source: exports_external.string().optional(),
     dest: exports_external.string().optional()
   })
 ]);
 var WorkspaceSchema = exports_external.object({
-  source: exports_external.string(),
+  source: exports_external.string().optional(),
   files: exports_external.array(WorkspaceFileSchema)
 });
 var PluginSourceSchema = exports_external.string();
@@ -19431,6 +19431,31 @@ function validatePluginSource(source) {
   }
   return { valid: true };
 }
+function parseFileSource(source, baseDir = process.cwd()) {
+  if (isGitHubUrl(source)) {
+    const parsed = parseGitHubUrl(source);
+    if (parsed) {
+      return {
+        type: "github",
+        original: source,
+        normalized: source,
+        owner: parsed.owner,
+        repo: parsed.repo,
+        ...parsed.subpath && { filePath: parsed.subpath }
+      };
+    }
+    return {
+      type: "local",
+      original: source,
+      normalized: normalizePluginPath(source, baseDir)
+    };
+  }
+  return {
+    type: "local",
+    original: source,
+    normalized: normalizePluginPath(source, baseDir)
+  };
+}
 async function verifyGitHubUrlExists(source) {
   const parsed = parseGitHubUrl(source);
   if (!parsed) {
@@ -19943,8 +19968,56 @@ async function copyPluginToWorkspace(pluginPath, workspacePath, client, options2
   ]);
   return [...commandResults, ...skillResults, ...hookResults, ...agentResults];
 }
+function isExplicitGitHubSource(source) {
+  if (source.startsWith("https://github.com/") || source.startsWith("http://github.com/") || source.startsWith("github.com/") || source.startsWith("gh:")) {
+    return true;
+  }
+  if (!source.startsWith(".") && !source.startsWith("/") && source.includes("/")) {
+    const parts = source.split("/");
+    if (parts.length >= 3) {
+      const validOwnerRepo = /^[a-zA-Z0-9_.-]+$/;
+      if (parts[0] && parts[1] && validOwnerRepo.test(parts[0]) && validOwnerRepo.test(parts[1])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function resolveFileSourcePath(source, defaultSourcePath, githubCache) {
+  if (!isExplicitGitHubSource(source)) {
+    if (source.startsWith("/")) {
+      return { path: source };
+    }
+    if (source.startsWith("../")) {
+      return { path: join4(process.cwd(), source) };
+    }
+    if (defaultSourcePath) {
+      return { path: join4(defaultSourcePath, source) };
+    }
+    return { path: join4(process.cwd(), source) };
+  }
+  const parsed = parseFileSource(source);
+  if (parsed.type === "github" && parsed.owner && parsed.repo && parsed.filePath) {
+    const cacheKey = `${parsed.owner}/${parsed.repo}`;
+    const cachePath = githubCache?.get(cacheKey);
+    if (!cachePath) {
+      return {
+        path: "",
+        error: `GitHub cache not found for ${cacheKey}. Ensure the repo is fetched.`
+      };
+    }
+    return { path: join4(cachePath, parsed.filePath) };
+  }
+  if (parsed.type === "github") {
+    return {
+      path: "",
+      error: `Invalid GitHub file source: ${source}. Must include path to file (e.g., owner/repo/path/to/file.md)`
+    };
+  }
+  return null;
+}
 async function copyWorkspaceFiles(sourcePath, workspacePath, files, options2 = {}) {
-  const { dryRun = false } = options2;
+  const { dryRun = false, githubCache } = options2;
   const results = [];
   const stringPatterns = [];
   const objectEntries = [];
@@ -19953,55 +20026,113 @@ async function copyWorkspaceFiles(sourcePath, workspacePath, files, options2 = {
     if (typeof file === "string") {
       stringPatterns.push(file);
     } else {
-      objectEntries.push({ source: file.source, dest: file.dest });
+      let dest = file.dest;
+      if (!dest && file.source) {
+        const parts = file.source.split("/");
+        dest = parts[parts.length - 1] || file.source;
+      }
+      if (!dest) {
+        results.push({
+          source: "unknown",
+          destination: join4(workspacePath, "unknown"),
+          action: "failed",
+          error: "File entry must have at least source or dest specified"
+        });
+        continue;
+      }
+      objectEntries.push(file.source ? { source: file.source, dest } : { dest });
     }
   }
   if (stringPatterns.length > 0) {
-    const resolvedFiles = await resolveGlobPatterns(sourcePath, stringPatterns);
-    for (const resolved of resolvedFiles) {
-      const destPath = join4(workspacePath, resolved.relativePath);
-      if (!existsSync3(resolved.sourcePath)) {
-        const wasLiteral = stringPatterns.some((p) => !isGlobPattern(p) && !p.startsWith("!") && p === resolved.relativePath);
-        if (wasLiteral) {
+    if (!sourcePath) {
+      for (const pattern of stringPatterns) {
+        if (!isGlobPattern(pattern) && !pattern.startsWith("!")) {
+          results.push({
+            source: pattern,
+            destination: join4(workspacePath, pattern),
+            action: "failed",
+            error: `Cannot resolve file '${pattern}' - no workspace.source configured and no explicit source provided`
+          });
+        }
+      }
+    } else {
+      const resolvedFiles = await resolveGlobPatterns(sourcePath, stringPatterns);
+      for (const resolved of resolvedFiles) {
+        const destPath = join4(workspacePath, resolved.relativePath);
+        if (!existsSync3(resolved.sourcePath)) {
+          const wasLiteral = stringPatterns.some((p) => !isGlobPattern(p) && !p.startsWith("!") && p === resolved.relativePath);
+          if (wasLiteral) {
+            results.push({
+              source: resolved.sourcePath,
+              destination: destPath,
+              action: "failed",
+              error: `Source file not found: ${resolved.sourcePath}`
+            });
+          }
+          continue;
+        }
+        if (dryRun) {
+          results.push({ source: resolved.sourcePath, destination: destPath, action: "copied" });
+          if (AGENT_FILES2.includes(resolved.relativePath)) {
+            copiedAgentFiles.push(resolved.relativePath);
+          }
+          continue;
+        }
+        try {
+          await mkdir2(dirname2(destPath), { recursive: true });
+          const content = await readFile3(resolved.sourcePath, "utf-8");
+          await writeFile(destPath, content, "utf-8");
+          results.push({ source: resolved.sourcePath, destination: destPath, action: "copied" });
+          if (AGENT_FILES2.includes(resolved.relativePath)) {
+            copiedAgentFiles.push(resolved.relativePath);
+          }
+        } catch (error) {
           results.push({
             source: resolved.sourcePath,
             destination: destPath,
             action: "failed",
-            error: `Source file not found: ${resolved.sourcePath}`
+            error: error instanceof Error ? error.message : "Unknown error"
           });
         }
+      }
+    }
+  }
+  for (const entry of objectEntries) {
+    const destPath = join4(workspacePath, entry.dest);
+    let srcPath;
+    if (entry.source) {
+      const resolved = resolveFileSourcePath(entry.source, sourcePath, githubCache);
+      if (!resolved) {
+        results.push({
+          source: entry.source,
+          destination: destPath,
+          action: "failed",
+          error: `Failed to resolve source: ${entry.source}`
+        });
         continue;
       }
-      if (dryRun) {
-        results.push({ source: resolved.sourcePath, destination: destPath, action: "copied" });
-        if (AGENT_FILES2.includes(resolved.relativePath)) {
-          copiedAgentFiles.push(resolved.relativePath);
-        }
+      if (resolved.error) {
+        results.push({
+          source: entry.source,
+          destination: destPath,
+          action: "failed",
+          error: resolved.error
+        });
         continue;
       }
-      try {
-        await mkdir2(dirname2(destPath), { recursive: true });
-        const content = await readFile3(resolved.sourcePath, "utf-8");
-        await writeFile(destPath, content, "utf-8");
-        results.push({ source: resolved.sourcePath, destination: destPath, action: "copied" });
-        if (AGENT_FILES2.includes(resolved.relativePath)) {
-          copiedAgentFiles.push(resolved.relativePath);
-        }
-      } catch (error) {
+      srcPath = resolved.path;
+    } else {
+      if (!sourcePath) {
         results.push({
-          source: resolved.sourcePath,
+          source: entry.dest,
           destination: destPath,
           action: "failed",
-          error: error instanceof Error ? error.message : "Unknown error"
+          error: `Cannot resolve file '${entry.dest}' - no workspace.source configured and no explicit source provided`
         });
+        continue;
       }
+      srcPath = join4(sourcePath, entry.dest);
     }
-  }
-  for (const entry of objectEntries) {
-    const srcPath = join4(sourcePath, entry.source);
-    const basename = entry.source.split("/").pop() || entry.source;
-    const destFilename = entry.dest ?? basename;
-    const destPath = join4(workspacePath, destFilename);
     if (!existsSync3(srcPath)) {
       results.push({
         source: srcPath,
@@ -20013,8 +20144,8 @@ async function copyWorkspaceFiles(sourcePath, workspacePath, files, options2 = {
     }
     if (dryRun) {
       results.push({ source: srcPath, destination: destPath, action: "copied" });
-      if (AGENT_FILES2.includes(destFilename)) {
-        copiedAgentFiles.push(destFilename);
+      if (AGENT_FILES2.includes(entry.dest)) {
+        copiedAgentFiles.push(entry.dest);
       }
       continue;
     }
@@ -20023,8 +20154,8 @@ async function copyWorkspaceFiles(sourcePath, workspacePath, files, options2 = {
       const content = await readFile3(srcPath, "utf-8");
       await writeFile(destPath, content, "utf-8");
       results.push({ source: srcPath, destination: destPath, action: "copied" });
-      if (AGENT_FILES2.includes(destFilename)) {
-        copiedAgentFiles.push(destFilename);
+      if (AGENT_FILES2.includes(entry.dest)) {
+        copiedAgentFiles.push(entry.dest);
       }
     } catch (error) {
       results.push({
@@ -20451,6 +20582,130 @@ async function cleanupEmptyParents(workspacePath, filePath) {
     }
   }
 }
+function isExplicitGitHubSourceForCollection(source) {
+  if (source.startsWith("https://github.com/") || source.startsWith("http://github.com/") || source.startsWith("github.com/") || source.startsWith("gh:")) {
+    return true;
+  }
+  if (!source.startsWith(".") && !source.startsWith("/") && source.includes("/")) {
+    const parts = source.split("/");
+    if (parts.length >= 3) {
+      const validOwnerRepo = /^[a-zA-Z0-9_.-]+$/;
+      if (parts[0] && parts[1] && validOwnerRepo.test(parts[0]) && validOwnerRepo.test(parts[1])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function collectGitHubReposFromFiles(files) {
+  const repos = new Map;
+  for (const file of files) {
+    if (typeof file === "string") {
+      continue;
+    }
+    if (file.source && isExplicitGitHubSourceForCollection(file.source)) {
+      const parsed = parseFileSource(file.source);
+      if (parsed.type === "github" && parsed.owner && parsed.repo) {
+        const key = `${parsed.owner}/${parsed.repo}`;
+        if (!repos.has(key)) {
+          repos.set(key, {
+            owner: parsed.owner,
+            repo: parsed.repo,
+            key
+          });
+        }
+      }
+    }
+  }
+  return Array.from(repos.values());
+}
+async function fetchFileSourceRepos(repos, _force) {
+  const cache = new Map;
+  const errors2 = [];
+  for (const repo of repos) {
+    const result = await fetchPlugin(`${repo.owner}/${repo.repo}`, { force: true });
+    if (result.success) {
+      cache.set(repo.key, result.cachePath);
+    } else {
+      errors2.push(`Failed to fetch ${repo.key}: ${result.error || "Unknown error"}`);
+    }
+  }
+  return { cache, errors: errors2 };
+}
+function isExplicitGitHubSourceForValidation(source) {
+  if (source.startsWith("https://github.com/") || source.startsWith("http://github.com/") || source.startsWith("github.com/") || source.startsWith("gh:")) {
+    return true;
+  }
+  if (!source.startsWith(".") && !source.startsWith("/") && source.includes("/")) {
+    const parts = source.split("/");
+    if (parts.length >= 3) {
+      const validOwnerRepo = /^[a-zA-Z0-9_.-]+$/;
+      if (parts[0] && parts[1] && validOwnerRepo.test(parts[0]) && validOwnerRepo.test(parts[1])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function validateFileSources(files, defaultSourcePath, githubCache) {
+  const errors2 = [];
+  for (const file of files) {
+    if (typeof file === "string") {
+      if (!defaultSourcePath) {
+        errors2.push(`Cannot resolve file '${file}' - no workspace.source configured`);
+        continue;
+      }
+      const fullPath = join7(defaultSourcePath, file);
+      if (!existsSync6(fullPath)) {
+        errors2.push(`File source not found: ${fullPath}`);
+      }
+      continue;
+    }
+    if (file.source) {
+      if (isExplicitGitHubSourceForValidation(file.source)) {
+        const parsed = parseFileSource(file.source);
+        if (!parsed.owner || !parsed.repo || !parsed.filePath) {
+          errors2.push(`Invalid GitHub file source: ${file.source}. Must include path to file.`);
+          continue;
+        }
+        const cacheKey = `${parsed.owner}/${parsed.repo}`;
+        const cachePath = githubCache.get(cacheKey);
+        if (!cachePath) {
+          errors2.push(`GitHub cache not found for ${cacheKey}`);
+          continue;
+        }
+        const fullPath = join7(cachePath, parsed.filePath);
+        if (!existsSync6(fullPath)) {
+          errors2.push(`Path not found in repository: ${cacheKey}/${parsed.filePath}`);
+        }
+      } else {
+        let fullPath;
+        if (file.source.startsWith("/")) {
+          fullPath = file.source;
+        } else if (file.source.startsWith("../")) {
+          fullPath = resolve4(file.source);
+        } else if (defaultSourcePath) {
+          fullPath = join7(defaultSourcePath, file.source);
+        } else {
+          fullPath = resolve4(file.source);
+        }
+        if (!existsSync6(fullPath)) {
+          errors2.push(`File source not found: ${fullPath}`);
+        }
+      }
+    } else {
+      if (!defaultSourcePath) {
+        errors2.push(`Cannot resolve file '${file.dest}' - no workspace.source configured and no explicit source provided`);
+        continue;
+      }
+      const fullPath = join7(defaultSourcePath, file.dest ?? "");
+      if (!existsSync6(fullPath)) {
+        errors2.push(`File source not found: ${fullPath}`);
+      }
+    }
+  }
+  return errors2;
+}
 function collectSyncedPaths(copyResults, workspacePath, clients) {
   const result = {};
   for (const client of clients) {
@@ -20623,17 +20878,52 @@ ${errors2}`
   }
   const pluginResults = await Promise.all(validatedPlugins.map((validatedPlugin) => copyValidatedPlugin(validatedPlugin, workspacePath, config.clients, dryRun)));
   let workspaceFileResults = [];
-  if (config.workspace && validatedWorkspaceSource) {
-    const sourcePath = validatedWorkspaceSource.resolved;
+  if (config.workspace) {
+    const sourcePath = validatedWorkspaceSource?.resolved;
     const filesToCopy = [...config.workspace.files];
-    for (const agentFile of AGENT_FILES) {
-      const agentPath = join7(sourcePath, agentFile);
-      if (existsSync6(agentPath) && !filesToCopy.includes(agentFile)) {
-        filesToCopy.push(agentFile);
+    if (sourcePath) {
+      for (const agentFile of AGENT_FILES) {
+        const agentPath = join7(sourcePath, agentFile);
+        if (existsSync6(agentPath) && !filesToCopy.includes(agentFile)) {
+          filesToCopy.push(agentFile);
+        }
       }
     }
-    workspaceFileResults = await copyWorkspaceFiles(sourcePath, workspacePath, filesToCopy, { dryRun });
-    if (!dryRun && config.clients.includes("claude")) {
+    const fileSourceRepos = collectGitHubReposFromFiles(filesToCopy);
+    let githubCache = new Map;
+    if (fileSourceRepos.length > 0) {
+      const { cache, errors: errors2 } = await fetchFileSourceRepos(fileSourceRepos, force);
+      if (errors2.length > 0) {
+        return {
+          success: false,
+          pluginResults,
+          totalCopied: 0,
+          totalFailed: errors2.length,
+          totalSkipped: 0,
+          totalGenerated: 0,
+          error: `File source fetch failed (workspace unchanged):
+${errors2.map((e) => `  - ${e}`).join(`
+`)}`
+        };
+      }
+      githubCache = cache;
+    }
+    const fileValidationErrors = validateFileSources(filesToCopy, sourcePath, githubCache);
+    if (fileValidationErrors.length > 0) {
+      return {
+        success: false,
+        pluginResults,
+        totalCopied: 0,
+        totalFailed: fileValidationErrors.length,
+        totalSkipped: 0,
+        totalGenerated: 0,
+        error: `File source validation failed (workspace unchanged):
+${fileValidationErrors.map((e) => `  - ${e}`).join(`
+`)}`
+      };
+    }
+    workspaceFileResults = await copyWorkspaceFiles(sourcePath, workspacePath, filesToCopy, { dryRun, githubCache });
+    if (!dryRun && config.clients.includes("claude") && sourcePath) {
       const claudePath = join7(workspacePath, "CLAUDE.md");
       const agentsPath = join7(workspacePath, "AGENTS.md");
       const claudeExistsInSource = existsSync6(join7(sourcePath, "CLAUDE.md"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allagents",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "CLI tool for managing multi-repo AI agent workspaces with plugin synchronization",
   "type": "module",
   "bin": {