@karmaniverous/jeeves-meta 0.10.1 → 0.11.1

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

@@ -46,11 +46,11 @@ const metaConfigSchema = z.object({
     /** Maximum lines of context to include in subprocess prompts. */
     maxLines: z.number().int().min(50).default(500),
     /** Architect subprocess timeout in seconds. */
-    architectTimeout: z.number().int().min(30).default(120),
+    architectTimeout: z.number().int().min(30).default(180),
     /** Builder subprocess timeout in seconds. */
-    builderTimeout: z.number().int().min(60).default(600),
+    builderTimeout: z.number().int().min(60).default(360),
     /** Critic subprocess timeout in seconds. */
-    criticTimeout: z.number().int().min(30).default(300),
+    criticTimeout: z.number().int().min(30).default(240),
     /** Thinking level for spawned synthesis sessions. */
     thinking: z.string().default('low'),
     /** Resolved architect system prompt text. Falls back to built-in default. */
@@ -834,6 +834,26 @@ async function listMetas(config, watcher) {
     };
 }
 
+/**
+ * Escape special glob characters in a path so it can be used as a literal
+ * prefix in glob patterns.
+ *
+ * Glob metacharacters `* ? [ ] { } ( ) !` are escaped with a backslash so
+ * that paths containing parentheses (e.g. Slack channel IDs) or other
+ * special characters are matched literally by the watcher's walk endpoint.
+ *
+ * @module escapeGlob
+ */
+/**
+ * Escape glob metacharacters in a string.
+ *
+ * @param s - Raw path string.
+ * @returns String with glob metacharacters backslash-escaped.
+ */
+function escapeGlob(s) {
+    return s.replace(/[*?[\]{}()!]/g, '\\$&');
+}
+
 /**
  * Filter file paths by modification time.
  *
@@ -934,7 +954,7 @@ function filterInScope(node, files) {
  */
 async function getScopeFiles(node, watcher, logger) {
     const walkStart = Date.now();
-    const rawFiles = await watcher.walk([`${node.ownerPath}/**`]);
+    const rawFiles = await watcher.walk([`${escapeGlob(node.ownerPath)}/**`]);
     const allFiles = rawFiles.map(normalizePath);
     const scopeFiles = filterInScope(node, allFiles);
     logger?.debug({
@@ -1746,7 +1766,7 @@ async function buildMinimalNode(metaPath, watcher) {
     // We include only *direct* children (nearest descendants in the ownership tree)
     // to match the ownership semantics used elsewhere.
     const rawMetaJsonPaths = await watcher.walk([
-        `${ownerPath}/**/.meta/meta.json`,
+        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
     ]);
     const candidateMetaPaths = [
         ...new Set(rawMetaJsonPaths.map((p) => normalizePath(dirname(p)))),
@@ -1882,7 +1902,7 @@ function discoverStalestPath(candidates, depthWeight) {
 async function isStale(scopePrefix, meta, watcher) {
     if (!meta._generatedAt)
         return true; // Never synthesized = stale
-    const files = await watcher.walk([`${scopePrefix}/**`]);
+    const files = await watcher.walk([`${escapeGlob(scopePrefix)}/**`]);
     return hasModifiedAfter(files, new Date(meta._generatedAt).getTime());
 }
 /** Maximum staleness for never-synthesized metas (1 year in seconds). */
@@ -2151,6 +2171,25 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
     const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
     // Step 7: Compute context (includes scope files and delta files)
     const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
+    // Skip empty-scope entities that have no prior content.
+    // Without scope files, child metas, or cross-refs there is nothing for
+    // the architect/builder to work with and the cycle will either time out
+    // or produce empty output.
+    const hasScope = ctx.scopeFiles.length > 0 ||
+        Object.keys(ctx.childMetas).length > 0 ||
+        Object.keys(ctx.crossRefMetas).length > 0;
+    if (!hasScope && !currentMeta._content) {
+        // Bump _generatedAt so this entity doesn't keep winning the staleness
+        // race every cycle. It will be re-evaluated when files appear.
+        // Uses lock-staging for atomic write consistency.
+        currentMeta._generatedAt = new Date().toISOString();
+        const lockPath = join(node.metaPath, '.lock');
+        const metaJsonPath = join(node.metaPath, 'meta.json');
+        await writeFile(lockPath, JSON.stringify(currentMeta, null, 2));
+        await copyFile(lockPath, metaJsonPath);
+        logger?.debug({ path: node.ownerPath }, 'Skipping empty-scope entity');
+        return { synthesized: false };
+    }
     // Step 5 (deferred): Structure hash from context scope files
     const newStructureHash = computeStructureHash(ctx.scopeFiles);
     const structureChanged = newStructureHash !== currentMeta._structureHash;
@@ -2447,21 +2486,41 @@ function formatSeconds(durationMs) {
 function titleCasePhase(phase) {
     return phase.charAt(0).toUpperCase() + phase.slice(1);
 }
-/** Build a link to the entity's meta.json output file. */
-function buildEntityLink(path, serverBaseUrl) {
-    // Normalize backslashes, then convert drive letter to URL path segment
+/**
+ * URL-encode each path segment individually so that spaces and special
+ * characters are safe while preserving the `/` separators.
+ */
+function encodePathSegments(p) {
+    return p
+        .split('/')
+        .map((seg) => encodeURIComponent(seg))
+        .join('/');
+}
+/** Build a link (or plain path) to the owner directory. */
+function buildDirectoryLink(path, serverBaseUrl) {
+    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
+    const encoded = encodePathSegments(normalized);
+    if (!serverBaseUrl)
+        return normalized;
+    const base = serverBaseUrl.replace(/\/+$/, '');
+    return `${base}/path${encoded}`;
+}
+/** Build a link (or plain path) to the entity's meta.json output file. */
+function buildMetaJsonLink(path, serverBaseUrl) {
     const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
     const metaJsonPath = `${normalized}/.meta/meta.json`;
+    const encoded = encodePathSegments(metaJsonPath);
     if (!serverBaseUrl)
         return metaJsonPath;
     const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${metaJsonPath}`;
+    return `${base}/path${encoded}`;
 }
 function formatProgressEvent(event, serverBaseUrl) {
-    const pathDisplay = buildEntityLink(event.path, serverBaseUrl);
     switch (event.type) {
-        case 'synthesis_start':
-            return `🔬 Started meta synthesis: ${pathDisplay}`;
+        case 'synthesis_start': {
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            return `🔬 Started meta synthesis: ${dirLink}`;
+        }
         case 'phase_start': {
             if (!event.phase) {
                 return '  ⚙️ Phase started';
@@ -2475,16 +2534,18 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `  ✅ ${phase} complete (${formatNumber(tokens)} tokens / ${duration})`;
         }
         case 'synthesis_complete': {
+            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl);
             const tokens = event.tokens ?? 0;
             const duration = event.durationMs !== undefined
                 ? formatSeconds(event.durationMs)
                 : '0.0s';
-            return `✅ Completed: ${pathDisplay} (${formatNumber(tokens)} tokens / ${duration})`;
+            return `✅ Completed: ${metaLink} (${formatNumber(tokens)} tokens / ${duration})`;
         }
         case 'error': {
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
             const phase = event.phase ? `${titleCasePhase(event.phase)} ` : '';
             const error = event.error ?? 'Unknown error';
-            return `❌ Synthesis failed at ${phase}phase: ${pathDisplay}\n   Error: ${error}`;
+            return `❌ Synthesis failed at ${phase}phase: ${dirLink}\n   Error: ${error}`;
         }
         default: {
             return 'Unknown progress event';
@@ -11078,6 +11139,11 @@ async function startService(config, configPath) {
             // orchestrate() always returns exactly one result
             const result = results[0];
             const durationMs = Date.now() - startMs;
+            if (!result.synthesized) {
+                // Entity was skipped (e.g. empty scope) — no progress to report.
+                logger.debug({ path: ownerPath }, 'Synthesis skipped');
+                return;
+            }
             // Update stats
             stats.totalSyntheses++;
             stats.lastCycleDurationMs = durationMs;
@@ -11087,6 +11153,7 @@ async function startService(config, configPath) {
                 await progress.report({
                     type: 'error',
                     path: ownerPath,
+                    phase: result.error.step,
                     error: result.error.message,
                 });
             }

package/dist/index.js

@@ -254,11 +254,11 @@ const metaConfigSchema = z.object({
     /** Maximum lines of context to include in subprocess prompts. */
     maxLines: z.number().int().min(50).default(500),
     /** Architect subprocess timeout in seconds. */
-    architectTimeout: z.number().int().min(30).default(120),
+    architectTimeout: z.number().int().min(30).default(180),
     /** Builder subprocess timeout in seconds. */
-    builderTimeout: z.number().int().min(60).default(600),
+    builderTimeout: z.number().int().min(60).default(360),
     /** Critic subprocess timeout in seconds. */
-    criticTimeout: z.number().int().min(30).default(300),
+    criticTimeout: z.number().int().min(30).default(240),
     /** Thinking level for spawned synthesis sessions. */
     thinking: z.string().default('low'),
     /** Resolved architect system prompt text. Falls back to built-in default. */
@@ -826,6 +826,26 @@ async function listMetas(config, watcher) {
     };
 }
 
+/**
+ * Escape special glob characters in a path so it can be used as a literal
+ * prefix in glob patterns.
+ *
+ * Glob metacharacters `* ? [ ] { } ( ) !` are escaped with a backslash so
+ * that paths containing parentheses (e.g. Slack channel IDs) or other
+ * special characters are matched literally by the watcher's walk endpoint.
+ *
+ * @module escapeGlob
+ */
+/**
+ * Escape glob metacharacters in a string.
+ *
+ * @param s - Raw path string.
+ * @returns String with glob metacharacters backslash-escaped.
+ */
+function escapeGlob(s) {
+    return s.replace(/[*?[\]{}()!]/g, '\\$&');
+}
+
 /**
  * Filter file paths by modification time.
  *
@@ -926,7 +946,7 @@ function filterInScope(node, files) {
  */
 async function getScopeFiles(node, watcher, logger) {
     const walkStart = Date.now();
-    const rawFiles = await watcher.walk([`${node.ownerPath}/**`]);
+    const rawFiles = await watcher.walk([`${escapeGlob(node.ownerPath)}/**`]);
     const allFiles = rawFiles.map(normalizePath);
     const scopeFiles = filterInScope(node, allFiles);
     logger?.debug({
@@ -1738,7 +1758,7 @@ async function buildMinimalNode(metaPath, watcher) {
     // We include only *direct* children (nearest descendants in the ownership tree)
     // to match the ownership semantics used elsewhere.
     const rawMetaJsonPaths = await watcher.walk([
-        `${ownerPath}/**/.meta/meta.json`,
+        `${escapeGlob(ownerPath)}/**/.meta/meta.json`,
     ]);
     const candidateMetaPaths = [
         ...new Set(rawMetaJsonPaths.map((p) => normalizePath(dirname(p)))),
@@ -1874,7 +1894,7 @@ function discoverStalestPath(candidates, depthWeight) {
 async function isStale(scopePrefix, meta, watcher) {
     if (!meta._generatedAt)
         return true; // Never synthesized = stale
-    const files = await watcher.walk([`${scopePrefix}/**`]);
+    const files = await watcher.walk([`${escapeGlob(scopePrefix)}/**`]);
     return hasModifiedAfter(files, new Date(meta._generatedAt).getTime());
 }
 /** Maximum staleness for never-synthesized metas (1 year in seconds). */
@@ -2143,6 +2163,25 @@ async function synthesizeNode(node, currentMeta, config, executor, watcher, onPr
     const steerChanged = hasSteerChanged(currentMeta._steer, latestArchive?._steer, Boolean(latestArchive));
     // Step 7: Compute context (includes scope files and delta files)
     const ctx = await buildContextPackage(node, currentMeta, watcher, logger);
+    // Skip empty-scope entities that have no prior content.
+    // Without scope files, child metas, or cross-refs there is nothing for
+    // the architect/builder to work with and the cycle will either time out
+    // or produce empty output.
+    const hasScope = ctx.scopeFiles.length > 0 ||
+        Object.keys(ctx.childMetas).length > 0 ||
+        Object.keys(ctx.crossRefMetas).length > 0;
+    if (!hasScope && !currentMeta._content) {
+        // Bump _generatedAt so this entity doesn't keep winning the staleness
+        // race every cycle. It will be re-evaluated when files appear.
+        // Uses lock-staging for atomic write consistency.
+        currentMeta._generatedAt = new Date().toISOString();
+        const lockPath = join(node.metaPath, '.lock');
+        const metaJsonPath = join(node.metaPath, 'meta.json');
+        await writeFile(lockPath, JSON.stringify(currentMeta, null, 2));
+        await copyFile(lockPath, metaJsonPath);
+        logger?.debug({ path: node.ownerPath }, 'Skipping empty-scope entity');
+        return { synthesized: false };
+    }
     // Step 5 (deferred): Structure hash from context scope files
     const newStructureHash = computeStructureHash(ctx.scopeFiles);
     const structureChanged = newStructureHash !== currentMeta._structureHash;
@@ -2439,21 +2478,41 @@ function formatSeconds(durationMs) {
 function titleCasePhase(phase) {
     return phase.charAt(0).toUpperCase() + phase.slice(1);
 }
-/** Build a link to the entity's meta.json output file. */
-function buildEntityLink(path, serverBaseUrl) {
-    // Normalize backslashes, then convert drive letter to URL path segment
+/**
+ * URL-encode each path segment individually so that spaces and special
+ * characters are safe while preserving the `/` separators.
+ */
+function encodePathSegments(p) {
+    return p
+        .split('/')
+        .map((seg) => encodeURIComponent(seg))
+        .join('/');
+}
+/** Build a link (or plain path) to the owner directory. */
+function buildDirectoryLink(path, serverBaseUrl) {
+    const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
+    const encoded = encodePathSegments(normalized);
+    if (!serverBaseUrl)
+        return normalized;
+    const base = serverBaseUrl.replace(/\/+$/, '');
+    return `${base}/path${encoded}`;
+}
+/** Build a link (or plain path) to the entity's meta.json output file. */
+function buildMetaJsonLink(path, serverBaseUrl) {
     const normalized = normalizePath(path).replace(/^([A-Za-z]):/, '/$1');
     const metaJsonPath = `${normalized}/.meta/meta.json`;
+    const encoded = encodePathSegments(metaJsonPath);
     if (!serverBaseUrl)
         return metaJsonPath;
     const base = serverBaseUrl.replace(/\/+$/, '');
-    return `${base}/path${metaJsonPath}`;
+    return `${base}/path${encoded}`;
 }
 function formatProgressEvent(event, serverBaseUrl) {
-    const pathDisplay = buildEntityLink(event.path, serverBaseUrl);
     switch (event.type) {
-        case 'synthesis_start':
-            return `🔬 Started meta synthesis: ${pathDisplay}`;
+        case 'synthesis_start': {
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
+            return `🔬 Started meta synthesis: ${dirLink}`;
+        }
         case 'phase_start': {
             if (!event.phase) {
                 return '  ⚙️ Phase started';
@@ -2467,16 +2526,18 @@ function formatProgressEvent(event, serverBaseUrl) {
             return `  ✅ ${phase} complete (${formatNumber(tokens)} tokens / ${duration})`;
         }
         case 'synthesis_complete': {
+            const metaLink = buildMetaJsonLink(event.path, serverBaseUrl);
             const tokens = event.tokens ?? 0;
             const duration = event.durationMs !== undefined
                 ? formatSeconds(event.durationMs)
                 : '0.0s';
-            return `✅ Completed: ${pathDisplay} (${formatNumber(tokens)} tokens / ${duration})`;
+            return `✅ Completed: ${metaLink} (${formatNumber(tokens)} tokens / ${duration})`;
         }
         case 'error': {
+            const dirLink = buildDirectoryLink(event.path, serverBaseUrl);
             const phase = event.phase ? `${titleCasePhase(event.phase)} ` : '';
             const error = event.error ?? 'Unknown error';
-            return `❌ Synthesis failed at ${phase}phase: ${pathDisplay}\n   Error: ${error}`;
+            return `❌ Synthesis failed at ${phase}phase: ${dirLink}\n   Error: ${error}`;
         }
         default: {
             return 'Unknown progress event';
@@ -11070,6 +11131,11 @@ async function startService(config, configPath) {
             // orchestrate() always returns exactly one result
             const result = results[0];
             const durationMs = Date.now() - startMs;
+            if (!result.synthesized) {
+                // Entity was skipped (e.g. empty scope) — no progress to report.
+                logger.debug({ path: ownerPath }, 'Synthesis skipped');
+                return;
+            }
             // Update stats
             stats.totalSyntheses++;
             stats.lastCycleDurationMs = durationMs;
@@ -11079,6 +11145,7 @@ async function startService(config, configPath) {
                 await progress.report({
                     type: 'error',
                     path: ownerPath,
+                    phase: result.error.step,
                     error: result.error.message,
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "author": "Jason Williscroft",
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "license": "BSD-3-Clause",