feat(settings): files-based layered settings foundation (#572 part 1 v2)

.changeset/settings-files-foundation.md

@@ -0,0 +1,14 @@
+---
+'@conciv/core': patch
+---
+
+Files-based layered settings foundation: a namespaced settings registry in `@conciv/protocol`
+(`appearance.scheme`), a `settings` oRPC group (`get`/`set`/`clear`/`applyGlobally`/`history`)
+resolving the project layer under `<stateRoot>/.conciv/` over the global layer under `~/.conciv/`
+over registry defaults. Each layer honors `settings.jsonc` if present, otherwise `settings.json`;
+comments are supported in `.jsonc` and survive programmatic writes. Includes per-layer content
+revisions for optimistic concurrency, atomic persistence, a cross-process lock on the shared global
+file, an append-only history sidecar, and live settings-changed events broadcast to every attached
+session.
+
+Adds dependencies on `c12`, `jsonc-parser`, `write-file-atomic` and `proper-lockfile`.

packages/contract/src/contract.ts

@@ -23,6 +23,7 @@ import {
 import {BundlerConfigSchema, ModuleNodeSchema} from '@conciv/protocol/bundler-types'
 import {SessionCapturesSchema} from '@conciv/protocol/element-capture-types'
 import {TOOL_ICON_KEYS} from '@conciv/protocol/tool-icon-types'
+import {SettingsHistoryEntrySchema, SettingsReadSchema, SettingsScopeSchema} from '@conciv/protocol/settings-types'
 import {DraftRowSchema, MarkerRowSchema, SessionMetaSchema} from './rows.js'
 
 const StreamChunkSchema = z.custom<StreamChunk>((value) => typeof value === 'object' && value !== null)
@@ -36,6 +37,18 @@ export const ChatSendInput = SessionIdInput.extend({
 const Ok = z.object({ok: z.literal(true)})
 const SendAccepted = z.object({ok: z.literal(true), runId: z.string()})
 const NavigationWriteResult = z.object({ok: z.literal(true), applied: z.boolean()})
+const SettingsWriteResult = z.object({ok: z.literal(true), opId: z.string()})
+const settingsWriteErrors = {
+  UNKNOWN_KEY: {message: 'no registered setting with that key'},
+  INVALID_VALUE: {message: 'the value failed the registry schema for this key'},
+  REVISION_CONFLICT: {
+    status: 409,
+    message: 'the settings file changed since it was read; refetch and retry',
+    data: z.object({scope: SettingsScopeSchema, revision: z.string()}),
+  },
+  LAYER_UNPARSEABLE: {message: 'the settings file does not parse; fix it before writing'},
+  LOCK_TIMEOUT: {message: 'another process is holding the global settings lock'},
+}
 const notFound = {NOT_FOUND: {message: 'session not found'}}
 const noBundler = {NO_BUNDLER: {message: 'no bundler bridge'}}
 const approvalDenied = {APPROVAL_DENIED: {message: 'the call was not approved'}}
@@ -115,6 +128,44 @@ export const contract = {
     get: oc.output(NavigationWriteSchema.nullable()),
     set: oc.input(NavigationWriteSchema).output(NavigationWriteResult),
   },
+  settings: {
+    get: oc.output(SettingsReadSchema),
+    set: oc
+      .errors(settingsWriteErrors)
+      .input(
+        z.object({
+          key: z.string(),
+          value: z.unknown(),
+          scope: SettingsScopeSchema,
+          expectedRevision: z.string(),
+        }),
+      )
+      .output(SettingsWriteResult),
+    clear: oc
+      .errors(settingsWriteErrors)
+      .input(z.object({key: z.string(), scope: SettingsScopeSchema, expectedRevision: z.string()}))
+      .output(SettingsWriteResult),
+    applyGlobally: oc
+      .errors(settingsWriteErrors)
+      .input(
+        z.object({
+          key: z.string(),
+          value: z.unknown(),
+          expectedRevisions: z.object({project: z.string(), global: z.string()}),
+        }),
+      )
+      .output(SettingsWriteResult),
+    reset: oc
+      .errors(settingsWriteErrors)
+      .input(
+        z.object({
+          key: z.string(),
+          expectedRevisions: z.object({project: z.string(), global: z.string()}),
+        }),
+      )
+      .output(SettingsWriteResult),
+    history: oc.input(z.object({key: z.string()})).output(z.array(SettingsHistoryEntrySchema)),
+  },
   chat: {
     subscribe: oc.input(SessionIdInput).output(eventIterator(StreamChunkSchema)),
     send: oc

packages/core/package.json

@@ -87,9 +87,13 @@
     "@tanstack/ai-isolate-quickjs": "catalog:",
     "@tanstack/ai-sandbox": "0.3.0",
     "@tanstack/ai-sandbox-local-process": "^0.2.1",
+    "c12": "~3.3.4",
     "drizzle-orm": "1.0.0-rc.4",
     "hono": "^4.12.0",
+    "jsonc-parser": "^3.3.1",
     "lucide-solid": "^1.18.0",
+    "proper-lockfile": "^4.1.2",
+    "write-file-atomic": "^8.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -102,6 +106,8 @@
     "@tanstack/ai-mcp": "catalog:",
     "@tanstack/ai-sandbox-local-process": "^0.2.1",
     "@types/node": "^22.19.21",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/write-file-atomic": "^4.0.3",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.8",
     "get-port": "^7.1.0",

packages/core/src/api/rpc/mount.ts

@@ -8,6 +8,7 @@ import type {CompositeRpcRouter as CompositeRouterOf} from '@conciv/extension/rp
 import type {ChatDeps} from '../../chat/runtime.js'
 import type {OpenSourceFrames, OpenSourceStatus} from '../../editor/open-source.js'
 import type {CoreRuntime, SessionScope} from '../../runtime/scope-types.js'
+import type {SettingsService} from '../../settings/service.js'
 import {runWithSession} from '../../runtime/session-context.js'
 import type {makeRpcRouter} from './router.js'
 
@@ -16,6 +17,7 @@ export type RpcDeps = {
   tools: ChatTool[]
   openFromFrames: (frames: OpenSourceFrames) => Promise<OpenSourceStatus>
   runtime: CoreRuntime
+  settings: SettingsService
   staleness: () => EngineStaleness
   askTimeoutMs?: number
 }

packages/core/src/api/rpc/router.ts

@@ -11,6 +11,8 @@ import {listCommands} from '../../chat/commands.js'
 import {makeAskGate, requiresApproval} from '../../chat/gate.js'
 import {rowById} from '../../chat/session-rows.js'
 import {session} from '../../runtime/session-context.js'
+import type {SettingsWriteOutcome} from '../../settings/service.js'
+import type {SettingsScope} from '@conciv/protocol/settings-types'
 import {chatRouter} from './chat.js'
 import {harnessMetaOf, sessionsRouter} from './sessions.js'
 import {makeSessionOs, os, type RpcDeps} from './mount.js'
@@ -36,6 +38,30 @@ function hasErrorCode(error: unknown, code: string): boolean {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === code
 }
 
+const SETTINGS_RPC_ACTOR = 'user'
+
+type SettingsErrors = {
+  UNKNOWN_KEY: () => Error
+  INVALID_VALUE: () => Error
+  REVISION_CONFLICT: (options: {data: {scope: SettingsScope; revision: string}}) => Error
+  LAYER_UNPARSEABLE: (options: {message: string}) => Error
+  LOCK_TIMEOUT: () => Error
+}
+
+function settled(outcome: SettingsWriteOutcome, errors: SettingsErrors): {ok: true; opId: string} {
+  if (outcome.ok) return {ok: true, opId: outcome.opId}
+  const failure = outcome.failure
+  if (failure.kind === 'unknown-key') throw errors.UNKNOWN_KEY()
+  if (failure.kind === 'invalid-value') throw errors.INVALID_VALUE()
+  if (failure.kind === 'lock-timeout') throw errors.LOCK_TIMEOUT()
+  if (failure.kind === 'revision-conflict') {
+    throw errors.REVISION_CONFLICT({data: {scope: failure.scope, revision: failure.revision}})
+  }
+  throw errors.LAYER_UNPARSEABLE({
+    message: `the ${failure.scope} settings file does not parse; fix it before writing`,
+  })
+}
+
 type ApprovalErrors = {APPROVAL_DENIED: (options: {message: string}) => Error}
 
 async function approveAskGatedCall(deps: RpcDeps, name: string, input: unknown, errors: ApprovalErrors): Promise<void> {
@@ -107,6 +133,22 @@ export function makeRpcRouter(deps: RpcDeps) {
       get: os.navigation.get.handler(() => engine.navigation.get()),
       set: os.navigation.set.handler(({input}) => engine.navigation.set(input)),
     },
+    settings: {
+      get: os.settings.get.handler(() => deps.settings.read()),
+      set: os.settings.set.handler(async ({input, errors}) =>
+        settled(await deps.settings.set({...input, actor: SETTINGS_RPC_ACTOR}), errors),
+      ),
+      clear: os.settings.clear.handler(async ({input, errors}) =>
+        settled(await deps.settings.clear({...input, actor: SETTINGS_RPC_ACTOR}), errors),
+      ),
+      applyGlobally: os.settings.applyGlobally.handler(async ({input, errors}) =>
+        settled(await deps.settings.applyGlobally({...input, actor: SETTINGS_RPC_ACTOR}), errors),
+      ),
+      reset: os.settings.reset.handler(async ({input, errors}) =>
+        settled(await deps.settings.reset({...input, actor: SETTINGS_RPC_ACTOR}), errors),
+      ),
+      history: os.settings.history.handler(({input}) => deps.settings.history(input.key)),
+    },
     registry: {
       catalog: os.registry.catalog.handler(() => engine.catalog()),
       call: sessionOs.registry.call.handler(async ({input, context, errors}) => {

packages/core/src/app.ts

@@ -59,6 +59,10 @@ import type {CompositeRpcRouter} from './api/rpc/mount.js'
 import pageServerExtension from '@conciv/extension-page/server'
 import {PAGE_TOOL_PREFIX} from '@conciv/extension-page/defs'
 import {logError} from './lib/debug.js'
+import {concivHomeDir} from './lib/conciv-home.js'
+import {makeSettingsService} from './settings/service.js'
+import {SETTINGS_CHANGED_EVENT, settingsRegistry} from '@conciv/protocol/settings-types'
+import {EventType} from '@tanstack/ai'
 import {engineStaleness} from './lib/engine-stamp.js'
 import type {OpenInEditor} from './editor/open.js'
 
@@ -94,6 +98,8 @@ export type MakeAppOpts = {
   nativeUrl?: () => string | undefined
 
   staleness?: () => EngineStaleness
+
+  globalSettingsDir?: string
 }
 
 export function slug(name: string): string {
@@ -315,6 +321,13 @@ export async function makeApp(opts: MakeAppOpts): Promise<MadeApp> {
     openInEditor: opts.openInEditor,
   })
   const {asks, liveRuns, registry, stream} = primitives
+  const settings = makeSettingsService({
+    projectStateDir: concivStateDir(opts.cfg.stateRoot),
+    globalStateDir: opts.globalSettingsDir ?? concivHomeDir(),
+    registry: settingsRegistry,
+    notify: (payload) =>
+      stream.publishAll({type: EventType.CUSTOM, name: SETTINGS_CHANGED_EVENT, value: payload, timestamp: Date.now()}),
+  })
   const rows = {db, harnessKind: harness.id, cwd: opts.cwd}
   const scopedToolCall: ScopedToolCall = (name, input, request) =>
     runtime.forSession(request.sessionId).tools.call(name, input, {toolCallId: request.toolCallId})
@@ -489,6 +502,7 @@ export async function makeApp(opts: MakeAppOpts): Promise<MadeApp> {
     tools: toolList,
     openFromFrames: (frames) => openSourceFromFrames(frames, opts.cwd, opts.openInEditor),
     runtime,
+    settings,
     staleness,
     ...(opts.askTimeoutMs === undefined ? {} : {askTimeoutMs: opts.askTimeoutMs}),
   })
@@ -531,6 +545,7 @@ export async function makeApp(opts: MakeAppOpts): Promise<MadeApp> {
     const drained = await drainWithDeadline(runControl.drain(), RUN_DRAIN_TIMEOUT_MS)
     if (!drained) logError('[core] disposed with run(s) still in flight')
     for (const disposer of disposers) await Promise.resolve(disposer()).catch(() => {})
+    settings.dispose()
     db.$client.close()
   }
 

packages/core/src/chat/subscribe.ts

@@ -6,6 +6,7 @@ import type {SessionId} from '@conciv/protocol/chat-types'
 
 export type SessionStreams = {
   publish: (sessionId: SessionId, chunk: StreamChunk) => void
+  publishAll: (chunk: StreamChunk) => void
   listen: (sessionId: SessionId, onChunk: (chunk: StreamChunk) => void) => () => void
   listening: (sessionId: SessionId) => boolean
 }
@@ -16,6 +17,9 @@ export function createSessionStreams(): SessionStreams {
     publish: (sessionId, chunk) => {
       for (const listener of bySession.get(sessionId) ?? []) listener(chunk)
     },
+    publishAll: (chunk) => {
+      for (const listeners of bySession.values()) for (const listener of listeners) listener(chunk)
+    },
     listening: (sessionId) => (bySession.get(sessionId)?.size ?? 0) > 0,
     listen: (sessionId, onChunk) => {
       const listeners = bySession.get(sessionId) ?? new Set()

packages/core/src/lib/conciv-home.ts

@@ -0,0 +1,7 @@
+import {homedir} from 'node:os'
+import {join} from 'node:path'
+import {CONCIV_STATE_DIR} from '@conciv/protocol/state-types'
+
+export function concivHomeDir(): string {
+  return join(homedir(), CONCIV_STATE_DIR)
+}

packages/core/src/lib/dev-endpoint.ts

@@ -1,8 +1,8 @@
 import {randomUUID} from 'node:crypto'
 import {chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync} from 'node:fs'
-import {homedir} from 'node:os'
 import {join} from 'node:path'
 import {z} from 'zod'
+import {concivHomeDir} from './conciv-home.js'
 
 const FILE_NAME = 'dev-endpoint.json'
 const FILE_MODE = 0o600
@@ -16,7 +16,7 @@ export const DevEndpointSchema = z.object({
 export type DevEndpoint = z.infer<typeof DevEndpointSchema>
 
 export function defaultDevEndpointDir(): string {
-  return join(homedir(), '.conciv')
+  return concivHomeDir()
 }
 
 function endpointPath(dir: string): string {

packages/core/src/settings/history.ts

@@ -0,0 +1,37 @@
+import {appendFileSync, mkdirSync, readFileSync} from 'node:fs'
+import {dirname} from 'node:path'
+import {SettingsHistoryEntrySchema, type SettingsHistoryEntry} from '@conciv/protocol/settings-types'
+import {logError} from '../lib/debug.js'
+
+export function appendHistory(path: string, entry: SettingsHistoryEntry): void {
+  try {
+    mkdirSync(dirname(path), {recursive: true})
+    appendFileSync(path, `${JSON.stringify(entry)}\n`)
+  } catch (error) {
+    logError(`[core] the settings history sidecar could not be appended: ${String(error)}`)
+  }
+}
+
+function parseLine(line: string): SettingsHistoryEntry | null {
+  try {
+    const parsed = SettingsHistoryEntrySchema.safeParse(JSON.parse(line))
+    return parsed.success ? parsed.data : null
+  } catch {
+    return null
+  }
+}
+
+export function readHistory(path: string, key: string): SettingsHistoryEntry[] {
+  try {
+    return readFileSync(path, 'utf8')
+      .split('\n')
+      .toReversed()
+      .flatMap((line) => {
+        if (line.trim() === '') return []
+        const entry = parseLine(line)
+        return entry !== null && entry.key === key ? [entry] : []
+      })
+  } catch {
+    return []
+  }
+}