@sqaoss/flowy 1.7.0 → 1.9.0

package/src/util/config.test.ts

@@ -52,7 +52,9 @@ describe('config', () => {
   test('loadConfig returns defaults when no config file exists', async () => {
     const { loadConfig } = await import('./config.ts')
     const config = loadConfig()
-    expect(config.mode).toBe('saas')
+    // Canonical default mode is "remote" (was "saas" — kept as a back-compat
+    // alias on read only).
+    expect(config.mode).toBe('remote')
     expect(config.apiUrl).toBe('https://flowy-ai.fly.dev/graphql')
     expect(config.apiKey).toBe('')
     expect(config.client.name).toBe('')
@@ -196,4 +198,169 @@ describe('config', () => {
       (updated.projects[cwd] as { activeFeature?: string }).activeFeature,
     ).toBe('feat_999')
   })
+
+  describe('per-mode profiles (F25)', () => {
+    test('default config canonicalizes mode to "remote"', async () => {
+      const { loadConfig } = await import('./config.ts')
+      const config = loadConfig()
+      // Canonical vocab is "remote"; "saas" is only a back-compat alias.
+      expect(config.mode).toBe('remote')
+    })
+
+    test('local apiKey/projects do not bleed into remote mode', async () => {
+      const { saveConfig, loadConfig } = await import('./config.ts')
+
+      // Configure the local profile with a key + a project mapping.
+      const local = loadConfig()
+      local.mode = 'local'
+      local.apiKey = 'local-secret'
+      local.apiUrl = 'http://localhost:4000/graphql'
+      local.projects['/work/local'] = { id: 'proj_local', name: 'LocalProj' }
+      saveConfig(local)
+
+      // Switch to remote: the local key/projects must NOT be visible.
+      const remote = loadConfig()
+      remote.mode = 'remote'
+      expect(remote.apiKey).toBe('')
+      expect(remote.apiUrl).toBe('https://flowy-ai.fly.dev/graphql')
+      expect(remote.projects['/work/local']).toBeUndefined()
+
+      // Set a different key/project in remote mode and persist.
+      remote.apiKey = 'remote-secret'
+      remote.projects['/work/remote'] = {
+        id: 'proj_remote',
+        name: 'RemoteProj',
+      }
+      saveConfig(remote)
+
+      // Back to local: local data intact, remote data not visible.
+      const reloadLocal = loadConfig()
+      reloadLocal.mode = 'local'
+      expect(reloadLocal.apiKey).toBe('local-secret')
+      expect(reloadLocal.projects['/work/local']?.name).toBe('LocalProj')
+      expect(reloadLocal.projects['/work/remote']).toBeUndefined()
+    })
+
+    test('getConfig reads from the active mode profile, not the other', async () => {
+      const { saveConfig, loadConfig, getConfig } = await import('./config.ts')
+
+      const local = loadConfig()
+      local.mode = 'local'
+      local.apiKey = 'local-secret'
+      local.apiUrl = 'http://localhost:4000/graphql'
+      saveConfig(local)
+
+      const remote = loadConfig()
+      remote.mode = 'remote'
+      remote.apiKey = 'remote-secret'
+      saveConfig(remote)
+
+      // Active mode is now remote (last saved). getConfig sees remote creds.
+      const cfg = getConfig()
+      expect(cfg.apiKey).toBe('remote-secret')
+      expect(cfg.apiUrl).toBe('https://flowy-ai.fly.dev/graphql')
+    })
+
+    test('client name is shared across modes', async () => {
+      const { saveConfig, loadConfig } = await import('./config.ts')
+      const config = loadConfig()
+      config.client.name = 'Acme'
+      saveConfig(config)
+      const reloaded = loadConfig()
+      reloaded.mode = reloaded.mode === 'local' ? 'remote' : 'local'
+      expect(reloaded.client.name).toBe('Acme')
+    })
+
+    test('migrates a legacy flat config into the active-mode profile', async () => {
+      const { loadConfig } = await import('./config.ts')
+      // Legacy shape written by an older CLI: flat apiKey/apiUrl/projects,
+      // mode="saas" (the old vocab).
+      writeFileSync(
+        CONFIG_PATH,
+        JSON.stringify({
+          mode: 'saas',
+          apiUrl: 'https://flowy-ai.fly.dev/graphql',
+          apiKey: 'legacy-key',
+          client: { name: 'Legacy Co' },
+          projects: { '/legacy/path': { id: 'p1', name: 'Legacy' } },
+        }),
+      )
+
+      const config = loadConfig()
+      // "saas" canonicalizes to "remote".
+      expect(config.mode).toBe('remote')
+      // Flat fields land in the (remote) active profile.
+      expect(config.apiKey).toBe('legacy-key')
+      expect(config.projects['/legacy/path']?.name).toBe('Legacy')
+      expect(config.client.name).toBe('Legacy Co')
+    })
+
+    test('resolveProject/resolveFeature use the active mode profile only', async () => {
+      const { saveConfig, loadConfig, resolveProject, resolveFeature } =
+        await import('./config.ts')
+      const cwd = process.cwd()
+
+      const local = loadConfig()
+      local.mode = 'local'
+      local.projects[cwd] = {
+        id: 'proj_local',
+        name: 'Local',
+        activeFeature: 'feat_local',
+      }
+      saveConfig(local)
+
+      const remote = loadConfig()
+      remote.mode = 'remote'
+      remote.projects[cwd] = {
+        id: 'proj_remote',
+        name: 'Remote',
+        activeFeature: 'feat_remote',
+      }
+      saveConfig(remote)
+
+      // Active mode is remote → resolution returns the remote project.
+      expect(resolveProject()?.id).toBe('proj_remote')
+      expect(resolveFeature()).toBe('feat_remote')
+    })
+
+    test('requireRemoteMode throws a coded error in local mode', async () => {
+      const { saveConfig, loadConfig, requireRemoteMode } = await import(
+        './config.ts'
+      )
+      const config = loadConfig()
+      config.mode = 'local'
+      saveConfig(config)
+
+      expect(() => requireRemoteMode('whoami')).toThrow(/local mode/i)
+      try {
+        requireRemoteMode('whoami')
+      } catch (error) {
+        expect((error as { code?: string }).code).toBe('LOCAL_MODE')
+      }
+    })
+
+    test('requireRemoteMode is a no-op in remote mode', async () => {
+      const { saveConfig, loadConfig, requireRemoteMode } = await import(
+        './config.ts'
+      )
+      const config = loadConfig()
+      config.mode = 'remote'
+      saveConfig(config)
+      expect(() => requireRemoteMode('whoami')).not.toThrow()
+    })
+
+    test('a half-written config (mode set, key not yet) still loads cleanly', async () => {
+      const { saveConfig, loadConfig } = await import('./config.ts')
+      // Simulate save-after-mode-switch but before the key arrives.
+      const config = loadConfig()
+      config.mode = 'remote'
+      saveConfig(config)
+
+      const reloaded = loadConfig()
+      expect(reloaded.mode).toBe('remote')
+      expect(reloaded.apiKey).toBe('')
+      expect(reloaded.apiUrl).toBe('https://flowy-ai.fly.dev/graphql')
+      expect(reloaded.projects).toEqual({})
+    })
+  })
 })

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/,
+      )
+    })
+  }
+})