@phnx-labs/agents-cli 1.22.56 → 1.22.58

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

@@ -2,13 +2,7 @@ import type { AgentId } from '../types.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 export * from './store.js';
 import { type PrunableKind } from '../staleness/prune.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
- */
+/** Resource selection for syncing to a version: 'all', a name list, or undefined (skip). */
 export interface ResourceSelection {
     commands?: string[] | 'all';
     skills?: string[] | 'all';
@@ -20,14 +14,7 @@ export interface ResourceSelection {
     plugins?: string[] | 'all';
     workflows?: 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.
- */
+/** Resources available in ~/.agents/ for syncing. `promptcuts` is a boolean because it is a single, version-unscoped file. */
 export interface AvailableResources {
     commands: string[];
     skills: string[];
@@ -40,14 +27,9 @@ export interface AvailableResources {
     workflows: string[];
     promptcuts: boolean;
 }
-/**
- * Get all available resources from ~/.agents/.
- */
+/** Discover all resources available for syncing 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.
- */
+/** Return what's actually synced to a version home (source of truth, not agents.yaml tracking). */
 export declare function getActuallySyncedResources(agent: AgentId, version: string, options?: {
     cwd?: string;
 }): AvailableResources;
@@ -60,103 +42,49 @@ export interface ProjectOnlyResources {
     plugins: Set<string>;
     workflows: Set<string>;
 }
-/**
- * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
- * user/system/extra layers). Sync intentionally skips project-layer commands,
- * skills, hooks, subagents, plugins, and workflows for security — see the
- * defense comments above each sync branch in syncResourcesToVersion. Without
- * this filter, those names would forever appear in the "New resources" diff
- * because they live in `available` but never reach `actuallySynced`.
- */
+/** Names that exist only in the project's `.agents/` layer. Sync skips project-layer resources for security, so filter them out of the "new resources" diff. */
 export declare function getProjectOnlyResources(cwd?: string): ProjectOnlyResources;
-/**
- * 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.
- *
- * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
- * Names listed there are filtered out for kinds that sync intentionally
- * excludes the project layer — otherwise they would re-appear as "new"
- * on every run and "Yes, sync all new" would silently do nothing for them.
- */
+/** Return resources in `available` that are not yet synced to the version home. `projectOnly` filters project-layer resources that sync skips for security. */
 export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources, projectOnly?: ProjectOnlyResources): AvailableResources;
-/**
- * Check if there are any new resources to sync.
- * When version is provided, uses version-specific capability checks.
- */
+/** Return true when `diff` contains any resources the agent/version actually supports. */
 export declare function hasNewResources(diff: AvailableResources, agent?: AgentId, version?: string): boolean;
-/**
- * Prompt user to select which NEW resources to sync.
- * Only shows resources that haven't been synced yet.
- */
+/** Prompt the user to select which new resources to sync. */
 export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources, version?: string): Promise<ResourceSelection | null>;
-/**
- * Prompt user to select which resources to sync from ~/.agents/.
- * Returns the selection, or null if user cancels.
- */
+/** Prompt the user to select which resources to sync from ~/.agents/. */
 export declare function promptResourceSelection(agent: AgentId): Promise<ResourceSelection | null>;
 /** Parsed agent@version specification from CLI input. */
 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" }
- */
+/** Parse an `agent@version` spec; bare agent means `latest`. */
 export declare function parseAgentSpec(spec: string): AgentSpec | null;
-/**
- * Get the latest available version from npm for an agent.
- */
 export declare function getLatestNpmVersion(agent: AgentId): Promise<string | null>;
-/**
- * Get the oldest published version from npm for an agent.
- */
 export declare function getOldestNpmVersion(agent: AgentId): Promise<string | null>;
-/**
- * Check if 'latest' version is already installed (by resolving to actual version).
- */
+/** Check whether the npm `latest` version is installed. */
 export declare function isLatestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
-/**
- * Check if 'oldest' published version is already installed (by resolving to actual version).
- */
+/** Check whether the npm `oldest` version is installed. */
 export declare function isOldestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
 /**
- * List every version directory for an agent, including ones missing the
- * binary (typically home-only leftovers from a prior `removeVersion`).
- *
- * Used by `agents prune cleanup` to surface stale installs that the regular
- * `listInstalledVersions` filters out. Do NOT use elsewhere — every other
- * call site assumes a working binary.
+ * List every version directory for an agent, including home-only leftovers, for
+ * `agents prune cleanup` only. Do NOT use elsewhere — every other call site
+ * assumes a working binary.
  */
 export declare function listInstalledVersionDirs(agent: AgentId): Array<{
     version: string;
     hasBinary: boolean;
 }>;
-/**
- * Set the global default version for an agent.
- */
+/** Set (or clear) the global default version for an agent. */
 export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
-/**
- * Set (or clear, with `undefined`) the preferred isolated version.
- *
- * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
- * symlink or the global default — the five things `setDefaultVersion` does. This is
- * a pointer inside the sandbox, so it stays inside the sandbox.
- */
+/** Set (or clear) the preferred isolated version without touching the launcher, shim, or global default. */
 export declare function setIsolatedDefault(agent: AgentId, version: string | undefined): void;
-/**
- * Install a specific version of an agent.
- */
+/** Install a specific version of an agent. */
 export declare function installVersion(agent: AgentId, version: string, onProgress?: (message: string) => void, opts?: {
     clean?: boolean;
 }): Promise<{
@@ -204,7 +132,7 @@ export declare function reconcileStaleLatestDir(agent: AgentId, installedVersion
  * re-install) without collision and gives a chronological audit trail.
  *
  * The whole versionDir moves — including `home/` (transcripts, sessions). The
- * user can recover everything via `agents trash restore <agent>@<version>`.
+ * user can recover everything via `agents restore <agent>@<version>`.
  * Nothing is ever hard-deleted.
  */
 export declare function softDeleteVersionDir(agent: AgentId, version: string): string | null;
@@ -212,7 +140,7 @@ export declare function softDeleteVersionDir(agent: AgentId, version: string): s
  * Remove a specific version of an agent.
  *
  * Soft-delete only: moves the entire version directory (including `home/`)
- * to ~/.agents/.system/trash/versions/. Recoverable via `agents trash restore`.
+ * to ~/.agents/.system/trash/versions/. Recoverable via `agents restore`.
  * Nothing is hard-deleted.
  */
 export declare function removeVersion(agent: AgentId, version: string): boolean;
@@ -270,24 +198,7 @@ export interface HealedVersionPointers {
  * isolated-only agent are left untouched.
  */
 export declare function healDanglingVersionPointers(agent: AgentId, cwd: string): Promise<HealedVersionPointers>;
-/**
- * Normalize a user-supplied @version token across CLI subcommands.
- *
- *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
- *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
- *   "latest"                    -> highest installed version (process.exit if none installed)
- *   "oldest"                    -> lowest installed version (process.exit if none installed)
- *   "x.y.z" (installed)         -> "x.y.z"
- *   "x.y.z" (not installed)     -> process.exit with installed-list hint
- *
- * `pinned` is a synonym for `default`: both name the project pin / global
- * default, which the caller resolves.
- *
- * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
- * vocabulary consistent. Subcommands with different semantics for `latest`
- * (install/remove/use, where `latest` means npm-latest) keep their existing
- * parsing.
- */
+/** Normalize a user-supplied `@version` token. `default`/`pinned`/`any` → undefined; `latest`/`oldest` → extreme installed version; concrete versions must be installed. */
 export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
@@ -535,44 +446,26 @@ export interface InstalledAgentTargetResult {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }
-/**
- * Thrown when the user references an agent@version that is not installed.
- * Carries the parsed (agentId, version) so callers can react — e.g. prompt
- * to install it on demand — without having to parse the error message.
- */
+/** Thrown when an `agent@version` target is not installed; carries the parsed ids so callers can react without parsing the message. */
 export declare class VersionNotInstalledError extends Error {
     readonly agentId: AgentId;
     readonly version: string;
     readonly installedVersions: readonly string[];
     constructor(agentId: AgentId, version: string, installedVersions: readonly 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.
- */
+/** Resolve a comma-separated `--agents` list into concrete installed version selections. */
 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.
- */
+/** Resolve a comma-separated `--agents` list into install/apply targets, distinguishing managed versions from direct homes. */
 export declare function resolveInstalledAgentTargets(value: string, availableAgents: readonly AgentId[], options?: {
     allVersions?: boolean;
 }): InstalledAgentTargetResult;
-/**
- * Resolve configured manifest targets into direct homes and managed versions.
- */
+/** 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.
- */
+/** Prompt the user to select agents and versions for resource installation. */
 export declare function promptAgentVersionSelection(availableAgents: AgentId[], options?: {
     skipPrompts?: boolean;
 }): Promise<VersionSelectionResult>;