@karmaniverous/jeeves 0.1.0 → 0.1.2

package/dist/cli/jeeves/index.js

@@ -2,10 +2,11 @@
 #!/usr/bin/env node
 import require$$0 from 'commander';
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { z } from 'zod';
 import { fileURLToPath } from 'node:url';
+import { packageDirectorySync } from 'package-directory';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, cpSync, rmSync } from 'node:fs';
+import { z } from 'zod';
 import Handlebars from 'handlebars';
 import { execSync } from 'node:child_process';
 import { lock } from 'proper-lockfile';
@@ -203,9 +204,16 @@ const SECTION_ORDER = [
  * Used for version-stamp convergence (Decision 21). The version stamp
  * on managed content reflects the actual published library version,
  * enabling higher-version writers to take precedence.
+ *
+ * Uses `package-directory` to locate the package root regardless of
+ * whether this code runs from `src/constants/` (dev) or `dist/` (bundled).
  */
+const pkgDir = packageDirectorySync({ cwd: fileURLToPath(import.meta.url) });
+if (!pkgDir) {
+    throw new Error('Could not find package root from ' + fileURLToPath(import.meta.url));
+}
 const require$1 = createRequire(import.meta.url);
-const pkg = require$1('../../package.json');
+const pkg = require$1(join(pkgDir, 'package.json'));
 /** The core library version from package.json. */
 const CORE_VERSION = pkg.version;
 
@@ -912,13 +920,22 @@ async function updateManagedSection(filePath, content, options = {}) {
 /**
  * Resolve the package's content directory.
  *
+ * @remarks
+ * Uses `package-directory` to locate the package root regardless of
+ * whether this code runs from `src/platform/` (dev) or `dist/` (bundled).
+ * Rollup flattens all source into `dist/index.js`, so static relative
+ * paths like `../../content/` break when consumed as a dependency.
+ *
  * @returns Absolute path to the content/ directory.
  */
 function getContentDir() {
-    const thisFile = fileURLToPath(import.meta.url);
-    // From src/platform/refreshPlatformContent.ts → ../../content/
-    // From dist/platform/refreshPlatformContent.js → ../../content/
-    return join(dirname(thisFile), '..', '..', 'content');
+    const pkgDir = packageDirectorySync({
+        cwd: fileURLToPath(import.meta.url),
+    });
+    if (!pkgDir) {
+        throw new Error('Could not find package root from ' + fileURLToPath(import.meta.url));
+    }
+    return join(pkgDir, 'content');
 }
 /**
  * Read a content file from the package's content/ directory.

package/dist/index.d.ts

@@ -100,6 +100,63 @@ declare class ComponentWriter {
     cycle(): Promise<void>;
 }
 
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @remarks
+ * Solves the sync/async gap in `JeevesComponent.generateToolsContent()`:
+ * the interface is synchronous, but most components fetch live data from
+ * their HTTP service. This utility returns a sync `() => string` that
+ * serves the last successfully fetched value while kicking off a background
+ * refresh on each call.
+ *
+ * First call returns `placeholder`. Subsequent calls return the last
+ * successfully fetched content. If a refresh fails, the previous good
+ * value is retained.
+ *
+ * @example
+ * ```typescript
+ * const getContent = createAsyncContentCache({
+ *   fetch: async () => {
+ *     const res = await fetch('http://127.0.0.1:1936/status');
+ *     return formatWatcherStatus(await res.json());
+ *   },
+ *   placeholder: '> Initializing watcher status...',
+ * });
+ *
+ * const writer = createComponentWriter({
+ *   // ...
+ *   generateToolsContent: getContent,
+ * });
+ * ```
+ */
+/** Options for {@link createAsyncContentCache}. */
+interface AsyncContentCacheOptions {
+    /**
+     * Async function that fetches fresh content.
+     * Errors are caught and logged; the previous value is retained.
+     */
+    fetch: () => Promise<string>;
+    /**
+     * Content returned before the first successful fetch.
+     *
+     * @defaultValue `'> Initializing...'`
+     */
+    placeholder?: string;
+    /**
+     * Optional error handler. Called when `fetch` throws.
+     * Defaults to `console.warn`.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
+ */
+declare function createAsyncContentCache(options: AsyncContentCacheOptions): () => string;
+
 /**
  * Factory function for creating a ComponentWriter.
  *
@@ -250,6 +307,9 @@ declare const SECTION_ORDER: readonly string[];
  * Used for version-stamp convergence (Decision 21). The version stamp
  * on managed content reflects the actual published library version,
  * enabling higher-version writers to take precedence.
+ *
+ * Uses `package-directory` to locate the package root regardless of
+ * whether this code runs from `src/constants/` (dev) or `dist/` (bundled).
  */
 /** The core library version from package.json. */
 declare const CORE_VERSION: string;
@@ -666,5 +726,5 @@ interface SeedContentOptions {
  */
 declare function seedContent(options: SeedContentOptions): Promise<void>;
 
-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 };
-export type { CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedSection, ParseManagedResult, PluginCommands, ProbeResult, RefreshPlatformContentOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, UpdateManagedSectionOptions, VersionStamp };
+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, createAsyncContentCache, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, seedContent, shingles, shouldWrite, updateManagedSection };
+export type { AsyncContentCacheOptions, CoreConfig, CreateComponentWriterOptions, InitOptions, JeevesComponent, ManagedSection, ParseManagedResult, PluginCommands, ProbeResult, RefreshPlatformContentOptions, SectionId, SeedContentOptions, ServiceCommands, ServiceStatus, UpdateManagedSectionOptions, VersionStamp };

package/dist/index.js

@@ -1,9 +1,10 @@
 import { join, dirname } from 'node:path';
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { packageDirectorySync } from 'package-directory';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, renameSync, cpSync } from 'node:fs';
 import { lock } from 'proper-lockfile';
 import { gte } from 'semver';
-import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
@@ -141,9 +142,16 @@ const SECTION_ORDER = [
  * Used for version-stamp convergence (Decision 21). The version stamp
  * on managed content reflects the actual published library version,
  * enabling higher-version writers to take precedence.
+ *
+ * Uses `package-directory` to locate the package root regardless of
+ * whether this code runs from `src/constants/` (dev) or `dist/` (bundled).
  */
+const pkgDir = packageDirectorySync({ cwd: fileURLToPath(import.meta.url) });
+if (!pkgDir) {
+    throw new Error('Could not find package root from ' + fileURLToPath(import.meta.url));
+}
 const require$1 = createRequire(import.meta.url);
-const pkg = require$1('../../package.json');
+const pkg = require$1(join(pkgDir, 'package.json'));
 /** The core library version from package.json. */
 const CORE_VERSION = pkg.version;
 
@@ -884,13 +892,22 @@ function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
 /**
  * Resolve the package's content directory.
  *
+ * @remarks
+ * Uses `package-directory` to locate the package root regardless of
+ * whether this code runs from `src/platform/` (dev) or `dist/` (bundled).
+ * Rollup flattens all source into `dist/index.js`, so static relative
+ * paths like `../../content/` break when consumed as a dependency.
+ *
  * @returns Absolute path to the content/ directory.
  */
 function getContentDir() {
-    const thisFile = fileURLToPath(import.meta.url);
-    // From src/platform/refreshPlatformContent.ts → ../../content/
-    // From dist/platform/refreshPlatformContent.js → ../../content/
-    return join(dirname(thisFile), '..', '..', 'content');
+    const pkgDir = packageDirectorySync({
+        cwd: fileURLToPath(import.meta.url),
+    });
+    if (!pkgDir) {
+        throw new Error('Could not find package root from ' + fileURLToPath(import.meta.url));
+    }
+    return join(pkgDir, 'content');
 }
 /**
  * Read a content file from the package's content/ directory.
@@ -1098,6 +1115,64 @@ class ComponentWriter {
     }
 }
 
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @remarks
+ * Solves the sync/async gap in `JeevesComponent.generateToolsContent()`:
+ * the interface is synchronous, but most components fetch live data from
+ * their HTTP service. This utility returns a sync `() => string` that
+ * serves the last successfully fetched value while kicking off a background
+ * refresh on each call.
+ *
+ * First call returns `placeholder`. Subsequent calls return the last
+ * successfully fetched content. If a refresh fails, the previous good
+ * value is retained.
+ *
+ * @example
+ * ```typescript
+ * const getContent = createAsyncContentCache({
+ *   fetch: async () => {
+ *     const res = await fetch('http://127.0.0.1:1936/status');
+ *     return formatWatcherStatus(await res.json());
+ *   },
+ *   placeholder: '> Initializing watcher status...',
+ * });
+ *
+ * const writer = createComponentWriter({
+ *   // ...
+ *   generateToolsContent: getContent,
+ * });
+ * ```
+ */
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
+ */
+function createAsyncContentCache(options) {
+    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
+        console.warn('[jeeves] async content cache refresh failed:', err);
+    }, } = options;
+    let cached = placeholder;
+    let refreshing = false;
+    return () => {
+        if (!refreshing) {
+            refreshing = true;
+            fetchContent()
+                .then((content) => {
+                cached = content;
+            })
+                .catch(onError)
+                .finally(() => {
+                refreshing = false;
+            });
+        }
+        return cached;
+    };
+}
+
 /**
  * Factory function for creating a ComponentWriter.
  *
@@ -1229,4 +1304,4 @@ async function seedContent(options) {
     });
 }
 
-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 };
+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, createAsyncContentCache, createComponentWriter, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, parseManaged, probeAllServices, probeService, refreshPlatformContent, resetInit, seedContent, shingles, shouldWrite, updateManagedSection };

package/package.json

@@ -15,6 +15,7 @@
   "dependencies": {
     "commander": "^14.0.2",
     "handlebars": "^4.7.8",
+    "package-directory": "^8.2.0",
     "proper-lockfile": "^4.1.2",
     "semver": "^7.7.2",
     "zod": "^3.25.67"
@@ -137,5 +138,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.1.0"
+  "version": "0.1.2"
 }