@hyper.authio/cli 0.0.0-stage → 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Why the CLI stopped. Each one is a sentence the person can act on; the code is stable for scripts and agents.
+ */
+type AuthioCliErrorCode = "ticket_missing" | "ticket_invalid" | "verification_missing" | "verification_invalid" | "api_unreachable" | "api_error" | "rate_limited" | "plan_version_unsupported" | "plan_path_invalid" | "project_not_found" | "stack_not_detected" | "pages_router_unsupported" | "nextauth_v4_unsupported" | "confirmation_required" | "invalid_arguments";
+/**
+ * An error the CLI raises on purpose: printed as its message, never as a stack, and mapped to exit code 1.
+ */
+declare class AuthioCliError extends Error {
+    /** What went wrong, stable across versions. */
+    readonly code: AuthioCliErrorCode;
+    /** The process exit code the CLI ends with. */
+    readonly exitCode: number;
+    constructor(code: AuthioCliErrorCode, message: string, options?: {
+        cause?: unknown;
+        exitCode?: number;
+    });
+}
+
+/** The API address the CLI talks to when `--api` is not given: the shared Authio platform. */
+declare const DEFAULT_API = "https://authio.api.hyperio.tech";
+/** The command line, read. */
+interface CliArguments {
+    /** `init`, `verify`, `help` or `version`. */
+    command: "init" | "verify" | "help" | "version";
+    ticket: string | undefined;
+    verification: string | undefined;
+    api: string | undefined;
+    cwd: string | undefined;
+    dryRun: boolean;
+    yes: boolean;
+    wait: boolean;
+}
+/**
+ * Reads `process.argv.slice(2)`. Accepts `--name value` and `--name=value`; refuses anything it does not know, so a
+ * typo never silently turns into the default.
+ */
+declare function parseArguments(argv: readonly string[]): CliArguments;
+/** The API address with no trailing slash, refusing anything that is not http(s). */
+declare function apiAddress(api: string | undefined): string;
+
+/**
+ * Everything the commands do outside their own logic: the network, the terminal and running a program. Injected, so
+ * every decision is testable without either.
+ */
+interface CliIo {
+    /** The `fetch` to call Authio with. */
+    fetch: typeof fetch;
+    /** Prints one line. */
+    print(line: string): void;
+    /** Asks a yes/no question; `defaultYes` is the answer to an empty line. */
+    confirm(question: string, defaultYes: boolean): Promise<boolean>;
+    /** Asks for a value without echoing what is typed. */
+    promptSecret(question: string): Promise<string>;
+    /** Runs a program in `cwd`, inheriting the terminal; resolves with its exit code. */
+    run(command: string, args: readonly string[], cwd: string): Promise<number>;
+    /** Whether a person can answer questions (stdin and stdout are a terminal). */
+    isInteractive: boolean;
+    /** The clock, in milliseconds. */
+    now(): number;
+    /** Waits. */
+    sleep(milliseconds: number): Promise<void>;
+}
+/**
+ * The command line `cmd.exe` runs for a program and its arguments, each argument in double quotes. Windows needs a shell
+ * to start `npm.cmd` and friends, and handing `spawn` one string (rather than arguments with `shell: true`) is what
+ * Node accepts without DEP0190. Inside quotes `cmd.exe` keeps `^`, so `pkg@^6.0.2` keeps its range.
+ */
+declare function windowsCommandLine(command: string, args: readonly string[]): string;
+/** The real terminal, network and process. */
+declare function createTerminalIo(): CliIo;
+
+/** The package managers the CLI installs with, named after their lockfile. */
+type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+/** What the CLI read from the project, without the network. */
+interface DetectedProject {
+    /** The project folder. */
+    root: string;
+    /** The major of the `next` dependency. */
+    nextMajor: number;
+    /** Whether the app lives under `src/` (`src/app`), where Next.js then expects `auth.ts` and `proxy.ts` too. */
+    srcDir: boolean;
+    /** The package manager, from the lockfile; `npm` when there is none. */
+    packageManager: PackageManager;
+    /** The port the `dev` script serves on: `-p N`/`--port N`, else 3000. */
+    devPort: number;
+}
+/**
+ * Reads the project the plan is applied to and stops, before any network call, when it is not one the plan fits: no
+ * `package.json`, no `next`, the pages router only, or NextAuth v4 already installed.
+ */
+declare function detectProject(root: string): DetectedProject;
+
+/** The plan versions this CLI knows how to apply. */
+declare const SUPPORTED_PLAN_VERSIONS: readonly number[];
+/** A package the plan installs. */
+interface IntegrationPackage {
+    name: string;
+    version: string;
+}
+/** A file the plan writes; `source` files go under `src/` when the project has it. */
+interface IntegrationFile {
+    path: string;
+    root: "source" | "project";
+    content: string;
+}
+/** An environment variable: its value comes in the plan, is typed by the person, or is generated on the machine. */
+interface IntegrationEnvironmentVariable {
+    name: string;
+    value?: string | null;
+    source: "plan" | "secret" | "generate";
+    comment?: string | null;
+}
+/** The integration plan Authio hands out for one client and one stack. It never carries the client secret. */
+interface IntegrationPlan {
+    stack: string;
+    planVersion: number;
+    issuer: string;
+    realm: string;
+    client: string;
+    clientActive: boolean;
+    packages: IntegrationPackage[];
+    files: IntegrationFile[];
+    environment: IntegrationEnvironmentVariable[];
+    redirectUris: string[];
+    callbackPath: string;
+}
+/** One file of the plan, placed in the project. */
+interface PlannedFile {
+    /** The path relative to the project, with forward slashes. */
+    path: string;
+    /** The absolute path. */
+    target: string;
+    content: string;
+    /** `create` when the file does not exist; `merge` when it does and is left alone for the person to merge. */
+    action: "create" | "merge";
+}
+/** What applying the plan would do to this project. */
+interface PlannedChanges {
+    files: PlannedFile[];
+    /** The variables `.env.local` does not have yet; the ones it has are kept. */
+    environment: IntegrationEnvironmentVariable[];
+    /** The variables `.env.local` already has, kept as they are. */
+    keptEnvironment: string[];
+    /** The redirect the app will use locally. */
+    localRedirect: string;
+    /** Whether that redirect is registered on the client. */
+    redirectRegistered: boolean;
+}
+/**
+ * Reads the plan as the API sends it. The API writes enum members by name (`Source`, `Plan`), the way every Authio
+ * response does, and leaves empty lists as `null`; the CLI compares in lower case and always has lists, so both
+ * spellings of a value apply the same.
+ */
+declare function normalizePlan(plan: IntegrationPlan): IntegrationPlan;
+/** Refuses a plan this CLI does not know how to apply, before anything is written. */
+declare function assertPlanVersion(plan: IntegrationPlan): void;
+/** The keys an env file already defines. */
+declare function readEnvKeys(path: string): Set<string>;
+/** The variable Auth.js builds its own addresses from: in `.env.local`, where the app runs on this machine. */
+declare const LOCAL_ORIGIN_VARIABLE = "AUTH_URL";
+/** The address the app is served from on this machine, from the `dev` script's port. */
+declare function localOrigin(project: DetectedProject): string;
+/**
+ * Works out, without writing, what applying the plan does to this project.
+ *
+ * `.env.local` is the development environment, so `AUTH_URL` there is the local address the `dev` script serves on,
+ * not the address the plan derives from the client's first redirect (often the production one): with that, Auth.js would
+ * send every sign-in on this machine back to the deployed app.
+ */
+declare function planChanges(project: DetectedProject, plan: IntegrationPlan): PlannedChanges;
+
+/** The paths the CLI writes that must never be committed. */
+declare const IGNORED_PATHS: readonly [".env.local", ".authio/"];
+/** The paths of {@link IGNORED_PATHS} the `.gitignore` at `path` does not cover yet. */
+declare function uncoveredPaths(path: string): string[];
+
+/** What redeeming a code answers: the plan, and the code that later confirms the first sign-in. */
+interface IntegrationRedemption {
+    plan: IntegrationPlan;
+    verification: string;
+    verificationExpiresAt: string;
+}
+/** Whether the client has had a successful sign-in since the code was redeemed. */
+interface IntegrationVerification {
+    signedIn: boolean;
+    firstSignInAt: string | null;
+}
+/** Exchanges the one-time code for the plan. The code is used up, whatever happens next. */
+declare function redeemTicket(fetcher: typeof fetch, api: string, ticket: string, nextMajor: number): Promise<IntegrationRedemption>;
+/** Asks whether the first sign-in has arrived. The verification code may be used until it expires. */
+declare function checkVerification(fetcher: typeof fetch, api: string, verification: string): Promise<IntegrationVerification>;
+
+/** The options of `authio init`. */
+interface InitOptions {
+    /** The one-time code from the client's guide. */
+    ticket: string | undefined;
+    /** The API address, already normalised. */
+    api: string;
+    /** The project folder. */
+    cwd: string;
+    /** Show the plan without writing, installing or asking for secrets. */
+    dryRun: boolean;
+    /** Answer yes to every question. */
+    yes: boolean;
+}
+/** What `authio init` did. */
+interface InitResult {
+    /** 0 when the plan was applied (or shown, with `dryRun`), 2 when the person declined. */
+    exitCode: number;
+    /** The files created, relative to the project. */
+    created: string[];
+    /** The files that already existed and are left for the person to merge. */
+    toMerge: string[];
+    /** The variables added to `.env.local`. */
+    addedEnvironment: string[];
+    /** The `secret` variables written empty, for the person to fill. */
+    emptySecrets: string[];
+    /** The plan, as redeemed. */
+    plan: IntegrationPlan | undefined;
+}
+/** The file `verify` reads the verification from. */
+declare const VERIFICATION_FILE: string;
+/** The command that installs `specs` with `manager`. */
+declare function installCommand(manager: PackageManager, specs: readonly string[]): [string, string[]];
+/**
+ * `authio init`: reads the project, exchanges the code for the plan and applies it, never overwriting a file, never
+ * committing, asking before writing and for each secret in a hidden prompt.
+ */
+declare function runInit(options: InitOptions, io: CliIo): Promise<InitResult>;
+
+/** The options of `authio verify`. */
+interface VerifyOptions {
+    /** The verification code; when absent, the one `init` saved in `.authio/verification`. */
+    verification: string | undefined;
+    /** The API address given on the command line, already normalised; the saved one wins when it is absent. */
+    api: string | undefined;
+    /** The address used when neither is given. */
+    defaultApi: string;
+    /** The project folder. */
+    cwd: string;
+    /** Keep checking until the first sign-in arrives or the verification expires. */
+    wait: boolean;
+}
+/** What `authio verify` found. */
+interface VerifyResult {
+    /** 0 when the first sign-in arrived, 2 when it has not yet. */
+    exitCode: number;
+    firstSignInAt: string | null;
+}
+/** How often `--wait` asks again. */
+declare const VERIFY_INTERVAL_MS = 3000;
+/**
+ * `authio verify`: asks Authio whether the client has had a successful sign-in since `init` redeemed the code. With
+ * `wait`, asks every three seconds until it has or the verification expires.
+ */
+declare function runVerify(options: VerifyOptions, io: CliIo): Promise<VerifyResult>;
+
+/**
+ * Runs the CLI with `argv` (without the node and script paths) and answers the exit code. Errors the CLI raises on
+ * purpose are printed as their message; anything else is printed with its stack, since it is a bug.
+ */
+declare function main(argv: readonly string[], io: CliIo, environment: Record<string, string | undefined>, version: string): Promise<number>;
+
+export { AuthioCliError, type AuthioCliErrorCode, type CliArguments, type CliIo, DEFAULT_API, type DetectedProject, IGNORED_PATHS, type InitOptions, type InitResult, type IntegrationEnvironmentVariable, type IntegrationFile, type IntegrationPackage, type IntegrationPlan, type IntegrationRedemption, type IntegrationVerification, LOCAL_ORIGIN_VARIABLE, type PackageManager, type PlannedChanges, type PlannedFile, SUPPORTED_PLAN_VERSIONS, VERIFICATION_FILE, VERIFY_INTERVAL_MS, type VerifyOptions, type VerifyResult, apiAddress, assertPlanVersion, checkVerification, createTerminalIo, detectProject, installCommand, localOrigin, main, normalizePlan, parseArguments, planChanges, readEnvKeys, redeemTicket, runInit, runVerify, uncoveredPaths, windowsCommandLine };