@love-moon/conductor-sdk 0.2.42 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# @love-moon/conductor-sdk
+
+## 0.3.1
+
+### Patch Changes
+
+- 4e8d4e5: Include `CHANGELOG.md` in published npm tarballs.
+
+  The `files` array in each package's `package.json` previously only
+  listed the build output (`bin`/`src` for the CLI, `dist` for the
+  modules). npm's `files` whitelist replaces the default include set,
+  and CHANGELOG is not one of the auto-included files (only
+  `package.json`, `README*`, `LICENSE*`, and `main` are unconditional).
+
+  As a result, every release through 0.3.0 published tarballs with no
+  CHANGELOG, so a consumer running `npm install` or unpacking the brew
+  artifact had no way to see what changed in the version they just
+  installed. The repo `cli/CHANGELOG.md` and the GitHub Release body
+  remain the canonical source until 0.3.1 ships with this fix.
+
+## 0.3.0
+
+### Minor Changes
+
+- be3b3cb: Project list now merges same-name git projects that share a remote URL across daemons into a single card.
+
+  - `ProjectContext.snapshot()` (SDK) now captures the origin remote URL via `git config --get remote.origin.url` and exposes a `normalizeGitRemoteUrl` helper for callers that need their own equality comparison.
+  - The daemon's `validate_project_path` response carries a new `git_remote_url` field. Old daemons that don't send it stay forward-compatible — the web server treats missing values as "unmergeable" so projects from those daemons render standalone until they're refreshed.
+  - New web API surface:
+    - `PATCH /api/projects { mergeOptOut: true }` opts a project out of auto-grouping (manual split for accidental name collisions).
+    - `PATCH /api/projects { refresh: true }` re-runs the daemon validation handshake and back-fills `git_remote_url` for projects created before this feature.
+    - `GET /api/issues?project_ids=a,b` fetches issues from multiple projects in one call; responses include `daemonHost` + `projectName` for cross-daemon attribution.
+  - Schema: two new optional columns on `projects`: `git_remote_url` (nullable string) and `merge_opt_out` (boolean, default false). Run `pnpm -C web db:push` before upgrading.
+
+### Other Changes (retroactively documented)
+
+The following changes shipped in `@love-moon/conductor-sdk@0.3.0` but
+were merged without a `changeset` entry. See
+`claw/lessons/arch_release-packages-pnpm-changesets-20260512.md` for
+why this happened and the rule that every PR touching `modules/**`
+must run `npm run changeset`.
+
+- SDK helpers and types behind the new CLI `conductor project|issue|task`
+  entity commands (RFC 0025). Programs that already depended on SDK
+  project/issue/task surfaces gain a few stable convenience entry
+  points; callers using only the public client API see no change.
+  (`2e10756`)
+- Reconnect: the SDK client survives the daemon-side websocket
+  late-send-after-disconnect crash path (companion fix to the daemon
+  change in `@love-moon/conductor-cli@0.3.0`). (`a3532cc`)
+- Reconnect: stale `taskAttach` calls from a previously-bound fire
+  process no longer establish ghost bindings. (`dc73be9`)

package/dist/api/index.d.ts

@@ -0,0 +1,4 @@
+export { ProjectsApi, type Project, type CreateProjectInput, type ListProjectsOptions, type ResolveProjectInput, } from './projects.js';
+export { IssuesApi, type Issue, type ListIssuesInput, type CreateIssueInput, type UpdateIssueInput, type UpdateIssueStatusOptions, } from './issues.js';
+export { TasksApi, type Task, type Message, type ListTasksInput, type SendTaskMessageOptions, type ListTaskMessagesOptions, } from './tasks.js';
+export { ProjectNotResolvedError, buildAuditMetadata, isBackendApiError, type ApiClient, type SdkClientOptions, } from './shared.js';

package/dist/api/index.js

@@ -0,0 +1,4 @@
+export { ProjectsApi, } from './projects.js';
+export { IssuesApi, } from './issues.js';
+export { TasksApi, } from './tasks.js';
+export { ProjectNotResolvedError, buildAuditMetadata, isBackendApiError, } from './shared.js';

package/dist/api/issues.d.ts

@@ -0,0 +1,57 @@
+import { ApiClient, SdkClientOptions } from './shared.js';
+export interface Issue {
+    id: string;
+    projectId: string;
+    title: string;
+    description?: string | null;
+    status: string;
+    priority?: string | null;
+    position?: number | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    /** Unmodified server payload, used by callers that need fields we haven't typed. */
+    raw: Record<string, unknown>;
+}
+export interface ListIssuesInput {
+    projectId: string;
+    status?: string | string[];
+    limit?: number;
+}
+export interface CreateIssueInput {
+    projectId: string;
+    title: string;
+    description?: string;
+    priority?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+    clientRequestId?: string;
+}
+export interface UpdateIssueInput {
+    title?: string;
+    description?: string;
+    priority?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateIssueStatusOptions {
+    evidence?: string;
+    /**
+     * Extra metadata merged into the patch; caller's `audit.*` fields win over
+     * SDK defaults (see shared.ts). Useful for the CLI to thread its
+     * `audit: { actor: "cli", ... }` namespace through without needing a custom
+     * call path.
+     */
+    metadata?: Record<string, unknown>;
+}
+export declare class IssuesApi {
+    private readonly client;
+    private readonly options;
+    constructor(client: ApiClient, options?: SdkClientOptions);
+    listIssues(input: ListIssuesInput): Promise<Issue[]>;
+    getIssue(issueId: string): Promise<Issue>;
+    createIssue(input: CreateIssueInput): Promise<Issue>;
+    updateIssue(issueId: string, patch: UpdateIssueInput): Promise<Issue>;
+    updateIssueStatus(issueId: string, status: string, options?: UpdateIssueStatusOptions): Promise<Issue>;
+    deleteIssue(issueId: string): Promise<void>;
+}

package/dist/api/issues.js

@@ -0,0 +1,177 @@
+import { buildAuditMetadata } from './shared.js';
+const normalizeIssue = (payload) => {
+    const id = payload.id ? String(payload.id) : '';
+    if (!id) {
+        throw new Error('Issue payload missing id');
+    }
+    return {
+        id,
+        projectId: String(payload.projectId ?? payload.project_id ?? ''),
+        title: String(payload.title ?? ''),
+        description: payload.description ?? null,
+        status: String(payload.status ?? ''),
+        priority: payload.priority ?? null,
+        position: typeof payload.position === 'number' ? payload.position : null,
+        metadata: payload.metadata && typeof payload.metadata === 'object' && !Array.isArray(payload.metadata)
+            ? payload.metadata
+            : null,
+        createdAt: payload.createdAt ?? payload.created_at ?? null,
+        updatedAt: payload.updatedAt ?? payload.updated_at ?? null,
+        raw: payload,
+    };
+};
+const extractIssue = (payload) => {
+    // The PATCH /issues/[issueId] route returns `{ issue, activeTask, ... }`.
+    // Other routes return the issue itself. Normalize both shapes here so
+    // facade callers always get the issue back regardless of source endpoint.
+    if (payload && typeof payload === 'object' && payload.issue && typeof payload.issue === 'object') {
+        return payload.issue;
+    }
+    return payload;
+};
+const mergeMetadataAtPath = (target, pathParts, value) => {
+    if (pathParts.length === 0) {
+        return target;
+    }
+    const [head, ...rest] = pathParts;
+    const next = { ...target };
+    if (rest.length === 0) {
+        next[head] = value;
+        return next;
+    }
+    const existing = target[head];
+    const child = existing && typeof existing === 'object' && !Array.isArray(existing)
+        ? existing
+        : {};
+    next[head] = mergeMetadataAtPath(child, rest, value);
+    return next;
+};
+export class IssuesApi {
+    client;
+    options;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+    }
+    async listIssues(input) {
+        if (!input.projectId) {
+            throw new Error('projectId is required');
+        }
+        // The server `/api/issues` route accepts a single `status` query string;
+        // it doesn't (yet) parse comma-separated lists, so we filter on the
+        // client side for the multi-status case to match RFC 0025 §3 wording.
+        const statusFilter = Array.isArray(input.status)
+            ? input.status.map((value) => String(value).trim()).filter(Boolean)
+            : input.status
+                ? [String(input.status).trim()].filter(Boolean)
+                : [];
+        const issues = await this.client.listIssues({
+            projectId: input.projectId,
+            status: statusFilter.length === 1 ? statusFilter[0] : undefined,
+        });
+        let normalized = issues.map((entry) => normalizeIssue(entry));
+        if (statusFilter.length > 1) {
+            const statusSet = new Set(statusFilter);
+            normalized = normalized.filter((issue) => statusSet.has(issue.status));
+        }
+        if (typeof input.limit === 'number' && Number.isFinite(input.limit)) {
+            normalized = normalized.slice(0, Math.max(0, Math.floor(input.limit)));
+        }
+        return normalized;
+    }
+    async getIssue(issueId) {
+        const trimmed = String(issueId ?? '').trim();
+        if (!trimmed) {
+            throw new Error('issueId is required');
+        }
+        const payload = await this.client.getIssue(trimmed);
+        return normalizeIssue(extractIssue(payload));
+    }
+    async createIssue(input) {
+        if (!input.projectId) {
+            throw new Error('projectId is required');
+        }
+        if (!input.title) {
+            throw new Error('title is required');
+        }
+        const userMetadata = input.clientRequestId
+            ? { clientRequestId: input.clientRequestId, ...(input.metadata ?? {}) }
+            : input.metadata;
+        const metadata = buildAuditMetadata(userMetadata, this.options);
+        const params = {
+            projectId: input.projectId,
+            title: input.title,
+            metadata,
+        };
+        if (input.description !== undefined) {
+            params.description = input.description;
+        }
+        if (input.priority !== undefined) {
+            params.priority = input.priority;
+        }
+        if (input.status !== undefined) {
+            params.status = input.status;
+        }
+        const payload = await this.client.createIssue(params);
+        return normalizeIssue(extractIssue(payload));
+    }
+    async updateIssue(issueId, patch) {
+        const trimmed = String(issueId ?? '').trim();
+        if (!trimmed) {
+            throw new Error('issueId is required');
+        }
+        const params = {};
+        if (patch.title !== undefined) {
+            params.title = patch.title;
+        }
+        if (patch.description !== undefined) {
+            params.description = patch.description;
+        }
+        if (patch.priority !== undefined) {
+            params.priority = patch.priority;
+        }
+        if (patch.status !== undefined) {
+            params.status = patch.status;
+        }
+        // We always include audit metadata on writes. If the caller passes a
+        // `metadata` patch, we merge our audit keys with theirs (caller wins).
+        params.metadata = buildAuditMetadata(patch.metadata, this.options);
+        const payload = await this.client.patchIssue(trimmed, params);
+        return normalizeIssue(extractIssue(payload));
+    }
+    async updateIssueStatus(issueId, status, options = {}) {
+        const callerMetadata = options.metadata && typeof options.metadata === 'object' && !Array.isArray(options.metadata)
+            ? { ...options.metadata }
+            : null;
+        if (!options.evidence) {
+            return this.updateIssue(issueId, {
+                status,
+                ...(callerMetadata ? { metadata: callerMetadata } : {}),
+            });
+        }
+        // Pull the existing metadata so we can merge `qa.evidence` without
+        // clobbering unrelated keys. The PATCH body fully replaces metadata, so
+        // we have to round-trip the current state (matches RFC 0025 §3 wording
+        // for `done --evidence`).
+        const existing = await this.getIssue(issueId);
+        const existingMetadata = existing.metadata && typeof existing.metadata === 'object'
+            ? existing.metadata
+            : {};
+        // Merge order: existing DB metadata < caller's patch metadata < qa.evidence.
+        // The `audit` key under `callerMetadata` is preserved when present so the
+        // CLI's `actor:"cli"` namespace flows through to `updateIssue` (and from
+        // there to `buildAuditMetadata`, where caller wins).
+        const baseMetadata = callerMetadata
+            ? { ...existingMetadata, ...callerMetadata }
+            : { ...existingMetadata };
+        const merged = mergeMetadataAtPath(baseMetadata, ['qa', 'evidence'], options.evidence);
+        return this.updateIssue(issueId, { status, metadata: merged });
+    }
+    async deleteIssue(issueId) {
+        const trimmed = String(issueId ?? '').trim();
+        if (!trimmed) {
+            throw new Error('issueId is required');
+        }
+        await this.client.deleteIssue(trimmed);
+    }
+}

package/dist/api/projects.d.ts

@@ -0,0 +1,71 @@
+import { ApiClient, SdkClientOptions } from './shared.js';
+/**
+ * Project record as returned by the REST API. We deliberately don't subclass
+ * `ProjectSummary` here because the REST surface returns more fields (notably
+ * `hidden`, `isDefault`, `metadata`) than the WS-flavored summary, and we
+ * want CLI / AI consumers to see the full picture.
+ */
+export interface Project {
+    id: string;
+    name?: string | null;
+    daemonHost?: string | null;
+    workspacePath?: string | null;
+    repoRoot?: string | null;
+    worktreeBranch?: string | null;
+    lastCommit?: string | null;
+    fileCount?: number | null;
+    isDefault: boolean;
+    hidden: boolean;
+    hiddenAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    /**
+     * The unmodified server payload, kept for callers that need fields the
+     * typed surface hasn't promoted yet (e.g. `gitRemoteUrl`, `mergeOptOut`).
+     */
+    raw: Record<string, unknown>;
+}
+export interface ResolveProjectInput {
+    id?: string;
+    name?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Daemon host to use when resolving by `cwd`. Required for the path-match
+     * fallback (the server keys workspace bindings on `(daemonHost, path)`).
+     * Defaults to `env.CONDUCTOR_DAEMON_NAME` if unset.
+     */
+    daemonHost?: string;
+}
+export interface CreateProjectInput {
+    name?: string;
+    workspacePath?: string;
+    daemonHost?: string;
+    isDefault?: boolean;
+    clientRequestId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ListProjectsOptions {
+    includeHidden?: boolean;
+}
+export interface ProjectWriteOptions {
+    /**
+     * Extra metadata merged into the request (caller-supplied audit fields
+     * under `metadata.audit` win over the SDK defaults, see shared.ts).
+     */
+    metadata?: Record<string, unknown>;
+}
+export declare class ProjectsApi {
+    private readonly client;
+    private readonly options;
+    constructor(client: ApiClient, options?: SdkClientOptions);
+    listProjects(options?: ListProjectsOptions): Promise<Project[]>;
+    getProject(idOrName: string): Promise<Project>;
+    createProject(input: CreateProjectInput): Promise<Project>;
+    setDefaultProject(idOrName: string, options?: ProjectWriteOptions): Promise<Project>;
+    setProjectHidden(idOrName: string, hidden: boolean, options?: ProjectWriteOptions): Promise<Project>;
+    resolveProject(input?: ResolveProjectInput): Promise<Project>;
+    private findUniqueByName;
+    private resolveById;
+}

package/dist/api/projects.js

@@ -0,0 +1,247 @@
+import { BackendApiError } from '../backend/index.js';
+import { ProjectNotResolvedError, buildAuditMetadata, } from './shared.js';
+const stripTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * Heuristic for "this string looks like a project id, not a name".
+ *
+ * The server uses cuid-like ids (e.g. `clxk1y0fz0000abc123`) and UUIDs. Names
+ * are arbitrary strings, but in practice users name their projects with
+ * spaces, slashes, accents, etc. — i.e. they almost never match the
+ * `^[a-zA-Z0-9_-]{12,}$` shape we treat as an id below. This lets the SDK
+ * skip a redundant `getProject(id)` round-trip when the caller (CLI) has
+ * already resolved to an id (review L-NEW-1). On a miss we fall back to the
+ * full resolve, so the only downside of a false positive is one extra
+ * 404 → re-list round trip.
+ */
+const looksLikeProjectId = (value) => {
+    if (!value || typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (trimmed.length < 12)
+        return false;
+    return /^[A-Za-z0-9_-]+$/.test(trimmed);
+};
+/**
+ * Local longest-prefix match used by `resolveProject` step 4 when no daemon
+ * host is available to delegate to the server-side matcher. We treat each
+ * project's `workspacePath` as a prefix and pick the longest one that's a
+ * proper directory ancestor of `cwd`. Mirrors the server's
+ * match-path/route.ts logic for the simple single-daemon case.
+ */
+const matchProjectByLocalPrefix = (projects, cwd) => {
+    const target = stripTrailingSlash(cwd.trim());
+    if (!target)
+        return null;
+    let best = null;
+    for (const project of projects) {
+        const path = project.workspacePath;
+        if (typeof path !== 'string' || !path.trim())
+            continue;
+        const normalized = stripTrailingSlash(path.trim());
+        if (target === normalized || target.startsWith(`${normalized}/`)) {
+            if (!best || normalized.length > best.length) {
+                best = { project, length: normalized.length };
+            }
+        }
+    }
+    return best?.project ?? null;
+};
+const normalizeProject = (payload) => {
+    const id = payload.id ? String(payload.id) : '';
+    if (!id) {
+        throw new Error('Project payload missing id');
+    }
+    const hiddenAt = payload.hiddenAt ?? payload.hidden_at ?? null;
+    return {
+        id,
+        name: payload.name ?? null,
+        daemonHost: payload.daemonHost ?? payload.daemon_host ?? null,
+        workspacePath: payload.workspacePath ?? payload.workspace_path ?? null,
+        repoRoot: payload.repoRoot ?? payload.repo_root ?? null,
+        worktreeBranch: payload.worktreeBranch ?? payload.worktree_branch ?? null,
+        lastCommit: payload.lastCommit ?? payload.last_commit ?? null,
+        fileCount: payload.fileCount ?? payload.file_count ?? null,
+        isDefault: Boolean(payload.isDefault ?? payload.is_default ?? false),
+        hidden: Boolean(payload.hidden ?? Boolean(hiddenAt)),
+        hiddenAt: hiddenAt ?? null,
+        metadata: payload.metadata && typeof payload.metadata === 'object' && !Array.isArray(payload.metadata)
+            ? payload.metadata
+            : null,
+        createdAt: payload.createdAt ?? payload.created_at ?? null,
+        updatedAt: payload.updatedAt ?? payload.updated_at ?? null,
+        raw: payload,
+    };
+};
+export class ProjectsApi {
+    client;
+    options;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+    }
+    async listProjects(options = {}) {
+        const summaries = await this.client.listProjects();
+        // `BackendApiClient.listProjects` already pulls /projects, but it loses
+        // the `hidden` and `isDefault` fields when collapsing to ProjectSummary.
+        // Promote each summary's `asObject()` payload back to a Project so we
+        // surface those fields. Hidden projects are filtered out here unless
+        // `includeHidden: true` is passed (RFC 0025 §3).
+        const promoted = summaries.map((summary) => normalizeProject(
+        // ProjectSummary `asObject()` always exists in the backend module.
+        summary.asObject ? summary.asObject() : summary));
+        if (options.includeHidden) {
+            return promoted;
+        }
+        return promoted.filter((project) => !project.hidden);
+    }
+    async getProject(idOrName) {
+        const trimmed = String(idOrName ?? '').trim();
+        if (!trimmed) {
+            throw new Error('idOrName is required');
+        }
+        // First try by id; if 404, fall back to a unique name match against the
+        // project list. Splitting these two paths keeps the happy-path single
+        // round-trip and only pulls the full list on miss.
+        try {
+            const payload = await this.client.getProject(trimmed);
+            return normalizeProject(payload);
+        }
+        catch (error) {
+            if (!(error instanceof BackendApiError) || error.statusCode !== 404) {
+                throw error;
+            }
+        }
+        return this.findUniqueByName(trimmed);
+    }
+    async createProject(input) {
+        const metadata = buildAuditMetadata(
+        // `clientRequestId` is stamped onto metadata per RFC 0025 §5 idempotency
+        // spec; the server treats it as the idempotency key.
+        input.clientRequestId
+            ? { clientRequestId: input.clientRequestId, ...(input.metadata ?? {}) }
+            : input.metadata, this.options);
+        const params = {};
+        if (input.name) {
+            params.name = input.name;
+        }
+        if (input.isDefault) {
+            params.isDefault = true;
+            params.is_default = true;
+        }
+        else {
+            // Non-default projects need a binding. The server validates with the
+            // daemon synchronously when `daemonHost + workspacePath` are present,
+            // which is the path AI / CLI will use most of the time.
+            if (input.workspacePath) {
+                params.workspacePath = input.workspacePath;
+            }
+            if (input.daemonHost) {
+                params.daemonHost = input.daemonHost;
+            }
+        }
+        params.metadata = metadata;
+        const summary = await this.client.createProject(params);
+        return normalizeProject(summary.asObject ? summary.asObject() : summary);
+    }
+    async setDefaultProject(idOrName, options = {}) {
+        // Short-circuit the pre-flight `getProject` when the caller already has
+        // a project id (review L-NEW-1). On a miss the server returns 404 and
+        // the caller can retry via `getProject(idOrName)` themselves, but the
+        // common CLI path passes the id directly.
+        const targetId = looksLikeProjectId(idOrName) ? idOrName.trim() : (await this.resolveById(idOrName)).id;
+        const metadata = buildAuditMetadata(options.metadata, this.options);
+        const payload = await this.client.setDefaultProject(targetId, { metadata });
+        return normalizeProject(payload);
+    }
+    async setProjectHidden(idOrName, hidden, options = {}) {
+        const targetId = looksLikeProjectId(idOrName) ? idOrName.trim() : (await this.resolveById(idOrName)).id;
+        const metadata = buildAuditMetadata(options.metadata, this.options);
+        const payload = await this.client.patchProjectByQuery(targetId, { hidden, metadata });
+        return normalizeProject(payload);
+    }
+    async resolveProject(input = {}) {
+        const env = input.env ?? this.options.env ?? process.env;
+        // 1. explicit id wins
+        if (input.id && input.id.trim()) {
+            try {
+                const payload = await this.client.getProject(input.id.trim());
+                return normalizeProject(payload);
+            }
+            catch (error) {
+                if (error instanceof BackendApiError && error.statusCode === 404) {
+                    throw new ProjectNotResolvedError(`Project not found: id=${input.id}`, 'not_found');
+                }
+                throw error;
+            }
+        }
+        // 2. explicit name
+        if (input.name && input.name.trim()) {
+            return this.findUniqueByName(input.name.trim());
+        }
+        // 3. env override
+        const envId = env.CONDUCTOR_PROJECT_ID;
+        if (typeof envId === 'string' && envId.trim()) {
+            try {
+                const payload = await this.client.getProject(envId.trim());
+                return normalizeProject(payload);
+            }
+            catch (error) {
+                if (error instanceof BackendApiError && error.statusCode === 404) {
+                    throw new ProjectNotResolvedError(`Project not found from CONDUCTOR_PROJECT_ID=${envId}`, 'not_found');
+                }
+                throw error;
+            }
+        }
+        // 4. cwd path match. We try two routes:
+        //    a. If a daemon host is known, delegate to the server-side matcher
+        //       (it understands binding-pending / repoRoot / multi-daemon rules).
+        //    b. Otherwise, do a local longest-prefix match against the project
+        //       list. This keeps the CLI usable when the user hasn't set
+        //       CONDUCTOR_DAEMON_NAME — review finding M1: never silently skip
+        //       cwd resolution just because a daemon hint is missing.
+        const projects = await this.listProjects({ includeHidden: true });
+        if (input.cwd && input.cwd.trim()) {
+            const daemonHost = input.daemonHost ?? env.CONDUCTOR_DAEMON_NAME ?? env.CONDUCTOR_AGENT_NAME;
+            if (daemonHost && daemonHost.trim()) {
+                const result = await this.client.matchProjectByPath({
+                    daemon_host: daemonHost.trim(),
+                    path: input.cwd,
+                });
+                if (result.project) {
+                    return normalizeProject(result.project.asObject());
+                }
+            }
+            else {
+                const localMatch = matchProjectByLocalPrefix(projects, input.cwd);
+                if (localMatch) {
+                    return localMatch;
+                }
+            }
+        }
+        // 5. default project — derived from the list we already fetched in (4).
+        //    Every healthy account has at most one default; we return it when
+        //    found.
+        const defaults = projects.filter((project) => project.isDefault);
+        if (defaults.length === 1) {
+            return defaults[0];
+        }
+        if (defaults.length > 1) {
+            throw new ProjectNotResolvedError('Multiple default projects exist; specify --project explicitly', 'multiple_matches');
+        }
+        throw new ProjectNotResolvedError('No project specified and no default project found. Pass --project <id|name>, set CONDUCTOR_PROJECT_ID, cd into a project directory, or configure a default project.', 'no_signal');
+    }
+    async findUniqueByName(name) {
+        const projects = await this.listProjects({ includeHidden: true });
+        const matches = projects.filter((project) => project.name === name);
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        if (matches.length === 0) {
+            throw new ProjectNotResolvedError(`No project found with name "${name}"`, 'not_found');
+        }
+        throw new ProjectNotResolvedError(`Multiple projects found with name "${name}" (${matches.length}); pass --project <id> to disambiguate`, 'multiple_matches');
+    }
+    async resolveById(idOrName) {
+        return this.getProject(idOrName);
+    }
+}

package/dist/api/shared.d.ts

@@ -0,0 +1,45 @@
+import { BackendApiClient, BackendApiError } from '../backend/index.js';
+export type ApiClient = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'getProject' | 'updateProject' | 'patchProjectByQuery' | 'setDefaultProject' | 'matchProjectByPath' | 'listIssues' | 'getIssue' | 'createIssue' | 'patchIssue' | 'deleteIssue' | 'listTasks' | 'getTask' | 'listTaskMessages' | 'postTaskMessage'>;
+export interface SdkClientOptions {
+    /**
+     * Optional override for the SDK version stamped onto audit metadata. Falls
+     * back to the package.json version. Tests may want to pin this so output is
+     * stable.
+     */
+    sdkVersion?: string;
+    /**
+     * Optional environment provider for `CONDUCTOR_INVOKED_BY` lookup. Defaults
+     * to `process.env`. Useful for tests that want to inject env without
+     * mutating globals.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Build the metadata payload every SDK write attaches to the request.
+ *
+ * Audit fields are namespaced under `metadata.audit` (RFC 0025 §5.2 + review
+ * findings M3/H1). This avoids two failure modes the original top-level shape
+ * had:
+ *   1. A caller passing `--metadata-json '{"actor":"system"}'` could spoof the
+ *      audit actor by colliding with our top-level key.
+ *   2. Server-side strippers had to know the full audit-key list to filter.
+ *
+ * Merge order:
+ *   - Non-audit user keys are passed through verbatim.
+ *   - Audit defaults (`actor:"sdk"`, `sdkVersion`, `invokedBy`) are layered
+ *     UNDER the caller's `audit` (so the CLI's `actor:"cli"` wins).
+ *   - The caller's top-level `audit` key, if any, takes precedence over the
+ *     SDK defaults but never replaces all of them — `cliVersion`, etc., are
+ *     additive.
+ */
+export declare const buildAuditMetadata: (userMetadata: Record<string, unknown> | undefined, options?: SdkClientOptions) => Record<string, unknown>;
+export declare class ProjectNotResolvedError extends Error {
+    readonly reason: 'not_found' | 'multiple_matches' | 'no_default' | 'no_signal';
+    constructor(message: string, reason: 'not_found' | 'multiple_matches' | 'no_default' | 'no_signal');
+}
+/**
+ * Best-effort mapping for HTTP-shaped failures so the CLI exit-code matrix
+ * (RFC 0025 §4) has a stable signal. Callers can choose to inspect
+ * `BackendApiError.statusCode` directly instead.
+ */
+export declare const isBackendApiError: (value: unknown) => value is BackendApiError;