@phnx-labs/agents-cli 0.1.0

package/dist/lib/versions.d.ts

@@ -0,0 +1,248 @@
+import type { AgentId } from './types.js';
+/**
+ * Resource selection for syncing to a version.
+ * Each field can be:
+ * - 'all' - sync all available resources of this type
+ * - string[] - sync only these specific resources
+ * - undefined - skip this resource type
+ */
+export interface ResourceSelection {
+    commands?: string[] | 'all';
+    skills?: string[] | 'all';
+    hooks?: string[] | 'all';
+    memory?: string[] | 'all';
+    mcp?: string[] | 'all';
+    permissions?: string[] | 'all';
+    subagents?: string[] | 'all';
+    plugins?: string[] | 'all';
+}
+/**
+ * Available resources in ~/.agents/ for syncing.
+ *
+ * `promptcuts` is a boolean, not a list — there is at most one
+ * ~/.agents/promptcuts.yaml file. It is NOT version-scoped: the
+ * expand-promptcuts hook reads it directly, so no per-version copy
+ * is made and no sync step is needed.
+ */
+export interface AvailableResources {
+    commands: string[];
+    skills: string[];
+    hooks: string[];
+    memory: string[];
+    mcp: string[];
+    permissions: string[];
+    subagents: string[];
+    plugins: string[];
+    promptcuts: boolean;
+}
+/**
+ * Get all available resources from ~/.agents/.
+ */
+export declare function getAvailableResources(cwd?: string): AvailableResources;
+/**
+ * Get what's ACTUALLY synced to a version by inspecting the version home.
+ * This is the source of truth - not the tracking in agents.yaml.
+ */
+export declare function getActuallySyncedResources(agent: AgentId, version: string, options?: {
+    cwd?: string;
+}): AvailableResources;
+/**
+ * Compare available resources with what's ACTUALLY synced to version home.
+ * Returns only NEW resources that haven't been synced yet.
+ * Source of truth: the actual files/config, NOT agents.yaml tracking.
+ */
+export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources): AvailableResources;
+/**
+ * Check if there are any new resources to sync.
+ */
+export declare function hasNewResources(diff: AvailableResources, agent?: AgentId): boolean;
+/**
+ * Prompt user to select which NEW resources to sync.
+ * Only shows resources that haven't been synced yet.
+ */
+export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources): Promise<ResourceSelection | null>;
+/**
+ * Prompt user to select which resources to sync from ~/.agents/.
+ * Returns the selection, or null if user cancels.
+ */
+export declare function promptResourceSelection(agent: AgentId): Promise<ResourceSelection | null>;
+export interface AgentSpec {
+    agent: AgentId;
+    version: string;
+}
+/**
+ * Parse agent@version syntax.
+ * Examples:
+ *   "claude@1.5.0" -> { agent: "claude", version: "1.5.0" }
+ *   "claude" -> { agent: "claude", version: "latest" }
+ *   "codex@latest" -> { agent: "codex", version: "latest" }
+ */
+export declare function parseAgentSpec(spec: string): AgentSpec | null;
+/**
+ * Get the directory where a specific version is installed.
+ */
+export declare function getVersionDir(agent: AgentId, version: string): string;
+/**
+ * Get the binary path for a specific agent version.
+ */
+export declare function getBinaryPath(agent: AgentId, version: string): string;
+/**
+ * Get the isolated HOME directory for a specific agent version.
+ * Each version has its own config isolation (like jobs sandbox).
+ */
+export declare function getVersionHomePath(agent: AgentId, version: string): string;
+/**
+ * Check if a specific version is installed.
+ */
+export declare function isVersionInstalled(agent: AgentId, version: string): boolean;
+/**
+ * Get the latest available version from npm for an agent.
+ */
+export declare function getLatestNpmVersion(agent: AgentId): Promise<string | null>;
+/**
+ * Check if 'latest' version is already installed (by resolving to actual version).
+ */
+export declare function isLatestInstalled(agent: AgentId): Promise<{
+    installed: boolean;
+    version: string | null;
+}>;
+/**
+ * List all installed versions for an agent.
+ */
+export declare function listInstalledVersions(agent: AgentId): string[];
+/**
+ * Get the global default version for an agent.
+ */
+export declare function getGlobalDefault(agent: AgentId): string | null;
+/**
+ * Set the global default version for an agent.
+ */
+export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
+/**
+ * Install a specific version of an agent.
+ */
+export declare function installVersion(agent: AgentId, version: string, onProgress?: (message: string) => void): Promise<{
+    success: boolean;
+    installedVersion: string;
+    error?: string;
+}>;
+/**
+ * Remove a specific version of an agent.
+ */
+export declare function removeVersion(agent: AgentId, version: string): boolean;
+/**
+ * Remove all versions of an agent.
+ */
+export declare function removeAllVersions(agent: AgentId): number;
+/**
+ * Get the resolved version for an agent in the current context.
+ * Checks project manifest first, then global default.
+ */
+export declare function resolveVersion(agent: AgentId, projectPath?: string): string | null;
+/**
+ * Get version specified in a project-root agents.yaml (not the user ~/.agents/agents.yaml).
+ */
+export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
+/**
+ * Compare semver versions for sorting.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Get actual version from an installed 'latest' directory.
+ */
+export declare function getInstalledVersion(agent: AgentId, version: string): Promise<string | null>;
+export interface SyncResult {
+    commands: boolean;
+    skills: boolean;
+    hooks: boolean;
+    memory: string[];
+    permissions: boolean;
+    mcp: string[];
+    subagents: string[];
+    plugins: string[];
+}
+export interface ResourceDiff {
+    commands: {
+        added: string[];
+        dangling: string[];
+    };
+    skills: {
+        added: string[];
+        dangling: string[];
+    };
+    hooks: {
+        added: string[];
+        dangling: string[];
+    };
+    memory: {
+        added: string[];
+        dangling: string[];
+    };
+    totalAdded: number;
+    totalDangling: number;
+}
+/**
+ * Get the diff between central resources (~/.agents/) and what's synced to a version.
+ * Uses filesystem state - no tracking needed.
+ */
+export declare function getResourceDiff(agent: AgentId, version: string): ResourceDiff;
+/**
+ * Sync central resources (~/.agents/) into a specific version's config directory.
+ * Copies selected resources from central storage into {versionHome}/.{agent}/.
+ *
+ * @param agent - The agent ID
+ * @param version - The version string
+ * @param selection - Optional resource selection. If not provided, syncs all resources.
+ *
+ * For Gemini: commands are converted from markdown to TOML.
+ */
+export declare function syncResourcesToVersion(agent: AgentId, version: string, selection?: ResourceSelection, options?: {
+    projectDir?: string;
+    cwd?: string;
+}): SyncResult;
+/**
+ * Get the effective HOME directory for an agent.
+ * If version-managed with a resolved version, returns the version's home directory.
+ * Otherwise returns the real HOME.
+ */
+export declare function getEffectiveHome(agentId: AgentId): string;
+export interface VersionSelectionResult {
+    selectedAgents: AgentId[];
+    versionSelections: Map<AgentId, string[]>;
+}
+export interface InstalledAgentTargetResult {
+    selectedAgents: AgentId[];
+    directAgents: AgentId[];
+    versionSelections: Map<AgentId, string[]>;
+}
+/**
+ * Resolve a comma-separated --agents list into concrete version selections.
+ * Bare agents target the default version, or the newest installed version when no default exists.
+ * Explicit agent@version targets only that installed version.
+ */
+export declare function resolveAgentVersionTargets(value: string, availableAgents: readonly AgentId[], options?: {
+    allVersions?: boolean;
+}): VersionSelectionResult;
+/**
+ * Resolve a comma-separated --agents list into install/apply targets.
+ * Bare agents target the default version (or newest installed version) when managed,
+ * and fall back to the agent's effective HOME when unmanaged.
+ * Explicit agent@version targets only that installed version.
+ */
+export declare function resolveInstalledAgentTargets(value: string, availableAgents: readonly AgentId[], options?: {
+    allVersions?: boolean;
+}): InstalledAgentTargetResult;
+/**
+ * Resolve configured manifest targets into direct homes and managed versions.
+ */
+export declare function resolveConfiguredAgentTargets(agents: readonly AgentId[] | undefined, agentVersions: Partial<Record<AgentId, string[]>> | undefined, availableAgents: readonly AgentId[], options?: {
+    allVersions?: boolean;
+}): InstalledAgentTargetResult;
+/**
+ * Prompt user to select agents and versions for resource installation.
+ * Returns selected agents and their version selections.
+ */
+export declare function promptAgentVersionSelection(availableAgents: AgentId[], options?: {
+    skipPrompts?: boolean;
+}): Promise<VersionSelectionResult>;
+//# sourceMappingURL=versions.d.ts.map

package/dist/lib/versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/lib/versions.ts"],"names":[],"mappings":"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"}