@cloudcare/hvigor-ohos-plugin 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0-alpha.1] - 2026-09-11
+
+- Prepared the initial npm prerelease of the console/HiLog and cold-launch instrumentation plugin.
+
+## [0.1.0] - 2026-09-05
+
+- Added compiler instrumentation for automatic console/HiLog collection.
+- Added compiler instrumentation for cold-launch tracking.
+- Fixed cold-launch instrumentation to retry first-frame observation after `WindowStage.loadContent(...)` completes successfully.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Changzhou Guance Information Technology Co., Ltd.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,45 @@
+# Guance HarmonyOS Hvigor Plugin
+
+`@cloudcare/hvigor-ohos-plugin` is the build-time companion for `@guancecloud/ft_sdk`. It instruments direct `console.*` and `hilog.*` calls and injects cold-launch lifecycle tracking into a HAP module's `src/main/ets` sources. Runtime log collection remains controlled by `FTLoggerConfig.setEnableConsoleLog(true)` in `@guancecloud/ft_sdk`.
+
+## Install
+
+This is a Hvigor tool package, so declare it in the project-level `hvigor/hvigor-config.json5` rather than a module `oh-package.json5`:
+
+```json5
+{
+  "dependencies": {
+    "@cloudcare/hvigor-ohos-plugin": "0.1.0-alpha.1"
+  }
+}
+```
+
+For local development, a filesystem dependency is also supported:
+
+```json5
+{
+  "dependencies": {
+    "@cloudcare/hvigor-ohos-plugin": "file:../ft_hvigor_plugin"
+  }
+}
+```
+
+## Enable in a HAP module
+
+```ts
+import { hapTasks } from '@ohos/hvigor-ohos-plugin'
+import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin'
+
+export default {
+  system: hapTasks,
+  plugins: [ftConsoleLogPlugin()]
+}
+```
+
+The plugin preserves the original console/HiLog output and does not modify application files on disk. It injects cold-launch application initialization into Ability `onCreate()` methods, first-UIAbility creation into `UIAbility.onCreate()`, and first-frame observation into `UIAbility.onWindowStageCreate()`. Do not add manual cold-launch timing calls to application code.
+
+## Compatibility
+
+The `0.1.0-alpha.1` prerelease is verified with Node.js 18 or newer, Hvigor and `@ohos/hvigor-ohos-plugin` 6.23.5, and HarmonyOS SDK 6.0.2 (API 22). It supports `@guancecloud/ft_sdk` `0.1.17` and later releases.
+
+`@ohos/hvigor-ohos-plugin` is supplied by DevEco Studio's Hvigor runtime. `@guancecloud/ft_sdk` must still be declared as the application's runtime HAR dependency because the generated imports target that package.

package/hvigorCompile/ft-cold-launch-transform.ts

@@ -0,0 +1,368 @@
+/**
+ * Guance cold-launch compiler plugin.
+ *
+ * The plugin injects cold-launch boundaries into Ability lifecycle methods in
+ * the compiler's in-memory source. Application files are never modified.
+ */
+
+declare const require: {
+  main: {
+    require(moduleName: string): any;
+  };
+};
+
+type TypeScriptApi = any;
+type AbilityClassKind = 'stage' | 'ui' | 'other';
+
+interface CompilePluginContext {
+  share: {
+    projectConfig: {
+      etsLoaderPath: string;
+    };
+  };
+}
+
+interface SharedSourceTransformRegistry {
+  originalReadFile: (fileName: string, options?: any) => any;
+  buffer: any;
+  transforms: Map<string, (fileName: string, code: string) => string>;
+}
+
+interface ColdLaunchInjection {
+  position: number;
+  content: string;
+}
+
+const COLD_LAUNCH_BRIDGE_IMPORT = '@guancecloud/ft_sdk/Index';
+const COLD_LAUNCH_TRANSFORM_MARKER = '/* guance-cold-launch-transform:instrumented */';
+const SOURCE_TRANSFORM_REGISTRY_KEY = '__guanceHvigorSourceTransformRegistry';
+const TRANSFORM_ID = 'guance-cold-launch-transform';
+
+let registeredFileSystem: any = null;
+
+export function isApplicationArkTsSource(id: string): boolean {
+  const normalizedId = id.replace(/\\/g, '/');
+  return (normalizedId.endsWith('.ets') || normalizedId.endsWith('.ts')) &&
+    normalizedId.includes('/src/main/ets/') && !normalizedId.includes('/oh_modules/') &&
+    !normalizedId.includes('/ft_sdk/src/main/ets/');
+}
+
+function visit(ts: TypeScriptApi, node: any, visitor: (current: any) => void): void {
+  visitor(node);
+  ts.forEachChild(node, (child: any) => visit(ts, child, visitor));
+}
+
+function collectIdentifierNames(ts: TypeScriptApi, sourceFile: any): Set<string> {
+  const identifiers = new Set<string>();
+  visit(ts, sourceFile, (node: any) => {
+    if (ts.isIdentifier(node)) {
+      identifiers.add(node.text);
+    }
+  });
+  return identifiers;
+}
+
+function selectBridgeName(identifiers: Set<string>): string {
+  const baseName = '__ftColdLaunchBridge';
+  let bridgeName = baseName;
+  let suffix = 1;
+  while (identifiers.has(bridgeName)) {
+    bridgeName = `${baseName}${suffix}`;
+    suffix++;
+  }
+  return bridgeName;
+}
+
+function findImportInsertionOffset(ts: TypeScriptApi, sourceFile: any): number {
+  let offset = 0;
+  sourceFile.statements.forEach((statement: any) => {
+    if (ts.isImportDeclaration(statement)) {
+      offset = statement.end;
+    }
+  });
+  return offset;
+}
+
+function classifyAbilityBaseName(name: string): AbilityClassKind | null {
+  if (name === 'AbilityStage') {
+    return 'stage';
+  }
+  if (name === 'UIAbility') {
+    return 'ui';
+  }
+  if (name.endsWith('Ability') || name.endsWith('ExtensionAbility')) {
+    return 'other';
+  }
+  return null;
+}
+
+function collectAbilityBindings(ts: TypeScriptApi, sourceFile: any): Map<string, AbilityClassKind> {
+  const bindings = new Map<string, AbilityClassKind>();
+  sourceFile.statements.forEach((statement: any) => {
+    if (!ts.isImportDeclaration(statement) || !statement.moduleSpecifier ||
+      !ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) {
+      return;
+    }
+    const moduleName = statement.moduleSpecifier.text;
+    if (!moduleName.startsWith('@ohos.app.ability/') && moduleName !== '@kit.AbilityKit') {
+      return;
+    }
+    const importClause = statement.importClause;
+    if (importClause.name) {
+      const defaultKind = classifyAbilityBaseName(moduleName.substring(moduleName.lastIndexOf('.') + 1));
+      if (defaultKind) {
+        bindings.set(importClause.name.text, defaultKind);
+      }
+    }
+    if (!importClause.namedBindings || !ts.isNamedImports(importClause.namedBindings)) {
+      return;
+    }
+    importClause.namedBindings.elements.forEach((element: any) => {
+      const importedName = element.propertyName ? element.propertyName.text : element.name.text;
+      const kind = classifyAbilityBaseName(importedName);
+      if (kind) {
+        bindings.set(element.name.text, kind);
+      }
+    });
+  });
+  return bindings;
+}
+
+function classAbilityKind(ts: TypeScriptApi, classDeclaration: any,
+  abilityBindings: Map<string, AbilityClassKind>): AbilityClassKind | null {
+  if (!classDeclaration.heritageClauses) {
+    return null;
+  }
+  for (const clause of classDeclaration.heritageClauses) {
+    if (clause.token !== ts.SyntaxKind.ExtendsKeyword || clause.types.length === 0) {
+      continue;
+    }
+    const expression = clause.types[0].expression;
+    if (!ts.isIdentifier(expression)) {
+      continue;
+    }
+    return abilityBindings.get(expression.text) || classifyAbilityBaseName(expression.text);
+  }
+  return null;
+}
+
+function methodIndentation(code: string, method: any): string {
+  const methodStart = method.getStart();
+  const lineStart = code.lastIndexOf('\n', methodStart) + 1;
+  const match = code.slice(lineStart, methodStart).match(/^\s*/);
+  return (match ? match[0] : '') + '  ';
+}
+
+function classIndentation(code: string, classDeclaration: any): string {
+  const classStart = classDeclaration.getStart();
+  const lineStart = code.lastIndexOf('\n', classStart) + 1;
+  const match = code.slice(lineStart, classStart).match(/^\s*/);
+  return match ? match[0] : '';
+}
+
+function blockIndentation(code: string, block: any): string {
+  const blockStart = block.getStart();
+  const lineStart = code.lastIndexOf('\n', blockStart) + 1;
+  const match = code.slice(lineStart, blockStart).match(/^\s*/);
+  return (match ? match[0] : '') + '  ';
+}
+
+function collectWindowStageParameterNames(ts: TypeScriptApi, sourceFile: any, method: any): Set<string> {
+  const names = new Set<string>();
+  method.parameters.forEach((parameter: any) => {
+    if (!ts.isIdentifier(parameter.name)) {
+      return;
+    }
+    const typeText = parameter.type ? parameter.type.getText(sourceFile) : '';
+    if (parameter.name.text === 'windowStage' || typeText.includes('WindowStage')) {
+      names.add(parameter.name.text);
+    }
+  });
+  return names;
+}
+
+function createFirstFrameRetryInjections(ts: TypeScriptApi, sourceFile: any, code: string,
+  method: any, bridgeName: string, windowStageNames: Set<string>): ColdLaunchInjection[] {
+  const injections: ColdLaunchInjection[] = [];
+  visit(ts, method.body, (node: any) => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) {
+      return;
+    }
+    const delegate = node.expression.expression;
+    if (!ts.isIdentifier(delegate) || !windowStageNames.has(delegate.text) ||
+      node.expression.name.text !== 'loadContent' || node.arguments.length === 0) {
+      return;
+    }
+    const windowStageName = delegate.text;
+    const callback = node.arguments[node.arguments.length - 1];
+    if ((!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) || !ts.isBlock(callback.body)) {
+      return;
+    }
+    const indentation = blockIndentation(code, callback.body);
+    const errorParameter = callback.parameters.length > 0 && ts.isIdentifier(callback.parameters[0].name)
+      ? callback.parameters[0].name.text : null;
+    const retry = `${bridgeName}.observeFirstFrame(${windowStageName});`;
+    const content = errorParameter === null
+      ? `\n${indentation}${retry}`
+      : `\n${indentation}if (!${errorParameter} || !${errorParameter}.code) {\n` +
+        `${indentation}  ${retry}\n${indentation}}`;
+    injections.push({ position: callback.body.getStart(sourceFile) + 1, content });
+  });
+  return injections;
+}
+
+function createColdLaunchInjections(ts: TypeScriptApi, sourceFile: any, code: string,
+  bridgeName: string): ColdLaunchInjection[] {
+  const injections: ColdLaunchInjection[] = [];
+  const abilityBindings = collectAbilityBindings(ts, sourceFile);
+  visit(ts, sourceFile, (node: any) => {
+    if (!ts.isClassDeclaration(node)) {
+      return;
+    }
+    const kind = classAbilityKind(ts, node, abilityBindings);
+    if (!kind) {
+      return;
+    }
+    let hasOnCreate = false;
+    node.members.forEach((member: any) => {
+      if (!ts.isMethodDeclaration(member) || !member.body || !member.name || !ts.isIdentifier(member.name)) {
+        return;
+      }
+      const indentation = methodIndentation(code, member);
+      const position = member.body.getStart(sourceFile) + 1;
+      if (member.name.text === 'onCreate') {
+        hasOnCreate = true;
+        let content = `\n${indentation}${bridgeName}.recordApplicationInit(this.context);`;
+        if (kind === 'ui') {
+          content += `\n${indentation}${bridgeName}.recordFirstUIAbilityCreate();`;
+        }
+        injections.push({ position, content });
+        return;
+      }
+      if (kind !== 'ui' || member.name.text !== 'onWindowStageCreate' || member.parameters.length === 0) {
+        return;
+      }
+      const windowStageParameter = member.parameters[0];
+      if (!ts.isIdentifier(windowStageParameter.name)) {
+        return;
+      }
+      const windowStageName = windowStageParameter.name.text;
+      injections.push({
+        position,
+        content: `\n${indentation}${bridgeName}.observeFirstFrame(${windowStageName});`
+      });
+    });
+    if (kind === 'ui') {
+      node.members.forEach((member: any) => {
+        if (!ts.isMethodDeclaration(member) || !member.body) {
+          return;
+        }
+        const windowStageNames = collectWindowStageParameterNames(ts, sourceFile, member);
+        if (windowStageNames.size > 0) {
+          injections.push(...createFirstFrameRetryInjections(
+            ts, sourceFile, code, member, bridgeName, windowStageNames));
+        }
+      });
+    }
+    if (kind === 'stage' && !hasOnCreate) {
+      const indentation = classIndentation(code, node);
+      injections.push({
+        position: node.end - 1,
+        content: `\n${indentation}  onCreate(): void {\n` +
+          `${indentation}    ${bridgeName}.recordApplicationInit(this.context);\n` +
+          `${indentation}  }\n`
+      });
+    }
+  });
+  return injections;
+}
+
+function applyColdLaunchInjections(code: string, injections: ColdLaunchInjection[]): string {
+  const contentsByPosition = new Map<number, string[]>();
+  injections.forEach((injection: ColdLaunchInjection) => {
+    const contents = contentsByPosition.get(injection.position) || [];
+    contents.push(injection.content);
+    contentsByPosition.set(injection.position, contents);
+  });
+  const positions = Array.from(contentsByPosition.keys()).sort((left: number, right: number) => right - left);
+  let transformedCode = code;
+  positions.forEach((position: number) => {
+    const content = (contentsByPosition.get(position) || []).join('');
+    transformedCode = transformedCode.slice(0, position) + content + transformedCode.slice(position);
+  });
+  return transformedCode;
+}
+
+function rewriteSource(ts: TypeScriptApi, id: string, code: string): string {
+  if (!isApplicationArkTsSource(id) || code.includes(COLD_LAUNCH_TRANSFORM_MARKER)) {
+    return code;
+  }
+  const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const bridgeName = selectBridgeName(collectIdentifierNames(ts, sourceFile));
+  const injections = createColdLaunchInjections(ts, sourceFile, code, bridgeName);
+  if (injections.length === 0) {
+    return code;
+  }
+  const insertionOffset = findImportInsertionOffset(ts, sourceFile);
+  const bridgeImport = `\n${COLD_LAUNCH_TRANSFORM_MARKER}\n` +
+    `import { FTColdLaunchBridge as ${bridgeName} } from '${COLD_LAUNCH_BRIDGE_IMPORT}';\n`;
+  const transformedCode = applyColdLaunchInjections(code, injections);
+  return transformedCode.slice(0, insertionOffset) + bridgeImport + transformedCode.slice(insertionOffset);
+}
+
+function installSourceReader(context: CompilePluginContext): void {
+  if (registeredFileSystem !== null) {
+    return;
+  }
+  const typeScriptPath = `${context.share.projectConfig.etsLoaderPath}/node_modules/typescript`;
+  const ts = require.main.require(typeScriptPath);
+  const fileSystem = require.main.require('fs');
+  let registry = fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (!registry) {
+    registry = {
+      originalReadFile: fileSystem.readFileSync as (fileName: string, options?: any) => any,
+      buffer: require.main.require('buffer'),
+      transforms: new Map<string, (fileName: string, code: string) => string>()
+    };
+    fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] = registry;
+    fileSystem.readFileSync = (fileName: string, options?: any): any => {
+      const content = registry!.originalReadFile(fileName, options);
+      if (typeof fileName !== 'string' || !isApplicationArkTsSource(fileName)) {
+        return content;
+      }
+      let transformedCode = typeof content === 'string' ? content : content.toString();
+      registry!.transforms.forEach((transform: (id: string, code: string) => string) => {
+        transformedCode = transform(fileName, transformedCode);
+      });
+      return typeof content === 'string' ? transformedCode : registry!.buffer.Buffer.from(transformedCode);
+    };
+  }
+  registry.transforms.set(TRANSFORM_ID, (fileName: string, code: string) => rewriteSource(ts, fileName, code));
+  registeredFileSystem = fileSystem;
+}
+
+function restoreSourceReader(): void {
+  if (registeredFileSystem === null) {
+    return;
+  }
+  const registry = registeredFileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (registry) {
+    registry.transforms.delete(TRANSFORM_ID);
+    if (registry.transforms.size === 0) {
+      registeredFileSystem.readFileSync = registry.originalReadFile;
+      delete registeredFileSystem[SOURCE_TRANSFORM_REGISTRY_KEY];
+    }
+  }
+  registeredFileSystem = null;
+}
+
+export default {
+  name: 'guance-cold-launch-transform',
+  order: 'first',
+  buildStart(this: CompilePluginContext): void {
+    installSourceReader(this);
+  },
+  buildEnd(): void {
+    restoreSourceReader();
+  }
+};

package/hvigorCompile/ft-console-log-transform.ts

@@ -0,0 +1,339 @@
+/**
+ * Guance console-log compiler plugin.
+ *
+ * Hvigor creates the ArkTS type-checking program before normal Rollup
+ * transform hooks run. This plugin therefore rewrites only the in-memory
+ * application source read by that program. Application files on disk are
+ * never changed.
+ */
+
+declare const require: {
+  main: {
+    require(moduleName: string): any;
+  };
+};
+
+type TypeScriptApi = any;
+
+interface CompilePluginContext {
+  share: {
+    projectConfig: {
+      etsLoaderPath: string;
+    };
+  };
+}
+
+interface SharedSourceTransformRegistry {
+  originalReadFile: (fileName: string, options?: any) => any;
+  buffer: any;
+  transforms: Map<string, (fileName: string, code: string) => string>;
+}
+
+interface TransformCandidate {
+  start: number;
+  end: number;
+  calleeEnd: number;
+  delegate: string;
+  level: string;
+  source: 'console' | 'hilog';
+  callArguments: SourceRange[];
+}
+
+interface SourceRange {
+  start: number;
+  end: number;
+}
+
+const HILOG_MODULES: string[] = ['@ohos.hilog', '@kit.PerformanceAnalysisKit'];
+const CONSOLE_LEVELS: string[] = ['log', 'debug', 'info', 'warn', 'error', 'trace'];
+const HILOG_LEVELS: string[] = ['debug', 'info', 'warn', 'error', 'fatal'];
+const BRIDGE_IMPORT = '@guancecloud/ft_sdk/Index';
+// Hvigor can read a source file through more than one compiler layer in an
+// incremental/daemon build. Keep a marker in the in-memory result so a later
+// reader does not wrap the original console/HiLog call a second time.
+const TRANSFORM_MARKER = '/* guance-console-log-transform:instrumented */';
+const SOURCE_TRANSFORM_REGISTRY_KEY = '__guanceHvigorSourceTransformRegistry';
+const TRANSFORM_ID = 'guance-console-log-transform';
+
+let registeredFileSystem: any = null;
+
+export function isApplicationArkTsSource(id: string): boolean {
+  const normalizedId = id.replace(/\\/g, '/');
+  return (normalizedId.endsWith('.ets') || normalizedId.endsWith('.ts')) &&
+    normalizedId.includes('/src/main/ets/') && !normalizedId.includes('/oh_modules/') &&
+    !normalizedId.includes('/ft_sdk/src/main/ets/');
+}
+
+function visit(ts: TypeScriptApi, node: any, visitor: (current: any) => void): void {
+  visitor(node);
+  ts.forEachChild(node, (child: any) => visit(ts, child, visitor));
+}
+
+function collectIdentifierNames(ts: TypeScriptApi, sourceFile: any): Set<string> {
+  const identifiers = new Set<string>();
+  visit(ts, sourceFile, (node: any) => {
+    if (ts.isIdentifier(node)) {
+      identifiers.add(node.text);
+    }
+  });
+  return identifiers;
+}
+
+function isNameDeclaredOutsideImports(ts: TypeScriptApi, sourceFile: any, name: string): boolean {
+  let declared = false;
+  visit(ts, sourceFile, (node: any) => {
+    if (declared || ts.isImportDeclaration(node)) {
+      return;
+    }
+    if (ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) ||
+      ts.isParameter(node) || ts.isEnumDeclaration(node) || ts.isInterfaceDeclaration(node) ||
+      ts.isTypeAliasDeclaration(node)) {
+      const declarationName = node.name;
+      if (declarationName && ts.isIdentifier(declarationName) && declarationName.text === name) {
+        declared = true;
+      }
+    }
+  });
+  return declared;
+}
+
+function collectHiLogBindings(ts: TypeScriptApi, sourceFile: any): Set<string> {
+  const bindings = new Set<string>();
+  sourceFile.statements.forEach((statement: any) => {
+    if (!ts.isImportDeclaration(statement) || !statement.moduleSpecifier ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      !HILOG_MODULES.includes(statement.moduleSpecifier.text) || !statement.importClause) {
+      return;
+    }
+
+    const importClause = statement.importClause;
+    if (importClause.name) {
+      bindings.add(importClause.name.text);
+    }
+    if (!importClause.namedBindings) {
+      return;
+    }
+    if (ts.isNamespaceImport(importClause.namedBindings)) {
+      bindings.add(importClause.namedBindings.name.text);
+      return;
+    }
+    importClause.namedBindings.elements.forEach((element: any) => {
+      const importedName = element.propertyName ? element.propertyName.text : element.name.text;
+      if (importedName === 'hilog') {
+        bindings.add(element.name.text);
+      }
+    });
+  });
+  return bindings;
+}
+
+function collectCandidates(ts: TypeScriptApi, sourceFile: any, code: string): TransformCandidate[] {
+  const candidates: TransformCandidate[] = [];
+  const hiLogBindings = collectHiLogBindings(ts, sourceFile);
+  const consoleIsShadowed = isNameDeclaredOutsideImports(ts, sourceFile, 'console');
+  const shadowedHiLogBindings = new Set<string>();
+  hiLogBindings.forEach((binding: string) => {
+    if (isNameDeclaredOutsideImports(ts, sourceFile, binding)) {
+      shadowedHiLogBindings.add(binding);
+    }
+  });
+
+  visit(ts, sourceFile, (node: any) => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) {
+      return;
+    }
+    const delegate = node.expression.expression;
+    if (!ts.isIdentifier(delegate)) {
+      return;
+    }
+    const delegateName = delegate.text;
+    const level = node.expression.name.text;
+    const start = node.getStart(sourceFile);
+    const end = node.end;
+    const calleeEnd = node.expression.end;
+    if (start < 0 || end > code.length || calleeEnd < start || calleeEnd > end) {
+      return;
+    }
+
+    const callArguments: SourceRange[] = node.arguments.map((argument: any) => ({
+      start: argument.getStart(sourceFile),
+      end: argument.end
+    }));
+    if (delegateName === 'console' && !consoleIsShadowed && CONSOLE_LEVELS.includes(level)) {
+      candidates.push({ start, end, calleeEnd, delegate: delegateName, level, source: 'console', callArguments });
+      return;
+    }
+    if (hiLogBindings.has(delegateName) && !shadowedHiLogBindings.has(delegateName) &&
+      HILOG_LEVELS.includes(level) && callArguments.length >= 3) {
+      candidates.push({ start, end, calleeEnd, delegate: delegateName, level, source: 'hilog', callArguments });
+    }
+  });
+  return candidates;
+}
+
+function selectBridgeName(identifiers: Set<string>): string {
+  const baseName = '__ftConsoleLogBridge';
+  let bridgeName = baseName;
+  let suffix = 1;
+  while (identifiers.has(bridgeName)) {
+    bridgeName = `${baseName}${suffix}`;
+    suffix++;
+  }
+  return bridgeName;
+}
+
+function isNestedIn(candidate: TransformCandidate, parent: TransformCandidate): boolean {
+  return parent !== candidate && parent.start <= candidate.start && parent.end >= candidate.end;
+}
+
+function renderCandidates(code: string, candidates: TransformCandidate[], bridgeName: string,
+  rangeStart: number, rangeEnd: number): string {
+  const inRange = candidates.filter((candidate: TransformCandidate) =>
+    candidate.start >= rangeStart && candidate.end <= rangeEnd);
+  const directCandidates = inRange.filter((candidate: TransformCandidate) =>
+    !inRange.some((parent: TransformCandidate) => isNestedIn(candidate, parent)));
+  if (directCandidates.length === 0) {
+    return code.slice(rangeStart, rangeEnd);
+  }
+
+  const descending = directCandidates.sort((left: TransformCandidate, right: TransformCandidate) =>
+    right.start - left.start);
+  let cursor = rangeEnd;
+  let output = '';
+  for (const candidate of descending) {
+    output = renderCandidate(code, candidates, bridgeName, candidate) + code.slice(candidate.end, cursor) + output;
+    cursor = candidate.start;
+  }
+  return code.slice(rangeStart, cursor) + output;
+}
+
+function renderCandidate(code: string, candidates: TransformCandidate[], bridgeName: string,
+  candidate: TransformCandidate): string {
+  const renderedArguments = candidate.callArguments.map((argument: SourceRange) =>
+    renderCandidates(code, candidates, bridgeName, argument.start, argument.end));
+  if (candidate.source === 'console') {
+    const argumentNames = renderedArguments.map((_argument: string, index: number) => `__ftConsoleArg${index}`);
+    const parameterDeclarations = argumentNames.map((name: string) => `${name}: Object`).join(', ');
+    const originalCallArguments = argumentNames.map((name: string) => `${name} as string`);
+    const originalCall = `${candidate.delegate}.${candidate.level}(${originalCallArguments.join(', ')})`;
+    const captureArguments = argumentNames.length > 0 ? `, ${argumentNames.join(', ')}` : '';
+    return `((${parameterDeclarations}): void => ${bridgeName}.console('${candidate.level}', ` +
+      `(): void => ${originalCall}${captureArguments}))(${renderedArguments.join(', ')})`;
+  }
+
+  const argumentNames = renderedArguments.map((_argument: string, index: number) => {
+    if (index === 0) {
+      return '__ftHiLogDomain';
+    }
+    if (index === 1) {
+      return '__ftHiLogTag';
+    }
+    if (index === 2) {
+      return '__ftHiLogFormat';
+    }
+    return `__ftHiLogArg${index - 3}`;
+  });
+  const parameterDeclarations = argumentNames.map((name: string, index: number) => {
+    if (index === 0) {
+      return `${name}: number`;
+    }
+    if (index === 1 || index === 2) {
+      return `${name}: string`;
+    }
+    return `${name}: Object`;
+  }).join(', ');
+  const originalCall = `${candidate.delegate}.${candidate.level}(${argumentNames.join(', ')})`;
+  const captureArguments = argumentNames.length > 3 ? `, ${argumentNames.slice(3).join(', ')}` : '';
+  return `((${parameterDeclarations}): void => ${bridgeName}.hilog('${candidate.level}', ` +
+    `${argumentNames[0]}, ${argumentNames[1]}, ${argumentNames[2]}, (): void => ${originalCall}` +
+    `${captureArguments}))(${renderedArguments.join(', ')})`;
+}
+
+function findImportInsertionOffset(ts: TypeScriptApi, sourceFile: any): number {
+  let offset = 0;
+  sourceFile.statements.forEach((statement: any) => {
+    if (ts.isImportDeclaration(statement)) {
+      offset = statement.end;
+    }
+  });
+  return offset;
+}
+
+function rewriteSource(ts: TypeScriptApi, id: string, code: string): string {
+  if (!isApplicationArkTsSource(id) || code.includes(TRANSFORM_MARKER)) {
+    return code;
+  }
+  const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const candidates = collectCandidates(ts, sourceFile, code);
+  if (candidates.length === 0) {
+    return code;
+  }
+
+  const bridgeName = selectBridgeName(collectIdentifierNames(ts, sourceFile));
+  const transformedCode = renderCandidates(code, candidates, bridgeName, 0, code.length);
+  const insertionOffset = findImportInsertionOffset(ts, sourceFile);
+  const transformedInsertionOffset = renderCandidates(code, candidates, bridgeName, 0, insertionOffset).length;
+  const bridgeImport = `\n${TRANSFORM_MARKER}\n` +
+    `import { FTConsoleLogBridge as ${bridgeName} } from '${BRIDGE_IMPORT}';\n` +
+    `${bridgeName}.markCompilerPluginInstalled();\n`;
+  return transformedCode.slice(0, transformedInsertionOffset) + bridgeImport +
+    transformedCode.slice(transformedInsertionOffset);
+}
+
+function installSourceReader(context: CompilePluginContext): void {
+  if (registeredFileSystem !== null) {
+    return;
+  }
+
+  const typeScriptPath = `${context.share.projectConfig.etsLoaderPath}/node_modules/typescript`;
+  const ts = require.main.require(typeScriptPath);
+  const fileSystem = require.main.require('fs');
+  let registry = fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (!registry) {
+    registry = {
+      originalReadFile: fileSystem.readFileSync as (fileName: string, options?: any) => any,
+      buffer: require.main.require('buffer'),
+      transforms: new Map<string, (fileName: string, code: string) => string>()
+    };
+    fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] = registry;
+    fileSystem.readFileSync = (fileName: string, options?: any): any => {
+      const content = registry!.originalReadFile(fileName, options);
+      if (typeof fileName !== 'string' || !isApplicationArkTsSource(fileName)) {
+        return content;
+      }
+      let transformedCode = typeof content === 'string' ? content : content.toString();
+      registry!.transforms.forEach((transform: (id: string, code: string) => string) => {
+        transformedCode = transform(fileName, transformedCode);
+      });
+      return typeof content === 'string' ? transformedCode : registry!.buffer.Buffer.from(transformedCode);
+    };
+  }
+  registry.transforms.set(TRANSFORM_ID, (fileName: string, code: string) => rewriteSource(ts, fileName, code));
+  registeredFileSystem = fileSystem;
+}
+
+function restoreSourceReader(): void {
+  if (registeredFileSystem === null) {
+    return;
+  }
+  const registry = registeredFileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (registry) {
+    registry.transforms.delete(TRANSFORM_ID);
+    if (registry.transforms.size === 0) {
+      registeredFileSystem.readFileSync = registry.originalReadFile;
+      delete registeredFileSystem[SOURCE_TRANSFORM_REGISTRY_KEY];
+    }
+  }
+  registeredFileSystem = null;
+}
+
+export default {
+  name: 'guance-console-log-transform',
+  order: 'first',
+  buildStart(this: CompilePluginContext): void {
+    installSourceReader(this);
+  },
+  buildEnd(): void {
+    restoreSourceReader();
+  }
+};

package/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const path = require('path');
+const { OhosPluginId } = require('@ohos/hvigor-ohos-plugin');
+
+/**
+ * Returns the HAP-level Hvigor plugin used to instrument console/HiLog calls
+ * and cold-launch lifecycle boundaries before ArkTS compilation.
+ *
+ * This package intentionally contains build tooling only. Applications still
+ * need @guancecloud/ft_sdk at runtime to receive the instrumented log calls.
+ */
+function ftConsoleLogPlugin() {
+  return {
+    pluginId: 'guance-console-log-compiler',
+    apply(node) {
+      const hapContext = node.getContext(OhosPluginId.OHOS_HAP_PLUGIN);
+      const consoleLogTransformPath = path.join(__dirname, 'hvigorCompile', 'ft-console-log-transform.ts');
+      const coldLaunchTransformPath = path.join(__dirname, 'hvigorCompile', 'ft-cold-launch-transform.ts');
+      hapContext.loadCompilePlugin(consoleLogTransformPath);
+      hapContext.loadCompilePlugin(coldLaunchTransformPath);
+    }
+  };
+}
+
+module.exports = {
+  ftConsoleLogPlugin
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@cloudcare/hvigor-ohos-plugin",
+  "version": "0.1.0-alpha.1",
+  "description": "Guance HarmonyOS Hvigor plugin for automatic console, HiLog, and cold-launch collection.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "hvigorCompile/ft-console-log-transform.ts",
+    "hvigorCompile/ft-cold-launch-transform.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "author": "Guance",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@guancecloud/ft_sdk": ">=0.1.17"
+  },
+  "peerDependenciesMeta": {
+    "@guancecloud/ft_sdk": {
+      "optional": true
+    }
+  }
+}