@harmonyos-arkts/d2h 0.1.3 → 0.1.6

package/dist/bin/install-opencode.js

@@ -2,57 +2,151 @@
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
-import { installOpenCode } from '../src/install-opencode.js';
-const help = `Install this package's skills and agents into OpenCode or DevEco Code.
-
-Usage: d2h [options]
-
-  --source-dir <path>  Source root (defaults to this package)
-  --agent <name>       opencode (default) or deveco
-  --config-dir <path>  Override the selected agent's config root
-                       OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
-                       $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
-  --link              Create absolute symbolic links (development only)
-  --force             Replace conflicting installed skills and agents
-  --dry-run           Print operations without writing files
-  -h, --help          Show this help
-
-Only skills/*/SKILL.md trees and agents/*.md are installed.
-Existing application configuration and AGENTS.md are not modified.
-With npx, prefer the default copy mode: its cache can be removed.
+import { inspectInstallation, installOpenCode } from '../src/install-opencode.js';
+import { inspectToolchain, installToolchain, loadToolchain } from '../src/toolchain.js';
+import fs from 'node:fs';
+import { inspectVSCodeInstallation, installVSCode } from '../src/install-vscode.js';
+const help = `Install this package's skills and agents into OpenCode or DevEco Code.
+
+Usage: d2h [options]
+
+  d2h install         Install compatible CLIs and agent/skill definitions
+  d2h upgrade         Reapply this package's tested toolchain and definitions
+  d2h upgrade --check Preview version and installation status only
+  d2h doctor [--agent opencode|deveco|vscode] [--config-dir <path>]
+                      Check definitions, host environment and CLI capabilities
+
+  --check-env         Check host tools and write reports without installing skills
+                       Example: d2h --check-env --output-dir ./environment-report
+                       Use d2h --check-env --help for check options
+
+  --source-dir <path>  Source root (defaults to this package)
+  --agent <name>       opencode (default), deveco or vscode
+  --extension-dir <path>  VS Code HarmonyOS Dev Assistant extension root
+  --config-dir <path>  Override the selected agent's config root
+                       OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
+                       $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
+  --link              Create absolute symbolic links (development only)
+  --force             Replace conflicting definitions and managed CLI npm links
+  --dry-run           Print operations without writing files
+  --skip-tools        Install definitions only (local development)
+  -h, --help          Show this help
+
+Managed AppGraph and droid2hmos CLIs plus skills/*/SKILL.md trees and agents/*.md are installed.
+Existing application configuration and AGENTS.md are not modified.
+With npx, prefer the default copy mode: its cache can be removed.
 `;
 try {
-    const options = {
-        sourceDir: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
-        agent: 'opencode',
-    };
     const args = process.argv.slice(2);
-    for (let index = 0; index < args.length; index++) {
-        const arg = args[index];
-        if (arg === '-h' || arg === '--help') {
-            console.log(help);
-            process.exit(0);
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+    if (args[0] === 'doctor') {
+        let agent = 'opencode';
+        let configDir;
+        let extensionDir;
+        for (let index = 1; index < args.length; index++) {
+            const arg = args[index];
+            if (arg === '--agent' || arg === '--config-dir' || arg === '--extension-dir') {
+                const value = args[++index];
+                if (!value || value.startsWith('--'))
+                    throw new Error(`${arg} requires a value`);
+                if (arg === '--agent')
+                    agent = value;
+                else if (arg === '--config-dir')
+                    configDir = value;
+                else
+                    extensionDir = value;
+            }
+            else
+                throw new Error(`unknown doctor option: ${arg}`);
         }
-        if (arg === '--source-dir' || arg === '--config-dir' || arg === '--agent') {
-            const value = args[++index];
-            if (!value || value.startsWith('--'))
-                throw new Error(`${arg} requires a value`);
-            const key = { '--source-dir': 'sourceDir', '--config-dir': 'configDir', '--agent': 'agent' }[arg];
-            options[key] = value;
+        if (!['opencode', 'deveco', 'vscode'].includes(agent))
+            throw new Error(`unsupported agent: ${agent}`);
+        configDir ??= process.env[agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), agent);
+        const installation = agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : inspectInstallation(configDir);
+        const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+        const definitionsMatch = installation.status === 'passed' && installation.packageVersion === packageVersion &&
+            (agent === 'vscode' || ('agent' in installation && installation.agent === agent));
+        console.log(`definitions ${definitionsMatch ? 'passed' : 'failed'}: ${installation.summary}${definitionsMatch ? '' : `; reinstall ${agent} definitions from D2H ${packageVersion}`}`);
+        const results = inspectToolchain(packageRoot);
+        for (const item of results)
+            console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}; capabilities ${JSON.stringify(item.capabilities)}`);
+        const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
+        const { main } = await import(checkerUrl.href);
+        const environmentExit = await main([]);
+        if (environmentExit !== 0 || !definitionsMatch || results.some(item => item.status !== 'passed'))
+            process.exitCode = 1;
+    }
+    else if (args.includes('--check-env')) {
+        if (args.filter(arg => arg === '--check-env').length !== 1)
+            throw new Error('--check-env may only be specified once');
+        const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
+        const { main } = await import(checkerUrl.href);
+        process.exitCode = await main(args.filter(arg => arg !== '--check-env'));
+    }
+    else {
+        const explicitSource = args.includes('--source-dir');
+        const upgrade = args[0] === 'upgrade';
+        const installArgs = ['install', 'upgrade'].includes(args[0]) ? args.slice(1) : args;
+        const checkOnly = upgrade && installArgs.includes('--check');
+        const skipTools = installArgs.includes('--skip-tools') || explicitSource;
+        let extensionDir;
+        const options = {
+            sourceDir: packageRoot,
+            agent: 'opencode',
+        };
+        for (let index = 0; index < installArgs.length; index++) {
+            const arg = installArgs[index];
+            if (arg === '-h' || arg === '--help') {
+                console.log(help);
+                process.exit(0);
+            }
+            if (arg === '--source-dir' || arg === '--config-dir' || arg === '--agent' || arg === '--extension-dir') {
+                const value = installArgs[++index];
+                if (!value || value.startsWith('--'))
+                    throw new Error(`${arg} requires a value`);
+                if (arg === '--extension-dir')
+                    extensionDir = value;
+                else {
+                    const key = { '--source-dir': 'sourceDir', '--config-dir': 'configDir', '--agent': 'agent' }[arg];
+                    options[key] = value;
+                }
+            }
+            else if (arg === '--link' || arg === '--force' || arg === '--dry-run') {
+                const key = { '--link': 'link', '--force': 'force', '--dry-run': 'dryRun' }[arg];
+                options[key] = true;
+            }
+            else if (arg === '--skip-tools' || (upgrade && arg === '--check')) {
+                continue;
+            }
+            else {
+                throw new Error(`unknown option: ${arg}`);
+            }
         }
-        else if (arg === '--link' || arg === '--force' || arg === '--dry-run') {
-            const key = { '--link': 'link', '--force': 'force', '--dry-run': 'dryRun' }[arg];
-            options[key] = true;
+        if (!options.agent || !['opencode', 'deveco', 'vscode'].includes(options.agent)) {
+            throw new Error(`unsupported agent: ${options.agent}; choose opencode, deveco or vscode`);
         }
-        else {
-            throw new Error(`unknown option: ${arg}`);
+        if (options.agent !== 'vscode' && extensionDir)
+            throw new Error('--extension-dir requires --agent vscode');
+        if (options.agent === 'vscode' && options.configDir)
+            throw new Error('--config-dir is not used for VS Code; use --extension-dir');
+        options.configDir ??= process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
+        if (checkOnly) {
+            const installation = options.agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : inspectInstallation(options.configDir);
+            console.log(`definitions ${installation.status}: ${installation.summary}`);
+            for (const item of inspectToolchain(packageRoot))
+                console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}`);
+        }
+        else if (!skipTools)
+            installToolchain(packageRoot, { dryRun: options.dryRun, force: options.force });
+        else if (!explicitSource && !options.dryRun)
+            console.log(`Skipped managed CLI installation (${Object.keys(loadToolchain(packageRoot).tools).join(', ')}).`);
+        if (!checkOnly) {
+            if (options.agent === 'vscode')
+                installVSCode({ sourceDir: options.sourceDir, extensionDir, dryRun: options.dryRun });
+            else
+                installOpenCode(options);
         }
     }
-    if (!options.agent || !['opencode', 'deveco'].includes(options.agent)) {
-        throw new Error(`unsupported agent: ${options.agent}; choose opencode or deveco`);
-    }
-    options.configDir ??= process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
-    installOpenCode(options);
 }
 catch (error) {
     console.error(`install-opencode: ${error instanceof Error ? error.message : String(error)}`);

package/dist/src/install-opencode.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
 function stat(file) {
     try {
         return fs.lstatSync(file);
@@ -28,6 +29,34 @@ function sameTree(source, destination) {
     }
     return left.isFile() && right.isFile() && fs.readFileSync(source).equals(fs.readFileSync(destination));
 }
+function digest(file) {
+    const info = fs.lstatSync(file);
+    const hash = crypto.createHash('sha256');
+    if (info.isSymbolicLink())
+        return hash.update(`link:${fs.readlinkSync(file)}`).digest('hex');
+    if (info.isFile())
+        return hash.update(fs.readFileSync(file)).digest('hex');
+    for (const name of fs.readdirSync(file).sort())
+        hash.update(name).update(digest(path.join(file, name)));
+    return hash.digest('hex');
+}
+export function inspectInstallation(configDir) {
+    const root = path.resolve(configDir);
+    const receipt = path.join(root, '.d2h-installation.json');
+    if (!fs.existsSync(receipt))
+        return { status: 'missing', summary: `installation record missing: ${receipt}` };
+    const value = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    if (value.schemaVersion !== 1 || !Array.isArray(value.entries))
+        throw new Error(`invalid installation record: ${receipt}`);
+    const changed = value.entries.filter(entry => {
+        if (!['skills', 'agents'].includes(entry.kind) || !/^[a-zA-Z0-9_.-]+$/.test(entry.name))
+            throw new Error(`invalid installation entry: ${entry.name}`);
+        const target = path.join(root, entry.kind, entry.name);
+        return !stat(target) || digest(target) !== entry.digest;
+    }).map(entry => `${entry.kind}/${entry.name}`);
+    return { status: changed.length ? 'failed' : 'passed', packageVersion: value.packageVersion, agent: value.agent,
+        summary: changed.length ? `changed or missing: ${changed.join(', ')}` : `${value.entries.length} installed definitions verified` };
+}
 function contains(parent, child) {
     const relative = path.relative(parent, child);
     return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
@@ -127,6 +156,21 @@ export function installOpenCode({ sourceDir, configDir, agent = 'opencode', link
     }
     const skills = entries.filter(entry => entry.kind === 'skills').length;
     const agents = entries.filter(entry => entry.kind === 'agents').length;
+    if (!dryRun) {
+        const receipt = path.join(configRoot, '.d2h-installation.json');
+        const temporary = path.join(configRoot, `.d2h-installation-${process.pid}.tmp`);
+        const packageFile = path.join(sourceRoot, 'package.json');
+        const packageVersion = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')).version : 'source';
+        const record = { schemaVersion: 1, packageVersion, agent, entries: entries.map(entry => ({ kind: entry.kind, name: entry.name, digest: digest(entry.destination) })) };
+        try {
+            fs.writeFileSync(temporary, JSON.stringify(record, null, 2) + '\n');
+            fs.renameSync(temporary, receipt);
+        }
+        finally {
+            if (fs.existsSync(temporary))
+                fs.rmSync(temporary);
+        }
+    }
     log(`${application} installation ${dryRun ? 'preview' : 'complete'}: ${skills} skill(s), ${agents} agent(s).`);
     log(`Config directory: ${configRoot}`);
     if (!dryRun)

package/dist/src/install-vscode.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const extensionPrefix = 'huaweideveloperserviceplatform.harmonyosdevassistantforvscode-';
+const modeLabel = '安卓转鸿蒙';
+function digest(file) {
+    const hash = crypto.createHash('sha256');
+    const info = fs.lstatSync(file);
+    if (info.isFile())
+        return hash.update(fs.readFileSync(file)).digest('hex');
+    for (const name of fs.readdirSync(file).sort())
+        hash.update(name).update(digest(path.join(file, name)));
+    return hash.digest('hex');
+}
+function inside(root, target) {
+    const relative = path.relative(root, target);
+    return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function assertSafeDestination(root, target) {
+    if (!inside(root, target))
+        throw new Error(`VS Code extension path escaped its root: ${target}`);
+    let parent = path.dirname(target);
+    while (inside(root, parent)) {
+        if (fs.existsSync(parent) && fs.lstatSync(parent).isSymbolicLink())
+            throw new Error(`refusing linked extension parent: ${parent}`);
+        parent = path.dirname(parent);
+    }
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+        throw new Error(`refusing linked extension target: ${target}`);
+}
+export function locateVSCodeExtension(extensionDir, home = os.homedir()) {
+    if (extensionDir)
+        return path.resolve(extensionDir);
+    const extensions = path.join(home, '.vscode', 'extensions');
+    if (!fs.existsSync(extensions))
+        throw new Error(`VS Code extensions directory not found: ${extensions}`);
+    const candidates = fs.readdirSync(extensions).filter(name => name.toLowerCase().startsWith(extensionPrefix))
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    if (!candidates.length)
+        throw new Error('HarmonyOS Dev Assistant VS Code extension is not installed');
+    return path.join(extensions, candidates[0]);
+}
+function validatedRoot(extensionDir) {
+    const root = fs.realpathSync(extensionDir);
+    const metadata = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (String(metadata.name).toLowerCase() !== 'harmonyosdevassistantforvscode' ||
+        String(metadata.publisher).toLowerCase() !== 'huaweideveloperserviceplatform') {
+        throw new Error(`not the HarmonyOS Dev Assistant VS Code extension: ${root}`);
+    }
+    return root;
+}
+function activeBundle(root, bundleCacheRoot = path.join(os.homedir(), '.harmonybot', 'opencode-bundle', 'vscode')) {
+    const hashFile = path.join(root, 'resources', 'opencode', '.bundle-hash');
+    const hash = fs.readFileSync(hashFile, 'utf8').trim();
+    if (!/^[a-f0-9]{16}$/i.test(hash))
+        throw new Error(`invalid VS Code OpenCode bundle hash: ${hashFile}`);
+    const bundle = path.join(bundleCacheRoot, hash);
+    if (!fs.existsSync(path.join(bundle, '.bundle-complete')) || !fs.existsSync(path.join(bundle, 'opencode.json'))) {
+        throw new Error(`VS Code OpenCode bundle is not extracted: ${bundle}; start the extension once before installing D2H`);
+    }
+    return fs.realpathSync(bundle);
+}
+export function updateD2HModeLabel(source) {
+    const map = /\{"harmonyos-multi-device"[^{}]{0,1000}"hmos-library-adapter-fast"[^{}]{0,300}\}/g;
+    const matches = [...source.matchAll(map)];
+    if (matches.length !== 1)
+        throw new Error(`expected one VS Code mode map, found ${matches.length}`);
+    const original = matches[0][0];
+    const next = /(?:^|,)d2h:"[^"]*"/.test(original)
+        ? original.replace(/((?:^|,)d2h:)"[^"]*"/, `$1${JSON.stringify(modeLabel)}`)
+        : original.slice(0, -1) + `,d2h:${JSON.stringify(modeLabel)}}`;
+    return source.slice(0, matches[0].index) + next + source.slice(matches[0].index + original.length);
+}
+function updateConfig(source) {
+    const value = JSON.parse(source);
+    value.agent ??= {};
+    value.agent.d2h = { ...value.agent.d2h, description: modeLabel,
+        tools: { ...value.agent.d2h?.tools, read: true, write: true, edit: true },
+        permission: { ...value.agent.d2h?.permission, read: 'allow', edit: 'allow' } };
+    delete value.agent.d2h.permission.write;
+    value.plugin ??= [];
+    if (!Array.isArray(value.plugin))
+        throw new Error('opencode plugin list must be an array');
+    if (!value.plugin.includes('./plugin/d2h'))
+        value.plugin.push('./plugin/d2h');
+    return JSON.stringify(value, null, 2) + '\n';
+}
+function copyWithBackup(source, destination, backupRoot, root) {
+    if (!inside(root, destination) || !inside(root, backupRoot))
+        throw new Error('VS Code extension path escaped its root');
+    if (fs.existsSync(destination) && digest(source) === digest(destination))
+        return false;
+    if (fs.existsSync(destination)) {
+        if (fs.lstatSync(destination).isSymbolicLink())
+            throw new Error(`refusing linked extension path: ${destination}`);
+        const backup = path.join(backupRoot, path.relative(root, destination));
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        fs.renameSync(destination, backup);
+        try {
+            fs.cpSync(source, destination, { recursive: fs.statSync(source).isDirectory() });
+        }
+        catch (error) {
+            fs.renameSync(backup, destination);
+            throw error;
+        }
+    }
+    else {
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.cpSync(source, destination, { recursive: fs.statSync(source).isDirectory() });
+    }
+    return true;
+}
+export function installVSCode({ sourceDir, extensionDir, bundleCacheRoot, dryRun = false, log = console.log }) {
+    const sourceRoot = fs.realpathSync(sourceDir);
+    const root = validatedRoot(locateVSCodeExtension(extensionDir));
+    const bundle = activeBundle(root, bundleCacheRoot);
+    const pluginRoot = path.join(root, 'resources', 'opencode', 'plugin', 'd2h');
+    const configFile = path.join(root, 'resources', 'opencode', 'opencode.json');
+    const bundleConfigFile = path.join(bundle, 'opencode.json');
+    const distFiles = ['dist/extension.js', 'dist/webview/main.js'];
+    const patches = [
+        { file: configFile, content: updateConfig(fs.readFileSync(configFile, 'utf8')) },
+        ...distFiles.map(name => ({ file: path.join(root, name), content: updateD2HModeLabel(fs.readFileSync(path.join(root, name), 'utf8')) })),
+    ];
+    const copies = [
+        { source: path.join(sourceRoot, 'skills'), destination: path.join(pluginRoot, 'skills') },
+        { source: path.join(sourceRoot, 'agents'), destination: path.join(pluginRoot, 'agents') },
+        { source: path.join(sourceRoot, 'AGENTS.md'), destination: path.join(pluginRoot, 'AGENTS.md') },
+        { source: path.join(sourceRoot, 'opencode', 'vscode-d2h-plugin.mjs'), destination: path.join(pluginRoot, 'src', 'index.js') },
+        { source: path.join(sourceRoot, 'opencode', 'vscode-d2h-package.json'), destination: path.join(pluginRoot, 'package.json') },
+    ];
+    const bundleCopies = copies.map(entry => ({ source: entry.source,
+        destination: path.join(bundle, 'plugin', 'd2h', path.relative(pluginRoot, entry.destination)) }));
+    const bundleConfig = updateConfig(fs.readFileSync(bundleConfigFile, 'utf8'));
+    for (const entry of copies)
+        if (!fs.existsSync(entry.source))
+            throw new Error(`missing D2H source: ${entry.source}`);
+    for (const target of [...copies.map(entry => entry.destination), ...patches.map(entry => entry.file)])
+        assertSafeDestination(root, target);
+    for (const target of [...bundleCopies.map(entry => entry.destination), bundleConfigFile])
+        assertSafeDestination(bundle, target);
+    if (dryRun) {
+        for (const entry of copies)
+            log(`would copy ${entry.source} -> ${entry.destination}`);
+        for (const entry of patches)
+            log(`would update ${entry.file}`);
+        for (const entry of bundleCopies)
+            log(`would copy ${entry.source} -> ${entry.destination}`);
+        log(`would update ${bundleConfigFile}`);
+        return { extensionRoot: root, changed: false };
+    }
+    if (!/^name: d2h\r?$/m.test(fs.readFileSync(path.join(sourceRoot, 'agents', 'd2h.md'), 'utf8'))) {
+        throw new Error('d2h.md frontmatter name is missing');
+    }
+    const backupRoot = fs.mkdtempSync(path.join(root, '.d2h-backup-'));
+    let changed = false;
+    for (const entry of copies)
+        changed = copyWithBackup(entry.source, entry.destination, backupRoot, root) || changed;
+    for (const entry of patches) {
+        if (fs.readFileSync(entry.file, 'utf8') === entry.content)
+            continue;
+        if (fs.lstatSync(entry.file).isSymbolicLink())
+            throw new Error(`refusing linked extension file: ${entry.file}`);
+        const backup = path.join(backupRoot, path.relative(root, entry.file));
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        fs.copyFileSync(entry.file, backup);
+        const temporary = `${entry.file}.d2h-${process.pid}.tmp`;
+        fs.writeFileSync(temporary, entry.content);
+        fs.renameSync(temporary, entry.file);
+        changed = true;
+    }
+    const bundleBackupRoot = fs.mkdtempSync(path.join(bundle, '.d2h-backup-'));
+    for (const entry of bundleCopies)
+        changed = copyWithBackup(entry.source, entry.destination, bundleBackupRoot, bundle) || changed;
+    if (fs.readFileSync(bundleConfigFile, 'utf8') !== bundleConfig) {
+        const backup = path.join(bundleBackupRoot, 'opencode.json');
+        fs.copyFileSync(bundleConfigFile, backup);
+        const temporary = `${bundleConfigFile}.d2h-${process.pid}.tmp`;
+        fs.writeFileSync(temporary, bundleConfig);
+        fs.renameSync(temporary, bundleConfigFile);
+        changed = true;
+    }
+    if (fs.readdirSync(bundleBackupRoot).length === 0)
+        fs.rmdirSync(bundleBackupRoot);
+    const tracked = [...copies.map(entry => entry.destination), ...patches.map(entry => entry.file)];
+    const receipt = { schemaVersion: 1, packageVersion: JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8')).version,
+        files: tracked.map(file => ({ path: path.relative(root, file).replaceAll('\\', '/'), digest: digest(file) })) };
+    fs.writeFileSync(path.join(pluginRoot, '.d2h-installation.json'), JSON.stringify(receipt, null, 2) + '\n');
+    if (!changed)
+        fs.rmdirSync(backupRoot);
+    log(`VS Code D2H ${changed ? 'installed' : 'unchanged'} at ${root}; active bundle: ${bundle}${changed ? `; backup: ${backupRoot}` : ''}`);
+    return { extensionRoot: root, changed, backupRoot: changed ? backupRoot : undefined };
+}
+export function inspectVSCodeInstallation(extensionDir, bundleCacheRoot) {
+    const root = validatedRoot(locateVSCodeExtension(extensionDir));
+    const file = path.join(root, 'resources', 'opencode', 'plugin', 'd2h', '.d2h-installation.json');
+    if (!fs.existsSync(file))
+        return { status: 'missing', summary: `installation record missing: ${file}` };
+    const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (receipt.schemaVersion !== 1 || !Array.isArray(receipt.files))
+        throw new Error(`invalid VS Code installation record: ${file}`);
+    const changed = receipt.files.filter(entry => {
+        const target = path.resolve(root, entry.path);
+        return !inside(root, target) || !fs.existsSync(target) || digest(target) !== entry.digest;
+    }).map(entry => entry.path);
+    try {
+        const bundle = activeBundle(root, bundleCacheRoot);
+        const pluginRoot = path.join(root, 'resources', 'opencode', 'plugin', 'd2h');
+        for (const name of ['skills', 'agents', 'AGENTS.md', 'src/index.js', 'package.json']) {
+            const source = path.join(pluginRoot, name);
+            const target = path.join(bundle, 'plugin', 'd2h', name);
+            if (!fs.existsSync(target) || digest(source) !== digest(target))
+                changed.push(`bundle/plugin/d2h/${name}`);
+        }
+        const config = JSON.parse(fs.readFileSync(path.join(bundle, 'opencode.json'), 'utf8'));
+        if (!config.plugin?.includes('./plugin/d2h') || config.agent?.d2h?.description !== modeLabel) {
+            changed.push('bundle/opencode.json');
+        }
+    }
+    catch (error) {
+        changed.push(`active bundle: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { status: changed.length ? 'failed' : 'passed', packageVersion: receipt.packageVersion,
+        summary: changed.length ? `changed: ${changed.join(', ')}` : `${receipt.files.length} VS Code resources and active bundle verified` };
+}

package/dist/src/toolchain.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+export function loadToolchain(root) {
+    const value = JSON.parse(fs.readFileSync(path.join(root, 'skills', 'managing-d2h-toolchain', 'toolchain.json'), 'utf8'));
+    if (value?.schemaVersion !== 1 || !value.tools || Array.isArray(value.tools) || !Object.keys(value.tools).length ||
+        !value.node || !/^\d+\.\d+\.\d+$/.test(value.node.minimum) ||
+        !/^\d+\.\d+\.\d+$/.test(value.node.maximumExclusive))
+        throw new Error('invalid toolchain manifest');
+    for (const [name, tool] of Object.entries(value.tools)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name) || tool?.package !== `@harmonyos-arkts/${name}` ||
+            !/^\d+\.\d+\.\d+$/.test(tool.version) || !tool.capabilities ||
+            typeof tool.capabilities !== 'object' || Array.isArray(tool.capabilities) ||
+            !Object.keys(tool.capabilities).length || Object.entries(tool.capabilities).some(([capability, args]) => !/^[a-z][a-z0-9-]*$/.test(capability) || !Array.isArray(args) || !args.length ||
+            args.some(arg => typeof arg !== 'string' || !arg))) {
+            throw new Error(`invalid toolchain entry: ${name}`);
+        }
+    }
+    return value;
+}
+export const run = (command, args) => {
+    let executable = command;
+    let parameters = args;
+    if (process.platform === 'win32') {
+        const quote = (value) => `'${value.replaceAll("'", "''")}'`;
+        const binary = /^(npm|appgraph|droid2hmos)$/.test(command) ? `${command}.cmd` : command;
+        const script = `& ${[binary, ...args].map(quote).join(' ')}; exit $LASTEXITCODE`;
+        executable = 'powershell.exe';
+        parameters = ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
+    }
+    const result = spawnSync(executable, parameters, { encoding: 'utf8', windowsHide: true, timeout: 300000 });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '', error: result.error };
+};
+function version(output) { return output.match(/\b\d+\.\d+\.\d+\b/)?.[0] ?? null; }
+export function inspectTool(name, tool, runner = run) {
+    const current = runner(name, ['--version']);
+    const installedVersion = current.status === 0 ? version(`${current.stdout}\n${current.stderr}`) : null;
+    const capabilities = Object.fromEntries(Object.entries(tool.capabilities).map(([capability, args]) => {
+        const result = installedVersion ? runner(name, args) : null;
+        const output = `${result?.stdout ?? ''}\n${result?.stderr ?? ''}`;
+        const expectedCommand = capability === 'analyze-android' ? 'analyze' : capability === 'build-android' ? 'build' : capability;
+        return [capability, result?.status === 0 && output.includes(expectedCommand)];
+    }));
+    return { name, package: tool.package, expectedVersion: tool.version, installedVersion,
+        status: installedVersion === tool.version && Object.values(capabilities).every(Boolean) ? 'passed' : 'failed', capabilities };
+}
+export function inspectToolchain(root, runner = run) {
+    const manifest = loadToolchain(root);
+    return Object.entries(manifest.tools).map(([name, tool]) => inspectTool(name, tool, runner));
+}
+export function installToolchain(root, { dryRun = false, force = false, runner = run, log = console.log } = {}) {
+    const manifest = loadToolchain(root);
+    const before = Object.entries(manifest.tools).map(([name, tool]) => inspectTool(name, tool, runner));
+    const targets = force ? before : before.filter(item => item.status !== 'passed');
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const globalRoot = targets.length ? runner(npm, ['root', '--global']) : null;
+    if (targets.length && globalRoot?.status !== 0)
+        throw new Error(`cannot inspect global npm installation: ${globalRoot?.stderr ?? 'unknown error'}`);
+    for (const item of targets) {
+        const tool = manifest.tools[item.name];
+        const coordinate = `${tool.package}@${tool.version}`;
+        const linkedPath = path.join(globalRoot.stdout.trim(), ...tool.package.split('/'));
+        const linked = fs.existsSync(linkedPath) && fs.lstatSync(linkedPath).isSymbolicLink();
+        if (linked && !force) {
+            if (dryRun) {
+                log(`would preserve npm link ${tool.package} at ${linkedPath}; rerun with --force to replace it`);
+                continue;
+            }
+            throw new Error(`${tool.package} is an npm link at ${linkedPath}; rerun with --force to replace it or use --skip-tools.`);
+        }
+        if (dryRun) {
+            log(`would ${linked ? 'replace npm link with' : 'install'} ${coordinate}`);
+            continue;
+        }
+        const result = runner(npm, ['install', '--global', coordinate]);
+        if (result.status !== 0)
+            throw new Error(`failed to install ${coordinate}: ${result.stderr || result.error?.message}`);
+        if (linked && fs.existsSync(linkedPath) && fs.lstatSync(linkedPath).isSymbolicLink()) {
+            throw new Error(`${coordinate} installation completed but npm link remains at ${linkedPath}`);
+        }
+        const verified = inspectTool(item.name, tool, runner);
+        if (verified.status !== 'passed')
+            throw new Error(`${coordinate} installed but CLI version or capabilities failed verification`);
+        log(`installed and verified ${coordinate}`);
+    }
+    return before;
+}