@phnx-labs/agents-cli 0.1.0

package/dist/lib/shims.d.ts

@@ -0,0 +1,228 @@
+import type { AgentId } from './types.js';
+import { getShimsDir } from './state.js';
+export { getShimsDir };
+/**
+ * Strategy for handling file conflicts during config migration.
+ */
+export type ConflictStrategy = 'keep-dest' | 'overwrite' | 'ask-per-file';
+/**
+ * Information about conflicts found during config migration.
+ */
+export interface ConflictInfo {
+    agent: AgentId;
+    version: string;
+    conflicts: string[];
+}
+/**
+ * Detect conflicting files between source and destination directories.
+ * Returns list of filenames that exist in both locations (excluding symlinks in dest).
+ */
+export declare function detectConflicts(src: string, dest: string, prefix?: string): string[];
+/**
+ * Prompt user for conflict resolution strategy.
+ */
+export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): Promise<ConflictStrategy | null>;
+/**
+ * Generate the shim script content for an agent.
+ *
+ * The shim resolves the version in order:
+ * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
+ * 2. ~/.agents/agents.yaml default
+ *
+ * If version is specified but not installed, auto-installs it.
+ *
+ * Config isolation is handled via symlinks:
+ * ~/.{agent} -> ~/.agents/versions/{agent}/{version}/home/.{agent}/
+ */
+/**
+ * Current shim schema version. Bump whenever `generateShimScript` changes
+ * in a way that requires existing on-disk shims to be regenerated (new
+ * flags, fixed argument parsing, new hooks, etc.). `isShimCurrent` reads
+ * this marker out of existing shims to decide whether to regenerate.
+ *
+ * History:
+ *   v1 — initial shim (implicit, no marker).
+ *   v2 — `--version=...` form in sync/refresh-memory calls; refresh-memory
+ *        shim hook for non-@-capable agents.
+ *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
+ *        so it no longer collides with commander's top-level `--version`.
+ *   v4 — project version marker changed from `.agents-version` to a
+ *        root-level `agents.yaml`; shim now skips ~/.agents/agents.yaml
+ *        when walking up for a project marker.
+ */
+export declare const SHIM_SCHEMA_VERSION = 4;
+export declare function generateShimScript(agent: AgentId): string;
+/**
+ * Create a shim for an agent.
+ */
+export declare function createShim(agent: AgentId): string;
+/**
+ * Remove the shim for an agent.
+ */
+export declare function removeShim(agent: AgentId): boolean;
+/**
+ * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
+ * changes in a way that requires existing on-disk aliases to be regenerated.
+ *
+ * History:
+ *   v1 — implicit (no marker); no CLAUDE_CONFIG_DIR export, so direct
+ *        `claude@X` invocations leaked into ~/.claude (the default version's
+ *        symlinked home) and `agents view` never saw the login.
+ *   v2 — emit CLAUDE_CONFIG_DIR for claude aliases so each version has its
+ *        own isolated config/OAuth slot; stamp a version marker so stale
+ *        aliases can be detected and regenerated.
+ */
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 2;
+/**
+ * Generate a versioned alias script that directly execs a specific version.
+ * e.g., claude@2.0.65 -> directly runs that version's binary
+ */
+export declare function generateVersionedAliasScript(agent: AgentId, version: string): string;
+/**
+ * Read the schema version of an on-disk versioned alias. Returns null if the
+ * alias doesn't exist or is a pre-v2 alias (no marker — treated as stale).
+ */
+export declare function readVersionedAliasSchemaVersion(agent: AgentId, version: string): number | null;
+export declare function isVersionedAliasCurrent(agent: AgentId, version: string): boolean;
+/**
+ * Regenerate a versioned alias if missing or stale. Mirrors ensureShimCurrent
+ * for the main shim — callers can surface a one-line notice when something
+ * was upgraded.
+ */
+export declare function ensureVersionedAliasCurrent(agent: AgentId, version: string): 'created' | 'updated' | 'current';
+export declare function getVersionedAliasPath(agent: AgentId, version: string): string;
+/**
+ * Create a versioned alias for a specific agent version.
+ * e.g., claude@2.0.65
+ */
+export declare function createVersionedAlias(agent: AgentId, version: string): string;
+/**
+ * Remove a versioned alias for a specific agent version.
+ */
+export declare function removeVersionedAlias(agent: AgentId, version: string): boolean;
+/**
+ * Check if a versioned alias exists.
+ */
+export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
+/**
+ * Detect conflicts that would occur when switching config symlink for an agent/version.
+ * This allows collecting conflicts upfront before prompting for a strategy.
+ *
+ * Returns null if no migration is needed (already symlink or doesn't exist),
+ * or ConflictInfo with the list of conflicting files.
+ */
+export declare function detectMigrationConflicts(agent: AgentId, version: string): ConflictInfo | null;
+/**
+ * Switch the agent's config symlink to point to a specific version.
+ * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/
+ *
+ * If a real directory exists at the config path, it will be backed up
+ * to ~/.agents/backups/{agent}/{timestamp}/ and replaced with a symlink.
+ *
+ * @param agent - The agent ID
+ * @param version - The version to switch to
+ *
+ * Returns: { success: boolean, backupPath?: string, error?: string }
+ */
+export declare function switchConfigSymlink(agent: AgentId, version: string): Promise<{
+    success: boolean;
+    backupPath?: string;
+    error?: string;
+}>;
+/**
+ * Switch home-level files (outside the config dir) to per-version symlinks.
+ * e.g., ~/.claude.json -> ~/.agents/versions/claude/2.0.65/home/.claude.json
+ *
+ * Uses atomic rename to avoid data loss if another session is running.
+ * On first migration (real file -> symlink), merges global auth into
+ * ALL installed versions so they inherit the current account.
+ */
+export declare function switchHomeFileSymlinks(agent: AgentId, version: string): {
+    switched: string[];
+    errors: string[];
+};
+/**
+ * Get the current config symlink target version, if any.
+ */
+export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
+/**
+ * Check if shim exists for an agent.
+ */
+export declare function shimExists(agent: AgentId): boolean;
+/**
+ * Read the schema version embedded in an existing on-disk shim. Returns
+ * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
+ */
+export declare function readShimSchemaVersion(agent: AgentId): number | null;
+/**
+ * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
+ * False means either the shim is missing, is pre-v2 (no marker), or is an
+ * older version that needs regeneration.
+ */
+export declare function isShimCurrent(agent: AgentId): boolean;
+/**
+ * Regenerate the shim if it's missing or outdated. Returns a status describing
+ * what happened — callers can surface a one-line notice to the user ("Updated
+ * shim for codex") when appropriate.
+ */
+export declare function ensureShimCurrent(agent: AgentId): 'created' | 'updated' | 'current';
+/**
+ * Get the path to the shim for an agent.
+ */
+export declare function getShimPath(agent: AgentId): string;
+/**
+ * Return the first executable path that would be launched for this agent when
+ * resolving against PATH, excluding the managed shim itself.
+ */
+export declare function getPathShadowingExecutable(agent: AgentId): string | null;
+/**
+ * Check if shims directory is in PATH.
+ */
+export declare function isShimsInPath(): boolean;
+/**
+ * Get shell configuration instructions for adding shims to PATH.
+ */
+export declare function getPathSetupInstructions(): string;
+/**
+ * Add shims directory to shell PATH configuration.
+ * Returns true if added, false if already present or failed.
+ */
+export declare function addShimsToPath(): {
+    success: boolean;
+    alreadyPresent?: boolean;
+    rcFile?: string;
+    error?: string;
+};
+/**
+ * Create shims for all installed agents.
+ */
+export declare function ensureAllShims(): void;
+/**
+ * Resource diff between two versions.
+ */
+export interface ResourceDiff {
+    commands: string[];
+    skills: string[];
+    hooks: string[];
+    memory: {
+        file: string;
+        currentLines: number;
+        targetLines: number;
+    }[];
+    mcp: string[];
+}
+/**
+ * Compare resources between two versions.
+ * Returns resources that exist in currentVersion but not in targetVersion.
+ */
+export declare function compareVersionResources(agent: AgentId, currentVersion: string, targetVersion: string): ResourceDiff;
+/**
+ * Check if a ResourceDiff has any differences.
+ */
+export declare function hasResourceDiff(diff: ResourceDiff): boolean;
+/**
+ * Copy resources from one version to another.
+ * Only copies resources listed in the diff (i.e., ones missing in target).
+ */
+export declare function copyResourcesToVersion(agent: AgentId, fromVersion: string, toVersion: string, diff: ResourceDiff): void;
+//# sourceMappingURL=shims.d.ts.map

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

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