@sqaoss/flowy 1.3.0 → 1.4.0

package/src/util/client.ts

@@ -1,56 +1,156 @@
 import { getConfig } from './config.ts'
 
+export interface GraphqlOptions {
+  /** Per-request timeout in milliseconds. Default 15s. */
+  timeoutMs?: number
+  /** Max retry attempts on transient transport failures. Default 2. */
+  retries?: number
+  /** Base backoff delay in milliseconds (exponential). Default 300ms. */
+  retryDelayMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000
+const DEFAULT_RETRIES = 2
+const DEFAULT_RETRY_DELAY_MS = 300
+
+/** HTTP statuses worth retrying — transient server/proxy conditions. */
+const TRANSIENT_STATUSES = new Set([429, 502, 503, 504])
+
+type CodedError = Error & { code?: string }
+
+function codedError(message: string, code: string): CodedError {
+  const err = new Error(message) as CodedError
+  err.code = code
+  return err
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.name === 'AbortError' || error.name === 'TimeoutError')
+  )
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function readBody(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}
+
 export async function graphql<T = unknown>(
   query: string,
   variables?: Record<string, unknown>,
+  options: GraphqlOptions = {},
 ): Promise<T> {
   const { apiUrl, apiKey } = getConfig()
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const retries = options.retries ?? DEFAULT_RETRIES
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
 
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
   }
-
   if (apiKey) {
     headers.Authorization = `Bearer ${apiKey}`
   }
 
-  const res = await fetch(apiUrl, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ query, variables }),
-  })
+  const body = JSON.stringify({ query, variables })
 
-  const json = (await res.json()) as {
-    data?: T
-    errors?: Array<{ message: string; extensions?: { code?: string } }>
-  }
+  let lastError: CodedError | undefined
 
-  if (json.errors?.length) {
-    const error = json.errors[0]
-    const code = error?.extensions?.code
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let res: Response
+    try {
+      res = await fetch(apiUrl, {
+        method: 'POST',
+        headers,
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+    } catch (error) {
+      // Network-layer failure: DNS, connection refused, or our timeout abort.
+      const message = isAbortError(error)
+        ? `Request timed out after ${timeoutMs}ms`
+        : `Network request failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+      lastError = codedError(message, 'NETWORK_ERROR')
+      if (attempt < retries) {
+        await sleep(retryDelayMs * 2 ** attempt)
+        continue
+      }
+      throw lastError
+    }
 
-    if (code === 'SUBSCRIPTION_REQUIRED') {
-      throw new Error(
-        'An active subscription is required. Run `flowy billing checkout` to subscribe.',
+    // HTTP-level (non-2xx) failure — handled before attempting to parse JSON,
+    // so proxy HTML / empty bodies never crash with a SyntaxError.
+    if (!res.ok) {
+      if (TRANSIENT_STATUSES.has(res.status) && attempt < retries) {
+        lastError = codedError(
+          `Server returned HTTP ${res.status}`,
+          'SERVER_ERROR',
+        )
+        await sleep(retryDelayMs * 2 ** attempt)
+        continue
+      }
+      const snippet = (await readBody(res)).trim().slice(0, 200)
+      const detail = snippet ? `: ${snippet}` : ''
+      throw codedError(
+        `Server returned HTTP ${res.status}${detail}`,
+        'SERVER_ERROR',
       )
     }
 
-    if (code === 'SUBSCRIPTION_EXPIRED') {
-      throw new Error(
-        'Your subscription has expired. Run `flowy billing checkout` to renew.',
+    type GraphqlBody = {
+      data?: T
+      errors?: Array<{ message: string; extensions?: { code?: string } }>
+    }
+    let json: GraphqlBody
+    try {
+      json = (await res.json()) as GraphqlBody
+    } catch {
+      const snippet = (await readBody(res)).trim().slice(0, 200)
+      const detail = snippet ? `: ${snippet}` : ''
+      throw codedError(
+        `Server returned a non-JSON response${detail}`,
+        'SERVER_ERROR',
       )
     }
 
-    if (code === 'SUBSCRIPTION_SUSPENDED') {
-      throw new Error(
-        'Your subscription is suspended. Please contact support to resolve this.',
-      )
+    if (json.errors?.length) {
+      const error = json.errors[0]
+      const code = error?.extensions?.code
+
+      if (code === 'SUBSCRIPTION_REQUIRED') {
+        throw new Error(
+          'An active subscription is required. Run `flowy billing checkout` to subscribe.',
+        )
+      }
+      if (code === 'SUBSCRIPTION_EXPIRED') {
+        throw new Error(
+          'Your subscription has expired. Run `flowy billing checkout` to renew.',
+        )
+      }
+      if (code === 'SUBSCRIPTION_SUSPENDED') {
+        throw new Error(
+          'Your subscription is suspended. Please contact support to resolve this.',
+        )
+      }
+
+      const err = new Error(error?.message) as CodedError
+      if (code) err.code = code
+      throw err
     }
 
-    const err = new Error(error?.message) as Error & { code?: string }
-    if (code) err.code = code
-    throw err
+    return json.data as T
   }
 
-  return json.data as T
+  // Exhausted retries on a transient condition.
+  throw lastError ?? codedError('Request failed after retries', 'NETWORK_ERROR')
 }

package/src/util/description.test.ts

@@ -1,7 +1,7 @@
-import { rmSync, writeFileSync } from 'node:fs'
+import { existsSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, test } from 'vitest'
+import { afterEach, describe, expect, test, vi } from 'vitest'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -12,18 +12,70 @@ describe('resolveDescription', () => {
     try {
       rmSync(TEST_FILE)
     } catch {}
+    vi.restoreAllMocks()
   })
 
-  test('returns file content when path exists', async () => {
+  test('returns --description verbatim, never as a file path', async () => {
+    // A literal value that also happens to be an existing path must NOT be read.
+    writeFileSync(TEST_FILE, '# File body\nshould not be used')
+    expect(existsSync(TEST_FILE)).toBe(true)
+
+    const { resolveDescription } = await import('./description.ts')
+    const result = await resolveDescription({ description: TEST_FILE })
+    expect(result).toBe(TEST_FILE)
+  })
+
+  test('returns the literal string identically regardless of CWD collisions', async () => {
+    const { resolveDescription } = await import('./description.ts')
+    const result = await resolveDescription({
+      description: 'Just a plain description',
+    })
+    expect(result).toBe('Just a plain description')
+  })
+
+  test('reads file contents when --description-file is given', async () => {
     writeFileSync(TEST_FILE, '# Test\nSome content')
     const { resolveDescription } = await import('./description.ts')
-    const result = await resolveDescription(TEST_FILE)
+    const result = await resolveDescription({ descriptionFile: TEST_FILE })
     expect(result).toBe('# Test\nSome content')
   })
 
-  test('returns value as-is when path does not exist', async () => {
+  test('reads stdin when --description-file is "-"', async () => {
     const { resolveDescription } = await import('./description.ts')
-    const result = await resolveDescription('Just a plain description')
-    expect(result).toBe('Just a plain description')
+    const fakeStdin = (async function* () {
+      yield Buffer.from('piped ')
+      yield Buffer.from('description')
+    })()
+    const result = await resolveDescription(
+      { descriptionFile: '-' },
+      // biome-ignore lint/suspicious/noExplicitAny: test stub for stdin
+      fakeStdin as any,
+    )
+    expect(result).toBe('piped description')
+  })
+
+  test('errors when --description-file points at a missing file', async () => {
+    const { resolveDescription } = await import('./description.ts')
+    await expect(
+      resolveDescription({ descriptionFile: resolve(__dirname, '../../nope') }),
+    ).rejects.toThrow(/not found|no such file|ENOENT/i)
+  })
+
+  test('errors when both --description and --description-file are given', async () => {
+    writeFileSync(TEST_FILE, 'body')
+    const { resolveDescription } = await import('./description.ts')
+    await expect(
+      resolveDescription({
+        description: 'literal',
+        descriptionFile: TEST_FILE,
+      }),
+    ).rejects.toThrow(/both|either|only one/i)
+  })
+
+  test('errors when neither --description nor --description-file is given', async () => {
+    const { resolveDescription } = await import('./description.ts')
+    await expect(resolveDescription({})).rejects.toThrow(
+      /--description|description-file|required/i,
+    )
   })
 })

package/src/util/description.ts

@@ -1,8 +1,63 @@
 import { existsSync, readFileSync } from 'node:fs'
 
-export async function resolveDescription(value: string): Promise<string> {
-  if (existsSync(value)) {
-    return readFileSync(value, 'utf-8')
+export interface DescriptionInput {
+  /** Literal description text. Used verbatim — never interpreted as a path. */
+  description?: string
+  /**
+   * Path to a file whose contents become the description.
+   * Use `-` to read from stdin.
+   */
+  descriptionFile?: string
+}
+
+type AsyncByteSource = AsyncIterable<Uint8Array | Buffer | string>
+
+async function readStdin(source: AsyncByteSource): Promise<string> {
+  const chunks: string[] = []
+  for await (const chunk of source) {
+    chunks.push(
+      typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8'),
+    )
+  }
+  return chunks.join('')
+}
+
+/**
+ * Resolve a node description from explicit options.
+ *
+ * - `--description <text>` is always literal (never read as a file).
+ * - `--description-file <path>` reads file contents; `-` reads stdin.
+ * - Supplying both, or neither, is an error.
+ */
+export async function resolveDescription(
+  input: DescriptionInput,
+  stdin: AsyncByteSource = process.stdin,
+): Promise<string> {
+  const hasLiteral = input.description != null
+  const hasFile = input.descriptionFile != null
+
+  if (hasLiteral && hasFile) {
+    throw new Error(
+      'Pass only one of --description or --description-file, not both.',
+    )
+  }
+
+  if (hasLiteral) {
+    return input.description as string
   }
-  return value
+
+  if (hasFile) {
+    const path = input.descriptionFile as string
+    if (path === '-') {
+      return readStdin(stdin)
+    }
+    if (!existsSync(path)) {
+      throw new Error(`--description-file not found: ${path}`)
+    }
+    return readFileSync(path, 'utf-8')
+  }
+
+  throw new Error(
+    'A description is required: pass --description or --description-file.',
+  )
 }

package/src/util/format.test.ts

@@ -45,4 +45,69 @@ describe('outputError', () => {
 
     expect(exitSpy).toHaveBeenCalledWith(1)
   })
+
+  test('exits 1 for VALIDATION_ERROR (usage/validation class)', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(
+      Object.assign(new Error('bad input'), { code: 'VALIDATION_ERROR' }),
+    )
+
+    expect(exitSpy).toHaveBeenCalledWith(1)
+  })
+
+  test('exits 1 for CONFLICT (usage/validation class)', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(Object.assign(new Error('conflict'), { code: 'CONFLICT' }))
+
+    expect(exitSpy).toHaveBeenCalledWith(1)
+  })
+
+  test('exits 2 for NOT_FOUND', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(
+      Object.assign(new Error('Node bad-id not found'), { code: 'NOT_FOUND' }),
+    )
+
+    expect(exitSpy).toHaveBeenCalledWith(2)
+  })
+
+  test('exits 3 for SERVER_ERROR', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(
+      Object.assign(new Error('Server returned HTTP 502'), {
+        code: 'SERVER_ERROR',
+      }),
+    )
+
+    expect(exitSpy).toHaveBeenCalledWith(3)
+  })
+
+  test('exits 4 for NETWORK_ERROR', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(
+      Object.assign(new Error('Request timed out'), { code: 'NETWORK_ERROR' }),
+    )
+
+    expect(exitSpy).toHaveBeenCalledWith(4)
+  })
 })

package/src/util/format.ts

@@ -2,6 +2,27 @@ export function output(data: unknown): void {
   console.log(JSON.stringify(data, null, 2))
 }
 
+/**
+ * Map a GraphQL `extensions.code` (or transport code) to a distinct process
+ * exit code so callers can branch on failure class:
+ *   1 — usage / validation / conflict (default)
+ *   2 — not found
+ *   3 — server error (non-2xx, masked, non-JSON)
+ *   4 — network / transport (timeout, connection failure)
+ */
+function exitCodeFor(code: string | undefined): number {
+  switch (code) {
+    case 'NOT_FOUND':
+      return 2
+    case 'SERVER_ERROR':
+      return 3
+    case 'NETWORK_ERROR':
+      return 4
+    default:
+      return 1
+  }
+}
+
 export function outputError(error: unknown): void {
   const message = error instanceof Error ? error.message : String(error)
   const rawCode =
@@ -10,5 +31,5 @@ export function outputError(error: unknown): void {
   console.error(
     JSON.stringify(code ? { error: message, code } : { error: message }),
   )
-  process.exit(1)
+  process.exit(exitCodeFor(code))
 }