@sqaoss/flowy 1.11.0 → 1.13.0

package/README.md

@@ -108,6 +108,41 @@ A manifest looks like:
 
 Each node's `parent` implies a `part_of` edge, so the simplest manifests need no explicit `edges`. `blocks` dependencies go in `edges`. The reserved `__flowyKey` metadata field stores the client-key; your own `metadata` is preserved alongside it and stripped back out on export.
 
+### Backup and restore (local SQLite)
+
+In self-hosted mode your backlog lives in a single SQLite file (see [Where your data lives](#where-your-data-lives)). `flowy backup` takes a consistent, file-level snapshot of that database, and `flowy restore` reinstates one.
+
+```bash
+flowy backup flowy-backup.sqlite             # snapshot the local DB (./flowy.sqlite by default)
+flowy backup ~/snapshots/flowy.sqlite --db ~/flowy.sqlite   # back up a DB at a custom path
+flowy restore flowy-backup.sqlite            # restore into a fresh DB (refuses to clobber)
+flowy restore flowy-backup.sqlite --force    # overwrite an existing DB
+```
+
+The snapshot is taken with SQLite's `VACUUM INTO`, so it is transactionally consistent **even while the server is running** and writes a single self-contained file (no `-wal`/`-shm` sidecars). `restore` validates the source is a real SQLite database before touching the target, and **refuses to overwrite an existing database** unless you pass `--force`.
+
+Both commands resolve the database path the same way the server does: `--db <path>`, then `$FLOWY_DB_PATH`, then `./flowy.sqlite`.
+
+**`backup` vs. `export` — they're complementary, not redundant:**
+
+| | `flowy export` (logical) | `flowy backup` (raw) |
+|---|---|---|
+| Format | Portable JSON manifest | Exact SQLite file |
+| Scope | The active project's subtree | The entire database (all projects) |
+| Re-importable | Yes — `flowy import` (idempotent, cross-backend) | No — restore only, local server |
+| Use it for | Migrating between machines/backends, re-importing, diffing in git | Point-in-time disaster recovery, an exact byte-faithful snapshot |
+
+Use `export`/`import` to move a backlog around or seed another backend; use `backup`/`restore` for a true snapshot of your local server's data.
+
+### Where your data lives
+
+The self-hosted server persists everything in one SQLite file. Its location depends on how you run the server:
+
+- **`flowy serve`** (native): `./flowy.sqlite` in the current directory by default, or wherever `--db`/`$FLOWY_DB_PATH` points.
+- **Docker (`docker compose up`)**: inside the named volume `flowy-data`, mounted at `/data`, with `FLOWY_DB_PATH=/data/flowy.sqlite`. The data outlives the container — but `docker compose down -v` deletes the volume **and your backlog with it**. Take a `flowy backup` first.
+
+To back up the Docker volume's database, point `--db` at the in-container path while running `flowy backup` from inside the container, or restore into a fresh `flowy serve` directory and snapshot there.
+
 ## Agent Skill
 
 `flowy setup` installs an agent skill so your AI agent automatically knows every command. If that install step fails (offline, no `npx`, registry hiccup), setup prints a warning telling you to install it manually:
@@ -145,7 +180,7 @@ flowy serve                  # bind 127.0.0.1:4000, store data in ./flowy.sqlite
 flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite   # override defaults
 ```
 
-The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, and `import`/`export`. Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
+The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, `import`/`export`, and `backup`/`restore` (raw SQLite snapshots). Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
 
 The canonical status flow is `draft → pending_review → approved → in_progress → done`, plus `blocked` and `cancelled`. By default any status change is allowed (and the `status` command validates the value client-side). To make the local server *enforce* legal transitions — rejecting illegal jumps like `draft → done` with a `VALIDATION_ERROR` — start it with `FLOWY_ENFORCE_STATUS_LIFECYCLE=1`. Enforcement is opt-in and off by default.
 
@@ -185,6 +220,8 @@ The canonical status flow is `draft → pending_review → approved → in_progr
 | `tree <id> [--depth N]` | Show subtree from any entity |
 | `import <manifest>` | Ingest a JSON manifest of nodes + edges (idempotent by client-key) |
 | `export [output]` | Dump the active project as a manifest (stdout or file) |
+| `backup <dest> [--db <path>]` | Consistent file-level snapshot of the local SQLite database |
+| `restore <src> [--db <path>] [--force]` | Restore the local SQLite database from a backup (refuses to clobber without `--force`) |
 | `whoami` | Show current user (remote mode) |
 | `billing checkout --tier <tier>` | Get a checkout URL for a subscription (remote mode) |
 | `key rotate` | Revoke all API keys and issue a new one (remote mode) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {

package/server/src/contract.test.ts

@@ -175,6 +175,48 @@ describe('CLI/local-server contract (P1-1)', () => {
       relation: 'part_of',
     })
 
+    // CREATE_NODE_WITH_PARENT (P1-4/F24): create a node AND its part_of edge to
+    // the feature in one atomic call. The returned node must be a real child of
+    // the feature (reachable via the part_of hierarchy), proving the edge was
+    // created in the same unit of work — no separate createEdge call needed.
+    const { createNode: parentedTask } = await ok<{
+      createNode: { id: string }
+    }>(LOCAL_CONTRACT_OPERATIONS.CREATE_NODE_WITH_PARENT, {
+      type: 'task',
+      title: 'Parented Task',
+      description: 'linked atomically',
+      parentId: feature.id,
+    })
+    expect(parentedTask.id).toMatch(/^task_/)
+    const parentedChildren = await ok<{ descendants: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.LIST_TASKS,
+      { nodeId: feature.id, relation: 'part_of', maxDepth: 1 },
+    )
+    expect(parentedChildren.descendants.map((n) => n.id)).toContain(
+      parentedTask.id,
+    )
+
+    // A non-existent parent must be rejected (NOT_FOUND) and leave no orphan.
+    const beforeOrphan = await ok<{ nodes: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.ALL_TASKS,
+      { type: 'task' },
+    )
+    const badParent = await run(
+      LOCAL_CONTRACT_OPERATIONS.CREATE_NODE_WITH_PARENT,
+      {
+        type: 'task',
+        title: 'Should Not Exist',
+        description: 'orphan attempt',
+        parentId: 'feat_missing',
+      },
+    )
+    expect(badParent.errors).toBeDefined()
+    const afterOrphan = await ok<{ nodes: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.ALL_TASKS,
+      { type: 'task' },
+    )
+    expect(afterOrphan.nodes).toHaveLength(beforeOrphan.nodes.length)
+
     // blocker blocks task
     const { createEdge: blocksEdge } = await ok<{
       createEdge: { relation: string; createdAt: string }
@@ -443,6 +485,7 @@ describe('CLI/local-server contract (P1-1)', () => {
       'CREATE_PROJECT',
       'CREATE_NODE',
       'CREATE_TASK',
+      'CREATE_NODE_WITH_PARENT',
       'UPDATE_NODE',
       'UPDATE_STATUS',
       'APPROVE_NODE',

package/server/src/resolvers.test.ts

@@ -151,6 +151,79 @@ describe('createResolvers', () => {
     })
   })
 
+  describe('Mutation.createNode with parentId (F24)', () => {
+    it('creates the node and a part_of edge to the parent atomically', () => {
+      const parent = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'Parent Feature',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Child Task',
+        parentId: parent.id,
+      })
+      expect(child.id).toMatch(/^task_/)
+      // the node exists
+      expect(resolvers.Query.node(null, { id: child.id })?.id).toBe(child.id)
+      // a part_of edge child -> parent exists (child reachable from parent)
+      const children = resolvers.Query.descendants(null, {
+        nodeId: parent.id,
+        relation: 'part_of',
+        maxDepth: 1,
+      })
+      expect(children.map((n) => n.id)).toContain(child.id)
+    })
+
+    it('writes a create audit row and a create_edge audit row for the link', () => {
+      const parent = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'Parent',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Child',
+        parentId: parent.id,
+      })
+      const childHistory = resolvers.Query.auditLog(null, { nodeId: child.id })
+      const actions = childHistory.map((e) => e.action)
+      expect(actions).toContain('create')
+      expect(actions).toContain('create_edge')
+      const edgeEntry = childHistory.find((e) => e.action === 'create_edge')
+      expect(edgeEntry?.field).toBe('part_of')
+      expect(edgeEntry?.newValue).toBe(parent.id)
+    })
+
+    it('rejects a non-existent parent with NOT_FOUND and creates no orphan', () => {
+      const before = resolvers.Query.nodes(null, {})
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Orphan?',
+          parentId: 'feat_does_not_exist',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('feat_does_not_exist')
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+      }
+      // nothing was written: no new node, no dangling edge
+      const after = resolvers.Query.nodes(null, {})
+      expect(after).toHaveLength(before.length)
+      expect(after.some((n) => n.title === 'Orphan?')).toBe(false)
+    })
+
+    it('behaves exactly like a plain create when parentId is omitted', () => {
+      const node = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'No parent',
+      })
+      expect(node.id).toMatch(/^task_/)
+      const history = resolvers.Query.auditLog(null, { nodeId: node.id })
+      expect(history.map((e) => e.action)).toEqual(['create'])
+    })
+  })
+
   describe('Query.node', () => {
     it('returns a node by id', () => {
       const created = resolvers.Mutation.createNode(null, {

package/server/src/resolvers.ts

@@ -495,6 +495,13 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
     },
 
     Mutation: {
+      // Create a node, optionally linking it under a parent in one atomic step
+      // (F24). When `parentId` is given we validate the parent exists FIRST —
+      // before any write — then, in a SINGLE transaction, insert the node, its
+      // `create` audit row, the `part_of` edge (child -> parent), and the
+      // edge's `create_edge` audit row. A failure anywhere rolls the whole unit
+      // back, so a bad link can never leave an orphaned node. With no
+      // `parentId`, behaviour is unchanged: just the node + its create audit.
       createNode: (
         _: unknown,
         args: {
@@ -503,6 +510,7 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           description?: string
           status?: string
           metadata?: string
+          parentId?: string
         },
       ): NodeGql => {
         if (!args.title.trim()) throw validationError('Title is required')
@@ -510,6 +518,15 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           throw validationError('Description cannot be empty')
         }
         if (args.status != null) assertValidStatus(args.status)
+        // Validate the parent up front so a bad link errors before any write.
+        if (args.parentId != null) {
+          const parentExists = db.raw
+            .query('SELECT id FROM nodes WHERE id = ?')
+            .get(args.parentId)
+          if (!parentExists) {
+            throw notFoundError(`Parent node ${args.parentId} not found`)
+          }
+        }
         const metadata =
           args.metadata != null ? normalizeMetadata(args.metadata) : null
         const id = generateId(args.type)
@@ -545,6 +562,18 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
             action: 'create',
             snapshot: node as unknown as Record<string, unknown>,
           })
+          if (args.parentId != null) {
+            db.raw.run(
+              'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
+              [id, args.parentId, 'part_of', now],
+            )
+            insertAudit(db, {
+              nodeId: id,
+              action: 'create_edge',
+              field: 'part_of',
+              newValue: args.parentId,
+            })
+          }
         })()
         return node
       },

package/server/src/schema.ts

@@ -85,6 +85,7 @@ export const typeDefs = /* GraphQL */ `
       description: String
       status: String
       metadata: String
+      parentId: String
     ): Node!
     updateNode(
       id: String!

package/skills/using-flowy/SKILL.md

@@ -22,6 +22,7 @@ Flowy runs against one of two backends. Which one you're in determines which com
 | Account / API key | None | Email registration; API key stored in config |
 | Subscription | None — fully free | Data operations require an active subscription |
 | Planning workflow | Full (`init`, project/feature/task CRUD, status, approve, search, tree, `task deps`, `task list --ready/--all`, `import`/`export`) | Full, same commands |
+| `backup` / `restore` | Available (raw SQLite snapshot of the local DB) | **Not available** — local-only |
 | `whoami` / `billing` / `key` | **Not available** — these hard-fail locally | Available |
 
 The planning workflow is **identical** in both modes. Only the account/billing commands differ.
@@ -183,6 +184,19 @@ A manifest is a single JSON document describing a backlog: `nodes` (projects, fe
 
 **Idempotency:** import upserts by client-key — re-importing the same manifest updates the matching nodes in place instead of creating duplicates. The key is stored in node metadata under the reserved `__flowyKey` field (your own `metadata` is preserved alongside it and stripped back out on export). A node's `parent` implies a `part_of` edge, so simple manifests need no explicit `edges`; `blocks` dependencies are listed in `edges`. Edges live in the real edge model (`createEdge` / `Query.edges`), so a `blocks` edge created by hand with `task block` is captured on export and never re-created on the next import. Works in both local and remote modes.
 
+### Backup and Restore (local mode only)
+```bash
+flowy backup flowy-backup.sqlite             # consistent snapshot of the local SQLite DB
+flowy restore flowy-backup.sqlite            # restore into a fresh DB (refuses to clobber)
+flowy restore flowy-backup.sqlite --force    # overwrite an existing DB
+```
+
+`backup`/`restore` operate on the **raw SQLite file** the self-hosted server uses, resolving its path from `--db`, then `$FLOWY_DB_PATH`, then `./flowy.sqlite`. The snapshot is taken with SQLite `VACUUM INTO`, so it is consistent even while the server is running. `restore` refuses to overwrite an existing database without `--force`.
+
+This is **complementary to** `export`/`import`, not a replacement: `export` produces a portable, re-importable JSON manifest of one project (works in both modes); `backup` produces an exact, byte-faithful snapshot of the whole local database for disaster recovery (local mode only). Use `export` to move or seed a backlog; use `backup` for a true point-in-time snapshot.
+
+**Where the data lives:** in self-hosted mode the entire backlog is one SQLite file — `./flowy.sqlite` by default (or `$FLOWY_DB_PATH`). Under Docker it lives in the named volume `flowy-data` (mounted at `/data`, `FLOWY_DB_PATH=/data/flowy.sqlite`); `docker compose down -v` deletes that volume and the backlog with it, so take a `flowy backup` first.
+
 ### Remote-only (hosted mode)
 These hit account/billing resolvers that do **not** exist on the local server; they fail in local mode.
 ```bash

package/src/commands/backup.test.ts

@@ -0,0 +1,252 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+let workDir: string
+
+// `bun:sqlite` is unavailable under the Node-based root test runner, so these
+// tests drive a real `bun` subprocess to seed and read SQLite files. That keeps
+// the row-level assertions genuine (open the backup, compare rows) without
+// importing `bun:sqlite` into Node — exactly how the CLI runs at runtime.
+
+/** Create a populated SQLite DB at `path` via a real bun subprocess. */
+function seedDb(
+  path: string,
+  rows: Array<{ id: string; title: string }> = [
+    { id: 'n1', title: 'Alpha' },
+    { id: 'n2', title: 'Beta' },
+    { id: 'n3', title: 'Gamma' },
+  ],
+): Array<{ id: string; title: string }> {
+  const script = `
+    const { Database } = require('bun:sqlite')
+    const db = new Database(process.argv[1])
+    db.run('PRAGMA journal_mode = WAL')
+    db.run('CREATE TABLE nodes (id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL)')
+    const rows = JSON.parse(process.argv[2])
+    for (const r of rows) db.run('INSERT INTO nodes (id, type, title) VALUES (?, ?, ?)', [r.id, 'task', r.title])
+    db.close()
+  `
+  const res = spawnSync('bun', ['-e', script, path, JSON.stringify(rows)], {
+    encoding: 'utf-8',
+  })
+  if (res.status !== 0) throw new Error(`seedDb failed: ${res.stderr}`)
+  return rows
+}
+
+/** Read all node {id,title} rows from a SQLite file via a real bun subprocess. */
+function readNodes(path: string): Array<{ id: string; title: string }> {
+  const script = `
+    const { Database } = require('bun:sqlite')
+    const db = new Database(process.argv[1], { readonly: true })
+    console.log(JSON.stringify(db.query('SELECT id, title FROM nodes ORDER BY id').all()))
+    db.close()
+  `
+  const res = spawnSync('bun', ['-e', script, path], { encoding: 'utf-8' })
+  if (res.status !== 0) throw new Error(`readNodes failed: ${res.stderr}`)
+  return JSON.parse(res.stdout.trim())
+}
+
+beforeEach(() => {
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+  workDir = mkdtempSync(join(tmpdir(), 'flowy-backup-'))
+  delete process.env.FLOWY_DB_PATH
+})
+
+afterEach(() => {
+  rmSync(workDir, { recursive: true, force: true })
+  delete process.env.FLOWY_DB_PATH
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('backup command', () => {
+  test('exports a command named "backup"', async () => {
+    const { backupCommand } = await import('./backup.ts')
+    expect(backupCommand.name()).toBe('backup')
+  })
+
+  test('declares a --db option', async () => {
+    const { backupCommand } = await import('./backup.ts')
+    const flags = backupCommand.options.map((o) => o.long)
+    expect(flags).toContain('--db')
+  })
+
+  test('writes a valid SQLite snapshot whose rows match the source DB', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const dest = join(workDir, 'backup.sqlite')
+    const expected = seedDb(src)
+
+    const { backupCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([dest, '--db', src], { from: 'user' })
+
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(existsSync(dest)).toBe(true)
+    // The backup is a real, openable SQLite database with identical rows.
+    expect(readNodes(dest)).toEqual(expected)
+  })
+
+  test('resolves the DB path from FLOWY_DB_PATH when --db is omitted', async () => {
+    const src = join(workDir, 'env.sqlite')
+    const dest = join(workDir, 'backup.sqlite')
+    const expected = seedDb(src)
+    process.env.FLOWY_DB_PATH = src
+
+    const { backupCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([dest], { from: 'user' })
+
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(readNodes(dest)).toEqual(expected)
+  })
+
+  test('produces a consistent snapshot while the source DB is open (WAL)', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const dest = join(workDir, 'backup.sqlite')
+    const expected = seedDb(src)
+
+    // A long-lived bun process holds the DB open to mimic a running server.
+    const holder = spawnSync(
+      'bun',
+      [
+        '-e',
+        `const { Database } = require('bun:sqlite'); const db = new Database(process.argv[1]); db.query('SELECT 1').get(); Bun.sleepSync(50); db.close()`,
+        src,
+      ],
+      { encoding: 'utf-8' },
+    )
+    expect(holder.status).toBe(0)
+
+    const { backupCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([dest, '--db', src], { from: 'user' })
+
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(readNodes(dest)).toEqual(expected)
+  })
+
+  test('errors when the source DB does not exist', async () => {
+    const dest = join(workDir, 'backup.sqlite')
+    const missing = join(workDir, 'nope.sqlite')
+
+    const { backupCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([dest, '--db', missing], { from: 'user' })
+
+    expect(mockOutputError).toHaveBeenCalled()
+    expect(existsSync(dest)).toBe(false)
+  })
+
+  test('reports the source and destination on success', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const dest = join(workDir, 'backup.sqlite')
+    seedDb(src)
+
+    const { backupCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([dest, '--db', src], { from: 'user' })
+
+    expect(mockOutput).toHaveBeenCalledWith(
+      expect.objectContaining({ source: src, file: dest }),
+    )
+  })
+})
+
+describe('restore command', () => {
+  test('exports a command named "restore"', async () => {
+    const { restoreCommand } = await import('./backup.ts')
+    expect(restoreCommand.name()).toBe('restore')
+  })
+
+  test('declares --db and --force options', async () => {
+    const { restoreCommand } = await import('./backup.ts')
+    const flags = restoreCommand.options.map((o) => o.long)
+    expect(flags).toContain('--db')
+    expect(flags).toContain('--force')
+  })
+
+  test('round-trips: restoring a backup reproduces the original rows', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const backup = join(workDir, 'backup.sqlite')
+    const target = join(workDir, 'restored.sqlite')
+    const expected = seedDb(src)
+
+    const { backupCommand, restoreCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([backup, '--db', src], { from: 'user' })
+    await restoreCommand.parseAsync([backup, '--db', target], { from: 'user' })
+
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(readNodes(target)).toEqual(expected)
+  })
+
+  test('refuses to clobber an existing DB without --force', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const backup = join(workDir, 'backup.sqlite')
+    const target = join(workDir, 'existing.sqlite')
+    // Pre-existing target whose content must NOT be overwritten.
+    const original = seedDb(target, [{ id: 'keep', title: 'Original' }])
+    // Source (and thus backup) differs from the existing target.
+    seedDb(src, [{ id: 'new', title: 'Incoming' }])
+
+    const { backupCommand, restoreCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([backup, '--db', src], { from: 'user' })
+
+    mockOutputError.mockClear()
+    await restoreCommand.parseAsync([backup, '--db', target], { from: 'user' })
+
+    expect(mockOutputError).toHaveBeenCalled()
+    // The existing DB is untouched.
+    expect(readNodes(target)).toEqual(original)
+  })
+
+  test('overwrites an existing DB when --force is given', async () => {
+    const src = join(workDir, 'flowy.sqlite')
+    const backup = join(workDir, 'backup.sqlite')
+    const target = join(workDir, 'existing.sqlite')
+    seedDb(target, [{ id: 'old', title: 'Stale' }]) // pre-existing, replaced
+    seedDb(src, [{ id: 'z9', title: 'New' }])
+
+    const { backupCommand, restoreCommand } = await import('./backup.ts')
+    await backupCommand.parseAsync([backup, '--db', src], { from: 'user' })
+    await restoreCommand.parseAsync([backup, '--db', target, '--force'], {
+      from: 'user',
+    })
+
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(readNodes(target)).toEqual([{ id: 'z9', title: 'New' }])
+  })
+
+  test('errors when the backup source does not exist', async () => {
+    const target = join(workDir, 'restored.sqlite')
+    const missing = join(workDir, 'nope.sqlite')
+
+    const { restoreCommand } = await import('./backup.ts')
+    await restoreCommand.parseAsync([missing, '--db', target], { from: 'user' })
+
+    expect(mockOutputError).toHaveBeenCalled()
+    expect(existsSync(target)).toBe(false)
+  })
+
+  test('errors when the backup source is not a valid SQLite database', async () => {
+    const target = join(workDir, 'restored.sqlite')
+    const garbage = join(workDir, 'garbage.bin')
+    writeFileSync(garbage, 'this is not a sqlite database')
+
+    const { restoreCommand } = await import('./backup.ts')
+    await restoreCommand.parseAsync([garbage, '--db', target], { from: 'user' })
+
+    // A corrupt source must surface as a clean snapshot failure, not an
+    // incidental downstream error (e.g. a rename ENOENT).
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'BACKUP_ERROR' }),
+    )
+    expect(existsSync(target)).toBe(false)
+    // No staged temp file is left behind.
+    expect(existsSync(`${target}.restore-tmp`)).toBe(false)
+  })
+})

package/src/commands/backup.ts

@@ -0,0 +1,145 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, renameSync, rmSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Command } from 'commander'
+import { output, outputError } from '../util/format.ts'
+
+/**
+ * Resolve the local SQLite database path the bundled server uses, from the same
+ * sources `server/src/index.ts` and `flowy serve` honour:
+ *   1. an explicit `--db <path>` flag
+ *   2. the `FLOWY_DB_PATH` env var
+ *   3. the default `./flowy.sqlite`
+ */
+export function resolveDbPath(dbOpt?: string): string {
+  return dbOpt ?? process.env.FLOWY_DB_PATH ?? './flowy.sqlite'
+}
+
+/**
+ * Snapshot one SQLite database into another file with `VACUUM INTO`.
+ *
+ * `VACUUM INTO` takes a transactionally-consistent snapshot even while the
+ * source is open/being written by a running server (it reads under a read
+ * transaction), and writes a single fully-checkpointed file with no `-wal`/
+ * `-shm` sidecars — strictly safer than copying the file bytes. It also fails
+ * cleanly if `src` is not a valid SQLite database, which doubles as validation.
+ *
+ * Runs in a `bun` subprocess so this module never imports `bun:sqlite`
+ * (unavailable under the Node-based unit-test runner); the CLI itself always
+ * runs under bun, so the subprocess shares the same runtime.
+ */
+function vacuumInto(src: string, dest: string): void {
+  // Note: `bun -e` does not reliably exit non-zero on an uncaught throw, so the
+  // script explicitly catches, writes the message to stderr, and exits 1 — that
+  // is what lets the parent distinguish a corrupt source from a clean snapshot.
+  const script = `
+    const { Database } = require('bun:sqlite')
+    try {
+      const db = new Database(process.argv[1], { readonly: true })
+      try {
+        db.run('VACUUM INTO ?', [process.argv[2]])
+      } finally {
+        db.close()
+      }
+    } catch (e) {
+      console.error(e && e.message ? e.message : String(e))
+      process.exit(1)
+    }
+  `
+  const result = spawnSync('bun', ['-e', script, src, dest], {
+    encoding: 'utf-8',
+  })
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim()
+    const err = new Error(
+      `Failed to snapshot SQLite database ${src}${detail ? `: ${detail}` : '.'}`,
+    ) as Error & { code?: string }
+    err.code = 'BACKUP_ERROR'
+    throw err
+  }
+}
+
+/** Remove a SQLite file together with its `-wal`/`-shm` sidecars. */
+function removeDbFiles(path: string): void {
+  for (const suffix of ['', '-wal', '-shm', '-journal']) {
+    rmSync(`${path}${suffix}`, { force: true })
+  }
+}
+
+export const backupCommand = new Command('backup')
+  .description(
+    'Write a consistent file-level snapshot of the local SQLite database',
+  )
+  .argument('<dest>', 'Path to write the backup file to')
+  .option(
+    '-d, --db <path>',
+    'SQLite database to back up (default: $FLOWY_DB_PATH or ./flowy.sqlite)',
+  )
+  .action((dest: string, opts: { db?: string }) => {
+    try {
+      const src = resolveDbPath(opts.db)
+      if (!existsSync(src)) {
+        const err = new Error(
+          `No SQLite database at ${resolve(src)}. ` +
+            `Set --db or FLOWY_DB_PATH, or start the server first.`,
+        ) as Error & { code?: string }
+        err.code = 'NOT_FOUND'
+        throw err
+      }
+      // VACUUM INTO refuses to write an existing file, so clear a stale dest.
+      removeDbFiles(dest)
+      vacuumInto(src, dest)
+      output({ source: src, file: dest })
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+export const restoreCommand = new Command('restore')
+  .description('Restore the local SQLite database from a backup file')
+  .argument('<src>', 'Path to a backup file produced by "flowy backup"')
+  .option(
+    '-d, --db <path>',
+    'SQLite database to restore into (default: $FLOWY_DB_PATH or ./flowy.sqlite)',
+  )
+  .option('-f, --force', 'Overwrite the target database if it already exists')
+  .action((src: string, opts: { db?: string; force?: boolean }) => {
+    try {
+      if (!existsSync(src)) {
+        const err = new Error(`No backup file at ${resolve(src)}.`) as Error & {
+          code?: string
+        }
+        err.code = 'NOT_FOUND'
+        throw err
+      }
+      const target = resolveDbPath(opts.db)
+      if (existsSync(target) && !opts.force) {
+        const err = new Error(
+          `Target database ${resolve(target)} already exists. ` +
+            `Re-run with --force to overwrite it (the current data will be lost).`,
+        ) as Error & { code?: string }
+        err.code = 'TARGET_EXISTS'
+        throw err
+      }
+      // VACUUM INTO validates that `src` is a real SQLite database and writes a
+      // clean single-file copy. Stage it next to the target first, so a corrupt
+      // backup never destroys the existing DB before validation succeeds.
+      const staged = `${target}.restore-tmp`
+      removeDbFiles(staged)
+      try {
+        vacuumInto(src, staged)
+      } catch (error) {
+        removeDbFiles(staged)
+        throw error
+      }
+      // Validation passed — swap the staged copy into place. `staged` sits in
+      // the same directory as `target`, so this rename stays on one filesystem.
+      // VACUUM INTO never creates `-wal`/`-shm` sidecars, so only the main file
+      // needs moving.
+      removeDbFiles(target)
+      renameSync(staged, target)
+      output({ restored: target, source: src })
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/feature.test.ts

@@ -56,6 +56,50 @@ describe('feature command', () => {
     )
   })
 
+  test('create issues ONE createNode-with-parent call under the active project', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { requireProject } = await import('../util/config.ts')
+    const { output } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(requireProject).mockReturnValueOnce({
+      id: 'proj_active',
+      name: 'active',
+    })
+    vi.mocked(graphql).mockResolvedValueOnce({
+      createNode: { id: 'feat_new', title: 'Test' },
+    })
+
+    const createCmd = featureCommand.commands.find((c) => c.name() === 'create')
+    await createCmd?.parseAsync(['--title', 'Test', '--description', 'Desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledTimes(1)
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('createNode')
+    expect(query).toContain('parentId')
+    expect(variables).toMatchObject({
+      type: 'feature',
+      title: 'Test',
+      description: 'Desc',
+      parentId: 'proj_active',
+    })
+    expect(output).toHaveBeenCalledWith({ id: 'feat_new', title: 'Test' })
+  })
+
+  test('create validates the project BEFORE any write (no createNode on bad project)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    const createCmd = featureCommand.commands.find((c) => c.name() === 'create')
+    await createCmd?.parseAsync(['--title', 'Test', '--description', 'Desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).not.toHaveBeenCalled()
+  })
+
   test('unset calls updateProjectConfig to delete activeFeature', async () => {
     const { featureCommand } = await import('./feature.ts')
     const { output } = await import('../util/format.ts')

package/src/commands/feature.ts

@@ -8,7 +8,6 @@ import {
 import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
 import {
-  CREATE_EDGE,
   CREATE_NODE,
   DELETE_NODE,
   DESCENDANTS,
@@ -35,21 +34,24 @@ featureCommand
   )
   .action(async (opts) => {
     try {
+      // Validate the active project BEFORE any write so a bad project context
+      // errors cleanly instead of orphaning a node (F24).
       const project = requireProject()
       const description = await resolveDescription({
         description: opts.description,
         descriptionFile: opts.descriptionFile,
       })
+      // One atomic call: the server creates the feature and its `part_of` edge
+      // to the project together, so a failed link can never leave an orphan.
       const nodeData = await graphql<{ createNode: { id: string } }>(
         CREATE_NODE,
-        { type: 'feature', title: opts.title, description },
+        {
+          type: 'feature',
+          title: opts.title,
+          description,
+          parentId: project.id,
+        },
       )
-      const featureId = nodeData.createNode.id
-      await graphql(CREATE_EDGE, {
-        sourceId: featureId,
-        targetId: project.id,
-        relation: 'part_of',
-      })
       output(nodeData.createNode)
     } catch (error) {
       outputError(error)

package/src/commands/task.test.ts

@@ -63,6 +63,50 @@ describe('task command', () => {
     )
   })
 
+  test('create validates the feature BEFORE any write (no createNode on bad feature)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    // requireFeature() throws (default mock) — the command must bail out before
+    // issuing any mutation, so the node is never created.
+    const createCmd = taskCommand.commands.find((c) => c.name() === 'create')!
+    await createCmd.parseAsync(['--title', 'Test', '--description', 'desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).not.toHaveBeenCalled()
+  })
+
+  test('create issues ONE createNode-with-parent call (not a create then a link)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { requireFeature } = await import('../util/config.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(requireFeature).mockReturnValueOnce('feat_active')
+    vi.mocked(graphql).mockResolvedValueOnce({
+      createNode: { id: 'task_new', title: 'Test' },
+    })
+
+    const createCmd = taskCommand.commands.find((c) => c.name() === 'create')!
+    await createCmd.parseAsync(['--title', 'Test', '--description', 'desc'], {
+      from: 'user',
+    })
+
+    // exactly one GraphQL call, and it is the parented createNode
+    expect(graphql).toHaveBeenCalledTimes(1)
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('createNode')
+    expect(query).toContain('parentId')
+    expect(variables).toMatchObject({
+      type: 'task',
+      title: 'Test',
+      description: 'desc',
+      parentId: 'feat_active',
+    })
+    expect(output).toHaveBeenCalledWith({ id: 'task_new', title: 'Test' })
+  })
+
   test('show calls outputError when graphql throws network error', async () => {
     const { graphql } = await import('../util/client.ts')
     const { outputError } = await import('../util/format.ts')

package/src/commands/task.ts

@@ -8,7 +8,6 @@ import {
   BLOCK_TASK,
   CREATE_TASK,
   DELETE_NODE,
-  LINK_TASK,
   LIST_TASKS,
   READY_TASKS,
   SHOW_TASK,
@@ -35,21 +34,20 @@ taskCommand
   )
   .action(async (opts) => {
     try {
+      // Validate the active feature BEFORE any write so a bad FLOWY_FEATURE
+      // errors cleanly instead of orphaning a node (F24).
       const featureId = requireFeature()
       const description = await resolveDescription({
         description: opts.description,
         descriptionFile: opts.descriptionFile,
       })
+      // One atomic call: the server creates the task and its `part_of` edge to
+      // the feature together, so a failed link can never leave an orphan.
       const data = await graphql<{ createNode: { id: string } }>(CREATE_TASK, {
         type: 'task',
         title: opts.title,
         description,
-      })
-      const taskId = data.createNode.id
-      await graphql(LINK_TASK, {
-        sourceId: taskId,
-        targetId: featureId,
-        relation: 'part_of',
+        parentId: featureId,
       })
       output(data.createNode)
     } catch (error) {

package/src/index.test.ts

@@ -51,6 +51,10 @@ vi.mock('./commands/import.ts', () => ({
 vi.mock('./commands/export.ts', () => ({
   exportCommand: { name: () => 'export' },
 }))
+vi.mock('./commands/backup.ts', () => ({
+  backupCommand: { name: () => 'backup' },
+  restoreCommand: { name: () => 'restore' },
+}))
 
 describe('index.ts command registration', () => {
   test('registers billing and key commands', async () => {
@@ -112,4 +116,18 @@ describe('index.ts command registration', () => {
     )
     expect(indexSource).toContain('program.addCommand(historyCommand)')
   })
+
+  test('registers the backup and restore commands', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { backupCommand, restoreCommand } from './commands/backup.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(backupCommand)')
+    expect(indexSource).toContain('program.addCommand(restoreCommand)')
+  })
 })

package/src/index.ts

@@ -12,6 +12,7 @@ const pkgPath = resolve(
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
 
 import { approveCommand } from './commands/approve.ts'
+import { backupCommand, restoreCommand } from './commands/backup.ts'
 import { billingCommand } from './commands/billing.ts'
 import { clientCommand } from './commands/client.ts'
 import { exportCommand } from './commands/export.ts'
@@ -51,5 +52,7 @@ program.addCommand(historyCommand)
 program.addCommand(whoamiCommand)
 program.addCommand(importCommand)
 program.addCommand(exportCommand)
+program.addCommand(backupCommand)
+program.addCommand(restoreCommand)
 
 program.parse()

package/src/util/operations.test.ts

@@ -57,7 +57,6 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     ],
     'feature.ts': [
       'CREATE_NODE',
-      'CREATE_EDGE',
       'DESCENDANTS',
       'DESCENDANTS_BRIEF',
       'UPDATE_NODE',
@@ -66,7 +65,6 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     ],
     'task.ts': [
       'CREATE_TASK',
-      'LINK_TASK',
       'READY_TASKS',
       'ALL_TASKS',
       'LIST_TASKS',

package/src/util/operations.ts

@@ -152,20 +152,44 @@ export const CREATE_PROJECT = `mutation CreateProject($type: String!, $title: St
   }
 }`
 
-/** feature.ts `create` — create a node with a description. */
-export const CREATE_NODE = `mutation CreateNode($type: String!, $title: String!, $description: String) {
-  createNode(type: $type, title: $title, description: $description) {
+/**
+ * feature.ts `create` — create a feature node linked under its parent project
+ * in ONE transactional call (F24). The optional `parentId` makes the server
+ * create the node and the `part_of` edge atomically, so a failed link can never
+ * orphan the node. Both backends accept `parentId` (bundled local since P1-4;
+ * SaaS since flowy-ai v33). When omitted, it is a plain create.
+ */
+export const CREATE_NODE = `mutation CreateNode($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
     id type title description status createdAt updatedAt
   }
 }`
 
-/** task.ts `create` — create a task node. */
-export const CREATE_TASK = `mutation CreateTask($type: String!, $title: String!, $description: String) {
-  createNode(type: $type, title: $title, description: $description) {
+/**
+ * task.ts `create` — create a task node linked under its parent feature in ONE
+ * transactional call (F24); see CREATE_NODE for the `parentId` semantics.
+ */
+export const CREATE_TASK = `mutation CreateTask($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
     id type title description status createdAt
   }
 }`
 
+/**
+ * Contract op (P1-4/F24): create a node AND its `part_of` edge to a parent in a
+ * single atomic `createNode(parentId:)` call. This is the operation `task
+ * create` / `feature create` issue at runtime (via CREATE_TASK / CREATE_NODE);
+ * exercised explicitly by the contract test to assert the bundled local server
+ * creates the node + edge atomically and rejects a non-existent parent without
+ * leaving an orphan. The SaaS contract guard mirrors this op so both backends
+ * stay aligned on the parented-create surface.
+ */
+export const CREATE_NODE_WITH_PARENT = `mutation CreateNodeWithParent($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
+    id type title description status createdAt updatedAt
+  }
+}`
+
 /** project/feature/task `update` — title/description/metadata. */
 export const UPDATE_NODE = `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
   updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
@@ -324,6 +348,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   CREATE_PROJECT,
   CREATE_NODE,
   CREATE_TASK,
+  CREATE_NODE_WITH_PARENT,
   UPDATE_NODE,
   UPDATE_STATUS,
   APPROVE_NODE,