@karmaniverous/jeeves-meta 0.20.0-0 → 0.20.0-2

package/README.md

@@ -56,7 +56,7 @@ jeeves-meta service install --config /path/to/jeeves-meta/config.json
 
 | Method | Path | Description |
 | --- | --- | --- |
-| GET | `/status` | Service health, queue state, dependency checks, phase-state summary |
+| GET | `/status` | Service health, queue state, dependency checks, phase-state summary. Meta counts come from the last meta list (at most 60 s old, refreshed in the background), so the check never waits on a corpus walk. |
 | GET | `/metas` | List metas with summary stats and per-meta projection. Response includes `phaseState` and `owedPhase` per meta. |
 | GET | `/metas/:path` | Full detail for a single meta, with optional archive history. Response includes `phaseState`, `owedPhase` and `crossRefs`. |
 | GET | `/preview` | Dry-run: preview inputs for next synthesis |
@@ -71,7 +71,7 @@ jeeves-meta service install --config /path/to/jeeves-meta/config.json
 | PATCH | `/metas/:path` | Update user-settable reserved properties (`_steer`, `_emphasis`, `_depth`, `_crossRefs`, `_disabled`) |
 | GET | `/openapi.json` | The OpenAPI 3.1 document of every route above |
 
-Every route is defined in `META_CATALOG` (`@karmaniverous/jeeves-meta-core`) and validated against it: a malformed request is answered 400 `FST_ERR_VALIDATION`. Every route except `/config`, `/config/apply` and `/openapi.json` answers 503 `META_NOT_READY` while the service starts. Use [`@karmaniverous/jeeves-meta-sdk`](../sdk/README.md) for a typed client.
+Every route is defined in `META_CATALOG` (`@karmaniverous/jeeves-meta-core`) and validated against it: a malformed request is answered 400 `FST_ERR_VALIDATION`. While the service starts, `GET /status` answers 200 with `serviceState: "starting"` (no meta counts until the first meta list loads), `/config`, `/config/apply` and `/openapi.json` are served, and every other route answers 503 `META_NOT_READY`. Use [`@karmaniverous/jeeves-meta-sdk`](../sdk/README.md) for a typed client.
 
 ### Errors
 

package/dist/cli/jeeves-meta/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { sleepAsync, computeInsiderKey, fetchWithTimeout, DEFAULT_PORTS, createConfigQueryHandler, createStatusHandler, getBindAddress, getServiceUrl, jeevesComponentDescriptorSchema, createConfigApplyHandler, createServiceCli } from '@karmaniverous/jeeves';
+import { sleepAsync, computeInsiderKey, fetchWithTimeout, DEFAULT_PORTS, createConfigQueryHandler, createStatusHandler, getBindAddress, rejectWindowsDrivePath, init, WORKSPACE_CONFIG_DEFAULTS, resolveConfigValue, loadWorkspaceConfig, getServiceUrl, jeevesComponentDescriptorSchema, createConfigApplyHandler, createServiceCli } from '@karmaniverous/jeeves';
 import { normalizePath, metaConfigSchema, META_ERROR_STATUS, updateBodySchema, META_COMPONENT, META_CATALOG, META_OPENAPI_DOCUMENT } from '@karmaniverous/jeeves-meta-core';
 import fs, { unlinkSync, writeFileSync, existsSync, readFileSync, statSync, mkdirSync, readdirSync, watchFile } from 'node:fs';
 import path, { join, dirname, relative, posix, sep, resolve } from 'node:path';
@@ -657,7 +657,8 @@ function getDeltaFiles(generatedAt, scopeFiles) {
 }
 
 /**
- * In-memory cache for listMetas results with TTL and concurrent refresh guard.
+ * In-memory cache for listMetas results with TTL, concurrent refresh guard
+ * and a non-blocking read (`peek`) for health checks.
  *
  * @module cache
  */
@@ -677,6 +678,22 @@ class MetaCache {
         }
         return this.refresh(config, watcher);
     }
+    /**
+     * The cached result without waiting on a stale one: when it has expired,
+     * return it anyway and refresh in the background. Only the first load,
+     * with nothing cached yet, is awaited. For callers that must answer fast
+     * (`GET /status`), where a 60 s-old list is good enough.
+     */
+    async peek(config, watcher) {
+        if (!this.result)
+            return this.refresh(config, watcher);
+        if (Date.now() - this.updatedAt >= TTL_MS) {
+            // A failed background refresh keeps the old result; the next caller
+            // retries it.
+            this.refresh(config, watcher).catch(() => undefined);
+        }
+        return this.result;
+    }
     /** Force-expire the cache so next get() triggers a refresh. */
     invalidate() {
         this.updatedAt = 0;
@@ -31854,6 +31871,8 @@ async function checkWatcher(url) {
 function deriveServiceState(deps) {
     if (deps.shuttingDown)
         return 'stopping';
+    if (!deps.ready)
+        return 'starting';
     if (deps.queue.currentPhase)
         return 'synthesizing';
     if (deps.queue.depth > 0)
@@ -31888,41 +31907,47 @@ function createStatusHandlers(deps) {
             };
             let nextPhase = null;
             let metaCounts = null;
-            try {
-                const metaResult = await cache.get(config, watcher);
-                // Count raw phase states (before retry) for display
-                for (const entry of metaResult.entries) {
-                    const ps = derivePhaseState(entry.meta);
-                    for (const phase of ['architect', 'builder', 'critic']) {
-                        phaseStateSummary[phase][ps[phase]]++;
+            // While starting, the first meta list is still loading: report the
+            // state, dependencies and stats without it (Decision 199).
+            if (deps.ready) {
+                try {
+                    // Never wait on a refresh of the whole corpus: a health check answers
+                    // from the last list, refreshed in the background.
+                    const metaResult = await cache.peek(config, watcher);
+                    // Count raw phase states (before retry) for display
+                    for (const entry of metaResult.entries) {
+                        const ps = derivePhaseState(entry.meta);
+                        for (const phase of ['architect', 'builder', 'critic']) {
+                            phaseStateSummary[phase][ps[phase]]++;
+                        }
                     }
-                }
-                // Build candidates (with auto-retry) for scheduling
-                const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
-                // Find next phase candidate
-                const winner = selectPhaseCandidate(candidates, config.depthWeight);
-                if (winner) {
-                    nextPhase = {
-                        path: winner.node.metaPath,
-                        phase: winner.owedPhase,
-                        band: winner.band,
-                        staleness: finiteOrNull(winner.effectiveStaleness),
+                    // Build candidates (with auto-retry) for scheduling
+                    const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
+                    // Find next phase candidate
+                    const winner = selectPhaseCandidate(candidates, config.depthWeight);
+                    if (winner) {
+                        nextPhase = {
+                            path: winner.node.metaPath,
+                            phase: winner.owedPhase,
+                            band: winner.band,
+                            staleness: finiteOrNull(winner.effectiveStaleness),
+                        };
+                    }
+                    // Meta counts summary
+                    const summary = computeSummary(metaResult.entries, config.depthWeight);
+                    metaCounts = {
+                        total: summary.total,
+                        enabled: summary.total - summary.disabled,
+                        disabled: summary.disabled,
+                        neverSynthesized: summary.neverSynthesized,
+                        stale: summary.stale,
+                        errors: summary.errors,
+                        locked: summary.locked,
                     };
                 }
-                // Meta counts summary
-                const summary = computeSummary(metaResult.entries, config.depthWeight);
-                metaCounts = {
-                    total: summary.total,
-                    enabled: summary.total - summary.disabled,
-                    disabled: summary.disabled,
-                    neverSynthesized: summary.neverSynthesized,
-                    stale: summary.stale,
-                    errors: summary.errors,
-                    locked: summary.locked,
-                };
-            }
-            catch {
-                // Watcher unreachable — phase summary unavailable
+                catch {
+                    // Watcher unreachable — phase summary unavailable
+                }
             }
             return {
                 serviceState: deriveServiceState(deps),
@@ -32169,7 +32194,12 @@ function registerRoutes(app, deps) {
  * @module server
  */
 /** Routes served while the service is starting (matched route URLs). */
-const UNGATED_ROUTES = new Set(['/config', '/config/apply', '/openapi.json']);
+const UNGATED_ROUTES = new Set([
+    '/status',
+    '/config',
+    '/config/apply',
+    '/openapi.json',
+]);
 /**
  * Create and configure the Fastify server.
  *
@@ -32400,9 +32430,10 @@ async function startService(config, configPath, configApply) {
     queue.onEnqueue(() => {
         void queue.processQueue(synthesizeFn);
     });
-    // Startup: clean stale locks (gap #16)
+    // Startup: clean stale locks (gap #16). Through the cache, so the first
+    // GET /status after start-up answers without a second walk.
     try {
-        const metaResult = await listMetas(config, watcher);
+        const metaResult = await cache.get(config, watcher);
         const metaPaths = metaResult.entries.map((e) => e.node.metaPath);
         cleanupStaleLocks(metaPaths, logger);
     }
@@ -32742,11 +32773,61 @@ function createMetaClient(options) {
     return Object.fromEntries(methods);
 }
 
+/**
+ * Workspace and config root for the custom CLI commands, so they can ask
+ * jeeves where meta runs (`getServiceUrl('meta')`, which reads the core
+ * config under the config root).
+ *
+ * Each root follows jeeves' shared precedence: the flag, then
+ * `JEEVES_WORKSPACE` / `JEEVES_CONFIG_ROOT`, then `core.*` in the
+ * workspace's `jeeves.config.json`, then the defaults (`.`, `./config`).
+ * jeeves does not export its own resolver, so this composes the exported
+ * `loadWorkspaceConfig()` and `resolveConfigValue()` as jeeves-runner does;
+ * karmaniverous/jeeves#169 moves this into jeeves.
+ *
+ * @module cliRoots
+ */
+/**
+ * Resolve the workspace and config root by flag, env,
+ * `jeeves.config.json`, then default.
+ *
+ * @param opts - The parsed flags.
+ * @param env - Environment to read (default `process.env`).
+ * @returns Both roots, as given (not yet made absolute).
+ */
+function resolveRoots(opts, env = process.env) {
+    const defaults = WORKSPACE_CONFIG_DEFAULTS.core;
+    const workspaceSeed = resolveConfigValue(opts.workspace, env['JEEVES_WORKSPACE'], undefined, defaults.workspace).value;
+    const file = loadWorkspaceConfig(workspaceSeed);
+    return {
+        workspace: resolveConfigValue(opts.workspace, env['JEEVES_WORKSPACE'], file?.core?.workspace, defaults.workspace).value,
+        configRoot: resolveConfigValue(opts.configRoot, env['JEEVES_CONFIG_ROOT'], file?.core?.configRoot, defaults.configRoot).value,
+    };
+}
+/**
+ * Resolve both roots and initialise jeeves with them.
+ *
+ * @param opts - The parsed flags.
+ * @param env - Environment to read (default `process.env`).
+ */
+function initRoots(opts, env = process.env) {
+    const roots = resolveRoots(opts, env);
+    // Check the raw values: on Linux, resolve('j:/x') hides the drive letter.
+    rejectWindowsDrivePath('configRoot', roots.configRoot);
+    rejectWindowsDrivePath('workspacePath', roots.workspace);
+    init({
+        workspacePath: resolve(roots.workspace),
+        configRoot: resolve(roots.configRoot),
+    });
+}
+
 /**
  * Custom CLI commands for the jeeves-meta service, built on the SDK
  * (`@karmaniverous/jeeves-meta-sdk`, Decision 187). Each command calls one
  * catalog entry and prints the response as JSON; a failure prints one
- * error line to stderr and sets exit code 1.
+ * error line to stderr and sets exit code 1. The service URL comes from
+ * jeeves (`getServiceUrl('meta')`) after the workspace and config root are
+ * resolved (`cliRoots`); `--port` overrides its port.
  *
  * Registered via `descriptor.customCliCommands` and added to the
  * standard service CLI produced by `createServiceCli`.
@@ -32754,15 +32835,17 @@ function createMetaClient(options) {
  * @module customCliCommands
  */
 /**
- * The service's base URL on the given port.
+ * The service's base URL: jeeves' URL for meta, with `--port` when it is
+ * not the default.
  *
- * @param port - Port string from `--port`.
+ * @param opts - The command's options.
  * @returns The base URL.
  */
-function serviceBaseUrl(port) {
+function serviceBaseUrl(opts) {
+    initRoots(opts);
     const url = new URL(getServiceUrl('meta'));
-    if (port !== DEFAULT_PORT_STR)
-        url.port = port;
+    if (opts.port !== DEFAULT_PORT_STR)
+        url.port = opts.port;
     return url.origin;
 }
 /**
@@ -32781,12 +32864,12 @@ function errorLine(error) {
  * Run one command: call the service, print the result as JSON, or print
  * the error line and set exit code 1.
  *
- * @param port - Port string from `--port`.
+ * @param opts - The command's options.
  * @param call - The SDK call.
  */
-async function runCommand(port, call) {
+async function runCommand(opts, call) {
     try {
-        const data = await call(createMetaClient({ baseUrl: serviceBaseUrl(port) }));
+        const data = await call(createMetaClient({ baseUrl: serviceBaseUrl(opts) }));
         console.log(JSON.stringify(data, null, 2));
     }
     catch (error) {
@@ -32794,27 +32877,38 @@ async function runCommand(port, call) {
         process.exitCode = 1;
     }
 }
+/**
+ * Add the options every service command takes: `--port`, and the roots
+ * jeeves resolves the service URL from (no defaults, so the environment and
+ * `jeeves.config.json` apply when a flag is absent).
+ *
+ * @param cmd - The command.
+ * @returns It.
+ */
+function withServiceOptions(cmd) {
+    return cmd
+        .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('--config-root <path>', 'Platform config root path');
+}
 /**
  * Register all custom meta commands on the parent program.
  *
  * @param program - The service CLI.
  */
 function registerCustomCliCommands(program) {
-    const command = (spec, description) => program
-        .command(spec)
-        .description(description)
-        .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR);
-    command('list', 'List all discovered meta entities').action((opts) => runCommand(opts.port, (meta) => meta.listMetas()));
-    command('detail <path>', 'Show full detail for a single meta entity').action((path, opts) => runCommand(opts.port, (meta) => meta.metaDetail({ path })));
+    const command = (spec, description) => withServiceOptions(program.command(spec).description(description));
+    command('list', 'List all discovered meta entities').action((opts) => runCommand(opts, (meta) => meta.listMetas()));
+    command('detail <path>', 'Show full detail for a single meta entity').action((path, opts) => runCommand(opts, (meta) => meta.metaDetail({ path })));
     command('preview', 'Dry-run: preview inputs for next synthesis cycle')
         .option('--path <path>', 'Specific meta path to preview')
-        .action((opts) => runCommand(opts.port, (meta) => meta.preview(opts.path ? { path: opts.path } : {})));
+        .action((opts) => runCommand(opts, (meta) => meta.preview(opts.path ? { path: opts.path } : {})));
     command('synthesize', 'Trigger synthesis (enqueues work)')
         .option('--path <path>', 'Specific meta path to synthesize')
-        .action((opts) => runCommand(opts.port, (meta) => meta.synthesize(opts.path ? { path: opts.path } : {})));
-    command('seed <path>', 'Create .meta/ directory + meta.json for a path').action((path, opts) => runCommand(opts.port, (meta) => meta.seed({ path })));
-    command('unlock <path>', 'Remove .lock file from a meta entity').action((path, opts) => runCommand(opts.port, (meta) => meta.unlock({ path })));
-    command('abort', 'Abort the current synthesis in progress').action((opts) => runCommand(opts.port, (meta) => meta.abort()));
+        .action((opts) => runCommand(opts, (meta) => meta.synthesize(opts.path ? { path: opts.path } : {})));
+    command('seed <path>', 'Create .meta/ directory + meta.json for a path').action((path, opts) => runCommand(opts, (meta) => meta.seed({ path })));
+    command('unlock <path>', 'Remove .lock file from a meta entity').action((path, opts) => runCommand(opts, (meta) => meta.unlock({ path })));
+    command('abort', 'Abort the current synthesis in progress').action((opts) => runCommand(opts, (meta) => meta.abort()));
     command('prune', 'Prune old archive snapshots beyond maxArchive').action(() => {
         // The service has no prune route yet (jeeves-meta#69); 0.19.0 called a
         // missing route and failed with HTTP 404.
@@ -32824,16 +32918,9 @@ function registerCustomCliCommands(program) {
     const queue = program
         .command('queue')
         .description('Queue management commands');
-    queue
-        .command('list')
-        .description('Show current queue state')
-        .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
-        .action((opts) => runCommand(opts.port, (meta) => meta.queue()));
-    queue
-        .command('clear')
-        .description('Remove all pending items from the queue')
-        .option('-p, --port <port>', 'Service port', DEFAULT_PORT_STR)
-        .action((opts) => runCommand(opts.port, (meta) => meta.queueClear()));
+    const queueCommand = (name, description) => withServiceOptions(queue.command(name).description(description));
+    queueCommand('list', 'Show current queue state').action((opts) => runCommand(opts, (meta) => meta.queue()));
+    queueCommand('clear', 'Remove all pending items from the queue').action((opts) => runCommand(opts, (meta) => meta.queueClear()));
 }
 
 /**

package/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@karmaniverous/jeeves": "0.11.0",
-    "@karmaniverous/jeeves-meta-core": "^0.4.0-0",
+    "@karmaniverous/jeeves-meta-core": "^0.4.0-1",
     "@karmaniverous/jeeves-meta-sdk": "^0.0.0 || ^0.1.0-0",
     "@karmaniverous/jeeves-watcher-sdk": "^0.4.1",
     "commander": "^15",
@@ -112,5 +112,5 @@
     "wire:record": "vitest run --config vitest.wire-record.config.ts"
   },
   "type": "module",
-  "version": "0.20.0-0"
+  "version": "0.20.0-2"
 }