@mcoda/core 0.1.4

package/dist/services/telemetry/TelemetryService.js

@@ -0,0 +1,434 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Connection, GlobalRepository } from "@mcoda/db";
+import { PathHelper } from "@mcoda/shared";
+import { TelemetryClient } from "@mcoda/integrations";
+const hasTables = async (db, required) => {
+    const rows = await db.all(`SELECT name FROM sqlite_master WHERE type='table'`);
+    const names = new Set(rows.map((r) => r.name));
+    return required.every((name) => names.has(name));
+};
+const parseMetadata = (raw) => {
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+const addCost = (current, value) => {
+    if (value === null || value === undefined)
+        return current;
+    return (current ?? 0) + value;
+};
+const parseDurationMs = (input) => {
+    const match = input.trim().match(/^(\d+)([smhdw])$/i);
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const multipliers = {
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        w: 7 * 24 * 60 * 60 * 1000,
+    };
+    return multipliers[unit] ? amount * multipliers[unit] : undefined;
+};
+const parseTimeInput = (input) => {
+    if (!input)
+        return undefined;
+    const duration = parseDurationMs(input);
+    if (duration !== undefined) {
+        return new Date(Date.now() - duration).toISOString();
+    }
+    const parsed = Date.parse(input);
+    if (!Number.isNaN(parsed)) {
+        return new Date(parsed).toISOString();
+    }
+    return undefined;
+};
+const normalizeGroupBy = (groupBy) => {
+    if (!groupBy || groupBy.length === 0) {
+        return ["project", "command", "agent"];
+    }
+    const seen = new Set();
+    for (const dim of groupBy) {
+        if (["project", "agent", "command", "day", "model", "job", "action"].includes(dim)) {
+            seen.add(dim);
+        }
+    }
+    return Array.from(seen);
+};
+const dayFromTimestamp = (timestamp) => {
+    if (!timestamp)
+        return null;
+    const parsed = Date.parse(timestamp);
+    if (Number.isNaN(parsed))
+        return null;
+    return new Date(parsed).toISOString().slice(0, 10);
+};
+export class TelemetryService {
+    constructor(workspace, deps) {
+        this.workspace = workspace;
+        this.db = deps.db;
+        this.connection = deps.connection;
+        this.client = deps.client;
+    }
+    static async create(workspace, options = {}) {
+        const baseUrl = workspace.config?.telemetry?.endpoint ?? process.env.MCODA_TELEMETRY_API;
+        const authToken = workspace.config?.telemetry?.authToken ?? process.env.MCODA_TELEMETRY_TOKEN;
+        if (baseUrl) {
+            return new TelemetryService(workspace, { client: new TelemetryClient({ baseUrl, authToken }) });
+        }
+        if (options.requireApi) {
+            throw new Error("Telemetry API is not configured (set MCODA_TELEMETRY_API/MCODA_TELEMETRY_TOKEN or telemetry.endpoint in workspace config).");
+        }
+        const dbPath = PathHelper.getWorkspaceDbPath(workspace.workspaceRoot);
+        try {
+            await fs.access(dbPath);
+        }
+        catch {
+            if (!options.allowMissingTelemetry) {
+                throw new Error(`No workspace DB found at ${dbPath}. Run mcoda init or create-tasks first.`);
+            }
+        }
+        const connection = await Connection.open(dbPath);
+        const ok = await hasTables(connection.db, ["token_usage"]);
+        if (!ok && !options.allowMissingTelemetry) {
+            await connection.close();
+            throw new Error("Workspace DB is missing telemetry tables (token_usage). Run create-tasks to initialize it.");
+        }
+        return new TelemetryService(workspace, { db: connection.db, connection });
+    }
+    async close() {
+        if (this.connection) {
+            await this.connection.close();
+        }
+        if (this.globalRepo) {
+            await this.globalRepo.close();
+        }
+    }
+    get configPath() {
+        return path.join(this.workspace.mcodaDir, "config.json");
+    }
+    async readConfigFile() {
+        try {
+            const raw = await fs.readFile(this.configPath, "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeConfigFile(config) {
+        await fs.mkdir(this.workspace.mcodaDir, { recursive: true });
+        await fs.writeFile(this.configPath, JSON.stringify(config, null, 2), "utf8");
+    }
+    async resolveProjectId(projectKey) {
+        if (!projectKey || !this.db)
+            return undefined;
+        const row = await this.db.get(`SELECT id FROM projects WHERE key = ?`, projectKey);
+        return row?.id;
+    }
+    async getGlobalRepo() {
+        if (!this.globalRepo) {
+            this.globalRepo = await GlobalRepository.create();
+        }
+        return this.globalRepo;
+    }
+    async resolveAgentId(agent) {
+        if (!agent)
+            return undefined;
+        try {
+            const repo = await this.getGlobalRepo();
+            const asId = await repo.getAgentById(agent);
+            if (asId)
+                return asId.id;
+            const bySlug = await repo.getAgentBySlug(agent);
+            if (bySlug)
+                return bySlug.id;
+        }
+        catch {
+            // ignore lookup failures; fall through to raw value
+        }
+        return agent;
+    }
+    filterRows(rows, options) {
+        const filtered = [];
+        for (const row of rows) {
+            const metadata = parseMetadata(row.metadata_json);
+            const commandName = metadata.commandName ??
+                metadata.command_name ??
+                metadata.command;
+            if (options.command && commandName && options.command !== commandName) {
+                continue;
+            }
+            filtered.push({ row, metadata });
+        }
+        return filtered;
+    }
+    mapConfig(apiConfig) {
+        return {
+            ...apiConfig,
+            localRecording: apiConfig.localRecording ?? true,
+            remoteExport: apiConfig.remoteExport ?? true,
+            optOut: apiConfig.optOut ?? false,
+            strict: apiConfig.strict ?? false,
+            configPath: this.configPath,
+        };
+    }
+    async getSummary(options = {}) {
+        const groupBy = normalizeGroupBy(options.groupBy);
+        const since = parseTimeInput(options.since ?? "7d") ?? undefined;
+        const until = parseTimeInput(options.until);
+        const projectId = options.projectKey ? await this.resolveProjectId(options.projectKey) : undefined;
+        if (options.projectKey && !projectId && !this.client) {
+            throw new Error(`Unknown project key: ${options.projectKey}`);
+        }
+        const agentId = await this.resolveAgentId(options.agent);
+        if (this.client) {
+            return this.client.getSummary({
+                workspaceId: this.workspace.workspaceId,
+                projectId: projectId ?? options.projectKey,
+                agentId: agentId ?? options.agent,
+                commandName: options.command,
+                jobId: options.jobId,
+                from: since,
+                to: until,
+                groupBy,
+            });
+        }
+        if (!this.db) {
+            throw new Error("Telemetry DB not available and no telemetry client configured.");
+        }
+        const clauses = ["workspace_id = ?"];
+        const params = [this.workspace.workspaceId];
+        if (projectId) {
+            clauses.push("project_id = ?");
+            params.push(projectId);
+        }
+        if (agentId) {
+            clauses.push("agent_id = ?");
+            params.push(agentId);
+        }
+        if (options.jobId) {
+            clauses.push("job_id = ?");
+            params.push(options.jobId);
+        }
+        if (since) {
+            clauses.push("timestamp >= ?");
+            params.push(since);
+        }
+        if (until) {
+            clauses.push("timestamp <= ?");
+            params.push(until);
+        }
+        const query = `SELECT * FROM token_usage ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""}`;
+        const rows = await this.db.all(query, ...params);
+        const filtered = this.filterRows(rows, { command: options.command });
+        const summary = new Map();
+        for (const { row, metadata } of filtered) {
+            const commandName = metadata.commandName ??
+                metadata.command_name ??
+                metadata.command ??
+                null;
+            const action = metadata.action ?? metadata.phase ?? null;
+            const keyParts = groupBy.map((dim) => {
+                switch (dim) {
+                    case "project":
+                        return row.project_id ?? "";
+                    case "agent":
+                        return row.agent_id ?? "";
+                    case "model":
+                        return row.model_name ?? "";
+                    case "command":
+                        return commandName ?? "";
+                    case "day":
+                        return dayFromTimestamp(row.timestamp) ?? "";
+                    case "job":
+                        return row.job_id ?? "";
+                    case "action":
+                        return action ?? "";
+                    default:
+                        return "";
+                }
+            });
+            const key = keyParts.join("|");
+            let record = summary.get(key);
+            if (!record) {
+                record = {
+                    workspace_id: this.workspace.workspaceId,
+                    project_id: groupBy.includes("project") ? row.project_id ?? null : undefined,
+                    agent_id: groupBy.includes("agent") ? row.agent_id ?? null : undefined,
+                    model_name: groupBy.includes("model") ? row.model_name ?? null : undefined,
+                    command_name: groupBy.includes("command") ? commandName : undefined,
+                    action: groupBy.includes("action") ? action : undefined,
+                    job_id: groupBy.includes("job") ? row.job_id ?? null : undefined,
+                    day: groupBy.includes("day") ? dayFromTimestamp(row.timestamp) : undefined,
+                    calls: 0,
+                    tokens_prompt: 0,
+                    tokens_completion: 0,
+                    tokens_total: 0,
+                    cost_estimate: null,
+                };
+                summary.set(key, record);
+            }
+            record.calls += 1;
+            record.tokens_prompt += row.tokens_prompt ?? 0;
+            record.tokens_completion += row.tokens_completion ?? 0;
+            record.tokens_total += row.tokens_total ?? 0;
+            record.cost_estimate = addCost(record.cost_estimate, row.cost_estimate);
+        }
+        return Array.from(summary.values());
+    }
+    async getTokenUsage(options = {}) {
+        const since = parseTimeInput(options.since);
+        const until = parseTimeInput(options.until);
+        const projectId = options.projectKey ? await this.resolveProjectId(options.projectKey) : undefined;
+        if (options.projectKey && !projectId && !this.client) {
+            throw new Error(`Unknown project key: ${options.projectKey}`);
+        }
+        const agentId = await this.resolveAgentId(options.agent);
+        if (this.client) {
+            const rows = await this.client.getTokenUsage({
+                workspaceId: this.workspace.workspaceId,
+                projectId: projectId ?? options.projectKey,
+                agentId: agentId ?? options.agent,
+                commandName: options.command,
+                jobId: options.jobId,
+                from: since,
+                to: until,
+                page: options.page,
+                pageSize: options.pageSize,
+                sort: "timestamp:asc",
+            });
+            return rows.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+        }
+        if (!this.db) {
+            throw new Error("Telemetry DB not available and no telemetry client configured.");
+        }
+        const clauses = ["workspace_id = ?"];
+        const params = [this.workspace.workspaceId];
+        if (projectId) {
+            clauses.push("project_id = ?");
+            params.push(projectId);
+        }
+        if (agentId) {
+            clauses.push("agent_id = ?");
+            params.push(agentId);
+        }
+        if (options.jobId) {
+            clauses.push("job_id = ?");
+            params.push(options.jobId);
+        }
+        if (since) {
+            clauses.push("timestamp >= ?");
+            params.push(since);
+        }
+        if (until) {
+            clauses.push("timestamp <= ?");
+            params.push(until);
+        }
+        const query = `SELECT * FROM token_usage ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""}`;
+        const rows = await this.db.all(query, ...params);
+        const filtered = this.filterRows(rows, { command: options.command });
+        const mapped = filtered
+            .map(({ row, metadata }) => {
+            const commandName = metadata.commandName ??
+                metadata.command_name ??
+                metadata.command ??
+                null;
+            const action = metadata.action ?? metadata.phase ?? null;
+            const errorKind = metadata.error_kind ??
+                metadata.errorKind ??
+                metadata.error ??
+                null;
+            return {
+                workspace_id: row.workspace_id,
+                agent_id: row.agent_id,
+                model_name: row.model_name,
+                job_id: row.job_id,
+                command_run_id: row.command_run_id,
+                task_run_id: row.task_run_id,
+                task_id: row.task_id,
+                project_id: row.project_id,
+                epic_id: row.epic_id,
+                user_story_id: row.user_story_id,
+                tokens_prompt: row.tokens_prompt,
+                tokens_completion: row.tokens_completion,
+                tokens_total: row.tokens_total,
+                cost_estimate: row.cost_estimate,
+                duration_seconds: row.duration_seconds,
+                timestamp: row.timestamp,
+                command_name: commandName,
+                action,
+                error_kind: errorKind,
+                metadata,
+            };
+        })
+            .sort((a, b) => {
+            const aTs = Date.parse(a.timestamp);
+            const bTs = Date.parse(b.timestamp);
+            if (Number.isNaN(aTs) || Number.isNaN(bTs))
+                return 0;
+            return aTs - bTs;
+        });
+        if (options.page && options.pageSize) {
+            const start = (options.page - 1) * options.pageSize;
+            return mapped.slice(start, start + options.pageSize);
+        }
+        return mapped;
+    }
+    async getConfig() {
+        if (this.client) {
+            const config = await this.client.getConfig(this.workspace.workspaceId);
+            return this.mapConfig(config);
+        }
+        const config = await this.readConfigFile();
+        const telemetry = config.telemetry ?? {};
+        const envOptOut = (process.env.MCODA_TELEMETRY ?? "").toLowerCase() === "off";
+        const optOut = telemetry.optOut === true || telemetry.optedOut === true || false;
+        const strict = telemetry.strict === true || false;
+        const remoteExport = !optOut && !envOptOut;
+        const localRecording = !strict;
+        return {
+            localRecording,
+            remoteExport,
+            optOut,
+            strict,
+            configPath: this.configPath,
+        };
+    }
+    async optOut(strict = false) {
+        if (this.client) {
+            const config = await this.client.optOut(this.workspace.workspaceId, strict);
+            return this.mapConfig(config);
+        }
+        const config = await this.readConfigFile();
+        config.telemetry = {
+            ...(config.telemetry ?? {}),
+            optOut: true,
+            strict: strict || (config.telemetry?.strict ?? false),
+        };
+        await this.writeConfigFile(config);
+        return this.getConfig();
+    }
+    async optIn() {
+        if (this.client) {
+            const config = await this.client.optIn(this.workspace.workspaceId);
+            return this.mapConfig(config);
+        }
+        const config = await this.readConfigFile();
+        config.telemetry = {
+            ...(config.telemetry ?? {}),
+            optOut: false,
+            strict: false,
+        };
+        await this.writeConfigFile(config);
+        return this.getConfig();
+    }
+}

package/dist/workspace/WorkspaceManager.d.ts

@@ -0,0 +1,35 @@
+export interface WorkspaceResolution {
+    workspaceRoot: string;
+    workspaceId: string;
+    id: string;
+    legacyWorkspaceIds: string[];
+    mcodaDir: string;
+    workspaceDbPath: string;
+    globalDbPath: string;
+    config?: WorkspaceConfig;
+}
+export interface TelemetryPreferences {
+    optOut?: boolean;
+    strict?: boolean;
+    endpoint?: string;
+    authToken?: string;
+}
+export interface WorkspaceConfig {
+    mirrorDocs?: boolean;
+    branch?: string;
+    docdexUrl?: string;
+    velocity?: {
+        implementationSpPerHour?: number;
+        reviewSpPerHour?: number;
+        qaSpPerHour?: number;
+        alpha?: number;
+    };
+    telemetry?: TelemetryPreferences;
+}
+export declare class WorkspaceResolver {
+    static resolveWorkspace(input: {
+        cwd?: string;
+        explicitWorkspace?: string;
+    }): Promise<WorkspaceResolution>;
+}
+//# sourceMappingURL=WorkspaceManager.d.ts.map

package/dist/workspace/WorkspaceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceManager.d.ts","sourceRoot":"","sources":["../../src/workspace/WorkspaceManager.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE;QACT,uBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAClC;AAqHD,qBAAa,iBAAiB;WACf,gBAAgB,CAAC,KAAK,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAiFjH"}

package/dist/workspace/WorkspaceManager.js

@@ -0,0 +1,201 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { PathHelper } from "@mcoda/shared";
+const fileExists = async (candidate) => {
+    try {
+        await fs.access(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const findGitRoot = async (start) => {
+    // Only consider the provided directory; do not walk upward.
+    const current = path.resolve(start);
+    const gitPath = path.join(current, ".git");
+    if (await fileExists(gitPath))
+        return current;
+    return undefined;
+};
+const findWorkspaceMarker = async (start) => {
+    // Only consider the provided directory; do not walk upward.
+    const current = path.resolve(start);
+    const marker = path.join(current, ".mcoda", "workspace.json");
+    const mcoda = path.join(current, ".mcoda");
+    if (await fileExists(marker))
+        return current;
+    if (await fileExists(mcoda))
+        return current;
+    return undefined;
+};
+const ensureGitignore = async (workspaceRoot) => {
+    const gitignorePath = path.join(workspaceRoot, ".gitignore");
+    const entry = ".mcoda/\n";
+    try {
+        const content = await fs.readFile(gitignorePath, "utf8");
+        if (content.includes(".mcoda/"))
+            return;
+        await fs.writeFile(gitignorePath, `${content.trimEnd()}\n${entry}`, "utf8");
+    }
+    catch {
+        await fs.writeFile(gitignorePath, entry, "utf8");
+    }
+};
+const readWorkspaceConfig = async (mcodaDir) => {
+    const configPath = path.join(mcodaDir, "config.json");
+    try {
+        const raw = await fs.readFile(configPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+};
+const readWorkspaceIdentity = async (mcodaDir) => {
+    const workspacePath = path.join(mcodaDir, "workspace.json");
+    try {
+        const raw = await fs.readFile(workspacePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.id)
+            return parsed;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const writeWorkspaceIdentity = async (mcodaDir, identity) => {
+    const workspacePath = path.join(mcodaDir, "workspace.json");
+    await fs.writeFile(workspacePath, JSON.stringify(identity, null, 2), "utf8");
+};
+const looksLikeWorkspaceId = (value) => /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value.trim());
+const migrateWorkspaceDbIds = async (workspace, legacyIds) => {
+    if (!legacyIds.length)
+        return;
+    try {
+        const { Connection } = await import("@mcoda/db");
+        const conn = await Connection.open(workspace.workspaceDbPath);
+        const db = conn.db;
+        const placeholders = legacyIds.map(() => "?").join(",");
+        const params = [workspace.workspaceId, ...legacyIds];
+        const tables = ["jobs", "command_runs", "token_usage"];
+        for (const table of tables) {
+            await db.run(`UPDATE ${table} SET workspace_id = ? WHERE workspace_id IN (${placeholders})`, params);
+        }
+        await conn.close();
+    }
+    catch {
+        /* best effort */
+    }
+    const updateJsonArray = async (filePath) => {
+        try {
+            const raw = await fs.readFile(filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed) || !parsed.length)
+                return;
+            let changed = false;
+            const updated = parsed.map((row) => {
+                if (row?.workspaceId && legacyIds.includes(row.workspaceId)) {
+                    changed = true;
+                    return { ...row, workspaceId: workspace.workspaceId };
+                }
+                return row;
+            });
+            if (changed) {
+                await fs.writeFile(filePath, JSON.stringify(updated, null, 2), "utf8");
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    await updateJsonArray(path.join(workspace.workspaceRoot, ".mcoda", "command_runs.json"));
+    await updateJsonArray(path.join(workspace.workspaceRoot, ".mcoda", "token_usage.json"));
+};
+export class WorkspaceResolver {
+    static async resolveWorkspace(input) {
+        const cwd = path.resolve(input.cwd ?? process.cwd());
+        let explicit = input.explicitWorkspace;
+        let explicitPath;
+        if (explicit) {
+            const candidatePath = path.resolve(explicit);
+            if (await fileExists(candidatePath)) {
+                explicitPath = candidatePath;
+            }
+            else if (await fileExists(path.join(candidatePath, ".mcoda"))) {
+                explicitPath = candidatePath;
+            }
+            else if (looksLikeWorkspaceId(explicit)) {
+                throw new Error(`Workspace id ${explicit} not recognized. Workspace registry lookups are not yet supported; pass a workspace path instead.`);
+            }
+            else {
+                throw new Error(`Workspace path ${explicit} not found`);
+            }
+        }
+        const fromMarker = await findWorkspaceMarker(explicitPath ?? cwd);
+        const gitRoot = await findGitRoot(explicitPath ?? cwd);
+        const workspaceRoot = explicitPath ?? fromMarker ?? gitRoot ?? cwd;
+        const mcodaDir = path.join(workspaceRoot, ".mcoda");
+        await PathHelper.ensureDir(mcodaDir);
+        await ensureGitignore(workspaceRoot);
+        const existingIdentity = await readWorkspaceIdentity(mcodaDir);
+        let identity;
+        let legacyIds = [];
+        if (existingIdentity) {
+            const existingLegacy = new Set(existingIdentity.legacyIds ?? []);
+            let updatedIdentity = false;
+            legacyIds = [...(existingIdentity.legacyIds ?? [])];
+            if (existingIdentity.id && existingIdentity.id !== workspaceRoot) {
+                legacyIds.push(workspaceRoot);
+                updatedIdentity = true;
+            }
+            if (!looksLikeWorkspaceId(existingIdentity.id)) {
+                legacyIds.push(existingIdentity.id);
+                identity = {
+                    ...existingIdentity,
+                    id: randomUUID(),
+                    legacyIds: Array.from(new Set(legacyIds)),
+                };
+                await writeWorkspaceIdentity(mcodaDir, identity);
+            }
+            else {
+                identity = {
+                    ...existingIdentity,
+                    legacyIds: Array.from(new Set(legacyIds)),
+                };
+                if ((identity.legacyIds?.length ?? 0) !== existingLegacy.size) {
+                    updatedIdentity = true;
+                }
+                if (updatedIdentity) {
+                    await writeWorkspaceIdentity(mcodaDir, identity);
+                }
+            }
+        }
+        else {
+            identity = {
+                id: randomUUID(),
+                name: path.basename(workspaceRoot),
+                createdAt: new Date().toISOString(),
+                legacyIds: [workspaceRoot],
+            };
+            await writeWorkspaceIdentity(mcodaDir, identity);
+        }
+        const legacyWorkspaceIds = Array.from(new Set([...(identity.legacyIds ?? []), workspaceRoot].filter(Boolean)));
+        const config = await readWorkspaceConfig(mcodaDir);
+        const resolution = {
+            workspaceRoot,
+            workspaceId: identity.id,
+            id: identity.id,
+            legacyWorkspaceIds,
+            mcodaDir,
+            workspaceDbPath: PathHelper.getWorkspaceDbPath(workspaceRoot),
+            globalDbPath: PathHelper.getGlobalDbPath(),
+            config,
+        };
+        // Best-effort migration of workspace_id columns and JSON logs from legacy IDs.
+        await migrateWorkspaceDbIds(resolution, legacyWorkspaceIds.filter((id) => id !== identity.id));
+        return resolution;
+    }
+}