hakira-mcp 0.1.0

package/dist/git/metadata.js

@@ -0,0 +1,40 @@
+import { tryGit } from './exec.js';
+/** The user's REAL git state — `commit_sha` is HEAD (or the resolved `ref`). */
+export function captureGitMetadata(root, ref) {
+    // `--verify` + the userRef channel: exactly one revision, never an option.
+    const commit_sha = tryGit(root, ['rev-parse', '--verify'], ref ?? 'HEAD');
+    const refName = ref ?? tryGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const porcelain = tryGit(root, ['status', '--porcelain']);
+    return {
+        commit_sha,
+        ref: refName,
+        is_dirty: porcelain !== null && porcelain.length > 0,
+        remote_url: tryGit(root, ['remote', 'get-url', 'origin']),
+    };
+}
+/**
+ * Changed-file list for `scope:'diff'`. A WORKING-TREE diff vs the merge-base
+ * with the default branch — so it naturally includes uncommitted edits to
+ * tracked files (the point; sidesteps Semgrep's dirty-tree limit, spec §9).
+ * Shipped as a prioritization HINT, not a hard allowlist (00 §3 row 8).
+ */
+export function computeChangedFiles(root, opts = {}) {
+    const base = opts.base ?? tryGit(root, ['merge-base', 'HEAD', 'origin/HEAD']) ?? opts.ref ?? 'HEAD';
+    const out = tryGit(root, ['diff', '--name-only'], base);
+    if (!out)
+        return [];
+    return out
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Human summary for sessions.target_gist (00 §5). */
+export function buildTargetGist(meta, scope, changedFiles) {
+    const sha = meta.commit_sha ? meta.commit_sha.slice(0, 7) : 'working-tree';
+    if (scope === 'diff') {
+        const n = changedFiles.length;
+        const branch = meta.ref ?? 'HEAD';
+        return `diff vs ${branch} @ ${sha} (${n} file${n === 1 ? '' : 's'})`;
+    }
+    return `full audit @ ${sha}`;
+}

package/dist/git/repo-key.d.ts

@@ -0,0 +1,7 @@
+/** Light, STABLE normalization — applied identically on every call. */
+export declare function normalizeRepoKey(url: string): string;
+/**
+ * 1. git remote origin URL → that URL is the repo_key.
+ * 2. else a stable uuid persisted in a locally-excluded `.hakira/mcp.json`.
+ */
+export declare function resolveRepoKey(projectRoot: string): string;

package/dist/git/repo-key.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { tryGit } from './exec.js';
+import { log } from '../log.js';
+// repo_key derivation (ticket S5). The authoritative binding is server-side
+// (00 §3 row 7 get-or-create on (user_id, repo_key)); this is the local id source.
+/** Light, STABLE normalization — applied identically on every call. */
+export function normalizeRepoKey(url) {
+    let s = url.trim();
+    s = s.replace(/\/+$/, ''); // trailing slash(es)
+    s = s.replace(/\.git$/, ''); // trailing .git
+    return s;
+}
+/**
+ * 1. git remote origin URL → that URL is the repo_key.
+ * 2. else a stable uuid persisted in a locally-excluded `.hakira/mcp.json`.
+ */
+export function resolveRepoKey(projectRoot) {
+    const origin = tryGit(projectRoot, ['remote', 'get-url', 'origin']);
+    if (origin && origin.length > 0)
+        return normalizeRepoKey(origin);
+    // Fallback: local uuid. Ensure `.hakira/` is ignored FIRST — a committed
+    // repo_key collides across teammates (workspaces are user-scoped, spec §7/G9).
+    ensureLocallyExcluded(projectRoot);
+    const dir = join(projectRoot, '.hakira');
+    const file = join(dir, 'mcp.json');
+    if (existsSync(file)) {
+        try {
+            const j = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof j.repo_key === 'string' && j.repo_key.length > 0)
+                return j.repo_key;
+        }
+        catch {
+            /* fall through and regenerate */
+        }
+    }
+    const id = randomUUID();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, JSON.stringify({ repo_key: id }, null, 2) + '\n');
+    return id;
+}
+const EXCLUDE_RULE = '# Hakira MCP local id\n.hakira/\n';
+/**
+ * Ignore `.hakira/` via `$GIT_DIR/info/exclude` — NOT the project's `.gitignore`.
+ *
+ * `.gitignore` is tracked: writing to it shows up in the user's `git status` as
+ * a change they did not make and can land in a commit or a PR. `info/exclude`
+ * has the same effect, is never tracked, and is invisible to `git status` (F9).
+ *
+ * Best-effort throughout: a non-repo folder is a clean no-op, and any write
+ * failure is a warning — never a crash of the MCP server.
+ */
+function ensureLocallyExcluded(projectRoot) {
+    try {
+        const gitDir = resolveGitCommonDir(projectRoot);
+        if (!gitDir)
+            return; // plain directory, not a repo — nothing to exclude
+        const exclude = join(gitDir, 'info', 'exclude');
+        if (existsSync(exclude)) {
+            const current = readFileSync(exclude, 'utf8');
+            const lines = current.split('\n').map((l) => l.trim());
+            if (lines.includes('.hakira/') || lines.includes('.hakira'))
+                return; // already there
+            appendFileSync(exclude, (current.endsWith('\n') || current.length === 0 ? '' : '\n') + EXCLUDE_RULE);
+        }
+        else {
+            mkdirSync(join(gitDir, 'info'), { recursive: true });
+            writeFileSync(exclude, EXCLUDE_RULE);
+        }
+    }
+    catch (err) {
+        log.warn('could not exclude .hakira/ via .git/info/exclude', err);
+    }
+}
+/**
+ * The repo's COMMON git dir, absolute — or null when `projectRoot` is not a repo.
+ *
+ * Asking git rather than looking for a `.git` directory handles the cases where
+ * `.git` is a FILE (linked worktrees, submodules) or absent entirely. The common
+ * dir is the right target: git resolves `info/exclude` against it, so the rule
+ * applies in every linked worktree too. `--git-common-dir` predates our floor but
+ * an ancient git would echo it back verbatim — hence the `--git-dir` fallback.
+ */
+function resolveGitCommonDir(projectRoot) {
+    const common = tryGit(projectRoot, ['rev-parse', '--git-common-dir']);
+    const raw = common && !common.startsWith('-') ? common : tryGit(projectRoot, ['rev-parse', '--git-dir']);
+    if (!raw || raw.startsWith('-'))
+        return null;
+    return isAbsolute(raw) ? raw : resolve(projectRoot, raw); // git reports it relative to cwd
+}

package/dist/http/cp-client.d.ts

@@ -0,0 +1,182 @@
+export interface BindWorkspaceResult {
+    workspace_id: string;
+    status: string;
+    bootstrapped: boolean;
+    estimate_status: string | null;
+    created: boolean;
+    /** Live credit balance — lets start_audit fail fast before zip/upload/provision. */
+    balance_credits?: number;
+    /** Server-built top-up link (correct app host) for the fail-fast paywall message. */
+    buy_credits_url?: string;
+}
+export interface UploadUrlResult {
+    uploadUrl: string;
+    key: string;
+    filename: string;
+    contentType: string;
+}
+export interface AuditTarget {
+    ref?: string;
+    url?: string;
+    scope: 'full' | 'diff';
+    focus?: string;
+    path?: string;
+    commit_sha?: string | null;
+    is_dirty?: boolean;
+    remote_url?: string | null;
+    changed_files?: string[];
+    target_gist: string;
+}
+export interface StartAuditBody {
+    workspace_id: string;
+    r2_key?: string;
+    target: AuditTarget;
+}
+export interface StartAuditResult {
+    audit_id: string;
+    status: string;
+    poll_after_ms?: number;
+    workspace_id: string;
+    target_gist: string;
+    full_project_estimate_usd?: number;
+}
+export interface AuditStatus {
+    audit_id: string;
+    status: string;
+    phase?: string;
+    findings_count: number;
+    cost_so_far_usd: number;
+    /** Full-project cost ceiling — present only for full-scope audits once computed. */
+    full_project_estimate_usd?: number;
+    poll_after_ms?: number;
+    error?: string;
+}
+/** Projected ChatEvent item from GET /mcp/audits/:id/events. */
+export type AuditEventItem = {
+    id: number;
+    ts: number;
+    type: string;
+    [key: string]: unknown;
+};
+export interface AuditEventsPage {
+    audit_id: string;
+    status: string;
+    events: AuditEventItem[];
+    next_after: number;
+    has_more: boolean;
+    poll_after_ms?: number;
+}
+export interface FindingSummary {
+    id: string;
+    title: string;
+    severity: string;
+    category?: string;
+    target?: string;
+    tier?: string;
+    commit_sha?: string;
+    resource?: {
+        uri: string;
+    };
+}
+export interface AuditFindings {
+    audit_id: string;
+    status: string;
+    commit_sha?: string;
+    is_dirty?: boolean;
+    ref?: string;
+    findings: FindingSummary[];
+}
+export interface AuditListItem {
+    audit_id: string;
+    status: string;
+    created_at: number;
+    target_gist: string | null;
+    ref?: string | null;
+    commit_sha?: string | null;
+    findings_count: number;
+    cost_usd: number;
+    workspace_id: string;
+    workspace_name?: string;
+    origin?: string | null;
+    /** Full-project cost ceiling — present only for full-scope audits once computed. */
+    full_project_estimate_usd?: number;
+    /** Set by the MCP tool after local repo bind (not from CP). */
+    is_current?: boolean;
+}
+export interface WorkspaceListItem {
+    workspace_id: string;
+    name: string;
+    status: string;
+    repo_key?: string;
+    /** Set by the MCP tool after local repo bind (not from CP). */
+    is_current?: boolean;
+}
+export interface Finding {
+    id: string;
+    sessionId: string;
+    workspaceId: string;
+    title: string;
+    severity: string;
+    category?: string;
+    target?: string;
+    description?: string;
+    evidence?: string;
+    recommendation?: string;
+    createdAt: number;
+    source?: string;
+    tier?: string;
+    commitSha?: string;
+    prNumber?: number;
+}
+type TokenResolver = () => Promise<string>;
+export declare class CpClient {
+    private readonly baseUrl;
+    private readonly getToken;
+    constructor(baseUrl: string, getToken: TokenResolver);
+    bindWorkspace(repoKey: string, name?: string): Promise<BindWorkspaceResult>;
+    getUploadUrl(wsId: string, args: {
+        size: number;
+        contentType: 'application/zip';
+    }): Promise<UploadUrlResult>;
+    completeUpload(wsId: string, args: {
+        key: string;
+        filename: string;
+        excludeFolders?: string[];
+    }): Promise<void>;
+    startAudit(body: StartAuditBody): Promise<StartAuditResult>;
+    getStatus(id: string): Promise<AuditStatus>;
+    getAuditEvents(id: string, opts?: {
+        after?: number;
+        limit?: number;
+    }): Promise<AuditEventsPage>;
+    getFindings(id: string, opts?: {
+        min_severity?: string;
+    }): Promise<AuditFindings>;
+    listWorkspaces(): Promise<{
+        workspaces: WorkspaceListItem[];
+    }>;
+    listAudits(opts?: {
+        workspace_id?: string;
+        limit?: number;
+    }): Promise<{
+        audits: AuditListItem[];
+    }>;
+    /**
+     * A 200 does NOT imply we cancelled. The handler reports the audit's REAL
+     * status, so `status` is `canceled` only when it actually stopped something;
+     * an already-finished audit comes back `ready`/`canceled`/`error`, and a
+     * deferred audit whose drive the poller already grabbed comes back
+     * `provisioning` (cancel again once its session row appears).
+     * The failure paths are errors, not 200s: 400 `not_cancelable` (not an
+     * MCP-origin session — do not retry) and 409 `cancel_failed` (may still be
+     * running) both surface through CpError.
+     */
+    cancelAudit(id: string): Promise<{
+        audit_id: string;
+        status: 'canceled' | 'ready' | 'error' | 'provisioning';
+    }>;
+    getFinding(id: string): Promise<Finding>;
+    putUpload(uploadUrl: string, buffer: Buffer): Promise<void>;
+    private request;
+}
+export {};

package/dist/http/cp-client.js

@@ -0,0 +1,196 @@
+import { CpError, CpUnauthorizedError } from './errors.js';
+import { log } from '../log.js';
+export class CpClient {
+    baseUrl;
+    getToken;
+    constructor(baseUrl, getToken) {
+        this.baseUrl = baseUrl;
+        this.getToken = getToken;
+    }
+    // ── row 7 — POST /mcp/workspaces (get-or-create by repo_key) ──────────────
+    bindWorkspace(repoKey, name) {
+        // get-or-create by repo_key → idempotent, safe to retry.
+        return this.request('POST', '/mcp/workspaces', { body: { repo_key: repoKey, name }, idempotent: true });
+    }
+    // ── row 14 — POST /workspaces/:id/upload-url ──────────────────────────────
+    getUploadUrl(wsId, args) {
+        // Mints a fresh presigned URL/key with no side effects → idempotent. Retries
+        // are bounded (≤3) and the mint is rate-limited to 10/min/user, so worst-case
+        // first-bind (2 mints × 3) stays under budget.
+        return this.request('POST', `/workspaces/${enc(wsId)}/upload-url`, {
+            body: { size: args.size, contentType: args.contentType },
+            idempotent: true,
+        });
+    }
+    // ── row 15 — POST /workspaces/:id/upload-complete (first-bind bootstrap) ──
+    async completeUpload(wsId, args) {
+        await this.request('POST', `/workspaces/${enc(wsId)}/upload-complete`, {
+            body: { key: args.key, filename: args.filename, excludeFolders: args.excludeFolders },
+            expectJson: false,
+        });
+    }
+    // ── row 8 — POST /mcp/audits ──────────────────────────────────────────────
+    startAudit(body) {
+        return this.request('POST', '/mcp/audits', { body });
+    }
+    // ── row 9 — GET /mcp/audits/:id ───────────────────────────────────────────
+    getStatus(id) {
+        return this.request('GET', `/mcp/audits/${enc(id)}`);
+    }
+    // ── GET /mcp/audits/:id/events — projected transcript for "check the audit"
+    getAuditEvents(id, opts = {}) {
+        return this.request('GET', `/mcp/audits/${enc(id)}/events`, {
+            query: { after: opts.after, limit: opts.limit },
+        });
+    }
+    // ── row 10 — GET /mcp/audits/:id/findings ─────────────────────────────────
+    getFindings(id, opts = {}) {
+        return this.request('GET', `/mcp/audits/${enc(id)}/findings`, {
+            query: { min_severity: opts.min_severity },
+        });
+    }
+    // ── GET /mcp/workspaces — owner list (all workspaces) ─────────────────────
+    listWorkspaces() {
+        return this.request('GET', '/mcp/workspaces');
+    }
+    // ── row 11 — GET /mcp/audits ──────────────────────────────────────────────
+    listAudits(opts = {}) {
+        return this.request('GET', '/mcp/audits', {
+            query: { workspace_id: opts.workspace_id, limit: opts.limit },
+        });
+    }
+    // ── row 12 — POST /mcp/audits/:id/cancel ──────────────────────────────────
+    /**
+     * A 200 does NOT imply we cancelled. The handler reports the audit's REAL
+     * status, so `status` is `canceled` only when it actually stopped something;
+     * an already-finished audit comes back `ready`/`canceled`/`error`, and a
+     * deferred audit whose drive the poller already grabbed comes back
+     * `provisioning` (cancel again once its session row appears).
+     * The failure paths are errors, not 200s: 400 `not_cancelable` (not an
+     * MCP-origin session — do not retry) and 409 `cancel_failed` (may still be
+     * running) both surface through CpError.
+     */
+    cancelAudit(id) {
+        return this.request('POST', `/mcp/audits/${enc(id)}/cancel`);
+    }
+    // ── row 6 — GET /findings/:id (owner-scoped) ──────────────────────────────
+    getFinding(id) {
+        return this.request('GET', `/findings/${enc(id)}`);
+    }
+    // ── raw PUT of the ZIP buffer to a presigned (or local no-R2) URL. NOT
+    //    CP-authed — no bearer (00 §3 note under the table; ticket S7 step 2). ──
+    async putUpload(uploadUrl, buffer) {
+        // Hand fetch a standalone ArrayBuffer — a member of both the DOM and undici
+        // `BodyInit` unions (a Node Buffer / generic Uint8Array is not, under TS 5.9).
+        const body = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        // Idempotent: same key, full-object PUT, last-write-wins — safe to retry on a
+        // transient network blip (the classic ECONNRESET/socket-hang-up on a fresh
+        // cross-host TLS connection streaming the whole ZIP).
+        const res = await fetchWithRetry(uploadUrl, { method: 'PUT', body, headers: { 'content-type': 'application/zip' } }, { retry: true, label: 'Upload PUT' });
+        if (!res.ok) {
+            throw new CpError(res.status, {}, `Upload PUT failed (${res.status} ${res.statusText})`);
+        }
+    }
+    // ── shared request core: bearer inject + structured error mapping ─────────
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const token = await this.getToken();
+        const headers = { authorization: `Bearer ${token}` };
+        let body;
+        if (opts.body !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(opts.body);
+        }
+        const res = await fetchWithRetry(url, { method, headers, body }, {
+            retry: method === 'GET' || opts.idempotent === true,
+            label: `${method} ${path}`,
+        });
+        if (!res.ok) {
+            const parsed = await safeParseJson(res);
+            if (res.status === 401)
+                throw new CpUnauthorizedError(res.status, parsed);
+            throw new CpError(res.status, parsed, `${method} ${path} failed (${res.status} ${res.statusText})`);
+        }
+        if (opts.expectJson === false)
+            return undefined;
+        // Some 2xx (202) may have no body.
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+// ── network resilience ──────────────────────────────────────────────────────
+// A Node/undici network failure rejects `fetch` with a generic
+// `TypeError: fetch failed` whose real reason (ECONNRESET / ETIMEDOUT / ENOTFOUND
+// / "socket hang up") lives on `.cause` — which the old code discarded, so the
+// agent only ever saw the opaque "fetch failed". We (a) annotate the thrown error
+// with the cause so it's diagnostic, and (b) retry idempotent calls a bounded
+// number of times with backoff so a single transient blip on the multi-hop
+// first-bind sequence (esp. the two full-buffer R2 PUTs) doesn't fail the audit.
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 500;
+async function fetchWithRetry(url, init, opts) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            const res = await fetch(url, init);
+            // Transient gateway failures on an idempotent call are worth one more try.
+            if (opts.retry && attempt < MAX_ATTEMPTS && (res.status === 502 || res.status === 503 || res.status === 504)) {
+                log.warn(`${opts.label} → ${res.status} — retry ${attempt}/${MAX_ATTEMPTS - 1}`);
+                await sleep(BASE_DELAY_MS * 2 ** (attempt - 1));
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            const detail = describeNetworkError(err);
+            if (opts.retry && attempt < MAX_ATTEMPTS) {
+                log.warn(`${opts.label} network error (${detail}) — retry ${attempt}/${MAX_ATTEMPTS - 1}`);
+                await sleep(BASE_DELAY_MS * 2 ** (attempt - 1));
+                continue;
+            }
+            // Re-throw with the underlying cause folded into the message so the tool
+            // layer (wrap.ts catch-all) surfaces something actionable, and keep `cause`
+            // attached for anyone reading the stack.
+            throw new Error(`${opts.label} failed: ${detail}`, { cause: err });
+        }
+    }
+}
+/** Pull the useful reason out of an undici `TypeError: fetch failed`. */
+function describeNetworkError(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause instanceof Error) {
+            const code = cause.code;
+            return code ? `${code}: ${cause.message}` : cause.message;
+        }
+        if (cause !== undefined && cause !== null)
+            return String(cause);
+        return err.message;
+    }
+    return String(err);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function safeParseJson(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : { message: text };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A structured, non-2xx Control-Plane response. Preserves the CP error `code`
+ * plus the known extra fields the client surfaces verbatim (00 §7):
+ *   - audit_already_running  → carries `audit_id` + `status`
+ *   - workspace_needs_repair → carries `workspace_id` + `detail`
+ */
+export declare class CpError extends Error {
+    readonly httpStatus: number;
+    /** CP error code, e.g. "audit_already_running" | "workspace_needs_repair". */
+    readonly error?: string;
+    readonly audit_id?: string;
+    readonly workspace_id?: string;
+    readonly detail?: string;
+    /** The in-flight audit's MCP status (audit_already_running body). */
+    readonly runningStatus?: string;
+    /** Top-up link (payment_required body) — where the user adds credits. */
+    readonly buy_credits_url?: string;
+    /** Full parsed body, for any field not promoted above. */
+    readonly data: Record<string, unknown>;
+    constructor(httpStatus: number, body: Record<string, unknown>, fallbackMessage: string);
+}
+/**
+ * A 401 from CP. The tool wrapper special-cases this: clear the cached
+ * credential + re-authorize ONCE, then retry the call (00 §7 / ticket S3).
+ */
+export declare class CpUnauthorizedError extends CpError {
+    constructor(httpStatus: number, body: Record<string, unknown>);
+}

package/dist/http/errors.js

@@ -0,0 +1,47 @@
+// Typed errors thrown by CpClient. The tool layer (tools/wrap.ts) maps these to
+// MCP `isError:true` results carrying the human-readable message (00 §7).
+/**
+ * A structured, non-2xx Control-Plane response. Preserves the CP error `code`
+ * plus the known extra fields the client surfaces verbatim (00 §7):
+ *   - audit_already_running  → carries `audit_id` + `status`
+ *   - workspace_needs_repair → carries `workspace_id` + `detail`
+ */
+export class CpError extends Error {
+    httpStatus;
+    /** CP error code, e.g. "audit_already_running" | "workspace_needs_repair". */
+    error;
+    audit_id;
+    workspace_id;
+    detail;
+    /** The in-flight audit's MCP status (audit_already_running body). */
+    runningStatus;
+    /** Top-up link (payment_required body) — where the user adds credits. */
+    buy_credits_url;
+    /** Full parsed body, for any field not promoted above. */
+    data;
+    constructor(httpStatus, body, fallbackMessage) {
+        const message = typeof body?.message === 'string' && body.message.length > 0
+            ? body.message
+            : fallbackMessage;
+        super(message);
+        this.name = 'CpError';
+        this.httpStatus = httpStatus;
+        this.error = typeof body?.error === 'string' ? body.error : undefined;
+        this.audit_id = typeof body?.audit_id === 'string' ? body.audit_id : undefined;
+        this.workspace_id = typeof body?.workspace_id === 'string' ? body.workspace_id : undefined;
+        this.detail = typeof body?.detail === 'string' ? body.detail : undefined;
+        this.runningStatus = typeof body?.status === 'string' ? body.status : undefined;
+        this.buy_credits_url = typeof body?.buy_credits_url === 'string' ? body.buy_credits_url : undefined;
+        this.data = body ?? {};
+    }
+}
+/**
+ * A 401 from CP. The tool wrapper special-cases this: clear the cached
+ * credential + re-authorize ONCE, then retry the call (00 §7 / ticket S3).
+ */
+export class CpUnauthorizedError extends CpError {
+    constructor(httpStatus, body) {
+        super(httpStatus, body, 'Unauthorized');
+        this.name = 'CpUnauthorizedError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from './tools/context.js';
+/** Build the fully-registered MCP server (shared by main() + tests). */
+export declare function buildServer(deps: ToolDeps): McpServer;

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { config } from './config.js';
+import { log } from './log.js';
+import { version } from './version.js';
+import { CpClient } from './http/cp-client.js';
+import { resolveToken, clearCredentials, logout } from './auth/credentials.js';
+import { registerStartAudit } from './tools/start-audit.js';
+import { registerGetStatus } from './tools/get-status.js';
+import { registerGetFindings } from './tools/get-findings.js';
+import { registerGetFinding } from './tools/get-finding.js';
+import { registerGetEvents } from './tools/get-audit-events.js';
+import { registerListAudits } from './tools/list-audits.js';
+import { registerListWorkspaces } from './tools/list-workspaces.js';
+import { registerCancel } from './tools/cancel.js';
+import { registerFindingResource } from './resources/finding.js';
+/** Build the fully-registered MCP server (shared by main() + tests). */
+export function buildServer(deps) {
+    const server = new McpServer({ name: 'hakira', version });
+    registerStartAudit(server, deps);
+    registerGetStatus(server, deps);
+    registerGetFindings(server, deps);
+    registerGetFinding(server, deps);
+    registerGetEvents(server, deps);
+    // estimate_audit intentionally not registered: the free pre-check dead-ended
+    // agents on fresh repos (null estimate → never paid). The full-project ceiling
+    // now rides on start_audit / get_audit_status / list_audits (full scope only).
+    registerListAudits(server, deps);
+    registerListWorkspaces(server, deps);
+    registerCancel(server, deps);
+    registerFindingResource(server, deps);
+    return server;
+}
+async function main() {
+    // Subcommands MUST run before connecting the stdio transport.
+    if (process.argv[2] === 'logout') {
+        logout();
+        process.exit(0);
+    }
+    const cp = new CpClient(config.apiUrl, resolveToken);
+    const deps = { cp, resolveToken, clearCredentials, root: process.cwd() };
+    const server = buildServer(deps);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the JSON-RPC channel.
+    log.info(`hakira-mcp v${version} connected (api=${config.apiUrl})`);
+}
+main().catch((err) => {
+    log.error('fatal', err);
+    process.exit(1);
+});

package/dist/log.d.ts

@@ -0,0 +1,5 @@
+export declare const log: {
+    info: (...a: unknown[]) => void;
+    warn: (...a: unknown[]) => void;
+    error: (...a: unknown[]) => void;
+};

package/dist/log.js

@@ -0,0 +1,11 @@
+// stderr-only logger. stdout is the JSON-RPC channel for the stdio transport —
+// ANY `console.log` / `process.stdout.write` corrupts the protocol frame and the
+// MCP client shows "disconnected" (00 §7, gotcha G2). Everything logs to stderr,
+// which Claude Code also captures at ~/Library/Logs/Claude/mcp*.log.
+//
+// `console.log` is BANNED in this package. Use `log.*` everywhere.
+export const log = {
+    info: (...a) => console.error('[hakira-mcp]', ...a),
+    warn: (...a) => console.error('[hakira-mcp] WARN', ...a),
+    error: (...a) => console.error('[hakira-mcp] ERROR', ...a),
+};