@sqaoss/flowy 1.7.0 → 1.8.0

package/src/util/config.ts

@@ -18,6 +18,32 @@ const DIR_MODE = 0o700
 const FILE_MODE = 0o600
 const isWindows = platform() === 'win32'
 
+/** The two configuration profiles. `saas` is a back-compat alias for `remote`. */
+export type Mode = 'local' | 'remote'
+
+const LOCAL_API_URL = 'http://localhost:4000/graphql'
+const REMOTE_API_URL = 'https://flowy-ai.fly.dev/graphql'
+
+export interface ProjectConfig {
+  id: string
+  name: string
+  activeFeature?: string
+}
+
+/** Per-mode settings — isolated so local creds never bleed into remote. */
+interface Profile {
+  apiUrl: string
+  apiKey: string
+  projects: Record<string, ProjectConfig>
+}
+
+/** On-disk shape (current). */
+interface StoredConfig {
+  mode: Mode
+  client: { name: string }
+  profiles: Record<Mode, Profile>
+}
+
 /**
  * Non-reversible fingerprint of an API key, safe to print to stdout/logs.
  * A short SHA-256 prefix lets a human confirm *which* key is configured
@@ -29,25 +55,157 @@ export function fingerprintKey(apiKey: string): string {
   return `sha256:${digest.slice(0, 12)}`
 }
 
-export function loadConfig() {
-  if (!existsSync(CONFIG_PATH)) {
-    return {
-      mode: 'saas' as const,
-      apiUrl: 'https://flowy-ai.fly.dev/graphql',
-      apiKey: '',
-      client: { name: '' },
-      projects: {} as Record<string, unknown>,
+/** Map any historical mode token onto the canonical vocabulary (F25). */
+function canonicalMode(raw: unknown): Mode {
+  // "saas" was the old name for the hosted service; "remote" is canonical now.
+  return raw === 'local' ? 'local' : 'remote'
+}
+
+function defaultProfile(mode: Mode): Profile {
+  return {
+    apiUrl: mode === 'local' ? LOCAL_API_URL : REMOTE_API_URL,
+    apiKey: '',
+    projects: {},
+  }
+}
+
+function emptyStored(mode: Mode = 'remote'): StoredConfig {
+  return {
+    mode,
+    client: { name: '' },
+    profiles: {
+      local: defaultProfile('local'),
+      remote: defaultProfile('remote'),
+    },
+  }
+}
+
+/**
+ * Read raw JSON off disk and normalize it into the current {mode, client,
+ * profiles} shape. Handles three eras gracefully:
+ *  - missing file           → defaults (remote mode, empty profiles)
+ *  - legacy flat config     → {mode, apiUrl, apiKey, projects} migrated into
+ *                             the active-mode profile
+ *  - current profiled config
+ * The migration is non-destructive: an old user's key/projects land in the
+ * profile matching their (canonicalized) mode, so nothing is lost.
+ */
+function readStored(): StoredConfig {
+  if (!existsSync(CONFIG_PATH)) return emptyStored()
+
+  let raw: Record<string, unknown>
+  try {
+    raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))
+  } catch {
+    return emptyStored()
+  }
+
+  const mode = canonicalMode(raw.mode)
+  const clientName =
+    typeof (raw.client as { name?: unknown })?.name === 'string'
+      ? (raw.client as { name: string }).name
+      : ''
+
+  const stored = emptyStored(mode)
+  stored.client.name = clientName
+
+  if (raw.profiles && typeof raw.profiles === 'object') {
+    // Current profiled shape — merge each known profile over the defaults.
+    const profiles = raw.profiles as Partial<Record<string, Partial<Profile>>>
+    // Fold a legacy "saas" profile onto "remote" if one is ever present.
+    for (const key of ['local', 'remote', 'saas'] as const) {
+      const p = profiles[key]
+      if (!p) continue
+      const target: Mode = key === 'saas' ? 'remote' : key
+      stored.profiles[target] = {
+        apiUrl:
+          typeof p.apiUrl === 'string'
+            ? p.apiUrl
+            : defaultProfile(target).apiUrl,
+        apiKey: typeof p.apiKey === 'string' ? p.apiKey : '',
+        projects: (p.projects as Record<string, ProjectConfig>) ?? {},
+      }
     }
+    return stored
+  }
+
+  // Legacy flat config — migrate apiUrl/apiKey/projects into the active profile.
+  const profile = stored.profiles[mode]
+  if (typeof raw.apiUrl === 'string') profile.apiUrl = raw.apiUrl
+  if (typeof raw.apiKey === 'string') profile.apiKey = raw.apiKey
+  if (raw.projects && typeof raw.projects === 'object') {
+    profile.projects = raw.projects as Record<string, ProjectConfig>
   }
-  return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))
+  return stored
 }
 
-export function saveConfig(config: ReturnType<typeof loadConfig>): void {
+/**
+ * A live, backward-compatible view over the stored config. Reading/writing
+ * `apiUrl`/`apiKey`/`projects` transparently targets the *active* mode's
+ * profile, so every existing command keeps working unchanged. Reassigning
+ * `mode` re-points those accessors at the other profile — the mechanism that
+ * keeps local and remote credentials from cross-contaminating (F25).
+ */
+export interface Config {
+  mode: Mode
+  client: { name: string }
+  apiUrl: string
+  apiKey: string
+  projects: Record<string, ProjectConfig>
+  /** @internal — the underlying per-mode storage, persisted by saveConfig. */
+  readonly profiles: Record<Mode, Profile>
+}
+
+function makeConfig(stored: StoredConfig): Config {
+  let mode = stored.mode
+  const view = {
+    client: stored.client,
+    get profiles() {
+      return stored.profiles
+    },
+    get mode() {
+      return mode
+    },
+    set mode(next: Mode) {
+      mode = canonicalMode(next)
+    },
+    get apiUrl() {
+      return stored.profiles[mode].apiUrl
+    },
+    set apiUrl(value: string) {
+      stored.profiles[mode].apiUrl = value
+    },
+    get apiKey() {
+      return stored.profiles[mode].apiKey
+    },
+    set apiKey(value: string) {
+      stored.profiles[mode].apiKey = value
+    },
+    get projects() {
+      return stored.profiles[mode].projects
+    },
+    set projects(value: Record<string, ProjectConfig>) {
+      stored.profiles[mode].projects = value
+    },
+  }
+  return view as Config
+}
+
+export function loadConfig(): Config {
+  return makeConfig(readStored())
+}
+
+export function saveConfig(config: Config): void {
+  const stored: StoredConfig = {
+    mode: canonicalMode(config.mode),
+    client: { name: config.client.name },
+    profiles: config.profiles,
+  }
   mkdirSync(CONFIG_DIR, { recursive: true, mode: DIR_MODE })
   // `mode` on writeFileSync only applies to *newly created* files and is
   // masked by umask, so an explicit chmod afterward both corrects a
   // pre-existing world-readable (0644) config and survives a tight umask.
-  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), {
+  writeFileSync(CONFIG_PATH, JSON.stringify(stored, null, 2), {
     mode: FILE_MODE,
   })
   if (!isWindows) {
@@ -56,10 +214,22 @@ export function saveConfig(config: ReturnType<typeof loadConfig>): void {
   }
 }
 
-export interface ProjectConfig {
-  id: string
-  name: string
-  activeFeature?: string
+/**
+ * Guard SaaS-only commands. The bundled local server has no whoami/billing/key
+ * endpoints, so running them in local mode used to fail with an obscure
+ * GraphQL error. Fail fast with a clear message + a distinct code (F25).
+ */
+export function requireRemoteMode(commandName: string): void {
+  const { mode } = loadConfig()
+  if (mode === 'local') {
+    const err = new Error(
+      `"flowy ${commandName}" is only available in remote mode. ` +
+        `The active mode is local mode — run "flowy setup remote" to connect ` +
+        `to the hosted Flowy service.`,
+    ) as Error & { code?: string }
+    err.code = 'LOCAL_MODE'
+    throw err
+  }
 }
 
 export function resolveProject(): ProjectConfig | null {
@@ -69,7 +239,7 @@ export function resolveProject(): ProjectConfig | null {
   if (envProject) {
     return (
       (Object.values(config.projects).find(
-        (p) => (p as ProjectConfig).name === envProject,
+        (p) => p.name === envProject,
       ) as ProjectConfig) ?? null
     )
   }
@@ -83,7 +253,7 @@ export function resolveProject(): ProjectConfig | null {
       (cwd === path || cwd.startsWith(`${path}/`)) &&
       path.length > bestLength
     ) {
-      bestMatch = project as ProjectConfig
+      bestMatch = project
       bestLength = path.length
     }
   }
@@ -126,7 +296,7 @@ export function updateProjectConfig(
 
   for (const [path, project] of Object.entries(config.projects)) {
     if (cwd === path || cwd.startsWith(`${path}/`)) {
-      updater(project as ProjectConfig)
+      updater(project)
       saveConfig(config)
       return
     }

package/src/util/operations.test.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  LOCAL_CONTRACT_OPERATIONS,
+  SAAS_ONLY_OPERATIONS,
+} from './operations.ts'
+
+/**
+ * Root-suite half of the CLI/local-server contract guard (P1-1).
+ *
+ * The executable half lives in `server/src/contract.test.ts` (runs the ops
+ * against a live local server). This half runs under the root `bun run test`
+ * and guards the *single source of truth*: every command must send a canonical
+ * operation from `operations.ts`, and the two op-sets must stay disjoint and
+ * well-formed. If a command re-inlines a query string (bypassing the contract),
+ * this fails.
+ */
+
+const allOps = {
+  ...LOCAL_CONTRACT_OPERATIONS,
+  ...SAAS_ONLY_OPERATIONS,
+} as Record<string, string>
+
+describe('operations module', () => {
+  it('every operation is a non-empty named query or mutation', () => {
+    for (const [name, op] of Object.entries(allOps)) {
+      expect(op.trim().length, name).toBeGreaterThan(0)
+      expect(op, name).toMatch(/^\s*(query|mutation)\s/)
+    }
+  })
+
+  it('local and SaaS-only operation sets are disjoint', () => {
+    const local = new Set(Object.keys(LOCAL_CONTRACT_OPERATIONS))
+    const saas = Object.keys(SAAS_ONLY_OPERATIONS)
+    for (const name of saas) expect(local.has(name), name).toBe(false)
+  })
+
+  it('SaaS-only set is exactly the documented divergences', () => {
+    // These are deliberately NOT served by the bundled local server.
+    expect(new Set(Object.keys(SAAS_ONLY_OPERATIONS))).toEqual(
+      new Set(['REGISTER', 'WHOAMI', 'ROTATE_API_KEY', 'CREATE_CHECKOUT']),
+    )
+  })
+})
+
+describe('commands send canonical operations (no re-inlined queries)', () => {
+  // command file -> the operation constants it must import from operations.ts
+  const expectations: Record<string, string[]> = {
+    'project.ts': [
+      'CREATE_PROJECT',
+      'LIST_PROJECTS_FOR_SET',
+      'LIST_PROJECTS',
+      'GET_PROJECT',
+      'UPDATE_NODE',
+      'DELETE_NODE',
+    ],
+    'feature.ts': [
+      'CREATE_NODE',
+      'CREATE_EDGE',
+      'DESCENDANTS',
+      'DESCENDANTS_BRIEF',
+      'UPDATE_NODE',
+      'DELETE_NODE',
+      'GET_NODE',
+    ],
+    'task.ts': [
+      'CREATE_TASK',
+      'LINK_TASK',
+      'READY_TASKS',
+      'ALL_TASKS',
+      'LIST_TASKS',
+      'SHOW_TASK',
+      'UPDATE_NODE',
+      'DELETE_NODE',
+      'BLOCK_TASK',
+      'UNBLOCK_TASK',
+      'TASK_DEPS',
+    ],
+    'status.ts': ['UPDATE_STATUS'],
+    'approve.ts': ['APPROVE_NODE'],
+    'search.ts': ['SEARCH'],
+    'tree.ts': ['SUBTREE'],
+    'whoami.ts': ['WHOAMI'],
+    'billing.ts': ['CREATE_CHECKOUT'],
+    'key.ts': ['ROTATE_API_KEY'],
+    'init.ts': ['CREATE_PROJECT'],
+    'setup.ts': ['REGISTER'],
+    'import.ts': [
+      'IMPORT_EXISTING',
+      'IMPORT_EDGES',
+      'IMPORT_CREATE',
+      'IMPORT_UPDATE',
+      'IMPORT_EDGE',
+    ],
+    'export.ts': ['EXPORT_PROJECT', 'EXPORT_DESCENDANTS', 'EXPORT_EDGES'],
+  }
+
+  for (const [file, ops] of Object.entries(expectations)) {
+    it(`${file} imports its operations from operations.ts`, () => {
+      const path = fileURLToPath(
+        new URL(`../commands/${file}`, import.meta.url),
+      )
+      const source = readFileSync(path, 'utf-8')
+      expect(source).toContain("from '../util/operations.ts'")
+      for (const op of ops) expect(source, `${file} -> ${op}`).toContain(op)
+      // A command file must not inline GraphQL operation text anymore: the
+      // backtick-wrapped query/mutation lives only in operations.ts.
+      expect(source, `${file} re-inlines a GraphQL operation`).not.toMatch(
+        /`\s*(query|mutation)\s/,
+      )
+    })
+  }
+})

package/src/util/operations.ts

@@ -0,0 +1,331 @@
+/**
+ * Canonical GraphQL operations the Flowy CLI sends.
+ *
+ * Every operation the CLI relies on lives here, copied verbatim from the
+ * command that issues it. Commands import these constants instead of inlining
+ * the query/mutation text, so there is a single source of truth for the
+ * contract the CLI expects a backend to satisfy.
+ *
+ * Two consumers share this module:
+ *   1. `src/commands/*.ts` — the runtime CLI commands.
+ *   2. `server/src/contract.test.ts` — the contract guard that executes each
+ *      operation against the bundled local server and asserts it is satisfied.
+ *
+ * If the bundled local server (or the SaaS server) renames an operation, a
+ * field, or an argument the CLI uses, the contract test fails — catching drift
+ * before it ships. See `server/src/contract.test.ts` for the documented list
+ * of intentional local/SaaS divergences (SaaS-only `whoami`, `register`,
+ * `rotateApiKey`, `createCheckout`, `auditLog`, `ancestors`).
+ */
+
+// --- Nodes: read --------------------------------------------------------------
+
+/** project.ts `show`, feature.ts `show` — fetch a single node by id. */
+export const GET_NODE = `query GetNode($id: String!) {
+  node(id: $id) {
+    id type title description status metadata createdAt updatedAt
+  }
+}`
+
+/** project.ts `show` — same shape as GET_NODE, distinct operation name. */
+export const GET_PROJECT = `query GetProject($id: String!) {
+  node(id: $id) {
+    id type title description status metadata createdAt updatedAt
+  }
+}`
+
+/** project.ts `set` — list nodes of a type, minimal fields for name matching. */
+export const LIST_PROJECTS_FOR_SET = `query ListProjects($type: String) {
+  nodes(type: $type) {
+    id title
+  }
+}`
+
+/** project.ts `list` — list nodes of a type with display fields. */
+export const LIST_PROJECTS = `query ListProjects($type: String) {
+  nodes(type: $type) {
+    id type title description status createdAt updatedAt
+  }
+}`
+
+/** task.ts `list --all` — every node of a type. */
+export const ALL_TASKS = `query AllTasks($type: String!) {
+  nodes(type: $type) {
+    id type title status createdAt
+  }
+}`
+
+/** feature.ts `list` — direct children via relation, full display fields. */
+export const DESCENDANTS = `query Descendants($nodeId: String!, $relation: String, $maxDepth: Int) {
+  descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title description status createdAt updatedAt
+  }
+}`
+
+/** feature.ts `set` — direct children via relation, brief fields for matching. */
+export const DESCENDANTS_BRIEF = `query Descendants($nodeId: String!, $relation: String, $maxDepth: Int) {
+  descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title status
+  }
+}`
+
+/** task.ts `list` (active feature) — children with status only. */
+export const LIST_TASKS = `query ListTasks($nodeId: String!, $relation: String!, $maxDepth: Int) {
+  descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title status createdAt
+  }
+}`
+
+/** tree.ts — full subtree from any root. */
+export const SUBTREE = `query Subtree($nodeId: String!, $maxDepth: Int) {
+  subtree(nodeId: $nodeId, maxDepth: $maxDepth) {
+    id type title status
+  }
+}`
+
+/** task.ts `list --ready` — actionable tasks (server-side dependency logic). */
+export const READY_TASKS = `query ReadyTasks($projectId: String) {
+  readyTasks(projectId: $projectId) {
+    id type title status createdAt
+  }
+}`
+
+/** task.ts `show` — node plus its incoming/outgoing `blocks` edges. */
+export const SHOW_TASK = `query ShowTask($id: String!) {
+  node(id: $id) {
+    id type title description status metadata createdAt updatedAt
+  }
+  blockedBy: edges(nodeId: $id, relation: "blocks", direction: "incoming") {
+    id type title status
+  }
+  blocks: edges(nodeId: $id, relation: "blocks", direction: "outgoing") {
+    id type title status
+  }
+}`
+
+/** task.ts `deps` — incoming/outgoing `blocks` edges only. */
+export const TASK_DEPS = `query TaskDeps($id: String!) {
+  blockedBy: edges(nodeId: $id, relation: "blocks", direction: "incoming") {
+    id type title status
+  }
+  blocks: edges(nodeId: $id, relation: "blocks", direction: "outgoing") {
+    id type title status
+  }
+}`
+
+/** search.ts — full-text search with optional type/status/limit filters. */
+export const SEARCH = `query Search($query: String!, $type: String, $status: String, $limit: Int) {
+  search(query: $query, type: $type, status: $status, limit: $limit) {
+    id type title description status
+  }
+}`
+
+// --- Nodes: write -------------------------------------------------------------
+
+/** project.ts `create`, init.ts — create a node by type/title. */
+export const CREATE_PROJECT = `mutation CreateProject($type: String!, $title: String!) {
+  createNode(type: $type, title: $title) {
+    id type title description status metadata createdAt updatedAt
+  }
+}`
+
+/** 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) {
+    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) {
+    id type title description status createdAt
+  }
+}`
+
+/** 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) {
+    id type title description status metadata createdAt updatedAt
+  }
+}`
+
+/** status.ts — status-only shorthand update. */
+export const UPDATE_STATUS = `mutation UpdateStatus($id: String!, $status: String) {
+  updateNode(id: $id, status: $status) {
+    id type title status updatedAt
+  }
+}`
+
+/** approve.ts — promote a pending_review node to approved. */
+export const APPROVE_NODE = `mutation ApproveNode($id: String!) {
+  approveNode(id: $id) { id type title status updatedAt }
+}`
+
+/** project/feature/task `delete` — remove a node (and its edges). */
+export const DELETE_NODE = `mutation DeleteNode($id: String!) {
+  deleteNode(id: $id)
+}`
+
+// --- Edges --------------------------------------------------------------------
+
+/** feature.ts `create` — link feature under project. */
+export const CREATE_EDGE = `mutation CreateEdge($sourceId: String!, $targetId: String!, $relation: String!) {
+  createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) {
+    sourceId targetId relation createdAt
+  }
+}`
+
+/** task.ts `create` — link task under feature (no createdAt selected). */
+export const LINK_TASK = `mutation LinkTask($sourceId: String!, $targetId: String!, $relation: String!) {
+  createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) {
+    sourceId targetId relation
+  }
+}`
+
+/** task.ts `block` — create a `blocks` edge between two tasks. */
+export const BLOCK_TASK = `mutation BlockTask($sourceId: String!, $targetId: String!, $relation: String!) {
+  createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) {
+    sourceId targetId relation createdAt
+  }
+}`
+
+/** task.ts `unblock` — remove a `blocks` edge. */
+export const UNBLOCK_TASK = `mutation UnblockTask($sourceId: String!, $targetId: String!, $relation: String!) {
+  removeEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation)
+}`
+
+// --- Import / export ----------------------------------------------------------
+
+/** import.ts — read existing nodes of a type to dedup by client-key. */
+export const IMPORT_EXISTING = `query ImportExisting($type: String) {
+  nodes(type: $type) { id type title metadata }
+}`
+
+/** import.ts — outgoing edges of a node, used to dedup edge creation. */
+export const IMPORT_EDGES = `query ImportEdges($nodeId: String!, $relation: String!) {
+  edges(nodeId: $nodeId, relation: $relation, direction: "outgoing") { id }
+}`
+
+/** import.ts — create a node (full arg surface incl. status/metadata). */
+export const IMPORT_CREATE = `mutation ImportCreate($type: String!, $title: String!, $description: String, $status: String, $metadata: String) {
+  createNode(type: $type, title: $title, description: $description, status: $status, metadata: $metadata) { id }
+}`
+
+/** import.ts — update a node (full arg surface incl. status/metadata). */
+export const IMPORT_UPDATE = `mutation ImportUpdate($id: String!, $title: String, $description: String, $status: String, $metadata: String) {
+  updateNode(id: $id, title: $title, description: $description, status: $status, metadata: $metadata) { id }
+}`
+
+/** import.ts — create an edge during materialization. */
+export const IMPORT_EDGE = `mutation ImportEdge($sourceId: String!, $targetId: String!, $relation: String!) {
+  createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) { sourceId targetId relation }
+}`
+
+/** export.ts — fetch the root project node. */
+export const EXPORT_PROJECT = `query ExportProject($id: String!) {
+  node(id: $id) { id type title description status metadata }
+}`
+
+/** export.ts — all descendants of the project for the dump. */
+export const EXPORT_DESCENDANTS = `query ExportDescendants($nodeId: String!, $relation: String, $maxDepth: Int) {
+  descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title description status metadata
+  }
+}`
+
+/** export.ts — outgoing edges of a node, read back through the edge model. */
+export const EXPORT_EDGES = `query ExportEdges($nodeId: String!, $relation: String!) {
+  edges(nodeId: $nodeId, relation: $relation, direction: "outgoing") {
+    id metadata
+  }
+}`
+
+// --- SaaS-only operations (NOT served by the bundled local server) ------------
+//
+// These belong to the hosted `flowy-saas` backend (auth, billing, audit). The
+// bundled local server intentionally does not implement them — see the
+// divergence list in `server/src/contract.test.ts`. They are exported here so
+// the CLI commands share the same single source of truth and the SaaS contract
+// test (flowy-saas `test/helpers/cli-queries.ts`) can mirror them.
+
+/** setup.ts remote — register a hosted account. */
+export const REGISTER = `mutation Register($email: String!, $tier: String) {
+  register(email: $email, tier: $tier) {
+    user { id email tier createdAt graceEndsAt }
+    apiKey
+    checkoutUrl
+  }
+}`
+
+/** whoami.ts — current hosted user. */
+export const WHOAMI = `query Whoami {
+  whoami {
+    id email tier createdAt graceEndsAt
+  }
+}`
+
+/** key.ts — rotate the hosted API key. */
+export const ROTATE_API_KEY = `mutation RotateApiKey {
+  rotateApiKey {
+    user { id email tier createdAt graceEndsAt }
+    apiKey
+  }
+}`
+
+/** billing.ts — create a checkout session for a tier. */
+export const CREATE_CHECKOUT = `mutation CreateCheckout($tier: String!) {
+  createCheckout(tier: $tier) {
+    url
+  }
+}`
+
+/**
+ * Operations the bundled local server is contractually required to satisfy.
+ * The contract test executes each of these against a live local server.
+ */
+export const LOCAL_CONTRACT_OPERATIONS = {
+  GET_NODE,
+  GET_PROJECT,
+  LIST_PROJECTS_FOR_SET,
+  LIST_PROJECTS,
+  ALL_TASKS,
+  DESCENDANTS,
+  DESCENDANTS_BRIEF,
+  LIST_TASKS,
+  SUBTREE,
+  READY_TASKS,
+  SHOW_TASK,
+  TASK_DEPS,
+  SEARCH,
+  CREATE_PROJECT,
+  CREATE_NODE,
+  CREATE_TASK,
+  UPDATE_NODE,
+  UPDATE_STATUS,
+  APPROVE_NODE,
+  DELETE_NODE,
+  CREATE_EDGE,
+  LINK_TASK,
+  BLOCK_TASK,
+  UNBLOCK_TASK,
+  IMPORT_EXISTING,
+  IMPORT_EDGES,
+  IMPORT_CREATE,
+  IMPORT_UPDATE,
+  IMPORT_EDGE,
+  EXPORT_PROJECT,
+  EXPORT_DESCENDANTS,
+  EXPORT_EDGES,
+} as const
+
+/**
+ * SaaS-only operations the bundled local server intentionally does NOT serve.
+ * Documented here so the divergence is explicit and discoverable.
+ */
+export const SAAS_ONLY_OPERATIONS = {
+  REGISTER,
+  WHOAMI,
+  ROTATE_API_KEY,
+  CREATE_CHECKOUT,
+} as const