@fractary/codex-cli 0.10.24 → 0.10.26

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.
Files changed (2) hide show
  1. package/README.md +313 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,93 +1,349 @@
1
1
  # Fractary Codex CLI
2
2
 
3
- Command-line interface for Fractary Codex knowledge management system.
4
-
5
- ## Installation
3
+ Command-line interface for Fractary Codex knowledge management.
6
4
 
7
5
  ```bash
8
6
  npm install -g @fractary/codex-cli
9
7
  ```
10
8
 
11
- ## Quick Start
9
+ ## Commands
10
+
11
+ - [config-init](#config-init) - Initialize codex configuration
12
+ - [config-update](#config-update) - Update configuration fields
13
+ - [config-validate](#config-validate) - Validate configuration
14
+ - [document-fetch](#document-fetch) - Fetch a document by URI
15
+ - [cache-list](#cache-list) - List cache entries
16
+ - [cache-clear](#cache-clear) - Clear cache entries
17
+ - [cache-stats](#cache-stats) - Display cache statistics
18
+ - [cache-health](#cache-health) - Run diagnostics
19
+ - [sync](#sync) - Sync project with codex repository
20
+
21
+ ---
22
+
23
+ ### config-init
24
+
25
+ Initialize the codex section in `.fractary/config.yaml`. Requires a base config file created by `@fractary/core`.
12
26
 
13
27
  ```bash
14
- # Initialize configuration
15
- fractary-codex configure
28
+ fractary-codex config-init [options]
29
+ ```
16
30
 
17
- # Fetch a document
18
- fractary-codex document-fetch codex://myorg/myproject/README.md
31
+ | Option | Type | Default | Description |
32
+ |--------|------|---------|-------------|
33
+ | `--org <slug>` | string | auto-detected from git remote | Organization slug (e.g., `fractary`) |
34
+ | `--project <name>` | string | derived from directory name | Project name |
35
+ | `--codex-repo <name>` | string | auto-discovered or `codex.{org}.com` | Codex repository name |
36
+ | `--sync-preset <name>` | string | `standard` | Sync preset: `standard` or `minimal` |
37
+ | `--force` | boolean | `false` | Overwrite existing codex section |
38
+ | `--no-mcp` | boolean | `false` | Skip MCP server installation |
39
+ | `--json` | boolean | `false` | Output as JSON |
19
40
 
20
- # Check cache status
21
- fractary-codex cache-stats
41
+ **Examples:**
42
+
43
+ ```bash
44
+ # Auto-detect everything
45
+ fractary-codex config-init
22
46
 
23
- # Run health check
24
- fractary-codex cache-health
47
+ # Specify organization and codex repo
48
+ fractary-codex config-init --org myorg --codex-repo codex.myorg.com
49
+
50
+ # Use minimal sync preset, skip MCP
51
+ fractary-codex config-init --sync-preset minimal --no-mcp
52
+
53
+ # Overwrite existing config
54
+ fractary-codex config-init --force
25
55
  ```
26
56
 
27
- ## Commands Overview
57
+ **What it does:**
58
+ - Adds a `codex:` section to `.fractary/config.yaml`
59
+ - Creates cache directory (`.fractary/codex/cache/`)
60
+ - Installs MCP server in `.mcp.json` (unless `--no-mcp`)
61
+ - Updates `.fractary/.gitignore`
28
62
 
29
- | Command | Description |
30
- |---------|-------------|
31
- | `configure` | Initialize configuration |
32
- | `document-fetch <uri>` | Fetch documents by codex:// URI |
33
- | `cache-list` | List cached documents |
34
- | `cache-clear` | Clear cache entries |
35
- | `cache-stats` | Show cache statistics |
36
- | `cache-health` | Run diagnostics |
37
- | `sync` | Sync project with codex repository |
63
+ ---
38
64
 
39
- ## Documentation
65
+ ### config-update
40
66
 
41
- **Full documentation**: [docs/cli/](../docs/cli/)
67
+ Update specific fields in the codex configuration. Requires at least one field to update.
42
68
 
43
- - [Commands Reference](../docs/cli/#commands-reference)
44
- - [Integration Patterns](../docs/cli/#integration-patterns)
45
- - [Troubleshooting](../docs/cli/#troubleshooting)
46
- - [Configuration Guide](../docs/configuration.md)
69
+ ```bash
70
+ fractary-codex config-update [options]
71
+ ```
47
72
 
48
- ## Configuration
73
+ | Option | Type | Default | Description |
74
+ |--------|------|---------|-------------|
75
+ | `--org <slug>` | string | | Update organization slug |
76
+ | `--project <name>` | string | | Update project name |
77
+ | `--codex-repo <name>` | string | | Update codex repository name |
78
+ | `--sync-preset <name>` | string | | Update sync preset: `standard` or `minimal` |
79
+ | `--no-mcp` | boolean | `false` | Skip MCP server update |
80
+ | `--json` | boolean | `false` | Output as JSON |
49
81
 
50
- Uses `.fractary/config.yaml`:
82
+ **Examples:**
51
83
 
52
- ```yaml
53
- organization: myorg
54
- cacheDir: .fractary/codex/cache
84
+ ```bash
85
+ # Change organization
86
+ fractary-codex config-update --org neworg
55
87
 
56
- storage:
57
- - type: github
58
- token: ${GITHUB_TOKEN}
88
+ # Update codex repo and sync preset
89
+ fractary-codex config-update --codex-repo codex.neworg.com --sync-preset minimal
59
90
  ```
60
91
 
61
- ## Environment Variables
92
+ ---
62
93
 
63
- | Variable | Description |
64
- |----------|-------------|
65
- | `GITHUB_TOKEN` | GitHub access token |
66
- | `CODEX_CACHE_DIR` | Override cache directory |
67
- | `CODEX_ORG` | Override organization |
94
+ ### config-validate
68
95
 
69
- ## Development
96
+ Validate the codex configuration in `.fractary/config.yaml`. Read-only - does not modify any files.
70
97
 
71
98
  ```bash
72
- # Build
73
- npm run build
99
+ fractary-codex config-validate [options]
100
+ ```
74
101
 
75
- # Test
76
- npm test
102
+ | Option | Type | Default | Description |
103
+ |--------|------|---------|-------------|
104
+ | `--json` | boolean | `false` | Output as JSON |
77
105
 
78
- # Type check
79
- npm run typecheck
106
+ **Checks performed:**
107
+ - Configuration structure and required fields
108
+ - Field format validation (org, project, codex-repo names)
109
+ - Cache directory existence
110
+ - MCP server configuration
111
+ - Gitignore entries
80
112
 
81
- # Link for local testing
82
- npm link
113
+ ---
114
+
115
+ ### document-fetch
116
+
117
+ Fetch a document by its `codex://` URI.
118
+
119
+ ```bash
120
+ fractary-codex document-fetch <uri> [options]
83
121
  ```
84
122
 
85
- ## License
123
+ | Argument | Type | Required | Description |
124
+ |----------|------|----------|-------------|
125
+ | `<uri>` | string | yes | Codex URI (e.g., `codex://org/project/docs/file.md`) |
86
126
 
87
- MIT
127
+ | Option | Type | Default | Description |
128
+ |--------|------|---------|-------------|
129
+ | `--bypass-cache` | boolean | `false` | Skip cache and fetch directly from source |
130
+ | `--ttl <seconds>` | number | type-based default | Override default TTL in seconds |
131
+ | `--json` | boolean | `false` | Output as JSON with metadata |
132
+ | `--output <file>` | string | stdout | Write content to file instead of stdout |
133
+
134
+ **Examples:**
135
+
136
+ ```bash
137
+ # Fetch and print to stdout
138
+ fractary-codex document-fetch codex://myorg/project/docs/api.md
139
+
140
+ # Bypass cache for fresh content
141
+ fractary-codex document-fetch codex://myorg/project/docs/api.md --bypass-cache
142
+
143
+ # Save to file with custom TTL
144
+ fractary-codex document-fetch codex://myorg/project/specs/auth.md --output ./auth.md --ttl 3600
145
+
146
+ # Get JSON response with metadata
147
+ fractary-codex document-fetch codex://myorg/project/docs/api.md --json
148
+ ```
149
+
150
+ ---
151
+
152
+ ### cache-list
153
+
154
+ List documents in the cache.
155
+
156
+ ```bash
157
+ fractary-codex cache-list [options]
158
+ ```
159
+
160
+ | Option | Type | Default | Description |
161
+ |--------|------|---------|-------------|
162
+ | `--status <status>` | string | `all` | Filter by status: `fresh`, `stale`, `expired`, `all` |
163
+ | `--limit <n>` | number | no limit | Maximum number of entries to show |
164
+ | `--sort <field>` | string | `uri` | Sort by: `uri`, `size`, `createdAt`, `expiresAt` |
165
+ | `--desc` | boolean | `false` | Sort in descending order |
166
+ | `--verbose` | boolean | `false` | Show detailed entry information |
167
+ | `--json` | boolean | `false` | Output as JSON |
168
+
169
+ **Examples:**
170
+
171
+ ```bash
172
+ # List all cached documents
173
+ fractary-codex cache-list
174
+
175
+ # Show only fresh entries, sorted by size
176
+ fractary-codex cache-list --status fresh --sort size --desc
177
+
178
+ # Detailed view of 10 most recent
179
+ fractary-codex cache-list --verbose --limit 10 --sort createdAt --desc
180
+
181
+ # JSON output for scripting
182
+ fractary-codex cache-list --json
183
+ ```
184
+
185
+ ---
186
+
187
+ ### cache-clear
188
+
189
+ Clear cache entries. Requires either `--all` or `--pattern`.
190
+
191
+ ```bash
192
+ fractary-codex cache-clear [options]
193
+ ```
194
+
195
+ | Option | Type | Default | Description |
196
+ |--------|------|---------|-------------|
197
+ | `--all` | boolean | `false` | Clear entire cache |
198
+ | `--pattern <glob>` | string | | Clear entries matching URI pattern |
199
+ | `--dry-run` | boolean | `false` | Show what would be cleared without clearing |
200
+
201
+ **Examples:**
202
+
203
+ ```bash
204
+ # Clear everything
205
+ fractary-codex cache-clear --all
206
+
207
+ # Clear entries for a specific project
208
+ fractary-codex cache-clear --pattern "codex://myorg/project/*"
209
+
210
+ # Preview what would be cleared
211
+ fractary-codex cache-clear --pattern "codex://myorg/*" --dry-run
212
+ ```
88
213
 
89
- ## See Also
214
+ ---
90
215
 
91
- - [SDK Package](../sdk/js/) - Core JavaScript SDK
92
- - [MCP Server](../mcp/server/) - AI agent integration
93
- - [Documentation](../docs/) - Full documentation
216
+ ### cache-stats
217
+
218
+ Display cache statistics (entry count, total size, hit rates).
219
+
220
+ ```bash
221
+ fractary-codex cache-stats [options]
222
+ ```
223
+
224
+ | Option | Type | Default | Description |
225
+ |--------|------|---------|-------------|
226
+ | `--json` | boolean | `false` | Output as JSON |
227
+
228
+ ---
229
+
230
+ ### cache-health
231
+
232
+ Run diagnostics on the codex setup.
233
+
234
+ ```bash
235
+ fractary-codex cache-health [options]
236
+ ```
237
+
238
+ | Option | Type | Default | Description |
239
+ |--------|------|---------|-------------|
240
+ | `--json` | boolean | `false` | Output as JSON |
241
+
242
+ **Diagnostics include:**
243
+ - Configuration validity
244
+ - Storage provider accessibility
245
+ - SDK client initialization
246
+ - Cache health and integrity
247
+ - Type registry status
248
+
249
+ ---
250
+
251
+ ### sync
252
+
253
+ Sync a project with its codex repository.
254
+
255
+ ```bash
256
+ fractary-codex sync [name] [options]
257
+ ```
258
+
259
+ | Argument | Type | Required | Description |
260
+ |----------|------|----------|-------------|
261
+ | `[name]` | string | no | Project name (auto-detected if not provided) |
262
+
263
+ | Option | Type | Default | Description |
264
+ |--------|------|---------|-------------|
265
+ | `--env <env>` | string | `prod` | Target environment: `dev`, `test`, `staging`, `prod` |
266
+ | `--dry-run` | boolean | `false` | Show what would sync without executing |
267
+ | `--direction <dir>` | string | `bidirectional` | Sync direction: `to-codex`, `from-codex`, `bidirectional` |
268
+ | `--include <pattern>` | string[] | from config | Include files matching pattern (repeatable) |
269
+ | `--exclude <pattern>` | string[] | from config | Exclude files matching pattern (repeatable) |
270
+ | `--force` | boolean | `false` | Force sync without checking timestamps |
271
+ | `--json` | boolean | `false` | Output as JSON |
272
+ | `--work-id <id>` | string | | GitHub issue number or URL to scope sync |
273
+
274
+ **Environment to branch mapping:**
275
+
276
+ | Environment | Branch |
277
+ |-------------|--------|
278
+ | `dev` | `develop` |
279
+ | `test` | `test` |
280
+ | `staging` | `staging` |
281
+ | `prod` | `main` |
282
+
283
+ **Default include patterns** (when none specified):
284
+ ```
285
+ docs/**/*.md
286
+ specs/**/*.md
287
+ .fractary/standards/**
288
+ .fractary/templates/**
289
+ ```
290
+
291
+ **Examples:**
292
+
293
+ ```bash
294
+ # Preview sync changes
295
+ fractary-codex sync --dry-run
296
+
297
+ # Sync only docs to codex
298
+ fractary-codex sync --direction to-codex --include "docs/**"
299
+
300
+ # Sync from dev environment
301
+ fractary-codex sync --env dev
302
+
303
+ # Sync scoped to a GitHub issue
304
+ fractary-codex sync --work-id 42
305
+
306
+ # Force sync a specific project
307
+ fractary-codex sync myproject --force
308
+ ```
309
+
310
+ ---
311
+
312
+ ## Configuration
313
+
314
+ The CLI uses `.fractary/config.yaml` for configuration. Initialize with:
315
+
316
+ ```bash
317
+ fractary-codex config-init
318
+ ```
319
+
320
+ Minimal configuration:
321
+
322
+ ```yaml
323
+ codex:
324
+ schema_version: "2.0"
325
+ organization: myorg
326
+ project: myproject
327
+ codex_repo: codex.myorg.com
328
+ remotes:
329
+ myorg/codex.myorg.com:
330
+ token: ${GITHUB_TOKEN}
331
+ ```
332
+
333
+ See the [Configuration Guide](../docs/configuration.md) for the full reference.
334
+
335
+ ## Environment Variables
336
+
337
+ | Variable | Description |
338
+ |----------|-------------|
339
+ | `GITHUB_TOKEN` | GitHub API token for private repository access |
340
+
341
+ Environment variables can be referenced in config files using `${VAR_NAME}` syntax.
342
+
343
+ ## Deprecated Commands
344
+
345
+ The `configure` command is deprecated. Use `config-init`, `config-update`, and `config-validate` instead.
346
+
347
+ ## License
348
+
349
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fractary/codex-cli",
3
- "version": "0.10.24",
3
+ "version": "0.10.26",
4
4
  "description": "Command-line interface for Fractary Codex knowledge management",
5
5
  "keywords": [
6
6
  "codex",