@sqaoss/flowy 1.2.2 → 1.3.1

package/src/commands/feature.ts

@@ -16,11 +16,21 @@ featureCommand
   .command('create')
   .description('Create a feature in the active project')
   .requiredOption('--title <title>', 'Feature title')
-  .requiredOption('--description <description>', 'Feature description')
+  .option(
+    '--description <text>',
+    'Feature description, used verbatim (never read as a file path)',
+  )
+  .option(
+    '--description-file <path>',
+    'Read the feature description from a file, or "-" for stdin',
+  )
   .action(async (opts) => {
     try {
       const project = requireProject()
-      const description = await resolveDescription(opts.description)
+      const description = await resolveDescription({
+        description: opts.description,
+        descriptionFile: opts.descriptionFile,
+      })
       const nodeData = await graphql<{ createNode: { id: string } }>(
         `mutation CreateNode($type: String!, $title: String!, $description: String) {
           createNode(type: $type, title: $title, description: $description) {

package/src/commands/serve.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockSpawnSync: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  mockSpawnSync = vi.fn(() => ({ status: 0 }))
+  mockOutputError = vi.fn()
+
+  vi.doMock('node:child_process', () => ({
+    spawnSync: mockSpawnSync,
+  }))
+  // Pretend the bundled server entry and its installed deps both exist so the
+  // command takes its normal path deterministically — independent of whether
+  // server/node_modules happens to be populated in this environment (CI runs
+  // the root test job before installing server deps).
+  vi.doMock('node:fs', async () => {
+    const actual = await vi.importActual<typeof import('node:fs')>('node:fs')
+    return { ...actual, existsSync: () => true }
+  })
+  vi.doMock('../util/format.ts', () => ({
+    output: vi.fn(),
+    outputError: mockOutputError,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('serve command', () => {
+  test('exports a command named "serve"', async () => {
+    const { serveCommand } = await import('./serve.ts')
+    expect(serveCommand.name()).toBe('serve')
+  })
+
+  test('declares --port, --host and --db options', async () => {
+    const { serveCommand } = await import('./serve.ts')
+    const flags = serveCommand.options.map((o) => o.long)
+    expect(flags).toContain('--port')
+    expect(flags).toContain('--host')
+    expect(flags).toContain('--db')
+  })
+
+  test('runs the bundled server with bun (no docker) on the chosen port/host', async () => {
+    const { serveCommand } = await import('./serve.ts')
+    await serveCommand.parseAsync(['--port', '4111', '--host', '127.0.0.1'], {
+      from: 'user',
+    })
+
+    // The run invocation is the `bun` call whose args point at the bundled
+    // server entry — not e.g. a `bun install` call. Target it explicitly so
+    // the assertion does not depend on call ordering or environment state.
+    const runCall = mockSpawnSync.mock.calls.find(
+      (call) =>
+        call[0] === 'bun' &&
+        Array.isArray(call[1]) &&
+        call[1].some((a: string) => a.endsWith('index.ts')),
+    )
+    expect(runCall).toBeDefined()
+    const [, args, options] = runCall!
+    // never invokes docker
+    expect(mockSpawnSync.mock.calls.some((call) => call[0] === 'docker')).toBe(
+      false,
+    )
+    // points bun at the bundled server entry
+    expect(args.some((a: string) => a.endsWith('index.ts'))).toBe(true)
+    expect(options.env.PORT).toBe('4111')
+    expect(options.env.HOST).toBe('127.0.0.1')
+  })
+})
+
+describe('pinnedInstallSpec', () => {
+  test('derives the pinned package spec from package.json version', async () => {
+    const { pinnedInstallSpec } = await import('./serve.ts')
+    const { readFileSync } = await import('node:fs')
+    const pkg = JSON.parse(
+      readFileSync(
+        new URL('../../package.json', import.meta.url).pathname,
+        'utf-8',
+      ),
+    ) as { version: string }
+
+    expect(pinnedInstallSpec()).toBe(`@sqaoss/flowy@${pkg.version}`)
+    // never an unpinned install
+    expect(pinnedInstallSpec()).not.toBe('@sqaoss/flowy')
+  })
+})

package/src/commands/serve.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Command } from 'commander'
+import { outputError } from '../util/format.ts'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(here, '..', '..')
+
+/**
+ * The exact, version-pinned npm spec for this CLI's own package. Used by
+ * `setup local` so the installed server matches the CLI rather than drifting
+ * to whatever an unpinned `bun add @sqaoss/flowy` happens to resolve.
+ */
+export function pinnedInstallSpec(): string {
+  const pkg = JSON.parse(
+    readFileSync(resolve(packageRoot, 'package.json'), 'utf-8'),
+  ) as { name: string; version: string }
+  return `${pkg.name}@${pkg.version}`
+}
+
+function serverDir(): string {
+  return resolve(packageRoot, 'server')
+}
+
+function serverEntry(): string {
+  return resolve(serverDir(), 'src', 'index.ts')
+}
+
+/** Install the bundled server's runtime deps once, if they're missing. */
+function ensureServerDeps(dir: string): void {
+  if (existsSync(resolve(dir, 'node_modules', 'graphql-yoga'))) return
+  const install = spawnSync('bun', ['install', '--production'], {
+    cwd: dir,
+    stdio: 'inherit',
+  })
+  if (install.status !== 0) {
+    throw new Error('Failed to install the bundled server dependencies.')
+  }
+}
+
+export const serveCommand = new Command('serve')
+  .description('Run the bundled local Flowy server natively (no Docker)')
+  .option('-p, --port <port>', 'Port to bind', '4000')
+  .option('-H, --host <host>', 'Hostname to bind', '127.0.0.1')
+  .option('-d, --db <path>', 'SQLite database file path', './flowy.sqlite')
+  .action((opts: { port: string; host: string; db: string }) => {
+    try {
+      const dir = serverDir()
+      const entry = serverEntry()
+      if (!existsSync(entry)) {
+        throw new Error(
+          `Bundled server not found at ${entry}. Reinstall ${pinnedInstallSpec()}.`,
+        )
+      }
+
+      ensureServerDeps(dir)
+
+      const result = spawnSync('bun', [entry], {
+        cwd: dir,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          PORT: String(opts.port),
+          HOST: opts.host,
+          FLOWY_DB_PATH: opts.db,
+        },
+      })
+      if (result.status !== 0 && result.status !== null) {
+        throw new Error(`Server exited with status ${result.status}.`)
+      }
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/setup.test.ts

@@ -53,29 +53,27 @@ describe('setup command', () => {
     expect(setupCommand.commands).toHaveLength(2)
   })
 
-  test('setup local checks for docker and errors if not found', async () => {
-    mockSpawnSync.mockReturnValue({ status: 1 })
+  test('setup local installs the pinned package version (no docker)', async () => {
+    mockSpawnSync.mockReturnValue({ status: 0 })
 
     const { setupCommand } = await import('./setup.ts')
+    const { pinnedInstallSpec } = await import('./serve.ts')
     await setupCommand.parseAsync(['local'], { from: 'user' })
 
-    expect(mockSpawnSync).toHaveBeenCalledWith('docker', ['--version'], {
-      stdio: 'ignore',
-    })
-    expect(mockOutputError).toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: expect.stringContaining('Docker is required'),
-      }),
+    // installs the package pinned to the exact CLI version
+    expect(mockSpawnSync).toHaveBeenCalledWith(
+      'bun',
+      ['add', pinnedInstallSpec()],
+      expect.anything(),
+    )
+    // never shells out to docker
+    expect(mockSpawnSync.mock.calls.some((call) => call[0] === 'docker')).toBe(
+      false,
     )
   })
 
   test('setup local saves config with mode "local" and apiUrl on success', async () => {
     mockSpawnSync.mockReturnValue({ status: 0 })
-    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true }))
-    vi.doMock('node:fs', async () => {
-      const actual = await vi.importActual<typeof import('node:fs')>('node:fs')
-      return { ...actual, existsSync: () => true }
-    })
 
     const { setupCommand } = await import('./setup.ts')
     await setupCommand.parseAsync(['local'], { from: 'user' })

package/src/commands/setup.ts

@@ -1,62 +1,8 @@
 import { spawnSync } from 'node:child_process'
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { resolve } from 'node:path'
 import { Command, Option } from 'commander'
 import { loadConfig, saveConfig } from '../util/config.ts'
 import { output, outputError } from '../util/format.ts'
-
-const COMPOSE_CONTENT = `services:
-  server:
-    build:
-      context: .
-      dockerfile_inline: |
-        FROM oven/bun:1.3.11
-        WORKDIR /app
-        RUN bun init -y && bun add @sqaoss/flowy
-        WORKDIR /app/node_modules/@sqaoss/flowy/server
-        RUN bun install --production
-        EXPOSE 4000
-        VOLUME /data
-        CMD ["bun", "src/index.ts"]
-    ports:
-      - "4000:4000"
-    volumes:
-      - flowy-data:/data
-    environment:
-      - FLOWY_DB_PATH=/data/flowy.sqlite
-      - PORT=4000
-    healthcheck:
-      test: ["CMD", "bun", "-e", "fetch('http://localhost:4000/health').then(r => r.ok ? process.exit(0) : process.exit(1))"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-volumes:
-  flowy-data:
-`
-
-function ensureComposeFile(): string {
-  const dir = resolve(homedir(), '.config', 'flowy')
-  mkdirSync(dir, { recursive: true })
-  const composePath = resolve(dir, 'docker-compose.yml')
-  writeFileSync(composePath, COMPOSE_CONTENT)
-  return composePath
-}
-
-async function pollHealth(url: string, timeoutMs = 60_000): Promise<void> {
-  const start = Date.now()
-  while (Date.now() - start < timeoutMs) {
-    try {
-      const res = await fetch(url)
-      if (res.ok) return
-    } catch {}
-    await new Promise((r) => setTimeout(r, 1_000))
-  }
-  throw new Error(
-    `Health check at ${url} did not respond within ${timeoutMs / 1_000}s.`,
-  )
-}
+import { pinnedInstallSpec } from './serve.ts'
 
 export const setupCommand = new Command('setup').description(
   'Configure the Flowy CLI \u2014 use "flowy setup local" or "flowy setup remote"',
@@ -64,28 +10,18 @@ export const setupCommand = new Command('setup').description(
 
 setupCommand
   .command('local')
-  .description('Set up Flowy with a local Docker server')
+  .description('Set up Flowy with a native local server (no Docker)')
   .action(async () => {
     try {
-      const dockerCheck = spawnSync('docker', ['--version'], {
-        stdio: 'ignore',
-      })
-      if (dockerCheck.status !== 0) {
-        throw new Error('Docker is required but was not found.')
+      // Pin the install to this CLI's exact version so the server can never
+      // drift to a stale npm release behind a cached Docker layer (F15).
+      const spec = pinnedInstallSpec()
+      const install = spawnSync('bun', ['add', spec], { stdio: 'inherit' })
+      if (install.status !== 0) {
+        throw new Error(`Failed to install ${spec}.`)
       }
 
-      const composePath = ensureComposeFile()
-      spawnSync(
-        'docker',
-        ['compose', '-f', composePath, 'up', '-d', '--build'],
-        {
-          stdio: 'inherit',
-        },
-      )
-
       const apiUrl = 'http://localhost:4000/graphql'
-      await pollHealth('http://localhost:4000/health')
-
       const config = loadConfig()
       config.mode = 'local'
       config.apiUrl = apiUrl
@@ -94,7 +30,12 @@ setupCommand
         stdio: 'inherit',
       })
 
-      output({ mode: 'local', apiUrl })
+      output({
+        mode: 'local',
+        apiUrl,
+        installed: spec,
+        next: 'Run "flowy serve" to start the local server (binds 127.0.0.1:4000).',
+      })
     } catch (error) {
       outputError(error)
     }

package/src/commands/task.test.ts

@@ -31,6 +31,14 @@ describe('task command', () => {
     expect(names).toContain('unblock')
   })
 
+  test('create exposes both --description and --description-file options', async () => {
+    const { taskCommand } = await import('./task.ts')
+    const createCmd = taskCommand.commands.find((c) => c.name() === 'create')!
+    const optionFlags = createCmd.options.map((o) => o.long)
+    expect(optionFlags).toContain('--description')
+    expect(optionFlags).toContain('--description-file')
+  })
+
   test('create calls outputError when no active feature', async () => {
     const { taskCommand } = await import('./task.ts')
     const { outputError } = await import('../util/format.ts')

package/src/commands/task.ts

@@ -12,14 +12,21 @@ taskCommand
   .command('create')
   .description('Create a task in the active feature')
   .requiredOption('--title <title>', 'Task title')
-  .requiredOption(
-    '--description <desc>',
-    'Task description (text or file path)',
+  .option(
+    '--description <text>',
+    'Task description, used verbatim (never read as a file path)',
+  )
+  .option(
+    '--description-file <path>',
+    'Read the task description from a file, or "-" for stdin',
   )
   .action(async (opts) => {
     try {
       const featureId = requireFeature()
-      const description = await resolveDescription(opts.description)
+      const description = await resolveDescription({
+        description: opts.description,
+        descriptionFile: opts.descriptionFile,
+      })
       const data = await graphql<{ createNode: { id: string } }>(
         `mutation CreateTask($type: String!, $title: String!, $description: String) {
           createNode(type: $type, title: $title, description: $description) {

package/src/index.test.ts

@@ -39,6 +39,9 @@ vi.mock('./commands/billing.ts', () => ({
 vi.mock('./commands/key.ts', () => ({
   keyCommand: { name: () => 'key' },
 }))
+vi.mock('./commands/serve.ts', () => ({
+  serveCommand: { name: () => 'serve' },
+}))
 
 describe('index.ts command registration', () => {
   test('registers billing and key commands', async () => {
@@ -57,4 +60,17 @@ describe('index.ts command registration', () => {
     expect(indexSource).toContain('program.addCommand(billingCommand)')
     expect(indexSource).toContain('program.addCommand(keyCommand)')
   })
+
+  test('registers the serve command', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { serveCommand } from './commands/serve.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(serveCommand)')
+  })
 })

package/src/index.ts

@@ -19,6 +19,7 @@ import { initCommand } from './commands/init.ts'
 import { keyCommand } from './commands/key.ts'
 import { projectCommand } from './commands/project.ts'
 import { searchCommand } from './commands/search.ts'
+import { serveCommand } from './commands/serve.ts'
 import { setupCommand } from './commands/setup.ts'
 import { statusCommand } from './commands/status.ts'
 import { taskCommand } from './commands/task.ts'
@@ -32,6 +33,7 @@ const program = new Command()
 
 program.addCommand(initCommand)
 program.addCommand(setupCommand)
+program.addCommand(serveCommand)
 program.addCommand(clientCommand)
 program.addCommand(projectCommand)
 program.addCommand(featureCommand)