Mirror 5b0a16f (2026-04-10)

Author: Prompsit CI

.gitignore

@@ -37,3 +37,4 @@ tmp/
 # AI tool config
 .claude/
 /.playwright-mcp
+/.hex-skills

CLAUDE.md

@@ -28,6 +28,17 @@ Prompsit CLI is a command-line interface for the Prompsit Translation API. Trans
 
 **Architecture:** Layered (Presentation → Application → Domain → Infrastructure). Entry point: [src/index.ts](src/index.ts) → Commander.js commands or REPL ([repl/](src/repl/)).
 
+## Related Projects
+
+**Prompsit API** (`../prompsit-api/`) — the backend API that this CLI consumes via HTTP/REST. When adapting CLI to API changes, read the API project for context:
+
+- **Entry point & agent instructions:** `../prompsit-api/CLAUDE.md`
+- **API endpoints:** `../prompsit-api/app/api/v1/` (translation, quality, jobs, user, etc.)
+- **Domain models:** `../prompsit-api/app/domain/`
+- **Documentation:** `../prompsit-api/docs/` (architecture, requirements, API spec, database schema)
+
+> **Read-only reference.** Do not edit API files from this project — switch to the API working directory for changes.
+
 ## Quick Start
 
 ```bash
@@ -132,4 +143,4 @@ src/
 - [ ] Critical rules align with current requirements
 - [ ] No duplicated content across documents
 
-**Last Updated:** 2026-02-26
+**Last Updated:** 2026-04-10

README.md

@@ -5,7 +5,7 @@
 [![license](https://img.shields.io/npm/l/prompsit-cli)](https://www.npmjs.com/package/prompsit-cli)
 [![node](https://img.shields.io/node/v/prompsit-cli)](https://nodejs.org/)
 
-One CLI for the entire Prompsit API services. Translate text and documents, evaluate translation quality, score parallel corpora with Bicleaner-AI, and annotate multilingual datasets with Monotextor — from your terminal or an interactive REPL.
+One CLI for the entire Prompsit Translation API. Translate text and documents, evaluate translation quality, score parallel corpora with Bicleaner-AI, and annotate monolingual data with Monotextor — from your terminal or an interactive REPL.
 
 ## Quick Start
 

src/api/models.ts

@@ -361,6 +361,54 @@ export interface AnnotateParams {
   lidModel: string;
 }
 
+// --- Device Flow schemas (RFC 8628) ---
+
+/**
+ * Device authorization response from POST /v1/auth/device.
+ *
+ * Fields:
+ * - device_code: Opaque 32-byte base64 token for polling
+ * - user_code: Human-readable XXXX-XXXX format
+ * - verification_uri: Short URL (RFC 8628 §3.3)
+ * - verification_uri_complete: URL with embedded user_code for QR codes (§3.3.1)
+ * - expires_in: Device code TTL in seconds (default 600s)
+ * - interval: Minimum polling interval in seconds (default 5s)
+ */
+export const DeviceAuthorizationResponseSchema = z.object({
+  device_code: z.string(),
+  user_code: z.string(),
+  verification_uri: z.string(),
+  verification_uri_complete: z.string().optional(),
+  expires_in: z.number().default(600),
+  interval: z.number().default(5),
+});
+
+/**
+ * Device token success response from POST /v1/auth/device/token.
+ *
+ * All fields are REQUIRED in the API (app/schemas/auth.py:277-320).
+ * Do NOT copy nullable/optional patterns from TokenResponseSchema — that models
+ * POST /v1/auth/token where refresh_token IS nullable. Device flow is different.
+ */
+export const DeviceTokenResponseSchema = z.object({
+  access_token: z.string(),
+  refresh_token: z.string(),
+  token_type: z.string().default("Bearer"),
+  expires_in: z.number(),
+  plan: z.string(),
+  account_id: z.string(),
+  prompsit_secret: z.string(),
+});
+
+/**
+ * Device token error response from POST /v1/auth/device/token (HTTP 400).
+ * RFC 8628 §3.5 error codes for polling.
+ */
+export const DeviceTokenErrorSchema = z.object({
+  error: z.enum(["authorization_pending", "slow_down", "expired_token", "access_denied"]),
+  error_description: z.string().optional(),
+});
+
 /**
  * Inferred TypeScript types from Zod schemas.
  * Single source of truth: types automatically match schema definitions.
@@ -377,3 +425,6 @@ export type JobStatusResponse = z.infer<typeof JobStatusResponseSchema>;
 export type DocJobCreateResponse = z.infer<typeof DocJobCreateResponseSchema>;
 export type DataJobCreateResponse = z.infer<typeof DataJobCreateResponseSchema>;
 export type UserUsageResponse = z.infer<typeof UserUsageResponseSchema>;
+export type DeviceAuthorizationResponse = z.infer<typeof DeviceAuthorizationResponseSchema>;
+export type DeviceTokenResponse = z.infer<typeof DeviceTokenResponseSchema>;
+export type DeviceTokenError = z.infer<typeof DeviceTokenErrorSchema>;

src/api/resources/auth.ts

@@ -3,8 +3,17 @@
 // Uses public transport (token endpoint does not require Authorization header).
 
 import type { HttpTransport } from "../transport.ts";
-import { TokenResponseSchema, type TokenResponse } from "../models.ts";
+import {
+  TokenResponseSchema,
+  DeviceAuthorizationResponseSchema,
+  DeviceTokenResponseSchema,
+  DeviceTokenErrorSchema,
+  type TokenResponse,
+  type DeviceAuthorizationResponse,
+  type DeviceTokenResponse,
+} from "../models.ts";
 import { Endpoint, GrantType } from "../../shared/constants.ts";
+import { APIError } from "../../errors/contracts.ts";
 
 /**
  * Auth API resource for OAuth2 token operations.
@@ -71,4 +80,70 @@ export class AuthResource {
     );
     return TokenResponseSchema.parse(data);
   }
+
+  /**
+   * Initiate device authorization flow (RFC 8628 §3.1).
+   *
+   * @returns Device code, user code, and verification URI for browser auth
+   */
+  async requestDeviceCode(): Promise<DeviceAuthorizationResponse> {
+    const data = await this.transport.request<unknown>(
+      "POST",
+      `${this.baseUrl}${Endpoint.AUTH_DEVICE}`,
+      {},
+      true // public client
+    );
+    return DeviceAuthorizationResponseSchema.parse(data);
+  }
+
+  /**
+   * Poll device token endpoint (RFC 8628 §3.4).
+   *
+   * Returns discriminated union to encapsulate RFC 8628 error semantics.
+   * Uses requestRaw with throwHttpErrors:false because transport.request<T>()
+   * catches HTTP 400 via handleError() → parseApiError() which doesn't understand
+   * OAuth2 error format {error, error_description} — the RFC 8628 fields are lost.
+   */
+  async pollDeviceToken(
+    deviceCode: string
+  ): Promise<
+    | { status: "success"; data: DeviceTokenResponse }
+    | { status: "pending" }
+    | { status: "slow_down" }
+    | { status: "expired" }
+    | { status: "denied" }
+  > {
+    const raw = await this.transport.requestRaw(
+      "POST",
+      `${this.baseUrl}${Endpoint.AUTH_DEVICE_TOKEN}`,
+      {
+        json: {
+          device_code: deviceCode,
+          grant_type: GrantType.DEVICE_CODE,
+        },
+        throwHttpErrors: false,
+      },
+      true // public client
+    );
+
+    if (raw.statusCode === 200) {
+      const body: unknown = JSON.parse(raw.body.toString());
+      return { status: "success", data: DeviceTokenResponseSchema.parse(body) };
+    }
+
+    if (raw.statusCode === 400) {
+      const body: unknown = JSON.parse(raw.body.toString());
+      const err = DeviceTokenErrorSchema.parse(body);
+      if (err.error === "authorization_pending") return { status: "pending" };
+      if (err.error === "slow_down") return { status: "slow_down" };
+      if (err.error === "expired_token") return { status: "expired" };
+      return { status: "denied" };
+    }
+
+    throw new APIError(
+      `Unexpected status ${String(raw.statusCode)}`,
+      "E_DEVICE_FLOW",
+      raw.statusCode
+    );
+  }
 }

src/api/transport.ts

@@ -3,6 +3,7 @@
 // Three request methods: request<T> (JSON), requestRaw (buffer+headers), requestToFile (streaming).
 
 import { createWriteStream } from "node:fs";
+import * as os from "node:os";
 import { pipeline } from "node:stream/promises";
 
 import got, {
@@ -25,6 +26,7 @@ import { getSettings } from "../config/settings.ts";
 import { getAccessToken } from "../config/credentials.ts";
 import { generateTraceId } from "./trace.ts";
 import { getTraceId } from "../logging/index.ts";
+import { getVersion } from "../shared/version.ts";
 import { logCurl, isCurlEnabled } from "./curl.ts";
 import {
   HEADER_AUTHORIZATION,
@@ -85,6 +87,8 @@ function createGotHooks() {
     // Inject X-Request-ID header — reuse trace_id from AsyncLocalStorage context,
     // fallback to fresh ID if called outside trace context (e.g. startup health check)
     options.headers["X-Request-ID"] = getTraceId() || generateTraceId();
+    // Identify CLI in API access logs (searchable in Loki as structured_metadata)
+    options.headers["User-Agent"] = `prompsit-cli/${getVersion()} (${os.platform()})`;
   };
 
   const afterResponse: AfterResponseHook = (response) => {

src/commands/auth.ts

@@ -6,60 +6,86 @@ import { Command } from "@commander-js/extra-typings";
 import { getApiClient, resetApiClient } from "../api/client.ts";
 import { saveTokens, clearTokens } from "../config/credentials.ts";
 import { setSigintExit } from "../cli/exit.ts";
-import { promptHidden, promptInput } from "../cli/prompts.ts";
 import { terminal } from "../output/index.ts";
 import { t } from "../i18n/index.ts";
 import { getLogger } from "../logging/index.ts";
 import { ErrorCode } from "../errors/codes.ts";
 import { failCommand, handleCommandError } from "./error-handler.ts";
+import { runDeviceFlow } from "./device-flow.ts";
+import { getCurrentAbortSignal } from "../runtime/request-context.ts";
 
 const log = getLogger(import.meta.url);
 
 /**
  * Login command.
  *
- * Authenticates via OAuth2 ROPC flow. Supports flags or interactive input.
+ * Two authentication paths:
+ * - No flags: Device Flow (RFC 8628) — opens browser for Google OAuth.
+ *   Works for both new registration and existing user recovery.
+ * - With -a/-s flags: OAuth2 ROPC flow (backward compatible).
+ *
  * Stores tokens in ~/.prompsit/credentials.json.
  */
 export const loginCommand = new Command("login")
-  .description("Authenticate with the Prompsit API")
+  .description("Sign in or register with the Prompsit API")
   .option("-a, --account <email>", "Account email address")
   .option("-s, --secret <key>", "API secret key")
   .action(async (options) => {
     const startMs = Date.now();
     try {
       log.debug("Login action entered");
-      // Resolve account and secret (flags or interactive)
-      const account = options.account ?? (await promptInput(t("auth.login.prompt_account")));
-      const secret = options.secret ?? (await promptHidden(t("auth.login.prompt_secret")));
-
-      if (!account || !secret) {
-        failCommand(ErrorCode.AUTH_FAILED, t("auth.login.credentials_required"));
-        return;
-      }
 
-      // Authenticate via OAuth2
-      terminal.info(t("auth.login.authenticating"));
-      log.debug("Sending auth request", { account });
-      const response = await getApiClient().auth.getToken(account, secret);
-      log.info("Authentication completed", { duration_ms: String(Date.now() - startMs) });
+      if (options.account && options.secret) {
+        // ROPC path: login with existing credentials (backward compatible)
+        terminal.info(t("auth.login.authenticating"));
+        log.debug("Sending ROPC auth request", { account: options.account });
+        const response = await getApiClient().auth.getToken(options.account, options.secret);
+        log.info("ROPC authentication completed", {
+          duration_ms: String(Date.now() - startMs),
+        });
 
-      // Save tokens (normalize nullable -> undefined for credential store)
-      saveTokens({
-        accessToken: response.access_token,
-        refreshToken: response.refresh_token ?? undefined,
-        accountId: account,
-        expiresIn: response.expires_in ?? undefined,
-        plan: response.plan,
-      });
+        saveTokens({
+          accessToken: response.access_token,
+          refreshToken: response.refresh_token ?? undefined,
+          accountId: options.account,
+          expiresIn: response.expires_in ?? undefined,
+          plan: response.plan,
+        });
+        resetApiClient();
+        terminal.success(t("auth.login.success"));
+      } else if (options.account || options.secret) {
+        // Partial flags: require both
+        failCommand(ErrorCode.AUTH_FAILED, t("auth.login.credentials_required"));
+      } else {
+        // Device Flow path: browser-based sign-in / registration
+        log.debug("Starting device flow");
+        const result = await runDeviceFlow(
+          getApiClient().auth,
+          getCurrentAbortSignal()
+        );
 
-      // Reset client to pick up new credentials
-      resetApiClient();
+        saveTokens({
+          accessToken: result.accessToken,
+          refreshToken: result.refreshToken,
+          accountId: result.accountId,
+          expiresIn: result.expiresIn,
+          plan: result.plan,
+          prompsitSecret: result.prompsitSecret,
+        });
+        resetApiClient();
 
-      terminal.success(t("auth.login.success"));
+        // Show hint for future ROPC login
+        terminal.dim(
+          t("auth.device.secret_hint", {
+            cmd: "login",
+            account: result.accountId,
+            secret: result.prompsitSecret,
+          })
+        );
+      }
     } catch (error: unknown) {
-      // Ctrl+C during interactive readline: POSIX SIGINT exit code
-      if ((error as Error).message === "Cancelled") {
+      // Ctrl+C during interactive readline or device flow polling
+      if ((error as Error).message === "Cancelled" || (error as Error).message === "Request cancelled") {
         setSigintExit();
         return;
       }