npm - @sqaoss/flowy - Versions diffs - 1.3.0 → 1.3.1 - Mend

@sqaoss/flowy 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/docker-compose.yml +7 -2
package/package.json +1 -1
package/server/src/index.errors.test.ts +37 -7
package/server/src/index.test.ts +29 -0
package/server/src/index.ts +15 -5
package/server/src/resolvers.test.ts +15 -4
package/server/src/resolvers.ts +3 -1
package/src/commands/feature.ts +12 -2
package/src/commands/serve.test.ts +89 -0
package/src/commands/serve.ts +76 -0
package/src/commands/setup.test.ts +12 -14
package/src/commands/setup.ts +14 -73
package/src/commands/task.test.ts +8 -0
package/src/commands/task.ts +11 -4
package/src/index.test.ts +16 -0
package/src/index.ts +2 -0
package/src/util/client.test.ts +194 -81
package/src/util/client.ts +127 -27
package/src/util/description.test.ts +59 -7
package/src/util/description.ts +59 -4
package/src/util/format.test.ts +65 -0
package/src/util/format.ts +22 -1

package/src/util/client.test.ts CHANGED Viewed

@@ -1,5 +1,25 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+function ok(json: unknown) {
+  return {
+    ok: true,
+    status: 200,
+    headers: { get: () => 'application/json' },
+    json: () => Promise.resolve(json),
+    text: () => Promise.resolve(JSON.stringify(json)),
+  }
+}
+function httpError(status: number, body = '<html>error</html>') {
+  return {
+    ok: false,
+    status,
+    headers: { get: () => 'text/html' },
+    json: () => Promise.reject(new SyntaxError('Unexpected token <')),
+    text: () => Promise.resolve(body),
+  }
+}
 beforeEach(() => {
   vi.doMock('./config.ts', () => ({
     getConfig: () => ({
@@ -18,12 +38,7 @@ describe('graphql client', () => {
   test('returns data on successful response', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            data: { whoami: { id: '1' } },
-          }),
-      }),
+      vi.fn().mockResolvedValue(ok({ data: { whoami: { id: '1' } } })),
     )
     const { graphql } = await import('./client.ts')
@@ -34,17 +49,16 @@ describe('graphql client', () => {
   test('attaches extensions.code to the thrown error', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [
-              {
-                message: 'Search query must be at least 3 characters',
-                extensions: { code: 'VALIDATION_ERROR' },
-              },
-            ],
-          }),
-      }),
+      vi.fn().mockResolvedValue(
+        ok({
+          errors: [
+            {
+              message: 'Search query must be at least 3 characters',
+              extensions: { code: 'VALIDATION_ERROR' },
+            },
+          ],
+        }),
+      ),
     )
     const { graphql } = await import('./client.ts')
@@ -59,17 +73,16 @@ describe('graphql client', () => {
   test('throws original server message for unknown error codes', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [
-              {
-                message: 'Something broke',
-                extensions: { code: 'UNKNOWN_CODE' },
-              },
-            ],
-          }),
-      }),
+      vi.fn().mockResolvedValue(
+        ok({
+          errors: [
+            {
+              message: 'Something broke',
+              extensions: { code: 'UNKNOWN_CODE' },
+            },
+          ],
+        }),
+      ),
     )
     const { graphql } = await import('./client.ts')
@@ -81,12 +94,7 @@ describe('graphql client', () => {
   test('throws error message when extensions are absent', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [{ message: 'Auth required' }],
-          }),
-      }),
+      vi.fn().mockResolvedValue(ok({ errors: [{ message: 'Auth required' }] })),
     )
     const { graphql } = await import('./client.ts')
@@ -97,18 +105,12 @@ describe('graphql client', () => {
   test('omits Authorization header when no apiKey configured', async () => {
     vi.doMock('./config.ts', () => ({
-      getConfig: () => ({
-        apiUrl: 'http://test/graphql',
-        apiKey: '',
-      }),
+      getConfig: () => ({ apiUrl: 'http://test/graphql', apiKey: '' }),
     }))
-    const mockFetch = vi.fn().mockResolvedValue({
-      json: () =>
-        Promise.resolve({
-          data: { whoami: { id: '1' } },
-        }),
-    })
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValue(ok({ data: { whoami: { id: '1' } } }))
     vi.stubGlobal('fetch', mockFetch)
     const { graphql } = await import('./client.ts')
@@ -118,29 +120,30 @@ describe('graphql client', () => {
     expect(callHeaders).not.toHaveProperty('Authorization')
   })
-  test('throws on network error', async () => {
+  test('throws a NETWORK_ERROR-coded error on fetch rejection', async () => {
     vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('fetch failed')))
     const { graphql } = await import('./client.ts')
-    await expect(graphql('query { whoami { id } }')).rejects.toThrow(
-      'fetch failed',
-    )
+    await expect(
+      graphql('query { whoami { id } }', undefined, { retryDelayMs: 0 }),
+    ).rejects.toMatchObject({
+      code: 'NETWORK_ERROR',
+    })
   })
   test('throws friendly message for SUBSCRIPTION_REQUIRED error code', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [
-              {
-                message: 'Active subscription required.',
-                extensions: { code: 'SUBSCRIPTION_REQUIRED' },
-              },
-            ],
-          }),
-      }),
+      vi.fn().mockResolvedValue(
+        ok({
+          errors: [
+            {
+              message: 'Active subscription required.',
+              extensions: { code: 'SUBSCRIPTION_REQUIRED' },
+            },
+          ],
+        }),
+      ),
     )
     const { graphql } = await import('./client.ts')
@@ -152,17 +155,16 @@ describe('graphql client', () => {
   test('throws friendly message for SUBSCRIPTION_EXPIRED error code', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [
-              {
-                message: 'Subscription has expired.',
-                extensions: { code: 'SUBSCRIPTION_EXPIRED' },
-              },
-            ],
-          }),
-      }),
+      vi.fn().mockResolvedValue(
+        ok({
+          errors: [
+            {
+              message: 'Subscription has expired.',
+              extensions: { code: 'SUBSCRIPTION_EXPIRED' },
+            },
+          ],
+        }),
+      ),
     )
     const { graphql } = await import('./client.ts')
@@ -174,17 +176,16 @@ describe('graphql client', () => {
   test('throws friendly message for SUBSCRIPTION_SUSPENDED error code', async () => {
     vi.stubGlobal(
       'fetch',
-      vi.fn().mockResolvedValue({
-        json: () =>
-          Promise.resolve({
-            errors: [
-              {
-                message: 'Subscription is suspended.',
-                extensions: { code: 'SUBSCRIPTION_SUSPENDED' },
-              },
-            ],
-          }),
-      }),
+      vi.fn().mockResolvedValue(
+        ok({
+          errors: [
+            {
+              message: 'Subscription is suspended.',
+              extensions: { code: 'SUBSCRIPTION_SUSPENDED' },
+            },
+          ],
+        }),
+      ),
     )
     const { graphql } = await import('./client.ts')
@@ -192,4 +193,116 @@ describe('graphql client', () => {
       /suspended.*contact support/,
     )
   })
+  describe('transport hardening (F11)', () => {
+    test('throws a SERVER_ERROR-coded error on a non-retryable non-2xx (e.g. 500) without crashing on HTML body', async () => {
+      vi.stubGlobal('fetch', vi.fn().mockResolvedValue(httpError(500)))
+      const { graphql } = await import('./client.ts')
+      await expect(
+        graphql('query { whoami { id } }', undefined, { retryDelayMs: 0 }),
+      ).rejects.toMatchObject({ code: 'SERVER_ERROR' })
+      // Must surface a real message, not a raw SyntaxError about "<"
+      await expect(
+        graphql('query { whoami { id } }', undefined, { retryDelayMs: 0 }),
+      ).rejects.toThrow(/500/)
+    })
+    test('throws SERVER_ERROR (no crash) when a 200 body is not JSON', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          ok: true,
+          status: 200,
+          headers: { get: () => 'text/html' },
+          json: () => Promise.reject(new SyntaxError('Unexpected token <')),
+          text: () => Promise.resolve('<html>proxy</html>'),
+        }),
+      )
+      const { graphql } = await import('./client.ts')
+      await expect(graphql('query { whoami { id } }')).rejects.toMatchObject({
+        code: 'SERVER_ERROR',
+      })
+    })
+    test('retries on a transient 429 then succeeds', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(httpError(429))
+        .mockResolvedValueOnce(ok({ data: { whoami: { id: '1' } } }))
+      vi.stubGlobal('fetch', mockFetch)
+      const { graphql } = await import('./client.ts')
+      const result = await graphql('query { whoami { id } }', undefined, {
+        retryDelayMs: 0,
+      })
+      expect(result).toEqual({ whoami: { id: '1' } })
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+    test('retries on 503 then gives up with a SERVER_ERROR-coded error', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(httpError(503))
+      vi.stubGlobal('fetch', mockFetch)
+      const { graphql } = await import('./client.ts')
+      await expect(
+        graphql('query { whoami { id } }', undefined, {
+          retries: 2,
+          retryDelayMs: 0,
+        }),
+      ).rejects.toMatchObject({ code: 'SERVER_ERROR' })
+      // initial attempt + 2 retries = 3 calls
+      expect(mockFetch).toHaveBeenCalledTimes(3)
+    })
+    test('does NOT retry on a non-transient 400', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(httpError(400))
+      vi.stubGlobal('fetch', mockFetch)
+      const { graphql } = await import('./client.ts')
+      await expect(
+        graphql('query { whoami { id } }', undefined, { retryDelayMs: 0 }),
+      ).rejects.toMatchObject({ code: 'SERVER_ERROR' })
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+    })
+    test('aborts and throws NETWORK_ERROR on timeout', async () => {
+      const mockFetch = vi.fn().mockImplementation((_url, init) => {
+        return new Promise((_resolve, reject) => {
+          const signal = (init as { signal?: AbortSignal }).signal
+          signal?.addEventListener('abort', () => {
+            reject(
+              Object.assign(new Error('The operation was aborted'), {
+                name: 'AbortError',
+              }),
+            )
+          })
+        })
+      })
+      vi.stubGlobal('fetch', mockFetch)
+      const { graphql } = await import('./client.ts')
+      await expect(
+        graphql('query { whoami { id } }', undefined, {
+          timeoutMs: 10,
+          retries: 0,
+          retryDelayMs: 0,
+        }),
+      ).rejects.toMatchObject({ code: 'NETWORK_ERROR' })
+    })
+    test('passes a timeout signal to fetch', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValue(ok({ data: { whoami: { id: '1' } } }))
+      vi.stubGlobal('fetch', mockFetch)
+      const { graphql } = await import('./client.ts')
+      await graphql('query { whoami { id } }')
+      const init = mockFetch.mock.calls[0]![1]
+      expect(init.signal).toBeInstanceOf(AbortSignal)
+    })
+  })
 })

package/src/util/client.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.',
+  )
 }