/**
 * The account's Cleo Nexus projects by name (T13102): the list the guided
 * first run of `cleo login nexus` shows on a machine with no linked project,
 * and the name resolution behind `cleo cloud restore <name>`.
 *
 * - A project's display name is its plaintext label, else its id. Its
 *   `encryptedName` is NOT opened by default: the format is not specified yet
 *   (cleo-nexus T098: cipher, AAD with the key version, re-encryption on
 *   rotation), and nothing in CLEO writes it. A caller may pass `openName`
 *   (the seam the spec's reader will fill); a name that does not open falls
 *   back to the label with one warning and never fails the list.
 * - Names are matched exactly first, then case-insensitively, against the
 *   display name, the label and the id. One match restores; several are
 *   refused with the candidates listed (`E_NEXUS_PROJECT_AMBIGUOUS`); none is
 *   `E_NEXUS_PROJECT_NOT_FOUND`. A UUID is taken as an id without listing.
 * - Names and organization names from the server are shown with control,
 *   zero-width, separator and bidi characters removed; a listed id that is
 *   not a CLEO `ProjectId` is left out; commands quote every word for a POSIX
 *   shell, and the machine-read restore command names the immutable id.
 *
 * Every request is a `GET`. No function here logs, and no result or error
 * carries a key or a token.
 *
 * @task T13102
 * @epic T12322
 */
import type { CloudWarning, NexusNamedProject } from '@cleocode/contracts';
import { NexusAccountError } from './nexus-auth.js';
import { type NexusCloudProjectsOptions } from './nexus-cloud.js';
/** Warning code: some project names are encrypted and could not be opened on this device. */
export declare const W_NEXUS_PROJECT_NAME_LOCKED = "W_NEXUS_PROJECT_NAME_LOCKED";
/** Warning code: the server listed a project whose id is not a CLEO project id; it was left out. */
export declare const W_NEXUS_PROJECT_ID_INVALID = "W_NEXUS_PROJECT_ID_INVALID";
/** Opens one project's `encryptedName`; throws when it cannot. */
export type NexusProjectNameOpener = (projectId: string, encryptedName: string) => Promise<string>;
/** Options of {@link listNexusNamedProjects} and {@link resolveNexusProjectRef}. */
export interface NexusNamedProjectsOptions extends NexusCloudProjectsOptions {
    /** This machine's device id, to mark projects already here; `null`/absent marks none. */
    deviceId?: string | null;
    /**
     * Opener of `encryptedName`. None by default: the format is not specified yet
     * (cleo-nexus T098), so names show as their label or id until it is.
     */
    openName?: NexusProjectNameOpener;
}
/** The account's projects with display names. */
export interface NexusNamedProjectsResult {
    /** API origin asked. */
    apiUrl: string;
    /** Every visible project, newest first. */
    projects: NexusNamedProject[];
    /** The list stopped short (a server ceiling or the page budget): a project may be missing. */
    incomplete: boolean;
    /** Non-fatal problems. */
    warnings: CloudWarning[];
}
/** What a project reference resolved to. */
export interface NexusProjectRef {
    /** The server's project id. */
    projectId: string;
    /** The display name it matched, or `null` when it was taken as an id. */
    name: string | null;
    /** `id`: the reference was the project id; `name`: a name or label. */
    matchedBy: 'id' | 'name';
}
/** The candidates an ambiguous or missing reference reports (the envelope's `error.details`). */
export interface NexusProjectRefDetails {
    /** The reference given. */
    ref: string;
    /** The projects it matched, each with a by-id restore command. */
    candidates: NexusNamedProject[];
}
/**
 * A reference that matched several projects or none. `publicDetails` is
 * secret-free and the CLI forwards it as the envelope's `error.details`.
 */
export declare class NexusProjectRefError extends NexusAccountError {
    /** The reference and its candidates. */
    readonly publicDetails: NexusProjectRefDetails;
    /**
     * @param code - `E_NEXUS_PROJECT_AMBIGUOUS` or `E_NEXUS_PROJECT_NOT_FOUND`.
     * @param message - Human message.
     * @param fix - Remedy.
     * @param publicDetails - The reference and its candidates.
     */
    constructor(code: 'E_NEXUS_PROJECT_AMBIGUOUS' | 'E_NEXUS_PROJECT_NOT_FOUND', message: string, fix: string, publicDetails: NexusProjectRefDetails);
}
/**
 * A server-held name made safe to print: control and bidi-override characters removed.
 *
 * @param raw - Name as the server or the decryption gave it.
 * @returns The cleaned name, or `null` when nothing printable is left.
 */
export declare function safeNexusProjectName(raw: string | null | undefined): string | null;
/**
 * Quote a word for a POSIX shell (single quotes; `'` becomes `'\''`).
 *
 * @param word - The word.
 * @returns It unchanged when it needs no quoting, else single-quoted.
 */
export declare function shellQuoteWord(word: string): string;
/**
 * The projects a reference names: exact matches on the id, display name or
 * label first; when there are none, case-insensitive matches on the names.
 *
 * @param projects - The account's projects.
 * @param ref - A project name, label or id.
 * @returns Every match (one: resolved; several: ambiguous; none: not found).
 */
export declare function matchNexusProjects(projects: readonly NexusNamedProject[], ref: string): NexusNamedProject[];
/**
 * ` --api-url <origin>` when the origin is not the one a bare `cleo` command
 * would use (`$CLEO_NEXUS_API_URL`, else the default), so a printed command
 * reaches the same server.
 *
 * @param apiUrl - API origin.
 * @returns The flag with a leading space, or `''`.
 */
export declare function nexusApiUrlFlag(apiUrl: string): string;
/**
 * The exact `cleo cloud restore` command for a project, by its id: the id
 * never changes, while a name can be renamed or matched by a newer project
 * between printing and running (review LOW-4). For agents and scripts.
 *
 * @param project - The project (its id is a validated `ProjectId`).
 * @param apiUrl - API origin (added as `--api-url` when not the default).
 * @returns The command.
 */
export declare function nexusRestoreCommand(project: NexusNamedProject, apiUrl: string): string;
/**
 * The same restore by name, for a person to type: only when the name resolves
 * to this project alone and cannot be read as a flag or an id; else `null`.
 *
 * @param project - The project.
 * @param all - Every project of the account, for the uniqueness check.
 * @param apiUrl - API origin (added as `--api-url` when not the default).
 * @returns The command, or `null`.
 */
export declare function nexusRestoreByNameCommand(project: NexusNamedProject, all: readonly NexusNamedProject[], apiUrl: string): string | null;
/**
 * `GET /v1/projects` (E13, every page) with display names and, for each
 * project this machine can restore, the exact restore commands.
 *
 * @param opts - Device id, name opener, API URL, stores and test overrides.
 * @returns The named projects, whether the list is complete, and warnings.
 * @throws {NexusAccountError} When the list itself cannot be read.
 */
export declare function listNexusNamedProjects(opts?: NexusNamedProjectsOptions): Promise<NexusNamedProjectsResult>;
/**
 * Resolve a project name, label or id to the server's project id, for
 * `cleo cloud restore <name>`. A UUID is taken as the id without a request.
 *
 * @param ref - What the user typed.
 * @param opts - Name opener, API URL, stores and test overrides.
 * @returns The project id and how it matched.
 * @throws {NexusProjectRefError} `E_NEXUS_PROJECT_AMBIGUOUS` (the candidates
 *   are listed) or `E_NEXUS_PROJECT_NOT_FOUND`.
 * @throws {NexusAccountError} When the project list cannot be read.
 */
export declare function resolveNexusProjectRef(ref: string, opts?: NexusNamedProjectsOptions): Promise<NexusProjectRef>;
/**
 * Refuse to restore a project into a directory nested inside another CLEO
 * project (review LOW-5): `cleo cloud restore <name>` without `--into`
 * restores into the current directory, and from a subdirectory of a project
 * that would create a second project inside the first. The directory itself
 * may be a project root (the restore checks it holds the same project); the
 * home directory never counts as an enclosing project.
 *
 * @param into - The restore target; defaults to the current directory.
 * @throws {NexusAccountError} `E_NEXUS_VAULT_TARGET_OCCUPIED` naming the enclosing project.
 */
export declare function assertNexusRestoreTarget(into?: string): void;
//# sourceMappingURL=nexus-project-names.d.ts.map