@phnx-labs/agents-cli 1.18.6 → 1.19.0

package/dist/lib/types.d.ts

@@ -27,6 +27,7 @@ export interface AgentConfig {
     commandsSubdir: string;
     skillsDir: string;
     hooksDir: string;
+    pluginManifestDir?: string;
     instructionsFile: string;
     format: 'markdown' | 'toml';
     variableSyntax: string;
@@ -109,6 +110,8 @@ export interface ManifestHook {
     agents?: AgentId[];
     /** Set to false in user hooks.yaml to disable a system-shipped hook. */
     enabled?: boolean;
+    /** Set true on user hooks that intentionally shadow system-shipped hooks. */
+    override?: boolean;
     /** Optional pre-filter predicates evaluated before invoking the script. */
     matches?: HookMatches;
 }
@@ -187,8 +190,6 @@ export interface RepoInfo {
 }
 /** Canonical system repo cloned into ~/.agents-system/. */
 export declare const DEFAULT_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
-/** Legacy system repo — kept so existing installs still recognize their origin. */
-export declare const MIRROR_SYSTEM_REPO = "gh:muqsitnawaz/.agents-system";
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export declare function systemRepoSlug(repo?: string): string;
 /** Kind of package that can be searched and installed from a registry. */
@@ -465,7 +466,7 @@ export interface BrowserProfileConfig {
     };
     /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
     logDir?: string;
-    /** Optional SSH host where logDir lives, e.g. "muqsit@mac-mini". */
+    /** Optional SSH host where logDir lives, e.g. "user@mac-mini". */
     logHost?: string;
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */

package/dist/lib/types.js

@@ -7,8 +7,6 @@
  */
 /** Canonical system repo cloned into ~/.agents-system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
-/** Legacy system repo — kept so existing installs still recognize their origin. */
-export const MIRROR_SYSTEM_REPO = 'gh:muqsitnawaz/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {
     return repo.replace(/^gh:/, '').replace(/\.git$/, '');

package/dist/lib/versions.js

@@ -50,7 +50,39 @@ const RULES_DOC_FILENAME = 'README.md';
 // at parse time so it can't reach an exec/shell boundary or get interpolated
 // into a generated bash alias. Must allow "latest" plus npm-dist-tag /
 // semver-shaped values (digits, dots, dashes, +, _).
-const VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
+const VERSION_RE = /^(?:latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+function getResourceBases(cwd) {
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    const userBase = getUserAgentsDir();
+    const systemBase = getAgentsDir();
+    const resourceBases = [];
+    if (projectAgentsDir) {
+        resourceBases.push({ scope: 'project', base: projectAgentsDir });
+    }
+    resourceBases.push({ scope: 'user', base: userBase });
+    resourceBases.push({ scope: 'user', base: systemBase });
+    for (const extra of getEnabledExtraRepos()) {
+        resourceBases.push({ scope: 'user', base: extra.dir });
+    }
+    return resourceBases;
+}
+function getScopedMcpResources(cwd) {
+    const resources = new Map();
+    for (const { base, scope } of getResourceBases(cwd)) {
+        const mcpDir = path.join(base, 'mcp');
+        if (!fs.existsSync(mcpDir))
+            continue;
+        const files = fs.readdirSync(mcpDir)
+            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+        for (const file of files) {
+            const config = parseMcpServerConfig(path.join(mcpDir, file));
+            if (config?.name && !resources.has(config.name)) {
+                resources.set(config.name, { name: config.name, scope });
+            }
+        }
+    }
+    return Array.from(resources.values());
+}
 /**
  * Get all available resources from ~/.agents/.
  */
@@ -68,19 +100,7 @@ export function getAvailableResources(cwd = process.cwd()) {
         promptcuts: false,
     };
     const projectAgentsDir = getProjectAgentsDir(cwd);
-    const userBase = getUserAgentsDir();
-    const systemBase = getAgentsDir();
-    const resourceBases = [];
-    if (projectAgentsDir) {
-        resourceBases.push({ scope: 'project', base: projectAgentsDir });
-    }
-    resourceBases.push({ scope: 'user', base: userBase });
-    resourceBases.push({ scope: 'user', base: systemBase });
-    // Extra DotAgent repos registered via `agents repo add`. Ordered last so
-    // project/user/system names win on collision.
-    for (const extra of getEnabledExtraRepos()) {
-        resourceBases.push({ scope: 'user', base: extra.dir });
-    }
+    const resourceBases = getResourceBases(cwd);
     // Commands (*.md files)
     const commandNames = new Set();
     for (const { base } of resourceBases) {
@@ -169,21 +189,7 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.memory = Array.from(presetNames);
-    // MCP servers (*.yaml files) — use the `name:` field inside, not filename
-    const mcpNames = new Set();
-    for (const { base } of resourceBases) {
-        const mcpDir = path.join(base, 'mcp');
-        if (!fs.existsSync(mcpDir))
-            continue;
-        const files = fs.readdirSync(mcpDir)
-            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
-        for (const file of files) {
-            const config = parseMcpServerConfig(path.join(mcpDir, file));
-            if (config?.name)
-                mcpNames.add(config.name);
-        }
-    }
-    result.mcp = Array.from(mcpNames);
+    result.mcp = getScopedMcpResources(cwd).map(resource => resource.name);
     // Permission groups (from permissions/groups/*.yaml)
     const permissionNames = new Set();
     for (const { base } of resourceBases) {
@@ -839,6 +845,9 @@ export async function promptResourceSelection(agent) {
  */
 export function parseAgentSpec(spec) {
     const parts = spec.split('@');
+    if (parts.length > 2) {
+        return null;
+    }
     const agentName = parts[0].toLowerCase();
     const version = parts[1] || 'latest';
     if (!AGENTS[agentName]) {
@@ -984,6 +993,12 @@ export async function installVersion(agent, version, onProgress) {
     if (!agentConfig.npmPackage) {
         return { success: false, installedVersion: version, error: 'Agent has no npm package' };
     }
+    // Validate before deriving filesystem paths or npm package specs. The CLI
+    // parser already enforces this for user input; this guard protects direct
+    // callers and tests the critical install path at the source.
+    if (!VERSION_RE.test(version)) {
+        throw new Error(`Invalid version: ${JSON.stringify(version)}`);
+    }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
     // Create version directory and isolated home
@@ -1000,12 +1015,6 @@ export async function installVersion(agent, version, onProgress) {
     const packageSpec = version === 'latest'
         ? agentConfig.npmPackage
         : `${agentConfig.npmPackage}@${version}`;
-    // Defense-in-depth: even if a future caller bypasses parseAgentSpec, the
-    // version string never reaches /bin/sh because we use execFile (argv form)
-    // and re-validate here.
-    if (version !== 'latest' && !VERSION_RE.test(version)) {
-        throw new Error(`Invalid version: ${JSON.stringify(version)}`);
-    }
     try {
         // Check npm is available
         try {
@@ -1261,10 +1270,17 @@ export function getProjectVersion(agent, startPath) {
                 const parsed = yaml.parse(content);
                 const version = parsed?.agents?.[agent];
                 if (typeof version === 'string' && version.trim()) {
-                    return version.trim();
+                    const normalized = version.trim();
+                    if (!VERSION_RE.test(normalized)) {
+                        throw new Error(`Invalid version in agents.yaml for ${agent}: ${normalized}. Allowed: latest or [A-Za-z0-9._+-]{1,64}`);
+                    }
+                    return normalized;
                 }
             }
-            catch {
+            catch (err) {
+                if (err instanceof Error && err.message.startsWith('Invalid version in agents.yaml')) {
+                    throw err;
+                }
                 // Ignore parsing errors
             }
         }
@@ -1520,9 +1536,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 const permMap = new Map(available.permissions.map(n => [n, 'system']));
                 patternSelection.permissions = expandPatterns(vr.permissions, permMap);
             }
-            // mcp: all declared servers are 'user' source.
+            // mcp: pattern matching must preserve project vs user scope.
             if (Array.isArray(vr.mcp) && vr.mcp.length > 0) {
-                const mcpMap = new Map(available.mcp.map(n => [n, 'user']));
+                const mcpMap = new Map(getScopedMcpResources(cwd).map(resource => [resource.name, resource.scope]));
                 patternSelection.mcp = expandPatterns(vr.mcp, mcpMap);
             }
             // plugins: treat all as 'user' source for now.
@@ -1649,6 +1665,15 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             : available.skills;
         if (skillsToSync.length > 0) {
             const skillsTarget = path.join(agentDir, 'skills');
+            // Old version homes may have skills -> ~/.agents/skills. Replace the
+            // parent symlink before touching children so removePath(destDir) cannot
+            // delete the central source through it.
+            try {
+                if (fs.lstatSync(skillsTarget).isSymbolicLink()) {
+                    removePath(skillsTarget);
+                }
+            }
+            catch { /* target does not exist yet */ }
             fs.mkdirSync(skillsTarget, { recursive: true });
             const syncedSkills = [];
             for (const skill of skillsToSync) {
@@ -1855,7 +1880,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             const plugin = pluginMap.get(name);
             if (!plugin || !pluginSupportsAgent(plugin, agent))
                 continue;
-            const pluginResult = syncPluginToVersion(plugin, agent, versionHome);
+            const pluginResult = syncPluginToVersion(plugin, agent, versionHome, { version });
             if (pluginResult.success) {
                 result.plugins.push(name);
             }

package/dist/lib/workflows.d.ts

@@ -43,6 +43,13 @@ export interface InstalledWorkflow {
 export declare function parseWorkflowFrontmatter(workflowDir: string): WorkflowFrontmatter | null;
 /** Count subagent .md files in a workflow's subagents/ directory. */
 export declare function countWorkflowSubagents(workflowDir: string): number;
+/**
+ * Resolve an `agents run <workflow>` reference.
+ *
+ * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
+ * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ */
+export declare function resolveWorkflowRef(ref: string, cwd?: string): string | null;
 /**
  * Discover all workflow directories (those containing WORKFLOW.md) in a local path.
  * Checks if the path itself is a workflow, then scans a top-level workflows/ subdirectory,

package/dist/lib/workflows.js

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
+import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 /** Agents that support running workflows via `agents run`. */
 export const WORKFLOW_CAPABLE_AGENTS = ['claude'];
@@ -56,6 +56,47 @@ export function countWorkflowSubagents(workflowDir) {
         return 0;
     }
 }
+function expandWorkflowPath(ref) {
+    if (ref === '~')
+        return process.env.HOME ?? ref;
+    if (ref.startsWith('~/')) {
+        const home = process.env.HOME;
+        return home ? path.join(home, ref.slice(2)) : ref;
+    }
+    return ref;
+}
+function isWorkflowDir(dir) {
+    return fs.existsSync(path.join(dir, 'WORKFLOW.md'));
+}
+function resolveWorkflowPath(ref, cwd) {
+    const expanded = expandWorkflowPath(ref);
+    const candidate = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+    return isWorkflowDir(candidate) ? candidate : null;
+}
+/**
+ * Resolve an `agents run <workflow>` reference.
+ *
+ * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
+ * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ */
+export function resolveWorkflowRef(ref, cwd = process.cwd()) {
+    const direct = resolveWorkflowPath(ref, cwd);
+    if (direct)
+        return direct;
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    const searchDirs = [
+        ...(projectAgentsDir ? [path.join(projectAgentsDir, 'workflows')] : []),
+        getUserWorkflowsDir(),
+        getSystemWorkflowsDir(),
+        ...getEnabledExtraRepos().map(r => path.join(r.dir, 'workflows')),
+    ];
+    for (const dir of searchDirs) {
+        const workflowPath = path.join(dir, ref);
+        if (isWorkflowDir(workflowPath))
+            return workflowPath;
+    }
+    return null;
+}
 /**
  * Discover all workflow directories (those containing WORKFLOW.md) in a local path.
  * Checks if the path itself is a workflow, then scans a top-level workflows/ subdirectory,