t3code-cli 0.10.0 → 0.12.0

package/src/auth/layer.ts

@@ -1,13 +1,23 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 
-import { T3Config } from "../config/service.ts";
+import {
+  defaultEnvironmentNameForLocal,
+  defaultEnvironmentNameFromUrl,
+} from "../config/environment-name/name.ts";
+import type { EnvironmentSummary, ResolvedConfig } from "../config/types.ts";
+import type { ConfigError } from "../config/error.ts";
+import type { UrlError } from "../config/url/error.ts";
+import { T3Config } from "../config/config.ts";
 import { AuthConfigError } from "./error.ts";
 import { T3LocalAuth } from "./local.ts";
 import { T3AuthPairing } from "./pairing.ts";
 import { T3Auth } from "./service.ts";
 import { T3AuthTransport } from "./transport.ts";
-import type { AuthConfigInput } from "./type.ts";
+import type { AuthConfigInput, AuthEnvironmentListItem, AuthResolvedConfig } from "./type.ts";
+
+const mapConfigError = (error: ConfigError | UrlError) =>
+  new AuthConfigError({ message: error.message, cause: error });
 
 export const makeT3Auth = Effect.fn("makeT3Auth")(function* () {
   const config = yield* T3Config;
@@ -16,58 +26,130 @@ export const makeT3Auth = Effect.fn("makeT3Auth")(function* () {
   const pairing = yield* T3AuthPairing;
 
   const status = Effect.fn("T3AuthLive.status")(function* () {
-    const resolved = yield* config.resolve().pipe(
-      Effect.catchTags({
-        ConfigError: (error) =>
-          Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
-        UrlError: (error) =>
-          Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
-      }),
-    );
-    return yield* transport.getSession(resolved);
+    const resolved = yield* config.resolve().pipe(Effect.mapError(mapConfigError));
+    const session = yield* transport.getSession(resolved);
+    return { config: toAuthResolvedConfig(resolved), session } as const;
   });
 
   const issueWebSocketTicket = Effect.fn("T3AuthLive.issueWebSocketTicket")(function* () {
-    const resolved = yield* config.resolve().pipe(
-      Effect.catchTags({
-        ConfigError: (error) =>
-          Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
-        UrlError: (error) =>
-          Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
-      }),
-    );
+    const resolved = yield* config.resolve().pipe(Effect.mapError(mapConfigError));
     return yield* transport.issueWebSocketTicket(resolved);
   });
 
-  const writeConfig = Effect.fn("T3AuthLive.writeConfig")(function* (input: AuthConfigInput) {
-    const existing = yield* config.readStored().pipe(
-      Effect.catchTags({
-        ConfigError: (error) =>
-          Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
-      }),
-    );
+  const persistEnvironment = Effect.fn("T3AuthLive.persistEnvironment")(function* (input: {
+    readonly name: string;
+    readonly url: string;
+    readonly token: string;
+    readonly local: boolean;
+    readonly replace?: boolean;
+    readonly allowReplace: boolean;
+  }) {
+    const exists = yield* config.hasEnvironment(input.name).pipe(Effect.mapError(mapConfigError));
+    if (exists && !input.allowReplace) {
+      return yield* Effect.fail(
+        new AuthConfigError({
+          message: `environment '${input.name}' already exists: pass --replace`,
+        }),
+      );
+    }
+    const makeDefault = exists && input.replace === true;
     yield* config
-      .writeStored({
-        ...existing,
+      .upsertEnvironment({
+        name: input.name,
         url: input.url,
         token: input.token,
-        ...(input.local !== undefined ? { local: input.local } : {}),
+        local: input.local,
+        ...(makeDefault ? { makeDefault: true } : {}),
       })
-      .pipe(
-        Effect.catchTags({
-          ConfigError: (error) =>
-            Effect.fail(new AuthConfigError({ message: "auth config failed", cause: error })),
+      .pipe(Effect.mapError(mapConfigError));
+    return input.name;
+  });
+
+  const listEnvironments = Effect.fn("T3AuthLive.listEnvironments")(function* () {
+    const [environments, activeName] = yield* Effect.all(
+      [config.listEnvironments(), config.resolveActiveEnvironmentName()],
+      { concurrency: "unbounded" },
+    ).pipe(Effect.mapError(mapConfigError));
+    return environments.map((environment) => toAuthEnvironmentListItem(environment, activeName));
+  });
+
+  const resolveUnpairTarget = Effect.fn("T3AuthLive.resolveUnpairTarget")(function* (input: {
+    readonly name?: string;
+  }) {
+    if (input.name !== undefined && input.name.length > 0) {
+      return input.name;
+    }
+    const defaultName = yield* config
+      .getDefaultEnvironmentName()
+      .pipe(Effect.mapError(mapConfigError));
+    if (defaultName === undefined) {
+      return yield* Effect.fail(
+        new AuthConfigError({
+          message: "no environment selected: pass --name or run: t3cli env use <name>",
         }),
       );
+    }
+    return defaultName;
   });
 
   return {
     pair: pairing.pair,
     local: localAuth.local,
-    writeConfig,
+    writeConfig: (input: AuthConfigInput) =>
+      config
+        .upsertEnvironment({
+          name: input.name,
+          url: input.url,
+          token: input.token,
+          local: input.local,
+          ...(input.makeDefault === true ? { makeDefault: true } : {}),
+        })
+        .pipe(Effect.mapError(mapConfigError)),
+    persistEnvironment,
+    environmentExists: (name: string) =>
+      config.hasEnvironment(name).pipe(Effect.mapError(mapConfigError)),
+    defaultNameFromUrl: (url: string) =>
+      defaultEnvironmentNameFromUrl(url).pipe(Effect.mapError(mapConfigError)),
+    defaultNameForLocal: () => Effect.succeed(defaultEnvironmentNameForLocal()),
+    listEnvironments,
+    useEnvironment: (name: string) =>
+      config
+        .setDefaultEnvironment(name)
+        .pipe(Effect.mapError(mapConfigError), Effect.as({ name, default: true as const })),
+    resolveUnpairTarget,
+    unpairEnvironment: (input: { readonly name: string }) =>
+      config
+        .removeEnvironment(input.name)
+        .pipe(
+          Effect.mapError(mapConfigError),
+          Effect.as({ name: input.name, removed: true as const }),
+        ),
     status,
     issueWebSocketTicket,
   };
 });
 
 export const T3AuthLive = Layer.effect(T3Auth, makeT3Auth());
+
+function toAuthResolvedConfig(config: ResolvedConfig): AuthResolvedConfig {
+  return {
+    url: config.url,
+    token: config.token,
+    source: config.source,
+    local: config.local,
+    ...(config.environment !== undefined ? { environment: config.environment } : {}),
+  };
+}
+
+function toAuthEnvironmentListItem(
+  environment: EnvironmentSummary,
+  activeName: string | undefined,
+): AuthEnvironmentListItem {
+  return {
+    name: environment.name,
+    url: environment.url,
+    local: environment.local,
+    default: environment.default,
+    active: environment.name === activeName,
+  };
+}

package/src/auth/local-base-dir.ts

@@ -1,17 +1,24 @@
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 
-import { Environment } from "../environment/service.ts";
-import { resolveT3BaseDir } from "../layout/base-dir.ts";
+import type { CliRuntime } from "../cli/runtime/service.ts";
+import type { T3CliEnvShape } from "../config/env/env.ts";
+import { resolveT3BaseDir } from "../config/env/layout.ts";
 
 export const resolveLocalBaseDir = Effect.fn("resolveLocalBaseDir")(function* (input: {
   readonly baseDir?: string | undefined;
+  readonly cliRuntime: CliRuntime["Service"];
+  readonly t3CliEnv: T3CliEnvShape;
 }) {
-  const environment = yield* Environment;
+  const homeDir = yield* Option.match(input.t3CliEnv.home, {
+    onNone: () => Effect.die("HOME is not set"),
+    onSome: Effect.succeed,
+  });
   return yield* resolveT3BaseDir({
     layout: {
-      cwd: environment.cwd,
-      homeDir: environment.homeDir,
-      t3codeHome: environment.env["T3CODE_HOME"],
+      cwd: input.cliRuntime.cwd,
+      homeDir,
+      t3codeHome: Option.getOrUndefined(input.t3CliEnv.t3codeHome),
     },
     baseDir: input.baseDir,
   });

package/src/auth/local-origin.ts

@@ -4,8 +4,9 @@ import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 
-import { normalizeHttpBaseUrl } from "../config/url.ts";
-import { Environment } from "../environment/service.ts";
+import { normalizeHttpBaseUrl } from "../config/url/url.ts";
+import { loadT3CliEnv } from "../config/env/env.ts";
+import { CliRuntime } from "../cli/runtime/service.ts";
 import { AuthLocalError } from "./error.ts";
 import { resolveLocalBaseDir } from "./local-base-dir.ts";
 import { decodeAuthLocalRuntimeStateFromJson } from "./schema.ts";
@@ -21,15 +22,17 @@ export class T3LocalAuthOrigin extends Context.Service<
 export const makeT3LocalAuthOrigin = Effect.fn("makeT3LocalAuthOrigin")(function* () {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const environment = yield* Environment;
+  const cliRuntime = yield* CliRuntime;
+  const t3CliEnv = yield* loadT3CliEnv;
 
   const resolve = Effect.fn("T3LocalAuthOriginLive.resolve")(function* (
     input?: LocalAuthOriginInput,
   ) {
-    const baseDir = yield* resolveLocalBaseDir({ baseDir: input?.baseDir }).pipe(
-      Effect.provideService(Environment, environment),
-      Effect.provideService(Path.Path, path),
-    );
+    const baseDir = yield* resolveLocalBaseDir({
+      baseDir: input?.baseDir,
+      cliRuntime,
+      t3CliEnv,
+    }).pipe(Effect.provideService(Path.Path, path));
     if (input?.origin !== undefined) {
       return yield* normalizeLocalOrigin(input.origin);
     }

package/src/auth/local-token.ts

@@ -2,7 +2,7 @@ import {
   AuthAdministrativeScopes,
   AuthSessionId,
   type AuthEnvironmentScope,
-} from "#t3tools/contracts";
+} from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
@@ -15,7 +15,8 @@ import * as Path from "effect/Path";
 import * as Predicate from "effect/Predicate";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
-import { Environment } from "../environment/service.ts";
+import { loadT3CliEnv } from "../config/env/env.ts";
+import { CliRuntime } from "../cli/runtime/service.ts";
 import { SqlClientFactory } from "../sql/service.ts";
 import {
   AuthLocalDatabaseError,
@@ -38,7 +39,8 @@ export class T3LocalAuthToken extends Context.Service<
 export const makeT3LocalAuthToken = Effect.fn("makeT3LocalAuthToken")(function* () {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const environment = yield* Environment;
+  const cliRuntime = yield* CliRuntime;
+  const t3CliEnv = yield* loadT3CliEnv;
   const crypto = yield* Crypto.Crypto;
   const sqlClientFactory = yield* SqlClientFactory;
 
@@ -100,14 +102,15 @@ export const makeT3LocalAuthToken = Effect.fn("makeT3LocalAuthToken")(function*
 
   function openAuthDatabase(dbPath: string) {
     return sqlClientFactory.sqliteClient({ filename: dbPath }).pipe(
-      Effect.catchTag("SqlError", (error) =>
-        Effect.fail(
-          new AuthLocalDatabaseError({
-            operation: "connect",
-            message: error.message,
-          }),
-        ),
-      ),
+      Effect.catchTags({
+        SqlError: (error) =>
+          Effect.fail(
+            new AuthLocalDatabaseError({
+              operation: "connect",
+              message: error.message,
+            }),
+          ),
+      }),
     );
   }
 
@@ -157,14 +160,15 @@ export const makeT3LocalAuthToken = Effect.fn("makeT3LocalAuthToken")(function*
       expiresAt: DateTime.formatIso(expiresAt),
     }).pipe(
       provideAuthDatabase(input.dbPath),
-      Effect.catchTag("SqlError", (error) =>
-        Effect.fail(
-          new AuthLocalDatabaseError({
-            operation: Predicate.isTagged(error.reason, "ConnectionError") ? "connect" : "query",
-            message: error.message,
-          }),
-        ),
-      ),
+      Effect.catchTags({
+        SqlError: (error) =>
+          Effect.fail(
+            new AuthLocalDatabaseError({
+              operation: Predicate.isTagged(error.reason, "ConnectionError") ? "connect" : "query",
+              message: error.message,
+            }),
+          ),
+      }),
     );
     return {
       token,
@@ -185,10 +189,11 @@ export const makeT3LocalAuthToken = Effect.fn("makeT3LocalAuthToken")(function*
       );
     }
 
-    const baseDir = yield* resolveLocalBaseDir({ baseDir: input.baseDir }).pipe(
-      Effect.provideService(Environment, environment),
-      Effect.provideService(Path.Path, path),
-    );
+    const baseDir = yield* resolveLocalBaseDir({
+      baseDir: input.baseDir,
+      cliRuntime,
+      t3CliEnv,
+    }).pipe(Effect.provideService(Path.Path, path));
     const session = yield* issueLocalDatabaseSession({
       dbPath: path.join(baseDir, "userdata", "state.sqlite"),
       secretsDir: path.join(baseDir, "userdata", "secrets"),

package/src/auth/service.test.ts

@@ -0,0 +1,200 @@
+import "vite-plus/test/config";
+
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { assert, describe, it } from "@effect/vitest";
+
+import { T3Auth } from "./service.ts";
+import { StoredConfigV2FileJson } from "../config/persist/schema.ts";
+import { ConfigPlatformLayer } from "../config/platform.test-utils.ts";
+import { makeTempHomeScoped } from "../config/temp-home.test-utils.ts";
+import { t3AuthDepsLayer } from "./layer.test-utils.ts";
+
+describe("T3Auth persistence", () => {
+  it.effect("fails to persist a duplicate environment without allowReplace", () =>
+    Effect.gen(function* () {
+      return yield* makeTempHomeScoped("t3cli-auth-");
+    }).pipe(
+      Effect.flatMap((homeDir) =>
+        Effect.gen(function* () {
+          const auth = yield* T3Auth;
+          yield* auth.persistEnvironment({
+            name: "work",
+            url: "https://work.example",
+            token: "work-token",
+            local: false,
+            allowReplace: true,
+          });
+          const result = yield* auth
+            .persistEnvironment({
+              name: "work",
+              url: "https://work.example",
+              token: "work-token-2",
+              local: false,
+              allowReplace: false,
+            })
+            .pipe(Effect.exit);
+          assert.equal(Exit.isFailure(result), true);
+        }).pipe(Effect.provide(t3AuthDepsLayer(homeDir))),
+      ),
+      Effect.provide(ConfigPlatformLayer),
+      Effect.scoped,
+    ),
+  );
+
+  it.effect("does not change default when replace is used for a new environment", () =>
+    Effect.gen(function* () {
+      return yield* makeTempHomeScoped("t3cli-auth-");
+    }).pipe(
+      Effect.flatMap((homeDir) =>
+        Effect.gen(function* () {
+          const auth = yield* T3Auth;
+          yield* auth.persistEnvironment({
+            name: "home",
+            url: "https://home.example",
+            token: "home-token",
+            local: false,
+            allowReplace: true,
+          });
+          yield* auth.persistEnvironment({
+            name: "work",
+            url: "https://work.example",
+            token: "work-token",
+            local: false,
+            replace: true,
+            allowReplace: true,
+          });
+          const listed = yield* auth.listEnvironments();
+          assert.equal(listed.find((environment) => environment.name === "home")?.default, true);
+          assert.equal(listed.find((environment) => environment.name === "work")?.default, false);
+        }).pipe(Effect.provide(t3AuthDepsLayer(homeDir))),
+      ),
+      Effect.provide(ConfigPlatformLayer),
+      Effect.scoped,
+    ),
+  );
+
+  it.effect("promotes default when replacing an existing environment with replace", () =>
+    Effect.gen(function* () {
+      return yield* makeTempHomeScoped("t3cli-auth-");
+    }).pipe(
+      Effect.flatMap((homeDir) =>
+        Effect.gen(function* () {
+          const auth = yield* T3Auth;
+          yield* auth.persistEnvironment({
+            name: "home",
+            url: "https://home.example",
+            token: "home-token",
+            local: false,
+            allowReplace: true,
+          });
+          yield* auth.persistEnvironment({
+            name: "work",
+            url: "https://work.example",
+            token: "work-token",
+            local: false,
+            allowReplace: true,
+          });
+          yield* auth.persistEnvironment({
+            name: "work",
+            url: "https://work.example",
+            token: "work-token-2",
+            local: false,
+            replace: true,
+            allowReplace: true,
+          });
+          const listed = yield* auth.listEnvironments();
+          assert.equal(listed.find((environment) => environment.name === "work")?.default, true);
+        }).pipe(Effect.provide(t3AuthDepsLayer(homeDir))),
+      ),
+      Effect.provide(ConfigPlatformLayer),
+      Effect.scoped,
+    ),
+  );
+
+  it.effect("lists environments without decrypting tokens", () =>
+    Effect.gen(function* () {
+      return yield* makeTempHomeScoped("t3cli-auth-");
+    }).pipe(
+      Effect.flatMap((homeDir) =>
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const configPath = path.join(homeDir, ".config", "t3cli", "config.json");
+
+          yield* Effect.gen(function* () {
+            const auth = yield* T3Auth;
+            yield* auth.persistEnvironment({
+              name: "home",
+              url: "https://home.example",
+              token: "home-token",
+              local: false,
+              allowReplace: true,
+            });
+            yield* auth.persistEnvironment({
+              name: "work",
+              url: "https://work.example",
+              token: "work-token",
+              local: false,
+              allowReplace: true,
+            });
+          }).pipe(Effect.provide(t3AuthDepsLayer(homeDir)));
+
+          const raw = yield* fs.readFileString(configPath);
+          const parsed = yield* Schema.decodeUnknownEffect(StoredConfigV2FileJson)(raw);
+          const homeEnvironment = parsed.environments.home;
+          assert.isDefined(homeEnvironment);
+          const corrupted = yield* Schema.encodeEffect(StoredConfigV2FileJson)({
+            ...parsed,
+            environments: {
+              ...parsed.environments,
+              home: {
+                ...homeEnvironment,
+                token: {
+                  ...homeEnvironment.token,
+                  tag: "AAAAAAAAAAAAAAAAAAAAAA==",
+                },
+              },
+            },
+          });
+          yield* fs.writeFileString(configPath, `${corrupted}\n`, { mode: 0o600 });
+
+          yield* Effect.gen(function* () {
+            const auth = yield* T3Auth;
+            const listed = yield* auth.listEnvironments();
+            assert.equal(listed.length, 2);
+            assert.equal(listed.find((environment) => environment.name === "home")?.active, true);
+          }).pipe(Effect.provide(t3AuthDepsLayer(homeDir)));
+        }),
+      ),
+      Effect.provide(ConfigPlatformLayer),
+      Effect.scoped,
+    ),
+  );
+
+  it.effect("resolves unpair target from encrypted default metadata", () =>
+    Effect.gen(function* () {
+      return yield* makeTempHomeScoped("t3cli-auth-");
+    }).pipe(
+      Effect.flatMap((homeDir) =>
+        Effect.gen(function* () {
+          const auth = yield* T3Auth;
+          yield* auth.persistEnvironment({
+            name: "home",
+            url: "https://home.example",
+            token: "home-token",
+            local: false,
+            allowReplace: true,
+          });
+          const target = yield* auth.resolveUnpairTarget({});
+          assert.equal(target, "home");
+        }).pipe(Effect.provide(t3AuthDepsLayer(homeDir))),
+      ),
+      Effect.provide(ConfigPlatformLayer),
+      Effect.scoped,
+    ),
+  );
+});

package/src/auth/service.ts

@@ -1,9 +1,19 @@
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
 
-import type { AuthSessionState, AuthWebSocketTicketResult } from "./schema.ts";
+import type { AuthWebSocketTicketResult } from "./schema.ts";
 import type { AuthError } from "./error.ts";
-import type { AuthConfigInput, LocalAuthInput, LocalAuthResult, PairResult } from "./type.ts";
+import type {
+  AuthConfigInput,
+  AuthEnvironmentListItem,
+  AuthStatusResult,
+  AuthUnpairResult,
+  AuthUseResult,
+  LocalAuthInput,
+  LocalAuthResult,
+  PairResult,
+  PersistEnvironmentInput,
+} from "./type.ts";
 
 export class T3Auth extends Context.Service<
   T3Auth,
@@ -11,7 +21,21 @@ export class T3Auth extends Context.Service<
     readonly pair: (value: string) => Effect.Effect<PairResult, AuthError>;
     readonly local: (input: LocalAuthInput) => Effect.Effect<LocalAuthResult, AuthError>;
     readonly writeConfig: (input: AuthConfigInput) => Effect.Effect<void, AuthError>;
-    readonly status: () => Effect.Effect<AuthSessionState, AuthError>;
+    readonly persistEnvironment: (
+      input: PersistEnvironmentInput,
+    ) => Effect.Effect<string, AuthError>;
+    readonly environmentExists: (name: string) => Effect.Effect<boolean, AuthError>;
+    readonly defaultNameFromUrl: (url: string) => Effect.Effect<string, AuthError>;
+    readonly defaultNameForLocal: () => Effect.Effect<string, AuthError>;
+    readonly listEnvironments: () => Effect.Effect<readonly AuthEnvironmentListItem[], AuthError>;
+    readonly useEnvironment: (name: string) => Effect.Effect<AuthUseResult, AuthError>;
+    readonly unpairEnvironment: (input: {
+      readonly name: string;
+    }) => Effect.Effect<AuthUnpairResult, AuthError>;
+    readonly resolveUnpairTarget: (input: {
+      readonly name?: string;
+    }) => Effect.Effect<string, AuthError>;
+    readonly status: () => Effect.Effect<AuthStatusResult, AuthError>;
     readonly issueWebSocketTicket: () => Effect.Effect<AuthWebSocketTicketResult, AuthError>;
   }
 >()("t3cli/T3Auth") {}

package/src/auth/transport.ts

@@ -2,14 +2,14 @@ import {
   AuthAccessTokenType,
   AuthEnvironmentBootstrapTokenType,
   AuthTokenExchangeGrantType,
-} from "#t3tools/contracts";
+} from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { HttpClient, HttpClientError, HttpClientRequest } from "effect/unstable/http";
 
-import { toHttpEndpointUrl } from "../config/url.ts";
+import { toHttpEndpointUrl } from "../config/url/url.ts";
 import { AuthTransportError } from "./error.ts";
 import {
   type AuthBearerBootstrapResult,

package/src/auth/type.ts

@@ -1,4 +1,5 @@
 import type { AuthBearerBootstrapResult } from "./schema.ts";
+import type { AuthSessionState } from "./schema.ts";
 
 export type AuthSessionRole = AuthBearerBootstrapResult["role"];
 
@@ -8,9 +9,44 @@ export type PairingUrl = {
 };
 
 export type AuthConfigInput = {
+  readonly name: string;
   readonly url: string;
   readonly token: string;
-  readonly local?: boolean;
+  readonly local: boolean;
+  readonly makeDefault?: boolean;
+};
+
+export type PersistEnvironmentInput = {
+  readonly name: string;
+  readonly url: string;
+  readonly token: string;
+  readonly local: boolean;
+  readonly replace?: boolean;
+  readonly allowReplace: boolean;
+};
+
+export type AuthResolvedConfig = {
+  readonly url: string;
+  readonly token: string;
+  readonly source: "env" | "config";
+  readonly local: boolean;
+  readonly environment?: string;
+};
+
+export type AuthEnvironmentSummary = {
+  readonly name: string;
+  readonly url: string;
+  readonly local: boolean;
+  readonly default: boolean;
+};
+
+export type AuthStatusResult = {
+  readonly config: AuthResolvedConfig;
+  readonly session: AuthSessionState;
+};
+
+export type AuthEnvironmentListItem = AuthEnvironmentSummary & {
+  readonly active: boolean;
 };
 
 export type PairResult = {
@@ -51,3 +87,13 @@ export type LocalAuthResult = {
   readonly source: "local";
   readonly baseDir: string;
 };
+
+export type AuthUseResult = {
+  readonly name: string;
+  readonly default: true;
+};
+
+export type AuthUnpairResult = {
+  readonly name: string;
+  readonly removed: true;
+};