android2harmony 0.1.0

package/agents/scripts/platform_query.mjs

@@ -0,0 +1,535 @@
+#!/usr/bin/env node
+
+import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DEFAULT_API_LEVEL = 22;
+const ALLOWED_STAGES = new Set(['planner', 'coder']);
+const DEFAULT_QUERY_TYPES_BY_STAGE = {
+  planner: ['api', 'pattern'],
+  coder: ['api', 'pattern'],
+};
+const DEEPWIKI_URL = 'https://mcp.deepwiki.com/mcp';
+const READ_TIMEOUT_MS = 120000;
+const MAX_RESPONSE_CHARS = 1600;
+const MAX_RETRIES = 2;
+const RETRY_BASE_MS = 2000;
+const DEEPWIKI_REPO = 'jjjzzz666/dev_kb_repo';
+const PROVIDER_FAILURE_PATTERNS = [
+  'Error processing question',
+  'Query failed',
+  'Error while executing query',
+];
+const PLANNER_SLOTS = [
+  'feasibility',
+  'owner_boundary',
+  'forbidden_path',
+  'version_gate',
+  'protocol_variant',
+  'fallback_gap',
+  'blocking_unknown',
+  'completion_evidence',
+  'implementation_implication',
+];
+const CODER_SLOTS = [
+  'exact_api',
+  'exact_import',
+  'return_error',
+  'context_permission',
+  'lifecycle_threading',
+  'local_forbidden',
+  'local_validation',
+  'planned_fallback',
+];
+const ALLOWED_STRUCTURED_SLOTS = new Set([...PLANNER_SLOTS, ...CODER_SLOTS]);
+const PREFACE_PATTERNS = [
+  'you are asking',
+  "you're asking",
+  'i understand',
+  'based on',
+  'summary:',
+  'here are',
+];
+const STRUCTURED_LINE_RE = /^[-*]\s*(?:\*\*)?(?<slot>extra:[a-z0-9_-]+|[a-z][a-z0-9_]*)(?:\*\*)?\s*:\s*(?<fact>.+)$/i;
+
+function parseArgs(argv) {
+  const args = {
+    request: '',
+    outDir: '',
+    apiLevel: null,
+    dryRun: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--request' && argv[index + 1]) {
+      args.request = argv[++index];
+      continue;
+    }
+    if (token === '--out-dir' && argv[index + 1]) {
+      args.outDir = argv[++index];
+      continue;
+    }
+    if (token === '--api-level' && argv[index + 1]) {
+      args.apiLevel = Number.parseInt(argv[++index], 10);
+      continue;
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    throw new Error(`unknown argument: ${token}`);
+  }
+  if (!args.request || !args.outDir) {
+    throw new Error('--request and --out-dir are required');
+  }
+  if (args.apiLevel !== null && !Number.isInteger(args.apiLevel)) {
+    throw new Error('--api-level must be an integer');
+  }
+  return args;
+}
+
+async function loadJson(filePath) {
+  const parsed = JSON.parse(await readFile(filePath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('request must be a JSON object');
+  }
+  return parsed;
+}
+
+async function writeJson(filePath, data) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+function normalize(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function normalizeList(value, name) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be a list`);
+  return value.map((item) => normalize(item)).filter(Boolean);
+}
+
+function resolveApiLevel(request, cliApiLevel) {
+  if (cliApiLevel != null) return { apiLevel: cliApiLevel, source: 'cli' };
+  const raw = request.api_level ?? request.api_version;
+  if (raw != null) {
+    const parsed = Number.parseInt(String(raw), 10);
+    if (!Number.isInteger(parsed)) throw new Error('api_level must be an integer');
+    return { apiLevel: parsed, source: 'request' };
+  }
+  return { apiLevel: DEFAULT_API_LEVEL, source: 'default' };
+}
+
+function validateRequest(request, apiLevel) {
+  const stage = normalize(request.stage);
+  if (!ALLOWED_STAGES.has(stage)) throw new Error("stage must be 'planner' or 'coder'");
+  const focusPoint = normalize(request.focus_point);
+  const taskExcerpt = normalize(request.task_excerpt ?? request.spec_excerpt);
+  if (!focusPoint) throw new Error('focus_point is required');
+  if (!taskExcerpt) throw new Error('task_excerpt is required');
+  const queryTypes = Array.isArray(request.query_types)
+    ? request.query_types.map((item) => normalize(item).toLowerCase()).filter(Boolean)
+    : [...DEFAULT_QUERY_TYPES_BY_STAGE[stage]];
+  for (const queryType of queryTypes) {
+    if (!['api', 'pattern', 'migration'].includes(queryType)) {
+      throw new Error(`unsupported query_type: ${queryType}`);
+    }
+  }
+  return {
+    stage,
+    api_level: apiLevel,
+    focus_point: focusPoint,
+    task_excerpt: taskExcerpt,
+    project_evidence: normalize(request.project_evidence) || 'none',
+    platform_surfaces: normalizeList(request.platform_surfaces, 'platform_surfaces'),
+    extra_constraints: normalizeList(request.extra_constraints, 'extra_constraints'),
+    query_types: [...new Set(queryTypes)],
+  };
+}
+
+function shortModuleName(stage, focusPoint) {
+  const base = focusPoint.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase() || 'platform_context';
+  return `${stage}_${base.slice(0, 72).replace(/_+$/g, '')}`;
+}
+
+function joinItems(items) {
+  return items.length ? items.join('; ') : 'none';
+}
+
+function defaultExtraConstraints(stage) {
+  if (stage === 'planner') {
+    return [
+      'Return only facts that affect feasibility, owner boundary, forbidden path, fallback/gap, edit boundary, blocking unknown, or completion evidence.',
+      'Check API-level gates, capability/permission/signing gates, owner/context/lifecycle constraints, sync/async protocol differences, state/persistence timing, return/error/null/default semantics, forbidden paths, false friends, fallback/gaps, completion evidence, and same-capability different-protocol traps.',
+      'Use the provided platform surfaces as natural signals. Prefer one primary API-family answer; do not enumerate broad alternative protocol families unless local evidence already narrows to the same capability family.',
+    ];
+  }
+  return [
+    'Return only facts that affect exact API/import/type/signature/member availability, return/error/null/default/conflict behavior, context/permission/config, lifecycle/threading, local forbidden usage, planned fallback, or local validation.',
+    'Check exact module imports, types, members, signatures, API-level gates, capability/permission/signing gates, owner/context/lifecycle constraints, sync/async protocol differences, state/persistence timing, return/error/null/default/conflict semantics, forbidden paths, false friends, and compile/runtime traps.',
+    'Use the provided platform surfaces as natural signals. Keep the answer local to the approved implementation point, prefer one primary API-family answer, and do not redesign the architecture.',
+  ];
+}
+
+function buildStageChecks(stage, queryType) {
+  if (stage === 'planner') {
+    if (queryType === 'api') {
+      return 'path feasibility at this API level; required owner/context/lifecycle/capability gate; API family traps that can invalidate the plan; fallback or blocking gap; code-observable completion evidence affected by this fact';
+    }
+    if (queryType === 'migration') {
+      return 'cross-platform assumptions that would make the plan invalid; HarmonyOS primary path; forbidden migration paths; owner/lifecycle/permission differences; fallback or blocking gap';
+    }
+    return 'forbidden paths and false friends; negative space that looks valid but should not be used; valid high-level pattern only if it changes the plan; hidden owner/lifecycle/state pitfalls; fallback or blocking gap; the smallest evidence a planner can require to know the path is complete';
+  }
+  if (queryType === 'api') {
+    return 'exact import/module/type/member/signature and minimal call shape; API-level availability for this call; required permission/config/context; return/error/null/default/conflict semantics; call-site lifecycle/threading constraints; compile/runtime failure traps';
+  }
+  if (queryType === 'migration') {
+    return 'old-platform assumptions that would break this local edit; exact HarmonyOS replacement API or local pattern; incompatible parameters/return semantics; permission/lifecycle differences at this call site';
+  }
+  return 'minimal valid local usage pattern; local forbidden usage that would fail compile/runtime; lifecycle/permission/state pitfalls at this call site; whether the planned fallback is valid; minimal validation checks for this edit; do not redesign the architecture';
+}
+
+function stageQualityBar(stage) {
+  if (stage === 'planner') {
+    return 'Quality bar: a planner can write a short contract from the answer: main path, forbidden path, fallback/gap, owner/lifecycle boundary, blocking unknown if unresolved, and observable completion evidence. ';
+  }
+  return 'Quality bar: a coder can write or check the local code from the answer: exact import/module/type/member/signature, minimal call shape, context/permission/config, lifecycle/threading, return/error/null/default/conflict semantics, forbidden local usage, and validation check. ';
+}
+
+function buildQuery(request, queryType) {
+  const stageGoal = request.stage === 'planner'
+    ? 'choose a valid implementation path before coding'
+    : 'verify exact local API usage while implementing';
+  const slots = request.stage === 'planner' ? PLANNER_SLOTS.join(', ') : CODER_SLOTS.join(', ');
+  return [
+    `HarmonyOS ArkTS/ArkUI platform fact check. API level: ${request.api_level}.`,
+    `Stage goal: ${stageGoal}. Focus: ${request.focus_point}.`,
+    `Task constraint: ${request.task_excerpt}.`,
+    `Project evidence: ${request.project_evidence}.`,
+    `Platform surfaces: ${joinItems(request.platform_surfaces)}.`,
+    `Extra constraints: ${joinItems(request.extra_constraints.length ? request.extra_constraints : defaultExtraConstraints(request.stage))}.`,
+    `Check only: ${buildStageChecks(request.stage, queryType)}.`,
+    stageQualityBar(request.stage),
+    'Return concise evidence bullets only.',
+    `Use these slots when applicable: ${slots}.`,
+    'For critical slots, write `slot: none` when the fact is not applicable or not known.',
+    'If sources disagree or the fact is unavailable, state the conflict or unknown explicitly; do not smooth it over.',
+    'You may add extra:<name> if a critical fact does not fit.',
+    'Do not invent missing facts.',
+    'Max 8 bullets. Format each bullet as \'- slot: fact\'.',
+    'No preface, headings, examples, tutorials, or steps.',
+  ].join(' ');
+}
+
+function cleanEvidenceResponse(text) {
+  const structuredLines = [];
+  const fallbackLines = [];
+  for (const rawLine of String(text).split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const lowered = line.toLowerCase().replace(/^[#*\-0-9.\s]+/, '');
+    if (line.startsWith('#') || PREFACE_PATTERNS.some((pattern) => lowered.startsWith(pattern))) {
+      continue;
+    }
+    const match = STRUCTURED_LINE_RE.exec(line);
+    if (match?.groups) {
+      let { slot } = match.groups;
+      const fact = match.groups.fact.trim();
+      if (!fact) continue;
+      slot = slot.toLowerCase();
+      if (!ALLOWED_STRUCTURED_SLOTS.has(slot) && !slot.startsWith('extra:')) {
+        slot = `extra:${slot}`;
+      }
+      structuredLines.push(`- ${slot}: ${fact}`);
+      continue;
+    }
+    fallbackLines.push(line);
+  }
+  if (structuredLines.length) return { cleaned: structuredLines.join('\n'), structured: true };
+  const cleaned = fallbackLines.join('\n').trim();
+  return { cleaned: cleaned || String(text), structured: false };
+}
+
+function buildQueries(request) {
+  const moduleName = shortModuleName(request.stage, request.focus_point);
+  return request.query_types.map((queryType) => ({
+    module: moduleName,
+    type: queryType,
+    query: buildQuery(request, queryType),
+  }));
+}
+
+function parseSseResponse(content) {
+  let result = '';
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line.startsWith('data: ')) continue;
+    try {
+      const data = JSON.parse(line.slice(6));
+      if (data.error) return `[provider_error] ${data.error}`;
+      for (const item of data.result?.content ?? []) {
+        if (item?.type === 'text') result += item.text ?? '';
+      }
+    } catch {
+      continue;
+    }
+  }
+  return result.trim();
+}
+
+function truncateResponse(text) {
+  if (text.length <= MAX_RESPONSE_CHARS) return text;
+  let cut = text.lastIndexOf('\n\n', MAX_RESPONSE_CHARS);
+  if (cut < MAX_RESPONSE_CHARS * 0.5) cut = MAX_RESPONSE_CHARS;
+  return `${text.slice(0, cut).trimEnd()}\n[truncated]`;
+}
+
+function providerTextFailure(text) {
+  return PROVIDER_FAILURE_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function retryWaitMillis(attempt) {
+  const base = RETRY_BASE_MS * (2 ** attempt);
+  return Math.round(base * (0.8 + (0.4 * Math.random())));
+}
+
+async function askDeepwikiOnce(repo, question) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+  try {
+    const response = await fetch(DEEPWIKI_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        'User-Agent': 'platform-context-query/0.1',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        id: 1,
+        params: {
+          name: 'ask_question',
+          arguments: {
+            repoName: repo,
+            question,
+          },
+        },
+      }),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      return {
+        ok: false,
+        response: `[http_error] ${response.status} ${response.statusText}`,
+        retryable: [429, 500, 502, 503, 504].includes(response.status),
+      };
+    }
+    const answer = parseSseResponse(text);
+    if (!answer) return { ok: false, response: '[provider_error] empty response', retryable: true };
+    if (answer.startsWith('[provider_error]')) return { ok: false, response: answer, retryable: true };
+    if (answer.includes('429 Too Many Requests') || answer.includes("Client error '429")) {
+      return { ok: false, response: answer, retryable: true };
+    }
+    if (providerTextFailure(answer)) return { ok: false, response: `[provider_error] ${answer}`, retryable: true };
+    return { ok: true, response: truncateResponse(answer), retryable: false };
+  } catch (error) {
+    if (error?.name === 'AbortError') return { ok: false, response: '[timeout]', retryable: true };
+    return { ok: false, response: `[provider_exception] ${error?.name ?? 'Error'}: ${error?.message ?? String(error)}`, retryable: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function askDeepwiki(repo, question) {
+  let lastResponse = '';
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+    const result = await askDeepwikiOnce(repo, question);
+    if (result.ok) return { ok: true, response: result.response };
+    lastResponse = result.response;
+    if (!result.retryable || attempt >= MAX_RETRIES) break;
+    await new Promise((resolve) => setTimeout(resolve, retryWaitMillis(attempt)));
+  }
+  return { ok: false, response: lastResponse };
+}
+
+async function queryOne(query) {
+  const { ok, response } = await askDeepwiki(DEEPWIKI_REPO, query.query);
+  return {
+    ok,
+    entry: {
+      ts: new Date().toISOString(),
+      provider: 'deepwiki',
+      repo: DEEPWIKI_REPO,
+      module: query.module ?? '',
+      type: query.type ?? 'pattern',
+      query: query.query ?? '',
+      response,
+      quality: ok ? 'verified' : 'query_failed',
+    },
+  };
+}
+
+async function runDeepwikiProvider(queries, cachePath) {
+  const results = await Promise.all(queries.map((query) => queryOne(query)));
+  const sortedEntries = results.map((result) => result.entry).sort((left, right) => String(left.type).localeCompare(String(right.type)));
+  const stderrLines = [];
+  let okCount = 0;
+  for (const { ok, entry } of results) {
+    if (ok) {
+      okCount += 1;
+      continue;
+    }
+    stderrLines.push(`${entry.module}/${entry.type}: ${entry.response}`);
+  }
+  await writeFile(cachePath, `${sortedEntries.map((entry) => JSON.stringify(entry)).join('\n')}${sortedEntries.length ? '\n' : ''}`, 'utf8');
+  return {
+    stdout: `Queried: ${okCount}, Failed: ${queries.length - okCount}, Total: ${queries.length}`,
+    stderr: stderrLines.join('\n'),
+  };
+}
+
+async function readCacheEntries(cachePath) {
+  try {
+    const content = await readFile(cachePath, 'utf8');
+    return content
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter((entry) => entry && typeof entry === 'object');
+  } catch {
+    return [];
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const started = Date.now();
+  const args = parseArgs(argv);
+  const requestPath = path.resolve(args.request);
+  const outDir = path.resolve(args.outDir);
+  const providerDir = path.join(outDir, 'provider');
+  const resultPath = path.join(outDir, 'platform-context-result.json');
+  const tracePath = path.join(outDir, 'platform-context-trace.json');
+  const queriesPath = path.join(providerDir, 'provider-queries.json');
+  const cachePath = path.join(providerDir, 'provider-cache.jsonl');
+
+  const rawRequest = await loadJson(requestPath);
+  const { apiLevel, source: apiLevelSource } = resolveApiLevel(rawRequest, args.apiLevel);
+  const request = validateRequest(rawRequest, apiLevel);
+  const queries = buildQueries(request);
+
+  await mkdir(providerDir, { recursive: true });
+  await rm(cachePath, { force: true, recursive: true });
+  await copyFile(requestPath, path.join(outDir, 'platform-context-request.json'));
+  await writeJson(queriesPath, queries);
+
+  let status = args.dryRun ? 'dry_run' : 'ok';
+  let providerStdout = '';
+  let providerStderr = '';
+  let exitCode = 0;
+
+  if (!args.dryRun) {
+    const providerResult = await runDeepwikiProvider(queries, cachePath);
+    providerStdout = providerResult.stdout;
+    providerStderr = providerResult.stderr;
+  }
+
+  const evidence = await readCacheEntries(cachePath);
+  const verifiedCount = evidence.filter((entry) => entry.quality === 'verified').length;
+  const failedCount = evidence.length - verifiedCount;
+  let structuredMissingCount = 0;
+  if (!args.dryRun) {
+    if (verifiedCount === 0) {
+      status = 'provider_failed';
+      exitCode = 1;
+    } else if (failedCount > 0) {
+      status = 'partial_ok';
+    }
+  }
+
+  const evidenceList = [];
+  const structuredEvidenceList = [];
+  for (const item of evidence) {
+    const rawResponse = String(item.response ?? '');
+    const { cleaned, structured } = cleanEvidenceResponse(rawResponse);
+    if (item.quality === 'verified' && !structured) structuredMissingCount += 1;
+    evidenceList.push({
+      type: item.type ?? '',
+      quality: item.quality ?? '',
+      query: item.query ?? '',
+      response: rawResponse,
+    });
+    structuredEvidenceList.push({
+      type: item.type ?? '',
+      quality: item.quality ?? '',
+      structured,
+      response: cleaned,
+    });
+  }
+
+  const result = {
+    status,
+    stage: request.stage,
+    api_level: apiLevel,
+    api_level_source: apiLevelSource,
+    focus_point: request.focus_point,
+    platform_surfaces: request.platform_surfaces,
+    evidence_count: evidence.length,
+    verified_evidence_count: verifiedCount,
+    failed_evidence_count: failedCount,
+    evidence: evidenceList,
+    structured_evidence: structuredEvidenceList,
+    structured_missing_count: structuredMissingCount,
+    llm_usage: [
+      'Use evidence only if it changes or confirms the platform contract, local API usage, forbidden path, fallback, blocking unknown, or validation condition.',
+      'If API facts and pattern facts disagree, do not merge them silently. Prefer the stricter lifecycle / permission / forbidden-path constraint; if the implementation path still depends on the disagreement, record blocking Unknown or platform_drift.',
+      'Do not paste raw evidence into plan.md or commit-info.md.',
+      'If status is not ok and the platform fact blocks the task, record blocking Unknown or platform_drift.',
+    ],
+  };
+  const trace = {
+    status,
+    provider: 'deepwiki',
+    api_level: apiLevel,
+    api_level_source: apiLevelSource,
+    query_count: queries.length,
+    evidence_count: evidence.length,
+    verified_evidence_count: verifiedCount,
+    failed_evidence_count: failedCount,
+    structured_missing_count: structuredMissingCount,
+    elapsed_ms: Date.now() - started,
+    dry_run: args.dryRun,
+    provider_stdout: providerStdout,
+    provider_stderr: providerStderr,
+    internal_files: {
+      queries: queriesPath,
+      cache: cachePath,
+    },
+  };
+
+  await writeJson(resultPath, result);
+  await writeJson(tracePath, trace);
+  process.stdout.write(`${resultPath}\n`);
+  return exitCode;
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  },
+);