@karmaniverous/jeeves 0.1.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.
@@ -0,0 +1,670 @@
1
+ import { z } from 'zod';
2
+
3
+ /**
4
+ * Component interface types for the Jeeves platform.
5
+ *
6
+ * @remarks
7
+ * These types define the contract that component plugins must implement
8
+ * to participate in the platform. The `JeevesComponent` interface is
9
+ * the primary integration point.
10
+ */
11
+ /** Service health status. */
12
+ interface ServiceStatus {
13
+ /** Whether the service is running. */
14
+ running: boolean;
15
+ /** Optional version string. */
16
+ version?: string;
17
+ /** Optional uptime in seconds. */
18
+ uptimeSeconds?: number;
19
+ }
20
+ /** Service lifecycle commands. */
21
+ interface ServiceCommands {
22
+ /** Stop the service. */
23
+ stop(): Promise<void>;
24
+ /** Uninstall the service. */
25
+ uninstall(): Promise<void>;
26
+ /** Query service status. */
27
+ status(): Promise<ServiceStatus>;
28
+ }
29
+ /** Plugin lifecycle commands. */
30
+ interface PluginCommands {
31
+ /** Uninstall the plugin. */
32
+ uninstall(): Promise<void>;
33
+ }
34
+ /**
35
+ * Component descriptor — the contract that Jeeves component plugins
36
+ * must implement to participate in the platform.
37
+ */
38
+ interface JeevesComponent {
39
+ /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
40
+ name: string;
41
+ /** Component's own version. */
42
+ version: string;
43
+ /** TOOLS.md section name (e.g., 'Watcher'). */
44
+ sectionId: string;
45
+ /** Refresh interval in seconds (must be a prime number). */
46
+ refreshIntervalSeconds: number;
47
+ /** Produce the component's TOOLS.md section content. */
48
+ generateToolsContent(): string;
49
+ /** Service lifecycle commands. */
50
+ serviceCommands: ServiceCommands;
51
+ /** Plugin lifecycle commands. */
52
+ pluginCommands: PluginCommands;
53
+ }
54
+
55
+ /**
56
+ * Timer-based orchestrator for managed content writing.
57
+ *
58
+ * @remarks
59
+ * `ComponentWriter` manages a component's TOOLS.md section writes
60
+ * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
61
+ * on a configurable prime-interval timer cycle.
62
+ */
63
+
64
+ /**
65
+ * Orchestrates managed content writing for a single Jeeves component.
66
+ *
67
+ * @remarks
68
+ * Created via `createComponentWriter()`. Manages a timer that fires
69
+ * at the component's prime-interval, calling `generateToolsContent()`
70
+ * and `refreshPlatformContent()` on each cycle.
71
+ */
72
+ declare class ComponentWriter {
73
+ private timer;
74
+ private readonly component;
75
+ private readonly configDir;
76
+ private readonly probeTimeoutMs;
77
+ /** @internal */
78
+ constructor(component: JeevesComponent, probeTimeoutMs?: number);
79
+ /** The component's config directory path. */
80
+ get componentConfigDir(): string;
81
+ /** Whether the writer timer is currently running. */
82
+ get isRunning(): boolean;
83
+ /**
84
+ * Start the writer timer.
85
+ *
86
+ * @remarks
87
+ * Performs an immediate first write, then sets up the interval.
88
+ */
89
+ start(): void;
90
+ /** Stop the writer timer. */
91
+ stop(): void;
92
+ /**
93
+ * Execute a single write cycle.
94
+ *
95
+ * @remarks
96
+ * Calls `generateToolsContent()` and writes the component's
97
+ * TOOLS.md section via `updateManagedSection()`. Also calls
98
+ * `refreshPlatformContent()` for shared content maintenance.
99
+ */
100
+ cycle(): Promise<void>;
101
+ }
102
+
103
+ /**
104
+ * Factory function for creating a ComponentWriter.
105
+ *
106
+ * @remarks
107
+ * Validates the component descriptor at runtime:
108
+ * - `refreshIntervalSeconds` must be a prime number
109
+ * - `serviceCommands` and `pluginCommands` must be provided
110
+ * - `name`, `version`, `sectionId` must be non-empty strings
111
+ * - `generateToolsContent` must be a function
112
+ */
113
+
114
+ /** Options for creating a ComponentWriter. */
115
+ interface CreateComponentWriterOptions {
116
+ /** Timeout for health probes in ms (default 3000). */
117
+ probeTimeoutMs?: number;
118
+ }
119
+ /**
120
+ * Create a ComponentWriter for a validated component descriptor.
121
+ *
122
+ * @param component - The component descriptor to validate and wrap.
123
+ * @param options - Optional configuration.
124
+ * @returns A new `ComponentWriter` instance.
125
+ * @throws Error if the component descriptor is invalid.
126
+ */
127
+ declare function createComponentWriter(component: JeevesComponent, options?: CreateComponentWriterOptions): ComponentWriter;
128
+
129
+ /**
130
+ * Comment markers for managed content blocks.
131
+ *
132
+ * @remarks
133
+ * Managed content in TOOLS.md, SOUL.md, and AGENTS.md is enclosed
134
+ * in HTML comment markers. Content between markers is refreshed
135
+ * atomically on each writer cycle. User content outside the markers
136
+ * is never touched.
137
+ */
138
+ /** Default markers for TOOLS.md managed block. */
139
+ declare const TOOLS_MARKERS: {
140
+ /** BEGIN comment marker text. */
141
+ readonly begin: "BEGIN JEEVES PLATFORM TOOLS — DO NOT EDIT THIS SECTION";
142
+ /** END comment marker text. */
143
+ readonly end: "END JEEVES PLATFORM TOOLS";
144
+ /** H1 title prepended in section mode. */
145
+ readonly title: "Jeeves Platform Tools";
146
+ };
147
+ /** Default markers for SOUL.md managed block. */
148
+ declare const SOUL_MARKERS: {
149
+ /** BEGIN comment marker text. */
150
+ readonly begin: "BEGIN JEEVES SOUL — DO NOT EDIT THIS SECTION";
151
+ /** END comment marker text. */
152
+ readonly end: "END JEEVES SOUL";
153
+ };
154
+ /** Default markers for AGENTS.md managed block. */
155
+ declare const AGENTS_MARKERS: {
156
+ /** BEGIN comment marker text. */
157
+ readonly begin: "BEGIN JEEVES AGENTS — DO NOT EDIT THIS SECTION";
158
+ /** END comment marker text. */
159
+ readonly end: "END JEEVES AGENTS";
160
+ };
161
+ /**
162
+ * Regex pattern to extract version stamp from a BEGIN marker comment.
163
+ *
164
+ * @remarks
165
+ * Format: `\<!-- BEGIN MARKER | core:X.Y.Z | ISO-TIMESTAMP --\>`
166
+ * Captures: [1] marker text, [2] version, [3] timestamp
167
+ */
168
+ declare const VERSION_STAMP_PATTERN: RegExp;
169
+ /** Staleness threshold for version-stamp convergence in milliseconds. */
170
+ declare const STALENESS_THRESHOLD_MS: number;
171
+ /** Warning text prepended inside managed block when cleanup is needed. */
172
+ declare const CLEANUP_FLAG = "> \u26A0\uFE0F CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.";
173
+
174
+ /**
175
+ * Directory and file path conventions for the Jeeves platform.
176
+ */
177
+ /** Core config directory name within the config root. */
178
+ declare const CORE_CONFIG_DIR = "jeeves-core";
179
+ /** Prefix for component config directories: `jeeves-{name}`. */
180
+ declare const COMPONENT_CONFIG_PREFIX = "jeeves-";
181
+ /** Default workspace file names. */
182
+ declare const WORKSPACE_FILES: {
183
+ /** TOOLS.md — live platform state and component sections. */
184
+ readonly tools: "TOOLS.md";
185
+ /** SOUL.md — professional discipline and behavioral foundations. */
186
+ readonly soul: "SOUL.md";
187
+ /** AGENTS.md — operational protocols and memory architecture. */
188
+ readonly agents: "AGENTS.md";
189
+ };
190
+ /** Templates directory name within core config. */
191
+ declare const TEMPLATES_DIR = "templates";
192
+ /** Registry cache file name. */
193
+ declare const REGISTRY_CACHE_FILE = "registry-cache.json";
194
+ /** Core config file name. */
195
+ declare const CONFIG_FILE = "config.json";
196
+
197
+ /**
198
+ * Default port assignments for Jeeves platform services.
199
+ *
200
+ * @remarks
201
+ * Each port number is a historical reference:
202
+ * - 1934: Wodehouse's *Thank You, Jeeves*; Popper's *Logic of Scientific Discovery*
203
+ * - 1936: Turing's "On Computable Numbers"; Church's lambda calculus
204
+ * - 1937: Turing's paper in *Proceedings of the London Mathematical Society*
205
+ * - 1938: Wodehouse's *The Code of the Woosters*; Shannon's relay/switching paper
206
+ */
207
+ /** Default port for jeeves-server. */
208
+ declare const SERVER_PORT = 1934;
209
+ /** Default port for jeeves-watcher. */
210
+ declare const WATCHER_PORT = 1936;
211
+ /** Default port for jeeves-runner. */
212
+ declare const RUNNER_PORT = 1937;
213
+ /** Default port for jeeves-meta. */
214
+ declare const META_PORT = 1938;
215
+ /** Map of service names to their default ports. */
216
+ declare const DEFAULT_PORTS: Record<string, number>;
217
+
218
+ /**
219
+ * Managed section IDs and their stable ordering for TOOLS.md.
220
+ *
221
+ * @remarks
222
+ * Section ordering is fixed to prevent diff churn regardless of which
223
+ * component writes last. Sections always appear in this order.
224
+ */
225
+ /** Known section IDs for TOOLS.md managed block. */
226
+ declare const SECTION_IDS: {
227
+ /** Platform health and guidance section. */
228
+ readonly Platform: "Platform";
229
+ /** Watcher index stats and search configuration. */
230
+ readonly Watcher: "Watcher";
231
+ /** Server export capabilities and connected services. */
232
+ readonly Server: "Server";
233
+ /** Runner job status and active scripts. */
234
+ readonly Runner: "Runner";
235
+ /** Meta synthesis entity summary and tools. */
236
+ readonly Meta: "Meta";
237
+ };
238
+ /** Section ID type. */
239
+ type SectionId = (typeof SECTION_IDS)[keyof typeof SECTION_IDS];
240
+ /**
241
+ * Stable ordering of sections within the managed TOOLS.md block.
242
+ * Sections always appear in this order regardless of write order.
243
+ */
244
+ declare const SECTION_ORDER: readonly string[];
245
+
246
+ /**
247
+ * Core library version, read from package.json at runtime.
248
+ *
249
+ * @remarks
250
+ * Used for version-stamp convergence (Decision 21). The version stamp
251
+ * on managed content reflects the actual published library version,
252
+ * enabling higher-version writers to take precedence.
253
+ */
254
+ /** The core library version from package.json. */
255
+ declare const CORE_VERSION: string;
256
+
257
+ /**
258
+ * Core configuration schema and resolution.
259
+ *
260
+ * @remarks
261
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
262
+ * Config resolution order:
263
+ * 1. Component's own config file
264
+ * 2. Core config file
265
+ * 3. Hardcoded library defaults
266
+ */
267
+
268
+ /** Zod schema for the core config file. */
269
+ declare const coreConfigSchema: z.ZodObject<{
270
+ /** JSON Schema pointer for IDE autocomplete. */
271
+ $schema: z.ZodOptional<z.ZodString>;
272
+ /** Owner identity keys (canonical identityLinks references). */
273
+ owners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
274
+ /** Service URL overrides keyed by service name. */
275
+ services: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
276
+ /** Service URL (must be a valid URL). */
277
+ url: z.ZodString;
278
+ }, "strip", z.ZodTypeAny, {
279
+ url: string;
280
+ }, {
281
+ url: string;
282
+ }>>>;
283
+ /** Registry cache configuration. */
284
+ registryCache: z.ZodDefault<z.ZodObject<{
285
+ /** Cache TTL in seconds for npm registry queries. */
286
+ ttlSeconds: z.ZodDefault<z.ZodNumber>;
287
+ }, "strip", z.ZodTypeAny, {
288
+ ttlSeconds: number;
289
+ }, {
290
+ ttlSeconds?: number | undefined;
291
+ }>>;
292
+ }, "strip", z.ZodTypeAny, {
293
+ owners: string[];
294
+ services: Record<string, {
295
+ url: string;
296
+ }>;
297
+ registryCache: {
298
+ ttlSeconds: number;
299
+ };
300
+ $schema?: string | undefined;
301
+ }, {
302
+ $schema?: string | undefined;
303
+ owners?: string[] | undefined;
304
+ services?: Record<string, {
305
+ url: string;
306
+ }> | undefined;
307
+ registryCache?: {
308
+ ttlSeconds?: number | undefined;
309
+ } | undefined;
310
+ }>;
311
+ /** Core config type derived from the Zod schema. */
312
+ type CoreConfig = z.infer<typeof coreConfigSchema>;
313
+ /**
314
+ * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
315
+ *
316
+ * @returns A JSON Schema object.
317
+ */
318
+ declare function generateJsonSchema(): Record<string, unknown>;
319
+
320
+ /**
321
+ * Service URL resolution.
322
+ *
323
+ * @remarks
324
+ * Resolves the URL for a named Jeeves service using the following
325
+ * resolution order:
326
+ * 1. Consumer's own component config
327
+ * 2. Core config (`{configRoot}/jeeves-core/config.json`)
328
+ * 3. Default port constants
329
+ */
330
+ /**
331
+ * Resolve the URL for a named Jeeves service.
332
+ *
333
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
334
+ * @param consumerName - Optional consumer component name for config override.
335
+ * @returns The resolved service URL.
336
+ * @throws Error if `init()` has not been called or the service is unknown.
337
+ */
338
+ declare function getServiceUrl(serviceName: string, consumerName?: string): string;
339
+
340
+ /**
341
+ * HTTP health probing for Jeeves platform services.
342
+ *
343
+ * @remarks
344
+ * Probes service ports for health endpoints (HTTP GET to /status or /health).
345
+ * Returns structured health data for rendering into TOOLS.md Platform section.
346
+ */
347
+ /** Health probe result for a single service. */
348
+ interface ProbeResult {
349
+ /** Service name (e.g., 'server', 'watcher'). */
350
+ name: string;
351
+ /** Port number. */
352
+ port: number;
353
+ /** Whether the service responded successfully. */
354
+ healthy: boolean;
355
+ /** Service version from the health response, if available. */
356
+ version?: string;
357
+ /** Error message if the probe failed. */
358
+ error?: string;
359
+ }
360
+ /**
361
+ * Probe a single service for health.
362
+ *
363
+ * @param serviceName - The service name (e.g., 'server', 'watcher').
364
+ * @param consumerName - Optional consumer name for URL resolution.
365
+ * @param timeoutMs - Request timeout in milliseconds (default 3000).
366
+ * @returns Probe result.
367
+ */
368
+ declare function probeService(serviceName: string, consumerName?: string, timeoutMs?: number): Promise<ProbeResult>;
369
+ /**
370
+ * Probe all known Jeeves services for health.
371
+ *
372
+ * @param consumerName - Optional consumer name for URL resolution.
373
+ * @param timeoutMs - Request timeout in milliseconds (default 3000).
374
+ * @returns Array of probe results for all services.
375
+ */
376
+ declare function probeAllServices(consumerName?: string, timeoutMs?: number): Promise<ProbeResult[]>;
377
+
378
+ /**
379
+ * Registry version cache for npm package update awareness.
380
+ *
381
+ * @remarks
382
+ * Caches the latest npm registry version in a local JSON file
383
+ * to avoid expensive `npm view` calls on every refresh cycle.
384
+ */
385
+ /**
386
+ * Check the npm registry for the latest version of a package.
387
+ *
388
+ * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
389
+ * @param cacheDir - Directory to store the cache file.
390
+ * @param ttlSeconds - Cache TTL in seconds (default 3600).
391
+ * @returns The latest version string, or undefined if the check fails.
392
+ */
393
+ declare function checkRegistryVersion(packageName: string, cacheDir: string, ttlSeconds?: number): string | undefined;
394
+
395
+ /**
396
+ * Workspace and config root initialization.
397
+ *
398
+ * @remarks
399
+ * `init()` must be called once before any other core library functions.
400
+ * It caches `workspacePath` and `configRoot` at module level.
401
+ * Core derives all namespaced paths from these values:
402
+ * - `{configRoot}/jeeves-core/` for core config
403
+ * - `{configRoot}/jeeves-{name}/` for each component
404
+ */
405
+ /** Options for initializing the core library. */
406
+ interface InitOptions {
407
+ /** Absolute path to the OpenClaw workspace root. */
408
+ workspacePath: string;
409
+ /** Absolute path to the platform config root (e.g., `j:/config`). */
410
+ configRoot: string;
411
+ }
412
+ /**
413
+ * Initialize the core library with workspace and config root paths.
414
+ *
415
+ * @param options - Workspace and config root paths.
416
+ */
417
+ declare function init(options: InitOptions): void;
418
+ /**
419
+ * Get the cached workspace path.
420
+ *
421
+ * @throws Error if `init()` has not been called.
422
+ */
423
+ declare function getWorkspacePath(): string;
424
+ /**
425
+ * Get the cached config root path.
426
+ *
427
+ * @throws Error if `init()` has not been called.
428
+ */
429
+ declare function getConfigRoot(): string;
430
+ /**
431
+ * Get the core config directory path.
432
+ *
433
+ * @throws Error if `init()` has not been called.
434
+ */
435
+ declare function getCoreConfigDir(): string;
436
+ /**
437
+ * Get the core config file path.
438
+ *
439
+ * @throws Error if `init()` has not been called.
440
+ */
441
+ declare function getCoreConfigFile(): string;
442
+ /**
443
+ * Derive the component config directory from the component name.
444
+ *
445
+ * @param componentName - The component name (e.g., 'watcher', 'runner').
446
+ * @returns Absolute path to the component's config directory.
447
+ * @throws Error if `init()` has not been called.
448
+ */
449
+ declare function getComponentConfigDir(componentName: string): string;
450
+ /**
451
+ * Reset initialization state. Used for testing only.
452
+ */
453
+ declare function resetInit(): void;
454
+
455
+ /**
456
+ * Similarity-based cleanup detection for orphaned managed content.
457
+ *
458
+ * @remarks
459
+ * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
460
+ * when orphaned managed content exists in the user content zone.
461
+ */
462
+ /**
463
+ * Generate a set of n-word shingles from text.
464
+ *
465
+ * @param text - Input text.
466
+ * @param n - Shingle size (default 3).
467
+ * @returns Set of n-word shingles.
468
+ */
469
+ declare function shingles(text: string, n?: number): Set<string>;
470
+ /**
471
+ * Compute Jaccard similarity between two sets.
472
+ *
473
+ * @param a - First set.
474
+ * @param b - Second set.
475
+ * @returns Jaccard similarity coefficient (0 to 1).
476
+ */
477
+ declare function jaccard(a: Set<string>, b: Set<string>): number;
478
+ /**
479
+ * Check whether user content contains orphaned managed content.
480
+ *
481
+ * @param managedContent - The current managed block content.
482
+ * @param userContent - Content below the END marker.
483
+ * @param threshold - Jaccard threshold (default 0.15).
484
+ * @returns `true` if cleanup is needed.
485
+ */
486
+ declare function needsCleanup(managedContent: string, userContent: string, threshold?: number): boolean;
487
+
488
+ /**
489
+ * Parse managed block from file content.
490
+ *
491
+ * @remarks
492
+ * Extracts managed content delimited by comment markers, parses H2
493
+ * sections within the block, and returns the structured result plus
494
+ * user content outside the markers.
495
+ */
496
+ /** A parsed H2 section within the managed block. */
497
+ interface ManagedSection {
498
+ /** Section heading text (without the `## ` prefix). */
499
+ id: string;
500
+ /** Content below the heading (trimmed). */
501
+ content: string;
502
+ }
503
+ /** Version stamp extracted from the BEGIN marker. */
504
+ interface VersionStamp {
505
+ /** Core library version (semver). */
506
+ version: string;
507
+ /** ISO timestamp of last write. */
508
+ timestamp: string;
509
+ }
510
+ /** Result of parsing a managed block from file content. */
511
+ interface ParseManagedResult {
512
+ /** Whether valid markers were found. */
513
+ found: boolean;
514
+ /** Version stamp from the BEGIN marker, if present. */
515
+ versionStamp: VersionStamp | undefined;
516
+ /** Raw managed block content (between markers, excluding markers). */
517
+ managedContent: string;
518
+ /** Parsed H2 sections within the managed block. */
519
+ sections: ManagedSection[];
520
+ /** Content before the BEGIN marker. */
521
+ beforeContent: string;
522
+ /** Content after the END marker (user content). */
523
+ userContent: string;
524
+ }
525
+ /**
526
+ * Parse a managed block from file content.
527
+ *
528
+ * @param fileContent - Full file content.
529
+ * @param markers - Optional custom markers (defaults to TOOLS markers).
530
+ * @returns Parsed result with sections, version stamp, and user content.
531
+ */
532
+ declare function parseManaged(fileContent: string, markers?: {
533
+ begin: string;
534
+ end: string;
535
+ }): ParseManagedResult;
536
+
537
+ /**
538
+ * Generic managed-section writer with block and section modes.
539
+ *
540
+ * @remarks
541
+ * Supports two modes:
542
+ * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
543
+ * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
544
+ *
545
+ * Provides file-level locking, version-stamp convergence, and atomic writes.
546
+ */
547
+ /** Options for updateManagedSection. */
548
+ interface UpdateManagedSectionOptions {
549
+ /** Write mode. Default: 'block'. */
550
+ mode?: 'block' | 'section';
551
+ /** Section ID — required when mode is 'section'. */
552
+ sectionId?: string;
553
+ /** Custom markers. Defaults to TOOLS markers. */
554
+ markers?: {
555
+ /** BEGIN comment marker text. */
556
+ begin: string;
557
+ /** END comment marker text. */
558
+ end: string;
559
+ /** Optional H1 title prepended in section mode. */
560
+ title?: string;
561
+ };
562
+ /** Core library version for version-stamp convergence. */
563
+ coreVersion?: string;
564
+ /** Staleness threshold in ms for version-stamp convergence. */
565
+ stalenessThresholdMs?: number;
566
+ }
567
+ /**
568
+ * Update a managed section in a file.
569
+ *
570
+ * @param filePath - Absolute path to the target file.
571
+ * @param content - New content to write.
572
+ * @param options - Write mode and optional configuration.
573
+ */
574
+ declare function updateManagedSection(filePath: string, content: string, options?: UpdateManagedSectionOptions): Promise<void>;
575
+
576
+ /**
577
+ * Version-stamp parsing and convergence logic.
578
+ *
579
+ * @remarks
580
+ * When multiple component plugins bundle different core library versions,
581
+ * they independently maintain shared managed content. The version-stamp
582
+ * mechanism ensures convergence without coordination state.
583
+ */
584
+
585
+ /**
586
+ * Format the BEGIN marker comment with a version stamp.
587
+ *
588
+ * @param markerText - The marker text (e.g., 'BEGIN JEEVES PLATFORM TOOLS').
589
+ * @param version - The core library version.
590
+ * @returns Formatted comment line.
591
+ */
592
+ declare function formatBeginMarker(markerText: string, version: string): string;
593
+ /**
594
+ * Format the END marker comment.
595
+ *
596
+ * @param markerText - The marker text (e.g., 'END JEEVES PLATFORM TOOLS').
597
+ * @returns Formatted comment line.
598
+ */
599
+ declare function formatEndMarker(markerText: string): string;
600
+ /**
601
+ * Determine whether this writer should proceed based on version-stamp
602
+ * convergence rules.
603
+ *
604
+ * @param myVersion - The current core library version.
605
+ * @param existing - The existing version stamp (if any).
606
+ * @param stalenessThresholdMs - Staleness threshold in ms (default: 5 min).
607
+ * @returns `true` if the writer should proceed with the write.
608
+ */
609
+ declare function shouldWrite(myVersion: string, existing: VersionStamp | undefined, stalenessThresholdMs?: number): boolean;
610
+
611
+ /**
612
+ * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
613
+ *
614
+ * @remarks
615
+ * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
616
+ * Probes service ports for health, reads content files from the package's
617
+ * `content/` directory, renders the Platform template with live service data,
618
+ * and writes managed sections using `updateManagedSection`.
619
+ */
620
+ /** Options for refreshPlatformContent. */
621
+ interface RefreshPlatformContentOptions {
622
+ /** Core library version for version-stamp convergence. */
623
+ coreVersion: string;
624
+ /** Component name (for registry cache directory). */
625
+ componentName?: string;
626
+ /** Staleness threshold override in ms. */
627
+ stalenessThresholdMs?: number;
628
+ /** Timeout for health probes in ms. */
629
+ probeTimeoutMs?: number;
630
+ /** Skip registry version check (useful for testing). */
631
+ skipRegistryCheck?: boolean;
632
+ }
633
+ /**
634
+ * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
635
+ *
636
+ * @param options - Configuration for the refresh cycle.
637
+ */
638
+ declare function refreshPlatformContent(options: RefreshPlatformContentOptions): Promise<void>;
639
+
640
+ /**
641
+ * One-shot content seeding used by the CLI install command.
642
+ *
643
+ * @remarks
644
+ * Seeds SOUL.md, AGENTS.md, and TOOLS.md Platform section using the same
645
+ * `updateManagedSection()` code path as writer cycles. Also copies templates
646
+ * and creates core config with defaults if missing.
647
+ */
648
+ /** Options for seeding content. */
649
+ interface SeedContentOptions {
650
+ /** Core library version for version-stamp convergence. */
651
+ coreVersion: string;
652
+ /** Timeout for health probes in ms. */
653
+ probeTimeoutMs?: number;
654
+ /** Skip registry version check. */
655
+ skipRegistryCheck?: boolean;
656
+ }
657
+ /**
658
+ * Seed all platform content into the workspace.
659
+ *
660
+ * @remarks
661
+ * Uses the same `updateManagedSection()` code path as writer cycles.
662
+ * Creates core config with defaults if missing. Copies templates.
663
+ * Jaccard cleanup detection runs automatically via `updateManagedSection`.
664
+ *
665
+ * @param options - Seeding configuration.
666
+ */
667
+ declare function seedContent(options: SeedContentOptions): Promise<void>;
668
+
669
+ export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, checkRegistryVersion, coreConfigSchema, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, seedContent, shingles, shouldWrite, updateManagedSection };
670
+ export type { CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedSection, ParseManagedResult, PluginCommands, ProbeResult, RefreshPlatformContentOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, UpdateManagedSectionOptions, VersionStamp };