@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/profiles.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Environment profiles for the yagni-code CLI.
+ *
+ * A profile is a named binding of an environment (base URL) to its own stored
+ * credentials, so you can point YAGNI Code at prod, a local backend, or a
+ * staging host and switch between them with a sticky `yagni use <name>`.
+ *
+ * Storage (each file 0600, the dir 0700, since profiles hold live API tokens):
+ *   ~/.yagni-code/profiles/<name>.json   one profile (name, baseUrl, token, …)
+ *   ~/.yagni-code/config.json            { activeProfile }
+ *
+ * The model is deliberately small but multi-account-ready: a second login to a
+ * different workspace/host is just another profile file. `prod` is the default
+ * active profile and the only built-in preset that needs no `--base-url`.
+ */
+import { type Credentials } from "./credentials.js";
+export interface Profile {
+    name: string;
+    baseUrl: string;
+    token?: string;
+    workspaceId?: string;
+    expiresAt?: string;
+}
+/** The default active profile when nothing has been configured yet. */
+export declare const DEFAULT_PROFILE: string;
+export declare function isValidProfileName(name: string): boolean;
+export declare function profilesDir(): string;
+export declare function profilePath(name: string): string;
+export declare function configPath(): string;
+export declare function readProfile(name: string): Promise<Profile | null>;
+export declare function writeProfile(profile: Profile): Promise<void>;
+export declare function deleteProfile(name: string): Promise<void>;
+export declare function listProfileNames(): Promise<string[]>;
+export declare function listProfiles(): Promise<Profile[]>;
+export declare function getActiveProfileName(): Promise<string>;
+export declare function setActiveProfileName(name: string): Promise<void>;
+/** A profile is a superset of Credentials; this yields creds iff it has a token. */
+export declare function credentialsFromProfile(profile: Profile): Credentials | null;
+/**
+ * Resolve the active profile, with its base URL. Always returns a profile (so
+ * callers get a base URL even before a first login); `token` is undefined when
+ * the environment has not been authenticated. `YAGNI_BASE_URL` overrides the
+ * stored/preset base URL for this run only.
+ */
+export declare function readActiveProfile(env?: NodeJS.ProcessEnv): Promise<Profile>;
+/** Persist freshly-minted credentials into a profile (keeping the name). */
+export declare function persistProfileCredentials(name: string, creds: Credentials): Promise<void>;
+/**
+ * Persist a launch-time token ROTATION into an existing profile without
+ * touching its stored base URL. The refresh runs against `creds.baseUrl`, which
+ * may be a per-run `YAGNI_BASE_URL` override (readActiveProfile bakes that in);
+ * persisting it would make a documented single-run override sticky, silently
+ * retargeting every later `yagni` launch at the wrong host. So we rotate only
+ * the token fields and keep the profile's own stored base URL. Falls back to the
+ * passed base URL only when no profile file exists yet (nothing stored to keep).
+ */
+export declare function persistProfileTokenRotation(name: string, creds: Credentials): Promise<void>;
+/** Clear the stored token for a profile but keep the environment binding. */
+export declare function clearProfileToken(name: string): Promise<void>;
+export declare class UnknownEnvironmentError extends Error {
+    constructor(name: string);
+}
+/**
+ * Switch the sticky active profile to `name`, creating it if needed. Base URL
+ * is resolved from (in order): an explicit `--base-url`, the profile's existing
+ * stored URL, or a built-in preset. A name with none of those is an error
+ * rather than a silent default. When `--base-url` changes an existing profile's
+ * host, the stored token is dropped (it belonged to the old environment).
+ */
+export declare function useProfile(name: string, opts?: {
+    baseUrl?: string;
+}): Promise<Profile>;
+/**
+ * One-shot migration: adopt a pre-profiles `~/.yagni-code/credentials.json` as
+ * a named profile so existing logged-in users keep working. No-op once profiles
+ * exist (config.json present or any profile file on disk) or when there is no
+ * legacy file. The legacy file is removed only after the profile is written.
+ */
+export declare function migrateLegacyCredentials(): Promise<void>;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/profiles.js

@@ -0,0 +1,222 @@
+/**
+ * Environment profiles for the yagni-code CLI.
+ *
+ * A profile is a named binding of an environment (base URL) to its own stored
+ * credentials, so you can point YAGNI Code at prod, a local backend, or a
+ * staging host and switch between them with a sticky `yagni use <name>`.
+ *
+ * Storage (each file 0600, the dir 0700, since profiles hold live API tokens):
+ *   ~/.yagni-code/profiles/<name>.json   one profile (name, baseUrl, token, …)
+ *   ~/.yagni-code/config.json            { activeProfile }
+ *
+ * The model is deliberately small but multi-account-ready: a second login to a
+ * different workspace/host is just another profile file. `prod` is the default
+ * active profile and the only built-in preset that needs no `--base-url`.
+ */
+import { chmod, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { credentialsDir, deleteCredentials, readCredentials } from "./credentials.js";
+import { DEFAULT_BASE_URL, PRESET_BASE_URLS, presetBaseUrl } from "./config.js";
+import { DISTRIBUTION } from "./distribution.js";
+/** The default active profile when nothing has been configured yet. */
+export const DEFAULT_PROFILE = DISTRIBUTION.defaultProfile;
+/**
+ * Allowed profile-name shape. Restricts to a safe filename so a name can never
+ * traverse out of the profiles dir or collide with `config.json`.
+ */
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function isValidProfileName(name) {
+    return NAME_RE.test(name) && name !== "config";
+}
+export function profilesDir() {
+    return join(credentialsDir(), "profiles");
+}
+export function profilePath(name) {
+    return join(profilesDir(), `${name}.json`);
+}
+export function configPath() {
+    return join(credentialsDir(), "config.json");
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    // writeFile honors mode only on create; chmod guarantees 0600 on overwrite.
+    await chmod(path, 0o600);
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function readProfile(name) {
+    const parsed = await readJson(profilePath(name));
+    if (!parsed || typeof parsed.baseUrl !== "string")
+        return null;
+    // The on-disk name is advisory; the filename is authoritative.
+    return { ...parsed, name };
+}
+export async function writeProfile(profile) {
+    await writeJson(profilePath(profile.name), profile);
+}
+export async function deleteProfile(name) {
+    await rm(profilePath(name), { force: true });
+}
+export async function listProfileNames() {
+    try {
+        const entries = await readdir(profilesDir());
+        return entries
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => f.slice(0, -".json".length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function listProfiles() {
+    const names = await listProfileNames();
+    const profiles = await Promise.all(names.map((n) => readProfile(n)));
+    return profiles.filter((p) => p !== null);
+}
+export async function getActiveProfileName() {
+    const config = await readJson(configPath());
+    const active = config?.activeProfile;
+    // Ensure the name conforms to the allowed profile name pattern to prevent
+    // path traversal when the config file is corrupted or maliciously edited.
+    // If the stored name is invalid, fall back to the safe default profile.
+    return typeof active === "string" && active.length > 0 && isValidProfileName(active)
+        ? active
+        : DEFAULT_PROFILE;
+}
+export async function setActiveProfileName(name) {
+    await writeJson(configPath(), { activeProfile: name });
+}
+/** A profile is a superset of Credentials; this yields creds iff it has a token. */
+export function credentialsFromProfile(profile) {
+    if (!profile.token)
+        return null;
+    return {
+        token: profile.token,
+        baseUrl: profile.baseUrl,
+        workspaceId: profile.workspaceId ?? "",
+        expiresAt: profile.expiresAt,
+    };
+}
+/**
+ * Resolve the active profile, with its base URL. Always returns a profile (so
+ * callers get a base URL even before a first login); `token` is undefined when
+ * the environment has not been authenticated. `YAGNI_BASE_URL` overrides the
+ * stored/preset base URL for this run only.
+ */
+export async function readActiveProfile(env = process.env) {
+    const name = await getActiveProfileName();
+    const stored = await readProfile(name);
+    const baseUrl = (env.YAGNI_BASE_URL?.trim() ||
+        stored?.baseUrl ||
+        presetBaseUrl(name) ||
+        DEFAULT_BASE_URL).replace(/\/$/, "");
+    return {
+        name,
+        baseUrl,
+        token: stored?.token,
+        workspaceId: stored?.workspaceId,
+        expiresAt: stored?.expiresAt,
+    };
+}
+/** Persist freshly-minted credentials into a profile (keeping the name). */
+export async function persistProfileCredentials(name, creds) {
+    await writeProfile({
+        name,
+        baseUrl: creds.baseUrl,
+        token: creds.token,
+        workspaceId: creds.workspaceId,
+        expiresAt: creds.expiresAt,
+    });
+}
+/**
+ * Persist a launch-time token ROTATION into an existing profile without
+ * touching its stored base URL. The refresh runs against `creds.baseUrl`, which
+ * may be a per-run `YAGNI_BASE_URL` override (readActiveProfile bakes that in);
+ * persisting it would make a documented single-run override sticky, silently
+ * retargeting every later `yagni` launch at the wrong host. So we rotate only
+ * the token fields and keep the profile's own stored base URL. Falls back to the
+ * passed base URL only when no profile file exists yet (nothing stored to keep).
+ */
+export async function persistProfileTokenRotation(name, creds) {
+    const stored = await readProfile(name);
+    await writeProfile({
+        name,
+        baseUrl: stored?.baseUrl ?? creds.baseUrl,
+        token: creds.token,
+        workspaceId: creds.workspaceId,
+        expiresAt: creds.expiresAt,
+    });
+}
+/** Clear the stored token for a profile but keep the environment binding. */
+export async function clearProfileToken(name) {
+    const stored = await readProfile(name);
+    if (!stored)
+        return;
+    await writeProfile({ name, baseUrl: stored.baseUrl });
+}
+export class UnknownEnvironmentError extends Error {
+    constructor(name) {
+        super(`Unknown environment "${name}". Pass --base-url <url> to define it ` +
+            `(or use a preset: ${Object.keys(PRESET_BASE_URLS).join(", ")}).`);
+        this.name = "UnknownEnvironmentError";
+    }
+}
+/**
+ * Switch the sticky active profile to `name`, creating it if needed. Base URL
+ * is resolved from (in order): an explicit `--base-url`, the profile's existing
+ * stored URL, or a built-in preset. A name with none of those is an error
+ * rather than a silent default. When `--base-url` changes an existing profile's
+ * host, the stored token is dropped (it belonged to the old environment).
+ */
+export async function useProfile(name, opts = {}) {
+    if (!isValidProfileName(name)) {
+        throw new Error(`Invalid profile name "${name}". Use letters, numbers, dashes or underscores.`);
+    }
+    const existing = await readProfile(name);
+    const explicit = opts.baseUrl?.trim();
+    const resolvedBaseUrl = (explicit || existing?.baseUrl || presetBaseUrl(name))?.replace(/\/$/, "");
+    if (!resolvedBaseUrl) {
+        throw new UnknownEnvironmentError(name);
+    }
+    // A host change invalidates any token minted for the old host. Compare the
+    // already-normalized resolvedBaseUrl (trailing slash stripped) against the
+    // stored baseUrl (also stripped) so re-using the same host with a trailing
+    // slash does NOT read as a change and drop a still-valid token.
+    const hostChanged = Boolean(existing?.token) && Boolean(explicit) && resolvedBaseUrl !== existing?.baseUrl;
+    const profile = hostChanged
+        ? { name, baseUrl: resolvedBaseUrl }
+        : { ...(existing ?? {}), name, baseUrl: resolvedBaseUrl };
+    await writeProfile(profile);
+    await setActiveProfileName(name);
+    return profile;
+}
+/**
+ * One-shot migration: adopt a pre-profiles `~/.yagni-code/credentials.json` as
+ * a named profile so existing logged-in users keep working. No-op once profiles
+ * exist (config.json present or any profile file on disk) or when there is no
+ * legacy file. The legacy file is removed only after the profile is written.
+ */
+export async function migrateLegacyCredentials() {
+    const alreadyMigrated = (await readJson(configPath())) !== null ||
+        (await listProfileNames()).length > 0;
+    if (alreadyMigrated)
+        return;
+    const legacy = await readCredentials();
+    if (!legacy?.token)
+        return;
+    const name = legacy.baseUrl.replace(/\/$/, "") === DEFAULT_BASE_URL
+        ? DISTRIBUTION.defaultProfile
+        : "default";
+    await persistProfileCredentials(name, legacy);
+    await setActiveProfileName(name);
+    await deleteCredentials();
+}
+//# sourceMappingURL=profiles.js.map

package/dist/refresh.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Refresh-at-launch client.
+ *
+ * When the active profile's token is inside the refresh window (but not yet
+ * expired), the launcher proactively rotates it via `POST /auth/refresh` before
+ * spawning pi, so a long coding session doesn't 401 mid-flight. Everything here
+ * is FAIL-SOFT: a refresh failure (network error, older backend that 404s, a
+ * revoked/expired token → 401) leaves the existing token in place and launches
+ * with a non-fatal warning. An already-expired token is NOT refreshed here — it
+ * stays the login flow's job (`buildLaunch` throws its own login prompt).
+ *
+ * The pure decision (`shouldRefresh`) is separated from the impure POST
+ * (`refreshToken`) so both are unit-testable without a live backend or clock.
+ */
+import type { Credentials } from "./credentials.js";
+/**
+ * How close to expiry (7 days) a token must be before launch proactively
+ * refreshes it. Wide enough that a normal cadence of use keeps the token fresh
+ * without a refresh on every single launch.
+ */
+export declare const REFRESH_WINDOW_MS: number;
+/**
+ * Pure: should we attempt a launch-time refresh for a token with this expiry?
+ *
+ * - unknown/unparseable expiry (older profiles) → no (nothing to reason about)
+ * - already expired → no (the login flow owns that case)
+ * - within the window → yes
+ * - comfortably valid → no
+ *
+ * Never throws.
+ */
+export declare function shouldRefresh(expiresAt: string | undefined, nowMs: number, windowMs?: number): boolean;
+/** The rotated token payload from `POST /auth/refresh` (contract §2). */
+export interface RefreshResult {
+    token: string;
+    expiresAt?: string;
+    workspaceId?: string;
+}
+export interface RefreshTokenDeps {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Impure: `POST /api/yagni-code/auth/refresh` with the current bearer token.
+ * Returns the rotated credentials, or `null` on ANY failure (non-2xx, malformed
+ * body, network error, or a 404 from an older backend that lacks the endpoint).
+ * Never throws — the caller degrades to the existing token.
+ */
+export declare function refreshToken(creds: Credentials, deps?: RefreshTokenDeps): Promise<RefreshResult | null>;
+export interface MaybeRefreshDeps {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** Persist the rotated credentials (0600). Omit to skip persistence. */
+    persist?: (creds: Credentials) => Promise<void>;
+    windowMs?: number;
+}
+export interface MaybeRefreshOutcome {
+    /** The rotated credentials when refreshed, otherwise the originals verbatim. */
+    creds: Credentials;
+    refreshed: boolean;
+    /** Non-fatal notices for the launcher to surface (e.g. a soft-failure). */
+    warnings: string[];
+}
+/**
+ * Orchestrate the launch-time refresh decision + attempt. Fail-soft throughout:
+ * outside the window → no-op; inside the window but the POST fails → keep the
+ * current token and warn. On success, the rotated token is persisted (when a
+ * `persist` seam is provided) and returned for the spawn.
+ */
+export declare function maybeRefreshAtLaunch(creds: Credentials, deps?: MaybeRefreshDeps): Promise<MaybeRefreshOutcome>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/refresh.js

@@ -0,0 +1,117 @@
+/**
+ * Refresh-at-launch client.
+ *
+ * When the active profile's token is inside the refresh window (but not yet
+ * expired), the launcher proactively rotates it via `POST /auth/refresh` before
+ * spawning pi, so a long coding session doesn't 401 mid-flight. Everything here
+ * is FAIL-SOFT: a refresh failure (network error, older backend that 404s, a
+ * revoked/expired token → 401) leaves the existing token in place and launches
+ * with a non-fatal warning. An already-expired token is NOT refreshed here — it
+ * stays the login flow's job (`buildLaunch` throws its own login prompt).
+ *
+ * The pure decision (`shouldRefresh`) is separated from the impure POST
+ * (`refreshToken`) so both are unit-testable without a live backend or clock.
+ */
+/**
+ * How close to expiry (7 days) a token must be before launch proactively
+ * refreshes it. Wide enough that a normal cadence of use keeps the token fresh
+ * without a refresh on every single launch.
+ */
+export const REFRESH_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Per-request wall-clock cap so a hung refresh never delays the spawn. */
+const REFRESH_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * Pure: should we attempt a launch-time refresh for a token with this expiry?
+ *
+ * - unknown/unparseable expiry (older profiles) → no (nothing to reason about)
+ * - already expired → no (the login flow owns that case)
+ * - within the window → yes
+ * - comfortably valid → no
+ *
+ * Never throws.
+ */
+export function shouldRefresh(expiresAt, nowMs, windowMs = REFRESH_WINDOW_MS) {
+    if (!expiresAt)
+        return false;
+    const expiryMs = Date.parse(expiresAt);
+    if (Number.isNaN(expiryMs))
+        return false;
+    const remaining = expiryMs - nowMs;
+    if (remaining <= 0)
+        return false;
+    return remaining <= windowMs;
+}
+/**
+ * Impure: `POST /api/yagni-code/auth/refresh` with the current bearer token.
+ * Returns the rotated credentials, or `null` on ANY failure (non-2xx, malformed
+ * body, network error, or a 404 from an older backend that lacks the endpoint).
+ * Never throws — the caller degrades to the existing token.
+ */
+export async function refreshToken(creds, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(`${creds.baseUrl}/api/yagni-code/auth/refresh`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${creds.token}`,
+            },
+            body: "{}",
+            signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS),
+        });
+        // 404 = older backend without /auth/refresh; 401/403 = revoked/expired.
+        // All non-2xx degrade to the existing token.
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        if (!data || typeof data.token !== "string")
+            return null;
+        return {
+            token: data.token,
+            expiresAt: typeof data.expiresAt === "string" ? data.expiresAt : undefined,
+            workspaceId: typeof data.workspaceId === "string" ? data.workspaceId : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Orchestrate the launch-time refresh decision + attempt. Fail-soft throughout:
+ * outside the window → no-op; inside the window but the POST fails → keep the
+ * current token and warn. On success, the rotated token is persisted (when a
+ * `persist` seam is provided) and returned for the spawn.
+ */
+export async function maybeRefreshAtLaunch(creds, deps = {}) {
+    const now = deps.now ?? Date.now;
+    if (!shouldRefresh(creds.expiresAt, now(), deps.windowMs)) {
+        return { creds, refreshed: false, warnings: [] };
+    }
+    const rotated = await refreshToken(creds, { fetchImpl: deps.fetchImpl });
+    if (!rotated) {
+        return {
+            creds,
+            refreshed: false,
+            warnings: [
+                "Could not refresh your YAGNI Code session; continuing with the current token.",
+            ],
+        };
+    }
+    const next = {
+        token: rotated.token,
+        baseUrl: creds.baseUrl,
+        workspaceId: rotated.workspaceId ?? creds.workspaceId,
+        expiresAt: rotated.expiresAt ?? creds.expiresAt,
+    };
+    if (deps.persist) {
+        try {
+            await deps.persist(next);
+        }
+        catch {
+            // A failed write shouldn't block the spawn; the rotated token is still
+            // used for this session, and a later launch re-attempts persistence.
+        }
+    }
+    return { creds: next, refreshed: true, warnings: [] };
+}
+//# sourceMappingURL=refresh.js.map

package/dist/upgrade.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `yagni upgrade` + the launch-time update nudge.
+ *
+ * npm is the only distribution channel, so "upgrade" means re-running the
+ * user's own global installer (`npm`/`pnpm`/`bun`, detected from where the
+ * running bin lives) against the published package. The nudge follows the
+ * desktop updater's posture: it must never cost anybody a launch. It reads
+ * only a local cache (`~/.yagni-code/update-check.json`) — zero network
+ * before the agent starts — and refreshes that cache in the background while
+ * the session runs, so the NEXT launch nudges from fresh data. Every network
+ * path fails soft to "say nothing".
+ *
+ * Set YAGNI_DISABLE_UPDATE_CHECK=1 to silence the nudge and the background
+ * check entirely (managed/enterprise environments); an explicit
+ * `yagni upgrade` still works there.
+ */
+export declare const PACKAGE_NAME: string;
+export declare const UPDATE_CHECK_DISABLE_ENV = "YAGNI_DISABLE_UPDATE_CHECK";
+export type InstallMethod = "npm" | "pnpm" | "bun";
+/**
+ * The CLI's own version, read from this package's package.json. Resolved
+ * relative to the module (src/ and dist/ both sit one level below the package
+ * root), so it is correct under tsx in tests and in the published tarball.
+ */
+export declare function currentCliVersion(): string;
+/** `"1"`/anything truthy disables; unset, empty, and `"0"` keep checks on. */
+export declare function updateChecksDisabled(env: NodeJS.ProcessEnv): boolean;
+/** Honors a private-registry override (proxy/mirror setups) like npm does. */
+export declare function registryUrl(env: NodeJS.ProcessEnv): string;
+/** Whether `candidate` is strictly newer than `current`. */
+export declare function isNewerVersion(current: string, candidate: string): boolean;
+/**
+ * Extract `dist-tags.latest` from a registry packument. Strict: this string
+ * gets printed to the terminal and interpolated into an install command, so
+ * anything that is not a plain version is treated as absent.
+ */
+export declare function parsePublishedVersion(body: unknown, tag: string): string | null;
+export declare function parseLatestVersion(body: unknown): string | null;
+export interface FetchLatestDeps {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** One fail-soft registry lookup: the latest published version, or null. */
+export declare function fetchLatestVersion(deps?: FetchLatestDeps): Promise<string | null>;
+export interface UpdateCache {
+    checkedAt: string;
+    latest: string;
+}
+export declare function updateCheckCachePath(): string;
+export declare function readUpdateCache(): Promise<UpdateCache | null>;
+export declare function writeUpdateCache(latest: string): Promise<void>;
+/** The one line the nudge is allowed, or null when there is nothing to say. */
+export declare function updateNudge(current: string, latest: string | null | undefined): string | null;
+export interface NudgeDeps {
+    current: string;
+    env?: NodeJS.ProcessEnv;
+    /** Where the nudge line goes; stderr so it never pollutes piped stdout. */
+    log?: (line: string) => void;
+    fetchLatest?: () => Promise<string | null>;
+}
+/**
+ * Print the (cache-backed) nudge, then kick off the background cache refresh.
+ * The caller awaits this function — a local file read — but must NOT await
+ * `refresh`; it completes during the session and is fire-and-forget.
+ */
+export declare function maybeNudgeAndRefresh(deps: NudgeDeps): Promise<{
+    nudged: boolean;
+    refresh: Promise<void>;
+}>;
+/**
+ * Which global installer owns the running bin, from its (real) path. The
+ * heuristic covers the three installers the package supports; `--method` is
+ * the escape hatch when a layout defeats it.
+ */
+export declare function detectInstallMethod(binPath: string): InstallMethod;
+export type ParsedUpgradeArgs = {
+    ok: true;
+    target?: string;
+    method?: InstallMethod;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseUpgradeArgs(args: string[]): ParsedUpgradeArgs;
+export interface UpgradeDeps {
+    current: string;
+    /** The running bin's path, for installer detection. */
+    binPath?: string;
+    env?: NodeJS.ProcessEnv;
+    fetchLatest?: () => Promise<string | null>;
+    runInstall?: (command: string, args: string[]) => Promise<number>;
+    log?: (line: string) => void;
+    logError?: (line: string) => void;
+}
+export declare function upgradeCommand(args: string[], deps: UpgradeDeps): Promise<number>;
+//# sourceMappingURL=upgrade.d.ts.map