@x-otto/setting 0.0.1-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -0
- package/dist/index.d.ts +2047 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# @x-otto/setting
|
|
2
|
+
|
|
3
|
+
> Configuration loading, merging, validation, migration, and monitoring. Single source of truth for the config shape via zod schema.
|
|
4
|
+
|
|
5
|
+
`@x-otto/setting` manages the entire configuration lifecycle: loading from file/env/memory sources, deep merging with precedence layering, version migration, validation with lenient error handling, file watching, and remote sync. The config shape is defined by a canonical zod schema (`schema.ts`) from which the `Setting` type and `SETTING_KEYS` are derived. Supports 2 built-in Reviewer Agent presets (spec-reviewer, quality-reviewer).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @x-otto/setting
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { SettingsManager, RawFileSettingStore } from '@x-otto/setting'
|
|
17
|
+
import { DEFAULT_CONFIG } from '@x-otto/setting'
|
|
18
|
+
|
|
19
|
+
// Load project config
|
|
20
|
+
const manager = new SettingsManager({
|
|
21
|
+
workspaceDir: '/path/to/project',
|
|
22
|
+
overrides: { log_level: 'debug' },
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
await manager.load()
|
|
26
|
+
console.log(manager.get('model')) // current model setting
|
|
27
|
+
console.log(manager.config) // merged full config
|
|
28
|
+
|
|
29
|
+
// Watch for file changes
|
|
30
|
+
const { createSettingWatcher } = await import('@x-otto/setting')
|
|
31
|
+
const watcher = createSettingWatcher({
|
|
32
|
+
paths: ['/path/to/project/.otto/config.json'],
|
|
33
|
+
reload: (path) => manager.reload(),
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## API
|
|
38
|
+
|
|
39
|
+
### SettingsManager
|
|
40
|
+
- `new SettingsManager(options)` — main config consumer entry point
|
|
41
|
+
- `load()` / `reload()` — load/reload from store + env
|
|
42
|
+
- `update(overrides)` — apply runtime overrides
|
|
43
|
+
- `get(key)` — typed access to specific settings
|
|
44
|
+
- `config` / `snapshot` — full merged config access
|
|
45
|
+
- `model` / `compaction` / `session` — convenience accessors
|
|
46
|
+
- Events: `'change'` — emitted on config change
|
|
47
|
+
|
|
48
|
+
### SettingLoader
|
|
49
|
+
- `loadSetting(options)` — multi-source load + merge + validate
|
|
50
|
+
- `SettingLoader.save(config)` — write back to store
|
|
51
|
+
|
|
52
|
+
### Stores
|
|
53
|
+
- `RawFileSettingStore` — literal file path read/write (with `~/` expansion)
|
|
54
|
+
- `RemoteSettingStore` — HTTP remote config fetching
|
|
55
|
+
- `SettingStore` interface — pluggable storage
|
|
56
|
+
|
|
57
|
+
### Watcher
|
|
58
|
+
- `createSettingWatcher(options)` — `fs.watch` with per-path debounce (300ms default)
|
|
59
|
+
- Implements `Disposable` (`Symbol.dispose`)
|
|
60
|
+
|
|
61
|
+
### Migration
|
|
62
|
+
- `migrate(config, migrations)` — pure function, semver-ordered migration chain
|
|
63
|
+
- Appends `_migrations` log on each step
|
|
64
|
+
|
|
65
|
+
### Claude Settings
|
|
66
|
+
- `translateClaudeSettings(raw)` — translate `.claude/settings.json` → otto config
|
|
67
|
+
- `loadClaudeSettingsLayer(dir)` — load claude layer from specifier
|
|
68
|
+
- `parseToolSpecifier(spec)` — parse `Bash(cmd:*)` style permission specifiers
|
|
69
|
+
|
|
70
|
+
### Export Format
|
|
71
|
+
- `buildExportPayload(config)` / `parseExportFile(json)` — config export/import
|
|
72
|
+
- Config export/import with version validation
|
|
73
|
+
|
|
74
|
+
### Config Merge Strategy
|
|
75
|
+
- `diffConfig(oldCfg, newCfg)` — structured diff
|
|
76
|
+
- `classifyPluginChanges(oldCfg, newCfg)` — classify plugin additions/removals
|
|
77
|
+
- `hasSecuritySensitiveChanges(diff)` — detect security-relevant changes
|
|
78
|
+
- `applyMergeStrategy(base, incoming, strategy)` — apply merge strategy
|
|
79
|
+
|
|
80
|
+
### Built-in Presets
|
|
81
|
+
- `BUILTIN_REVIEWER_AGENTS` — 2 reviewer agent presets
|
|
82
|
+
- `DEFAULT_CONFIG` — complete default configuration
|
|
83
|
+
- `BUILTIN_AGENT_PROFILES` — agent profile presets
|
|
84
|
+
- `HIGH_RISK_PROJECT_KEYS` / `sanitizeUntrustedProjectLayer` — project trust model
|
|
85
|
+
|
|
86
|
+
### Constants
|
|
87
|
+
- `SETTING_KEYS` — all valid config keys (derived from schema)
|
|
88
|
+
- `TOOL_PRESETS`, `LOG_LEVELS`, `PERMISSION_MODES`
|
|
89
|
+
- `SYNCABLE_KEYS`, `NEVER_SYNCED_KEYS` — remote sync configuration
|
|
90
|
+
|
|
91
|
+
## Dependencies
|
|
92
|
+
|
|
93
|
+
- Internal: `@x-otto/env`, `@x-otto/shared`, `@x-otto/hook-contracts`, `@x-otto/orchestration-contracts`, `@x-otto/plugin`, `@x-otto/prompt`
|
|
94
|
+
- External: `semver`, `zod`
|
|
95
|
+
|
|
96
|
+
## Related
|
|
97
|
+
|
|
98
|
+
- [Architecture](./ARCHITECTURE.md)
|