@remixhq/mcp 0.1.13 → 0.1.14

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { createRequire } from "module";
-import { drainPendingFinalizeQueue } from "@remixhq/core/collab";
+import { drainAsyncJobs, drainPendingFinalizeQueue } from "@remixhq/core/collab";
 
 // src/domain/apiClient.ts
 import { createApiClient as createCoreApiClient, resolveConfig as resolveConfig2 } from "@remixhq/core";
@@ -623,7 +623,7 @@ var statusDataSchema = z2.object({
   status: genericRecordSchema,
   riskLevel: z2.enum(["low", "medium", "high"])
 });
-var initDataSchema = z2.object({
+var initSyncDataSchema = z2.object({
   reused: z2.boolean(),
   projectId: z2.string(),
   appId: z2.string(),
@@ -635,6 +635,23 @@ var initDataSchema = z2.object({
   createdCanonicalFamily: z2.boolean().optional(),
   baselineStatus: z2.enum(["seeded", "existing", "requires_re_anchor", "requires_sync"]).optional()
 });
+var initQueuedDataSchema = z2.object({
+  queued: z2.literal(true),
+  status: z2.literal("ready_to_record"),
+  doNotRetry: z2.literal(true),
+  jobId: z2.string(),
+  projectId: z2.string(),
+  appId: z2.string(),
+  dashboardUrl: z2.string(),
+  upstreamAppId: z2.string(),
+  bindingPath: z2.string(),
+  repoRoot: z2.string(),
+  bindingMode: z2.enum(["legacy", "lane", "explicit_root"]),
+  createdCanonicalFamily: z2.boolean(),
+  remoteUrl: z2.string().nullable(),
+  defaultBranch: z2.string().nullable()
+});
+var initDataSchema = initSyncDataSchema;
 var listDataSchema = z2.object({
   apps: genericArraySchema,
   pagination: paginationSchema
@@ -814,9 +831,15 @@ function getRecommendedNextActions(status) {
     case "pull":
       return ["Run remix_collab_sync_preview, then remix_collab_sync_apply if the preview is acceptable. This pulls the server delta into the local working tree without rewriting local git history."];
     case "re_anchor":
-      return ["Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to re-anchor the lane after manual Git/GitHub history movement."];
+      return [
+        "Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply. This seeds a local Remix baseline. It is required because no local baseline exists for this lane yet (fresh clone, deleted .remix/ state, or first init didn't seed) \u2014 not because of any specific git operation. After it succeeds, normal recording (remix_collab_finalize_turn) becomes available."
+      ];
+    case "record":
+      return [
+        "Run remix_collab_finalize_turn to capture the local boundary delta. This is the catch-all for any local content change since the last recorded turn, regardless of whether the change came from agent edits, manual user edits, git commit, git pull, git merge, git rebase, or git reset."
+      ];
     case "reconcile":
-      return ["Run remix_collab_reconcile_preview before attempting remix_collab_reconcile_apply. Reconcile now routes through the explicit Remix recovery/re-anchor flow for diverged state."];
+      return ["Run remix_collab_reconcile_preview before attempting remix_collab_reconcile_apply. Reconcile applies only when both the local workspace and the server lane changed since the last agreed baseline."];
     case "await_finalize":
       return [
         "Run remix_collab_drain_finalize_queue before merge-related or recovery flows. finalize_turn is queued only until the local finalize queue is drained."
@@ -865,6 +888,10 @@ function spawnFinalizeQueueDrainer() {
   child.unref();
   return true;
 }
+async function drainBeforeMutation(api) {
+  const results = await coreDrainPendingFinalizeQueue({ api });
+  return results.flatMap((result) => collectResultWarnings(result));
+}
 async function getStatus(params) {
   const api = params.includeRemote ? await createCollabApiClient() : null;
   const status = await coreCollabStatus({
@@ -890,19 +917,26 @@ async function initCollab(params) {
     api,
     cwd: params.cwd,
     appName: params.appName ?? null,
-    forceNew: params.forceNew ?? false
+    forceNew: params.forceNew ?? false,
+    asyncSubmit: false
   });
+  if ("queued" in result && result.queued) {
+    throw new Error(
+      "Unexpected queued init result on the MCP path. Async init is currently disabled for agent callers; if you intended to re-enable it, also restore the queued shape in initDataSchema (see remix-mcp/src/contracts/collab.ts)."
+    );
+  }
+  const syncResult = result;
   return {
-    data: result,
+    data: syncResult,
     warnings: collectResultWarnings(result),
-    recommendedNextActions: result.baselineStatus === "requires_re_anchor" ? [
-      "Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to anchor this checkout before recording turns."
-    ] : result.baselineStatus === "requires_sync" ? [
+    recommendedNextActions: syncResult.baselineStatus === "requires_re_anchor" ? [
+      "This checkout has no local Remix baseline yet. Run remix_collab_re_anchor_preview, then remix_collab_re_anchor_apply to seed one. After it succeeds, normal recording (remix_collab_finalize_turn) becomes available."
+    ] : syncResult.baselineStatus === "requires_sync" ? [
       "Run remix_collab_sync_preview, then remix_collab_sync_apply to pull the server delta and create the first local baseline for this checkout."
     ] : ["Run remix_collab_status to inspect sync, reconcile, and merge-request readiness before mutating bound-repo state."],
     logContext: {
-      repoRoot: result.repoRoot,
-      appId: result.appId
+      repoRoot: syncResult.repoRoot,
+      appId: syncResult.appId
     }
   };
 }
@@ -972,9 +1006,11 @@ async function finalizeCollabTurn(params) {
     sync: params.sync,
     allowBranchMismatch: params.allowBranchMismatch ?? false,
     idempotencyKey: params.idempotencyKey ?? null,
-    actor: params.agent
+    actor: params.agent,
+    awaitingUsageDeadlineMs: params.awaitingUsageDeadlineMs ?? null
   });
-  if (result.queued) {
+  const hasAwaitingDeadline = typeof params.awaitingUsageDeadlineMs === "number" && params.awaitingUsageDeadlineMs > 0;
+  if (result.queued && !hasAwaitingDeadline) {
     if (!spawnFinalizeQueueDrainer()) {
       await coreDrainPendingFinalizeQueue({ api });
     }
@@ -1038,7 +1074,9 @@ async function reAnchor(params) {
   return {
     data: result,
     warnings: collectWarnings(result.warnings),
-    recommendedNextActions: params.dryRun ? ["Run remix_collab_re_anchor_apply with confirm=true to re-anchor this lane after manual Git/GitHub history movement."] : [],
+    recommendedNextActions: params.dryRun ? [
+      "Run remix_collab_re_anchor_apply with confirm=true to seed a local Remix baseline for this checkout. Re-anchor is for missing-baseline cases only and does not replace remix_collab_finalize_turn for ordinary local content changes."
+    ] : [],
     logContext: {
       repoRoot: result.repoRoot,
       appId: result.currentAppId
@@ -1047,13 +1085,14 @@ async function reAnchor(params) {
 }
 async function requestMerge(params) {
   const api = await createCollabApiClient();
+  const drainWarnings = await drainBeforeMutation(api);
   const result = await coreCollabRequestMerge({
     api,
     cwd: params.cwd
   });
   return {
     data: result,
-    warnings: [],
+    warnings: drainWarnings,
     recommendedNextActions: result.id ? [`Run remix_collab_view_merge_request with mrId=${String(result.id)} to inspect the request before deciding whether to approve or reject it.`] : [],
     logContext: {
       mrId: typeof result.id === "string" ? result.id : null
@@ -1209,6 +1248,7 @@ async function syncUpstream(params) {
 }
 async function reconcile(params) {
   const api = await createCollabApiClient();
+  const drainWarnings = params.dryRun ? [] : await drainBeforeMutation(api);
   const result = await coreCollabReconcile({
     api,
     cwd: params.cwd,
@@ -1217,9 +1257,9 @@ async function reconcile(params) {
   });
   return {
     data: result,
-    warnings: collectWarnings(result.warnings),
+    warnings: [...drainWarnings, ...collectWarnings(result.warnings)],
     recommendedNextActions: params.dryRun ? ["Run remix_collab_reconcile_apply with confirm=true only if the preview is acceptable. This is the explicit Remix recovery flow for diverged state."] : [],
-    risks: params.dryRun ? ["Reconcile may upload local history to re-anchor the server lane before future recording continues."] : [],
+    risks: params.dryRun ? ["Reconcile may upload local history to recover the server lane onto the latest agreed state before future recording continues."] : [],
     logContext: {
       repoRoot: result.repoRoot ?? null
     }
@@ -1766,6 +1806,50 @@ async function accessDebug(params) {
   };
 }
 
+// src/tools/collab/autoSpawnHistoryImport.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync, mkdirSync, openSync } from "fs";
+import path2 from "path";
+var MARKER_REL_PATH = path2.join(".remix", ".history-imported");
+var LOG_REL_PATH = path2.join(".remix", "history-import.log");
+function shouldAutoSpawnHistoryImport(repoRoot) {
+  try {
+    return !existsSync(path2.join(repoRoot, MARKER_REL_PATH));
+  } catch {
+    return false;
+  }
+}
+function spawnHistoryImportDetached(repoRoot) {
+  const remixDir = path2.join(repoRoot, ".remix");
+  try {
+    mkdirSync(remixDir, { recursive: true });
+  } catch {
+  }
+  const logPath = path2.join(repoRoot, LOG_REL_PATH);
+  const out = openSync(logPath, "a");
+  const err = openSync(logPath, "a");
+  const child = spawn2(
+    "remix",
+    [
+      "history",
+      "import",
+      "--repo",
+      repoRoot,
+      // Include prompt text for parity with the CLI auto-spawn path:
+      // first-time UX is a lot worse if the dashboard renders every
+      // historical row as "(prompt not uploaded)".
+      "--include-prompt-text"
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", out, err],
+      env: { ...process.env, REMIX_HISTORY_AUTO_SPAWN: "1" }
+    }
+  );
+  child.unref();
+  return { pid: child.pid, logPath };
+}
+
 // src/tools/collab/register.ts
 function getAnnotations(access, options) {
   if (access === "read") {
@@ -1887,18 +1971,37 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_init",
-    description: "Import the current repository into Remix and write the local binding file.",
+    description: "Import the current repository into Remix and write the local binding file. Synchronous: by the time this tool resolves, the local binding file AND the local Remix baseline are both on disk, so the very next call to remix_collab_finalize_turn will succeed. Brand-new init on the default branch typically takes ~10s; non-default-branch init can take 30-90s while the server provisions a feature lane. The result includes `reused: boolean` (false for a brand-new app, true if a binding already existed) plus the canonical app/project identifiers and the dashboard URL. Use forceNew=true only when intentionally creating a new canonical family from scratch in a previously-bound repo; do NOT use forceNew as a retry mechanism for a failed init \u2014 it creates orphan backend apps and triggers canonical-family ambiguity errors on subsequent inits in this directory.",
     access: "remote_write",
     inputSchema: initInputSchema,
     outputSchema: initSuccessSchema,
     run: async (args) => {
       const input = z3.object(initInputSchema).parse(args);
       const cwd = resolvePolicyCwd(context.policy, input.cwd);
-      return initCollab({
+      const result = await initCollab({
         cwd,
         appName: input.appName,
         forceNew: input.forceNew
       });
+      try {
+        const repoRoot = result && typeof result === "object" && "data" in result && result.data && typeof result.data.repoRoot === "string" ? result.data.repoRoot : null;
+        if (repoRoot && shouldAutoSpawnHistoryImport(repoRoot)) {
+          const spawned = spawnHistoryImportDetached(repoRoot);
+          context.logger.log({
+            level: "info",
+            message: `history_import_auto_spawned pid=${spawned.pid ?? "?"} log=${spawned.logPath}`,
+            tool: "remix_collab_init",
+            repoRoot
+          });
+        }
+      } catch (spawnError) {
+        context.logger.log({
+          level: "error",
+          message: `history_import_auto_spawn_failed: ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`,
+          tool: "remix_collab_init"
+        });
+      }
+      return result;
     }
   });
   registerTool(server, context, {
@@ -1954,7 +2057,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_finalize_turn",
-    description: "Primary turn recorder for the current bound repository. Call this exactly once before the final response; it captures the current boundary locally and queues remote processing. Queued only: no remote change step exists yet until the finalize queue is drained.",
+    description: "Primary turn recorder for the current bound repository. Required: call this exactly once before the final response on every turn that touched a Remix-bound repo. Captures the current boundary locally and queues remote processing. Queued only: no remote change step exists yet until the finalize queue drains. Runtime exception: if this turn's context contains a [Remix runtime status] system note from the Remix UserPromptSubmit hook stating that the Stop hook will record this turn automatically, do NOT call this tool \u2014 the runtime is recording it on your behalf and a manual call would create a duplicate record. The runtime note is the only sanctioned override; trivial prompts, error states, and ambiguity all still require this call.",
     access: "local_write",
     inputSchema: finalizeTurnInputSchema,
     outputSchema: finalizeTurnSuccessSchema,
@@ -1969,13 +2072,14 @@ function registerCollabTools(server, context) {
         sync: input.sync,
         allowBranchMismatch: input.allowBranchMismatch ?? false,
         idempotencyKey: input.idempotencyKey,
-        agent: context.agentMetadata
+        agent: context.agentMetadata,
+        awaitingUsageDeadlineMs: 3e4
       });
     }
   });
   registerTool(server, context, {
     name: "remix_collab_drain_finalize_queue",
-    description: "Drain the local finalize queue and record queued finalize_turn jobs immediately. Use this before request-merge, reconcile, or other flows that require the remote change step to exist already.",
+    description: "Drain the local finalize queue and record queued finalize_turn jobs immediately. NOT required as a precondition for `remix_collab_request_merge` or `remix_collab_reconcile_apply` \u2014 those tools drain the queue internally before they run. Useful only for explicit recovery flows (e.g. status reports `await_finalize` and you want to flush before re-checking). Runtime exception: if this turn's context contains a [Remix runtime status] system note from the Remix UserPromptSubmit hook, the runtime drains the queue automatically in the background; do NOT call this tool unless an explicit recovery flow requires it.",
     access: "local_write",
     inputSchema: drainFinalizeQueueInputSchema,
     outputSchema: drainFinalizeQueueSuccessSchema,
@@ -2013,7 +2117,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_re_anchor_preview",
-    description: "Preview whether the current checkout needs an explicit re-anchor to adopt or recover external Git/GitHub history.",
+    description: "Preview whether this checkout needs a fresh local Remix baseline. Use only when status reports `re_anchor` (no local baseline exists for this lane yet \u2014 fresh clone, deleted `.remix/` state, or first init didn't seed). Re-anchor does not replace `remix_collab_finalize_turn`; ordinary local content changes (including merges, pulls, and rebases) are recorded by `finalize-turn`, not by re-anchor.",
     access: "read",
     inputSchema: previewInputSchema,
     outputSchema: reAnchorSuccessSchema,
@@ -2025,7 +2129,7 @@ function registerCollabTools(server, context) {
   });
   registerTool(server, context, {
     name: "remix_collab_re_anchor_apply",
-    description: "Explicitly re-anchor the current lane to adopted or recovered external Git/GitHub history, without rewriting the local checkout afterward.",
+    description: "Establish a local Remix baseline for the current checkout against the existing app head, without rewriting the local checkout afterward. Required only when status reports `re_anchor` (missing local baseline). It does not replace `remix_collab_finalize_turn` \u2014 local commits, pulls, merges, and rebases must still be recorded with `finalize-turn`.",
     access: "local_write",
     inputSchema: reAnchorInputSchema,
     outputSchema: reAnchorSuccessSchema,
@@ -3847,6 +3951,11 @@ async function main() {
     await drainPendingFinalizeQueue({ api });
     return;
   }
+  if (process.argv.includes("--drain-async-jobs")) {
+    const api = await createCollabApiClient();
+    await drainAsyncJobs({ api });
+    return;
+  }
   await startStdioServer({ version });
 }
 main().catch((error) => {