@lumoai/cli 1.0.0

package/dist/cli/src/lib/doc-input.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDocContent = resolveDocContent;
+exports.readStdinToString = readStdinToString;
+exports.readFileUtf8 = readFileUtf8;
+const fs = __importStar(require("fs"));
+/**
+ * Pick one of --content / --file / stdin as the markdown source.
+ * Explicit flags win: if --content or --file is set, stdin is ignored
+ * (whether the shell is interactive or not). --content and --file are
+ * mutually exclusive. stdin is only consulted when neither flag is set
+ * and the shell is non-TTY.
+ */
+async function resolveDocContent(args) {
+    const hasContent = args.content !== undefined;
+    const hasFile = args.file !== undefined && args.file.length > 0;
+    if (hasContent && hasFile) {
+        return {
+            kind: 'error',
+            message: '--content and --file are mutually exclusive (pick one)',
+        };
+    }
+    if (hasContent)
+        return { kind: 'ok', markdown: args.content };
+    if (hasFile) {
+        const text = await args.readFile(args.file);
+        return { kind: 'ok', markdown: text };
+    }
+    if (!args.stdinIsTTY) {
+        const text = await args.readStdin();
+        return { kind: 'ok', markdown: text };
+    }
+    return { kind: 'none' };
+}
+/** Read stdin to end as UTF-8 string. */
+function readStdinToString() {
+    return new Promise(resolve => {
+        let buf = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => (buf += chunk));
+        process.stdin.on('end', () => resolve(buf));
+    });
+}
+/** Default readFile wrapper for production CLI use. */
+function readFileUtf8(path) {
+    return fs.promises.readFile(path, 'utf8');
+}

package/dist/cli/src/lib/doc-sort-order.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickNextSortOrder = pickNextSortOrder;
+/**
+ * Compute the sortOrder to assign to a new/relocated doc so it lands at the
+ * end of its sibling list. Empty siblings → 0. Otherwise max(sortOrder) + 1.
+ *
+ * The "siblings" passed in MUST be the docs already under the target parent
+ * (or under root). The caller filters this out of the GET /api/documents
+ * payload before calling — keeping this function pure makes it cheap to
+ * unit-test in the future.
+ */
+function pickNextSortOrder(siblings) {
+    if (siblings.length === 0)
+        return 0;
+    let max = siblings[0].sortOrder;
+    for (let i = 1; i < siblings.length; i++) {
+        const v = siblings[i].sortOrder;
+        if (v > max)
+            max = v;
+    }
+    return max + 1;
+}

package/dist/cli/src/lib/doc-tree.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTree = buildTree;
+exports.flattenWithDepth = flattenWithDepth;
+/**
+ * Group a flat list of docs into a forest. Docs whose parentId is null OR
+ * whose parent is absent from the input become roots ("virtual roots" in
+ * spec parlance). Siblings are sorted by sortOrder ascending; ties broken
+ * by id to keep ordering stable when sortOrder collides.
+ */
+function buildTree(rows) {
+    const byId = new Map();
+    for (const row of rows) {
+        byId.set(row.id, { row, children: [] });
+    }
+    const roots = [];
+    for (const row of rows) {
+        const node = byId.get(row.id);
+        const parent = row.parentId ? byId.get(row.parentId) : undefined;
+        if (parent) {
+            parent.children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    const sortNodes = (nodes) => {
+        nodes.sort((a, b) => {
+            const ao = a.row.sortOrder ?? 0;
+            const bo = b.row.sortOrder ?? 0;
+            if (ao !== bo)
+                return ao - bo;
+            return a.row.id < b.row.id ? -1 : a.row.id > b.row.id ? 1 : 0;
+        });
+        for (const n of nodes)
+            sortNodes(n.children);
+    };
+    sortNodes(roots);
+    return roots;
+}
+/**
+ * Pre-order traversal yielding rows tagged with depth. Roots → depth 0.
+ */
+function flattenWithDepth(roots) {
+    const out = [];
+    const visit = (node, depth) => {
+        out.push({ row: node.row, depth });
+        for (const child of node.children)
+            visit(child, depth + 1);
+    };
+    for (const r of roots)
+        visit(r, 0);
+    return out;
+}

package/dist/cli/src/lib/format.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTaskListTable = formatTaskListTable;
+/**
+ * Render a task list as a fixed-width table. Each row:
+ *   LUM-42  IN_PROGRESS  HIGH    project-name   Title here
+ * Columns are right-padded to the widest cell in the result set so output
+ * lines up regardless of identifier or project-name length.
+ */
+function formatTaskListTable(tasks) {
+    if (tasks.length === 0)
+        return 'No tasks.';
+    const rows = tasks.map(t => ({
+        identifier: `${t.teamIdentifier}-${t.number}`,
+        status: t.status,
+        priority: t.priority,
+        project: t.project.name,
+        title: t.title,
+    }));
+    const widths = {
+        identifier: Math.max(...rows.map(r => r.identifier.length)),
+        status: Math.max(...rows.map(r => r.status.length)),
+        priority: Math.max(...rows.map(r => r.priority.length)),
+        project: Math.max(...rows.map(r => r.project.length)),
+    };
+    return rows
+        .map(r => `${r.identifier.padEnd(widths.identifier)}  ` +
+        `${r.status.padEnd(widths.status)}  ` +
+        `${r.priority.padEnd(widths.priority)}  ` +
+        `${r.project.padEnd(widths.project)}  ` +
+        r.title)
+        .join('\n');
+}

package/dist/cli/src/lib/hook-log.js

@@ -0,0 +1,81 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logHookError = logHookError;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function logDir() {
+    return path.join(os.homedir(), '.lumo');
+}
+function logPath() {
+    return path.join(logDir(), 'hook.log');
+}
+/**
+ * Best-effort append to `~/.lumo/hook.log`.
+ *
+ * Hook commands must never emit to stderr (that would pollute Claude Code's
+ * terminal output). All errors — network, auth, timeout, filesystem — are
+ * appended here instead. If the log write itself fails, we swallow that too:
+ * a broken log is better than a broken hook.
+ *
+ * @param context Short label identifying the call site (e.g. `"[pre-tool-use]"`)
+ * @param error   Either an `Error`, a string, or anything else; stringified internally
+ */
+function logHookError(context, error) {
+    try {
+        const dir = logDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { mode: 0o700, recursive: true });
+        const msg = error instanceof Error ? error.message : String(error);
+        const line = `${new Date().toISOString()} ${context} ${msg}\n`;
+        const p = logPath();
+        const existed = fs.existsSync(p);
+        fs.appendFileSync(p, line, { mode: 0o600 });
+        // Best-effort permission tightening: appendFileSync's mode is only honored
+        // on initial create, so chmod existing files to match config.ts style.
+        if (existed) {
+            try {
+                fs.chmodSync(p, 0o600);
+            }
+            catch {
+                // Best-effort
+            }
+        }
+    }
+    catch {
+        // Log writes are best-effort; never throw
+    }
+}

package/dist/cli/src/lib/hook-runner.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatHookStdoutLines = formatHookStdoutLines;
+exports.runHook = runHook;
+exports.runHookWithBody = runHookWithBody;
+const config_1 = require("./config");
+const api_1 = require("./api");
+const hook_log_1 = require("./hook-log");
+/**
+ * Hard timeout for the hook POST. On timeout the request is aborted,
+ * logged, and `runHook` exits 0 — Claude Code is never blocked beyond
+ * this ceiling.
+ *
+ * Sizing history:
+ *   - 1000ms (initial): too tight, false timeouts on cold starts
+ *   - 1500ms (per plan): still below observed p95 for cold
+ *     Next.js + Prisma + Clerk on dev; server actually inserts the row
+ *     but the client aborts before reading the 200, so `hook.log` fills
+ *     with "This operation was aborted" noise
+ *   - 3000ms (now): matches observed p95 on dev; catches the full
+ *     happy path without being long enough to make users feel per-tool
+ *     hook lag. Revisit when Day 4 makes hook POSTs fire-and-forget so
+ *     the client can exit 0 before the server finishes.
+ */
+const TIMEOUT_MS = 3000;
+/**
+ * Read the full hook JSON from stdin.
+ *
+ * Resolves to an empty string on EOF if no bytes were produced (e.g. tests
+ * or a client that invoked the command with no stdin attached). This lets
+ * the runner POST `{}` rather than hanging.
+ */
+function readStdin() {
+    return new Promise(resolve => {
+        // If stdin is a TTY (nothing piped in), resolve immediately so the hook
+        // doesn't hang when invoked outside of Claude Code.
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+/**
+ * Build the array of stdout lines to emit for a given hook path + response
+ * body. Returns an empty array for any path other than 'session-start'.
+ *
+ * For 'session-start' the array contains:
+ *   [0] plain-text bind/unbound status line (always present when taskBinding exists)
+ *   [1] (optional) hookSpecificOutput JSON when memorySection is a non-empty string
+ *
+ * The JSON on line [1] conforms to Claude Code's hookSpecificOutput envelope so
+ * the runtime injects additionalContext into the conversation automatically.
+ */
+function formatHookStdoutLines(path, responseBody) {
+    if (path !== 'session-start')
+        return [];
+    if (responseBody == null || typeof responseBody !== 'object')
+        return [];
+    const body = responseBody;
+    if (!body.sessionId)
+        return [];
+    const lines = [];
+    const sessionId = body.sessionId;
+    const tb = body.taskBinding;
+    if (tb && tb.bound === true) {
+        lines.push(`[Lumo] session_id=${sessionId} | 当前任务: ${tb.taskIdentifier} - ${tb.taskTitle}`);
+    }
+    else if (tb && tb.bound === false) {
+        lines.push(`[Lumo] session_id=${sessionId} | 当前未绑定任务。请告诉我你要处理的任务编号（如 LUM-42），或说"跳过"。`);
+    }
+    if (typeof body.memorySection === 'string' && body.memorySection !== '') {
+        lines.push(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'SessionStart',
+                additionalContext: body.memorySection,
+            },
+        }));
+    }
+    return lines;
+}
+/**
+ * POST the hook body to /api/hooks/<path> with a short timeout. All errors
+ * — credential missing, network failure, timeout, non-2xx — are routed to
+ * hook.log and then the caller exits 0.
+ *
+ * This function NEVER throws and NEVER rejects.
+ */
+async function runHook(path) {
+    const body = await readStdin();
+    return runHookWithBody(path, body);
+}
+/**
+ * Test-friendly worker. Takes the hook body as an argument so tests can
+ * exercise the side-effect logic without poking process.stdin. Production
+ * code always goes through `runHook`, which feeds it real stdin.
+ */
+async function runHookWithBody(path, body) {
+    try {
+        const creds = (0, config_1.readCredentials)();
+        if (!creds) {
+            (0, hook_log_1.logHookError)(`[${path}]`, 'no credentials; skipping');
+            return;
+        }
+        // Allow `LUMO_API_URL` to override the baked-in creds.apiUrl for
+        // redirecting hooks at dev-env switch without re-running `lumo auth
+        // login`. The bearer token from creds.json is still used as-is.
+        const envUrl = process.env.LUMO_API_URL?.trim();
+        const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+        const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/hooks/${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${creds.token}`,
+                },
+                body: body || '{}',
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                (0, hook_log_1.logHookError)(`[${path}]`, `HTTP ${res.status} from ${url}`);
+            }
+            else if (path === 'session-start') {
+                // Per-hook side effects fire only after a 2xx response so a transient
+                // server failure doesn't desync local state from server state.
+                try {
+                    const responseBody = await res.json();
+                    for (const line of formatHookStdoutLines(path, responseBody)) {
+                        process.stdout.write(line + '\n');
+                    }
+                }
+                catch {
+                    // response body parse failure is non-fatal
+                }
+            }
+        }
+        catch (err) {
+            (0, hook_log_1.logHookError)(`[${path}]`, err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (err) {
+        (0, hook_log_1.logHookError)(`[${path}] runner`, err);
+    }
+}

package/dist/cli/src/lib/markdown-tiptap.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tiptapToMarkdown = exports.markdownToTiptap = void 0;
+// Single source of truth lives in shared/src/markdown-tiptap.ts
+var markdown_tiptap_1 = require("../../../shared/src/markdown-tiptap");
+Object.defineProperty(exports, "markdownToTiptap", { enumerable: true, get: function () { return markdown_tiptap_1.markdownToTiptap; } });
+Object.defineProperty(exports, "tiptapToMarkdown", { enumerable: true, get: function () { return markdown_tiptap_1.tiptapToMarkdown; } });

package/dist/cli/src/lib/prompt.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptSecret = promptSecret;
+/**
+ * Prompt the user for a secret with echo disabled.
+ *
+ * Returns the trimmed input. Exits the process with code 130 on Ctrl+C.
+ * Falls back to a regular line-read when stdin is not a TTY (piped input).
+ */
+function promptSecret(message) {
+    return new Promise(resolve => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        if (!stdin.isTTY) {
+            let buf = '';
+            stdin.setEncoding('utf8');
+            const onData = (chunk) => {
+                buf += chunk;
+                const nl = buf.indexOf('\n');
+                if (nl !== -1) {
+                    stdin.pause();
+                    stdin.removeListener('data', onData);
+                    resolve(buf.slice(0, nl).trim());
+                }
+            };
+            stdin.on('data', onData);
+            stdin.on('end', () => resolve(buf.trim()));
+            return;
+        }
+        stdout.write(message);
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        let buf = '';
+        const cleanup = () => {
+            stdin.setRawMode(wasRaw);
+            stdin.removeListener('data', onData);
+            stdin.pause();
+            stdout.write('\n');
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\u0003') {
+                    // Ctrl+C — treat as cancel, exit cleanly
+                    cleanup();
+                    resolve('');
+                    process.exit(130);
+                }
+                if (ch === '\u0004') {
+                    cleanup();
+                    resolve(buf.trim());
+                    return;
+                }
+                if (ch === '\r' || ch === '\n') {
+                    cleanup();
+                    resolve(buf.trim());
+                    return;
+                }
+                if (ch === '\u0008' || ch === '\u007f') {
+                    buf = buf.slice(0, -1);
+                    continue;
+                }
+                if (ch.charCodeAt(0) < 0x20)
+                    continue;
+                buf += ch;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}

package/dist/cli/src/lib/resolve-doc-id.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupDocId = lookupDocId;
+const api_1 = require("./api");
+const resolve_doc_1 = require("./resolve-doc");
+/**
+ * Resolve a user-typed doc reference (cuid OR case-insensitive title) to a
+ * document id. Fetches GET /api/documents to perform a title lookup when
+ * needed. Returns null on not-found or ambiguity (and prints a helpful
+ * error in the ambiguous case so the caller can just exit).
+ */
+async function lookupDocId(apiUrl, token, reference) {
+    if ((0, resolve_doc_1.isLikelyCuid)(reference))
+        return reference;
+    const listUrl = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents`;
+    const res = await fetch(listUrl, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok)
+        return null;
+    const { documents } = (await res.json());
+    const result = (0, resolve_doc_1.resolveDoc)(reference, documents);
+    if (result.kind === 'found')
+        return result.doc.id;
+    if (result.kind === 'ambiguous') {
+        console.error(`Error: title "${reference}" matches ${result.candidates.length} docs:`);
+        for (const c of result.candidates) {
+            console.error(`  ${c.id}  ${c.title}`);
+        }
+        console.error('Re-run with the cuid.');
+        return null;
+    }
+    return null;
+}

package/dist/cli/src/lib/resolve-doc.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLikelyCuid = isLikelyCuid;
+exports.resolveDoc = resolveDoc;
+/** A loose check — a real cuid is 'c' + 24 base36 chars. */
+function isLikelyCuid(s) {
+    return /^c[a-z0-9]{20,}$/i.test(s);
+}
+/**
+ * Resolve a user-typed doc reference against a list. If the input looks
+ * like a cuid, do exact-id match; otherwise do case-insensitive title
+ * match. Multiple title hits return 'ambiguous'.
+ */
+function resolveDoc(input, docs) {
+    const trimmed = input.trim();
+    if (isLikelyCuid(trimmed)) {
+        const doc = docs.find(d => d.id === trimmed);
+        return doc ? { kind: 'found', doc } : { kind: 'not-found' };
+    }
+    const lower = trimmed.toLowerCase();
+    const hits = docs.filter(d => d.title.toLowerCase() === lower);
+    if (hits.length === 0)
+        return { kind: 'not-found' };
+    if (hits.length === 1)
+        return { kind: 'found', doc: hits[0] };
+    return { kind: 'ambiguous', candidates: hits };
+}

package/dist/cli/src/lib/resolve-member.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchMembers = fetchMembers;
+exports.resolveMember = resolveMember;
+const api_1 = require("./api");
+/**
+ * Fetch the workspace member directory once. Used by doc-share commands to
+ * resolve a free-form member ref → memberId locally, because the document
+ * shares endpoint expects WorkspaceMember.id (cuid) and does not do
+ * server-side ref resolution the way /api/tasks does for assigneeRef.
+ */
+async function fetchMembers(apiUrl, token) {
+    const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/workspaces/members`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`failed to load members (${res.status} ${res.statusText}): ${text}`);
+    }
+    const body = (await res.json());
+    return body.members.map(m => ({
+        memberId: m.id,
+        displayName: m.name,
+        email: m.email,
+    }));
+}
+/**
+ * Resolve `me`, an email, or a display name against the directory.
+ * Match is case-insensitive. `me` resolves via the caller's stored email.
+ * Email matches win over name matches so `alice@x.com` is unambiguous even
+ * if a display name happens to collide.
+ */
+function resolveMember(members, ref, myEmail) {
+    const trimmed = ref.trim();
+    if (trimmed.length === 0)
+        return { kind: 'not_found', query: ref };
+    if (trimmed.toLowerCase() === 'me') {
+        const me = members.find(m => (m.email ?? '').toLowerCase() === myEmail.toLowerCase());
+        if (!me)
+            return { kind: 'not_found', query: 'me' };
+        return { kind: 'ok', member: me };
+    }
+    const lower = trimmed.toLowerCase();
+    const byEmail = members.filter(m => (m.email ?? '').toLowerCase() === lower);
+    if (byEmail.length === 1)
+        return { kind: 'ok', member: byEmail[0] };
+    if (byEmail.length > 1) {
+        return { kind: 'ambiguous', query: ref, candidates: byEmail };
+    }
+    const byName = members.filter(m => m.displayName.toLowerCase() === lower);
+    if (byName.length === 1)
+        return { kind: 'ok', member: byName[0] };
+    if (byName.length > 1) {
+        return { kind: 'ambiguous', query: ref, candidates: byName };
+    }
+    return { kind: 'not_found', query: ref };
+}