@karmaniverous/jeeves-meta 0.3.2 → 0.4.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.
Files changed (6) hide show
  1. package/README.md +44 -33
  2. package/dist/cli/jeeves-meta/index.js +3799 -0
  3. package/dist/index.d.ts +540 -106
  4. package/dist/index.js +2144 -419
  5. package/package.json +20 -25
  6. package/dist/cli.js +0 -2159
package/README.md CHANGED
@@ -1,62 +1,73 @@
1
1
  # @karmaniverous/jeeves-meta
2
2
 
3
- Core synthesis engine for the Jeeves platform. Provides schemas, filesystem discovery, weighted staleness scheduling, three-step orchestration, and a full CLI.
3
+ HTTP service for the Jeeves knowledge synthesis engine. Provides a Fastify API, built-in croner-based scheduler, single-threaded synthesis queue, and a Commander CLI.
4
4
 
5
5
  ## Features
6
6
 
7
- - **Zod schemas** — validated `meta.json` and config structures with open schema support
8
- - **Filesystem discovery** — glob `.meta/` directories, build ownership trees, compute scopes
9
- - **Weighted staleness** — depth-aware scheduling formula with emphasis multipliers
7
+ - **Fastify HTTP API** — `/status`, `/metas`, `/preview`, `/synthesize`, `/seed`, `/unlock`, `/config/validate`
8
+ - **Built-in scheduler** — croner-based cron with adaptive backoff
9
+ - **Synthesis queue** — single-threaded, priority-aware, deduplicated
10
10
  - **Three-step orchestration** — architect, builder, critic with conditional re-architecture
11
+ - **Discovery via watcher** — scan-based meta discovery with configurable domain tags
12
+ - **Ownership tree** — hierarchical scoping with child meta rollup
11
13
  - **Archive management** — timestamped snapshots with configurable pruning
12
- - **Structure hashing** — detect scope changes (file additions/removals)
13
- - **Lock management** — filesystem locks with 30-minute stale timeout
14
- - **Pluggable executor** — `SynthExecutor` interface for runtime-agnostic subprocess spawning
15
- - **Pluggable watcher client** — `WatcherClient` interface with HTTP implementation (3-retry exponential backoff)
16
- - **Token tracking** — per-step token counts with exponential moving averages
17
- - **CLI** — 10 commands for status, listing, synthesis, debugging, and maintenance
18
- - **Config loader** — `loadSynthConfig()` with `@file:` reference resolution
14
+ - **Lock staging** — write to `.lock` → copy to `meta.json` → archive (crash-safe)
15
+ - **Virtual rule registration** — registers 3 watcher inference rules at startup with retry
16
+ - **Progress reporting** — real-time synthesis events via gateway channel messages
17
+ - **Graceful shutdown** — stop scheduler, release locks, close server
18
+ - **Config hot-reload** — schedule, reportChannel, log level reload without restart
19
+ - **Token tracking** — per-step counts with exponential moving averages
20
+ - **CLI** — `status`, `list`, `detail`, `preview`, `synthesize`, `seed`, `unlock`, `validate`, `service` commands
21
+ - **Zod schemas** — validated meta.json and config with open schema support
19
22
 
20
23
  ## Install
21
24
 
22
25
  ```bash
23
- npm install @karmaniverous/jeeves-meta
26
+ npm install -g @karmaniverous/jeeves-meta
24
27
  ```
25
28
 
26
29
  ## Quick Start
27
30
 
28
- ### Library usage
31
+ ```bash
32
+ # Start the service
33
+ jeeves-meta start --config /path/to/jeeves-meta.config.json
34
+
35
+ # Check status
36
+ jeeves-meta status
29
37
 
30
- ```typescript
31
- import {
32
- createSynthEngine,
33
- HttpWatcherClient,
34
- loadSynthConfig,
35
- } from '@karmaniverous/jeeves-meta';
38
+ # List all metas
39
+ jeeves-meta list
36
40
 
37
- const config = loadSynthConfig('/path/to/jeeves-meta.config.json');
38
- const watcher = new HttpWatcherClient({ baseUrl: config.watcherUrl });
41
+ # Run synthesis
42
+ jeeves-meta synthesize
39
43
 
40
- const engine = createSynthEngine(config, myExecutor, watcher);
41
- const results = await engine.synthesize();
44
+ # Install as a system service (prints OS-specific instructions)
45
+ jeeves-meta service install --config /path/to/jeeves-meta.config.json
42
46
  ```
43
47
 
44
- ### CLI usage
48
+ ## HTTP API
45
49
 
46
- ```bash
47
- export JEEVES_META_CONFIG=/path/to/jeeves-meta.config.json
50
+ | Method | Path | Description |
51
+ |--------|------|-------------|
52
+ | GET | `/status` | Service health, queue state, dependency checks |
53
+ | GET | `/metas` | List metas with filtering and field projection |
54
+ | GET | `/metas/:path` | Single meta detail with optional archive |
55
+ | GET | `/preview` | Dry-run: preview inputs for next synthesis |
56
+ | POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
57
+ | POST | `/seed` | Create `.meta/` directory + meta.json |
58
+ | POST | `/unlock` | Remove `.lock` file from a meta entity |
59
+ | GET | `/config/validate` | Return sanitized active configuration |
48
60
 
49
- npx @karmaniverous/jeeves-meta status # summary stats
50
- npx @karmaniverous/jeeves-meta list # list all metas
51
- npx @karmaniverous/jeeves-meta synthesize # run synthesis cycle
52
- npx @karmaniverous/jeeves-meta help # all commands
53
- ```
61
+ ## Configuration
62
+
63
+ See the [Configuration Guide](guides/configuration.md) for all fields, defaults, and environment variable substitution.
54
64
 
55
65
  ## Documentation
56
66
 
57
- - **[Engine Guides](guides/index.md)** — concepts, configuration, orchestration, scheduling, architecture patterns
58
- - **[CLI Reference](guides/cli.md)** — all 10 commands with examples
67
+ - **[Guides](guides/index.md)** — concepts, configuration, orchestration, scheduling, architecture
68
+ - **[CLI Reference](guides/cli.md)** — all commands with usage
59
69
 
60
70
  ## License
61
71
 
62
72
  BSD-3-Clause
73
+