@hmharness/domain-harmony 0.1.0

package/dist/apikg.d.ts

@@ -0,0 +1,34 @@
+import type { Tool } from '@hmharness/kernel';
+export interface ApiSymbolEntry {
+    module: string;
+    kind: string;
+    kit: string;
+    file: string;
+    line: number;
+    snippet: string;
+}
+export interface ApiIndex {
+    builtAt: string;
+    sdkPath: string;
+    sdkMtime: number;
+    symbolCount: number;
+    symbols: Record<string, ApiSymbolEntry[]>;
+}
+export declare function sdkApiDir(devecoHome: string): string;
+/** Parse one d.ts into symbols. Deliberately line-based and tolerant -
+ *  d.ts is regular enough that declaration headers live on single lines. */
+export declare function parseDeclaration(file: string, relModule: string, text: string): Array<[string, ApiSymbolEntry]>;
+export declare function buildApiIndex(devecoHome: string, cacheDir: string): Promise<ApiIndex>;
+/** Load the index (building it on first use / SDK change). */
+export declare function loadApiIndex(devecoHome: string, home: string): Promise<ApiIndex | null>;
+export interface LookupResult {
+    query: string;
+    exact: Array<ApiSymbolEntry>;
+    fuzzy: Array<{
+        name: string;
+        entry: ApiSymbolEntry;
+    }>;
+    totalSymbols: number;
+}
+export declare function lookupSymbol(index: ApiIndex, query: string, limit?: number): LookupResult;
+export declare const harmonyApiLookup: Tool;

package/dist/apikg.js

@@ -0,0 +1,185 @@
+/**
+ * @hmharness/domain-harmony - apikg (API knowledge graph, the codelin api_kg gap)
+ * The agent guesses HarmonyOS APIs because it cannot SEE the SDK. The
+ * declarations are right there on disk (ets/api/*.d.ts, 927 files) - this
+ * module indexes them ONCE into HMH_HOME/apikg and answers lookups with
+ * EVIDENCE: the declaration snippet + file:line + kit membership, so a
+ * wrong API name is caught by "not in the SDK" instead of hallucinated.
+ *
+ * Index shape (one JSON per run, rebuilt when the SDK mtime changes):
+ *   symbols: { name -> [{ module, kind, kit, file, line, snippet }] }
+ * kinds: namespace(declare module), interface, class, enum, type, function,
+ *        const, method, property. Methods index under "Class.method".
+ */
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function sdkApiDir(devecoHome) {
+    return join(devecoHome, 'sdk', 'default', 'openharmony', 'ets', 'api');
+}
+/* ---------------- parsing ---------------- */
+function extractKit(text) {
+    const m = text.match(/@kit\s+([A-Za-z0-9]+)/);
+    return m ? m[1] : '';
+}
+/** Parse one d.ts into symbols. Deliberately line-based and tolerant -
+ *  d.ts is regular enough that declaration headers live on single lines. */
+export function parseDeclaration(file, relModule, text) {
+    const kit = extractKit(text);
+    const out = [];
+    const lines = text.split('\n');
+    const declRe = /^(?:export\s+)?(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(interface|class|enum|type|const|namespace|module)\s+([A-Za-z_$][\w$]*)?/;
+    let currentName = '';
+    let currentKind = '';
+    let currentStart = -1;
+    const push = (end) => {
+        if (!currentName || currentStart < 0)
+            return;
+        const snippet = lines.slice(currentStart, Math.min(end, currentStart + 12)).join('\n').slice(0, 320);
+        out.push([currentName, { module: relModule, kind: currentKind, kit, file, line: currentStart + 1, snippet }]);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const m = declRe.exec(lines[i]);
+        if (m) {
+            push(i); // close previous
+            currentKind = m[1];
+            currentName = m[2] ?? '';
+            currentStart = i;
+            continue;
+        }
+        // methods/props inside a class/interface/namespace: foo(...): X; / foo: X;
+        // and namespace-level "function foo(...)" - both indented members
+        if (currentName && currentStart >= 0 && i > currentStart) {
+            const mm = /^\s{2,}(?:static\s+|readonly\s+|function\s+|const\s+|get\s+|set\s+)?([A-Za-z_$][\w$]*)\s*\??\s*[(:=]/.exec(lines[i]);
+            if (mm && !/^(constructor|declare|export)$/.test(mm[1]) && !/^\/\//.test(lines[i])) {
+                const member = `${currentName}.${mm[1]}`;
+                const isFn = /^\s{2,}function\s/.test(lines[i]) || lines[i].includes('(');
+                const snippet = lines[i].trim().slice(0, 200);
+                out.push([member, { module: relModule, kind: isFn ? 'function' : 'member', kit, file, line: i + 1, snippet }]);
+            }
+        }
+        // top-level (unindented) exported functions inside a namespace body get
+        // caught by the member branch above via their 4-space indent in d.ts
+    }
+    push(lines.length);
+    return out;
+}
+/* ---------------- index build ---------------- */
+export async function buildApiIndex(devecoHome, cacheDir) {
+    const apiDir = sdkApiDir(devecoHome);
+    // SDK identity = newest mtime among the api dir's entries
+    let sdkMtime = 0;
+    try {
+        for (const e of await readdir(apiDir)) {
+            const m = (await stat(join(apiDir, e))).mtimeMs;
+            if (m > sdkMtime)
+                sdkMtime = m;
+        }
+    }
+    catch { /* no SDK */ }
+    const indexFile = join(cacheDir, 'apikg.json');
+    try {
+        const prev = JSON.parse(await readFile(indexFile, 'utf8'));
+        if (prev.sdkMtime === sdkMtime && prev.symbolCount > 0)
+            return prev; // fresh
+    }
+    catch { /* rebuild */ }
+    const symbols = {};
+    let files = 0;
+    try {
+        files = (await readdir(apiDir)).filter((f) => f.endsWith('.d.ts') || f.endsWith('.d.ets')).length;
+    }
+    catch { /* none */ }
+    for (const f of (await readdir(apiDir).catch(() => []))) {
+        if (!/\.d\.(ts|ets)$/.test(f))
+            continue;
+        const text = await readFile(join(apiDir, f), 'utf8');
+        const relModule = f.replace(/\.d\.(ts|ets)$/, '');
+        for (const [name, entry] of parseDeclaration(f, relModule, text)) {
+            (symbols[name] ??= []).push(entry);
+        }
+    }
+    const index = {
+        builtAt: new Date().toISOString(),
+        sdkPath: apiDir,
+        sdkMtime,
+        symbolCount: Object.keys(symbols).length,
+        symbols,
+    };
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(indexFile, JSON.stringify(index), 'utf8');
+    return index;
+}
+/** Load the index (building it on first use / SDK change). */
+export async function loadApiIndex(devecoHome, home) {
+    try {
+        return await buildApiIndex(devecoHome, join(home, 'apikg'));
+    }
+    catch {
+        return null;
+    }
+}
+export function lookupSymbol(index, query, limit = 4) {
+    const q = query.trim();
+    const exact = (index.symbols[q] ?? []).slice(0, limit);
+    const fuzzy = [];
+    const lower = q.toLowerCase();
+    for (const [name, entries] of Object.entries(index.symbols)) {
+        if (name.toLowerCase().includes(lower) && name !== q) {
+            for (const entry of entries.slice(0, 1))
+                fuzzy.push({ name, entry });
+            if (fuzzy.length >= limit)
+                break;
+        }
+    }
+    return { query: q, exact, fuzzy, totalSymbols: index.symbolCount };
+}
+/* ---------------- tool ---------------- */
+export const harmonyApiLookup = {
+    name: 'harmony_api_lookup',
+    description: 'Look up a HarmonyOS/ArkTS API symbol in the ACTUAL local SDK declarations (927 d.ts files indexed) - returns the declaration snippet with file:line evidence and kit membership. Use BEFORE writing code that calls any @ohos API: confirms the symbol exists, its exact signature context, and which kit it belongs to. A miss means "not in this SDK" - do not guess, reconsider the name or check the docs.',
+    parameters: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string', description: 'symbol name, e.g. "UIAbility", "hilog.info" (hierarchical too), "Want"' },
+        },
+        required: ['symbol'],
+    },
+    needsApproval: () => false, // read-only; first call builds the local index
+    async execute(args) {
+        const { homedir } = await import('node:os');
+        const deveco = process.env.HM_DEVECO_HOME ?? 'C:\\DevEco-Studio';
+        const home = process.env.HMH_HOME ?? join(homedir(), '.hmharness');
+        const index = await loadApiIndex(deveco, home);
+        if (!index || index.symbolCount === 0) {
+            return { output: `SDK declarations not found at ${sdkApiDir(deveco)} - set HM_DEVECO_HOME.`, isError: true };
+        }
+        const raw = String(args.symbol ?? '').trim();
+        if (!raw)
+            return { output: 'symbol required', isError: true };
+        // support "hilog.info" - namespace.method form: try full, then the tail
+        const tries = [raw];
+        if (raw.includes('.'))
+            tries.push(raw.split('.').pop());
+        let best = null;
+        for (const t of tries) {
+            const r = lookupSymbol(index, t);
+            if (r.exact.length > 0) {
+                best = r;
+                break;
+            }
+            if (!best)
+                best = r;
+        }
+        const r = best;
+        if (r.exact.length === 0 && r.fuzzy.length === 0) {
+            return { output: `"${raw}" not found in the local SDK index (${r.totalSymbols} symbols). The symbol does not exist in THIS SDK version - do not guess; check the docs or reconsider the name.`, isError: true };
+        }
+        const fmt = (e, name) => `  ${name ? name + ' ' : ''}[${e.kind}${e.kit ? ' · ' + e.kit : ''}] ${e.module} :: ${e.file}:${e.line}\n${e.snippet}`;
+        const lines = [
+            `query: ${raw} (index: ${r.totalSymbols} symbols, built ${index.builtAt.slice(0, 10)})`,
+            ...r.exact.map((e) => fmt(e)),
+            ...(r.fuzzy.length ? ['', 'similar:', ...r.fuzzy.map((f) => fmt(f.entry, f.name))] : []),
+        ];
+        return { output: lines.join('\n') };
+    },
+};

package/dist/apimatrix.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @hmharness/domain-harmony - apimatrix (API-level capability matrix)
+ * SDK version strings come in TWO shapes and toolchain behavior differs
+ * across them:
+ *   legacy:  "6.1.1(24)"            - <version>(<api-level>) up to API 25
+ *   semver:  "26.0.0" and later     - pure SemVer; the API level IS the
+ *                                     major (26.0.0 == API 26)
+ *
+ * Everything that branches on "which SDK / API level is this" (scaffold
+ * defaults, capability guards, compat warnings) goes through this module
+ * so the 26.0.0 switch happens in exactly one place.
+ */
+export interface SdkVersion {
+    raw: string;
+    apiLevel: number;
+    shape: 'legacy' | 'semver';
+    /** comparable numeric tuple for range math */
+    tuple: [number, number, number];
+}
+/** Parse "6.1.1(24)" / "5.0.5(17)" / "26.0.0" / "26.1.2". Throws on junk. */
+export declare function parseSdkVersion(raw: string): SdkVersion;
+/** Compare two SDK versions (tuple math; throws on unparseable input). */
+export declare function compareSdk(a: string, b: string): number;
+export interface CapabilityRule {
+    id: string;
+    /** minimum SDK version (inclusive) */
+    since: string;
+    /** maximum SDK version (exclusive); omit = open-ended */
+    until?: string;
+    note: string;
+}
+/**
+ * The capability matrix. Extend entries as toolchain knowledge lands; the
+ * radar/knowledge pipeline can propose additions through the normal skill
+ * gate. Keep notes one actionable line each.
+ */
+export declare const CAPABILITY_MATRIX: CapabilityRule[];
+/** Which matrix rules apply to a given SDK version (sorted by since). */
+export declare function capabilitiesFor(sdk: string): Array<CapabilityRule & {
+    available: boolean;
+}>;
+/** Format a version for build-profile compatibleSdkVersion: as-parsed. */
+export declare function formatSdkVersion(v: SdkVersion): string;

package/dist/apimatrix.js

@@ -0,0 +1,63 @@
+/**
+ * @hmharness/domain-harmony - apimatrix (API-level capability matrix)
+ * SDK version strings come in TWO shapes and toolchain behavior differs
+ * across them:
+ *   legacy:  "6.1.1(24)"            - <version>(<api-level>) up to API 25
+ *   semver:  "26.0.0" and later     - pure SemVer; the API level IS the
+ *                                     major (26.0.0 == API 26)
+ *
+ * Everything that branches on "which SDK / API level is this" (scaffold
+ * defaults, capability guards, compat warnings) goes through this module
+ * so the 26.0.0 switch happens in exactly one place.
+ */
+/** Parse "6.1.1(24)" / "5.0.5(17)" / "26.0.0" / "26.1.2". Throws on junk. */
+export function parseSdkVersion(raw) {
+    const s = raw.trim();
+    const legacy = /^(\d+)\.(\d+)\.(\d+)\((\d+)\)$/.exec(s);
+    if (legacy) {
+        const [, a, b, c, lvl] = legacy;
+        return { raw: s, apiLevel: Number(lvl), shape: 'legacy', tuple: [Number(a), Number(b), Number(c)] };
+    }
+    const semver = /^(\d+)\.(\d+)\.(\d+)$/.exec(s);
+    if (semver) {
+        const [, a, b, c] = semver;
+        const tuple = [Number(a), Number(b), Number(c)];
+        // from 26 on, the major IS the API level (HarmonyOS NEXT renumbering)
+        return { raw: s, apiLevel: tuple[0], shape: tuple[0] >= 26 ? 'semver' : 'legacy', tuple };
+    }
+    throw new Error(`unrecognized SDK version "${raw}" - expected "6.1.1(24)" or "26.0.0" style`);
+}
+/** Compare two SDK versions (tuple math; throws on unparseable input). */
+export function compareSdk(a, b) {
+    const ta = parseSdkVersion(a).tuple;
+    const tb = parseSdkVersion(b).tuple;
+    for (let i = 0; i < 3; i++) {
+        if (ta[i] !== tb[i])
+            return ta[i] < tb[i] ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * The capability matrix. Extend entries as toolchain knowledge lands; the
+ * radar/knowledge pipeline can propose additions through the normal skill
+ * gate. Keep notes one actionable line each.
+ */
+export const CAPABILITY_MATRIX = [
+    { id: 'stage-model', since: '5.0.0(12)', note: 'stage model is the only supported model' },
+    { id: 'har-module', since: '5.0.0(12)', note: 'har shared libraries' },
+    { id: 'shared-module', since: '5.0.5(17)', note: 'shared (static) module type' },
+    { id: '2in1-devicetype', since: '5.0.5(17)', note: '"2in1" deviceType token' },
+    { id: 'semver-numbering', since: '26.0.0', note: 'version strings drop the (api) suffix; major == API level' },
+];
+/** Which matrix rules apply to a given SDK version (sorted by since). */
+export function capabilitiesFor(sdk) {
+    const out = CAPABILITY_MATRIX.map((r) => ({
+        ...r,
+        available: compareSdk(sdk, r.since) >= 0 && (r.until ? compareSdk(sdk, r.until) < 0 : true),
+    }));
+    return out.sort((a, b) => (a.available === b.available ? compareSdk(a.since, b.since) : a.available ? -1 : 1));
+}
+/** Format a version for build-profile compatibleSdkVersion: as-parsed. */
+export function formatSdkVersion(v) {
+    return v.raw;
+}

package/dist/builddoctor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @hmharness/domain-harmony - builddoctor (compile-fix loop, the codelin icf gap)
+ * When hvigor fails, its log is a wall of stack traces. This tool parses
+ * the failure into ONE OF A SMALL SET OF KNOWN CAUSE CLASSES and returns
+ * the concrete fix for that class - so the agent (or user) repairs the
+ * actual cause instead of googling the tail of a stack trace.
+ *
+ * The classifier is deliberately regex-on-tail: hvigor's stable failure
+ * signatures are few (env/sdk/signing/deps/arkts/config), each with a
+ * known remedy. Unknown signatures pass through with the raw tail so
+ * nothing is hidden.
+ */
+import type { Tool } from '@hmharness/kernel';
+export interface DiagnosedError {
+    kind: string;
+    fix: string;
+    evidence: string;
+}
+/** Diagnose a hvigor/build failure output; unknown returns null (caller
+ *  shows the raw tail - never hide unclassified failures). */
+export declare function diagnoseBuildFailure(log: string): DiagnosedError | null;
+/** Extract the first ERROR block (file/line/position) from a build log. */
+export declare function firstErrorBlock(log: string): string;
+export declare const harmonyBuildDoctor: Tool;

package/dist/builddoctor.js

@@ -0,0 +1,99 @@
+/** Cause classes: signature -> fix. Order matters (first hit wins). */
+const SIGNATURES = [
+    {
+        re: /Invalid value of DEVECO_SDK_HOME|sdk home|not find sdk|SdkHomePath/i,
+        kind: 'sdk-home',
+        fix: 'DEVECO_SDK_HOME is unset or wrong. Set HM_DEVECO_HOME (default C:\\DevEco-Studio) or export DEVECO_SDK_HOME=<DevEco>/sdk; our build wrapper already tries - set HM_DEVECO_HOME and retry.',
+    },
+    {
+        re: /signingConfigs|signing config|keystore|\.p12|\.cer|no signing/i,
+        kind: 'signing',
+        fix: 'Signing config missing/invalid. For a debug run on emulator this is usually a stale auto-signature: in DevEco re-enable auto-sign (File > Project Structure > Signing), or clear signingConfigs and build unsigned for install checks. Production signing needs real certs from AppGallery.',
+    },
+    {
+        re: /ohpm (install|ERROR)|ohos_modules|Failed to install dependencies|ERESOLVE|404 .*ohpm/i,
+        kind: 'ohpm-deps',
+        fix: 'ohpm dependency resolution failed. Run: ohpm install --all (in the project root) and check oh-package.json5 versions actually exist on the registry; .har file: deps must exist or be pre-built.',
+    },
+    {
+        re: /hvigor (daemon|wrapper)|node: not found|NODE_HOME|Cannot find module .*hvigor/i,
+        kind: 'hvigor-env',
+        fix: 'hvigor/node environment broken. Set HM_DEVECO_HOME so the bundled tools/node is found; delete the project .hvigor cache dir and retry (a corrupted daemon cache is common).',
+    },
+    {
+        re: /ERROR: ArkTS|arkts-\d+|Cannot find module '@|Struct.*must|expected component/i,
+        kind: 'arkts-source',
+        fix: 'ArkTS compile error (source). Open the file+line named in the log above this diagnosis; the fix is a code edit (missing import, wrong type, struct syntax) - not an environment issue. Read the first "ERROR" block for the exact location.',
+    },
+    {
+        re: /build-profile|module.json5|parse.*json|Expected.*json|module.*not found in/i,
+        kind: 'config',
+        fix: 'Project config problem. Run harmony_schema_check first - it names the exact broken field in module.json5/build-profile.json5 in milliseconds instead of this stack trace.',
+    },
+    {
+        re: /network|ECONN|timeout|registry|fetch failed/i,
+        kind: 'network',
+        fix: 'Network failure fetching deps/registry. Check proxy (or disable proxy for 127.0.0.1 registries) and retry; ohpm may need a mirror (ohpm config set registry https://ohpm.openharmony.cn/ohpm/).',
+    },
+];
+/** Diagnose a hvigor/build failure output; unknown returns null (caller
+ *  shows the raw tail - never hide unclassified failures). */
+export function diagnoseBuildFailure(log) {
+    // the interesting part is the LAST error block, not the whole log
+    const tail = log.slice(-8000);
+    for (const s of SIGNATURES) {
+        const m = tail.match(s.re);
+        if (m) {
+            const evidence = tail.split('\n').find((l) => s.re.test(l))?.trim().slice(0, 200) ?? m[0];
+            return { kind: s.kind, fix: s.fix, evidence };
+        }
+    }
+    return null;
+}
+/** Extract the first ERROR block (file/line/position) from a build log. */
+export function firstErrorBlock(log) {
+    const i = log.search(/^.*\bERROR\b/m);
+    if (i < 0)
+        return '';
+    return log.slice(i, i + 700).split('\n').slice(0, 8).join('\n');
+}
+export const harmonyBuildDoctor = {
+    name: 'harmony_build_doctor',
+    description: 'Diagnose a failed HarmonyOS build log: classifies the failure into a known cause class (sdk-home / signing / ohpm-deps / hvigor-env / arkts-source / config / network) and returns the concrete fix for that class plus the first ERROR block. Pass the build output text; also runs harmony_build yourself and diagnoses when given a project path with run=true.',
+    parameters: {
+        type: 'object',
+        properties: {
+            log: { type: 'string', description: 'the failed build output to diagnose (from a previous harmony_build)' },
+            project: { type: 'string', description: 'alternative: run harmony_build on this path now and diagnose its output' },
+        },
+        required: [],
+    },
+    needsApproval: () => false,
+    async execute(args, ctx) {
+        let log = typeof args.log === 'string' ? args.log : '';
+        if (!log && typeof args.project === 'string') {
+            const { harmonyBuild } = await import("./index.js");
+            const r = await harmonyBuild.execute({ project: args.project }, ctx);
+            log = r.output;
+            if (!r.isError)
+                return { output: `build succeeded - nothing to diagnose.\n${log.split('\n').slice(0, 3).join('\n')}` };
+        }
+        if (!log.trim())
+            return { output: 'pass the failed build output in `log`, or a project path to run a fresh build.', isError: true };
+        const d = diagnoseBuildFailure(log);
+        const first = firstErrorBlock(log);
+        if (!d) {
+            return { output: `Unclassified failure (no known signature matched) - full context follows. If a pattern repeats, it belongs in the doctor's signature table.\n\nFirst ERROR block:\n${first || '(none found)'}\n\nTail:\n${log.slice(-1200)}` };
+        }
+        return {
+            output: [
+                `kind: ${d.kind}`,
+                `evidence: ${d.evidence}`,
+                `fix: ${d.fix}`,
+                '',
+                'First ERROR block:',
+                first || '(no explicit ERROR line - see evidence above)',
+            ].join('\n'),
+        };
+    },
+};

package/dist/cangjie.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '@hmharness/kernel';
+export declare function findCjpm(): Promise<string>;
+export declare const harmonyCjpmBuild: Tool;
+export declare const harmonyCjpmTest: Tool;

package/dist/cangjie.js

@@ -0,0 +1,129 @@
+/**
+ * @hmharness/domain-harmony - cangjie (cjpm) tools
+ * Cangjie package-manager build/test for HarmonyOS native modules.
+ * Resolution: HM_CJPM env override > PATH > known DevEco-adjacent install
+ * roots. CANGJIE_HOME is derived from the cjpm.exe layout and injected -
+ * the #1 Windows pitfall recorded in the cjpm-build-repair skill.
+ */
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const CJPM_CANDIDATE_ROOTS = [
+    'C:\\鸿蒙开发工具\\cangjie\\cangjie-1.1.0\\tools\\bin\\cjpm.exe',
+    'C:\\cangjie113\\tools\\bin\\cjpm.exe',
+];
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function findCjpm() {
+    if (process.env.HM_CJPM)
+        return process.env.HM_CJPM;
+    const probe = await run('cjpm', ['--version'], 8000);
+    if (probe.ok)
+        return 'cjpm';
+    for (const p of CJPM_CANDIDATE_ROOTS)
+        if (await exists(p))
+            return p;
+    return '';
+}
+function cjpmHome(cjpm) {
+    // <root>/tools/bin/cjpm.exe -> <root>. Only meaningful for an absolute
+    // install path; the PATH alias already carries its own environment, and a
+    // wrong CANGJIE_HOME is precisely the Windows pitfall the skill warns of.
+    if (!/^[a-zA-Z]:[\\/]/.test(cjpm))
+        return null;
+    return resolve(cjpm, '..', '..', '..');
+}
+async function run(cmd, args, timeoutMs = 20_000, cwd, extraEnv) {
+    try {
+        const { stdout, stderr } = await exec(cmd, args, {
+            timeout: timeoutMs,
+            windowsHide: true,
+            maxBuffer: 16 * 1024 * 1024,
+            cwd,
+            ...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {}),
+        });
+        return { ok: true, out: (stdout || stderr || '(no output)').trim() };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, out: [e.stdout, e.stderr, e.message].filter(Boolean).join('\n').slice(0, 4000) };
+    }
+}
+/** Walk up looking for a cjpm project marker. */
+async function findCjpmRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (await exists(join(dir, 'cjpm.toml')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '';
+        dir = parent;
+    }
+}
+async function cjpmEnv() {
+    const cjpm = await findCjpm();
+    if (!cjpm) {
+        return { error: 'cjpm not found. Install the Cangjie toolchain, add it to PATH, or set HM_CJPM to cjpm.exe.' };
+    }
+    const env = {};
+    const home = cjpmHome(cjpm);
+    if (home && !process.env.CANGJIE_HOME)
+        env.CANGJIE_HOME = home;
+    return { cjpm, env };
+}
+export const harmonyCjpmBuild = {
+    name: 'harmony_cjpm_build',
+    description: 'Build a Cangjie (cjpm) package with cjpm build. Looks for cjpm.toml at/above the given path (default cwd). Injects CANGJIE_HOME derived from the resolved cjpm.exe - the classic Windows pitfall. Long-running: allow minutes.',
+    parameters: {
+        type: 'object',
+        properties: {
+            project: { type: 'string', description: 'directory containing cjpm.toml (default: auto-detect from cwd)' },
+            release: { type: 'boolean', description: 'build in release mode (default false)' },
+        },
+        required: [],
+    },
+    async execute(args, ctx) {
+        const e = await cjpmEnv();
+        if ('error' in e)
+            return { output: e.error, isError: true };
+        const start = typeof args.project === 'string' && args.project ? resolve(ctx.cwd, args.project) : ctx.cwd;
+        const root = await findCjpmRoot(start);
+        if (!root)
+            return { output: `No cjpm project found at or above ${start} (looking for cjpm.toml).`, isError: true };
+        const r = await run(e.cjpm, ['build', ...(args.release === true ? ['--release'] : [])], 900_000, root, e.env);
+        const ok = r.ok && (/build finished/i.test(r.out) || !/error/i.test(r.out));
+        const tail = r.out.length > 4000 ? '...\n' + r.out.slice(-4000) : r.out;
+        return { output: `project: ${root}\ncjpm: ${e.cjpm}\n${tail}`, isError: !ok };
+    },
+};
+export const harmonyCjpmTest = {
+    name: 'harmony_cjpm_test',
+    description: 'Run Cangjie unit tests (cjpm test) in the project at/above the given path. Same CANGJIE_HOME injection as harmony_cjpm_build.',
+    parameters: {
+        type: 'object',
+        properties: { project: { type: 'string', description: 'directory containing cjpm.toml (default: auto-detect from cwd)' } },
+        required: [],
+    },
+    async execute(args, ctx) {
+        const e = await cjpmEnv();
+        if ('error' in e)
+            return { output: e.error, isError: true };
+        const start = typeof args.project === 'string' && args.project ? resolve(ctx.cwd, args.project) : ctx.cwd;
+        const root = await findCjpmRoot(start);
+        if (!root)
+            return { output: `No cjpm project found at or above ${start}.`, isError: true };
+        const r = await run(e.cjpm, ['test'], 900_000, root, e.env);
+        const tail = r.out.length > 4000 ? '...\n' + r.out.slice(-4000) : r.out;
+        return { output: `project: ${root}\n${tail}`, isError: !r.ok };
+    },
+};

package/dist/emulator.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from '@hmharness/kernel';
+export declare function deployedDir(): string;
+export declare function imageRoot(): string;
+export declare const harmonyEmulatorList: Tool;
+export declare const harmonyEmulatorStart: Tool;
+export declare const harmonyEmulatorStop: Tool;
+export declare const harmonyEmulatorCatalog: Tool;
+export declare const harmonyEmulatorCreate: Tool;
+export declare const harmonyEmulatorDelete: Tool;
+export declare const harmonyImageDownloadCheck: Tool;
+export declare const emulatorTools: Tool[];