@skrr-ai/cli 0.1.8

package/dist/lib/web-url.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * Canonical skrr web deep-link builder for the `skrr` CLI.
+ *
+ * The CLI is the source of truth for entity links. It already knows which
+ * deployment it is pointed at (`config.baseURL` — `https://oversky.dev` in dev,
+ * `https://oversky.ai` in prod), so it can hand an agent a ready-to-click URL
+ * instead of a bare ID. We mirror the client's canonical route shapes here so
+ * the agent never has to guess the path or the environment.
+ *
+ * Keep the route shapes in lockstep with the client:
+ *   - `client/src/utils/taskUrl.ts`
+ *   - `client/src/routes/paneRouteConfig.ts`
+ *
+ * An absolute web URL is `webOrigin + canonicalPath`, where `webOrigin` is the
+ * baseURL mapped to the host that serves the SPA (see `toWebOrigin` — the apex
+ * and the `api.` subdomain are distinct origins in skrr's topology).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webPath = webPath;
+exports.webUrl = webUrl;
+exports.taskViewUrl = taskViewUrl;
+exports.taskUrlFrom = taskUrlFrom;
+exports.spaceUrlFrom = spaceUrlFrom;
+exports.conversationUrlFrom = conversationUrlFrom;
+exports.groupChatUrlFrom = groupChatUrlFrom;
+exports.goalUrlFrom = goalUrlFrom;
+exports.commitmentUrlFrom = commitmentUrlFrom;
+exports.northstarUrlFrom = northstarUrlFrom;
+exports.agentUrlFrom = agentUrlFrom;
+exports.compassUrlFrom = compassUrlFrom;
+exports.triggerUrlFrom = triggerUrlFrom;
+exports.withTaskUrl = withTaskUrl;
+exports.withSpaceUrl = withSpaceUrl;
+exports.withGoalUrl = withGoalUrl;
+exports.projectUrlFrom = projectUrlFrom;
+exports.withProjectUrl = withProjectUrl;
+exports.withCommitmentUrl = withCommitmentUrl;
+exports.withNorthstarUrl = withNorthstarUrl;
+exports.withAgentUrl = withAgentUrl;
+exports.withDataUrls = withDataUrls;
+exports.workflowUrlFrom = workflowUrlFrom;
+/**
+ * Site-relative canonical path for an entity, or `null` when the required id is
+ * missing. When a task/goal knows its hosting space we emit the canonical
+ * space-scoped route; otherwise we fall back to the legacy id-only route, which
+ * still resolves via a transparent redirect.
+ */
+function webPath(ref) {
+    switch (ref.kind) {
+        case 'task': {
+            const taskId = encodeId(ref.taskId);
+            if (!taskId)
+                return null;
+            const spaceId = encodeId(ref.spaceId);
+            return spaceId ? `/spaces/${spaceId}/tasks/${taskId}` : `/task/${taskId}`;
+        }
+        case 'space': {
+            const spaceId = encodeId(ref.spaceId);
+            return spaceId ? `/spaces/${spaceId}` : null;
+        }
+        case 'goal': {
+            const goalId = encodeId(ref.goalId);
+            if (!goalId)
+                return null;
+            const spaceId = encodeId(ref.spaceId);
+            return spaceId ? `/spaces/${spaceId}/goals/${goalId}` : `/goals/${goalId}`;
+        }
+        case 'commitment': {
+            const commitmentId = encodeId(ref.commitmentId);
+            return commitmentId ? `/commitments/${commitmentId}` : null;
+        }
+        case 'northstar': {
+            const northstarId = encodeId(ref.northstarId);
+            return northstarId ? `/northstars/${northstarId}` : null;
+        }
+        case 'agent': {
+            const agentId = encodeId(ref.agentId);
+            return agentId ? `/agent/${agentId}` : null;
+        }
+        case 'compass': {
+            const agentId = encodeId(ref.agentId);
+            const compassId = encodeId(ref.compassId);
+            return agentId && compassId ? `/agent/${agentId}?compassId=${compassId}#compass` : null;
+        }
+        case 'trigger': {
+            const agentId = encodeId(ref.agentId);
+            const triggerId = encodeId(ref.triggerId);
+            return agentId && triggerId ? `/agent/${agentId}?triggerId=${triggerId}#triggers` : null;
+        }
+        case 'conversation': {
+            return ref.conversationId ? `/c/${encodeURIComponent(ref.conversationId)}` : null;
+        }
+        case 'groupChat': {
+            const groupChatId = encodeId(ref.groupChatId);
+            return groupChatId ? `/groups/${groupChatId}` : null;
+        }
+        case 'project': {
+            const spaceId = encodeId(ref.spaceId);
+            if (!spaceId)
+                return null;
+            const projectId = encodeId(ref.projectId);
+            return projectId ? `/spaces/${spaceId}/projects/${projectId}` : `/spaces/${spaceId}/projects`;
+        }
+        case 'workflow': {
+            const spaceId = encodeId(ref.spaceId);
+            if (!spaceId)
+                return null;
+            const query = new URLSearchParams();
+            if (ref.workflowId)
+                query.set('workflowId', String(ref.workflowId));
+            if (ref.runId)
+                query.set('runId', String(ref.runId));
+            if (ref.nodeKey)
+                query.set('nodeKey', String(ref.nodeKey));
+            const suffix = query.toString();
+            return `/spaces/${spaceId}/workflows${suffix ? `?${suffix}` : ''}`;
+        }
+        default:
+            return null;
+    }
+}
+/** Absolute web URL (`<webOrigin><path>`), or `null` when the ref lacks its id. */
+function webUrl(baseURL, ref) {
+    const path = webPath(ref);
+    if (!path)
+        return null;
+    return `${toWebOrigin(baseURL)}${path}`;
+}
+/**
+ * Map a configured baseURL to the web origin that serves the SPA.
+ *
+ * skrr's topology splits the web app onto the apex (oversky.ai / oversky.dev)
+ * and the HTTP/realtime API onto an `api.` subdomain (api.oversky.ai /
+ * api.oversky.dev) — see `config/public-endpoints.json` and
+ * `cli/src/lib/oauthLogin.ts` (`OAUTH_WEB_URL_FROM_API`), the source of truth for
+ * this mapping. The CLI's baseURL is normally the apex already, but it MAY be set
+ * to the api. subdomain (supported via `--base-url` / `OVERSKY_BASE_URL`); web
+ * links must then resolve back to the apex or they'd hit the API host and never
+ * render the SPA. Every other origin (localhost, self-hosted single-origin,
+ * custom) passes through unchanged — only the known skrr api hosts are mapped.
+ */
+const WEB_ORIGIN_FROM_API = {
+    'https://api.oversky.ai': 'https://oversky.ai',
+    'https://api.oversky.dev': 'https://oversky.dev',
+};
+function toWebOrigin(baseURL) {
+    const trimmed = trimTrailingSlash(baseURL);
+    return WEB_ORIGIN_FROM_API[trimmed.toLowerCase()] ?? trimmed;
+}
+/** A persisted personalized Task View always opens as a focused modal on /tasks. */
+function taskViewUrl(baseURL, viewId) {
+    return `${toWebOrigin(baseURL)}/tasks?view=${encodeURIComponent(viewId)}`;
+}
+/** Build a task URL from a raw server task record. */
+function taskUrlFrom(baseURL, task) {
+    const taskId = idOf(task, 'id', '_id');
+    if (!taskId)
+        return null;
+    return webUrl(baseURL, { kind: 'task', taskId, spaceId: idOf(task, 'spaceId') ?? null });
+}
+/** Build a space URL from a raw server space record. */
+function spaceUrlFrom(baseURL, space) {
+    const spaceId = idOf(space, 'id', '_id');
+    if (!spaceId)
+        return null;
+    return webUrl(baseURL, { kind: 'space', spaceId });
+}
+/**
+ * Build a conversation URL from a raw server conversation record.
+ *
+ * Commands print this instead of the bare id: an id is not something a person
+ * can open, and the CLI already attaches URLs to conversations elsewhere
+ * (`convos list --json` runs results through `withDataUrls`).
+ */
+function conversationUrlFrom(baseURL, conversation) {
+    const conversationId = idOf(conversation, 'conversationId', 'id', '_id');
+    if (!conversationId)
+        return null;
+    return webUrl(baseURL, { kind: 'conversation', conversationId });
+}
+/**
+ * Build a group-chat URL from a raw server group-chat record.
+ *
+ * Reads the `groupChatId` handle every route resolves by — never the Mongo
+ * `_id`, which no route accepts. `chats create` / `chats show` print this so a
+ * caller gets a clickable link instead of grepping the client router to learn
+ * the page is `/groups/<id>` (OSK-4908).
+ */
+function groupChatUrlFrom(baseURL, chat) {
+    const groupChatId = idOf(chat, 'groupChatId');
+    if (!groupChatId)
+        return null;
+    return webUrl(baseURL, { kind: 'groupChat', groupChatId });
+}
+/** Build a goal URL from a raw server goal record. */
+function goalUrlFrom(baseURL, goal) {
+    const goalId = idOf(goal, 'id', '_id');
+    if (!goalId)
+        return null;
+    return webUrl(baseURL, { kind: 'goal', goalId, spaceId: idOf(goal, 'spaceId') ?? null });
+}
+/** Build a commitment URL from a raw server commitment record. */
+function commitmentUrlFrom(baseURL, commitment) {
+    const commitmentId = idOf(commitment, 'id', '_id');
+    if (!commitmentId)
+        return null;
+    return webUrl(baseURL, { kind: 'commitment', commitmentId });
+}
+/** Build a Northstar detail URL from a raw server Northstar record. */
+function northstarUrlFrom(baseURL, northstar) {
+    const northstarId = idOf(northstar, 'id', '_id');
+    if (!northstarId)
+        return null;
+    return webUrl(baseURL, { kind: 'northstar', northstarId });
+}
+/** Build an agent detail URL from a raw server agent record. */
+function agentUrlFrom(baseURL, agent) {
+    const agentId = idOf(agent, 'id', '_id', 'agentId', 'agent_id');
+    return agentId ? webUrl(baseURL, { kind: 'agent', agentId }) : null;
+}
+/** Build the Agent-page deep link that selects this Compass instance. */
+function compassUrlFrom(baseURL, compass) {
+    const agentId = firstText(compass.agentId, compass.agent_id);
+    const compassId = firstText(compass.id, compass._id, compass.compassId);
+    return agentId && compassId ? webUrl(baseURL, { kind: 'compass', agentId, compassId }) : null;
+}
+/** Build the Agent-page deep link that opens this agent-scoped trigger. */
+function triggerUrlFrom(baseURL, trigger) {
+    const triggerId = idOf(trigger, 'id', '_id', 'triggerId');
+    const scope = trigger.scope;
+    const refs = scope && typeof scope === 'object' && !Array.isArray(scope)
+        ? scope.refs
+        : undefined;
+    const agentId = refs && typeof refs === 'object' && !Array.isArray(refs)
+        ? refs.agentId
+        : undefined;
+    return typeof agentId === 'string' && triggerId
+        ? webUrl(baseURL, { kind: 'trigger', agentId, triggerId })
+        : null;
+}
+/** Return a shallow copy of a task record with a `url` field attached. */
+function withTaskUrl(baseURL, task) {
+    return { ...task, url: taskUrlFrom(baseURL, task) };
+}
+/** Return a shallow copy of a space record with a `url` field attached. */
+function withSpaceUrl(baseURL, space) {
+    return { ...space, url: spaceUrlFrom(baseURL, space) };
+}
+/** Return a shallow copy of a goal record with a `url` field attached. */
+function withGoalUrl(baseURL, goal) {
+    return { ...goal, url: goalUrlFrom(baseURL, goal) };
+}
+/**
+ * Build a project URL from a raw server project record.
+ *
+ * Reads `spaceId` off the record — a project is only addressable through its
+ * space. Returns null when the record carries none, rather than guessing.
+ */
+function projectUrlFrom(baseURL, project) {
+    const spaceId = idOf(project, 'spaceId');
+    if (!spaceId)
+        return null;
+    return webUrl(baseURL, {
+        kind: 'project',
+        spaceId,
+        projectId: idOf(project, 'id', '_id') ?? null,
+    });
+}
+/** Return a shallow copy of a project record with a `url` field attached. */
+function withProjectUrl(baseURL, project) {
+    return { ...project, url: projectUrlFrom(baseURL, project) };
+}
+/** Return a shallow copy of a commitment record with a `url` field attached. */
+function withCommitmentUrl(baseURL, commitment) {
+    return { ...commitment, url: commitmentUrlFrom(baseURL, commitment) };
+}
+/** Return a shallow copy of a Northstar record with a canonical web URL. */
+function withNorthstarUrl(baseURL, northstar) {
+    return { ...northstar, url: northstarUrlFrom(baseURL, northstar) };
+}
+/** Return a shallow copy of an agent record with a canonical web URL. */
+function withAgentUrl(baseURL, agent) {
+    return { ...agent, url: agentUrlFrom(baseURL, agent) };
+}
+/**
+ * Attach a `url` to every entity inside a `{ data: [...] }` list envelope.
+ * Returns a shallow copy; a response whose `data` is not an array (or a
+ * non-object response) passes through untouched, so this is safe to apply
+ * blindly to any list command's JSON output.
+ */
+function withDataUrls(baseURL, response, urlFor) {
+    if (!response || typeof response !== 'object')
+        return response;
+    if (Array.isArray(response)) {
+        return response.map((item) => item && typeof item === 'object'
+            ? { ...item, url: urlFor(baseURL, item) }
+            : item);
+    }
+    const envelope = response;
+    const data = envelope.data;
+    if (!Array.isArray(data))
+        return response;
+    return {
+        ...envelope,
+        data: data.map((item) => item && typeof item === 'object'
+            ? { ...item, url: urlFor(baseURL, item) }
+            : item),
+    };
+}
+/**
+ * Build a workflow-definition URL from a raw server workflow record.
+ *
+ * The record may be a definition, a run, or a version — they all carry the ids
+ * this needs under stable names, and every one of them is something a person
+ * asks to "open".
+ */
+function workflowUrlFrom(baseURL, record) {
+    const spaceId = idOf(record, 'spaceId');
+    if (!spaceId)
+        return null;
+    return webUrl(baseURL, {
+        kind: 'workflow',
+        spaceId,
+        // A run record names its definition in `definitionId`; a definition names
+        // itself in `id`. Reading both means one helper serves every command.
+        workflowId: idOf(record, 'definitionId', 'workflowId') ?? idOf(record, 'id', '_id') ?? null,
+        runId: idOf(record, 'workflowRunId') ?? (isRunRecord(record) ? idOf(record, 'id') : null),
+    });
+}
+/** A run id is `wfr_`-prefixed; a definition id is `wfd_`. */
+function isRunRecord(record) {
+    const id = idOf(record, 'id', '_id');
+    return typeof id === 'string' && id.startsWith('wfr_');
+}
+/** First non-empty string value among the given keys, trimmed. */
+function idOf(entity, ...keys) {
+    for (const key of keys) {
+        const value = entity[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function firstText(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function encodeId(value) {
+    const raw = (value ?? '').toString().trim();
+    return raw ? encodeURIComponent(raw) : '';
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}

package/dist/lib/wiki-update.d.ts

@@ -0,0 +1,29 @@
+import type { WikiPageUpdateParams } from '@skrr-ai/data-provider';
+export type WikiPageUpdateInput = {
+    title?: string;
+    icon?: string;
+    clearIcon?: boolean;
+    order?: number;
+};
+export type WikiPageUpdateResult = {
+    ok: true;
+    data: WikiPageUpdateParams;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Build the PATCH body for `skrr wiki update`.
+ *
+ * Two rules carry the weight:
+ *
+ *   - An empty patch REFUSES rather than reporting success. The server's
+ *     `updatePageSchema` accepts `{}` and returns 200 having changed nothing,
+ *     so a caller who typo'd a flag name would otherwise be told the update
+ *     worked.
+ *   - Clearing the icon is its own flag. `--icon ""` cannot mean "clear": the
+ *     server types `icon` as a nullable string with `.min(1)` when present, so
+ *     an empty string is a 400. Only `null` clears it, and a boolean flag is
+ *     the only way for a shell to say `null`.
+ */
+export declare function buildWikiPageUpdate(input: WikiPageUpdateInput): WikiPageUpdateResult;

package/dist/lib/wiki-update.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWikiPageUpdate = buildWikiPageUpdate;
+/**
+ * Build the PATCH body for `skrr wiki update`.
+ *
+ * Two rules carry the weight:
+ *
+ *   - An empty patch REFUSES rather than reporting success. The server's
+ *     `updatePageSchema` accepts `{}` and returns 200 having changed nothing,
+ *     so a caller who typo'd a flag name would otherwise be told the update
+ *     worked.
+ *   - Clearing the icon is its own flag. `--icon ""` cannot mean "clear": the
+ *     server types `icon` as a nullable string with `.min(1)` when present, so
+ *     an empty string is a 400. Only `null` clears it, and a boolean flag is
+ *     the only way for a shell to say `null`.
+ */
+function buildWikiPageUpdate(input) {
+    const data = {};
+    if (input.title !== undefined) {
+        const title = input.title.trim();
+        if (!title)
+            return { ok: false, error: '--title cannot be empty.' };
+        data.title = title;
+    }
+    if (input.clearIcon) {
+        data.icon = null;
+    }
+    else if (input.icon !== undefined) {
+        const icon = input.icon.trim();
+        if (!icon) {
+            return { ok: false, error: 'Use --clear-icon to remove the icon; --icon cannot be empty.' };
+        }
+        data.icon = icon;
+    }
+    if (input.order !== undefined) {
+        if (!Number.isInteger(input.order) || input.order < 0) {
+            return { ok: false, error: '--order must be a non-negative integer.' };
+        }
+        data.order = input.order;
+    }
+    if (Object.keys(data).length === 0) {
+        return {
+            ok: false,
+            error: 'Nothing to update. Pass --title, --icon, --clear-icon, or --order.',
+        };
+    }
+    return { ok: true, data };
+}

package/dist/lib/wiki.d.ts

@@ -0,0 +1,53 @@
+import type { WikiTreeNode } from '@skrr-ai/data-provider';
+/** Read page content from a flag, a file, or stdin (`-`). */
+export declare function readContentInput(options: {
+    content?: string;
+    file?: string;
+    stdin?: boolean;
+}): Promise<string>;
+/** Render a tree as the classic `tree(1)` box drawing. */
+export declare function renderTree(nodes: WikiTreeNode[], emit: (line: string) => void): void;
+export declare function sortNodes(nodes: WikiTreeNode[]): WikiTreeNode[];
+/** Split `A/B/c` into `{ dir: 'A/B', name: 'c' }` — the `dirname`/`basename` pair. */
+export declare function splitParentPath(path: string): {
+    dir: string;
+    name: string;
+};
+/**
+ * A one-line hint printed after `wiki mv` renames a page whose title was never
+ * authored. (OSK-4842)
+ *
+ * `mv` owns the path and `update` owns the title, by design — see mv.ts. A page
+ * written with no `--title` defaults its title to the slug it was born with, so
+ * after a rename that default title still spells the OLD name: `tree` shows
+ * `new  [old]` and `search` still calls it `old`. We cannot silently retitle
+ * (the two are deliberately separate operations), but a user who typed no title
+ * should not have to discover the second command on their own.
+ *
+ * Returns `null` unless the title still equals the OLD slug AND the slug
+ * actually changed — an authored title, or a move that did not rename, gets no
+ * hint.
+ */
+export declare function retitleAfterMoveHint(opts: {
+    oldSlug: string;
+    newSlug: string;
+    title: string;
+    binName: string;
+    spaceId: string;
+    newPath: string;
+}): string | null;
+/** Normalize a user-supplied path: trim segments, drop empties, no leading slash. */
+export declare function normalizeWikiPath(path: string): string;
+/**
+ * Resolve a folder path to its id, or `null` when no folder sits at that path.
+ *
+ * `ls` already returns the id of the directory it listed, so a lookup is one
+ * request and needs no client-side tree walk. The root (`''`) is deliberately
+ * NOT resolvable to an id — it is not a folder anyone can address or delete.
+ */
+export declare function resolveWikiFolderId(spaceId: string, path: string, ls: (spaceId: string, options?: {
+    path?: string;
+    includeFiles?: boolean;
+}) => Promise<{
+    folder_id: string | null;
+}>, isNotFound: (err: unknown) => boolean): Promise<string | null>;

package/dist/lib/wiki.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readContentInput = readContentInput;
+exports.renderTree = renderTree;
+exports.sortNodes = sortNodes;
+exports.splitParentPath = splitParentPath;
+exports.retitleAfterMoveHint = retitleAfterMoveHint;
+exports.normalizeWikiPath = normalizeWikiPath;
+exports.resolveWikiFolderId = resolveWikiFolderId;
+/**
+ * Shared helpers for the `skrr wiki` commands.
+ *
+ * The CLI's whole design premise: a wiki is a filesystem, so the commands are
+ * the filesystem verbs (`ls`, `cat`, `write`, `mkdir`, `mv`, `rm`, `tree`).
+ * An agent that can use a shell can use this without being taught anything.
+ */
+const node_fs_1 = require("node:fs");
+/** Read page content from a flag, a file, or stdin (`-`). */
+async function readContentInput(options) {
+    if (options.content !== undefined)
+        return options.content;
+    if (options.file && options.file !== '-') {
+        return (0, node_fs_1.readFileSync)(options.file, 'utf8');
+    }
+    if (options.stdin || options.file === '-') {
+        return readStdin();
+    }
+    throw new Error('Provide content via --content, --file <path>, or --stdin.');
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+/** Render a tree as the classic `tree(1)` box drawing. */
+function renderTree(nodes, emit) {
+    const walk = (list, prefix) => {
+        const sorted = sortNodes(list);
+        sorted.forEach((node, index) => {
+            const isLast = index === sorted.length - 1;
+            const branch = isLast ? '└── ' : '├── ';
+            emit(`${prefix}${branch}${decorate(node)}`);
+            if (node.children?.length) {
+                walk(node.children, prefix + (isLast ? '    ' : '│   '));
+            }
+        });
+    };
+    walk(nodes, '');
+}
+function decorate(node) {
+    if (node.type === 'folder')
+        return `${node.name}/`;
+    if (node.type === 'file')
+        return `${node.name}  (file)`;
+    // The SLUG sits where a filename sits, because that is what `cat`, `mv` and
+    // `rm` take. This was the other way round: the unbracketed word — the one the
+    // eye reads as the name, in the position `tree(1)` puts a filename — was the
+    // TITLE, which is not a path, while the addressable name hid in brackets.
+    // `wiki ls` printed the slug all along, so the two views of one directory
+    // disagreed about what each page was called, and `tree` put the wrong one
+    // first. The title still shows when it differs, because a page whose display
+    // name has drifted from its slug is worth seeing.
+    const slug = node.slug || node.name;
+    const title = node.name && node.name !== slug ? `  [${node.name}]` : '';
+    return `${slug}${title}`;
+}
+function sortNodes(nodes) {
+    return [...nodes].sort((a, b) => {
+        if (a.type === 'folder' && b.type !== 'folder')
+            return -1;
+        if (a.type !== 'folder' && b.type === 'folder')
+            return 1;
+        if ((a.order ?? 0) !== (b.order ?? 0))
+            return (a.order ?? 0) - (b.order ?? 0);
+        return a.name.localeCompare(b.name);
+    });
+}
+/** Split `A/B/c` into `{ dir: 'A/B', name: 'c' }` — the `dirname`/`basename` pair. */
+function splitParentPath(path) {
+    const segments = String(path)
+        .split('/')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const name = segments.pop() ?? '';
+    return { dir: segments.join('/'), name };
+}
+/**
+ * A one-line hint printed after `wiki mv` renames a page whose title was never
+ * authored. (OSK-4842)
+ *
+ * `mv` owns the path and `update` owns the title, by design — see mv.ts. A page
+ * written with no `--title` defaults its title to the slug it was born with, so
+ * after a rename that default title still spells the OLD name: `tree` shows
+ * `new  [old]` and `search` still calls it `old`. We cannot silently retitle
+ * (the two are deliberately separate operations), but a user who typed no title
+ * should not have to discover the second command on their own.
+ *
+ * Returns `null` unless the title still equals the OLD slug AND the slug
+ * actually changed — an authored title, or a move that did not rename, gets no
+ * hint.
+ */
+function retitleAfterMoveHint(opts) {
+    const { oldSlug, newSlug, title, binName, spaceId, newPath } = opts;
+    if (!oldSlug || !newSlug || newSlug === oldSlug)
+        return null;
+    if (title !== oldSlug)
+        return null;
+    return (`Title is still '${title}' — mv renames the path, not the title, so tree and ` +
+        `search still show the old name. Run \`${binName} wiki update ${spaceId} ${newPath} ` +
+        `--title <name>\` to change it.`);
+}
+/** Normalize a user-supplied path: trim segments, drop empties, no leading slash. */
+function normalizeWikiPath(path) {
+    return String(path)
+        .split('/')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join('/');
+}
+/**
+ * Resolve a folder path to its id, or `null` when no folder sits at that path.
+ *
+ * `ls` already returns the id of the directory it listed, so a lookup is one
+ * request and needs no client-side tree walk. The root (`''`) is deliberately
+ * NOT resolvable to an id — it is not a folder anyone can address or delete.
+ */
+async function resolveWikiFolderId(spaceId, path, ls, isNotFound) {
+    const normalized = normalizeWikiPath(path);
+    if (!normalized)
+        return null;
+    try {
+        const listing = await ls(spaceId, { path: normalized, includeFiles: false });
+        return listing.folder_id ?? null;
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+}