@taptap/instant-games-open-mcp 1.23.3 → 1.23.4

package/dist/maker.js

@@ -29334,9 +29334,132 @@ async function readMakerProjectLocalChanges(cwd) {
     ahead: unpushed.ahead
   };
 }
+async function inspectMakerRemoteSyncStatus(cwd) {
+  ensureGitAvailable();
+  const { projectRoot } = resolveUsableMakerGitWorkspace(cwd);
+  const branch = await currentBranch(projectRoot);
+  const remoteRef = `origin/${branch}`;
+  const rawStatus = await readGit(["status", "--porcelain", "-z"], projectRoot);
+  const localChanges = parseGitStatusFiles(rawStatus).filter(
+    (file2) => !isIgnoredBuildGuardChange(file2)
+  );
+  const hasLocalChanges = localChanges.length > 0;
+  if (branch !== "main") {
+    return {
+      projectRoot,
+      branch,
+      remoteRef,
+      status: "branch_not_allowed",
+      hasLocalChanges,
+      localChangeCount: localChanges.length,
+      localChanges,
+      aheadCount: 0,
+      behindCount: 0,
+      nextAction: "Maker 远端只接受 main 分支。开发或提交前请切回 main；如果当前分支已有本地提交，先让本地 AI 确认工作区状态，再把提交迁移到 main 后继续。"
+    };
+  }
+  try {
+    await runGitWithTransientRetry(["fetch", "origin"], {
+      cwd: projectRoot
+    });
+  } catch (error2) {
+    const failure = toMakerGitFailure(error2, "fetch");
+    return {
+      projectRoot,
+      branch,
+      remoteRef,
+      status: "remote_unavailable",
+      hasLocalChanges,
+      localChangeCount: localChanges.length,
+      localChanges,
+      aheadCount: 0,
+      behindCount: 0,
+      failure,
+      nextAction: getMakerRemoteSyncFailureNextAction(failure)
+    };
+  }
+  const counts = await readRemoteAheadBehindCounts(projectRoot, remoteRef);
+  if (!counts) {
+    return {
+      projectRoot,
+      branch,
+      remoteRef,
+      status: "remote_missing",
+      hasLocalChanges,
+      localChangeCount: localChanges.length,
+      localChanges,
+      aheadCount: 0,
+      behindCount: 0,
+      nextAction: "未找到 origin/main。请先确认当前目录是否是完整 Maker clone；不要新建分支或手动 git push，必要时重新执行 taptap-maker init。"
+    };
+  }
+  return {
+    projectRoot,
+    branch,
+    remoteRef,
+    status: classifyRemoteSyncStatus(counts.aheadCount, counts.behindCount),
+    hasLocalChanges,
+    localChangeCount: localChanges.length,
+    localChanges,
+    aheadCount: counts.aheadCount,
+    behindCount: counts.behindCount,
+    nextAction: nextActionForRemoteSync({
+      aheadCount: counts.aheadCount,
+      behindCount: counts.behindCount,
+      hasLocalChanges,
+      branch
+    })
+  };
+}
+function getMakerRemoteSyncFailureNextAction(failure) {
+  if (failure.classification === "auth") {
+    return "暂时无法检查 Maker 远端是否有新提交：Git 鉴权失败。请先运行 `taptap-maker pat set` 并粘贴新的 Maker PAT 后，再重新读取 maker://status。";
+  }
+  return "暂时无法检查 Maker 远端是否有新提交。请把 failure 信息反馈给用户；如果只是 503、5xx、超时或网络中断，可稍后重新读取 maker://status。";
+}
 function isIgnoredBuildGuardChange(file2) {
   return file2 === ".gitignore" || file2 === ".maker-mcp" || file2.startsWith(".maker-mcp/");
 }
+async function readRemoteAheadBehindCounts(cwd, remoteRef) {
+  try {
+    await readGit(["rev-parse", "--verify", remoteRef], cwd);
+    const text = await readGit(["rev-list", "--left-right", "--count", `HEAD...${remoteRef}`], cwd);
+    const [aheadText, behindText] = text.trim().split(/\s+/);
+    return {
+      aheadCount: Number.parseInt(aheadText || "0", 10) || 0,
+      behindCount: Number.parseInt(behindText || "0", 10) || 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function classifyRemoteSyncStatus(aheadCount, behindCount) {
+  if (aheadCount > 0 && behindCount > 0) {
+    return "diverged";
+  }
+  if (behindCount > 0) {
+    return "needs_pull";
+  }
+  if (aheadCount > 0) {
+    return "ahead";
+  }
+  return "up_to_date";
+}
+function nextActionForRemoteSync(input2) {
+  if (input2.aheadCount > 0 && input2.behindCount > 0) {
+    return `本地和远端都已有新提交（本地 ahead ${input2.aheadCount}，远端 behind ${input2.behindCount}）。不要直接 push 或无脑 pull；请让本地 AI 先检查 git status，再选择 rebase 或 merge 当前 Maker 远端变更。`;
+  }
+  if (input2.behindCount > 0) {
+    if (input2.hasLocalChanges) {
+      return `Maker 远端有 ${input2.behindCount} 个新提交，但本地有未提交改动。不要直接 pull；请让本地 AI 先查看 git status，然后由用户选择：先提交当前改动、stash 后 pull 再恢复，或暂时取消同步。`;
+    }
+    return `Maker 远端有 ${input2.behindCount} 个新提交，且本地工作区干净。可以让本地 AI 执行 git pull --ff-only origin ${input2.branch} 后再开始修改。`;
+  }
+  if (input2.aheadCount > 0) {
+    return `本地已有 ${input2.aheadCount} 个未推送提交。构建或提交时请继续使用 maker_build_current_directory，不要手动执行通用 git push。`;
+  }
+  return "本地 main 与 Maker 远端 main 已同步，可以继续开发。";
+}
 function ensureTargetCanBindApp(target, appId) {
   const existingConfig = loadProjectConfig(target);
   if (!(existingConfig == null ? void 0 : existingConfig.project_id) || existingConfig.project_id === appId) {
@@ -29454,6 +29577,12 @@ function classifyGitFailure(message) {
   )) {
     return "git_missing";
   }
+  if (/only refs\/heads\/main is accepted/i.test(message)) {
+    return "branch_not_allowed";
+  }
+  if (/matches forbidden pattern|forbidden pattern/i.test(message)) {
+    return "forbidden_path";
+  }
   if (/authentication|authorization|401|403|forbidden|unauthorized|could not read username|repository not found/i.test(
     message
   )) {
@@ -29496,7 +29625,7 @@ function getMakerGitRetryDecision(message) {
   return { retry: false };
 }
 function isNonRetryableGitFailure(message) {
-  return /authentication|authorization|401|403|forbidden|unauthorized|could not read username|repository not found|not a git repository|not empty|already exists and is not an empty directory|permission denied|Operation not permitted|non-fast-forward|fetch first|rejected|failed to push some refs|would be overwritten|conflicting local files/i.test(
+  return /authentication|authorization|401|403|forbidden|unauthorized|could not read username|repository not found|only refs\/heads\/main is accepted|matches forbidden pattern|forbidden pattern|not a git repository|not empty|already exists and is not an empty directory|permission denied|Operation not permitted|non-fast-forward|fetch first|rejected|failed to push some refs|would be overwritten|conflicting local files/i.test(
     message
   );
 }
@@ -29508,6 +29637,10 @@ function nextActionForFailure(classification) {
       return "运行 `taptap-maker pat set` 并粘贴新的 Maker PAT 后，再重试 maker_build_current_directory；如果仍失败，请确认 PAT 是否过期或缺少 Maker git 权限。";
     case "remote_transient":
       return "远端 Maker git 服务临时不可用。本地 commit 会保留；不要手动执行通用 git push，稍后直接重试 maker_build_current_directory。";
+    case "branch_not_allowed":
+      return "Maker 远端只接受 main 分支提交。当前本地 commit 已保留但未推送；不要 pull/rebase、不要新建分支、不要手动执行通用 git push。请先确认工作区无未提交改动，切回 main 分支（必要时从 origin/main 创建 main），把这次本地 commit cherry-pick 到 main 后，再重试 maker_build_current_directory。";
+    case "forbidden_path":
+      return "本地 commit 包含 Maker 远端禁止提交的路径或目录。远端 pre-receive hook 已返回具体 forbidden pattern；这不是鉴权问题，不要刷新 Maker PAT。请按 stderr 中的 pattern 找到对应文件，把这些路径从本地 commit 移除（例如保留工作区文件但取消跟踪后修正当前未推送 commit），确认 git status 不再包含这些路径后，再重试 maker_build_current_directory。";
     case "remote_rejected":
       return "远端已有新提交。不要新建分支、不要要任务号、不要手动执行通用 git push；先询问用户是否 pull/rebase 当前 Maker 远端变更，再重试 maker_build_current_directory。";
     case "local":
@@ -30334,7 +30467,7 @@ function getBundledSkillSourceDir(skillName) {
 }
 
 // src/maker/server/mcp.ts
-var VERSION = true ? "1.23.3" : "dev";
+var VERSION = true ? "1.23.4" : "dev";
 var DEFAULT_PROXY_PACKAGE = "@taptap/instant-games-open-mcp@1.22.0";
 var DEFAULT_BUILD_TIMEOUT_MS = 10 * 60 * 1e3;
 var LONG_OPERATION_HEARTBEAT_MS = 3 * 60 * 1e3;
@@ -30357,6 +30490,10 @@ var tools = [
         target_dir: {
           type: "string",
           description: "Optional user current working directory to inspect. Use when the MCP process cwd differs from the user project CWD."
+        },
+        skip_remote_sync: {
+          type: "boolean",
+          description: "If true, skip git fetch/ahead-behind remote sync checks. Use this for frequent polling or quick local status checks."
         }
       }
     }
@@ -30470,7 +30607,8 @@ async function startMakerMcpServer() {
             {
               type: "text",
               text: await formatStatus({
-                targetDir: args.target_dir
+                targetDir: args.target_dir,
+                skipRemoteSync: args.skip_remote_sync
               })
             }
           ]
@@ -30536,6 +30674,7 @@ async function formatStatus(options = {}) {
   const targetDir = resolveMakerToolTargetDir(options.targetDir);
   const identify = identifyMakerProject({ cwd: targetDir });
   const gitDirectoryStatus = inspectMakerDirectoryGitStatus(targetDir);
+  const remoteSyncText = identify.projectRoot && gitDirectoryStatus.isUsableMakerGitRepo && !options.skipRemoteSync ? await formatMakerRemoteSyncStatusSafely(identify.projectRoot) : identify.projectRoot && gitDirectoryStatus.isUsableMakerGitRepo ? formatMakerRemoteSyncSkipped() : "";
   const pat = loadPat();
   let tapAuth = loadTapAuth();
   const makerPatTokensUrl = getMakerPatTokensUrl();
@@ -30581,6 +30720,8 @@ async function formatStatus(options = {}) {
     "",
     formatMakerGitDirectoryStatus(gitDirectoryStatus),
     "",
+    remoteSyncText,
+    "",
     pat ? "" : ["Auth next step", "", `Maker PAT 缺失。PAT 页面：${makerPatTokensUrl}`].join("\n"),
     "",
     tapAuthRefreshText,
@@ -30592,6 +30733,59 @@ async function formatStatus(options = {}) {
     projectSection
   ].filter(Boolean).join("\n");
 }
+function formatMakerRemoteSyncSkipped() {
+  return [
+    "Maker remote sync",
+    "",
+    "- status: skipped",
+    "- next_action: 已跳过远端同步检查；如需确认是否需要 pull，请重新读取 maker_status_lite 且不要设置 skip_remote_sync。"
+  ].join("\n");
+}
+async function formatMakerRemoteSyncStatus(projectRoot) {
+  const status = await inspectMakerRemoteSyncStatus(projectRoot);
+  return formatMakerRemoteSyncStatusLines(status).join("\n");
+}
+async function formatMakerRemoteSyncStatusSafely(projectRoot) {
+  try {
+    return await formatMakerRemoteSyncStatus(projectRoot);
+  } catch (error2) {
+    return formatMakerRemoteSyncUnavailable(error2);
+  }
+}
+function formatMakerRemoteSyncUnavailable(error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return [
+    "Maker remote sync",
+    "",
+    "- status: unavailable",
+    `- failure_name: ${error2 instanceof Error ? error2.name : typeof error2}`,
+    `- failure_message: ${message}`,
+    "- next_action: 远端同步检查失败；本地状态仍可继续查看。请稍后重试 maker_status_lite，频繁轮询时可设置 skip_remote_sync=true。"
+  ].join("\n");
+}
+function formatMakerRemoteSyncStatusLines(status) {
+  var _a2, _b, _c;
+  const localPreview = status.localChanges.slice(0, 10);
+  return [
+    "Maker remote sync",
+    "",
+    `- status: ${status.status}`,
+    `- branch: ${status.branch}`,
+    `- remote_ref: ${status.remoteRef}`,
+    `- ahead: ${status.aheadCount}`,
+    `- behind: ${status.behindCount}`,
+    `- local_changes: ${status.hasLocalChanges ? "yes" : "no"}`,
+    status.hasLocalChanges ? `- local_change_count: ${status.localChangeCount}` : "",
+    ...localPreview.map((file2) => `  - ${file2}`),
+    status.localChanges.length > localPreview.length ? `  - ... ${status.localChanges.length - localPreview.length} more` : "",
+    status.failure ? `- failure_classification: ${status.failure.classification}` : "",
+    ((_a2 = status.failure) == null ? void 0 : _a2.retryable) !== void 0 ? `- failure_retryable: ${status.failure.retryable ? "yes" : "no"}` : "",
+    ((_b = status.failure) == null ? void 0 : _b.retryReason) ? `- failure_retry_reason: ${status.failure.retryReason}` : "",
+    ((_c = status.failure) == null ? void 0 : _c.stderr) ? `- failure_stderr:
+${indent(status.failure.stderr)}` : "",
+    `- next_action: ${status.nextAction}`
+  ].filter(Boolean);
+}
 function formatMakerGitDirectoryStatus(status) {
   return [
     "Maker Git directory",
@@ -30658,9 +30852,9 @@ async function formatAutoProjectListFromPat() {
     const projects = await listMakerProjects();
     return [
       "本地已有 Maker PAT，当前目录尚未绑定 Maker 项目。",
-      "当前目录未绑定时，必须逐项展示下面完整 Maker Apps 列表，不要只总结数量；选择、解释和 clone 顺序请参考 taptap-maker-local skill。",
+      "当前目录未绑定时，先展示下面的 Maker Apps 预览和总数，避免长列表刷屏；选择、解释和 clone 顺序请参考 taptap-maker-local skill。",
       "",
-      formatProjectList(projects)
+      formatStatusProjectList(projects)
     ].join("\n");
   } catch (error2) {
     return [
@@ -30670,7 +30864,22 @@ async function formatAutoProjectListFromPat() {
     ].join("\n");
   }
 }
-function formatProjectList(projects) {
+var MAKER_STATUS_PROJECT_TEXT_LIMIT = 40;
+function getStatusProjectActivityTime(project) {
+  const value = project.lastConversationAt || project.lastAccessedAt || project.createdAt;
+  if (!value) {
+    return 0;
+  }
+  const time3 = Date.parse(value);
+  return Number.isNaN(time3) ? 0 : time3;
+}
+function sortStatusProjectsByRecentActivity(projects) {
+  return projects.map((project, index) => ({ project, index })).sort((left, right) => {
+    const timeDiff = getStatusProjectActivityTime(right.project) - getStatusProjectActivityTime(left.project);
+    return timeDiff || left.index - right.index;
+  }).map(({ project }) => project);
+}
+function formatStatusProjectList(projects) {
   if (projects.length === 0) {
     return [
       "No Maker apps found.",
@@ -30678,18 +30887,25 @@ function formatProjectList(projects) {
       "请确认 Maker PAT 是否有效，或等待 Maker app list 接口对齐。"
     ].join("\n");
   }
+  const visibleProjects = sortStatusProjectsByRecentActivity(projects).slice(
+    0,
+    MAKER_STATUS_PROJECT_TEXT_LIMIT
+  );
+  const hiddenCount = projects.length - visibleProjects.length;
   return [
-    "Maker apps",
+    `Maker apps (${projects.length})`,
     "",
-    "请把下面每一个 app 条目展示给用户，不要只说共有多少个。",
+    hiddenCount > 0 ? `默认按最近活跃排序展示前 ${visibleProjects.length} 个；其余 ${hiddenCount} 个请不要逐条刷屏。` : "已按最近活跃排序展示全部 app；请询问用户选择。",
+    hiddenCount > 0 ? "如果用户没有看到目标 app，请提示可以继续查看更多：在 taptap-maker init 交互中输入 next，或运行 taptap-maker apps --offset 40 --limit 40；也可以让用户提供 app_id，或运行 taptap-maker apps --json 做机器可读查询。" : void 0,
+    "AI 展示建议：如果聊天或客户端宽度足够，可把 app 预览整理成两列紧凑布局；每个 app 保留序号、app_id、名称，以及可用的最近活跃时间或 user_id。窄屏保持单列。不要省略 app_id，也不要在用户确认前自动选择 app。",
     "",
-    ...projects.map(
+    ...visibleProjects.map(
       (project, index) => `${index + 1}. ${project.id}${project.name ? `  ${project.name}` : ""}${project.user_id ? `  user_id=${project.user_id}` : ""}${project.gameType ? `  gameType=${project.gameType}` : ""}${project.stage ? `  stage=${project.stage}` : ""}${project.createdAt ? `  createdAt=${project.createdAt}` : ""}${project.lastConversationAt ? `  lastConversationAt=${project.lastConversationAt}` : ""}`
     ),
     "",
     "仅当当前目录未绑定且用户要初始化或 clone 时，才让用户选择 app 并继续 taptap-maker init。",
     "如果当前目录已绑定 Maker 项目，这个列表仅作账号项目参考；请继续当前项目，除非用户明确要求切换或重新 clone。"
-  ].join("\n");
+  ].filter((line) => line !== void 0).join("\n");
 }
 function formatClonePartialStateLines(targetDir) {
   const resolvedTargetDir = path7.resolve(targetDir);
@@ -30878,6 +31094,10 @@ function formatDuration(ms) {
   }
   return `${minutes}m ${seconds}s`;
 }
+function formatMakerAppWebUrl(projectId, env) {
+  const makerEnv = env === "rnd" || env === "production" ? env : void 0;
+  return `${getMakerWebUrl(makerEnv)}/app/${encodeURIComponent(projectId)}`;
+}
 async function buildCurrentDirectory(options) {
   var _a2;
   const localChanges = await readMakerProjectLocalChanges(options.targetDir);
@@ -30977,6 +31197,7 @@ async function runRemoteBuildCurrentDirectory(options, targetDir) {
       projectPath: proxy.projectPath,
       serverUrl: proxy.serverUrl,
       env: proxy.env,
+      makerUrl: formatMakerAppWebUrl(proxy.projectId, proxy.env),
       timeoutMs,
       buildArgs,
       resultText: formatRemoteToolResult(result)
@@ -31105,6 +31326,7 @@ function formatBuildResult(result, progressSummary) {
     "",
     `- project_root: ${result.projectRoot}`,
     `- project_id: ${result.projectId}`,
+    `- maker_url: ${result.makerUrl || formatMakerAppWebUrl(result.projectId, result.env)}`,
     `- project_path: ${result.projectPath}`,
     `- server_url: ${result.serverUrl}`,
     `- env: ${result.env}`
@@ -31132,9 +31354,21 @@ function formatPushRecoveryLines(submitResult) {
     submitResult.ahead ? `- git_state: ${submitResult.ahead}` : "",
     "- retry_tool: maker_build_current_directory",
     "- do_not_use_generic_git_push: yes",
-    "- user_message: 本地提交已经保留，但还没推送到 Maker 远端；直接重试 Maker 提交/构建工具即可。"
+    `- user_message: ${pushRecoveryUserMessage(submitResult.failure)}`
   ].filter(Boolean);
 }
+function pushRecoveryUserMessage(failure) {
+  switch (failure == null ? void 0 : failure.classification) {
+    case "branch_not_allowed":
+      return "本地提交已经保留，但 Maker 远端只接受 main 分支；请切回 main 并把本地提交迁移到 main 后，再重试 Maker 提交/构建工具。";
+    case "forbidden_path":
+      return "本地提交已经保留，但包含 Maker 远端禁止提交的路径或目录；请按 failure.stderr 中的 forbidden pattern 从未推送 commit 中移除这些路径，再重试 Maker 提交/构建工具。";
+    case "remote_transient":
+      return "本地提交已经保留，但还没推送到 Maker 远端；远端临时异常恢复后，直接重试 Maker 提交/构建工具即可。";
+    default:
+      return "本地提交已经保留，但还没推送到 Maker 远端；请先按 failure.next_action 修复原因，再重试 Maker 提交/构建工具。";
+  }
+}
 function formatMakerBuildFailureLines(failure) {
   return [
     "build_failure:",
@@ -31438,16 +31672,18 @@ async function runApps(parsed, ctx) {
   if (pat) {
     warnPatArgExposure();
   }
+  const limit = numberOption(parsed, "limit");
+  const offset = numberOption(parsed, "offset");
   const projects = await listMakerProjects({ pat });
   if (ctx.json) {
     writeJson(projects);
     return;
   }
-  process.stdout.write(`${formatProjectList2(projects)}
+  process.stdout.write(`${formatMakerProjectList(projects, { limit, offset })}
 `);
 }
 async function runPatSet(parsed, ctx) {
-  const pat = await resolvePatSet(parsed);
+  const pat = await resolvePatSet(parsed, ctx);
   saveManualMakerPat(pat);
   const tapAuth = await requestTapAuthWithPat(pat);
   emit(ctx, "pat", "Maker PAT and TapTap token saved", {
@@ -31456,7 +31692,7 @@ async function runPatSet(parsed, ctx) {
     kid: mask(tapAuth.kid)
   });
 }
-async function resolvePatSet(parsed) {
+async function resolvePatSet(parsed, ctx) {
   if (booleanOption(parsed, "pat_stdin") || booleanOption(parsed, "pat_from_stdin")) {
     const pat = fs7.readFileSync(0, "utf8").trim();
     if (!pat) {
@@ -31470,6 +31706,10 @@ async function resolvePatSet(parsed) {
     warnPatArgExposure();
     return fromPositional || fromOption;
   }
+  if (!ctx.json) {
+    process.stdout.write(`Create one at: ${getMakerPatTokensUrl(makerEnvOption(parsed))}
+`);
+  }
   return promptRequired("PAT");
 }
 async function runMcpInstall(parsed, ctx) {
@@ -31495,15 +31735,22 @@ async function runMcpVerify(parsed, ctx) {
   const result = spawnSync4(command.command, [...command.args, "help"], {
     encoding: "utf8"
   });
+  const failureType = classifyMcpVerifyFailure(result);
+  const commandText = formatShellCommand([command.command, ...command.args, "help"]);
   const payload = {
     mode,
     package: mode === "npx" ? pkg : void 0,
-    command: formatShellCommand([command.command, ...command.args, "help"]),
+    command: commandText,
     status: result.status,
+    signal: result.signal,
     ok: result.status === 0,
     stdout: result.stdout,
     stderr: result.stderr,
-    error: (_a2 = result.error) == null ? void 0 : _a2.message
+    error: (_a2 = result.error) == null ? void 0 : _a2.message,
+    failure_type: failureType,
+    explanation: failureType ? getMcpVerifyFailureExplanation(mode, failureType) : void 0,
+    next_steps: failureType ? getMcpVerifyNextSteps(mode, commandText) : void 0,
+    is_maker_mcp_started: false
   };
   if (ctx.json) {
     writeJson(payload);
@@ -31511,18 +31758,68 @@ async function runMcpVerify(parsed, ctx) {
   }
   process.stdout.write(
     [
-      payload.ok ? "✓ MCP config command can spawn taptap-maker" : "✗ MCP config command spawn failed",
+      payload.ok ? "✓ MCP config command can spawn taptap-maker" : "✗ MCP config command check failed before Maker MCP started",
       `- mode: ${payload.mode}`,
       `- command: ${payload.command}`,
       mode === "npx" ? "- scope: verifies the npx command written by taptap-maker mcp install" : "- scope: verifies only the currently running CLI binary",
       `- status: ${payload.status}`,
+      payload.signal ? `- signal: ${payload.signal}` : "",
+      payload.failure_type ? `- failure_type: ${payload.failure_type}` : "",
+      payload.explanation ? `- explanation: ${payload.explanation}` : "",
       payload.error ? `- error: ${payload.error}` : "",
       payload.stderr ? `- stderr:
 ${indent2(payload.stderr)}` : "",
+      payload.next_steps ? ["Next steps:", ...payload.next_steps.map((step, index) => `${index + 1}. ${step}`)].join(
+        "\n"
+      ) : "",
       ""
     ].filter(Boolean).join("\n")
   );
 }
+function classifyMcpVerifyFailure(result) {
+  if (result.status === 0) {
+    return void 0;
+  }
+  if (result.error) {
+    return "spawn_error";
+  }
+  if (result.signal) {
+    return "signal";
+  }
+  if (typeof result.status === "number") {
+    return "non_zero_exit";
+  }
+  return "unknown_no_status";
+}
+function getMcpVerifyFailureExplanation(mode, failureType) {
+  if (mode === "self") {
+    return [
+      "The current taptap-maker CLI help command did not exit cleanly.",
+      "This is a local CLI startup check, not a Maker MCP business error."
+    ].join(" ");
+  }
+  const base = "This is a local Node/npm/npx startup check, not a Maker MCP business error.";
+  if (failureType === "non_zero_exit") {
+    return `The configured npx command exited with a non-zero status. ${base}`;
+  }
+  if (failureType === "spawn_error") {
+    return `The configured npx command could not be spawned. ${base}`;
+  }
+  if (failureType === "signal") {
+    return `The configured npx command was terminated by a signal. ${base}`;
+  }
+  return `The configured npx command did not exit normally. ${base}`;
+}
+function getMcpVerifyNextSteps(mode, commandText) {
+  if (mode === "self") {
+    return ["Run `taptap-maker help` directly and inspect the printed error."];
+  }
+  return [
+    `Run the command above directly: ${commandText}`,
+    "Run `taptap-maker mcp verify --mode self` to verify the current CLI binary.",
+    "If direct npx also fails, check `where.exe npx`, `where.exe node`, `where.exe npm`, `node -v`, and `npm -v`."
+  ];
+}
 async function runDevKitUpdate(parsed, ctx) {
   const targetDir = path8.resolve(stringOption(parsed, "target_dir") || process.cwd());
   const result = await installAiDevKit({
@@ -31548,9 +31845,14 @@ async function resolvePat(parsed, ctx) {
       `Maker PAT missing. Create one at ${getMakerPatTokensUrl(makerEnvOption(parsed))}`
     );
   }
+  const patPage = getMakerPatTokensUrl(makerEnvOption(parsed));
   emit(ctx, "pat_required", "Maker PAT is required", {
-    pat_page: getMakerPatTokensUrl(makerEnvOption(parsed))
+    pat_page: patPage
   });
+  if (!ctx.json) {
+    process.stdout.write(`Create one at: ${patPage}
+`);
+  }
   const pat = await promptRequired("Paste Maker PAT");
   saveManualMakerPat(pat);
   return pat;
@@ -31566,18 +31868,38 @@ async function resolveProjectSelection(parsed, projects, options) {
   if (options.skipConfirm) {
     throw new Error("Missing --app-id in non-interactive init mode.");
   }
-  process.stdout.write(`${formatProjectList2(projects)}
+  const orderedProjects = sortProjectsByRecentActivity(projects);
+  const limit = MAKER_PROJECT_DEFAULT_TEXT_LIMIT;
+  let offset = 0;
+  for (; ; ) {
+    process.stdout.write(`${formatMakerProjectList(orderedProjects, { limit, offset })}
 `);
-  const answer = await promptRequired("Choose app by index or app_id");
-  const byIndex = Number(answer);
-  if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= projects.length) {
-    return projects[byIndex - 1];
-  }
-  const selected = projects.find((project) => project.id === answer.trim());
-  if (!selected) {
-    throw new Error(`Unknown Maker app selection: ${answer}`);
+    const answer = await promptRequired("Choose app by index, app_id, or next");
+    const normalized = answer.trim().toLowerCase();
+    if (["n", "next", "more"].includes(normalized)) {
+      const nextOffset = offset + limit;
+      if (nextOffset >= orderedProjects.length) {
+        process.stdout.write("No more Maker apps in this list.\n");
+      } else {
+        offset = nextOffset;
+      }
+      continue;
+    }
+    if (["p", "prev", "previous"].includes(normalized)) {
+      offset = Math.max(offset - limit, 0);
+      continue;
+    }
+    const byIndex = Number(answer);
+    const visibleCount = Math.min(limit, orderedProjects.length - offset);
+    if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= visibleCount) {
+      return orderedProjects[offset + byIndex - 1];
+    }
+    const selected = projects.find((project) => project.id === answer.trim());
+    if (!selected) {
+      throw new Error(`Unknown Maker app selection: ${answer}`);
+    }
+    return selected;
   }
-  return selected;
 }
 async function prepareDevKit(targetDir, ctx) {
   const before = inspectAiDevKit(targetDir);
@@ -31755,17 +32077,59 @@ function saveInitState(targetDir, state) {
     "utf8"
   );
 }
-function formatProjectList2(projects) {
+var MAKER_PROJECT_DEFAULT_TEXT_LIMIT = 40;
+var MAKER_PROJECT_MAX_TEXT_LIMIT = 100;
+function normalizeListLimit(limit) {
+  if (!Number.isFinite(limit) || limit === void 0) {
+    return MAKER_PROJECT_DEFAULT_TEXT_LIMIT;
+  }
+  return Math.min(Math.max(Math.trunc(limit), 1), MAKER_PROJECT_MAX_TEXT_LIMIT);
+}
+function normalizeListOffset(offset) {
+  if (!Number.isFinite(offset) || offset === void 0) {
+    return 0;
+  }
+  return Math.max(Math.trunc(offset), 0);
+}
+function getProjectActivityTime(project) {
+  const value = project.lastConversationAt || project.lastAccessedAt || project.createdAt;
+  if (!value) {
+    return 0;
+  }
+  const time3 = Date.parse(value);
+  return Number.isNaN(time3) ? 0 : time3;
+}
+function sortProjectsByRecentActivity(projects) {
+  return projects.map((project, index) => ({ project, index })).sort((left, right) => {
+    const timeDiff = getProjectActivityTime(right.project) - getProjectActivityTime(left.project);
+    return timeDiff || left.index - right.index;
+  }).map(({ project }) => project);
+}
+function formatProjectListItem(project, index) {
+  const name = project.name || "(unnamed)";
+  const lastActive = project.lastConversationAt || project.lastAccessedAt || project.createdAt;
+  return `${index + 1}. ${name}  id=${project.id}${lastActive ? `  last_active=${lastActive}` : ""}`;
+}
+function formatMakerProjectList(projects, options = {}) {
   if (projects.length === 0) {
     return "No Maker apps found.";
   }
+  const limit = normalizeListLimit(options.limit);
+  const offset = normalizeListOffset(options.offset);
+  const sortedProjects = sortProjectsByRecentActivity(projects);
+  const visibleProjects = sortedProjects.slice(offset, offset + limit);
+  const hiddenCount = projects.length - visibleProjects.length;
+  const nextOffset = offset + visibleProjects.length;
+  const hasNextPage = nextOffset < projects.length;
+  const startIndex = visibleProjects.length > 0 ? offset + 1 : 0;
+  const endIndex = visibleProjects.length > 0 ? Math.min(offset + visibleProjects.length, projects.length) : 0;
   return [
     `Maker apps (${projects.length})`,
+    visibleProjects.length > 0 && offset === 0 ? `Showing ${visibleProjects.length} most recently active apps, sorted by last activity. ${hiddenCount} more hidden.` : `Showing apps ${startIndex}-${endIndex} of ${projects.length}, sorted by last activity.`,
+    hasNextPage ? `To continue, run: taptap-maker apps --offset ${nextOffset} --limit ${limit}. If the target is hidden, enter its app_id directly or use --json to get the complete app list.` : `No more apps in this view. If needed, use --json to get the complete app list.`,
     "",
-    ...projects.map(
-      (project, index) => `${index + 1}. ${project.id}${project.name ? `  ${project.name}` : ""}${project.user_id ? `  user_id=${project.user_id}` : ""}${project.gameType ? `  gameType=${project.gameType}` : ""}${project.stage ? `  stage=${project.stage}` : ""}${project.lastConversationAt ? `  lastConversationAt=${project.lastConversationAt}` : ""}`
-    )
-  ].join("\n");
+    ...visibleProjects.map((project, index) => formatProjectListItem(project, index))
+  ].filter((line) => line !== "").join("\n");
 }
 function emit(ctx, step, message, data) {
   if (ctx.json) {
@@ -31822,6 +32186,14 @@ function stringOption(parsed, key) {
   const value = parsed.options[key];
   return typeof value === "string" ? value : void 0;
 }
+function numberOption(parsed, key) {
+  const value = stringOption(parsed, key);
+  if (value === void 0) {
+    return void 0;
+  }
+  const number3 = Number(value);
+  return Number.isFinite(number3) ? number3 : void 0;
+}
 function booleanOption(parsed, key) {
   return parsed.options[key] === true || parsed.options[key] === "true";
 }
@@ -31867,9 +32239,10 @@ function printHelp() {
       "  taptap-maker                         Start MCP server mode",
       "  taptap-maker init [--env rnd|production] [--app-id ID] [--target-dir DIR] [--pat PAT]",
       "                     [--skip-confirm] [--skip-mcp-install] [--register-mcp codex,cursor,claude]",
-      "                     [--package @taptap/instant-games-open-mcp] [--json]",
+      "                     [--json]",
       "  taptap-maker doctor [--target-dir DIR] [--env rnd|production] [--json]",
-      "  taptap-maker apps [--pat PAT] [--json]  # warns: PAT appears in ps/history",
+      "  taptap-maker apps [--pat PAT] [--limit N] [--offset N] [--json]",
+      "                     # --pat warns: PAT appears in ps/history",
       "  taptap-maker pat set [--pat-stdin] [--json]",
       "  taptap-maker pat set [PAT|--pat PAT] [--json]  # warns: PAT appears in ps/history",
       "  taptap-maker mcp install [--ide codex,cursor,claude] [--env rnd|production]",
@@ -31879,6 +32252,7 @@ function printHelp() {
       "  taptap-maker dev-kit update [--target-dir DIR] [--json]",
       "",
       "MCP verify defaults to the npx command written into AI client config.",
+      "Advanced: init and mcp install accept --package only when testing a different npm package.",
       "",
       "Windows note:",
       "  Generated MCP configs use npx.cmd automatically on Windows.",
@@ -31977,21 +32351,23 @@ function printHelp2() {
       "  taptap-maker                         Start MCP server mode",
       "  taptap-maker init [--env rnd|production] [--app-id ID] [--target-dir DIR] [--pat PAT]",
       "                     [--skip-confirm] [--skip-mcp-install] [--register-mcp codex,cursor,claude]",
-      "                     [--package @taptap/instant-games-open-mcp] [--json]",
+      "                     [--json]",
       "  taptap-maker doctor [--target-dir DIR] [--env rnd|production] [--json]",
-      "  taptap-maker apps [--pat PAT] [--json]",
+      "  taptap-maker apps [--pat PAT] [--limit N] [--offset N] [--json]",
+      "                     # --pat warns: PAT appears in ps/history",
       "  taptap-maker pat set [--pat-stdin] [--json]",
       "  taptap-maker pat set [PAT|--pat PAT] [--json]  # warns: PAT appears in ps/history",
       "  taptap-maker mcp install [--ide codex,cursor,claude] [--env rnd|production]",
       "                             [--package @taptap/instant-games-open-mcp] [--json]",
-      "  taptap-maker mcp verify              Verify CLI spawn path",
+      "  taptap-maker mcp verify [--package @taptap/instant-games-open-mcp]",
+      "                           [--mode npx|self] [--json]",
       "  taptap-maker dev-kit update [--target-dir DIR] [--json]",
-      "  taptap-maker help                    Show this help",
+      "",
+      "MCP verify defaults to the npx command written into AI client config.",
+      "Advanced: init and mcp install accept --package only when testing a different npm package.",
       "",
       "Windows note:",
       "  Generated MCP configs use npx.cmd automatically on Windows.",
-      "",
-      "MCP server mode is still used by AI clients after configuration reload.",
       ""
     ].join("\n")
   );