@oniroproject/oniro-app 0.10.0 → 0.11.0

package/README.md

@@ -103,7 +103,7 @@ All flags are required except where a default is shown (non-interactive). On suc
 | `--bundle <bundleName>` | Bundle name in reverse-DNS form, e.g. `com.example.myapp`. |
 | `--location <dir>` | Parent directory the new project folder is created in. |
 | `--sdk <api>` | Target SDK API level (e.g. `18`, `20`). |
-| `--template <id>` | Template id (default `EmptyAbility`). |
+| `--template <id>` | Template id (default `EmptyAbility`; `HarmonyOSApp` targets HarmonyOS). |
 | `--module <name>` | Module folder name (defaults to the template default, usually `entry`). |
 | `--overwrite` | Replace the destination if it already exists. |
 
@@ -113,6 +113,17 @@ All flags are required except where a default is shown (non-interactive). On suc
 | --- | --- |
 | `templates list [--json]` | List the project templates shipped with the CLI. |
 
+#### `auth` — sign in to a Huawei developer account
+
+Only needed for HarmonyOS signing; see [HarmonyOS apps](#harmonyos-apps).
+
+| Command | Description |
+| --- | --- |
+| `auth login [--timeout <s>]` | Sign in via the browser (default timeout 600s). |
+| `auth logout` | Delete the locally stored token. |
+| `auth status [--json]` | Show the signed-in account; exits non-zero when signed out. |
+| `auth team list [--json]` | List AGC teams. |
+
 #### `sign` — generate signing keys, certs, and `signingConfigs`
 
 `sign [project-dir]` (defaults to the current directory). Requires `java` on `PATH`. Rewrites only the `signingConfigs` block of `build-profile.json5` (other keys are preserved). The generated profile uses the SDK's built-in development cert (`issuer=pki_internal`) and its validity window — **dev/local builds only, not distribution.** See [Signing apps that need system permissions](#signing-apps-that-need-system-permissions) for `--apl` / `--acls`.
@@ -123,6 +134,10 @@ All flags are required except where a default is shown (non-interactive). On suc
 | `--app-feature <feature>` | `hos_normal_app` or `hos_system_app`. Defaults follow `--apl`. |
 | `--acls <list>` | Comma-separated permissions to write into the profile's `acls.allowed-acls`. |
 | `--bootstrap` | No-op if signing material is already present; otherwise generate it. |
+| `--harmonyos` | Sign a HarmonyOS project via AppGallery Connect instead of the offline flow. See [HarmonyOS apps](#harmonyos-apps). |
+| `--team-id <id>` | With `--harmonyos`: AGC team to sign under. |
+| `--product <name>` | With `--harmonyos`: product to sign (default `default`). |
+| `--force` | With `--harmonyos`: regenerate even when the existing material is still valid. |
 | `--store-password <pwd>` / `--key-password <pwd>` | Keystore passwords (default `123456`, the SDK keystore password). |
 
 #### `build` — build the app via `hvigorw`
@@ -300,6 +315,9 @@ The CLI reads paths and URLs from environment variables. All are optional; defau
 | `ONIRO_EMULATOR_URL` | Latest `oniro_emulator.zip` | Emulator download URL |
 | `ONIRO_TMP_DIR` | `<install root>/.oniro-tmp` | Scratch directory for download/extract temporaries (see [Temporary space](#temporary-space)) |
 | `ONIRO_APPLICATION_CERT_PATH` | (unset) | External application-cert chain to use when signing system apps |
+| `ONIRO_HARMONYOS_SDK_PATH` | autodetected | HarmonyOS SDK: a DevEco Studio or HarmonyOS command-line-tools install, or its `sdk` directory |
+| `ONIRO_HARMONYOS_AUTH_DIR` | `~/.oniro/harmonyos` | Where the encrypted Huawei account token is stored |
+| `ONIRO_HARMONYOS_SIGNING_DIR` | `~/.ohos/config` | Where generated HarmonyOS signing material (p12/csr/cer/p7b) is written |
 | `ONIRO_DEBUG` | (unset) | Set to `1` for full stack traces on error |
 
 ### Temporary space
@@ -332,6 +350,103 @@ through.
 
 **Command-line tools on Windows / macOS.** The Huawei mirror only publishes a Linux build of the command-line tools. On Windows and macOS you must either download the ZIP manually from the Huawei developer portal and install it with `oniro-app cmdtools install --from-zip path/to/commandline-tools-<platform>.zip`, or host the archive yourself and set `ONIRO_CMD_TOOLS_URL_WINDOWS` / `ONIRO_CMD_TOOLS_URL_MAC` so `cmdtools install` can fetch it.
 
+## HarmonyOS apps
+
+`oniro-app` builds and signs **HarmonyOS** projects as well as OpenHarmony ones. A project
+is HarmonyOS when its product declares `runtimeOS: "HarmonyOS"` in `build-profile.json5`, as
+DevEco Studio writes; every other project is OpenHarmony and behaves exactly as before.
+
+The two paths differ in one way that matters:
+
+| | OpenHarmony | HarmonyOS |
+| --- | --- | --- |
+| SDK | `oniro-app sdk install` downloads it | Ships inside DevEco Studio or the HarmonyOS command-line tools. Found automatically in Studio's default location or at the command-line-tools path; otherwise set `ONIRO_HARMONYOS_SDK_PATH` |
+| Signing | `oniro-app sign` — fully offline, uses the SDK's development certificate | `oniro-app sign --harmonyos` — AppGallery Connect issues the certificate and profile |
+| Account | none | a Huawei developer account (`oniro-app auth login`) |
+| Network | none | required |
+| Device | not required | one registered to the AGC team — a debug profile names the devices it is valid for |
+
+### Workflow
+
+```bash
+oniro-app auth login                       # once per machine
+oniro-app create --name MyApp --bundle com.example.myapp \
+                 --location ~/projects --sdk 24 --template HarmonyOSApp
+cd ~/projects/MyApp
+oniro-app sign --harmonyos                 # registers any connected device
+oniro-app build
+oniro-app app install && oniro-app app launch
+```
+
+Pass `--sdk` the API level of the installed HarmonyOS SDK (`apiVersion` in its
+`default/sdk-pkg.json`). hvigor builds a HarmonyOS project only against the release its
+`compileSdkVersion` names ("SDK component missing" otherwise), so `create` writes the
+installed SDK's release, e.g. `6.1.1(24)`, and warns when `--sdk` asks for another one.
+
+### `oniro-app auth`
+
+| Command | What it does |
+| --- | --- |
+| `auth login [--timeout <s>]` | Opens the Huawei sign-in page and waits for the browser to redirect back to a loopback port. The URL is also printed, so a headless host can be signed in from another machine. |
+| `auth logout` | Deletes the locally stored token. |
+| `auth status [--json]` | Prints the signed-in account, and warns when it is not allowed to sign. Exits non-zero when signed out. |
+| `auth team list [--json]` | Lists AGC teams; pass an id to `sign --harmonyos --team-id`. |
+
+The token is stored encrypted under `ONIRO_HARMONYOS_AUTH_DIR`. It is a credential: the
+directory is created `0700` and the files `0600`.
+
+### `oniro-app sign --harmonyos`
+
+Mirrors DevEco Studio's automatic signing:
+
+1. generates a local p12 keystore and a CSR (via the SDK's `hap-sign-tool.jar`, so a JDK is needed — DevEco Studio's bundled JBR is used when present);
+2. has AppGallery Connect issue a debug certificate for that CSR;
+3. registers every connected device's UDID with the team — no device is needed when the team already has some registered (from another machine, or by DevEco Studio);
+4. issues a debug provisioning profile naming that certificate, all of the team's registered devices, and any ACL-gated permissions the project requests;
+5. writes an encrypted `signingConfigs` entry into `build-profile.json5`, leaving other entries untouched.
+
+Material lands in `ONIRO_HARMONYOS_SIGNING_DIR` (default `~/.ohos/config`, the directory
+DevEco Studio also uses) and is **reused**, without contacting AGC for anything, while it is
+still valid: same bundle name and team, unexpired, naming the attached devices and requested
+permissions, and wired into this project's `build-profile.json5`. Certificates are a small
+per-team quota; `--force` regenerates anyway.
+
+The AGC certificate is named `oniro_debug_<team>.cer`, distinct from DevEco Studio's
+`auto_debug_<team>.cer`: each tool replaces only its own certificate when regenerating, so
+using both on one team does not revoke the other's signing material.
+
+| Flag | Meaning |
+| --- | --- |
+| `--harmonyos` | Use the AGC path instead of the offline OpenHarmony one |
+| `--team-id <id>` | AGC team to issue under (default: the account's own id) |
+| `--product <name>` | Product to sign (default `default`) |
+| `--force` | Regenerate even when the existing material is still valid |
+
+### Account regions
+
+Accounts from every Huawei region can sign. Sign-in redirects to the account's own region,
+which then decides the hosts every later call goes to — the ones DevEco Studio resolves
+through Huawei's routing service:
+
+| Region | Sign-in host | AGC signing host |
+| --- | --- | --- |
+| `CN` | `cn.devecostudio.huawei.com` | `connect-api.cloud.huawei.com` |
+| `EU` | `de.devecostudio.huawei.com` | `connect-api-dre.cloud.huawei.com` |
+| `SG` | `sg.devecostudio.huawei.com` | `connect-api-dra.cloud.huawei.com` |
+| `RU` | `ru.devecostudio.huawei.com` | `connect-api-drru.cloud.huawei.com` |
+
+The whole flow has been run with an `EU` account. Huawei's own CLI accepts only `CN` accounts.
+
+### Limitations
+
+- **Real-name verification is not required**, but an account without it must have accepted
+  the current HUAWEI Developer Basic Service Agreement — in AppGallery Connect, or by running
+  automatic signing once in DevEco Studio. `oniro-app auth status --json` reports it as
+  `developerAgreement`; `oniro-app` checks it but never accepts it for you.
+- A refusal from AGC surfaces as a permissions or not-enrolled error, not as a crash.
+- The AGC endpoints are private and undocumented, and can change without notice. See
+  `packages/core/src/harmonyos/NOTICE.md` for provenance and attribution.
+
 ## Signing apps that need system permissions
 
 `oniro-app sign` defaults to `--apl normal` / `--app-feature hos_normal_app`, which is fine for ordinary apps. Apps that request permissions above `normal` (anything with `system_basic` or `system_core` availability — e.g. `ohos.permission.GET_WIFI_INFO_INTERNAL`, `ohos.permission.ACCESS_PIN_AUTH`) need a higher APL, otherwise `bm install` fails with `grant request permissions failed`.

package/dist/oniro-app.js

@@ -2,7 +2,7 @@
 
 // src/bin/oniro-app.ts
 import { Command as Command4 } from "commander";
-import { OniroError } from "@oniroproject/core";
+import { OniroError as OniroError2 } from "@oniroproject/core";
 
 // src/commands/sdk.ts
 import * as fs from "fs";
@@ -73,7 +73,10 @@ var ENV_VAR_BY_KEY = {
   emulatorUrl: "ONIRO_EMULATOR_URL",
   tmpDir: "ONIRO_TMP_DIR",
   sdkUrlBase: "ONIRO_SDK_URL_BASE",
-  applicationCertPath: "ONIRO_APPLICATION_CERT_PATH"
+  applicationCertPath: "ONIRO_APPLICATION_CERT_PATH",
+  harmonyosSdkPath: "ONIRO_HARMONYOS_SDK_PATH",
+  harmonyosAuthDir: "ONIRO_HARMONYOS_AUTH_DIR",
+  harmonyosSigningDir: "ONIRO_HARMONYOS_SIGNING_DIR"
 };
 function createEnvConfig(env = process.env) {
   return {
@@ -252,7 +255,9 @@ function registerEmulatorCommand(program) {
 import * as path2 from "path";
 import { buildHap } from "@oniroproject/core";
 function registerBuildCommand(program) {
-  program.command("build [project-dir]").description("Build an OpenHarmony app via hvigorw. Defaults to the current directory.").option("--product <product>", "hvigor product name", "default").option("--module <module>", "restrict the build to a specific module").option("--mode <mode>", "hvigor build mode (e.g. release, debug)").option("--task <task>", "hvigor task to run", "assembleHap").option("--no-deps", "skip the automatic `ohpm install --all` when oh_modules/ is missing").option("--no-parallel", "build modules serially (default: parallel)").option("--json", "emit the build result (discovered HAPs, warnings) as JSON").action(async (projectDir, opts) => {
+  program.command("build [project-dir]").description(
+    'Build an OpenHarmony or HarmonyOS app via hvigorw. Defaults to the current directory. Projects declaring runtimeOS "HarmonyOS" build against the HarmonyOS SDK (ONIRO_HARMONYOS_SDK_PATH or an installed DevEco Studio).'
+  ).option("--product <product>", "hvigor product name", "default").option("--module <module>", "restrict the build to a specific module").option("--mode <mode>", "hvigor build mode (e.g. release, debug)").option("--task <task>", "hvigor task to run", "assembleHap").option("--no-deps", "skip the automatic `ohpm install --all` when oh_modules/ is missing").option("--no-parallel", "build modules serially (default: parallel)").option("--json", "emit the build result (discovered HAPs, warnings) as JSON").action(async (projectDir, opts) => {
     const { config, logger } = getRuntime();
     const dir = path2.resolve(projectDir ?? process.cwd());
     logger.info(`Building project at ${dir}...`);
@@ -285,7 +290,11 @@ import * as path3 from "path";
 import {
   APL_VALUES,
   APP_FEATURE_VALUES,
+  OniroError,
+  createHarmonyOsSession,
+  detectRuntimeOs,
   generateSigningConfigs,
+  harmonyOsAutoSign,
   prepareSigning,
   getOhosBaseSdkHome
 } from "@oniroproject/core";
@@ -298,7 +307,9 @@ function registerSignCommand(program) {
       "Generate signing keys, certificates, and signingConfigs for an OpenHarmony project.",
       "Requires java on PATH. The generated profile uses the SDK's built-in development",
       "cert (issuer=pki_internal) and its bundled validity window \u2014 dev/local builds only.",
-      "Overwrites the `signingConfigs` block in build-profile.json5 (other keys preserved)."
+      "Overwrites the `signingConfigs` block in build-profile.json5 (other keys preserved).",
+      "HarmonyOS projects need --harmonyos instead, which has AppGallery Connect issue the",
+      "certificate and profile for a signed-in Huawei account (`oniro-app auth login`)."
     ].join(" ")
   ).addOption(
     new Option(
@@ -315,10 +326,31 @@ function registerSignCommand(program) {
       "--acls <list>",
       "Comma-separated permission names to write into the profile's acls.allowed-acls. Required for apps that request permissions above their apl (e.g. a system_basic app requesting ohos.permission.CAPTURE_SCREEN). Example: --acls ohos.permission.REBOOT,ohos.permission.INJECT_INPUT_EVENT"
     ).argParser(parseAclsList)
-  ).option("--bootstrap", "No-op if signing material is already present; otherwise generate it.").option("--store-password <pwd>", "Keystore store password (default 123456 \u2014 the SDK keystore password).").option("--key-password <pwd>", "Keystore key password (default 123456 \u2014 the SDK keystore password).").action(
-    (projectDir, opts) => {
+  ).option(
+    "--harmonyos",
+    "Sign a HarmonyOS project through AppGallery Connect. Needs `oniro-app auth login`, and a connected device unless the team already has devices registered."
+  ).option("--team-id <id>", "With --harmonyos: the AGC team to sign under. Default: the account's own (`oniro-app auth team list`).").option("--product <name>", "With --harmonyos: the product to sign. Default `default`.").option("--force", "With --harmonyos: regenerate the certificate and profile even when they are still valid.").option("--bootstrap", "No-op if signing material is already present; otherwise generate it.").option("--store-password <pwd>", "Keystore store password (default 123456 \u2014 the SDK keystore password).").option("--key-password <pwd>", "Keystore key password (default 123456 \u2014 the SDK keystore password).").action(
+    async (projectDir, opts) => {
       const { config, logger } = getRuntime();
       const dir = path3.resolve(projectDir ?? process.cwd());
+      if (opts.harmonyos) {
+        const result = await harmonyOsAutoSign({
+          config,
+          session: createHarmonyOsSession({ config, logger }),
+          projectDir: dir,
+          productName: opts.product,
+          teamId: opts.teamId,
+          force: opts.force,
+          logger
+        });
+        logger.info(`Signing configs ready for ${result.bundleName} (profile names ${result.deviceIds.length} device(s)).`);
+        return;
+      }
+      if (detectRuntimeOs(dir, opts.product) === "HarmonyOS") {
+        throw new OniroError(
+          `${dir} targets HarmonyOS, which needs a certificate from AppGallery Connect: run \`oniro-app auth login\` once, then \`oniro-app sign --harmonyos\`.`
+        );
+      }
       const passwords = opts.storePassword || opts.keyPassword ? { store: opts.storePassword ?? "123456", key: opts.keyPassword ?? "123456" } : void 0;
       if (opts.bootstrap) {
         const result = prepareSigning({
@@ -349,6 +381,68 @@ function registerSignCommand(program) {
   );
 }
 
+// src/commands/auth.ts
+import { HUAWEI_SITES, createHarmonyOsSession as createHarmonyOsSession2 } from "@oniroproject/core";
+function session() {
+  const { config, logger } = getRuntime();
+  return createHarmonyOsSession2({
+    config,
+    logger,
+    onLoginUrl: (url) => process.stderr.write(`Opening the Huawei sign-in page. If no browser opens, visit:
+  ${url}
+`)
+  });
+}
+function registerAuthCommand(program) {
+  const auth = program.command("auth").description(
+    "Sign in to a Huawei developer account, which HarmonyOS signing (`oniro-app sign --harmonyos`) needs. OpenHarmony signing needs no account. The token is stored encrypted under ONIRO_HARMONYOS_AUTH_DIR (default ~/.oniro/harmonyos)."
+  );
+  auth.command("login").description("Sign in through the browser, which redirects back to a loopback port on this machine.").option("--timeout <seconds>", "How long to wait for the browser sign-in. Default 600.", (v) => Number(v)).action(async (opts) => {
+    const user = await session().login(opts.timeout ? { timeoutMs: Math.max(1, opts.timeout) * 1e3 } : void 0);
+    process.stdout.write(`${user.userName || user.userId}
+`);
+  });
+  auth.command("logout").description("Sign out and delete the stored token.").action(async () => {
+    const signedOut = await session().logout();
+    getRuntime().logger.info(signedOut ? "Signed out." : "Not signed in; nothing to do.");
+  });
+  auth.command("status").description("Show the signed-in account. Exits non-zero when not signed in.").option("--json", "Emit the account details as JSON.").action(async (opts) => {
+    const s = session();
+    const user = await s.getUserInfo({ refresh: true });
+    if (!user) {
+      process.stderr.write("Not signed in. Run `oniro-app auth login`.\n");
+      process.exitCode = 1;
+      return;
+    }
+    const agreement = user.isRealName ? null : await s.getDeveloperAgreement(user);
+    if (opts.json) {
+      const { userId, userName, countryCode, siteCode, isRealName } = user;
+      const agcBaseUrl = HUAWEI_SITES[siteCode].agcBaseUrl;
+      const status = { userId, userName, countryCode, site: siteCode, agcBaseUrl, isRealName, developerAgreement: agreement, tokenPath: s.tokenPath };
+      process.stdout.write(`${JSON.stringify(status, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(`${user.userName || user.userId} (${user.userId}) [${user.siteCode}]
+`);
+    if (agreement && !(agreement.signed && agreement.latest)) {
+      process.stderr.write(
+        "[warn] This account has neither real-name verification nor the current HUAWEI Developer Basic Service Agreement accepted, so AppGallery Connect will not issue signing material. Accept the agreement in AppGallery Connect or DevEco Studio.\n"
+      );
+    }
+  });
+  auth.command("team").description("AGC teams this account belongs to.").command("list").description("List the AGC teams this account belongs to, for `oniro-app sign --harmonyos --team-id <id>`.").option("--json", "Emit the team list as JSON.").action(async (opts) => {
+    const teams = await session().listTeams();
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(teams, null, 2)}
+`);
+      return;
+    }
+    for (const t of teams) process.stdout.write(`${t.id}	${t.name}
+`);
+  });
+}
+
 // src/commands/app.ts
 import * as path4 from "path";
 import { installApp, launchApp, uninstallApp, forceStop, applyChanges, getBundleName } from "@oniroproject/core";
@@ -443,7 +537,7 @@ function getBundledTemplateRoot() {
 
 // src/commands/create.ts
 function registerCreateCommand(program) {
-  program.command("create").description("Scaffold a new Oniro/OpenHarmony app from a template. All flags are required (non-interactive).").requiredOption("--name <name>", "Project folder name (letters, digits, ._- only)").requiredOption("--bundle <bundleName>", "Bundle name in reverse-DNS form, e.g. com.example.myapp").requiredOption("--location <dir>", "Parent directory where the new project folder will be created").requiredOption("--sdk <api>", "Target SDK API level (e.g. 18, 20)").option("--template <id>", "Template id", "EmptyAbility").option("--module <name>", "Module folder name (defaults to the template default, usually `entry`)").option("--overwrite", "Replace the destination if it already exists").action(async (opts) => {
+  program.command("create").description("Scaffold a new Oniro/OpenHarmony or HarmonyOS app from a template. All flags are required (non-interactive).").requiredOption("--name <name>", "Project folder name (letters, digits, ._- only)").requiredOption("--bundle <bundleName>", "Bundle name in reverse-DNS form, e.g. com.example.myapp").requiredOption("--location <dir>", "Parent directory where the new project folder will be created").requiredOption("--sdk <api>", "Target SDK API level (e.g. 18, 20)").option("--template <id>", "Template id", "EmptyAbility").option("--module <name>", "Module folder name (defaults to the template default, usually `entry`)").option("--overwrite", "Replace the destination if it already exists").action(async (opts) => {
     const { config, logger } = getRuntime();
     if (!isValidProjectName(opts.name)) {
       throw new Error(`Invalid --name '${opts.name}'. Use letters/numbers/._- and no slashes.`);
@@ -901,7 +995,7 @@ function registerInputCommand(program) {
 }
 
 // src/bin/oniro-app.ts
-var CLI_VERSION = "0.10.0";
+var CLI_VERSION = "0.11.0";
 function buildProgram() {
   const program = new Command4().name("oniro-app").description(
     "Cross-platform CLI for Oniro/OpenHarmony app development.\n\nDesigned for non-interactive use (CI, scripts, agents): every command\ntakes explicit flags, results go to stdout, progress/logs go to stderr,\nand a non-zero exit code indicates failure."
@@ -911,6 +1005,7 @@ function buildProgram() {
   registerEmulatorCommand(program);
   registerBuildCommand(program);
   registerSignCommand(program);
+  registerAuthCommand(program);
   registerAppCommand(program);
   registerCreateCommand(program);
   registerTemplatesCommand(program);
@@ -930,7 +1025,7 @@ async function main() {
   try {
     await program.parseAsync(process.argv);
   } catch (err) {
-    const message = err instanceof OniroError ? err.message : err instanceof Error ? err.message : String(err);
+    const message = err instanceof OniroError2 ? err.message : err instanceof Error ? err.message : String(err);
     process.stderr.write(`[error] ${message}
 `);
     if (process.env.ONIRO_DEBUG === "1" && err instanceof Error && err.stack) {