android2harmony 0.1.0

package/agents/scripts/hmos-precheck/index.mjs

@@ -0,0 +1,926 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findArktsTool, findHmsSdkEts, findSystemResourceFile, runArktsStandalonePrecheck } from "./arkts.mjs";
+import { findCodelinterTool, runCodelinterDiffScan } from "./codelinter.mjs";
+const PROJECT_CONFIG_NAME = ".hmos-precheck.json";
+const USER_CONFIG_BASENAME = "config.json";
+const DEFAULT_PROFILES = ["arkts-diff", "codelinter-diff"];
+const SUPPORTED_PROFILES = new Set(DEFAULT_PROFILES);
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+async function exists(pathname) {
+  try {
+    await access(pathname, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadJson(pathname) {
+  try {
+    const parsed = JSON.parse(await readFile(pathname, "utf8"));
+    return isObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function expandHome(input) {
+  if (!input) return input;
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/") || input.startsWith("~\\")) return path.join(os.homedir(), input.slice(2));
+  return input;
+}
+function defaultUserConfigPath() {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "hmos-precheck", USER_CONFIG_BASENAME);
+  }
+  if (process.platform.startsWith("win")) {
+    const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appdata, "hmos-precheck", USER_CONFIG_BASENAME);
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(xdg, "hmos-precheck", USER_CONFIG_BASENAME);
+}
+function defaultHomeTransConfigPath() {
+  return path.join(os.homedir(), ".hometrans", "config.json");
+}
+function commandlineToolsHelp() {
+  return "Run `hmos-precheck init --scope user --commandline-tools /abs/path/to/command-line-tools`, or pass `--commandline-tools`.";
+}
+async function hasSdkShape(candidate) {
+  const probes = [
+    path.join(candidate, "default", "openharmony", "toolchains"),
+    path.join(candidate, "default", "openharmony", "ets"),
+    path.join(candidate, "default", "hms", "ets"),
+    path.join(candidate, "default", "hms", "toolchains")
+  ];
+  for (const probe of probes) {
+    if (await exists(probe)) return true;
+  }
+  return false;
+}
+async function normalizeCommandlineToolsCandidate(candidate) {
+  const resolved = path.resolve(expandHome(candidate));
+  if (await hasSdkShape(resolved)) return { sdkRoot: resolved, toolRoot: path.dirname(resolved) };
+  const nested = path.join(resolved, "sdk");
+  if (await hasSdkShape(nested)) return { sdkRoot: nested, toolRoot: resolved };
+  return null;
+}
+async function resolveCommonCommandlineTools() {
+  const candidates = [];
+  if (process.platform.startsWith("win")) {
+    for (const root of [process.env.LOCALAPPDATA, process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.USERPROFILE].filter(Boolean)) {
+      candidates.push(
+        path.join(root, "HarmonyOS", "command-line-tools"),
+        path.join(root, "Huawei", "HarmonyOS", "command-line-tools"),
+        path.join(root, "OpenHarmony", "command-line-tools")
+      );
+    }
+    candidates.push(path.join(os.homedir(), "HarmonyOS", "command-line-tools"));
+  } else if (process.platform === "darwin") {
+    candidates.push("/Applications/HarmonyOS/command-line-tools", path.join(os.homedir(), "HarmonyOS", "command-line-tools"));
+  } else {
+    candidates.push("/opt/harmonyos/command-line-tools", path.join(os.homedir(), "HarmonyOS", "command-line-tools"), path.join(os.homedir(), "harmonyos", "command-line-tools"));
+  }
+  for (const candidate of candidates) {
+    const info = await normalizeCommandlineToolsCandidate(candidate);
+    if (info) return info.sdkRoot;
+  }
+  return null;
+}
+async function resolveCommandlineToolsInfo(options) {
+  const env = options.env ?? process.env;
+  const hint = commandlineToolsHelp();
+  const wrap = async (candidate, source) => {
+    if (!candidate) return null;
+    const info = await normalizeCommandlineToolsCandidate(candidate);
+    if (!info) {
+      return {
+        path: path.resolve(expandHome(candidate)),
+        toolRoot: null,
+        sdkRoot: null,
+        source,
+        configured: true,
+        available: false,
+        message: `Configured HarmonyOS command-line tools path is unavailable: ${path.resolve(expandHome(candidate))}`,
+        hint
+      };
+    }
+    return {
+      path: info.sdkRoot,
+      toolRoot: info.toolRoot,
+      sdkRoot: info.sdkRoot,
+      source,
+      configured: true,
+      available: true,
+      message: null,
+      hint
+    };
+  };
+  const explicit = await wrap(options.explicitPath ?? null, "cli");
+  if (explicit) return explicit;
+  const sdkResult = await wrap(env.DEVECO_SDK_HOME ?? null, "env");
+  if (sdkResult) return sdkResult;
+  if (options.projectRoot) {
+    const projectConfig = await loadJson(path.join(options.projectRoot, PROJECT_CONFIG_NAME));
+    const value = isObject(projectConfig?.toolchain) ? projectConfig.toolchain.commandline_tools : void 0;
+    const projectResult = await wrap(typeof value === "string" ? value : null, "project_config");
+    if (projectResult) return projectResult;
+  }
+  const homeTransConfig = await loadJson(defaultHomeTransConfigPath());
+  const homeTransValue = isObject(homeTransConfig?.env) ? homeTransConfig.env.DEVECO_SDK_HOME : void 0;
+  const homeTransResult = await wrap(typeof homeTransValue === "string" ? homeTransValue : null, "hometrans_config");
+  if (homeTransResult) return homeTransResult;
+  const userConfig = await loadJson(options.userConfigPath ?? defaultUserConfigPath());
+  const userValue = isObject(userConfig?.toolchain) ? userConfig.toolchain.commandline_tools : void 0;
+  const userResult = await wrap(typeof userValue === "string" ? userValue : null, "user_config");
+  if (userResult) return userResult;
+  const auto = await resolveCommonCommandlineTools();
+  if (auto) {
+    return { path: auto, toolRoot: path.dirname(auto), sdkRoot: auto, source: "auto", configured: true, available: true, message: null, hint };
+  }
+  return {
+    path: null,
+    toolRoot: null,
+    sdkRoot: null,
+    source: "missing",
+    configured: false,
+    available: false,
+    message: "HarmonyOS command-line tools are not configured. ArkTS-dependent checks will be skipped.",
+    hint
+  };
+}
+async function resolveProfiles(options) {
+  const normalize = (values) => {
+    if (!values) return null;
+    const raw = Array.isArray(values) ? values : values.split(",");
+    const deduped = [...new Set(raw.map((item) => item.trim()).filter(Boolean))];
+    return deduped.length ? deduped : null;
+  };
+  const explicit = normalize(options.explicitProfiles ?? null);
+  if (explicit) return explicit;
+  if (options.projectRoot) {
+    const projectConfig = await loadJson(path.join(options.projectRoot, PROJECT_CONFIG_NAME));
+    const value2 = isObject(projectConfig?.run) ? projectConfig.run.profiles : void 0;
+    const fromProject = normalize(Array.isArray(value2) ? value2.map(String) : typeof value2 === "string" ? value2 : null);
+    if (fromProject) return fromProject;
+  }
+  const userConfig = await loadJson(options.userConfigPath ?? defaultUserConfigPath());
+  const value = isObject(userConfig?.run) ? userConfig.run.profiles : void 0;
+  return normalize(Array.isArray(value) ? value.map(String) : typeof value === "string" ? value : null);
+}
+async function initConfig(targetPath, commandlineTools) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, `${JSON.stringify({ toolchain: { commandline_tools: path.resolve(commandlineTools) } }, null, 2)}
+`, "utf8");
+  return targetPath;
+}
+async function writeJson(pathname, payload) {
+  await mkdir(path.dirname(pathname), { recursive: true });
+  await writeFile(pathname, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+}
+async function runGit(projectRoot, args) {
+  const { spawn } = await import("node:child_process");
+  return await new Promise((resolve) => {
+    const proc = spawn("git", args, { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    proc.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    proc.on("error", (error) => resolve({ code: 1, stdout, stderr: error instanceof Error ? error.message : String(error) }));
+  });
+}
+function prepareRunOutputDir(outputDir, runId) {
+  return path.join(outputDir, `run-${runId}`);
+}
+function backendCrashPayload(profile, error) {
+  const reason = error instanceof Error ? error.message : String(error);
+  if (profile === "arkts-diff") {
+    return {
+      tool: "arkts_standalone_precheck",
+      tool_status: "unavailable",
+      evidence_status: "partial",
+      success: true,
+      mode: "diff",
+      checked_files: [],
+      errors: [],
+      summary: { errorCount: 0, warnCount: 0 },
+      reason,
+      scope: "diff",
+      changed_files_only: true,
+      changed_line_ranges: {},
+      failure_rule: "backend-crashed"
+    };
+  }
+  return {
+    tool: "codelinter",
+    tool_status: "unavailable",
+    evidence_status: "partial",
+    success: true,
+    checked_files: [],
+    diagnostics: [],
+    summary: { errorCount: 0, warnCount: 0, suggestionCount: 0 },
+    reason,
+    scope: "diff",
+    changed_files_only: true,
+    changed_line_ranges: {},
+    failure_rule: "backend-crashed"
+  };
+}
+function repairHint(item) {
+  const rule = String(item.rule ?? "");
+  const file = String(item.file ?? "the flagged file");
+  const line = item.line ?? "?";
+  const message = String(item.message ?? "");
+  if (item.profile === "arkts-diff") return `Edit the ArkTS code at ${file}:${line} to satisfy compiler rule \`${rule}\`. Resolve the exact reported error: ${message}`;
+  if (item.profile === "codelinter-diff") return `Edit ${file}:${line} to satisfy linter rule \`${rule}\`. Apply the rule-specific fix implied by: ${message}`;
+  return `Edit ${file}:${line} to remove the blocking condition reported as \`${rule}\`: ${message}`;
+}
+function warningHint(item) {
+  const profile = String(item.profile ?? "");
+  const rule = String(item.rule ?? "");
+  if (rule === "git-diff-failed") return "Use a valid git base/head ref and ensure the repository has the required history.";
+  if (rule === "invalid-profile") return "Remove unsupported profiles from CLI/config and use only supported profiles.";
+  if (profile === "arkts-diff") return "Configure HarmonyOS command-line tools if you need ArkTS validation.";
+  if (profile === "codelinter-diff") return "Install or configure codelinter if you need lint validation.";
+  return "Restore the skipped validation path if you need full confidence from this check run.";
+}
+function warningIssue(item) {
+  const profile = String(item.profile ?? "validation");
+  const message = String(item.message ?? "check unavailable");
+  const label = profile.endsWith("-diff") ? profile.slice(0, -5) : profile;
+  const rule = String(item.rule ?? "");
+  const problem = ["git-diff-failed", "invalid-profile"].includes(rule) ? message : `${label} check skipped: ${message}`;
+  return {
+    kind: rule || "environment-issue",
+    problem,
+    fix: warningHint(item)
+  };
+}
+async function fileExists(pathname) {
+  return Boolean(pathname) && await exists(String(pathname));
+}
+async function sanitizeIssueEvidence(evidence) {
+  if (!evidence) return null;
+  let status = String(evidence.status ?? "partial");
+  const rawFile = typeof evidence.raw_file === "string" ? evidence.raw_file : null;
+  if (rawFile && await fileExists(rawFile)) {
+    return { status, raw_file: rawFile };
+  }
+  if (status === "raw_structured") status = "partial";
+  return { status };
+}
+function dedupeIssues(issues) {
+  const deduped = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const key = JSON.stringify([
+      issue.kind,
+      issue.file,
+      issue.line,
+      issue.column,
+      issue.rule,
+      issue.problem,
+      issue.fix
+    ]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(issue);
+  }
+  return deduped;
+}
+async function existingRawFile(backend) {
+  const rawFile = typeof backend.artifact_paths?.raw_json === "string" ? backend.artifact_paths.raw_json : null;
+  return rawFile && await fileExists(rawFile) ? rawFile : null;
+}
+async function effectiveBackendEvidenceStatus(backend) {
+  const status = String(backend.evidence_status ?? "partial");
+  if (status === "raw_structured" && !await existingRawFile(backend)) return "partial";
+  return status;
+}
+async function repairIssue(item) {
+  const issue = {
+    kind: String(item.rule ?? "code-issue"),
+    file: item.file ?? null,
+    line: item.line ?? null,
+    column: item.column ?? null,
+    rule: item.rule ?? null,
+    problem: item.message ?? "",
+    fix: repairHint(item)
+  };
+  const evidence = await sanitizeIssueEvidence(isObject(item.evidence) ? item.evidence : null);
+  if (evidence) issue.evidence = evidence;
+  return issue;
+}
+function repairSummary(hardFindings) {
+  const fileCount = new Set(hardFindings.map((item) => item.file).filter(Boolean)).size;
+  return `Fix ${hardFindings.length} blocking issue(s) across ${fileCount || 1} file(s).`;
+}
+function blockingEnvironmentSummary(count) {
+  return `Resolve ${count} blocking environment issue(s).`;
+}
+function degradedSummary(count) {
+  return `No blocking code issues, but ${count} profile(s) were not fully checked.`;
+}
+function overallStatus(summaryCounts, backendResults) {
+  if (summaryCounts.hard_fixable) return "fail";
+  const hasCheckedBackend = Object.values(backendResults).some((backend) => String(backend?.tool_status ?? "") === "ok");
+  if (summaryCounts.not_checked) return hasCheckedBackend ? "warn" : "fail";
+  return "pass";
+}
+async function resultPayload(payload) {
+  const rawFiles = (await Promise.all(Object.values(payload.backend_results).map((backend) => existingRawFile(backend)))).filter((value) => Boolean(value));
+  const evidenceStatuses = new Set(await Promise.all(Object.values(payload.backend_results).map((backend) => effectiveBackendEvidenceStatus(backend))));
+  let evidenceStatus = "partial";
+  if (!evidenceStatuses.size) {
+    evidenceStatus = "partial";
+  } else if (evidenceStatuses.size === 1 && evidenceStatuses.has("raw_structured")) {
+    evidenceStatus = "raw_structured";
+  } else if (evidenceStatuses.has("derived_from_text")) {
+    evidenceStatus = "derived_from_text";
+  }
+  const hardFindings = payload.findings.filter((item) => item.classification === "hard_fixable");
+  const blockingFindings = payload.findings.filter((item) => item.classification === "not_checked");
+  const blockingIssues = dedupeIssues(blockingFindings.map((item) => warningIssue(item)));
+  if (hardFindings.length) {
+    const issues = dedupeIssues((await Promise.all(hardFindings.map((item) => repairIssue(item)))).concat(blockingIssues));
+    let summary = repairSummary(hardFindings);
+    if (blockingIssues.length) summary = `${summary} ${blockingEnvironmentSummary(blockingIssues.length)}`;
+    return {
+      run_id: payload.run_id,
+      summary,
+      evidence_status: evidenceStatus,
+      raw_files: rawFiles,
+      issues
+    };
+  }
+  if (payload.status === "warn") {
+    return {
+      ok: true,
+      degraded: true,
+      run_id: payload.run_id,
+      status: "warn",
+      summary: degradedSummary(blockingIssues.length || 1),
+      evidence_status: evidenceStatus,
+      raw_files: rawFiles,
+      issues: blockingIssues
+    };
+  }
+  if (payload.status === "pass") return { ok: true };
+  return {
+    run_id: payload.run_id,
+    summary: blockingEnvironmentSummary(blockingIssues.length || 1),
+    evidence_status: evidenceStatus,
+    raw_files: rawFiles,
+    issues: blockingIssues
+  };
+}
+function compactResult(payload) {
+  const hasHard = payload.findings.some((item) => item.classification === "hard_fixable");
+  if (hasHard || payload.status === "fail") {
+    const result = { ok: false };
+    if (payload.artifact_paths.json) result.read_file = payload.artifact_paths.json;
+    return result;
+  }
+  if (payload.status === "warn") {
+    const result = { ok: true, degraded: true };
+    if (payload.artifact_paths.json) result.read_file = payload.artifact_paths.json;
+    return result;
+  }
+  return { ok: true };
+}
+async function writeSummary(payload, pathname) {
+  const findings = Array.isArray(payload.findings) ? payload.findings : [];
+  const hard = findings.filter((item) => item.classification === "hard_fixable");
+  const lines = [
+    "# HMOS Precheck Summary",
+    "",
+    `- ok: ${String(payload.ok ?? false)}`,
+    `- compact_summary: ${String(payload.compact_summary ?? "")}`,
+    `- profiles: ${Array.isArray(payload.profiles) ? payload.profiles.join(", ") : ""}`,
+    `- hard_fixable: ${String(payload.summary_counts?.hard_fixable ?? 0)}`,
+    `- strong_warn_hidden_from_fixer: ${String(payload.summary_counts?.strong_warn ?? 0)}`,
+    `- not_checked: ${String(payload.summary_counts?.not_checked ?? 0)}`,
+    "",
+    "## Fixer Findings"
+  ];
+  if (!hard.length) lines.push("- none");
+  for (const item of hard.slice(0, 40)) {
+    lines.push(`- [${String(item.profile ?? "")}] ${String(item.file ?? "<unknown>")}:${String(item.line ?? "?")}:${String(item.column ?? "?")} [${String(item.rule ?? "no-rule")}] ${String(item.message ?? "")}`);
+  }
+  await writeFile(pathname, `${lines.join("\n")}
+`, "utf8");
+}
+async function writeArktsSummary(payload, pathname, maxErrors = 30) {
+  const errors = (Array.isArray(payload.errors) ? payload.errors : []).filter((item) => item.severity === "error");
+  const warnings = (Array.isArray(payload.errors) ? payload.errors : []).filter((item) => item.severity === "warning");
+  const suppressed = Array.isArray(payload.suppressed_diagnostics) ? payload.suppressed_diagnostics : [];
+  const lines = [
+    "# ArkTS Precheck Fix Summary",
+    "",
+    `- status: ${String(payload.tool_status ?? "")}`,
+    `- checked_files: ${Array.isArray(payload.checked_files) ? payload.checked_files.length : 0}`,
+    `- errors: ${errors.length}`,
+    `- warnings_hidden_from_fixer: ${warnings.length}`,
+    `- suppressed_project_config_diagnostics: ${suppressed.length}`,
+    "",
+    "## Blocking Errors"
+  ];
+  if (!errors.length) lines.push("- none");
+  for (const item of errors.slice(0, maxErrors)) {
+    const issue = item;
+    lines.push(`- ${String(issue.file ?? "<unknown>")}:${String(issue.line ?? "?")}:${String(issue.column ?? "?")} [${String(issue.rule ?? "no-rule")}] ${String(issue.message ?? "")}`);
+  }
+  await writeFile(pathname, `${lines.join("\n")}
+`, "utf8");
+}
+async function runArktsDiff(options) {
+  const precheckOutputDir = path.join(options.outputDir, "arkts-precheck");
+  await mkdir(precheckOutputDir, { recursive: true });
+  const resultPath = path.join(options.outputDir, "arkts-precheck-result.json");
+  const summaryPath = path.join(options.outputDir, "arkts-precheck-fix-summary.md");
+  const rawOutput = {
+    raw_json: path.join(precheckOutputDir, "arkts-raw-diagnostics.json"),
+    runner: path.join(precheckOutputDir, "arkts-standalone-check-runner.js"),
+    stdout: path.join(precheckOutputDir, "arkts-checker-stdout.txt"),
+    stderr: path.join(precheckOutputDir, "arkts-checker-stderr.txt")
+  };
+  let payload;
+  try {
+    const diffArgs = ["diff", "--name-only", options.baseRef];
+    if (options.headRef) diffArgs.push(options.headRef);
+    diffArgs.push("--", "*.ets");
+    const diffResult = await runGit(options.projectRoot, diffArgs);
+    if (diffResult.code !== 0) {
+      throw new Error(`git diff failed: ${(diffResult.stderr || diffResult.stdout || `exit_code=${diffResult.code}`).trim()}`);
+    }
+    const checkedFiles = diffResult.stdout.split(/\r?\n/).filter((line) => line.endsWith(".ets")).filter(Boolean).map((line) => line.replace(/\\/g, "/")).filter((line, index, all) => all.indexOf(line) === index);
+    if (options.headRef === null) {
+      const untrackedResult = await runGit(options.projectRoot, ["ls-files", "--others", "--exclude-standard", "--", "*.ets"]);
+      if (untrackedResult.code !== 0) {
+        throw new Error(`git ls-files failed: ${(untrackedResult.stderr || untrackedResult.stdout || `exit_code=${untrackedResult.code}`).trim()}`);
+      }
+      for (const line of untrackedResult.stdout.split(/\r?\n/)) {
+        if (!line.endsWith(".ets")) continue;
+        const normalized = line.replace(/\\/g, "/");
+        if (!checkedFiles.includes(normalized)) checkedFiles.push(normalized);
+      }
+    }
+    const lineArgs = ["diff", "--unified=0", options.baseRef];
+    if (options.headRef) lineArgs.push(options.headRef);
+    lineArgs.push("--", "*.ets");
+    const lineResult = await runGit(options.projectRoot, lineArgs);
+    if (lineResult.code !== 0) {
+      throw new Error(`git diff failed: ${(lineResult.stderr || lineResult.stdout || `exit_code=${lineResult.code}`).trim()}`);
+    }
+    const changedLineRanges = {};
+    let currentFile = null;
+    for (const line of lineResult.stdout.split(/\r?\n/)) {
+      if (line.startsWith("+++ b/")) {
+        currentFile = line.replace("+++ b/", "");
+        if (!changedLineRanges[currentFile]) changedLineRanges[currentFile] = [];
+        continue;
+      }
+      if (!currentFile || !line.startsWith("@@")) continue;
+      const match = /@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+      if (!match) continue;
+      const start = Number.parseInt(match[1], 10);
+      const count = match[2] !== undefined ? Number.parseInt(match[2], 10) : 1;
+      if (count > 0) changedLineRanges[currentFile].push([start, start + count - 1]);
+    }
+    if (!checkedFiles.length) {
+      payload = {
+        tool: "arkts_standalone_precheck",
+        tool_status: "ok",
+        success: true,
+        mode: options.headRef === null ? "diff-working-tree" : "diff",
+        checked_files: [],
+        errors: [],
+        summary: { errorCount: 0, warnCount: 0 },
+        reason: "no changed ETS files",
+        scope: "diff",
+        changed_files_only: true,
+        changed_line_ranges: {}
+      };
+    } else if (!options.commandlineTools) {
+      payload = {
+        tool: "arkts_standalone_precheck",
+        tool_status: "unavailable",
+        success: true,
+        mode: options.headRef === null ? "diff-working-tree" : "diff",
+        checked_files: checkedFiles,
+        errors: [],
+        summary: { errorCount: 0, warnCount: 0 },
+        reason: "commandline_tools not configured",
+        scope: "diff",
+        changed_files_only: true,
+        changed_line_ranges: changedLineRanges
+      };
+    } else {
+      const files = checkedFiles.map((file) => path.join(options.projectRoot, file));
+      const raw = await runArktsStandalonePrecheck({
+        projectRoot: options.projectRoot,
+        commandlineTools: options.commandlineTools,
+        outputDir: precheckOutputDir,
+        files
+      });
+      const normalizedCheckedFiles = new Set((Array.isArray(raw.checked_files) ? raw.checked_files : []).map((item) => String(item).replace(/\\/g, "/")));
+      const filteredErrors = (Array.isArray(raw.errors) ? raw.errors : []).filter((item) => {
+        const file = String(item.file ?? "").replace(/\\/g, "/");
+        const ranges = Array.isArray(changedLineRanges[file]) ? changedLineRanges[file] : null;
+        const line = item.line == null ? null : Number(item.line);
+        if (ranges && line !== null && !ranges.some(([start, end]) => start <= line && line <= end)) return false;
+        if (normalizedCheckedFiles.size && !normalizedCheckedFiles.has(file)) return false;
+        return true;
+      });
+      payload = {
+        ...raw,
+        errors: filteredErrors,
+        summary: {
+          errorCount: filteredErrors.filter((item) => item.severity === "error").length,
+          warnCount: filteredErrors.filter((item) => item.severity === "warning").length
+        },
+        success: filteredErrors.filter((item) => item.severity === "error").length === 0,
+        scope: "diff",
+        changed_files_only: true,
+        mode: options.headRef === null ? "diff-working-tree" : "diff",
+        changed_line_ranges: changedLineRanges
+      };
+    }
+  } catch (error) {
+    payload = {
+      tool: "arkts_standalone_precheck",
+      tool_status: "unavailable",
+      success: true,
+      mode: options.headRef === null ? "diff-working-tree" : "diff",
+      checked_files: [],
+      errors: [],
+      summary: { errorCount: 0, warnCount: 0 },
+      reason: error instanceof Error ? error.message : String(error),
+      scope: "diff",
+      changed_files_only: true,
+      changed_line_ranges: {},
+      failure_rule: "git-diff-failed"
+    };
+  }
+  payload.artifact_paths = {
+    json: resultPath,
+    summary: summaryPath,
+    raw_json: typeof payload.artifact_paths?.raw_json === "string" ? payload.artifact_paths.raw_json : rawOutput.raw_json,
+    runner: typeof payload.artifact_paths?.runner === "string" ? payload.artifact_paths.runner : rawOutput.runner,
+    stdout: typeof payload.artifact_paths?.stdout === "string" ? payload.artifact_paths.stdout : rawOutput.stdout,
+    stderr: typeof payload.artifact_paths?.stderr === "string" ? payload.artifact_paths.stderr : rawOutput.stderr
+  };
+  await writeJson(resultPath, payload);
+  await writeArktsSummary(payload, summaryPath);
+  return payload;
+}
+async function runChecks(options) {
+  const runId = randomUUID().replace(/-/g, "");
+  await mkdir(path.resolve(options.outputDir), { recursive: true });
+  const runDir = prepareRunOutputDir(path.resolve(options.outputDir), runId);
+  await mkdir(runDir, { recursive: true });
+  const selectedProfiles = [...new Set(options.profiles)];
+  const unknownProfiles = selectedProfiles.filter((profile) => !SUPPORTED_PROFILES.has(profile));
+  if (unknownProfiles.length) throw new Error(`unsupported profile(s): ${unknownProfiles.join(", ")}`);
+  const backendResults = {};
+  const jobs = [];
+  if (selectedProfiles.includes("arkts-diff")) {
+    jobs.push((async () => {
+      try {
+        backendResults["arkts-diff"] = await runArktsDiff({
+          projectRoot: path.resolve(options.projectRoot),
+          outputDir: runDir,
+          commandlineTools: options.commandlineTools.sdkRoot,
+          baseRef: options.baseRef,
+          headRef: options.headRef
+        });
+      } catch (error) {
+        backendResults["arkts-diff"] = backendCrashPayload("arkts-diff", error);
+      }
+    })());
+  }
+  if (selectedProfiles.includes("codelinter-diff")) {
+    jobs.push((async () => {
+      try {
+        backendResults["codelinter-diff"] = await runCodelinterDiffScan({
+          projectRoot: path.resolve(options.projectRoot),
+          validationOutputDir: runDir,
+          commandlineTools: options.commandlineTools.sdkRoot,
+          baseRef: options.baseRef,
+          headRef: options.headRef
+        });
+      } catch (error) {
+        backendResults["codelinter-diff"] = backendCrashPayload("codelinter-diff", error);
+      }
+    })());
+  }
+  await Promise.all(jobs);
+  const findings = [];
+  const summaryCounts = { hard_fixable: 0, strong_warn: 0, risk_only: 0, not_checked: 0 };
+  const arkts = backendResults["arkts-diff"];
+  if (arkts) {
+    if (String(arkts.tool_status ?? "") !== "ok") {
+      findings.push({
+        profile: "arkts-diff",
+        category: "tooling",
+        classification: "not_checked",
+        file: null,
+        line: null,
+        column: null,
+        rule: String(arkts.failure_rule ?? "backend-unavailable"),
+        message: String(arkts.reason ?? "ArkTS backend unavailable")
+      });
+      summaryCounts.not_checked += 1;
+    } else {
+      for (const item of Array.isArray(arkts.errors) ? arkts.errors : []) {
+        if (item.severity !== "error") continue;
+        findings.push({
+          profile: "arkts-diff",
+          category: "compile",
+          classification: "hard_fixable",
+          file: item.file ?? null,
+          line: item.line ?? null,
+          column: item.column ?? null,
+          rule: item.rule || "no-rule",
+          message: item.message ?? "",
+          evidence: { status: arkts.evidence_status ?? "partial", raw_file: arkts.artifact_paths?.raw_json }
+        });
+        summaryCounts.hard_fixable += 1;
+      }
+    }
+  }
+  const codelinter = backendResults["codelinter-diff"];
+  if (codelinter) {
+    if (String(codelinter.tool_status ?? "") !== "ok") {
+      findings.push({
+        profile: "codelinter-diff",
+        category: "tooling",
+        classification: "not_checked",
+        file: null,
+        line: null,
+        column: null,
+        rule: String(codelinter.failure_rule ?? "backend-unavailable"),
+        message: String(codelinter.reason ?? "CodeLinter backend unavailable")
+      });
+      summaryCounts.not_checked += 1;
+    } else {
+      for (const item of Array.isArray(codelinter.diagnostics) ? codelinter.diagnostics : []) {
+        const severity = String(item.severity ?? "");
+        const classification = severity === "error" ? "hard_fixable" : severity === "warning" ? "strong_warn" : "risk_only";
+        findings.push({
+          profile: "codelinter-diff",
+          category: "lint",
+          classification,
+          file: item.file ?? null,
+          line: item.line ?? null,
+          column: item.column ?? null,
+          rule: item.rule || "no-rule",
+          message: item.message ?? "",
+          evidence: { status: codelinter.evidence_status ?? "partial", raw_file: codelinter.artifact_paths?.raw_json }
+        });
+        if (classification === "hard_fixable") summaryCounts.hard_fixable += 1;
+        else if (classification === "strong_warn") summaryCounts.strong_warn += 1;
+        else summaryCounts.risk_only += 1;
+      }
+    }
+  }
+  const status = overallStatus(summaryCounts, backendResults);
+  const compactSummary = summaryCounts.hard_fixable
+    ? `${summaryCounts.hard_fixable} blocking finding(s) across ${selectedProfiles.length} profile(s)`
+    : summaryCounts.not_checked
+      ? `no blocking findings; ${summaryCounts.not_checked} profile(s) not fully checked`
+      : "no blocking findings";
+  const payload = {
+    tool: "hmos-precheck",
+    run_id: runId,
+    schema_version: "hmos_precheck.v1",
+    status,
+    ok: status !== "fail",
+    profiles: selectedProfiles,
+    project_root: path.resolve(options.projectRoot),
+    summary: summaryCounts,
+    summary_counts: summaryCounts,
+    findings,
+    fixable: Boolean(summaryCounts.hard_fixable),
+    compact_summary: compactSummary,
+    backend_results: backendResults
+  };
+  const artifactPaths = {
+    json: path.join(runDir, "hmos-precheck-result.json"),
+    summary: path.join(runDir, "hmos-precheck-summary.md")
+  };
+  if (options.debugArtifact) artifactPaths.debug = path.join(runDir, "hmos-precheck-debug.json");
+  if (artifactPaths.debug) await writeJson(artifactPaths.debug, payload);
+  await writeSummary(payload, artifactPaths.summary);
+  await writeJson(artifactPaths.json, await resultPayload({ run_id: runId, status, backend_results: backendResults, findings }));
+  return { run_id: runId, status, backend_results: backendResults, findings, artifact_paths: artifactPaths };
+}
+function splitCsv(values) {
+  const items = [];
+  for (const value of values) {
+    items.push(...value.split(",").map((item) => item.trim()).filter(Boolean));
+  }
+  return items;
+}
+function parseFlags(argv, flag) {
+  const values = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === flag && argv[i + 1]) values.push(argv[i + 1]);
+  }
+  return values;
+}
+function singleFlag(argv, flag) {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : void 0;
+}
+async function writeCliFailure(baseOutputDir, problem, fix, kind) {
+  const runId = randomUUID().replace(/-/g, "");
+  const resolvedBase = path.resolve(baseOutputDir);
+  await mkdir(resolvedBase, { recursive: true });
+  const runDir = path.join(resolvedBase, `run-${runId}`);
+  await mkdir(runDir, { recursive: true });
+  const resultPath = path.join(runDir, "hmos-precheck-result.json");
+  await writeJson(resultPath, {
+    run_id: runId,
+    summary: "Fix the blocking environment issue(s) first.",
+    evidence_status: "partial",
+    raw_files: [],
+    issues: [{ kind, problem, fix }]
+  });
+  return { ok: false, read_file: resultPath };
+}
+function fallbackOutputDir(argv) {
+  const explicit = singleFlag(argv, "--output-dir");
+  if (explicit) return path.resolve(explicit);
+  return path.join(os.tmpdir(), "hmos-precheck-cli-failures");
+}
+async function cmdRun(argv) {
+  try {
+    const projectRoot = singleFlag(argv, "--project-root");
+    const outputDir = singleFlag(argv, "--output-dir");
+    if (!projectRoot || !outputDir) throw new Error("--project-root and --output-dir are required");
+    const commandlineToolsInfo = await resolveCommandlineToolsInfo({
+      projectRoot: path.resolve(projectRoot),
+      explicitPath: singleFlag(argv, "--commandline-tools")
+    });
+    const explicitProfiles = splitCsv(parseFlags(argv, "--profile"));
+    const profiles = await resolveProfiles({
+      explicitProfiles: explicitProfiles.length ? explicitProfiles : null,
+      projectRoot: path.resolve(projectRoot)
+    }) ?? DEFAULT_PROFILES;
+    const payload = await runChecks({
+      projectRoot: path.resolve(projectRoot),
+      outputDir: path.resolve(outputDir),
+      commandlineTools: commandlineToolsInfo,
+      profiles,
+      baseRef: singleFlag(argv, "--base-ref") ?? "HEAD",
+      headRef: singleFlag(argv, "--head-ref") ?? null,
+      debugArtifact: argv.includes("--debug-artifact")
+    });
+    const result = compactResult(payload);
+    console.log(JSON.stringify(result));
+    return result.ok ? 0 : 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const invalidProfile = message.startsWith("unsupported profile(s):");
+    const result = await writeCliFailure(
+      fallbackOutputDir(argv),
+      invalidProfile ? `invalid profile configuration: ${message}` : message,
+      invalidProfile ? "Remove unsupported profiles from CLI/config and use only supported profiles." : "Resolve the reported blocking issue and rerun hmos-precheck.",
+      invalidProfile ? "invalid-profile" : "internal-error"
+    );
+    console.log(JSON.stringify(result));
+    return 1;
+  }
+}
+async function cmdDoctor(argv) {
+  const projectRoot = singleFlag(argv, "--project-root") ? path.resolve(singleFlag(argv, "--project-root")) : void 0;
+  const info = await resolveCommandlineToolsInfo({
+    projectRoot,
+    explicitPath: singleFlag(argv, "--commandline-tools")
+  });
+  const configuredProfiles = await resolveProfiles({ projectRoot });
+  const codelinter = await findCodelinterTool(info.sdkRoot);
+  const arktsTool = await findArktsTool(info.sdkRoot);
+  const hmsSdkEts = await findHmsSdkEts(info.sdkRoot);
+  const systemResourceFile = await findSystemResourceFile(info.sdkRoot);
+  const payload = {
+    tool: "hmos-precheck",
+    status: info.available ? "pass" : "warn",
+    commandline_tools: info.path,
+    commandline_tools_source: info.source,
+    node: process.execPath,
+    codelinter,
+    checks: {
+      commandline_tools_configured: info.configured,
+      commandline_tools_found: info.available,
+      node_found: true,
+      ets_loader_found: Boolean(arktsTool.etsLoader),
+      hms_sdk_found: Boolean(hmsSdkEts),
+      system_resource_file_found: Boolean(systemResourceFile),
+      codelinter_found: Boolean(codelinter)
+    },
+    config_paths: {
+      project: projectRoot ? path.join(projectRoot, PROJECT_CONFIG_NAME) : null,
+      hometrans: defaultHomeTransConfigPath(),
+      user: defaultUserConfigPath()
+    },
+    profiles: {
+      default: DEFAULT_PROFILES,
+      supported: DEFAULT_PROFILES,
+      configured: configuredProfiles
+    }
+  };
+  if (info.message) payload.toolchain_warning = { message: info.message, hint: info.hint };
+  console.log(JSON.stringify(payload, null, 2));
+  return 0;
+}
+async function cmdInit(argv) {
+  const projectRoot = singleFlag(argv, "--project-root") ? path.resolve(singleFlag(argv, "--project-root")) : void 0;
+  const info = await resolveCommandlineToolsInfo({
+    projectRoot,
+    explicitPath: singleFlag(argv, "--commandline-tools")
+  });
+  if (!info.sdkRoot) throw new Error("commandline_tools could not be resolved; pass --commandline-tools");
+  const scope = singleFlag(argv, "--scope") ?? "project";
+  const target = scope === "project" ? path.join(projectRoot ?? path.resolve("."), PROJECT_CONFIG_NAME) : defaultUserConfigPath();
+  await initConfig(target, info.sdkRoot);
+  console.log(JSON.stringify({ written: target, commandline_tools: info.sdkRoot, source: info.source }, null, 2));
+  return 0;
+}
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const [command, ...rest] = argv;
+    if (!command) {
+      const result2 = await writeCliFailure(
+        fallbackOutputDir(argv),
+        "usage: hmos-precheck <run|doctor|init> ...",
+        "Invoke one supported command and rerun hmos-precheck.",
+        "invalid-command"
+      );
+      console.log(JSON.stringify(result2));
+      return 1;
+    }
+    if (command === "run") return await cmdRun(rest);
+    if (command === "doctor") return await cmdDoctor(rest);
+    if (command === "init") return await cmdInit(rest);
+    const result = await writeCliFailure(
+      fallbackOutputDir(argv),
+      `unknown command: ${command}`,
+      "Use one of: run, doctor, init.",
+      "invalid-command"
+    );
+    console.log(JSON.stringify(result));
+    return 1;
+  } catch (error) {
+    const result = await writeCliFailure(
+      fallbackOutputDir(argv),
+      error instanceof Error ? error.message : String(error),
+      "Resolve the reported blocking issue and rerun hmos-precheck.",
+      "internal-error"
+    );
+    console.log(JSON.stringify(result));
+    return 1;
+  }
+}
+const __test__ = {
+  runChecks,
+  prepareRunOutputDir
+};
+export {
+  __test__,
+  main
+};
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    async (error) => {
+      const result = await writeCliFailure(
+        fallbackOutputDir(process.argv.slice(2)),
+        error instanceof Error ? error.message : String(error),
+        "Resolve the reported blocking issue and rerun hmos-precheck.",
+        "internal-error"
+      );
+      console.log(JSON.stringify(result));
+      process.exitCode = 1;
+    }
+  );
+}