@nesalia/cli 1.0.0

package/src/index.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { login, status, logout } from "./commands/index.js";
+
+const program = new Command();
+
+program
+  .name("nesalia")
+  .version("1.0.0")
+  .description("@nesalia/cli — Manage your account authentication");
+
+program
+  .command("auth", { isDefault: false })
+  .description("Authentication commands")
+  .addCommand(
+    new Command("login")
+      .description("Login via device authorization")
+      .action(login),
+  )
+  .addCommand(
+    new Command("status")
+      .description("Check authentication status")
+      .action(status),
+  )
+  .addCommand(
+    new Command("logout")
+      .description("Logout and clear credentials")
+      .action(logout),
+  );
+
+program.parse(process.argv);

package/src/lib/api/client.ts

@@ -0,0 +1,20 @@
+import { createTRPCClient, httpBatchLink } from "@trpc/client";
+import type { AppRouter } from "@complete-web-template/api";
+import { loadCredentials } from "../auth/index.js";
+
+const BASE_URL = process.env.CLI_AUTH_API_URL ?? "http://localhost:3000";
+
+export const trpcClient = createTRPCClient<AppRouter>({
+  links: [
+    httpBatchLink({
+      url: `${BASE_URL}/api/trpc`,
+      headers() {
+        const creds = loadCredentials();
+        if (creds?.accessToken) {
+          return { Authorization: `Bearer ${creds.accessToken}` };
+        }
+        return {};
+      },
+    }),
+  ],
+});

package/src/lib/auth/client.ts

@@ -0,0 +1,14 @@
+import { createAuthClient } from "better-auth/client";
+import { deviceAuthorizationClient, organizationClient } from "better-auth/client/plugins";
+
+const BASE_URL = process.env.CLI_AUTH_API_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+
+export const authClient = createAuthClient({
+  baseURL: BASE_URL,
+  plugins: [
+    deviceAuthorizationClient(),
+    organizationClient(),
+  ],
+});
+
+export type AuthClient = typeof authClient;

package/src/lib/auth/device-flow/config.ts

@@ -0,0 +1,4 @@
+export const CLIENT_ID = process.env.CLI_AUTH_CLIENT_ID ?? "cli";
+export const POLL_TIMEOUT_MS = 30 * 60 * 1000; // 30 min max (matches server default expiresIn)
+export const SCOPE = "openid profile email";
+export const MAX_NETWORK_RETRIES = 3;

package/src/lib/auth/device-flow/device-code.ts

@@ -0,0 +1,39 @@
+import { log } from "@clack/prompts";
+import open from "open";
+import type { AuthClient } from "../client.js";
+import { CLIENT_ID, SCOPE } from "./config.js";
+import { AuthFlowError } from "./errors.js";
+
+export interface DeviceCodeResult {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  interval: number;
+}
+
+export const requestDeviceCode = async (client: AuthClient): Promise<DeviceCodeResult> => {
+  log.info("Requesting device authorization...");
+
+  const { data, error } = await client.device.code({
+    client_id: CLIENT_ID,
+    scope: SCOPE,
+  });
+
+  if (error || !data) {
+    const msg = error?.error_description ?? "Failed to get device code";
+    throw new AuthFlowError(msg);
+  }
+
+  return {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: data.verification_uri_complete,
+    interval: data.interval ?? 5,
+  };
+};
+
+export const openBrowser = async (uri: string): Promise<void> => {
+  await open(uri).catch(() => {
+    // Non-fatal: browser may fail to open, user can still use the URL
+  });
+};

package/src/lib/auth/device-flow/errors.ts

@@ -0,0 +1,29 @@
+// Transient network error codes from Node.js
+export const TRANSIENT_ERROR_CODES = new Set([
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "ENETUNREACH",
+]);
+
+export const isTransientError = (error: unknown): boolean => {
+  if (error && typeof error === "object") {
+    const code = (error as { code?: string }).code;
+    if (code && TRANSIENT_ERROR_CODES.has(code)) return true;
+  }
+  return false;
+};
+
+// Generic auth flow error (network or oauth)
+export class AuthFlowError extends Error {
+  constructor(
+    message: string,
+    public readonly isNetwork = false,
+  ) {
+    super(message);
+    this.name = "AuthFlowError";
+  }
+
+  static network = (msg: string): AuthFlowError => new AuthFlowError(msg, true);
+}

package/src/lib/auth/device-flow/index.ts

@@ -0,0 +1,19 @@
+import { log } from "@clack/prompts";
+import { authClient } from "../client.js";
+import { requestDeviceCode, openBrowser } from "./device-code.js";
+import { pollForToken } from "./polling.js";
+import type { AuthFlowResult } from "./types.js";
+
+export const startDeviceFlow = async (): Promise<AuthFlowResult> => {
+  const { deviceCode, userCode, verificationUri, interval } = await requestDeviceCode(authClient);
+
+  log.message(
+    `Open this URL in your browser:\n  ${verificationUri}\n` +
+    `Or enter the code: ${userCode}`
+  );
+
+  await openBrowser(verificationUri);
+  log.info(`Waiting for authorization... (polling every ${interval}s)`);
+
+  return pollForToken(authClient, deviceCode, interval);
+}

package/src/lib/auth/device-flow/polling.ts

@@ -0,0 +1,91 @@
+import { log } from "@clack/prompts";
+import type { AuthClient } from "../client.js";
+import { CLIENT_ID, POLL_TIMEOUT_MS, MAX_NETWORK_RETRIES } from "./config.js";
+import { isTransientError } from "./errors.js";
+import type { AuthFlowResult } from "./types.js";
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+const resolveUser = async (client: AuthClient, accessToken: string): Promise<AuthFlowResult["user"]> => {
+  const response = await client.getSession({
+    fetchOptions: {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    },
+  });
+
+  const user = response?.data?.user;
+  if (!user) {
+    throw new Error("Could not retrieve user session.");
+  }
+  return { id: user.id, name: user.name, email: user.email, image: user.image ?? undefined };
+};
+
+export const pollForToken = async (
+  client: AuthClient,
+  deviceCode: string,
+  intervalSeconds: number,
+  startedAt = Date.now(),
+  networkRetries = 0,
+): Promise<AuthFlowResult> => {
+  if (Date.now() - startedAt > POLL_TIMEOUT_MS) {
+    throw new Error("Authorization timed out. Please try again.");
+  }
+
+  let data: Awaited<ReturnType<AuthClient["device"]["token"]>>["data"];
+  let error: Awaited<ReturnType<AuthClient["device"]["token"]>>["error"];
+
+  try {
+    const result = await client.device.token({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: deviceCode,
+      client_id: CLIENT_ID,
+    });
+    data = result.data;
+    error = result.error;
+  } catch (err) {
+    if (isTransientError(err)) {
+      const retries = networkRetries + 1;
+      if (retries > MAX_NETWORK_RETRIES) {
+        throw new Error(`Network error after ${MAX_NETWORK_RETRIES} retries. Check your connection.`);
+      }
+      log.warn(`Network error during polling — retry ${retries}/${MAX_NETWORK_RETRIES}.`);
+      await sleep(intervalSeconds * 1000);
+      return pollForToken(client, deviceCode, intervalSeconds, startedAt, retries);
+    }
+    throw err;
+  }
+
+  if (data?.access_token) {
+    log.success("Authorization successful!");
+    const user = await resolveUser(client, data.access_token);
+    if (!user.id) {
+      throw new Error("Could not retrieve user information. Please try again.");
+    }
+    log.success(`Connected as ${user.name || user.email || "user"}`);
+    return { accessToken: data.access_token, user };
+  }
+
+  if (error) {
+    switch (error.error) {
+      case "authorization_pending":
+        await sleep(intervalSeconds * 1000);
+        return pollForToken(client, deviceCode, intervalSeconds, startedAt);
+      case "slow_down":
+        const newInterval = intervalSeconds + 5;
+        log.warn(`Slowing down polling to ${newInterval}s`);
+        await sleep(newInterval * 1000);
+        return pollForToken(client, deviceCode, newInterval, startedAt);
+      case "access_denied":
+        throw new Error("Authorization was denied.");
+      case "expired_token":
+        throw new Error("The code expired. Please try again.");
+      default:
+        throw new Error(error.error_description ?? `Unexpected error: ${error.error}`);
+    }
+  }
+
+  // No data and no error — should not happen, but guard anyway
+  await sleep(intervalSeconds * 1000);
+  return pollForToken(client, deviceCode, intervalSeconds, startedAt);
+};

package/src/lib/auth/device-flow/types.ts

@@ -0,0 +1,9 @@
+export type AuthFlowResult = {
+  accessToken: string;
+  user: {
+    id: string;
+    name: string;
+    email: string;
+    image?: string;
+  };
+};

package/src/lib/auth/index.ts

@@ -0,0 +1,41 @@
+// Re-export everything from submodules
+export { authClient } from "./client.js";
+export type { AuthClient } from "./client.js";
+
+export { startDeviceFlow } from "./device-flow/index.js";
+export type { AuthFlowResult } from "./device-flow/types.js";
+
+export {
+  saveCredentials,
+  loadCredentials,
+  clearCredentials,
+  isExpired,
+  requireAuth,
+  type StoredCredentials,
+} from "./storage.js";
+
+import { log } from "@clack/prompts";
+import { loadCredentials, clearCredentials, isExpired, type StoredCredentials } from "./storage.js";
+
+/**
+ * HOF - wraps an async operation requiring authentication.
+ * Checks credentials before execution, exits with error message if not authed.
+ */
+export async function withAuth<T>(
+  fn: (credentials: StoredCredentials) => Promise<T>,
+): Promise<T> {
+  const credentials = loadCredentials();
+
+  if (!credentials) {
+    log.error("Not logged in. Run 'auth login' first.");
+    process.exit(1);
+  }
+
+  if (isExpired(credentials)) {
+    log.error("Session expired. Run 'auth login' again.");
+    clearCredentials();
+    process.exit(1);
+  }
+
+  return fn(credentials);
+}

package/src/lib/auth/storage.ts

@@ -0,0 +1,69 @@
+import Conf from "conf";
+import { log } from "@clack/prompts";
+
+export type StoredCredentials = {
+  accessToken: string;
+  user: {
+    id: string;
+    email: string;
+    name: string;
+    image?: string;
+  };
+  expiresAt: number;
+};
+
+// Support test configuration via environment variable
+const configPath = process.env.CLI_AUTH_CONFIG_PATH;
+
+export const storage = new Conf<{ credentials: StoredCredentials | null }>({
+  projectName: "complete-web-template",
+  configName: "auth",
+  cwd: configPath, // Use custom path if set (for tests)
+  defaults: {
+    credentials: null,
+  },
+});
+
+export function saveCredentials(credentials: StoredCredentials): void {
+  storage.set("credentials", credentials);
+}
+
+export function loadCredentials(): StoredCredentials | null {
+  const raw = storage.get("credentials");
+
+  // Guard against corrupted storage (e.g., old version, partial write)
+  if (
+    !raw ||
+    typeof raw !== "object" ||
+    !("accessToken" in raw) ||
+    !("user" in raw) ||
+    !("expiresAt" in raw)
+  ) {
+    clearCredentials();
+    return null;
+  }
+
+  return raw as StoredCredentials;
+}
+
+export function clearCredentials(): void {
+  storage.delete("credentials");
+}
+
+export function isExpired(credentials: StoredCredentials): boolean {
+  return Date.now() > credentials.expiresAt;
+}
+
+export function requireAuth(): StoredCredentials {
+  const credentials = loadCredentials();
+  if (!credentials) {
+    log.error("Not logged in. Run 'auth login' first.");
+    process.exit(1);
+  }
+  if (isExpired(credentials)) {
+    log.error("Session expired. Run 'auth login' again.");
+    clearCredentials();
+    process.exit(1);
+  }
+  return credentials;
+}

package/tests/auth.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { status, logout } from "../src/commands/auth";
+import { loadCredentials, clearCredentials, saveCredentials } from "../src/lib/auth/storage";
+import { testServer } from "./setup";
+
+// Mock @clack/prompts before importing auth commands
+vi.mock("@clack/prompts", () => ({
+  log: {
+    info: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    message: vi.fn(),
+  },
+}));
+
+// Mock open before importing device-flow
+vi.mock("../src/lib/auth/device-flow", async () => {
+  const actual = await vi.importActual("../src/lib/auth/device-flow");
+  return {
+    ...actual,
+    startDeviceFlow: vi.fn().mockImplementation(async () => ({
+      accessToken: "test-access-token",
+      user: {
+        id: "test-user-id",
+        name: "Test User",
+        email: "test@example.com",
+      },
+    })),
+  };
+});
+
+// Import login AFTER mocking
+const { login } = await import("../src/commands/auth");
+
+describe("CLI Auth Commands", () => {
+  describe("login", () => {
+    it("should login successfully with device flow", async () => {
+      // Mock open to prevent browser from actually opening
+      const openMock = vi.fn();
+      vi.stubGlobal("open", Object.assign(openMock, { default: openMock }));
+
+      // Start login - it uses mocked startDeviceFlow internally
+      await login();
+
+      // Verify credentials were stored
+      const creds = loadCredentials();
+      expect(creds).toBeDefined();
+      expect(creds?.accessToken).toBe("test-access-token");
+      expect(creds?.user).toBeDefined();
+      expect(creds?.user.email).toBe("test@example.com");
+
+      vi.unstubAllGlobals();
+    });
+  });
+
+  describe("status", () => {
+    it("should show not logged in message when no credentials", async () => {
+      const { log } = await import("@clack/prompts");
+      clearCredentials();
+
+      await status();
+
+      expect(log.info).toHaveBeenCalledWith(
+        "Not logged in. Run 'auth login' to authenticate."
+      );
+    });
+
+    it("should show logged in message when credentials exist", async () => {
+      const { log } = await import("@clack/prompts");
+
+      // Simulate logged in state
+      saveCredentials({
+        accessToken: "test-token",
+        user: { id: "1", name: "Test User", email: "test@example.com" },
+        expiresAt: Date.now() + 86400000, // 1 day from now
+      });
+
+      // Mock the fetch call for session verification
+      const fetchMock = vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ user: { name: "Test User", email: "test@example.com" } }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      );
+      vi.stubGlobal("fetch", fetchMock);
+
+      await status();
+
+      expect(log.success).toHaveBeenCalledWith(
+        expect.stringContaining("Test User")
+      );
+      vi.unstubAllGlobals();
+    });
+  });
+
+  describe("logout", () => {
+    it("should show not logged in when no credentials", async () => {
+      const { log } = await import("@clack/prompts");
+      clearCredentials();
+
+      await logout();
+
+      expect(log.info).toHaveBeenCalledWith("Not logged in.");
+    });
+
+    it("should clear credentials and confirm logout", async () => {
+      const { log } = await import("@clack/prompts");
+
+      // Set up credentials
+      saveCredentials({
+        accessToken: "test-token",
+        user: { id: "1", name: "Test User", email: "test@example.com" },
+        expiresAt: Date.now() + 86400000,
+      });
+
+      await logout();
+
+      expect(log.success).toHaveBeenCalledWith("Successfully logged out.");
+      expect(loadCredentials() ?? null).toBeNull();
+    });
+  });
+});

package/tests/setup.ts

@@ -0,0 +1,43 @@
+import { createTestServerWithAuth } from "@complete-web-template/test-utils";
+import { createTempDir, mockOpen, restoreOpen } from "@complete-web-template/test-utils";
+import { clearCredentials } from "../src/lib/auth/storage";
+import type { TestServer } from "@complete-web-template/test-utils";
+
+// Test server instance
+export let testServer: Awaited<ReturnType<typeof createTestServerWithAuth>> | null = null;
+
+// Temp directory for config
+export let tempDir: { configPath: string; cleanup: () => void };
+
+// Set up test environment before all tests
+beforeAll(async () => {
+  // Create temp directory for config storage
+  tempDir = createTempDir();
+  process.env.CLI_AUTH_CONFIG_PATH = tempDir.configPath;
+
+  // Start test server with auth
+  testServer = await createTestServerWithAuth();
+
+  // Set API URL for CLI
+  process.env.CLI_AUTH_API_URL = testServer.baseUrl;
+
+  // Mock open to prevent browser launching
+  mockOpen();
+});
+
+// Clean up after all tests
+afterAll(async () => {
+  if (testServer) {
+    await testServer.close();
+  }
+  restoreOpen();
+  tempDir.cleanup();
+  delete process.env.CLI_AUTH_CONFIG_PATH;
+  delete process.env.CLI_AUTH_API_URL;
+});
+
+// Clean up before each test (reset credentials)
+beforeEach(() => {
+  // Reset the config storage between tests
+  clearCredentials();
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    setupFiles: ["./tests/setup.ts"],
+    pool: "forks",
+  },
+});