@hmharness/domain-harmony 0.1.0

package/dist/ondevice.js

@@ -0,0 +1,174 @@
+/**
+ * @hmharness/domain-harmony - ondevicetest (minimal honest version)
+ * The ROADMAP gap "onDeviceTest 设备测试": a scripted assertion loop over
+ * the REAL device instead of a hypothetical unit-test framework. What we
+ * can actually verify on-device today, deterministically:
+ *   1. the hap installs
+ *   2. the ability launches
+ *   3. the app's own lifecycle log marker appears in hilog within N seconds
+ *   4. (cleanup) uninstalls
+ * That is exactly the loop our e2e script runs by hand - productized as a
+ * tool with a pass/fail verdict per step. Richer device-side test runners
+ * (aa test / ArkTSTDD) can slot in behind the same verdict shape later.
+ */
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execCb = promisify(execFile);
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runDeviceTest(o) {
+    const pre = o.target ? ['-t', o.target] : [];
+    const run = o.runImpl ?? (async (args, timeout) => {
+        try {
+            const { stdout, stderr } = await execCb(o.hdc, [...pre, ...args], { timeout, windowsHide: true });
+            return { ok: true, out: ((stdout || '') + (stderr ? '\n' + stderr : '')).trim() };
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, out: [e.stdout, e.stderr, e.message].filter(Boolean).join('\n').slice(0, 600) };
+        }
+    });
+    const steps = [];
+    // 1. install
+    let r = await run(['install', '-r', o.hap], 120_000);
+    if (!r.ok || /fail/i.test(r.out))
+        r = await run(['app', 'install', '-r', o.hap], 120_000);
+    steps.push({ step: 'install', pass: r.ok && /success/i.test(r.out), detail: r.out.slice(0, 200) });
+    if (!steps[0].pass)
+        return steps;
+    // 2. launch
+    r = await run(['shell', 'aa', 'start', '-a', o.ability, '-b', o.bundle], 30_000);
+    steps.push({ step: 'launch', pass: r.ok && /successfully/i.test(r.out), detail: r.out.slice(0, 200) });
+    // 3. lifecycle marker in hilog (poll briefly - logs flush asynchronously)
+    let sawMarker = false;
+    let tail = '';
+    const wait = o.waitMs ?? 6000;
+    const t0 = Date.now();
+    while (!sawMarker && Date.now() - t0 < wait) {
+        await new Promise((res) => setTimeout(res, 1000));
+        const g = await run(['shell', 'hilog', '-x'], 30_000);
+        tail = g.out;
+        sawMarker = tail.includes(o.expectLog);
+    }
+    steps.push({ step: `log-marker "${o.expectLog}"`, pass: sawMarker, detail: sawMarker ? `found in hilog within ${Date.now() - t0}ms` : `NOT found in ${(wait / 1000).toFixed(0)}s of hilog tail` });
+    // 4. cleanup uninstall
+    r = await run(['uninstall', o.bundle], 60_000);
+    if (!r.ok || /unknown command/i.test(r.out))
+        r = await run(['app', 'uninstall', o.bundle], 60_000);
+    steps.push({ step: 'uninstall(cleanup)', pass: r.ok && /success/i.test(r.out), detail: r.out.slice(0, 120) });
+    return steps;
+}
+export const harmonyDeviceTest = {
+    name: 'harmony_device_test',
+    description: 'On-device smoke test of a .hap against a connected device/emulator: install -> launch ability -> assert the app lifecycle marker appears in hilog (polls up to 6s) -> cleanup uninstall. Returns a per-step pass/fail verdict table. This is the honest minimal device test: real install, real launch, real log evidence.',
+    parameters: {
+        type: 'object',
+        properties: {
+            hap: { type: 'string', description: 'signed .hap path (default: newest -signed under the project)' },
+            bundle: { type: 'string', description: 'bundle name (default: read from AppScope/app.json5)' },
+            ability: { type: 'string', description: 'ability to launch (default: EntryAbility)' },
+            expect_log: { type: 'string', description: 'log marker to assert (default: "EntryAbility onCreate")' },
+            target: { type: 'string', description: 'device target id from harmony_devices' },
+        },
+        required: [],
+    },
+    needsApproval: () => true, // installs+launches+uninstalls on the device
+    async execute(args, ctx) {
+        // resolve hdc
+        const deveco = process.env.HM_DEVECO_HOME ?? 'C:\\DevEco-Studio';
+        let hdc = 'hdc';
+        try {
+            await execCb(hdc, ['--version'], { timeout: 8000, windowsHide: true });
+        }
+        catch {
+            const cand = join(deveco, 'sdk', 'default', 'openharmony', 'toolchains', 'hdc.exe');
+            if (await exists(cand))
+                hdc = cand;
+            else
+                return { output: 'hdc not found.', isError: true };
+        }
+        // project root walk
+        let root = ctx.cwd;
+        for (;;) {
+            if (await exists(join(root, 'build-profile.json5')))
+                break;
+            const parent = resolve(root, '..');
+            if (parent === root)
+                break;
+            root = parent;
+        }
+        // hap: explicit or newest -signed
+        let hap = typeof args.hap === 'string' && args.hap ? resolve(ctx.cwd, args.hap) : '';
+        if (!hap) {
+            const { readdir, stat } = await import('node:fs/promises');
+            let best = '';
+            let bestMtime = 0;
+            const stack = [root];
+            while (stack.length) {
+                const d = stack.pop();
+                let entries;
+                try {
+                    entries = await readdir(d, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const e of entries) {
+                    const p = join(d, e.name);
+                    if (e.isDirectory()) {
+                        if (!['node_modules', 'oh_modules', '.hvigor', '.preview', 'src'].includes(e.name))
+                            stack.push(p);
+                    }
+                    else if (e.name.endsWith('-signed.hap')) {
+                        const m = (await stat(p)).mtimeMs;
+                        if (m > bestMtime) {
+                            bestMtime = m;
+                            best = p;
+                        }
+                    }
+                }
+            }
+            hap = best;
+            if (!hap)
+                return { output: 'No signed .hap found. harmony_build then harmony_sign first (device tests need a signed hap).', isError: true };
+        }
+        if (!(await exists(hap)))
+            return { output: `No such file: ${hap}`, isError: true };
+        // bundle from app.json5 (via the schema module's lenient parser)
+        let bundle = typeof args.bundle === 'string' && args.bundle ? args.bundle : '';
+        if (!bundle) {
+            const { parseJson5 } = await import("./schema.js");
+            try {
+                const app = parseJson5(await (await import('node:fs/promises')).readFile(join(root, 'AppScope', 'app.json5'), 'utf8'));
+                bundle = app.app?.bundleName ?? '';
+            }
+            catch { /* schema check reports */ }
+        }
+        if (!bundle)
+            return { output: 'Could not determine bundle name - pass `bundle` explicitly.', isError: true };
+        const steps = await runDeviceTest({
+            hdc,
+            target: typeof args.target === 'string' ? args.target : undefined,
+            hap,
+            bundle,
+            ability: typeof args.ability === 'string' && args.ability ? args.ability : 'EntryAbility',
+            expectLog: typeof args.expect_log === 'string' && args.expect_log ? args.expect_log : 'EntryAbility onCreate',
+        });
+        const allPass = steps.every((s) => s.pass);
+        const lines = [
+            `device test: ${hap} (bundle ${bundle})`,
+            ...steps.map((s) => `  ${s.pass ? 'PASS' : 'FAIL'} ${s.step}${s.detail && !s.pass ? ` - ${s.detail}` : ''}`),
+            allPass ? 'ALL STEPS PASS - the app really installed, launched and logged on device.' : 'FAILED steps above - each names what broke.',
+        ];
+        return { output: lines.join('\n'), isError: !allPass };
+    },
+};

package/dist/profile.d.ts

@@ -0,0 +1,22 @@
+import type { Tool } from '@hmharness/kernel';
+export interface ProjectProfile {
+    root: string;
+    bundleName: string;
+    sdkVersion: string;
+    modules: Array<{
+        name: string;
+        type: string;
+        pages: string[];
+        abilities: string[];
+        deviceTypes: string[];
+    }>;
+    hapDependencies: string[];
+    resourceCounts: {
+        strings: number;
+        media: number;
+    };
+    sourceFiles: number;
+    configIssues: number;
+}
+export declare function profileProject(root: string): Promise<ProjectProfile>;
+export declare const harmonyProjectProfile: Tool;

package/dist/profile.js

@@ -0,0 +1,159 @@
+/**
+ * @hmharness/domain-harmony - profile (project picture, quality-trio minimal)
+ * A one-call inventory of a HarmonyOS project: modules, pages, abilities,
+ * har/hap dependency edges, resource counts, and config health (schema
+ * issues inline). Answer "what is this project" without reading 20 files -
+ * the base layer the old line's quality trio (profile / regression /
+ * scoring) starts from.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parseJson5, checkProjectSchemas } from "./schema.js";
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function countFiles(dir, ext, maxDepth = 6) {
+    let n = 0;
+    const stack = [[dir, 0]];
+    while (stack.length) {
+        const [d, dep] = stack.pop();
+        if (dep > maxDepth)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.') || ['node_modules', 'oh_modules', 'build', '.hvigor'].includes(e.name))
+                continue;
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                stack.push([p, dep + 1]);
+            else if (e.name.endsWith(ext))
+                n++;
+        }
+    }
+    return n;
+}
+export async function profileProject(root) {
+    const r = resolve(root);
+    // app scope
+    let bundleName = '';
+    try {
+        const app = parseJson5(await readFile(join(r, 'AppScope', 'app.json5'), 'utf8'));
+        bundleName = app.app?.bundleName ?? '';
+    }
+    catch { /* no AppScope */ }
+    // root build-profile for sdk
+    let sdk = '';
+    try {
+        const bp = parseJson5(await readFile(join(r, 'build-profile.json5'), 'utf8'));
+        sdk = bp.app?.products?.[0]?.compatibleSdkVersion ?? '';
+    }
+    catch { /* absent */ }
+    // modules
+    const modules = [];
+    let entries = [];
+    try {
+        entries = (await readdir(r, { withFileTypes: true })).filter((d) => d.isDirectory() && !d.name.startsWith('.') && !['AppScope', 'hvigor', 'build', 'oh_modules', 'node_modules', '.hvigor'].includes(d.name)).map((d) => ({ name: d.name }));
+    }
+    catch { /* none */ }
+    for (const { name } of entries) {
+        const mp = join(r, name, 'src', 'main', 'module.json5');
+        if (!(await exists(mp)))
+            continue;
+        try {
+            const m = parseJson5(await readFile(mp, 'utf8'));
+            // pages list from the profile json
+            let pages = [];
+            try {
+                const pp = parseJson5(await readFile(join(r, name, 'src', 'main', 'resources', 'base', 'profile', 'main_pages.json'), 'utf8'));
+                pages = pp.src ?? [];
+            }
+            catch { /* no pages (har) */ }
+            modules.push({
+                name,
+                type: m.module?.type ?? '',
+                pages,
+                abilities: (m.module?.abilities ?? []).map((a) => a.name),
+                deviceTypes: m.module?.deviceTypes ?? [],
+            });
+        }
+        catch { /* unparseable module.json5 - schema check will report it */ }
+    }
+    // entry's har deps
+    let hapDependencies = [];
+    try {
+        const pkg = parseJson5(await readFile(join(r, 'entry', 'oh-package.json5'), 'utf8'));
+        hapDependencies = Object.entries(pkg.dependencies ?? {}).map(([k, v]) => `${k}@${v}`);
+    }
+    catch { /* none */ }
+    const schema = await checkProjectSchemas(r);
+    return {
+        root: r,
+        bundleName,
+        sdkVersion: sdk,
+        modules,
+        hapDependencies,
+        resourceCounts: {
+            strings: await countFiles(join(r, 'AppScope', 'resources'), '.json') + await countFiles(join(r, 'entry', 'src', 'main', 'resources'), '.json'),
+            media: await countFiles(join(r, 'AppScope', 'resources'), '.png') + await countFiles(join(r, 'entry', 'src', 'main', 'resources'), '.png'),
+        },
+        sourceFiles: await countFiles(r, '.ets'),
+        configIssues: schema.issues.length,
+    };
+}
+export const harmonyProjectProfile = {
+    name: 'harmony_project_profile',
+    description: 'One-call project inventory: modules (type/pages/abilities/deviceTypes), har dependencies, resource + source counts, bundle/SDK, and config health (issue count from schema check). The "what is this project" answer without reading files one by one - use before planning changes or estimating scope.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'project root (default: auto-detect from cwd)' },
+        },
+        required: [],
+    },
+    needsApproval: () => false,
+    async execute(args, ctx) {
+        let root = ctx.cwd;
+        if (typeof args.path === 'string' && args.path)
+            root = resolve(ctx.cwd, args.path);
+        // walk up to the project root marker
+        let dir = root;
+        for (;;) {
+            if (await exists(join(dir, 'build-profile.json5'))) {
+                root = dir;
+                break;
+            }
+            const parent = resolve(dir, '..');
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        try {
+            const p = await profileProject(root);
+            const lines = [
+                `project: ${p.root}`,
+                `bundle: ${p.bundleName || '(unknown)'} · SDK: ${p.sdkVersion || '(not set)'}`,
+                `modules (${p.modules.length}):`,
+                ...p.modules.map((m) => `  - ${m.name} [${m.type}] pages:${m.pages.length} abilities:${m.abilities.join(',') || '-'} devices:${m.deviceTypes.join(',') || '-'}`),
+                `entry deps: ${p.hapDependencies.join(', ') || '(none)'}`,
+                `sources: ${p.sourceFiles} .ets · resources: ${p.resourceCounts.strings} json / ${p.resourceCounts.media} png`,
+                `config health: ${p.configIssues === 0 ? 'OK' : `${p.configIssues} issue(s) - run harmony_schema_check for details`}`,
+            ];
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `profile failed: ${String(err).slice(0, 160)}`, isError: true };
+        }
+    },
+};

package/dist/project.d.ts

@@ -0,0 +1,22 @@
+import type { Tool } from '@hmharness/kernel';
+/** Solid-color RGBA PNG (used for app/start icons - content is cosmetic). */
+export declare function solidPng(size: number, rgba: [number, number, number, number]): Buffer;
+export declare function sdkVersion(): string;
+export interface ScaffoldModule {
+    name: string;
+    type?: 'feature' | 'har';
+}
+export interface ScaffoldOptions {
+    name?: string;
+    bundleId?: string;
+    /** Extra pages beyond Index (PascalCase identifiers). */
+    pages?: string[];
+    /** Extra modules: feature HAPs or har libraries. */
+    modules?: ScaffoldModule[];
+}
+export declare function scaffoldProject(dir: string, opts?: ScaffoldOptions): Promise<{
+    root: string;
+    bundleId: string;
+    files: number;
+}>;
+export declare const harmonyProjectCreate: Tool;