@skrr-ai/cli 0.1.8

package/dist/lib/slack-tools.d.ts

@@ -0,0 +1,97 @@
+type QueryValue = string | number | boolean | null | undefined;
+type SlackToolName = 'catalog' | 'channels' | 'users' | 'usergroups' | 'messages' | 'thread' | 'search';
+export declare function slackToolPath(agentId: string, tool: SlackToolName, params?: Record<string, QueryValue>): string;
+export declare function getSlackTool<T>(agentId: string, tool: SlackToolName, params?: Record<string, QueryValue>): Promise<T>;
+export declare function invokeSlackTool<T>(agentId: string, toolName: string, input?: Record<string, unknown>): Promise<T>;
+export type SlackToolResponseMetadata = {
+    nextCursor?: string | null;
+};
+export type SlackToolChannel = {
+    id: string;
+    name?: string;
+    displayName?: string;
+    isPrivate?: boolean;
+    isIm?: boolean;
+    isMpim?: boolean;
+    isMember?: boolean;
+    memberCount?: number;
+    allowed?: boolean;
+    accessReason?: string | null;
+    configured?: boolean;
+};
+export type SlackToolUser = {
+    id: string;
+    name?: string;
+    realName?: string;
+    displayName?: string;
+    isBot?: boolean;
+    isAppUser?: boolean;
+    isDeleted?: boolean;
+    allowed?: boolean;
+    accessReason?: string | null;
+};
+export type SlackToolMessage = {
+    ts: string;
+    threadTs?: string;
+    user?: string;
+    botId?: string;
+    text?: string;
+    subtype?: string;
+    isBot?: boolean;
+    replyCount?: number;
+};
+export type SlackChannelsResult = {
+    ok: boolean;
+    channels: SlackToolChannel[];
+    responseMetadata?: SlackToolResponseMetadata;
+};
+export type SlackUsersResult = {
+    ok: boolean;
+    users: SlackToolUser[];
+    responseMetadata?: SlackToolResponseMetadata;
+};
+export type SlackMessagesResult = {
+    ok: boolean;
+    channelId?: string;
+    threadTs?: string;
+    messages: SlackToolMessage[];
+    hasMore?: boolean;
+    responseMetadata?: SlackToolResponseMetadata;
+};
+export type SlackToolUserGroup = {
+    id: string;
+    handle?: string;
+    name?: string;
+    description?: string;
+    isExternal?: boolean;
+    isDisabled?: boolean;
+    userCount?: number;
+    users?: string[];
+};
+export type SlackUserGroupsResult = {
+    ok: boolean;
+    usergroups: SlackToolUserGroup[];
+};
+export type SlackSearchMatch = {
+    ts: string;
+    text?: string;
+    user?: string;
+    username?: string;
+    channelId?: string;
+    channelName?: string;
+    permalink?: string;
+    allowed?: boolean;
+    accessReason?: string | null;
+};
+export type SlackSearchResult = {
+    ok: boolean;
+    query?: string;
+    matches: SlackSearchMatch[];
+    total?: number;
+    pagination?: unknown;
+};
+export declare function printNextCursor(nextCursor: string | null | undefined, log: (line: string) => void): void;
+export declare function channelKind(channel: SlackToolChannel): string;
+export declare function yesNo(value: unknown): string;
+export declare function messageAuthor(message: SlackToolMessage): string;
+export {};

package/dist/lib/slack-tools.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slackToolPath = slackToolPath;
+exports.getSlackTool = getSlackTool;
+exports.invokeSlackTool = invokeSlackTool;
+exports.printNextCursor = printNextCursor;
+exports.channelKind = channelKind;
+exports.yesNo = yesNo;
+exports.messageAuthor = messageAuthor;
+const data_provider_1 = require("@skrr-ai/data-provider");
+function buildQuery(params) {
+    const query = Object.entries(params)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join('&');
+    return query ? `?${query}` : '';
+}
+function slackToolPath(agentId, tool, params = {}) {
+    const base = `/api/slack/agents/${encodeURIComponent(agentId)}/tools`;
+    return `${tool === 'catalog' ? base : `${base}/${tool}`}${buildQuery(params)}`;
+}
+async function getSlackTool(agentId, tool, params = {}) {
+    return data_provider_1.request.get(slackToolPath(agentId, tool, params));
+}
+async function invokeSlackTool(agentId, toolName, input = {}) {
+    return data_provider_1.request.post(`/api/slack/agents/${encodeURIComponent(agentId)}/tools/${encodeURIComponent(toolName)}/invoke`, input);
+}
+function printNextCursor(nextCursor, log) {
+    if (nextCursor) {
+        log(`Next cursor: ${nextCursor}`);
+    }
+}
+function channelKind(channel) {
+    if (channel.isIm)
+        return 'im';
+    if (channel.isMpim)
+        return 'mpim';
+    if (channel.isPrivate)
+        return 'private';
+    return 'public';
+}
+function yesNo(value) {
+    return value ? 'yes' : 'no';
+}
+function messageAuthor(message) {
+    return message.user || message.botId || (message.isBot ? 'bot' : '-');
+}

package/dist/lib/space-argument.d.ts

@@ -0,0 +1,32 @@
+/**
+ * space-argument.ts — accept a space given either way.
+ *
+ * Across the CLI there IS a rule about how a space is passed, and it is almost
+ * true: `spaces` (51 of 52) and `wiki` (10 of 10) take it as a positional,
+ * because there the space is the SUBJECT of the command; every other topic
+ * takes `--space`. `projects` was the exception that made the rule unlearnable
+ * — 15 of its 19 commands take `--space` while four took a positional, so
+ * `skrr projects create <SPACE>` sat beside `skrr projects archive --space` in
+ * one topic.
+ *
+ * Those four now accept both. Adding the majority form rather than renaming
+ * keeps every existing invocation working: the positional is what the help has
+ * always documented and what scripts pass.
+ */
+export interface SpaceArgumentInput {
+    positional?: string;
+    flag?: string;
+    /** When false, resolving nothing is legal (a cross-space listing). */
+    required?: boolean;
+}
+export declare class SpaceArgumentError extends Error {
+}
+/**
+ * Pick the space reference from whichever form was used.
+ *
+ * Giving BOTH is an error rather than a precedence rule. Silently preferring
+ * one would let `skrr projects create A --space B` write into a space the
+ * caller did not name last, and no ordering of that is more defensible than
+ * refusing.
+ */
+export declare function resolveSpaceArgument(input: SpaceArgumentInput): string | undefined;

package/dist/lib/space-argument.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * space-argument.ts — accept a space given either way.
+ *
+ * Across the CLI there IS a rule about how a space is passed, and it is almost
+ * true: `spaces` (51 of 52) and `wiki` (10 of 10) take it as a positional,
+ * because there the space is the SUBJECT of the command; every other topic
+ * takes `--space`. `projects` was the exception that made the rule unlearnable
+ * — 15 of its 19 commands take `--space` while four took a positional, so
+ * `skrr projects create <SPACE>` sat beside `skrr projects archive --space` in
+ * one topic.
+ *
+ * Those four now accept both. Adding the majority form rather than renaming
+ * keeps every existing invocation working: the positional is what the help has
+ * always documented and what scripts pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpaceArgumentError = void 0;
+exports.resolveSpaceArgument = resolveSpaceArgument;
+class SpaceArgumentError extends Error {
+}
+exports.SpaceArgumentError = SpaceArgumentError;
+/**
+ * Pick the space reference from whichever form was used.
+ *
+ * Giving BOTH is an error rather than a precedence rule. Silently preferring
+ * one would let `skrr projects create A --space B` write into a space the
+ * caller did not name last, and no ordering of that is more defensible than
+ * refusing.
+ */
+function resolveSpaceArgument(input) {
+    const { positional, flag, required = true } = input;
+    const pos = positional?.trim() || undefined;
+    const fl = flag?.trim() || undefined;
+    if (pos && fl && pos !== fl) {
+        throw new SpaceArgumentError(`Two different spaces given: \`${pos}\` positionally and \`--space ${fl}\`. Pass one.`);
+    }
+    const chosen = pos ?? fl;
+    if (!chosen && required) {
+        throw new SpaceArgumentError('A space is required. Pass it as `--space <id>` or as the first argument.');
+    }
+    return chosen;
+}

package/dist/lib/space-members.d.ts

@@ -0,0 +1,7 @@
+import { AccessRoleIds, PrincipalType } from '@skrr-ai/data-provider';
+export type SpaceMemberKind = 'user' | 'agent';
+export type SpaceMemberRole = 'viewer' | 'editor' | 'owner';
+export declare function spaceRoleId(role: SpaceMemberRole): AccessRoleIds;
+export declare function spaceRoleLabel(accessRoleId?: string): string;
+export declare function principalType(kind: SpaceMemberKind): PrincipalType;
+export declare function principalIdForDisplay(principal: Record<string, unknown>): string;

package/dist/lib/space-members.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spaceRoleId = spaceRoleId;
+exports.spaceRoleLabel = spaceRoleLabel;
+exports.principalType = principalType;
+exports.principalIdForDisplay = principalIdForDisplay;
+const data_provider_1 = require("@skrr-ai/data-provider");
+function spaceRoleId(role) {
+    switch (role) {
+        case 'owner':
+            return data_provider_1.AccessRoleIds.SPACE_OWNER;
+        case 'editor':
+            return data_provider_1.AccessRoleIds.SPACE_EDITOR;
+        case 'viewer':
+        default:
+            return data_provider_1.AccessRoleIds.SPACE_VIEWER;
+    }
+}
+function spaceRoleLabel(accessRoleId) {
+    switch (accessRoleId) {
+        case data_provider_1.AccessRoleIds.SPACE_OWNER:
+            return 'owner';
+        case data_provider_1.AccessRoleIds.SPACE_EDITOR:
+            return 'editor';
+        case data_provider_1.AccessRoleIds.SPACE_VIEWER:
+            return 'viewer';
+        default:
+            return accessRoleId || '-';
+    }
+}
+function principalType(kind) {
+    return kind === 'agent' ? data_provider_1.PrincipalType.AGENT : data_provider_1.PrincipalType.USER;
+}
+function principalIdForDisplay(principal) {
+    if (principal.type === data_provider_1.PrincipalType.AGENT && typeof principal.idOnTheSource === 'string') {
+        return principal.idOnTheSource;
+    }
+    return String(principal.id ?? principal.idOnTheSource ?? '-');
+}

package/dist/lib/space-output.d.ts

@@ -0,0 +1,28 @@
+export type SpacePerspective = 'dashboard' | 'tasks' | 'room' | 'goals' | 'schedule' | 'actions' | 'files' | 'widgets' | 'skills' | 'members' | 'execution' | 'workflows' | 'live' | 'settings';
+export declare function spacePerspectiveUrl(baseURL: string, spaceId: string, perspective: SpacePerspective): string;
+export declare function withSpacePerspectiveUrl<T extends Record<string, unknown>>(baseURL: string, spaceId: string, perspective: SpacePerspective, value: T): T & {
+    url: string;
+    next_command: string;
+};
+export declare function withSpaceResourceUrls(baseURL: string, spaceId: string, perspective: SpacePerspective, response: unknown, idKeys?: string[], itemUrl?: (id: string) => string): unknown;
+export declare function withSpaceUrlIfEntity(baseURL: string, value: Record<string, unknown>): Record<string, unknown> & {
+    url: string | null;
+};
+/**
+ * Attach an OPENABLE workflow link, not just the tab it lives on.
+ *
+ * `withSpacePerspectiveUrl(..., 'workflows', ...)` returns
+ * `/spaces/:id/workflows` for every workflow command, so `workflows show` and
+ * `workflows runs` hand back the same URL — one that opens a list and names
+ * nothing. The Workflows tab already selects by `?workflowId=` / `?runId=` /
+ * `?nodeKey=`; this is the CLI half of that contract.
+ */
+export declare function withWorkflowUrl<T extends Record<string, unknown>>(baseURL: string, spaceId: string, value: T, ref?: {
+    workflowId?: string | null;
+    runId?: string | null;
+    nodeKey?: string | null;
+}): T & {
+    url: string;
+    next_command: string;
+};
+export declare function nextSpaceCommand(spaceId: string, perspective: SpacePerspective): string;

package/dist/lib/space-output.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spacePerspectiveUrl = spacePerspectiveUrl;
+exports.withSpacePerspectiveUrl = withSpacePerspectiveUrl;
+exports.withSpaceResourceUrls = withSpaceResourceUrls;
+exports.withSpaceUrlIfEntity = withSpaceUrlIfEntity;
+exports.withWorkflowUrl = withWorkflowUrl;
+exports.nextSpaceCommand = nextSpaceCommand;
+const web_url_1 = require("./web-url");
+function spacePerspectiveUrl(baseURL, spaceId, perspective) {
+    return `${(0, web_url_1.webUrl)(baseURL, { kind: 'space', spaceId }) ?? ''}/${perspective}`;
+}
+function withSpacePerspectiveUrl(baseURL, spaceId, perspective, value) {
+    return {
+        ...value,
+        url: spacePerspectiveUrl(baseURL, spaceId, perspective),
+        next_command: nextSpaceCommand(spaceId, perspective),
+    };
+}
+function withSpaceResourceUrls(baseURL, spaceId, perspective, response, idKeys = ['id', '_id'], itemUrl) {
+    const enrich = (item) => {
+        if (!item || typeof item !== 'object')
+            return item;
+        const record = item;
+        const id = idKeys
+            .map((key) => record[key])
+            .find((candidate) => typeof candidate === 'string' && candidate);
+        return {
+            ...record,
+            url: id
+                ? itemUrl
+                    ? itemUrl(String(id))
+                    : `${spacePerspectiveUrl(baseURL, spaceId, perspective)}${perspective === 'tasks' ? `/${encodeURIComponent(String(id))}` : ''}`
+                : spacePerspectiveUrl(baseURL, spaceId, perspective),
+        };
+    };
+    if (Array.isArray(response))
+        return response.map(enrich);
+    if (!response || typeof response !== 'object')
+        return response;
+    const record = response;
+    if (Array.isArray(record.data))
+        return {
+            ...record,
+            data: record.data.map(enrich),
+            url: spacePerspectiveUrl(baseURL, spaceId, perspective),
+            next_command: nextSpaceCommand(spaceId, perspective),
+        };
+    if (Array.isArray(record.widgets))
+        return {
+            ...record,
+            widgets: record.widgets.map(enrich),
+            url: spacePerspectiveUrl(baseURL, spaceId, perspective),
+            next_command: nextSpaceCommand(spaceId, perspective),
+        };
+    return {
+        ...record,
+        url: spacePerspectiveUrl(baseURL, spaceId, perspective),
+        next_command: nextSpaceCommand(spaceId, perspective),
+    };
+}
+function withSpaceUrlIfEntity(baseURL, value) {
+    return { ...value, url: (0, web_url_1.spaceUrlFrom)(baseURL, value) };
+}
+/**
+ * Attach an OPENABLE workflow link, not just the tab it lives on.
+ *
+ * `withSpacePerspectiveUrl(..., 'workflows', ...)` returns
+ * `/spaces/:id/workflows` for every workflow command, so `workflows show` and
+ * `workflows runs` hand back the same URL — one that opens a list and names
+ * nothing. The Workflows tab already selects by `?workflowId=` / `?runId=` /
+ * `?nodeKey=`; this is the CLI half of that contract.
+ */
+function withWorkflowUrl(baseURL, spaceId, value, ref = {}) {
+    return {
+        ...value,
+        url: (0, web_url_1.webUrl)(baseURL, { kind: 'workflow', spaceId, ...ref }) ?? '',
+        next_command: ref.runId
+            ? `skrr spaces workflows run ${spaceId} ${ref.runId} --json`
+            : ref.workflowId
+                ? `skrr spaces workflows show ${spaceId} ${ref.workflowId} --json`
+                : nextSpaceCommand(spaceId, 'workflows'),
+    };
+}
+function nextSpaceCommand(spaceId, perspective) {
+    const commands = {
+        dashboard: `skrr spaces summary ${spaceId} --json`,
+        tasks: `skrr tasks list --space ${spaceId} --json`,
+        room: `skrr spaces room show ${spaceId} --json`,
+        goals: `skrr spaces goals ${spaceId} --json`,
+        schedule: `skrr spaces triggers show ${spaceId} --json`,
+        actions: `skrr spaces actions list ${spaceId} --json`,
+        files: `skrr spaces files list ${spaceId} --json`,
+        widgets: `skrr spaces widgets list ${spaceId} --json`,
+        skills: `skrr spaces skills list ${spaceId} --json`,
+        members: `skrr spaces members list ${spaceId} --json`,
+        execution: `skrr spaces capacity ${spaceId} --json`,
+        workflows: `skrr spaces workflows list ${spaceId} --json`,
+        live: `skrr spaces live cards list ${spaceId} --json`,
+        settings: `skrr spaces show ${spaceId} --json`,
+    };
+    return commands[perspective];
+}

package/dist/lib/space-resolver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Space reference resolution — turn what a person typed into exactly one
+ * space id, or an actionable failure.
+ *
+ * Every `--space` flag in the CLI (35 commands at last count) took a raw UUID
+ * and nothing else. Passing a name did not error — it filtered on a UUID that
+ * matches no space and returned an empty result:
+ *
+ *     skrr tasks list --space "Always on"     →     "No tasks."
+ *
+ * A person retries. An agent concludes the space is empty and proceeds on a
+ * false premise, which is the failure mode this module exists to remove. The
+ * contract is deliberately narrow: a value that already looks like an id is
+ * forwarded untouched (no request, no behavior change for existing scripts);
+ * anything else must resolve to exactly one space or the command fails.
+ *
+ * Modeled on `assignee-resolver.ts`, which already does this for people and
+ * agents — `--assignee-user frank` has worked for a while. Spaces were the
+ * outlier, not the exception.
+ */
+export type SpaceRef = {
+    /** The space UUID — what every `--space` flag ultimately wants. */
+    id: string;
+    /** The human-readable ref, e.g. `OSK-S-12`. Absent on spaces not yet backfilled. */
+    identifier?: string;
+    title?: string;
+    status?: string;
+    archived?: boolean;
+};
+export type SpaceResolutionFailure = {
+    ok: false;
+    /**
+     * NOT_FOUND — nothing matched, and nothing archived matched either.
+     * AMBIGUOUS — several equally-good matches; refusing to guess.
+     * ARCHIVED  — the only matches are archived, which the default listing
+     *             hides. Distinct from NOT_FOUND because the fix is different:
+     *             pass --include-archived (or the id), not a different name.
+     */
+    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'ARCHIVED';
+    query: string;
+    candidates: SpaceRef[];
+};
+export type SpaceResolution = {
+    ok: true;
+    space: SpaceRef;
+} | SpaceResolutionFailure;
+/**
+ * Does this already look like something the API can consume directly?
+ *
+ * Accepts the UUID `id` (canonical) and a 24-hex Mongo `_id`, because some
+ * callers hold the latter. Both are passed through untouched — the point of
+ * this check is that adding name resolution must not change the behavior of
+ * a single existing invocation.
+ */
+export declare function looksLikeSpaceId(value: string): boolean;
+/**
+ * Does this already identify the canonical storage row?
+ *
+ * Human-readable refs deliberately do not qualify here. Some read endpoints
+ * resolve `OSK-S-12` server-side, but space-scoped mutation routes require the
+ * UUID. Callers that need a value safe for every endpoint must resolve refs to
+ * their canonical id first.
+ */
+export declare function looksLikeCanonicalSpaceId(value: string): boolean;
+/** Normalize a space ref to the casing the server matches (`osk-s-3` → `OSK-S-3`). */
+export declare function normalizeSpaceRef(value: string): string;
+/** Map a raw space document from the API onto the shape we match against. */
+export declare function spaceRefFrom(doc: Record<string, unknown>): SpaceRef | null;
+/**
+ * Resolve `query` against `spaces`, narrowest match first.
+ *
+ * The tiers matter because the server-side `q` is a substring match: asking
+ * for "Dogfood" against a workspace holding "Dogfood Lab", "Dogfood Bugs" and
+ * a space named exactly "Dogfood" comes back with three rows, and only the
+ * exact-title tier makes that unambiguous. A tier matching nothing falls
+ * through; a tier matching more than one stops and reports AMBIGUOUS rather
+ * than picking — silently operating on the wrong space is the thing we are
+ * here to prevent, and it is worse than making the caller be specific.
+ */
+export declare function resolveSpaceRef(query: string, spaces: SpaceRef[]): SpaceResolution;
+export declare function describeSpace(s: SpaceRef): string;
+/** Render the candidate list for an error message, bounded so it stays readable. */
+export declare function describeSpaceCandidates(candidates: SpaceRef[], limit?: number): string;
+/** One human-readable block per failure, suitable for a CLI error body. */
+export declare function formatSpaceResolutionFailure(failure: SpaceResolutionFailure, bin?: string): string;
+export declare const SPACE_CLI_ERROR_CODE: Record<SpaceResolutionFailure['code'], string>;

package/dist/lib/space-resolver.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Space reference resolution — turn what a person typed into exactly one
+ * space id, or an actionable failure.
+ *
+ * Every `--space` flag in the CLI (35 commands at last count) took a raw UUID
+ * and nothing else. Passing a name did not error — it filtered on a UUID that
+ * matches no space and returned an empty result:
+ *
+ *     skrr tasks list --space "Always on"     →     "No tasks."
+ *
+ * A person retries. An agent concludes the space is empty and proceeds on a
+ * false premise, which is the failure mode this module exists to remove. The
+ * contract is deliberately narrow: a value that already looks like an id is
+ * forwarded untouched (no request, no behavior change for existing scripts);
+ * anything else must resolve to exactly one space or the command fails.
+ *
+ * Modeled on `assignee-resolver.ts`, which already does this for people and
+ * agents — `--assignee-user frank` has worked for a while. Spaces were the
+ * outlier, not the exception.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACE_CLI_ERROR_CODE = void 0;
+exports.looksLikeSpaceId = looksLikeSpaceId;
+exports.looksLikeCanonicalSpaceId = looksLikeCanonicalSpaceId;
+exports.normalizeSpaceRef = normalizeSpaceRef;
+exports.spaceRefFrom = spaceRefFrom;
+exports.resolveSpaceRef = resolveSpaceRef;
+exports.describeSpace = describeSpace;
+exports.describeSpaceCandidates = describeSpaceCandidates;
+exports.formatSpaceResolutionFailure = formatSpaceResolutionFailure;
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const OBJECT_ID_RE = /^[0-9a-fA-F]{24}$/;
+/**
+ * The human-readable space ref, e.g. `OSK-S-12`. Resolved server-side.
+ * Case-insensitive so `osk-s-12` is recognized and normalized rather than
+ * falling through to a title search that can never match it.
+ */
+const SPACE_IDENTIFIER_RE = /^[A-Za-z]+-S-\d+$/i;
+/**
+ * Does this already look like something the API can consume directly?
+ *
+ * Accepts the UUID `id` (canonical) and a 24-hex Mongo `_id`, because some
+ * callers hold the latter. Both are passed through untouched — the point of
+ * this check is that adding name resolution must not change the behavior of
+ * a single existing invocation.
+ */
+function looksLikeSpaceId(value) {
+    const v = value.trim();
+    // The ref is included because `getSpace` resolves it server-side, exactly as
+    // it does for `OSK-2423` on tasks — sending it through a title search would
+    // find nothing.
+    return UUID_RE.test(v) || OBJECT_ID_RE.test(v) || SPACE_IDENTIFIER_RE.test(v);
+}
+/**
+ * Does this already identify the canonical storage row?
+ *
+ * Human-readable refs deliberately do not qualify here. Some read endpoints
+ * resolve `OSK-S-12` server-side, but space-scoped mutation routes require the
+ * UUID. Callers that need a value safe for every endpoint must resolve refs to
+ * their canonical id first.
+ */
+function looksLikeCanonicalSpaceId(value) {
+    const v = value.trim();
+    return UUID_RE.test(v) || OBJECT_ID_RE.test(v);
+}
+/** Normalize a space ref to the casing the server matches (`osk-s-3` → `OSK-S-3`). */
+function normalizeSpaceRef(value) {
+    const v = value.trim();
+    return SPACE_IDENTIFIER_RE.test(v) ? v.toUpperCase() : v;
+}
+function norm(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+/** A string field, or '' — so absent and wrong-typed collapse to one falsy case. */
+function str(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** Map a raw space document from the API onto the shape we match against. */
+function spaceRefFrom(doc) {
+    const id = str(doc.id) || str(doc._id);
+    if (!id)
+        return null;
+    return {
+        id,
+        identifier: typeof doc.identifier === 'string' ? doc.identifier : undefined,
+        title: typeof doc.title === 'string' ? doc.title : undefined,
+        status: typeof doc.status === 'string' ? doc.status : undefined,
+        archived: Boolean(doc.archivedAt),
+    };
+}
+/**
+ * Resolve `query` against `spaces`, narrowest match first.
+ *
+ * The tiers matter because the server-side `q` is a substring match: asking
+ * for "Dogfood" against a workspace holding "Dogfood Lab", "Dogfood Bugs" and
+ * a space named exactly "Dogfood" comes back with three rows, and only the
+ * exact-title tier makes that unambiguous. A tier matching nothing falls
+ * through; a tier matching more than one stops and reports AMBIGUOUS rather
+ * than picking — silently operating on the wrong space is the thing we are
+ * here to prevent, and it is worse than making the caller be specific.
+ */
+function resolveSpaceRef(query, spaces) {
+    const raw = query.trim();
+    const q = norm(raw);
+    if (!q) {
+        return { ok: false, code: 'NOT_FOUND', query: raw, candidates: spaces };
+    }
+    // An exact id or ref wins over everything, archived or not: both are
+    // explicit and unambiguous, so there is nothing to protect the caller from.
+    // Names are matched against live spaces only — see the ARCHIVED branch.
+    const byId = spaces.filter((s) => s.id === raw || norm(s.identifier) === q);
+    if (byId.length === 1)
+        return { ok: true, space: byId[0] };
+    const live = spaces.filter((s) => !s.archived);
+    const tiers = [
+        // 1. Exact title.
+        (s) => norm(s.title) === q,
+        // 2. Title prefix ("dogfood l" → "Dogfood Lab — Standing").
+        (s) => norm(s.title).startsWith(q),
+        // 3. Anywhere in the title.
+        (s) => norm(s.title).includes(q),
+    ];
+    for (const match of tiers) {
+        const hits = live.filter(match);
+        if (hits.length === 1)
+            return { ok: true, space: hits[0] };
+        if (hits.length > 1) {
+            return { ok: false, code: 'AMBIGUOUS', query: raw, candidates: hits };
+        }
+    }
+    // Nothing live matched. If the only matches are archived, say so — the
+    // caller's name was right and telling them "not found" would send them
+    // looking for a typo that isn't there.
+    const archivedHits = spaces.filter((s) => s.archived && norm(s.title).includes(q));
+    if (archivedHits.length > 0) {
+        return { ok: false, code: 'ARCHIVED', query: raw, candidates: archivedHits };
+    }
+    return { ok: false, code: 'NOT_FOUND', query: raw, candidates: spaces };
+}
+function describeSpace(s) {
+    // Lead with the ref when there is one — it is the short thing a person can
+    // type back, the same role `OSK-2423` plays for tasks.
+    const ref = s.identifier ? `${s.identifier} ` : '';
+    const label = s.title || s.id;
+    const marks = [s.status, s.archived ? 'archived' : null].filter(Boolean).join(', ');
+    return `${ref}${label} (${s.id})${marks ? ` — ${marks}` : ''}`;
+}
+/** Render the candidate list for an error message, bounded so it stays readable. */
+function describeSpaceCandidates(candidates, limit = 10) {
+    if (candidates.length === 0)
+        return '';
+    const shown = candidates.slice(0, limit).map((s) => `  - ${describeSpace(s)}`);
+    if (candidates.length > limit) {
+        shown.push(`  … and ${candidates.length - limit} more`);
+    }
+    return shown.join('\n');
+}
+/** One human-readable block per failure, suitable for a CLI error body. */
+function formatSpaceResolutionFailure(failure, bin = 'skrr') {
+    switch (failure.code) {
+        case 'AMBIGUOUS':
+            return (`"${failure.query}" matches ${failure.candidates.length} spaces:\n` +
+                `${describeSpaceCandidates(failure.candidates)}\n` +
+                `  → use the full title or the space id to disambiguate.`);
+        case 'ARCHIVED':
+            return (`"${failure.query}" only matches archived spaces:\n` +
+                `${describeSpaceCandidates(failure.candidates)}\n` +
+                `  → pass the space id directly, or unarchive it with ` +
+                `\`${bin} spaces unarchive <space-id>\`.`);
+        default:
+            return (`No space matching "${failure.query}".\n` +
+                `  → list what you can see with \`${bin} spaces list\`, ` +
+                `or search with \`${bin} spaces list --q "${failure.query}"\`.`);
+    }
+}
+exports.SPACE_CLI_ERROR_CODE = {
+    AMBIGUOUS: 'SPACE_AMBIGUOUS',
+    ARCHIVED: 'SPACE_ARCHIVED',
+    NOT_FOUND: 'SPACE_NOT_FOUND',
+};