@north-light/crouter 0.3.175 → 0.3.176

package/dist/daemon/api/handlers/reviews.js

@@ -7,70 +7,22 @@ import { isSafeNodeId, reviewResultPath } from '../../../core/canvas/paths.js';
 import { responsePath, reviewPath } from '../../../core/human/convention.js';
 import { ticketDir } from '../../../core/human/root.js';
 import { createReview } from '../../../core/review/birth.js';
-import { readAnchorBase, getReview, getReviewByBridge, listReviews } from '../../../core/review/store.js';
+import { readAnchorBase, getReviewByBridge, listReviews, requireVisibleReview } from '../../../core/review/store.js';
 import { ReviewOperationError } from '../../../core/review/types.js';
 import { cancelReview, submitReviewApproval } from '../../review/finish.js';
 import { toFeedbackResultDTO, toReviewDTO } from '../map.js';
+import { invalidRequest as rejectRequest, objectBody, optionalString, requireParam, requiredString, } from './validate.js';
 const REVIEW_STATES = new Set(['open', 'approved', 'canceled']);
 const CREATE_FIELDS = ['origin_kind', 'origin_node_id', 'file', 'idempotency_key', 'subtitle', 'output_path'];
 const CANCEL_FIELDS = ['reason', 'actor'];
 function invalidRequest(violations) {
-    throw new ApiError(400, 'invalid_request', 'review request is invalid', { violations });
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function objectBody(body, allowed, violations) {
-    if (!isRecord(body)) {
-        violations.push({ field: 'body', problem: 'must be an object', received: body });
-        return {};
-    }
-    for (const key of Object.keys(body)) {
-        if (!allowed.includes(key))
-            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
-    }
-    return body;
-}
-function requiredString(body, field, violations) {
-    const value = body[field];
-    if (typeof value !== 'string' || value === '') {
-        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
-        return undefined;
-    }
-    return value;
-}
-function optionalString(body, field, violations) {
-    const value = body[field];
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'string' || value === '') {
-        violations.push({ field, problem: 'must be a non-empty string', received: value });
-        return undefined;
-    }
-    return value;
+    rejectRequest('review request', violations);
 }
 function requireReviewId(ctx, violations) {
-    const reviewId = ctx.params['review_id'];
-    if (reviewId === undefined || !isSafeNodeId(reviewId)) {
-        violations.push({ field: 'review_id', problem: 'must be a safe review id', ...(reviewId === undefined ? {} : { received: reviewId }) });
-        return undefined;
-    }
-    return reviewId;
+    return requireParam(ctx, 'review_id', 'must be a safe review id', isSafeNodeId, violations);
 }
 function requireBridgeNodeId(ctx, violations) {
-    const bridgeNodeId = ctx.params['bridge_node_id'];
-    if (bridgeNodeId === undefined || !isSafeNodeId(bridgeNodeId)) {
-        violations.push({ field: 'bridge_node_id', problem: 'must be a safe node id', ...(bridgeNodeId === undefined ? {} : { received: bridgeNodeId }) });
-        return undefined;
-    }
-    return bridgeNodeId;
-}
-function requireVisibleReview(reviewId) {
-    const review = getReview(reviewId);
-    if (review === null || review.state === 'binding') {
-        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
-    }
-    return review;
+    return requireParam(ctx, 'bridge_node_id', 'must be a safe node id', isSafeNodeId, violations);
 }
 function approvedResultPath(review) {
     if (review.origin_kind === 'inline')

package/dist/daemon/api/handlers/validate.d.ts

@@ -0,0 +1,22 @@
+import type { RequestContext } from '../router.js';
+export type Violation = {
+    field: string;
+    problem: string;
+    received?: unknown;
+};
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export declare function invalidRequest(subject: string, violations: Violation[]): never;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export declare function objectBody(body: unknown, allowed: readonly string[], violations: Violation[]): Record<string, unknown>;
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export declare function requiredString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** `requiredString`'s rule when present; absence is allowed. */
+export declare function optionalString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export declare function requireParam(ctx: RequestContext, field: string, problem: string, accepts: (value: string) => boolean, violations: Violation[]): string | undefined;

package/dist/daemon/api/handlers/validate.js

@@ -0,0 +1,59 @@
+// Shared wire-request validation for the daemon's `/v1` handlers.
+//
+// A handler collects `Violation`s while parsing a request, then calls
+// `invalidRequest` once so a caller sees every problem with its body in a
+// single 400 rather than one per round trip.
+import { ApiError } from '../../../api/index.js';
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export function invalidRequest(subject, violations) {
+    throw new ApiError(400, 'invalid_request', `${subject} is invalid`, { violations });
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export function objectBody(body, allowed, violations) {
+    if (!isRecord(body)) {
+        violations.push({ field: 'body', problem: 'must be an object', received: body });
+        return {};
+    }
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
+    }
+    return body;
+}
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export function requiredString(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+/** `requiredString`'s rule when present; absence is allowed. */
+export function optionalString(body, field, violations) {
+    const value = body[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', received: value });
+        return undefined;
+    }
+    return value;
+}
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export function requireParam(ctx, field, problem, accepts, violations) {
+    const value = ctx.params[field];
+    if (value === undefined || !accepts(value)) {
+        violations.push({ field, problem, ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}

package/dist/daemon/api/map.js

@@ -259,6 +259,7 @@ export function toProfileDTO(entry) {
         id: entry.profileId,
         name: entry.manifest.name,
         projects: [...entry.manifest.projects],
+        home: entry.manifest.home,
         default_dir: null,
     };
 }

package/dist/daemon/review/finish.js

@@ -8,7 +8,7 @@ import { reviewResultPath } from '../../core/canvas/paths.js';
 import { snapshotCommentsLocked } from '../../core/review/comments.js';
 import { readReviewSource } from '../../core/review/document.js';
 import { signalReviewActivity } from '../../core/review/signal.js';
-import { approveReviewLocked, cancelReviewRow, getReview, markDelivered, markDeliveryError, markProjected, markProjectionError, } from '../../core/review/store.js';
+import { approveReviewLocked, cancelReviewRow, markDelivered, markDeliveryError, markProjected, markProjectionError, requireVisibleReview, } from '../../core/review/store.js';
 import { ReviewOperationError } from '../../core/review/types.js';
 import { transition } from '../../core/runtime/lifecycle.js';
 import { headlessBrokerHost } from '../../core/runtime/host.js';
@@ -22,15 +22,6 @@ function now() {
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function unknownReview(reviewId) {
-    throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
-}
-function requireVisibleReview(reviewId) {
-    const review = getReview(reviewId);
-    if (review === null || review.state === 'binding')
-        return unknownReview(reviewId);
-    return review;
-}
 function terminalConflict(review, requested) {
     throw new ReviewOperationError('review_terminal', 'review already has a terminal outcome', {
         state: review.state,

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -34,7 +34,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
-import { renderOnReadDocsForSubject } from '../core/substrate/on-read-pure.js';
+import { renderOnReadDocsForSubject } from '../core/substrate/on-read.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
 import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';

package/dist/pi-extensions/canvas-preview-result.d.ts

@@ -0,0 +1,22 @@
+interface ToolCallEvent {
+    toolName: string;
+    toolCallId: string;
+    input: {
+        command?: string;
+    };
+}
+interface ToolResultEvent {
+    toolName: string;
+    toolCallId: string;
+    details?: Record<string, unknown>;
+}
+interface PiLike {
+    on(event: 'tool_call', handler: (event: ToolCallEvent) => void): void;
+    on(event: 'tool_result', handler: (event: ToolResultEvent) => {
+        details: Record<string, unknown>;
+    } | void): void;
+}
+/** Loaded into every canvas broker. Plain Pi sessions have no node id and
+ * deliberately receive no filesystem transport. */
+export declare function registerCanvasPreviewResult(pi: PiLike): void;
+export default registerCanvasPreviewResult;

package/dist/pi-extensions/canvas-preview-result.js

@@ -0,0 +1,60 @@
+// canvas-preview-result.ts — private structured result transport for crtr bash calls.
+//
+// A crtr leaf returns a record, but the CLI normally renders that record to
+// stdout for the agent. stdout is model context, so this hook assigns every
+// bash call a private file, lets crtr atomically mirror its record there, then
+// attaches the record to Pi's ToolResult.details. The attach viewer can render
+// a structured preview without parsing the agent-facing text.
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+function isPreviewRecord(value) {
+    if (value === null || typeof value !== 'object' || typeof value['path'] !== 'string')
+        return false;
+    const record = value;
+    return (record.result !== undefined && record.result !== null && typeof record.result === 'object' && !Array.isArray(record.result))
+        || (Array.isArray(record.jsonl) && record.jsonl.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item)))
+        || (record.error !== undefined && record.error !== null && typeof record.error === 'object' && !Array.isArray(record.error));
+}
+/** Loaded into every canvas broker. Plain Pi sessions have no node id and
+ * deliberately receive no filesystem transport. */
+export function registerCanvasPreviewResult(pi) {
+    if (process.env['CRTR_NODE_ID'] === undefined || process.env['CRTR_NODE_ID'] === '')
+        return;
+    const directory = join(tmpdir(), 'crouter-preview-results');
+    const paths = new Map();
+    pi.on('tool_call', (event) => {
+        if (event.toolName !== 'bash' || typeof event.input.command !== 'string')
+            return;
+        mkdirSync(directory, { recursive: true });
+        const path = join(directory, `${encodeURIComponent(event.toolCallId)}.json`);
+        paths.set(event.toolCallId, path);
+        // Export before the complete script rather than prefixing its first simple
+        // command: agent bash calls routinely start with `cd … &&`, a compound
+        // statement, or setup commands before crtr itself.
+        event.input.command = `export CRTR_PREVIEW_RESULT_PATH=${JSON.stringify(path)}\n${event.input.command}`;
+    });
+    pi.on('tool_result', (event) => {
+        const path = paths.get(event.toolCallId);
+        if (path === undefined)
+            return;
+        paths.delete(event.toolCallId);
+        if (!existsSync(path))
+            return;
+        try {
+            const record = JSON.parse(readFileSync(path, 'utf8'));
+            if (!isPreviewRecord(record))
+                return;
+            return { details: { ...(event.details ?? {}), crtrPreview: record } };
+        }
+        catch {
+            // A malformed side-channel record is not agent-visible output and must
+            // not change the bash call's actual result.
+            return;
+        }
+        finally {
+            rmSync(path, { force: true });
+        }
+    });
+}
+export default registerCanvasPreviewResult;

package/dist/types.d.ts

@@ -323,6 +323,10 @@ export interface ProfileManifest {
     schema_version: number;
     name: string;
     projects: string[];
+    /** The directory nodes under this profile are pinned to (see
+     *  `profileHome`). Normalized on read to the first project when the manifest
+     *  carries none, so a profile written before homes existed still has one. */
+    home: string | null;
     created_at: string;
     last_used_at: string | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.175",
+  "version": "0.3.176",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.175",
+  "version": "0.3.176",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.175",
+      "version": "0.3.176",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/core/substrate/on-read-pure.d.ts

@@ -1,7 +0,0 @@
-import type { NodeConfigSubject } from './subject-fields.js';
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: Set<string>): string;
-/** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
- * lookup. */
-export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null): string;

package/dist/core/substrate/on-read-pure.js

@@ -1,272 +0,0 @@
-// on-read.ts — file-context delivery for the document substrate.
-//
-// A memory with file-read visibility participates only through an explicit
-// `applies-to` path glob (authoring lint requires one). Two events use that one
-// routing mechanism:
-//
-//   • A successful `read` tool call evaluates the read file against every
-//     visible substrate doc. Project stores encountered between that file and
-//     the filesystem root join the resolved cwd/profile corpus, so a nested
-//     workspace can contribute guidance exactly when a file beneath it is read.
-//   • Opening a workspace evaluates the reserved `applies-to: "."` target for
-//     every project store mounted by the cwd and selected profile. This happens
-//     while the first-message bearings are assembled, so workspace-wide context
-//     arrives before the task rather than waiting for an arbitrary first file.
-//
-// `read-when` remains an additional OR trigger over a read markdown file's own
-// frontmatter. It does not replace `applies-to`: every non-none file-read rung
-// still declares its path boundary explicitly.
-//
-// Every candidate renders at its own fileReadVisibility rung. Explicit routing
-// is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
-// concern and do not cap a deliberately matched document.
-import { realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, dirname, matchesGlob, parse, relative, sep } from 'node:path';
-import { CRTR_DIR_NAME } from '../../types.js';
-import { pathExists, readText, walkFiles } from '../fs-utils.js';
-import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { evalCondition } from '../predicate.js';
-import { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
-import { userScopeRoot } from '../scope.js';
-import { displayName } from './ceiling.js';
-import { gatePasses } from './gate.js';
-import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
-import { cachedSubstrateDocs } from './session-cache.js';
-const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
-function realpathOrSelf(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return p;
-    }
-}
-function attr(s) {
-    return s
-        .replace(/&/g, '&')
-        .replace(/"/g, '"')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
-function gitRootOf(p) {
-    let d = p;
-    const root = parse(d).root;
-    while (true) {
-        if (pathExists(`${d}${sep}.git`))
-            return d;
-        if (d === root)
-            return null;
-        const parent = dirname(d);
-        if (parent === d)
-            return null;
-        d = parent;
-    }
-}
-function disp(p) {
-    const root = gitRootOf(p);
-    if (!root)
-        return p;
-    const rel = relative(root, p);
-    return rel === '' ? '.' : rel;
-}
-function isJunkAncestor(dir) {
-    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
-}
-function owningRootOf(doc) {
-    const parts = doc.path.split(sep);
-    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
-    if (idx <= 0)
-        return null;
-    return parts.slice(0, idx).join(sep) || sep;
-}
-function loadProjectDoc(file, memoryDir) {
-    try {
-        const raw = relative(memoryDir, file)
-            .replace(/\.md$/i, '')
-            .split(sep)
-            .join('/');
-        const fallbackName = normalizeDocName(raw);
-        if (fallbackName === '')
-            return null;
-        const { data, body } = parseFrontmatterGeneric(readText(file));
-        const schema = parseSubstrateFrontmatter(data);
-        if (schema === null)
-            return null;
-        return {
-            ...schema,
-            name: resolveDocName(data, fallbackName),
-            scope: 'project',
-            path: file,
-            body,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-function safeWalkMarkdown(dir) {
-    try {
-        return walkFiles(dir, (name) => name.toLowerCase().endsWith('.md'));
-    }
-    catch {
-        return [];
-    }
-}
-/** Project docs from every workspace store enclosing the read file. This is a
- * discovery walk only: each returned doc must still match an explicit trigger. */
-function enclosingProjectDocs(absReadFile) {
-    const docs = [];
-    const seen = new Set();
-    const home = realpathOrSelf(homedir());
-    const userRoot = realpathOrSelf(userScopeRoot());
-    const fsRoot = parse(absReadFile).root;
-    let dir = dirname(absReadFile);
-    while (true) {
-        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
-            const memoryDir = `${dir}${sep}${CRTR_DIR_NAME}${sep}memory`;
-            if (pathExists(memoryDir)) {
-                for (const file of safeWalkMarkdown(memoryDir)) {
-                    const real = realpathOrSelf(file);
-                    if (seen.has(real))
-                        continue;
-                    seen.add(real);
-                    const doc = loadProjectDoc(file, memoryDir);
-                    if (doc !== null)
-                        docs.push(doc);
-                }
-            }
-        }
-        if (dir === home || dir === fsRoot)
-            break;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return docs;
-}
-function resolvedDocs() {
-    try {
-        return cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
-    }
-    catch {
-        return [];
-    }
-}
-function dedupeByPhysicalPath(docs) {
-    const seen = new Set();
-    const out = [];
-    for (const doc of docs) {
-        const real = realpathOrSelf(doc.path);
-        if (seen.has(real))
-            continue;
-        seen.add(real);
-        out.push(doc);
-    }
-    return out;
-}
-function globMatches(glob, absReadFile, owningRoot) {
-    const targets = [absReadFile, basename(absReadFile)];
-    if (owningRoot !== null)
-        targets.push(relative(owningRoot, absReadFile));
-    return targets.some((target) => {
-        try {
-            return matchesGlob(target, glob);
-        }
-        catch {
-            return false;
-        }
-    });
-}
-function readFileFrontmatter(absReadFile) {
-    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
-        return {};
-    try {
-        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
-    }
-    catch {
-        return {};
-    }
-}
-function matchesReadEvent(doc, absReadFile, readFrontmatter) {
-    const pathMatch = doc.appliesTo?.some((glob) => globMatches(glob, absReadFile, owningRootOf(doc))) === true;
-    const frontmatterMatch = doc.readWhen !== undefined &&
-        Object.keys(readFrontmatter).length > 0 &&
-        evalCondition(doc.readWhen, readFrontmatter);
-    return pathMatch || frontmatterMatch;
-}
-function envelopeName(doc) {
-    const displayed = displayName(doc.name);
-    if (displayed !== '')
-        return displayed;
-    const root = owningRootOf(doc);
-    return root === null ? doc.name : basename(root);
-}
-function renderDocEnvelope(doc) {
-    const rung = doc.fileReadVisibility;
-    if (rung === 'none')
-        return null;
-    let body = '';
-    if (rung === 'content')
-        body = doc.body.trim();
-    else if (rung === 'preview')
-        body = previewLine(doc);
-    const attrs = `kind="${attr(doc.kind)}" name="${attr(envelopeName(doc))}" src="${attr(disp(doc.path))}"`;
-    return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
-}
-function renderCandidates(subject, docs, seen) {
-    const rendered = [];
-    for (const doc of docs) {
-        const real = realpathOrSelf(doc.path);
-        if (seen.has(real))
-            continue;
-        try {
-            if (!gatePasses(doc, subject))
-                continue;
-            const block = renderDocEnvelope(doc);
-            if (block === null)
-                continue;
-            seen.add(real);
-            rendered.push(block);
-        }
-        catch {
-            continue;
-        }
-    }
-    return rendered.length === 0
-        ? ''
-        : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
-}
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Set()) {
-    const absReadFile = realpathOrSelf(readFilePath);
-    const readFrontmatter = readFileFrontmatter(absReadFile);
-    const docs = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
-        .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
-        .filter((doc) => matchesReadEvent(doc, absReadFile, readFrontmatter));
-    return renderCandidates(subject, docs, seen);
-}
-/** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
- * lookup. */
-export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId) {
-    let docs;
-    try {
-        docs = listProjectMemoryDocs(cwd, profileId)
-            .map(parseSubstrateDoc)
-            .filter((doc) => doc !== null);
-    }
-    catch {
-        return '';
-    }
-    docs = dedupeByPhysicalPath(docs)
-        .filter((doc) => doc.appliesTo?.some((glob) => glob.trim() === '.') === true)
-        .sort((a, b) => {
-        const aRoot = owningRootOf(a) ?? '';
-        const bRoot = owningRootOf(b) ?? '';
-        const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
-        return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
-    });
-    return renderCandidates(subject, docs, new Set());
-}